RGBMatrix.Animation.Config behaviour (rgb_matrix v0.1.0) View Source
Provides a behaviour and macros for defining animation configurations.
Link to this section Summary
Types
A map used during creation of an Animation.<type>.Config
.
A keyword list containing the configuration fields for an animation type.
A tuple of the form, {name, field}
. name
is one of the valid
FieldType
names and field
is a
RGBMatrix.Animation.Config.FieldType.t/0
struct.
A struct containing runtime configuration for a specific animation.
A map used to update an Animation.<type>.Config
.
Link to this section Types
Specs
creation_params() :: %{ optional(atom()) => RGBMatrix.Animation.Config.FieldType.value() }
A map used during creation of an Animation.<type>.Config
.
The keys are defined by the first atom, the name, provided to an Animation's
field
definition(s) and must match the field being defined.
The value should be appropriate for the specified field.
Specs
schema() :: keyword(RGBMatrix.Animation.Config.FieldType.t())
A keyword list containing the configuration fields for an animation type.
It provides the defaults for each field, the available parameters to configure
(such as :default
, :min
, :options
, and so on). It can provide :doc
, a
keyword list, for documentation such as a human-readable :name
and
:description
.
The keys are defined by the first atom, the name, provided to an Animation's
field
definition(s). The values are
RGBMatrix.Animation.Config.FieldType.t/0
types.
The documentation is optional and will be initialized to an empty list if omitted.
Specs
schema_field() :: {name :: atom(), RGBMatrix.Animation.Config.FieldType.t()}
A tuple of the form, {name, field}
. name
is one of the valid
FieldType
names and field
is a
RGBMatrix.Animation.Config.FieldType.t/0
struct.
Specs
t() :: struct()
A struct containing runtime configuration for a specific animation.
Example:
RGBMatrix.Animation.HueWave.Config
RGBMatrix.Animation.SolidReactive.Config
Configs should not be accessed or modified directly. Use the functions
Xebow.get_animation_config/0
and Xebow.update_animation_config/1
for
access and modification.
Specs
A map used to update an Animation.<type>.Config
.
The keys are defined by the first atom, the name, provided to an Animation's
field
definition(s) and must match the field(s) being updated. The key may
be a string or an atom.
The value should be appropriate for the field.
Link to this section Functions
Specs
field_types() :: %{ required(atom()) => RGBMatrix.Animation.Config.FieldType.submodule() }
Returns a map of field types provided by the Config module
Specs
new_config(module :: module(), schema :: schema(), params :: creation_params()) :: t()
Creates a new t/0
struct belonging to the provided
Animation.<type>.Config
module.
The provided Config must be defined through the use Animation
and field
macros in an Animation.<type>
module.
The params provided are a map of creation_params/0
.
Returns a t/0
struct.
Example:
iex> module = RGBMatrix.Animation.HueWave.Config
iex> schema = module.schema()
iex> params = %{direction: :up, width: 30}
iex> RGBMatrix.Animation.Config.new_config(module, schema, params)
%RGBMatrix.Animation.HueWave.Config{direction: :up, speed: 4, width: 30}
The above example shows setting the direction and width to non-default values.
Any invalid keys in the creation_params/0
map will cause that param to be
ignored. Invalid values for fields will be ignored. In both cases, the default
provided to the type will be used as the initial value for that field.
All errors will be logged.
Specs
update_config(config :: t(), schema :: schema(), params :: update_params()) :: t()
Updates the provided t/0
struct using the provided schema and params.
The params are a map of update_params/0
.
Configs must be retrieved through the use of Xebow.get_animation_config/0
,
which will return both the config and the schema.
Returns the updated t/0
struct.
Example:
iex> {config, schema} = Xebow.get_animation_config()
iex> params = %{"direction" => "left", speed: 8}
iex> RGBMatrix.Animation.Config.update_config(config, schema, params)
%RGBMatrix.Animation.HueWave.Config{direction: :left, speed: 8, width: 20}
The above example shows updating the direction and speed.
Any errors encountered during update are logged, and the struct is returned unchanged.
Link to this section Callbacks
Specs
new(%{optional(atom()) => RGBMatrix.Animation.Config.FieldType.value()}) :: t()
Specs
schema() :: schema()