|
1 | 1 | # Graph Overview |
2 | 2 |
|
3 | | -Give an overview of a graph here |
| 3 | +The most important state a Scene is responsible for is its Graph. The Graph |
| 4 | +defines what is to be drawn to the screen, any referenced components, and the |
| 5 | +overall draw order. When a Scene decides the graph is ready to be drawn to the |
| 6 | +screen, it pushes it to the Viewport. |
4 | 7 |
|
5 | | -Coming soon |
| 8 | +Graphs are made out of a handful of primitives, each of which knows how to draw |
| 9 | +one thing. When multiple primitives are put together, almost any standard UI can be drawn. |
6 | 10 |
|
7 | | -## Positions, rotation, scale and more |
| 11 | +For example, the graph below shows the words "Hello World" around them. |
8 | 12 |
|
9 | | -A major mental model difference between Scenic and everything web is how things |
10 | | -are positioned on the screen. In this case, Scenic is built like a game. |
| 13 | + @graph Graph.build(font: :roboto, font_size: 24) |
| 14 | + |> text("Hello World", text_align: center, translate: {300, 300}) |
| 15 | + |> circle(100, stroke: {2, :green} translate: {300, 300}) |
11 | 16 |
|
12 | | -Scenic is aimed at fixed-screen devices and apps that control their own layout. |
13 | | -On the web, there is no guarantee what size screen or window the client will |
14 | | -use, so it relies on dynamic layout that is computed on the client. |
| 17 | +In the example above, the first line creates a new graph and assigns two font styles to its root. The next two lines form a pipeline that adds primitives to the root |
| 18 | +node of the new graph. Each of these primitives also assigns styles. |
15 | 19 |
|
16 | | -Scenic does not have an auto-layout engine. Instead, everything rendered on the |
17 | | -screen is positioned with transform matrices, just like a game. |
| 20 | +## Primitives |
18 | 21 |
|
19 | | -**Don’t worry!** You will not need to look at any matrices unless you want to |
20 | | -get fancy. |
| 22 | +There is a fixed set of primitives that Scenic knows how to draw. These form the base set of things that you can do. While they seem simple, when combined you draw pretty much any 2D UI that you need. |
21 | 23 |
|
22 | | -To move something on the screen, just add one of the transform options. Like |
23 | | -this |
| 24 | +[Read more about the primitives here.](overview_primitives.html) |
| 25 | + |
| 26 | +In general, each primitive renders one thing to the screen. The Group primitive is |
| 27 | +sort of like a `<div>` tag in html in that it creates a new node in the graph hierarchy that more primitives can be organized beneath. |
| 28 | + |
| 29 | +Each primitive can also be assigned styles and transforms, which affect how (or whether) they are drawn and where. |
| 30 | + |
| 31 | +## Styles |
| 32 | + |
| 33 | +In addition to the fixed set of primitives, there is also a fixed set of primitive styles. (Some components support more styles, but they really get boiled down to the primitive styles when it is time to render) |
| 34 | + |
| 35 | +[Read more about the styles here.](overview_styles.html) |
| 36 | + |
| 37 | +Styles are inherited down the graph hierarchy. This means that if you set a style on the root of a graph, or in a group, then any primitives below that node inherit those styles without needing to explicitly set them on every single primitive. |
| 38 | + |
| 39 | +For example, in the following graph, the font and font_size styles are set at the root. Both text primitives inherit those values, although the second one overrides the size with something bigger. |
| 40 | + |
| 41 | + @graph Graph.build(font: :roboto, font_size: 24) |
| 42 | + |> text("Hello World", translate: {300, 300}) |
| 43 | + |> text("Bigger Hello", font_size: 40, translate: {400, 300}) |
| 44 | + |
| 45 | + |
| 46 | +## Transforms |
| 47 | + |
| 48 | +The final type of primitive control is transforms. Unlike html, which uses auto-layout to position items on the screen, Scenic moves primitives around using matrix transforms. This is common in video games and provides powerful control of your primitives. |
| 49 | + |
| 50 | +A [matrix](https://en.wikipedia.org/wiki/Matrix_(mathematics)) is an array of numbers that can be used to change the positions, rotations, scale and more of locations. |
| 51 | + |
| 52 | +**Don’t worry!** You will not need to look at any matrices unless you want to get fancy. In Scenic, you will rarely (if ever) create matrices on your own (you can if you know what you are doing!), and will instead use the transform helpers. |
| 53 | + |
| 54 | +[You can read about the transform types here.](overview_transforms.html) |
| 55 | + |
| 56 | +Transforms are inherited down the graph hierarchy. This means that if you place a rotation transform at the root of a graph, then all the primitives will be rotated around a common point. |
| 57 | + |
| 58 | +If you want to zoom in, scroll, or rotate a UI, or just pieces of the UI, you can do that very easily by applying transforms. |
| 59 | + |
| 60 | +In the example below, the first text line is translated, and the second is scaled bigger, and the whole graph rotated 0.4 radians. |
| 61 | + |
| 62 | + @graph Graph.build(font: :roboto, font_size: 24, rotate: 0.4) |
| 63 | + |> text("Hello World", translate: {300, 300}) |
| 64 | + |> text("Bigger Hello", font_size: 40, scale: 1.5) |
| 65 | + |
| 66 | + |
| 67 | +## Modifying a graph |
| 68 | + |
| 69 | +Scenic was written specifically for Erlang/Elixir, which is a functional programming model with immutable data. |
| 70 | + |
| 71 | +As such, once you make a graph, it stays in memory unchanged - until you change 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. |
| 72 | + |
| 73 | +[Graph.modify/3](Scenic.Graph.html#modify/3) is the single Graph function that you will use the most. |
| 74 | + |
| 75 | +For example, lets go back to our graph with the two text items in it. |
| 76 | + |
| 77 | + @graph Graph.build(font: :roboto, font_size: 24, rotate: 0.4) |
| 78 | + |> text("Hello World", translate: {300, 300}, id: :small_text) |
| 79 | + |> text("Bigger Hello", font_size: 40, scale: 1.5, id: :big_text) |
| 80 | + |
| 81 | +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. |
| 82 | + |
| 83 | + graph = |
| 84 | + @graph |
| 85 | + |> Graph.modify( :small_text, &text(&1, "Smaller Hello", font_size: 16)) |
| 86 | + |> Graph.modify( :big_text, &text(&1, "Bigger Hello", font_size: 60)) |
| 87 | + |> push_graph() |
| 88 | + |
| 89 | +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 and then push once at the end. |
| 90 | + |
| 91 | + |
| 92 | +## What to read next? |
| 93 | + |
| 94 | +If you are exploring Scenic, then you should read the [Primitives Overview](overview_primitives.html) next. |
0 commit comments