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.

t()

A struct containing runtime configuration for a specific animation.

A map used to update an Animation.<type>.Config.

Functions

Returns a map of field types provided by the Config module

Creates a new t/0 struct belonging to the provided Animation.<type>.Config module.

Updates the provided t/0 struct using the provided schema and params.

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

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

update_params() :: %{required(atom() | String.t()) => any()}

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

Link to this function

new_config(module, schema, params)

View Source

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.

Link to this function

update_config(config, schema, params)

View Source

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()

Specs

update(t(), %{optional(atom() | String.t()) => any()}) :: t()