Scenic.Component behaviour (Scenic v0.10.3) View Source

A Component is simply a Scene that is optimized to be referenced by another scene.

All you need to do to create a Component is call

use Scenic.Component

instead of

use Scenic.Scene

At the top of your module definition.

Standard Components

Scenic includes a small number of standard components that you can simply reuse in your scenes. These were chosen to be in the main library because a) they are used frequently, and b) their use promotes a certain amount of "common" look and feel.

All of these components are typically added/modified via the helper functions in the Scenic.Components module.

Button a simple button.
Checkbox a checkbox input field.
Dropdown a dropdown / select input field.
RadioGroup a group of radio button inputs.
Slider a slider input.
TextField a text / password input field.
Toggle an on/off toggle input.

Other Components

For completeness, Scenic also includes the following standard components. They are used by the components above, although you are free to use them as well if they fit your needs.

Caret the vertical, blinking, caret line in a text field.
RadioButton a single radio button in a radio group.

Verifiers

One of the main differences between a Component and a Scene is the two extra callbacks that are used to verify incoming data. Since Components are meant to be reused, you should do some basic validation that the data being set up is valid, then provide feedback if it isn't.

Optional: No Children

There is an optimization you can use. If you know for certain that your component will not attempt to use any components, you can set has_children to false like this.

use Scenic.Component, has_children: false

Setting has_children to false this will do two things. First, it won't create a dynamic supervisor for this scene, which saves some resources.

For example, the Button component sets has_children to false.

This option is available for any Scene, not just components

Link to this section Summary

Callbacks

add_to_graph(graph, data, opts)

Add this component to a Scenic.Graph

info(data)

Provide an info string about what was wrong with the provided data.

verify(data)

Verify that this the data for this component is valid.

Link to this section Callbacks

add_to_graph(graph, data, opts)

(optional)

Specs

add_to_graph(graph :: Scenic.Graph.t(), data :: any(), opts :: list()) ::
  Scenic.Graph.t()

Add this component to a Scenic.Graph

info(data)

(optional)

Specs

info(data :: any()) :: String.t()

Provide an info string about what was wrong with the provided data.

This string will typically be displayed in the terminal. Example implementation:

def info(data) do
"""
#{IO.ANSI.red()}Button data must be a binary
#{IO.ANSI.yellow()}Received: #{inspect(data)}
#{IO.ANSI.default_color()}
"""
end

verify(data)

Specs

verify(data :: any()) :: {:ok, any()} | any()

Verify that this the data for this component is valid.

Return an {:ok, data} tuple if the data is valid and any other term if the data is not valid. Here is an example implementation that checks if the input is a valid binary:

@impl Scenic.Component
def verify(data) do
  if is_binary(data) do
    {:ok, data}
  else
    :invalid_data
  end
end