# SLayout SLayout is a Unity component that can be added alongside any RectTransform, and provides: * **Easier, more convenient layout properties:** using a consistent coordinate system that works independently from a RectTransform’s anchoring, you can use properties like `x` to always refer to the distance from the parent rect’s left edge to the given rect’s edge (a bit like Unity’s IMGUI). * **Animation:** a system inspired by iOS’s Core Animation allows easy animation/tweening when using the above properties. ![](https://github.com/inkle/slayout/raw/master/slayout.gif) ## Getting started The core of SLayout is its set of [root properties](https://github.com/inkle/slayout/raw/master/#root-animatable-properties) such as `x`, `height` and `color`. Partly, these are simply convenience properties that wrap calls to the RectTransform (and any Text/Image/CanvasGroup) on your object, and use a simplified rect-based [coordinate system](https://github.com/inkle/slayout/raw/master/#coordinate-system) that doesn't depend on the RectTransform's anchoring. For example: var layout = GetComponent(); // Position RectTransform’s left edge at 100px from parent’s left edge layout.x = 100.0f; // Set the height to 50px, extending from the bottom edge upwards layout.height = 50.0f; However, using these properties consistently (instead of direct calls to the RectTransform) also allows you use SLayout's [animation methods](https://github.com/inkle/slayout/raw/master/#animation-reference). Each property does a quick check in the setter to see whether an animation is currently being defined, and then automatically lerps/tweens to the given values if so: // Animate x to 200px, height to 150px, easing with a duration 2.0 seconds layout.Animate(2.0f, () => { layout.x = 200.0f; layout.height = 150.0f; }); Which gives the following result: ![](https://github.com/inkle/slayout/raw/master/simple-anim.gif) There are a number of advantages to this technique. You don't have to learn a new syntax to an Animate method - you simply provide a duration and then in the animation method set the properties using the same code that you would use if you weren't animating. It also allows you to re-use code that you use to lay out views dynamically, even if the method does other things besides simply setting properties. You can even include loops in your animation code, positioning a set of views in one single `Animate` call. As mentioned above, the animation system was inspired by Apple's Core Animation system, and this is how iOS fluidly resizes views when the orientation of a device changes - it simply calls a standard layout method from within an animation block. For example, you could make your animation call like this: layout.Animate(0.5f, RefreshLayout); Which calls a standard `RefreshLayout()`, which may sometimes by called without animation (such as in `Start()`), and sometimes with animation as above: void RefreshLayout() { layout.width = layout.parentWidth; layout.height = 0.25f * layout.parentHeight; layout.color = _selected ? Color.yellow : Color.white; } You can also animate the values on another SLayout, such as a child: layout.Animate(0.5f, () => { childA.x = 100.0f; childB.color = Color.Red; }); The animation works by snapshotting the initial state of a property right before it's actually changed, and then snapshotting the state when the method that defines the animation is complete. It then automatically lerps (tweens) between them on subsequent frames. You can see examples of some of these things, take a look in the [SLayoutExamples project](https://github.com/inkle/slayout/tree/master/SLayoutExamples/SLayoutExamples) - start by taking a look at the **SimpleExamples** scene, with source in SimpleExamples.cs. For a more complex version of the `RefreshLayout` example, read on... ### A slightly more complex example Also in the [SLayoutExamples project](https://github.com/inkle/slayout/tree/master/SLayoutExamples/SLayoutExamples) is the ParagraphAnimatorExample, as shown in the gif: ![](https://github.com/inkle/slayout/raw/master/slayout.gif) We define the static layout function which positions all the individual word view using word wrapping. It takes 3 parameters which define how we're going to animate the individual words: void LayoutWords(Color color, float offset, float rotation) { float x = margin; float y = margin; foreach(var wordLayout in _wordLayouts) { var nextX = x; var nextY = y; // Word wrap when we exceed our line length if( nextX + wordLayout.width > lineWidth ) { nextX = margin; nextY += lineHeight; } wordLayout.x = nextX + offset; wordLayout.y = nextY; wordLayout.color = color; wordLayout.rotation = rotation; x = nextX + wordLayout.width + spaceWidth; y = nextY; // Delay before next word animates in // (When not animating, this does nothing) _layout.AddDelay(0.05f); } } Then, here's the setup to create the looping animation, which is initially kicked off from the `Start()` method: void Animate() { // Static, non-animated layout LayoutWords(Color.clear, offset:250, rotation:-5); // Animate into position with a new paragraph width _layout.Animate(0.5f, () => LayoutWords(Color.black, offset:150, rotation:0), completeAction:() => { // Animate out again in completion callback after a 2 second pause _layout.Animate(0.5f, 2.0f, () => LayoutWords(Color.clear, offset:50, rotation:+5) ); } ); // Repeat the whole sequence again _layout.After(6.0f, Animate); } For a few more examples, take a look in the full [Animation reference](https://github.com/inkle/slayout/raw/master/#animation-reference). ## Coordinate system SLayout provides a choice of two different coordinate systems, but by default it simply matches the normal UI system, where the Y axis points up the screen. To toggle between them, use the `originTopLeft` field on the `SLayout`, either in code or in the inspector. Importantly though, the coordinate system is consistent, no matter how the anchoring is set up on the RectTransform. * **Origin bottom left (default)**: `(0,0)` is in the bottom left corner of the parent RectTransform (the parent doesn't need to be an SLayout), with positive y going up the screen. This matches the way that Unity's UI system works. * **Origin top left**: Sometimes it's useful to flip the Y axis, so that the origin is in the top left of the parent rect, with positive Y values going down the screen. This matches Unity's legacy/Editor GUI system, and can make a lot more sense when you want to dynamically lay out a vertical flow that goes down the screen - for example paragraphs of text, or pretty much any other UI that "stacks". # Reference ### Root animatable properties All these properties get/set values on the RectTransform, CanvasGroup or Graphic directly - values aren't cached on the SLayout, except when animating. * `x` the distance from the left edge of the rect to the left edge of the parent rect. * `y` the distance from the bottom edge to the bottom edge of the parent rect, or when `originTopLeft` is true, `y` is the distance between he top edges. * `width` and `height` give the size of the RectTransform's rect. * `rotation` - single float maps to the transform's z euler rotation. * `scale` - single float maps to all three scale components on the transform. * `groupAlpha` - Tries to get/set a CanvasGroup's alpha property. Ignored if no CanvasGroup exists, it does nothing when setting, and returns `1.0` when getting. * `color` - Tries to get/set the color property of a Graphic component on the same object - for example, a Text or Image component. If no Graphic exists, it does nothing when setting, and returns `Color.white` when getting. ### Convenience animatable properties To make your code shorter and easier to read - these properties are simple wrappers for the root properties. All of these properties are animatable. * `rightX` - distance from right edge to parent rect's left edge. * `topY` - distance from top edge to parent's bottom edge. When using `originTopLeft`, it's the distance from the top edge to the parent's top edge. * `bottomY` - distance from bottom edge to parent's bottom edge. When using `originTopLeft`, it's the distance from the bottom edge to the parent's top edge. * `position` - `Vector2` of the root properties `x` and `y`. * `size` - `Vector2` of the root properties `width` and `height`. * `rect` - `Rect` of root properties `x`, `y`, `width` and `height`. * `localRect` - `Rect` that uses `width` and `height`. When getting, position is always `(0, 0)`. When setting, the position is used as an offset from the existing position. * `centerX` - `x + 0.5f * width` - doesn't use the RectTransform's pivot position. * `centerY` - `y + 0.5f * height` - doesn't use the RectTransform's pivot position. * `center` - `Vector2` of `centerX` and `centerY`. * `originX` - x position of own pivot in parent's rect. * `originY` - y position of own pivot in parent's rect. * `origin` - `Vector2` of `originX` and `originY`. ### Cached/other properties SLayout caches certain component references for easy/quick access and also provides a few other related properties: * `graphic` - internally obtained using `GetComponent` * `image` - attempts to cast the internal Graphic reference: `graphic as Image`. * `text` - attempts to cast the internal Graphic reference: `graphic as Text`. * `rectTransform` - calls `transform as RectTransform`. * `parentRectTransform` - calls `transform.parent as RectTransform`. * `parent` - calls `transform.parent.GetComponent()` * `parentRect` - Even if parent doesn't have an SLayout, this will be correct (as long as it is a RectTransform). * `canvas` - internally obtained using `transform.GetComponentInParent