Yoga Docs: Rename website-next to website (#1613)
Summary: Pull Request resolved: https://github.com/facebook/yoga/pull/1613 So that GitHub links to edit a page point to the right place. This will fail in OSS build until I switch the directory used by Vercel instance, but I am waiting to do that until ready to land, since that would cause other in progress changes to fail when exported. Reviewed By: joevilches Differential Revision: D54837857 fbshipit-source-id: 9bec90232dbe3ec8638568685671185d597fcf2d
This commit is contained in:
Nick Gerleman
committed by
Facebook GitHub Bot
Facebook GitHub Bot
parent
108c2f30a2
commit
206b95aba5
4
website/docs/getting-started/_category_.json
Normal file
4
website/docs/getting-started/_category_.json
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Getting Started",
|
||||
"position": 2
|
||||
}
|
||||
165
website/docs/getting-started/configuring-yoga.mdx
Normal file
165
website/docs/getting-started/configuring-yoga.mdx
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Configuring Yoga
|
||||
|
||||
Yoga may be configured to use different behavior, using a **Yoga Config**. A config is attached to a specific Yoga Node, allowing different parts of the Yoga tree to behave differently during layout.
|
||||
|
||||
Most UI frameworks will apply a single uniform configuration. It is common in these cases to allocate a single Yoga Config which lasts the duration of the application. Other ownership structures are possible, which allow scenarios like laying out part of a tree with a different layout conformance than another part of the tree.
|
||||
|
||||
| Global | Per-node | Contextual |
|
||||
| - | - | - |
|
||||
|  |  |  |
|
||||
|
||||
<Tabs groupId="language">
|
||||
|
||||
<TabItem value="cpp" label="C/C++">
|
||||
|
||||
```cpp
|
||||
#include <yoga/Yoga.h>
|
||||
|
||||
YGConfigRef config = YGConfigNew();
|
||||
// Setup config...
|
||||
|
||||
YGNodeRef root = YGNodeNewWithConfig(config);
|
||||
```
|
||||
|
||||
:::warning
|
||||
|
||||
Yoga configs are not freed automatically, and should be freed via `YGConfigFree(config)` when no longer needed.
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
import com.facebook.yoga.YogaConfigFactory;
|
||||
import com.facebook.yoga.YogaNodeFactory;
|
||||
|
||||
YogaConfig config = YogaConfigFactory.create();
|
||||
// Setup config...
|
||||
|
||||
YogaNode root = YogaNodeFactory.create(config);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="js" label="JavaScript">
|
||||
|
||||
```ts
|
||||
import Yoga from 'yoga-layout';
|
||||
|
||||
const config = Yoga.Config.create();
|
||||
// Setup config...
|
||||
|
||||
const root = Yoga.Node.create(config);
|
||||
```
|
||||
|
||||
:::warning
|
||||
|
||||
Yoga configs are not freed automatically, and should be freed via `config.free()` when no longer needed.
|
||||
|
||||
A future revision of JavaScript bindings for Yoga may move to garbage collection to remove this requirement.
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Layout Conformance and Yoga Errata
|
||||
|
||||
Yoga has historically had several behaviors which are not standards compliant, and can lead to styles being laid out differently compared to a web browser. Fixing issues with Yoga's behavior may change the layout of existing applications written against Yoga's previous behaviors. Yoga can be configured with a set of **Errata** which control whether Yoga prefers standard compliance, or backwards compatibility. By default, Yoga will prefer standards compliance.
|
||||
|
||||
Errata may be configured granularity, as a set of bit flags, with several common presets available:
|
||||
1. `None` (default): Prefer standards compliance. Breaking layout fixes are enabled when updating Yoga.
|
||||
2. `Classic`: Operate as close as possible to Yoga 1.x.
|
||||
3. `All`: Enable the errata in `Classic`, alongside `StretchFlexBasis`, mapping to `UseLegacyStretchBehaviour` in Yoga 1.x, which was not enabled by default.
|
||||
|
||||
<Tabs groupId="language">
|
||||
|
||||
<TabItem value="cpp" label="C/C++">
|
||||
|
||||
```cpp
|
||||
#include <yoga/Yoga.h>
|
||||
|
||||
YGConfigRef config = YGConfigNew();
|
||||
YGConfigSetErrata(config, YGErrataClassic);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
import com.facebook.yoga.YogaConfigFactory;
|
||||
import com.facebook.yoga.YogaErrata;
|
||||
|
||||
YogaConfig config = YogaConfigFactory.create();
|
||||
config.setErrata(YogaErrata.CLASSIC);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="js" label="JavaScript">
|
||||
|
||||
```ts
|
||||
import Yoga, {Errata} from 'yoga-layout';
|
||||
|
||||
const config = Yoga.Config.create();
|
||||
config.setErrata(Errata.Classic);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Point Scale Factor
|
||||
|
||||
Yoga represents positions on a floating-point grid of "points". This would normally lead to edges of a layout box ending up on a subpixel boundary when displayed by the underlying UI framework. This can create issues such as inconsistent rendering, or blurriness. To mitigate this, Yoga will by default round positions such that box edges are aligned to a physical "pixel grid".
|
||||
|
||||
Nodes may be configured with a `PointScaleFactor` to inform Yoga of the mapping between points to physical pixels (usually the "density" of the display). Pixel grid rounding may be disabled by setting `PointScaleFactor` to `0`.
|
||||
|
||||
| Before rounding | After rounding |
|
||||
| - | - |
|
||||
|  |  |
|
||||
|
||||
<Tabs groupId="language">
|
||||
|
||||
<TabItem value="cpp" label="C/C++">
|
||||
|
||||
```cpp
|
||||
#include <yoga/Yoga.h>
|
||||
|
||||
YGConfigRef config = YGConfigNew();
|
||||
YGConfigSetPointScaleFactor(config, 2.0f);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
import com.facebook.yoga.YogaConfigFactory;
|
||||
|
||||
YogaConfig config = YogaConfigFactory.create();
|
||||
config.setPointScaleFactor(2.0f);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="js" label="JavaScript">
|
||||
|
||||
```ts
|
||||
import Yoga from 'yoga-layout';
|
||||
|
||||
const config = Yoga.Config.create();
|
||||
config.setPointScaleFactor(2);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
178
website/docs/getting-started/laying-out-a-tree.mdx
Normal file
178
website/docs/getting-started/laying-out-a-tree.mdx
Normal file
@@ -0,0 +1,178 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
# Laying out a Yoga tree
|
||||
|
||||
Each box in Yoga is represented as a **Yoga Node**. These nodes form a tree which is used to store both input styles, and output layout results.
|
||||
|
||||
## Building a Yoga tree
|
||||
|
||||
Yoga nodes may be created, styled, and linked together. See [Styling](../styling/) for a more comprehensive reference of how to style a Yoga Node.
|
||||
|
||||
<Tabs groupId="language">
|
||||
|
||||
<TabItem value="cpp" label="C/C++">
|
||||
|
||||
```cpp
|
||||
#include <yoga/Yoga.h>
|
||||
|
||||
YGNodeRef root = YGNodeNew();
|
||||
YGNodeStyleSetFlexDirection(root, YGFlexDirectionRow);
|
||||
YGNodeStyleSetWidth(root, 100.0f);
|
||||
YGNodeStyleSetHeight(root, 100.0f);
|
||||
|
||||
YGNodeRef child0 = YGNodeNew();
|
||||
YGNodeStyleSetFlexGrow(child0, 1.0f);
|
||||
YGNodeStyleSetMargin(child0, YGEdgeRight, 10.0f);
|
||||
YGNodeInsertChild(root, child0, 0.0f);
|
||||
|
||||
YGNodeRef child1 = YGNodeNew();
|
||||
YGNodeStyleSetFlexGrow(child1, 1.0f);
|
||||
YGNodeInsertChild(root, child1, 1.0f);
|
||||
```
|
||||
|
||||
:::warning
|
||||
|
||||
Yoga Nodes are not freed automatically and should be discarded when no longer needed. Individual nodes may be freed by calling `YGNodeFree(node)`, or an entire Yoga tree may be freed by calling `YGNodeFreeRecursive(node)`.
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
import com.facebook.yoga.YogaEdge;
|
||||
import com.facebook.yoga.YogaFlexDirection;
|
||||
import com.facebook.yoga.YogaNode;
|
||||
import com.facebook.yoga.YogaNodeFactory;
|
||||
import com.facebook.yoga.YogaPositionType;
|
||||
|
||||
YogaNode root = YogaNodeFactory.create();
|
||||
root.setFlexDirection(YogaFlexDirection.ROW);
|
||||
root.setWidth(100.0f);
|
||||
root.setHeight(100.0f);
|
||||
|
||||
YogaNode child0 = YogaNodeFactory.create();
|
||||
child0.setFlexGrow(1.0f);
|
||||
child0.setMargin(YogaEdge.Right, 10.0f);
|
||||
root.addChildAt(child0, 0.0f);
|
||||
|
||||
YogaNode child1 = YogaNodeFactory.create();
|
||||
child1.setFlexGrow(1.0f);
|
||||
root.addChildAt(child1, 1.0f);
|
||||
```
|
||||
|
||||
:::info
|
||||
|
||||
Java backed Yoga Nodes are garbage collected, and do not need to manually be freed.
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="js" label="JavaScript">
|
||||
|
||||
```ts
|
||||
import Yoga, {Edge, FlexDirection, PositionType} from 'yoga-layout';
|
||||
|
||||
const root = Yoga.Node.create();
|
||||
root.setFlexDirection(FlexDirection.Row);
|
||||
root.setWidth(100);
|
||||
root.setHeight(100);
|
||||
|
||||
const child0 = Yoga.Node.create();
|
||||
child0.setFlexGrow(1);
|
||||
child0.setMargin(Edge.Right, 10);
|
||||
root.insertChild(child0, 0);
|
||||
|
||||
const child1 = Yoga.Node.create();
|
||||
child1.setFlexGrow(1);
|
||||
root.insertChild(child1, 1);
|
||||
```
|
||||
|
||||
:::warning
|
||||
|
||||
Yoga Nodes are not freed automatically and should be discarded when no longer needed. Individual nodes may be freed by calling `node.free()`, or an entire Yoga tree may be freed by calling `node.freeRecursive()`.
|
||||
|
||||
A future revision of JavaScript bindings for Yoga may move to garbage collection to remove this requirement.
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Laying out the tree
|
||||
|
||||
The full tree of Yoga nodes is laid out all at once. This layout may be constrained to a passed `availableWidth` and `availableHeight`, or may be allowed to expand infinitely in a given axis by passing Undefined.
|
||||
|
||||
<Tabs groupId="language">
|
||||
|
||||
<TabItem value="cpp" label="C/C++">
|
||||
|
||||
```cpp
|
||||
YGNodeCalculateLayout(root, YGUndefined, YGUndefined, YGDirectionLTR);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
root.calculateLayout(YogaConstants.UNDEFINED, YogaConstants.UNDEFINED);
|
||||
```
|
||||
|
||||
:::info
|
||||
|
||||
A tree of Java Yoga nodes may be laid out in RTL by setting the `direction` of the root node.
|
||||
|
||||
:::
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="js" label="JavaScript">
|
||||
|
||||
```ts
|
||||
root.calculateLayout(undefined, undefined, Direction.LTR);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## Reading layout results
|
||||
|
||||
Layout results are now written to each Yoga node. This includes an offset relative to the border box of the node's parent, along with dimensions, and the resolved values for margin, border, and padding for each physical edge.
|
||||
|
||||
<Tabs groupId="language">
|
||||
|
||||
<TabItem value="cpp" label="C/C++">
|
||||
|
||||
```cpp
|
||||
float left = YGNodeLayoutGetLeft(child0);
|
||||
float height = YGNodeLayoutGetHeight(child0);
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="java" label="Java">
|
||||
|
||||
```java
|
||||
float left = child0.getLayoutX();
|
||||
float height = child0.getLayoutHeight();
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
|
||||
<TabItem value="js" label="JavaScript">
|
||||
|
||||
```ts
|
||||
const left = child0.getComputedLeft();
|
||||
const height = child0.getComputedHeight();
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
Reference in New Issue
Block a user