From 49e18738c3b9e98aa652afcd2a9c66628670d332 Mon Sep 17 00:00:00 2001 From: Christine Abernathy Date: Wed, 5 Apr 2017 05:27:56 -0700 Subject: [PATCH] Remove gists and fix iOS instructions Summary: Remove gists in code blocks. This also made it easier to fix the iOS sample app instructions in the getting started. >Note: I also needed to update my gems as I was having problems running `bundle install`. The errors were around installing json v1.8.3. It was resolved by creating a new Gemfile.lock. 1. Build website and check changed pages (see attached Getting Started for an example) 2. Also check how it would look for mobile site (see attached index page) Verified that the code snippets matched previous snippets and styling acceptable. ![yoga_gs](https://cloud.githubusercontent.com/assets/691109/24681238/1601fcc8-1949-11e7-8caa-5ac78a4c9a6b.png) ![yoga_index_mobile](https://cloud.githubusercontent.com/assets/691109/24681248/1ee3ea86-1949-11e7-9677-83056f93e385.png) Closes https://github.com/facebook/yoga/pull/500 Differential Revision: D4834356 Pulled By: emilsjolander fbshipit-source-id: f47dca4b7518822b195f0bd5076fbf852904372b --- docs/Gemfile.lock | 40 ++--- docs/_docs/api/android.md | 49 +++++- docs/_docs/api/c.md | 242 +++++++++++++++++++++++++-- docs/_docs/api/csharp.md | 202 +++++++++++++++++++++- docs/_docs/api/java.md | 209 ++++++++++++++++++++++- docs/_docs/getting-started.md | 26 ++- docs/_docs/learn-more.md | 18 +- docs/_sass/_syntax-highlighting.scss | 20 ++- docs/css/main.scss | 2 +- docs/index.md | 128 ++++++++++++-- 10 files changed, 863 insertions(+), 73 deletions(-) diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 346fc6c1..e732b13d 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -11,14 +11,14 @@ GEM coffee-script (2.4.1) coffee-script-source execjs - coffee-script-source (1.10.0) + coffee-script-source (1.12.2) colorator (1.1.0) - ethon (0.9.1) + ethon (0.10.1) ffi (>= 1.3.0) execjs (2.7.0) - faraday (0.9.2) + faraday (0.12.0.1) multipart-post (>= 1.2, < 3) - ffi (1.9.14) + ffi (1.9.18) forwardable-extended (2.6.0) gemoji (2.1.0) github-pages (104) @@ -51,10 +51,10 @@ GEM octokit (~> 4.0) public_suffix (~> 1.4) typhoeus (~> 0.7) - html-pipeline (2.4.2) + html-pipeline (2.5.0) activesupport (>= 2) nokogiri (>= 1.4) - i18n (0.7.0) + i18n (0.8.1) jekyll (3.3.0) addressable (~> 2.4) colorator (~> 1.0) @@ -98,7 +98,7 @@ GEM gemoji (~> 2.0) html-pipeline (~> 2.2) jekyll (>= 3.0) - json (1.8.3) + json (1.8.6) kramdown (1.11.1) liquid (3.0.6) listen (3.0.6) @@ -107,33 +107,33 @@ GEM mercenary (0.3.6) mini_portile2 (2.1.0) minima (2.0.0) - minitest (5.9.1) + minitest (5.10.1) multipart-post (2.0.0) net-dns (0.8.0) - nokogiri (1.6.8.1) + nokogiri (1.7.1) mini_portile2 (~> 2.1.0) - octokit (4.4.1) - sawyer (~> 0.7.0, >= 0.5.3) + octokit (4.6.2) + sawyer (~> 0.8.0, >= 0.5.3) pathutil (0.14.0) forwardable-extended (~> 2.6) public_suffix (1.5.3) rb-fsevent (0.9.8) - rb-inotify (0.9.7) + rb-inotify (0.9.8) ffi (>= 0.5.0) rouge (1.11.1) safe_yaml (1.0.4) - sass (3.4.22) - sawyer (0.7.0) - addressable (>= 2.3.5, < 2.5) - faraday (~> 0.8, < 0.10) + sass (3.4.23) + sawyer (0.8.1) + addressable (>= 2.3.5, < 2.6) + faraday (~> 0.8, < 1.0) terminal-table (1.7.3) unicode-display_width (~> 1.1.1) - thread_safe (0.3.5) + thread_safe (0.3.6) typhoeus (0.8.0) ethon (>= 0.8.0) - tzinfo (1.2.2) + tzinfo (1.2.3) thread_safe (~> 0.1) - unicode-display_width (1.1.1) + unicode-display_width (1.1.3) PLATFORMS ruby @@ -142,4 +142,4 @@ DEPENDENCIES github-pages (~> 104) BUNDLED WITH - 1.13.1 + 1.14.6 diff --git a/docs/_docs/api/android.md b/docs/_docs/api/android.md index 1f46ab1f..3b9349d1 100644 --- a/docs/_docs/api/android.md +++ b/docs/_docs/api/android.md @@ -6,15 +6,56 @@ permalink: /docs/api/android/ --- To include the java bindings and `.so` libraries, add to your build: - -There is an easy interface to Yoga called `YogaLayout`. This is a view group that lays out its children using Yoga. We recommend looking at the sample app for details on its usage. However, as an overview you can simply define XML layouts such as - +```java +compile 'com.facebook.yoga:yoga:1.2.0' +``` + +There is an easy interface to Yoga called `YogaLayout`. This is a view group that lays out its children using Yoga. We recommend looking at the sample app for details on its usage. However, as an overview you can simply define XML layouts such as: + +```xml + + + + + + + +``` Note that there are some caveats, such as requiring the custom `YogaLayoutViewFactory` in order to have tags `YogaLayout` instead of `com.facebook.samples.yoga.YogaLayout`. To include this in your project, add to your build: - + +```java +compile 'com.facebook.yoga.android:yoga-layout:1.2.0' +``` ## layout\_width and layout\_height diff --git a/docs/_docs/api/c.md b/docs/_docs/api/c.md index 79b828ed..6560b4fe 100644 --- a/docs/_docs/api/c.md +++ b/docs/_docs/api/c.md @@ -10,7 +10,12 @@ permalink: /docs/api/c/ The following functions control the lifecycle of a `YGNodeRef`. - +```c +YGNodeRef YGNodeNew(); +void YGNodeReset(YGNodeRef node); +void YGNodeFree(YGNodeRef node); +void YGNodeFreeRecursive(YGNodeRef node); +``` - `YGNodeReset` will reset a node to its initial state so it can be re-used without needing to re-allocate a new node. - `YGNodeFreeRecursive` is mostly used for testing and will free not only the node itself but also its children. @@ -19,19 +24,167 @@ The following functions control the lifecycle of a `YGNodeRef`. The following functions help manage the children of a node. - +```c +void YGNodeInsertChild(YGNodeRef node, YGNodeRef child, uint32_t index); +void YGNodeRemoveChild(YGNodeRef node, YGNodeRef child); +YGNodeRef YGNodeGetChild(YGNodeRef node, uint32_t index); +uint32_t YGNodeChildCount(YGNodeRef node); +``` ### Style getters & setters The large part of Yoga's API consists of setters and getters for styles. These all follow the same general structure. Bellow are the function and enums used to control the various styles. For an in depth guide to how each style works see the getting started guide. - +```c +typedef enum YGDirection { + YGDirectionInherit, + YGDirectionLTR, + YGDirectionRTL, +} YGDirection; + +void YGNodeStyleSetDirection(YGNodeRef node, YGDirection direction); +YGDirection YGNodeStyleGetDirection(YGNodeRef node); + +typedef enum YGFlexDirection { + YGFlexDirectionColumn, + YGFlexDirectionColumnReverse, + YGFlexDirectionRow, + YGFlexDirectionRowReverse, +} YGFlexDirection; + +void YGNodeStyleSetFlexDirection(YGNodeRef node, + YGFlexDirection flexDirection); +YGFlexDirection YGNodeStyleGetFlexDirection(YGNodeRef node); + +typedef enum YGJustify { + YGJustifyFlexStart, + YGJustifyCenter, + YGJustifyFlexEnd, + YGJustifySpaceBetween, + YGJustifySpaceAround, +} YGJustify; + +void YGNodeStyleSetJustifyContent(YGNodeRef node, + YGJustify justifyContent); +YGJustify YGNodeStyleGetJustifyContent(YGNodeRef node); + +typedef enum YGAlign { + YGAlignAuto, + YGAlignFlexStart, + YGAlignCenter, + YGAlignFlexEnd, + YGAlignStretch, +} YGAlign; + +void YGNodeStyleSetAlignContent(YGNodeRef node, YGAlign alignContent); +YGAlign YGNodeStyleGetAlignContent(YGNodeRef node); + +void YGNodeStyleSetAlignItems(YGNodeRef node, YGAlign alignItems); +YGAlign YGNodeStyleGetAlignItems(YGNodeRef node); + +void YGNodeStyleSetAlignSelf(YGNodeRef node, YGAlign alignSelf); +YGAlign YGNodeStyleGetAlignSelf(YGNodeRef node); + +typedef enum YGPositionType { + YGPositionTypeRelative, + YGPositionTypeAbsolute, +} YGPositionType; + +void YGNodeStyleSetPositionType(YGNodeRef node, + YGPositionType positionType); +YGPositionType YGNodeStyleGetPositionType(YGNodeRef node); + +typedef enum YGWrap { + YGWrapNoWrap, + YGWrapWrap, +} YGWrap; + +void YGNodeStyleSetFlexWrap(YGNodeRef node, YGWrap flexWrap); +YGWrap YGNodeStyleGetFlexWrap(YGNodeRef node); + +typedef enum YGOverflow { + YGOverflowVisible, + YGOverflowHidden, + YGOverflowScroll, +} YGOverflow; + +void YGNodeStyleSetOverflow(YGNodeRef node, YGOverflow overflow); +YGOverflow YGNodeStyleGetOverflow(YGNodeRef node); + +void YGNodeStyleSetFlex(YGNodeRef node, float flex); + +void YGNodeStyleSetFlexGrow(YGNodeRef node, float flexGrow); +float YGNodeStyleGetFlexGrow(YGNodeRef node); + +void YGNodeStyleSetFlexShrink(YGNodeRef node, float flexShrink); +float YGNodeStyleGetFlexShrink(YGNodeRef node); + +void YGNodeStyleSetFlexBasis(YGNodeRef node, float flexBasis); +float YGNodeStyleGetFlexBasis(YGNodeRef node); + +typedef enum YGEdge { + YGEdgeLeft, + YGEdgeTop, + YGEdgeRight, + YGEdgeBottom, + YGEdgeStart, + YGEdgeEnd, + YGEdgeHorizontal, + YGEdgeVertical, + YGEdgeAll, +} YGEdge; + +void YGNodeStyleSetPosition(YGNodeRef node, YGEdge edge, float position); +float YGNodeStyleGetPosition(YGNodeRef node, YGEdge edge); + +void YGNodeStyleSetMargin(YGNodeRef node, YGEdge edge, float margin); +float YGNodeStyleGetMargin(YGNodeRef node, YGEdge edge); + +void YGNodeStyleSetPadding(YGNodeRef node, YGEdge edge, float padding); +float YGNodeStyleGetPadding(YGNodeRef node, YGEdge edge); + +void YGNodeStyleSetBorder(YGNodeRef node, YGEdge edge, float border); +float YGNodeStyleGetBorder(YGNodeRef node, YGEdge edge); + +void YGNodeStyleSetWidth(YGNodeRef node, float width); +float YGNodeStyleGetWidth(YGNodeRef node); + +void YGNodeStyleSetHeight(YGNodeRef node, float height); +float YGNodeStyleGetHeight(YGNodeRef node); + +void YGNodeStyleSetMinWidth(YGNodeRef node, float minWidth); +float YGNodeStyleGetMinWidth(YGNodeRef node); + +void YGNodeStyleSetMinHeight(YGNodeRef node, float minHeight); +float YGNodeStyleGetMinHeight(YGNodeRef node); + +void YGNodeStyleSetMaxWidth(YGNodeRef node, float maxWidth); +float YGNodeStyleGetMaxWidth(YGNodeRef node); + +void YGNodeStyleSetMaxHeight(YGNodeRef node, float maxHeight); +float YGNodeStyleGetMaxHeight(YGNodeRef node); + +void YGNodeStyleSetAspectRatio(YGNodeRef node, float aspectRatio); +float YGNodeStyleGetAspectRatio(YGNodeRef node); +``` ### Layout results Once you have set up a tree of nodes with styles you will want to get the result of a layout calculation. Call `YGNodeCalculateLayout` with the desired width and height or `YGUndefined` to perform the layout calculation. Once this function returns the results of the layout calculation is stored on each node. Traverse the tree and retrieve the values from each node. - +```c +void YGNodeCalculateLayout(YGNodeRef node, + float availableWidth, + float availableHeight, + YGDirection parentDirection); +float YGNodeLayoutGetLeft(YGNodeRef node); +float YGNodeLayoutGetTop(YGNodeRef node); +float YGNodeLayoutGetRight(YGNodeRef node); +float YGNodeLayoutGetBottom(YGNodeRef node); +float YGNodeLayoutGetWidth(YGNodeRef node); +float YGNodeLayoutGetHeight(YGNodeRef node); +YGDirection YGNodeLayoutGetDirection(YGNodeRef node); +``` ### Custom measurements @@ -41,34 +194,103 @@ Certain nodes need the ability to measure themselves, the most common example is > A measure function can only be attached to a leaf node in the hierarchy. - +```c +typedef enum YGMeasureMode { + YGMeasureModeUndefined, + YGMeasureModeExactly, + YGMeasureModeAtMost, +} YGMeasureMode; + +typedef struct YGSize { + float width; + float height; +} YGSize; + +typedef YGSize (*YGMeasureFunc)(YGNodeRef node, + float width, + YGMeasureMode widthMode, + float height, + YGMeasureMode heightMode); + +void YGNodeSetMeasureFunc(YGNodeRef node, YGMeasureFunc measureFunc); +YGMeasureFunc YGNodeGetMeasureFunc(YGNodeRef node); + +void YGNodeMarkDirty(YGNodeRef node); +bool YGNodeIsDirty(YGNodeRef node); +``` ### Context Context is important when integrating Yoga into another layout system. Context allows you to associate another object with a `YGNodeRef`. This context can then be retrieved from a `YGNodeRef` when for example its measure function is called. This is what enables Yoga to rely on the Android and iOS system implementations of text measurement in React Native. - +```c +void YGNodeSetContext(YGNodeRef node, void *context); +void *YGNodeGetContext(YGNodeRef node); +``` ### Logging Yoga will by default log to stdout and stderr. You may however customize this to instead log to your own logger. - +```c +typedef enum YGLogLevel { + YGLogLevelError, + YGLogLevelWarn, + YGLogLevelInfo, + YGLogLevelDebug, + YGLogLevelVerbose, +} YGLogLevel; + +typedef int (*YGLogger)(YGLogLevel level, char *format, va_list args); +void YGSetLogger(YGLogger logger); +void YGLog(YGLogLevel level, char *message, ...); +``` ### Experiments Yoga has the concept of experiments. An experiment is a feature which is not yet stable. To enable a feature use the following functions. Once a feature has been tested and is ready to be released as a stable API we will remove its feature flag. - +```c +typedef enum YGExperimentalFeature { + // Current experiments +} YGExperimentalFeature; + +void YGSetExperimentalFeatureEnabled(YGExperimentalFeature feature, + bool enabled); +bool YGIsExperimentalFeatureEnabled(YGExperimentalFeature feature); +``` ### Custom allocators You may want to swap out the allocator used in Yoga. These functions allow that. - +```c +typedef void *(*YGMalloc)(size_t size); +typedef void *(*YGCalloc)(size_t count, size_t size); +typedef void *(*YGRealloc)(void *ptr, size_t size); +typedef void (*YGFree)(void *ptr); + +void YGSetMemoryFuncs(YGMalloc cssMalloc, + YGCalloc cssCalloc, + YGRealloc cssRealloc, + YGFree cssFree); +``` ### Printing Yoga has some hooks to print debug information while calculating layout. With the printing APIs you can add additional information to a node when it is printed. - +```c +typedef enum YGPrintOptions { + YGPrintOptionsLayout = 1, + YGPrintOptionsStyle = 2, + YGPrintOptionsChildren = 4, +} YGPrintOptions; + +typedef void (*YGPrintFunc)(YGNodeRef node); + +void YGNodeSetPrintFunc(YGNodeRef node, YGPrintFunc printFunc); +YGPrintFunc YGNodeGetPrintFunc(YGNodeRef node); + +void YGNodePrint(YGNodeRef node, YGPrintOptions options); +``` diff --git a/docs/_docs/api/csharp.md b/docs/_docs/api/csharp.md index b3158ac2..8cf1e9e1 100644 --- a/docs/_docs/api/csharp.md +++ b/docs/_docs/api/csharp.md @@ -10,25 +10,176 @@ permalink: /docs/api/csharp/ Create a `YogaNode` via its default constructor or the static `Create()` builder method and use `Reset` if you want to pool and re-use nodes. The native memory of a `YogaNode` will automatically be freed when the node is garbage collected. - +```csharp +YogaNode(); +void Reset(); + +static YogaNode Create( + YogaDirection? styleDirection = null, + YogaFlexDirection? flexDirection = null, + YogaJustify? justifyContent = null, + YogaAlign? alignContent = null, + YogaAlign? alignItems = null, + YogaAlign? alignSelf = null, + YogaPositionType? positionType = null, + YogaWrap? wrap = null, + YogaOverflow? overflow = null, + float? flex = null, + float? flexGrow = null, + float? flexShrink = null, + float? flexBasis = null, + Spacing position = null, + Spacing margin = null, + Spacing padding = null, + Spacing border = null, + float? Width = null, + float? Height = null, + float? MaxWidth = null, + float? MaxHeight = null, + float? MinWidth = null, + float? MinHeight = null); +``` ### Children The following methods help manage the children of a node. - +```csharp +int Count { get }; +YogaNode this[int index] { get }; +void Insert(int index, YogaNode node); +void RemoveAt(int index); +void Clear(); +int IndexOf(YogaNode node); +``` ### Style getters & setters The large part of Yoga's API consists of properties, setters, and getters for styles. These all follow the same general structure. Bellow are the function and enums used to control the various styles. For an in depth guide to how each style works see the getting started guide. - +```csharp +enum YogaDirection +{ + Inherit, + LTR, + RTL, +} + +YogaDirection StyleDirection {get, set}; + +enum YogaFlexDirection +{ + Column, + ColumnReverse, + Row, + RowReverse, +} + +YogaFlexDirection FlexDirection {get, set}; + +enum YogaJustify +{ + FlexStart, + Center, + FlexEnd, + SpaceBetween, + SpaceAround, +} + +YogaJustify JustifyContent {get, set}; + +enum YogaAlign +{ + Auto, + FlexStart, + Center, + FlexEnd, + Stretch, +} + +YogaAlign AlignItems {get, set}; +YogaAlign AlignSelf {get, set}; +YogaAlign AlignContent {get, set}; + +enum YogaPositionType +{ + Relative, + Absolute, +} + +YogaPositionType PositionType {get, set}; + +enum YogaWrap +{ + NoWrap, + Wrap, +} + +YogaWrap Wrap {get, set}; + +enum YogaOverflow +{ + Visible, + Hidden, + Scroll, +} + +YogaOverflow Overflow {get, set}; + +float Flex {set}; +float FlexGrow {get, set}; +float FlexShrink {get, set}; +float FlexBasis {get, set}; + +enum YogaEdge +{ + Left, + Top, + Right, + Bottom, + Start, + End, + Horizontal, + Vertical, + All, +} + +float GetMargin(YogaEdge edge); +void SetMargin(YogaEdge edge, float margin); + +float GetPadding(YogaEdge edge); +void SetPadding(YogaEdge edge, float padding); + +float GetBorder(YogaEdge edge); +void SetBorder(YogaEdge edge, float border); + +float GetPosition(YogaEdge edge); +void SetPosition(YogaEdge edge, float position); + +float Width {get, set}; +float Height {get, set}; + +float MaxWidth {get, set}; +float MinWidth {get, set}; + +float MaxHeight {get, set}; +float MinHeight {get, set}; + +float AspectRatio {get, set}; +``` ### Layout results Once you have set up a tree of nodes with styles you will want to get the result of a layout calculation. Call `CalculateLayout()` perform layout calculation. Once this function returns the results of the layout calculation is stored on each node. Traverse the tree and retrieve the values from each node. - +```csharp +void CalculateLayout(); +float LayoutX {get}; +float LayoutY {get}; +float LayoutWidth {get}; +float LayoutHeight {get}; +YogaDirection LayoutDirection {get}; +``` ### Custom measurements @@ -38,16 +189,53 @@ Certain nodes need to ability to measure themselves, the most common example is > A measure function can only be attached to a leaf node in the hierarchy. - +```csharp +enum YogaMeasureMode +{ + Undefined, + Exactly, + AtMost, +} + +public delegate long MeasureFunction( + YogaNode node, + float width, + YogaMeasureMode widthMode, + float height, + YogaMeasureMode heightMode); + +class MeasureOutput +{ + public static long Make(int width, int height); +} + +void SetMeasureFunction(MeasureFunction measureFunction); +bool IsMeasureDefined(); + +bool IsDirty {get}; +void MarkDirty(); +``` ### Data Data is important when integrating Yoga into another layout system. Data allows you to associate another object with a `YogaNode`. This data can then be retrieved from a `YogaNode` when for example its measure function is called. This is what enables Yoga to rely on the Android system implementations of text measurement in React Native. - +```csharp +object Data {get, set} +``` ### Experiments Yoga has the concept of experiments. An experiment is a feature which is not yet stable. To enable a feature use the following functions. Once a feature has been tested and is ready to be released as a stable API we will remove its feature flag. - +```csharp +enum YogaExperimentalFeature { + // Current experiments +} + +static void setExperimentalFeatureEnabled( + YogaExperimentalFeature feature, + boolean enabled); +static boolean isExperimentalFeatureEnabled( + YogaExperimentalFeature feature); +``` diff --git a/docs/_docs/api/java.md b/docs/_docs/api/java.md index 16a9f10f..35686ce7 100644 --- a/docs/_docs/api/java.md +++ b/docs/_docs/api/java.md @@ -10,25 +10,166 @@ permalink: /docs/api/java/ Create a `YogaNode` via its default constructor and use `reset` if you want to pool and re-use nodes. The native memory of a `YogaNode` will automatically be freed when the node is garbage collected. - +```java +YogaNode(); +void reset(); +``` ### Children The following methods help manage the children of a node. - +```java +int getChildCount(); +YogaNodeType getChildAt(int i); +void addChildAt(YogaNodeType child, int i); +YogaNodeType removeChildAt(int i); +YogaNodeType getParent(); +int indexOf(YogaNodeType child); +``` ### Style getters & setters The large part of Yoga's API consists of setters and getters for styles. These all follow the same general structure. Bellow are the function and enums used to control the various styles. For an in depth guide to how each style works see the getting started guide. - +```java +enum YogaDirection { + INHERIT, + LTR, + RTL +} + +YogaDirection getStyleDirection(); +void setDirection(YogaDirection direction); + +enum YogaFlexDirection { + COLUMN, + COLUMN_REVERSE, + ROW, + ROW_REVERSE +} + +YogaFlexDirection getFlexDirection(); +void setFlexDirection(YogaFlexDirection flexDirection); + +enum YogaJustify { + FLEX_START, + CENTER, + FLEX_END, + SPACE_BETWEEN, + SPACE_AROUND +} + +YogaJustify getJustifyContent(); +void setJustifyContent(YogaJustify justifyContent); + +enum YogaAlign { + AUTO, + FLEX_START, + CENTER, + FLEX_END, + STRETCH +} + +YogaAlign getAlignItems(); +void setAlignItems(YogaAlign alignItems); + +YogaAlign getAlignSelf(); +void setAlignSelf(YogaAlign alignSelf); + +YogaAlign getAlignContent(); +void setAlignContent(YogaAlign alignContent); + +enum YogaPositionType { + RELATIVE, + ABSOLUTE +} + +YogaPositionType getPositionType(); +void setPositionType(YogaPositionType positionType); + +enum YogaWrap { + NO_WRAP, + WRAP +} + +void setWrap(YogaWrap flexWrap); + +enum YogaOverflow { + VISIBLE, + HIDDEN, + SCROLL +} + +YogaOverflow getOverflow(); +void setOverflow(YogaOverflow overflow); + +void setFlex(float flex); +float getFlexGrow(); +void setFlexGrow(float flexGrow); +float getFlexShrink(); +void setFlexShrink(float flexShrink); +float getFlexBasis(); +void setFlexBasis(float flexBasis); + +enum YogaEdge { + LEFT, + TOP, + RIGHT, + BOTTOM, + START, + END, + HORIZONTAL, + VERTICAL, + ALL +} + +float getMargin(YogaEdge edge); +void setMargin(YogaEdge edge, float margin); + +float getPadding(YogaEdge edge); +void setPadding(YogaEdge edge, float padding); + +float getBorder(YogaEdge edge); +void setBorder(YogaEdge edge, float border); + +float getPosition(YogaEdge edge); +void setPosition(YogaEdge edge, float position); + +float getWidth(); +void setWidth(float width); + +float getHeight(); +void setHeight(float height); + +float getMaxWidth(); +void setMaxWidth(float maxWidth); + +float getMinWidth(); +void setMinWidth(float minWidth); + +float getMaxHeight(); +void setMaxHeight(float maxHeight); + +float getMinHeight(); +void setMinHeight(float minHeight); + +float getAspectRatio(); +void setAspectRatio(float aspectRatio); +``` ### Layout results Once you have set up a tree of nodes with styles you will want to get the result of a layout calculation. Call `calculateLayout()` perform layout calculation. Once this function returns the results of the layout calculation is stored on each node. Traverse the tree and retrieve the values from each node. - +```java +void calculateLayout(); +float getLayoutX(); +float getLayoutY(); +float getLayoutWidth(); +float getLayoutHeight(); +YogaDirection getLayoutDirection(); +``` ### Custom measurements @@ -38,22 +179,74 @@ Certain nodes need to ability to measure themselves, the most common example is > A measure function can only be attached to a leaf node in the hierarchy. - +```java +enum YogaMeasureMode { + UNDEFINED, + EXACTLY, + AT_MOST +} + +interface YogaMeasureFunction { + long measure( + YogaNodeAPI node, + float width, + YogaMeasureMode widthMode, + float height, + YogaMeasureMode heightMode); +} + +class YogaMeasureOutput { + static long make(int width, int height); +} + +void setMeasureFunction(YogaMeasureFunction measureFunction); +boolean isMeasureDefined(); + +boolean isDirty(); +void dirty(); +``` ### Data Data is important when integrating Yoga into another layout system. Data allows you to associate another object with a `YogaNode`. This data can then be retrieved from a `YogaNode` when for example its measure function is called. This is what enables Yoga to rely on the Android system implementations of text measurement in React Native. - +```java +void setData(Object data); +Object getData(); +``` ### Logging Yoga will by default log to stdout and stderr (or logcat on Android). You may however customize this to instead log to your own logger. - +```java +enum YogaLogLevel { + ERROR, + WARN, + INFO, + DEBUG, + VERBOSE +} + +interface YogaLogger { + void log(YogaLogLevel level, String message); +} + +void setLogger(YogaLogger logger); +``` ### Experiments Yoga has the concept of experiments. An experiment is a feature which is not yet stable. To enable a feature use the following functions. Once a feature has been tested and is ready to be released as a stable API we will remove its feature flag. - +```java +enum YogaExperimentalFeature { + // Current experiments +} + +static void setExperimentalFeatureEnabled( + YogaExperimentalFeature feature, + boolean enabled); +static boolean isExperimentalFeatureEnabled( + YogaExperimentalFeature feature); +``` diff --git a/docs/_docs/getting-started.md b/docs/_docs/getting-started.md index 4b386c00..e01ff671 100644 --- a/docs/_docs/getting-started.md +++ b/docs/_docs/getting-started.md @@ -19,13 +19,22 @@ For now we recommend including Yoga as a [git submodule](https://git-scm.com/doc Yoga ships with an [iOS example](https://github.com/facebook/yoga/tree/master/YogaKit/YogaKitSample). To get it running: - +```sh +$ git clone https://github.com/facebook/yoga.git +$ cd open yoga/YogaKit/YogaKitSample/ +$ pod install +$ open YogaKitSample.xcworkspace +``` #### Android Yoga ships with an [Android example too](https://github.com/facebook/yoga/tree/master/android/sample). To get it running on an attached device (or emulator): - +```sh +$ git clone https://github.com/facebook/yoga.git +$ cd yoga +$ buck install -r android/sample +``` Actually, this is more than just an example, and more a layout system for Android using Yoga in general (see `YogaLayout`). For more information see the [Android API section](/yoga/docs/api/android). @@ -35,4 +44,15 @@ Yoga uses [Buck](https://buckbuild.com/) as its build system. Buck is not requir If you are using Buck all you need to do is reference the language bindings you want to use in your `BUCK` file. - +```sh +deps = [ + # C + '//path/to/submodule/yoga:yoga', + + # Java + '//path/to/submodule/yoga/java:jni', + + # Objective-C + '//path/to/submodule/yoga/YogaKit:YogaKit', +] +``` diff --git a/docs/_docs/learn-more.md b/docs/_docs/learn-more.md index 43e3e679..d7b1079a 100644 --- a/docs/_docs/learn-more.md +++ b/docs/_docs/learn-more.md @@ -15,7 +15,23 @@ Yoga aims to be compatible with Flexbox according to the [w3 specification](http Yoga has chosen to change the default values of some properties to better fit mobile layout use cases. The following CSS block describes the differences in default values from the [Flexbox w3 specification](https://www.w3.org/TR/css3-flexbox). - +```css +div { + box-sizing: border-box; + position: relative; + + display: flex; + flex-direction: column; + align-items: stretch; + flex-shrink: 0; + align-content: flex-start; + + border-width: 0px; + margin: 0px; + padding: 0px; + min-width: 0px; +} +``` We have set up a [JSFiddle](https://jsfiddle.net/emilsjolander/jckmwztt/) so you can see these default values in action. diff --git a/docs/_sass/_syntax-highlighting.scss b/docs/_sass/_syntax-highlighting.scss index 816e7493..50df5889 100644 --- a/docs/_sass/_syntax-highlighting.scss +++ b/docs/_sass/_syntax-highlighting.scss @@ -1,15 +1,15 @@ -.rougeHighlight { background-color: $code-bg; color: #93a1a1 } +.rougeHighlight { background-color: $code-bg; color: #000 } .rougeHighlight .c { color: #586e75 } /* Comment */ .rougeHighlight .err { color: #93a1a1 } /* Error */ .rougeHighlight .g { color: #93a1a1 } /* Generic */ .rougeHighlight .k { color: #859900 } /* Keyword */ .rougeHighlight .l { color: #93a1a1 } /* Literal */ -.rougeHighlight .n { color: #93a1a1 } /* Name */ +.rougeHighlight .n { color: #795da3 } /* Name */ .rougeHighlight .o { color: #859900 } /* Operator */ .rougeHighlight .x { color: #cb4b16 } /* Other */ -.rougeHighlight .p { color: #93a1a1 } /* Punctuation */ +.rougeHighlight .p { color: #000000 } /* Punctuation */ .rougeHighlight .cm { color: #586e75 } /* Comment.Multiline */ .rougeHighlight .cp { color: #859900 } /* Comment.Preproc */ .rougeHighlight .c1 { color: #72c02c; } /* Comment.Single */ @@ -20,7 +20,7 @@ .rougeHighlight .gh { color: #cb4b16 } /* Generic.Heading */ .rougeHighlight .gi { color: #859900 } /* Generic.Inserted */ .rougeHighlight .go { color: #93a1a1 } /* Generic.Output */ -.rougeHighlight .gp { color: #93a1a1 } /* Generic.Prompt */ +.rougeHighlight .gp { color: #000000 } /* Generic.Prompt */ .rougeHighlight .gs { color: #93a1a1; font-weight: bold } /* Generic.Strong */ .rougeHighlight .gu { color: #cb4b16 } /* Generic.Subheading */ .rougeHighlight .gt { color: #93a1a1 } /* Generic.Traceback */ @@ -41,11 +41,11 @@ .rougeHighlight .ni { color: #cb4b16 } /* Name.Entity */ .rougeHighlight .ne { color: #cb4b16 } /* Name.Exception */ .rougeHighlight .nf { color: #268bd2 } /* Name.Function */ -.rougeHighlight .nl { color: #93a1a1 } /* Name.Label */ +.rougeHighlight .nl { color: #0086b3 } /* Name.Label */ .rougeHighlight .nn { color: #93a1a1 } /* Name.Namespace */ .rougeHighlight .nx { color: #93a1a1 } /* Name.Other */ .rougeHighlight .py { color: #93a1a1 } /* Name.Property */ -.rougeHighlight .nt { color: #268bd2 } /* Name.Tag */ +.rougeHighlight .nt { color: #63a35c } /* Name.Tag */ .rougeHighlight .nv { color: #268bd2 } /* Name.Variable */ .rougeHighlight .ow { color: #859900 } /* Operator.Word */ .rougeHighlight .w { color: #93a1a1 } /* Text.Whitespace */ @@ -72,11 +72,12 @@ .highlighter-rouge { color: darken(#72c02c, 8%); - font: 800 12px/1.5em Hack, monospace; + font: 500 12px/1.8em "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace; max-width: 100%; .rougeHighlight { border-radius: 3px; + border: 1px solid #ccc; margin: 20px 0; padding: 0px; overflow-x: scroll; @@ -97,8 +98,9 @@ flex: 1 1; &.gutter { - border-right: 1px solid lighten($code-bg, 10%); - color: lighten($code-bg, 15%); + border-right: 1px solid darken($code-bg, 10%); + color: darken($code-bg, 25%); + margin-left: 10px; margin-right: 10px; max-width: 40px; padding-right: 10px; diff --git a/docs/css/main.scss b/docs/css/main.scss index 0dba6179..e977338b 100644 --- a/docs/css/main.scss +++ b/docs/css/main.scss @@ -86,7 +86,7 @@ $sidenav-overlay: lighten($sidenav, 10%); $sidenav-active: darken($sidenav, 10%); {% endif %} -$code-bg: #002b36; +$code-bg: #ffffff; $header-height: 34px; diff --git a/docs/index.md b/docs/index.md index 3faa5e21..6a2345c3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,8 +13,28 @@ id: home
-
- +
+
+```c +YGNodeRef root = YGNodeNew(); +YGNodeStyleSetWidth(root, 500); +YGNodeStyleSetHeight(root, 120); +YGNodeStyleSetFlexDirection(root, YGFlexDirectionRow); +YGNodeStyleSetPadding(root, YGEdgeAll, 20); + +YGNodeRef image = YGNodeNew(); +YGNodeStyleSetWidth(image, 80); +YGNodeStyleSetMargin(image, YGEdgeEnd, 20); + +YGNodeRef text = YGNodeNew(); +YGNodeStyleSetHeight(text, 25); +YGNodeStyleSetAlignSelf(text, YGAlignCenter); +YGNodeStyleSetFlexGrow(text, 1); + +YGNodeInsertChild(root, image, 0); +YGNodeInsertChild(root, text, 1); +``` +
@@ -28,8 +48,28 @@ id: home
-
- +
+
+```objc +UIView *root = [[UIView alloc] initWithFrame:CGRectMake(0, 0, 500, 300)]; +[root configureLayoutWithBlock:^void(YGLayout *layout) { + layout.isEnabled = YES; + layout.alignItems = YGAlignCenter; + layout.justifyContent = YGJustifyContentCenter; + layout.padding = 20.0f; +}]; + +UIImageView *image = [[UIImageView alloc] initWithFrame:CGRectMake(0, 0, 150, 150)]; +[image configureLayoutWithBlock:^void(YGLayout *layout) { + layout.isEnabled = YES; + layout.marginBottom = 20.0f; +}]; +[root addSubview:image]; + +UILabel *text = [[UILabel alloc] initWithFrame:CGRectMake(0, 0, 25, 100)]; +[root addSubview:text]; +``` +
@@ -43,8 +83,31 @@ id: home
-
- +
+
+```java +YogaNode root = new YogaNode(); +root.setWidth(500); +root.setHeight(300); +root.setAlignItems(CENTER); +root.setJustifyContent(CENTER); +root.setPadding(ALL, 20); + +YogaNode text = new YogaNode(); +text.setWidth(200); +text.setHeight(25); + +YogaNode image = new YogaNode(); +image.setWidth(50); +image.setHeight(50); +image.setPositionType(ABSOLUTE); +image.setPosition(END, 20); +image.setPosition(TOP, 20); + +root.addChildAt(text, 0); +root.addChildAt(image, 1); +``` +
@@ -58,8 +121,26 @@ id: home
-
- +
+
+```csharp +YogaNode root = YogaNode.Create( + width: 500, + height: 300, +); + +YogaNode image = YogaNode.Create(flexGrow: 1); + +YogaNode text = YogaNode.Create( + width: 300, + height: 25, + margin: new Spacing(left: 20, top: 20, right: 20, bottom: 20), +); + +root.Insert(image, 0); +root.Insert(text, 1); +``` +
@@ -76,8 +157,35 @@ id: home -
- +
+
+```xml + + + + + + + +``` +