diff --git a/sdk/lib/base/README.md b/sdk/lib/base/README.md index 56cb8a346b3df3348b3f9b5168db1589319f36f4..43cd23fb3afbe638522e8e461c6a4f22307a8ac2 100644 --- a/sdk/lib/base/README.md +++ b/sdk/lib/base/README.md @@ -1,2 +1,7 @@ -Libraries in this directory depend on nothing but Dart's core -libraries and the ```dart:sky``` library exposed by Sky's platform. +Sky Base +======== + +Dependencies +------------ + +No dependencies except for `dart:sky` and Dart's core libraries. diff --git a/sdk/lib/rendering/README.md b/sdk/lib/rendering/README.md index 8726c5aa7a5abea664ad9f91f6651e8868ac1207..37ad6e2e8913f9ccf6df5b9d90f06f7376ffdc5d 100644 --- a/sdk/lib/rendering/README.md +++ b/sdk/lib/rendering/README.md @@ -1,3 +1,93 @@ -This directory introduces a layout and painting system built on the -Sky APIs. It depends on Dart primitives, ../base/*, ../mojo/*, and -../animation/*. +Sky Rendering +============= + +The Sky render tree is a low-level layout and painting system based on a +retained tree of objects that inherit from [`RenderObject`](object.dart). Most +developers using Sky will not need to interact directly with the rendering tree. +Instead, most developers should use [Sky widgets](../widgets/README.md), which +are built using the render tree. + +Base Model +---------- + +The base class for every node in the render tree is +[`RenderObject`](object.dart), which defines the base layout model. The base +layout mode is extremely general and can accomodate a large number of more +concrete layout models that can co-exist in the same tree. For example, the base +model does not commit to a fixed number of dimensions or even a cartesian +coordinate system. In this way, a single render tree can contain render objects +operating in three-dimensional space together with other render objects +operating in two-dimensional space, e.g., on the face of a cube in the three- +dimensional space. Moreover, the two-dimensional layout might be partially +computed in cartesian coordinates and partially computed in polar coordinates. +These distinct models can interact during layout, for example determining the +size of the cube by the height of a block of text on the cube's face. + +Not entirely free-wheeling, the base model does impose some structure on the +render tree: + + * Subclasses of `RenderObject` must implement a `performLayout` function that + takes as input a `constraints` object provided by its parent. `RenderObject` + has no opinion about the structure of this object and different layout models + use different types of constraints. However, whatever type they choose must + implement `operator==` in such a way that `performLayout` produces the same + output for two `constraints` objects that are `operator==`. + + * Implementations of `performLayout` are expected to call `layout` on their + children. When calling `layout`, a `RenderObject` must use the + `parentUsesSize` parameter to declare whether its `performLayout` function + depends on information read from the child. If the parent doesn't declare + that it uses the child's size, the edge from the parent to the child becomes + a _relayout boundary_, which means the child (and its subtree) might undergo + layout without the parent undergoing layout. + + * Subclasses of `RenderObject` must implement a `paint` function that draws a + visual representation of the object onto an `RenderObjectDisplayList`. If + the `RenderObject` has children, the `RenderObject` is responsible for + painting its children using the `paintChild` function. + + * Subclasses of `RenderObject` must call `adoptChild` whenever they add a + child. Similarly, they must call `dropChild` whenever they remove a child. + + * Most subclasses of `RenderObject` will implement a `hitTest` function that + lets clients query the render tree for objects that intersect with a given + user input location. `RenderObject` itself does not impose a particular + type signature on `hitTest`, but most implementations will take an argument + of type `HitTestResult` (or, more likely, a model-specific subclass of + `HitTestResult`) as well as an object that describes the location at which + the user provided input (e.g., a `Point` for a two-dimensional cartesian + model). + + * Finally, subclasses of `RenderObject` can override the default, do-nothing + implemenations of `handleEvent` and `rotate` to respond to user input and + screen rotation, respectively. + +The base model also provides two mixins for common child models: + + * `RenderObjectWithChildMixin` is useful for subclasses of `RenderObject` that + have a unique child. + + * `ContainerRenderObjectMixin` is useful for subclasses of `RenderObject` that + have a child list. + +Subclasses of `RenderObject` are not required to use either of these child +models and are free to invent novel child models for their specific use cases. + +Parent Data +----------- + + +Box Model +--------- + + +Bespoke Models +-------------- + + +Dependencies +------------ + + * [`package:sky/base`](../base) + * [`package:sky/mojo`](../mojo) + * [`package:sky/animation`](../mojo) diff --git a/sdk/lib/widgets/README.md b/sdk/lib/widgets/README.md index a2842527fecd0634a72f980803bff22f8594f5fb..3ddfb85aadcdb6e5a9d6b069c85a2a80b0d8ac01 100644 --- a/sdk/lib/widgets/README.md +++ b/sdk/lib/widgets/README.md @@ -411,3 +411,13 @@ copies of a particular widget to fill its visible region: Moreover, syncing the entries semantically means that state retained in stateful subcomponents will remain attached to the same semantic entry rather than the entry in the same numerical position in the viewport. + +Dependencies +------------ + + * `package:vector_math` + * [`package:sky/animation`](../animation) + * [`package:sky/base`](../base) + * [`package:sky/painting`](../painting) + * [`package:sky/rendering`](../rendering) + * [`package:sky/theme`](../theme)