OLD | NEW |
1 Sky Rendering | 1 Sky Rendering |
2 ============= | 2 ============= |
3 | 3 |
4 The Sky render tree is a low-level layout and painting system based on a | 4 The Sky render tree is a low-level layout and painting system based on a |
5 retained tree of objects that inherit from [`RenderObject`](object.dart). Most | 5 retained tree of objects that inherit from [`RenderObject`](object.dart). Most |
6 developers using Sky will not need to interact directly with the rendering tree. | 6 developers using Sky will not need to interact directly with the rendering tree. |
7 Instead, most developers should use [Sky widgets](../widgets/README.md), which | 7 Instead, most developers should use [Sky widgets](../widgets/README.md), which |
8 are built using the render tree. | 8 are built using the render tree. |
9 | 9 |
10 Overview | 10 Overview |
(...skipping 61 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
72 * `ContainerRenderObjectMixin` is useful for subclasses of `RenderObject` that | 72 * `ContainerRenderObjectMixin` is useful for subclasses of `RenderObject` that |
73 have a child list. | 73 have a child list. |
74 | 74 |
75 Subclasses of `RenderObject` are not required to use either of these child | 75 Subclasses of `RenderObject` are not required to use either of these child |
76 models and are free to invent novel child models for their specific use cases. | 76 models and are free to invent novel child models for their specific use cases. |
77 | 77 |
78 ### Parent Data | 78 ### Parent Data |
79 | 79 |
80 TODO(ianh): Describe the parent data concept. | 80 TODO(ianh): Describe the parent data concept. |
81 | 81 |
82 The `setParentData()` method is automatically called for each child | 82 The `setupParentData()` method is automatically called for each child |
83 when the child's parent is changed. However, if you need to | 83 when the child's parent is changed. However, if you need to |
84 preinitialise the `parentData` member to set its values before you add | 84 preinitialise the `parentData` member to set its values before you add |
85 a node to its parent, you can preemptively call that future parent's | 85 a node to its parent, you can preemptively call that future parent's |
86 `setParentData()` method with the future child as the argument. | 86 `setupParentData()` method with the future child as the argument. |
87 | 87 |
88 ### Box Model | 88 ### Box Model |
89 | 89 |
90 #### Dimensions | 90 #### Dimensions |
91 | 91 |
92 All dimensions are expressed as logical pixel units. Font sizes are | 92 All dimensions are expressed as logical pixel units. Font sizes are |
93 also in logical pixel units. Logical pixel units are approximately | 93 also in logical pixel units. Logical pixel units are approximately |
94 96dpi, but the precise value varies based on the hardware, in such a | 94 96dpi, but the precise value varies based on the hardware, in such a |
95 way as to optimise for performance and rendering quality while keeping | 95 way as to optimise for performance and rendering quality while keeping |
96 interfaces roughly the same size across devices regardless of the | 96 interfaces roughly the same size across devices regardless of the |
(...skipping 50 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
147 | 147 |
148 A subclass of `RenderObject` must fulfill the following contract: | 148 A subclass of `RenderObject` must fulfill the following contract: |
149 | 149 |
150 * It must fulfill the [AbstractNode contract](../base/README.md) when | 150 * It must fulfill the [AbstractNode contract](../base/README.md) when |
151 dealing with children. Using `RenderObjectWithChildMixin` or | 151 dealing with children. Using `RenderObjectWithChildMixin` or |
152 `ContainerRenderObjectMixin` can make this easier. | 152 `ContainerRenderObjectMixin` can make this easier. |
153 | 153 |
154 * Information about the child managed by the parent, e.g. typically | 154 * Information about the child managed by the parent, e.g. typically |
155 position information and configuration for the parent's layout, | 155 position information and configuration for the parent's layout, |
156 should be stored on the `parentData` member; to this effect, a | 156 should be stored on the `parentData` member; to this effect, a |
157 ParentData subclass should be defined and the `setParentData()` | 157 ParentData subclass should be defined and the `setupParentData()` |
158 method should be overriden to initialise the child's parent data | 158 method should be overriden to initialise the child's parent data |
159 appropriately. | 159 appropriately. |
160 | 160 |
161 * Layout constraints must be expressed in a Constraints subclass. This | 161 * Layout constraints must be expressed in a Constraints subclass. This |
162 subclass must implement operator== (and hashCode). | 162 subclass must implement operator== (and hashCode). |
163 | 163 |
164 * Whenever the layout needs updating, the `markNeedsLayout()` method | 164 * Whenever the layout needs updating, the `markNeedsLayout()` method |
165 should be called. | 165 should be called. |
166 | 166 |
167 * Whenever the rendering needs updating without changing the layout, | 167 * Whenever the rendering needs updating without changing the layout, |
(...skipping 33 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
201 ### The RenderBox contract | 201 ### The RenderBox contract |
202 | 202 |
203 A `RenderBox` subclass is required to implement the following contract: | 203 A `RenderBox` subclass is required to implement the following contract: |
204 | 204 |
205 * It must fulfill the [AbstractNode contract](../base/README.md) when | 205 * It must fulfill the [AbstractNode contract](../base/README.md) when |
206 dealing with children. Note that using `RenderObjectWithChildMixin` | 206 dealing with children. Note that using `RenderObjectWithChildMixin` |
207 or `ContainerRenderObjectMixin` takes care of this for you, assuming | 207 or `ContainerRenderObjectMixin` takes care of this for you, assuming |
208 you fulfill their contract instead. | 208 you fulfill their contract instead. |
209 | 209 |
210 * If it has any data to store on its children, it must define a | 210 * If it has any data to store on its children, it must define a |
211 BoxParentData subclass and override setParentData() to initialise | 211 BoxParentData subclass and override setupParentData() to initialise |
212 the child's parent data appropriately, as in the following example. | 212 the child's parent data appropriately, as in the following example. |
213 (If the subclass has an opinion about what type its children must | 213 (If the subclass has an opinion about what type its children must |
214 be, e.g. the way that `RenderBlock` wants its children to be | 214 be, e.g. the way that `RenderBlock` wants its children to be |
215 `RenderBox` nodes, then change the `setParentData()` signature | 215 `RenderBox` nodes, then change the `setupParentData()` signature |
216 accordingly, to catch misuse of the method.) | 216 accordingly, to catch misuse of the method.) |
217 | 217 |
218 ```dart | 218 ```dart |
219 class FooParentData extends BoxParentData { ... } | 219 class FooParentData extends BoxParentData { ... } |
220 | 220 |
221 // In RenderFoo | 221 // In RenderFoo |
222 void setParentData(RenderObject child) { | 222 void setupParentData(RenderObject child) { |
223 if (child.parentData is! FooParentData) | 223 if (child.parentData is! FooParentData) |
224 child.parentData = new FooParentData(); | 224 child.parentData = new FooParentData(); |
225 } | 225 } |
226 ``` | 226 ``` |
227 | 227 |
228 * The class must encapsulate a layout algorithm that has the following | 228 * The class must encapsulate a layout algorithm that has the following |
229 features: | 229 features: |
230 | 230 |
231 ** It uses as input a set of constraints, described by a | 231 ** It uses as input a set of constraints, described by a |
232 BoxConstraints object, and a set of zero or more children, as | 232 BoxConstraints object, and a set of zero or more children, as |
(...skipping 119 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
352 | 352 |
353 * Avoid using save/restore on canvases. | 353 * Avoid using save/restore on canvases. |
354 | 354 |
355 | 355 |
356 Dependencies | 356 Dependencies |
357 ------------ | 357 ------------ |
358 | 358 |
359 * [`package:sky/base`](../base) | 359 * [`package:sky/base`](../base) |
360 * [`package:sky/mojo`](../mojo) | 360 * [`package:sky/mojo`](../mojo) |
361 * [`package:sky/animation`](../mojo) | 361 * [`package:sky/animation`](../mojo) |
OLD | NEW |