overview

Overview

Scenes are the core of the UI model.

A Scene is a type of GenServer that maintains state, handles input, events and other messages, and plays a role managing the supervision of components/controls such as buttons and other input.

a-brief-aside

A brief aside

Before saying anything else I want to emphasize that the rest of your application, meaning device control logic, sensor reading / writing, services, whatever, does not need to have anything to do with Scenes.

In many cases I recommend treating those as separate GenServers in their own supervision trees that you maintain. Then your Scenes would query or send information to/from them via cast or call messages.

Part of the point of using Elixir/Erlang/OTP is separating this sort of logic into independent trees. That way, an error in one part of your application does not mean the rest of it will fail.

scenes

Scenes

Scenes are the core of the UI model. A scene consists of one or more graphs, and a set of event handlers and filters to deal with user input and other messages.

Think of a scene as being a little like an HTML page. HTML pages have:

• Structure (the DOM)
• Logic (Javascript)
• Links to other pages.

A Scene has:

• Structure (graphs),
• Logic (event handlers and filters)
• Transitions to other scenes. Well... it can request the ViewPort to go to a different scene.

Your application is a collection of scenes that are in use at different times. There is only ever one scene showing in a ViewPort at a given time. However, scenes can instantiate components, effectively embedding their graphs inside the main one. More on that below.

graphs

Graphs

Each scene should maintain at least one graph. You can build graphs at compile time, or dynamically while your scene is running. Building them at compile time has two advantages

1. Performance: It is clearly faster to build the graph once during build time than to build it repeatedly during runtime.
2. Error checking: If your graph has an error in it, it is much better to have it stop compilation than cause an error during runtime.

Example of building a graph during compile time:

@graph Scenic.Graph.build(font_size: 24)
  |> button({"Press Me", :button_id}, translate: {20, 20})

Rather than having a single scene maintain a massive graph of UI, graphs can reference graphs in other scenes.

On a typical screen of UI, there is one scene that is the root. Each control, is its own scene process with its own state. These child scenes can in turn contain other child scenes. This allows for strong code reuse, isolates knowledge and logic to just the pieces that need it, and keeps the size of any given graph to a reasonable size. For example, the handlers of a check-box scene don't need to know anything about how a slider works, even though they are both used in the same parent scene. At best, they only need to know that they both conform to the Component.Input behavior, and can thus query or set each others value. Though it is usually the parent scene that does that.

The application developer is responsible for building and maintaining the scene's graph. It only enters the world of the ViewPort when you call push_graph. Once you have called push_graph, that graph is sent to the drivers and is out of your immediate control. You update that graph by calling push_graph again.

scene-structure

Scene Structure

The overall structure of a scene has several parts. It is a GenServer, which means you have an input function and can implement the GenServer callbacks such as handle_info/2, handle_cast/2, handle_call/3 and any others. The terms you return from those callbacks is pretty much what you expect with the requirement that the state is always a scene structure.

The init/3 callback takes 3 parameters. They are the scene structure (state), params that the parent scene set up, and opts, which includes things like the id, theme, and some styles that were set on the scene.

There are several additional callbacks that your scene can support. The main ones are handle_input/2, and handle_event/3. If you are making a Component (a reusable scene), then there are additional callbacks that allow it to play nicely with others.

scene-example

Scene Example

This example shows a simple scene that contains a button. When the button is clicked, the scene increments a counter and displays the number of clicks it has received.

defmodule MySimpleScene do
  use Scenic.Scene

  alias Scenic.Graph
  import Scenic.Primitives
  import Scenic.Components

  @initial_count  0

  # This graph is built at compile time so it doesn't do any work at runtime.
  # It could also be built in the init function (or any other) if you want
  # it to be dynamic based on the params or whatever.
  @graph Graph.build()
      |> group( fn graph ->
        graph
        |> text( "Count: " <> inspect(@initial_count), id: :count )
        |> button( "Click Me", id: :btn, translate: {0, 30} )
      end,
      translate: {100, 100}
    )

  # Simple function to return @graph.
  # @graph is built at compile time and stored directly in the BEAM file every
  # time it is used. A simple accessor function will cause it to be stored only once.
  # Do this when you build graphs at compile time to save space in your file.
  defp graph(), do: @graph

  # The Scenic.Scene init function
  @impl Scenic.Scene
  def init(scene, _params, _opts) do
    scene =
      scene
      |> assign( count: @initial_count )
      |> push_graph( graph() )
    {:ok, scene}
  end

  @impl Scenic.Scene
  def handle_event( {:click, :btn}, _, %{assigns: %{count: count}} = scene ) do
    count = count + 1

    # modify the graph to show the current click count
    graph =
      graph()
      |> Graph.modify( :count, &text(&1, "Count: " <> inspect(count)) )

    # update the count and push the modified graph
    scene =
      scene
      |> assign( count: count )
      |> push_graph( graph )

    # return the updated scene
    { :noreply, scene }
  end

