Please see Graph Overview for a high-level description.

What is a Graph

There are many types of graphs in the world of computer science. There are graphs that show data to a user. There are graphs that give access to databases. Graphs that link people to a social network.

In Scenic, a Graph is a graph in same way that the DOM in HTML is a graph. It is a hierarchical tree of data that describes a set of things to draw on the screen.

You build a graph by appending primitives (individual things to draw) to the current node in the tree. Nodes are represented by the Group primitive in Scenic.

The following example builds a simple graph that displays some text, creates a group, then adds more text and a rounded rectangle to it.

@graph  Scenic.Graph.build()
|> text( "This is some text", translate: {20, 20} )
|> group( fn(graph) ->
  graph
  |> text( "This text is in a group", translate: {200, 24} )
  |> rounded_rectangle( {400, 30}, stroke: {2, :blue})
end, translate: {20, 100}, text_align: :center)

There is a fair amount going on in the example above, we we will break it down. The first line

@graph  Scenic.Graph.build()

builds an empty graph with only one group as the root node. By assigning it to the compile directive @group, we know that this group will be built once at compile time and will be very fast to access later during runtime.

The empty graph that is returned from build() is then passed to text(...), which adds a text primitive to the root group. The resulting graph from that call is then passed again into the group(...) call. This creates a new group and then calls an anonymous function that you can use to add primitives to the newly created group.

Notice that the anonymous "builder" function receives a graph as its only parameter. This is the same graph that we are building, except that it has a marker indicating that new primitives added to it are inserted into the new group instead of the root of the graph.

Finally, when the group is finished, a translation matrix and a :text_align style are added to it. These properties are inherited by the primitives in the group.

Inheritance

An important concept to understand is that both styles and transforms are inherited down the graph. This means that if you apply a style or transform to any group (including the root), then all primitives contained by that group will have those properties applied to them too. This is true even if the primitive is nested in several groups at the same time.

@graph  Scenic.Graph.build(font: :roboto_mono)
|> text( "This text inherits the font", translate: {20, 20} )
|> group( fn(graph) ->
  graph
  |> text( "This text also inherits the font", translate: {200, 24} )
  |> text( "This text overrides the font", font: :roboto )
end, translate: {20, 100}, text_align: :center)

Transforms, such as translate, rotate, scale, also inherit down the graph, but do so slightly differently than the styles. With a style, when you set a specific value on a primitive, that overrides the inherited value of the same type.

With a transform, the values multiply together. This allows you to position items within a group relative to the origin {0,0}, then move the group as a whole, keeping the interior positions unchanged.

Modifying a Graph

Scenic was written specifically for Erlang/Elixir, which is a functional programming model with immutable data.

As such, once you make a graph, it stays in memory unchanged - until you transform it via Graph.modify/3. Technically you never change it (that's the immutable part), instead Graph.modify returns a new graph with different data in it.

Graph.modify/3 is the single Graph function that you will use the most.

For example, lets go back to our graph with the two text items in it.

@graph Graph.build(font: :roboto, font_size: 24, rotate: 0.4)
  |> text("Hello World", translate: {300, 300}, id: :small_text)
  |> text("Bigger Hello", font_size: 40, scale: 1.5, id: :big_text)

This time, we've assigned ids to both of the text primitives. This makes it easy to find and modify that primitive in the graph.

graph =
  @graph
  |> Graph.modify( :small_text, &text(&1, "Smaller Hello", font_size: 16))
  |> Graph.modify( :big_text, &text(&1, "Bigger Hello", font_size: 60))

Notice that the graph is modified multiple times in the pipeline. The push_graph/1 function is relatively heavy when the graph references other scenes. The recommended pattern is to make multiple changes to the graph .

Accessing Primitives

When using a Graph, it is extremely common to access and modify primitives. They way you do this is by putting an id on the primitives you care about in a graph.

@graph Graph.build()
  |> text("small text", id: :small_text)
  |> text("bit text", id: :big_text)

When you get primitives, or modify a graph, you specify them by id. This happens quickly, but at a cost of using a little memory. If you aren't going to access a primitive, then don't assign an id to them.

One interesting note: There is nothing saying you have to use an atom as the id. In fact you can use any Erlang term you want. This can be very powerful, especially when used to identify components...