diff --git a/_data/nav_docs.yml b/_data/nav_docs.yml index 5b54c005..77789128 100755 --- a/_data/nav_docs.yml +++ b/_data/nav_docs.yml @@ -34,6 +34,7 @@ - title: Layout items: - automatic-layout-containers + - layout-api-debugging - layout-api-sizing - layout-transition-api - title: Conveniences diff --git a/_docs/automatic-layout-containers.md b/_docs/automatic-layout-containers.md index 4b2be8ff..d728283d 100644 --- a/_docs/automatic-layout-containers.md +++ b/_docs/automatic-layout-containers.md @@ -3,7 +3,7 @@ title: LayoutSpecs layout: docs permalink: /docs/automatic-layout-containers.html prevPage: scroll-node.html -nextPage: layout-api-sizing.html +nextPage: layout-api-debugging.html --- AsyncDisplayKit includes a library of `layoutSpec` components that can be composed to declaratively specify a layout. The **child(ren) of a layoutSpec may be a node, a layoutSpec or a combination of the two types.** In the below image, an ASStackLayoutSpec (vertical) containing a text node and an image node, is wrapped in another ASStackLayoutSpec (horizontal) with another text node. diff --git a/_docs/automatic-layout-debugging.md b/_docs/automatic-layout-debugging.md deleted file mode 100755 index d3936467..00000000 --- a/_docs/automatic-layout-debugging.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Layout Debugging -layout: docs -permalink: /docs/automatic-layout-debugging.html -prevPage: automatic-layout-examples.html -nextPage: layout-options.html ---- - -##Debugging with ASCII Art - -##ASLayoutSpecPlayground App diff --git a/_docs/layout-api-debugging.md b/_docs/layout-api-debugging.md new file mode 100755 index 00000000..d79b7196 --- /dev/null +++ b/_docs/layout-api-debugging.md @@ -0,0 +1,73 @@ +--- +title: Layout Debugging +layout: docs +permalink: /docs/layout-api-debugging.html +prevPage: automatic-layout-containers.html +nextPage: layout-api-sizing.html +--- + +## Am I the child of a Stack spec or a Static spec? +
+Certain `ASLayoutable` properties will _only_ apply when the layoutable is a child of a _stack_ node (also known as ASStackLayoutable), while other properties _only_ apply when the layoutable is a child of a _static_ node (also known as ASStaticLayoutable). + +- table of `ASStackLayoutables` [properties](http://asyncdisplaykit.org/docs/automatic-layout-containers.html#asstacklayoutable-properties) +- table of `ASStaticLayoutable` [properties](http://asyncdisplaykit.org/docs/automatic-layout-containers.html#asstaticlayoutable-properties) + + +All ASLayoutable properties can be applied to _any_ layoutable (e.g. any node or layout spec), however certain properties will only take effect depending on the type of the parent layout spec they are wrapped in. + +## Have I provided sizes for any node that lacks an intrinsic size? +
+AsyncDisplayKit's layout pass is recursive, starting at the layoutSpec returned from -layoutSpecThatFits: and proceeding down until it reaches the leaf nodes included in any nested layoutSpecs. + +Some leaf nodes have a concept of their own intrinsic size, such as ASTextNode or ASImageNode. A text node knows the length of its formatted string and an ASImageNode knows the size of its static image. Other leaf nodes require an intrinsic size to be set. + +Nodes that require the developer to provide an intrinsic size: + +- `ASNetworkImageNode` or `ASMultiplexImageNode` have no intrinsic size until the image is downloaded. **A size must be provided for either node.** +- `ASVideoNode` or `ASVideoNodePlayer` have no intrinsic size until the video is downloaded. **A size must be provided for either node.** +- `ASDisplayNode` custom subclasses may provide their intrinisc size by implementing `-calculateSizeThatFits:`. + +To provide an intrinisc size for these nodes that lack intrinsic sizes (even if only momentarily), you can set one of the following: + +- set `.preferredFrameSize` for children of stack or static specs. +- set `.sizeRange` for children of **static** specs only. +- implement `-calculateSizeThatFits:` for **custom ASDisplayNode subclasses only**. + +*_Note that .preferredFrameSize is not considered by ASTextNodes. Also, setting .sizeRange on a node will override the node's intrinisic size provided by -calculateSizeThatFits:_ + +## Have I propogated selected `ASLayoutable` properties from an `ASLayoutable` object to its parent? +
+Upward and downward propogation of `ASLayoutable` properties between a child and its parent layoutSpec is currently disabled. This can be confusing, espcially for nodes in a single child layoutSpec. Depending on the desired UI, in certain cases, `ASLayoutable` properties must be manually set on the layout spec rather than its child. + +Make sure this is the layout effect that you actually desire. For layout specs with multiple children, such as a stack, setting flexShrink on the layout spec itself of course has a very different meaning than on one of the children. + +Two common examples of this that we see include: + +- A node with `.flexGrow` enabled is wrapped in an inset spec. "It" will not flexGrow. **Solution:** enable .flexGrow on the parent inset spec as well. +- A node with `.flexGrow` enabled is wrapped in a static layoutSpec, wrapped in a stack layoutSpec. **Solution:** enable .flexGrow on the static layoutSpec as well. + +## When do I use `.preferredFrameSize` vs `.sizeRange`? +
+Set `.preferredFrameSize` to set a size for the child of any layout spec. Note that setting .preferredFrameSize on an `ASTextNode` will silently fail. We are working on fixing this, but in the meantime, you can wrap the ASTextNode in a static spec and provide it a .sizeRange. + +If your `ASLayoutable` object (any node or layout spec) is the child of a *static* spec, then you may provide it a `.sizeRange`, consisting of a minimum and maximum constrained size. These sizes can be a specific point value or a relative value, like 70%. + +For details on the `.sizeRange` property's custom value type, check out our [Layout API Sizing guide](http://asyncdisplaykit.org/docs/layout-api-sizing.html). + +## `ASRelativeDimension` vs `ASRelativeSize` vs `ASRelativeSizeRange` vs `ASSizeRange` +
+AsyncDisplayKit's Layout API supports configuring node and layout spec sizes with specific point values as well as relative values. Read the [Layout API Sizing guide](http://asyncdisplaykit.org/docs/layout-api-sizing.html) for a helpful chart and documentation on our custom layout value types. + +## Debugging layout specs with ASCII art +
+Calling `-asciiArtString` on any `ASDisplayNode` or `ASLayoutSpec` returns an ascii-art representation of the object and its children. An example of a simple layoutSpec ascii-art console output can be seen below. + +``` +-----------------------ASStackLayoutSpec---------------------- +| -----ASStackLayoutSpec----- -----ASStackLayoutSpec----- | +| | ASImageNode | | ASImageNode | | +| | ASImageNode | | ASImageNode | | +| --------------------------- --------------------------- | +-------------------------------------------------------------- + ``` diff --git a/_docs/layout-api-sizing.md b/_docs/layout-api-sizing.md index d6815a9a..8bfe499c 100644 --- a/_docs/layout-api-sizing.md +++ b/_docs/layout-api-sizing.md @@ -2,7 +2,7 @@ title: Layout API Sizing layout: docs permalink: /docs/layout-api-sizing.html -prevPage: automatic-layout-containers.html +prevPage: layout-api-debugging.html nextPage: layout-transition-api.html ---