end

scene-state

Scene State

Scenes are just a specialized form of GenServer. This means they can react to messages and can have state. However, scene state is a bit like socket state in Phoenix in that It has a strict format, but you can add anything you want into its :assigns map.

Multiple Graphs

Any given scene can maintain multiple graphs and multiple draw scripts. They are identified from each other with an id that you attach.

Normally when you use push_graph, you don't attach an ID. In that case the scene's id is used as the graph id.

The act of pushing a graph to the ViewPort causes it to be compiled into a script, which is stored in an ETS table so that the drivers can quickly access it. To use a second, or third, graph that you scene has pushed, refer to it using a Scenic.Primitive.Script primitive.

def init( scene, param, opts ) do
  second_graph = Scenic.Graph.build()
    |> text( "Text in the second graph" )

  main_graph = Scenic.Graph.build()
    |> script( "my_fancy_id" )

  scene =
    scene
    |> push_graph( main_graph )
    |> push_graph( second_graph, "my_fancy_id" )

  { :ok, scene }
end

Note that it doesn't matter which graph you push first. They will link to each other via the string id that you supply.

communications

Communications

Scenes are specialized GenServers. As such, they communicate with each other (and the rest of your application) through messages. You can receive messages with the standard handle_info, handle_cast, handle_call callbacks just like any other scene.

Scenes have two new event handling callbacks that you can optionally implement. These are about user input vs UI events.

input-vs-events

Input vs. Events

Input is data generated by the drivers and sent up to the scenes through Scenic.ViewPort. There is a limited set of input types and they are standardized so that the drivers can be built independently of the scenes. Input follows certain rules about which scene receives them.

Events are messages that one scene generates for consumption by other scenes. For example, a Scenic.Component.Button scene would generate a {:click, msg} event that is sent to its parent scene.

You can generate any message you want, however, the standard component libraries follow certain patterns to keep things sensible.

input-handling

Input Handling

You handle incoming input events by adding handle_input/3 callback functions to your scene. Each handle_input/3 call passes in the input message itself, an input context struct, and your scene's state. You can then take the appropriate actions, including generating events (below) in response.

Under normal operation, input that is not position dependent (keys, window events, more...) is sent to the root scene. Input that does have a screen position (cursor_pos, cursor button presses, etc.) is sent to the scene that contains the graph that was hit.

Your scene can "capture" all input of a given type so that it is sent to itself instead of the default scene for that type. this is how a text input field receives the key input. First, the user selects that field by clicking on it. In response to the cursor input, the text field captures text input (and maybe transforms its graph to show that it is selected).

Captured input types should be released when no longer needed so that normal operation can resume.

The input messages are passed on to a scene's parent if not processed.

event-filtering

Event Filtering

In response to input, (or anything else... a timer perhaps?), a scene can generate an event (any term), which is sent backwards up the tree of scenes that make up the current aggregate graph.

In this way, a Scenic.Component.Button scene can generate a {:click, msg} event that is sent to its parent. If the parent doesn't handle it, it is sent to that scene's parent. And so on until the event reaches the root scene. If the root scene also doesn't handle it then the event is dropped.

To handle events, you add handle_event/3 functions to your scene. This function handles the event, and stops its progress backwards up the graph. It can handle it and allow it to continue up the graph. Or it can transform the event and pass the transformed version up the graph.

You choose the behavior by returning either

{:cont, msg, state}

or

{:halt, state}

Parameters passed in to handle_event/3 are the event itself, a reference to the originating scene (which you can to communicate back to it), and your scene's state.

A pattern I'm using is to handle an event at the filter and stop its progression. It also generates and sends a new event to its parent. I do this instead of transforming and continuing when I want to change the originating scene.

no-children

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 means the scene won't create a dynamic supervisor for this scene, which saves some resources and imporoves startup time.

For example, the Button component sets has_children to false.