You.i Engine
CYILinearLayout Class Reference

Detailed Description

A layout that positions all of its children in a row, a column, or a 'shaft'.

By default, children are arranged horizontally (i.e. in a row).

This layout respects the padding layout configuration option and the margin per-node layout configuration option.

Note
There are three 'helper' layout classes that can be used instead of CYILinearLayout: CYIRowLayout, CYIColumnLayout, and CYIShaftLayout. Using these classes will force a specific orientation on the linear layout.

Container View Template Comments Specification

These values are applied to the comment field of the container composition. All properties are optional.

Label Default value Accepted values Description
spacing 10.0 floating point The amount of space left between laid-out items.
justify false true, false If true, items will be laid-out to take the full width (or height for vertical layouts, or depth for shaft layouts) of the container. Items will be separated by an equal amount of space.
orientation horizontal horizontal, vertical, or shaft The orientation in which items will be laid-out in the layout: in a row, a column, or a shaft, respectively.
overflow ignore ignore, hide, wrap, wrap-and-hide The behaviour when items overflow the container. See the 'overflow' section for details.
line-gravity default default, start, middle, end, justify The alignment of lines in the non-layout direction. See the 'overflow' section for details.
Note
The meaning of the 'gravity' property of CYILayout is modified slightly by this class. See the 'Gravity and Justification' section for details.

The parent layout class may define more properties that can be used.

See also
CYIAnimatingLayout

Children View Template Comments Specification

This class has no configurable per-child properties, except for those of the parent class.

See also
CYIAnimatingLayout

Gravity and Justification

The meaning of the 'gravity' property is slightly altered by this layout. Normally, the gravity is applied to each child of the layout individually. But for linear layouts, the gravity value in the layout direction (for example the horizontal component of the gravity for horizontal linear layouts) is applied to the group of laid-out children rather than to individual children.

When an 'item gravity' per-node layout configuration is set on one (or more) of the children, that child may be aligned separately. The linear layout sorts children within each line in three groups: children aligned at the start of the line, children aligned at the end of the line, and children aligned at the middle of the line. If, during arrangement, the middle children would overlap with either the start or end children, then the middle children are offset appropriately to avoid overlap.

Warning
Setting a gravity value of 'none' for the layout direction will result in undefined behaviour.

As an example, the following diagram shows using a horizontal layout with two items and a gravity of 'top-right'.

+--------------------------------+
|               +------+ +------+|
|               |Item 1| |Item 2||
|               +------+ +------+|
|                                |
|                                |
+--------------------------------+

The 'justify' property has a special effect: if there are two or more layoutable children in the layout, the children will be laid out so that they fill the whole width of the container (or the full height for vertical layouts, or the full depth for shaft layouts). The amount of space between each pair of child will be kept equal, and will not be smaller than the value of the 'spacing' property. The following diagram shows justification when a gravity of 'bottom-right' is used:

+--------------------------------+
|                                |
|                                |
|+------+    +------+    +------+|
||Item 1|    |Item 2|    |Item 3||
|+------+    +------+    +------+|
+--------------------------------+

Overflow

By default, children are arranged in a single line. If the total length of all items exceeds the dimensions of the parent container in the layout direction, items are allowed to overflow outside of the container. This behaviour can be changed by setting the 'overflow' property.

Four different modes are available:

  • Ignore overflow. This is the default mode, where children are allowed to overflow outside of the container's bounds.
  • Hide. In this mode, children that overflow outside of the container's bounds (and any subsequent children) are hidden. Their size and position does not count towards the container's size when 'fit content' is used.
  • Wrap. In this mode, children that would overflow outside of the container's bounds are wrapped onto a new line. New lines are added and lines are allowed to overflow outside of the container (in the non-layout direction).
  • Wrap and hide. In this mode, children that would overflow outside of the container's bounds are wrapped onto a new line. If a new line would overflow outside of the bounds of the container, that line (and subsequent lines) is hidden.

When one of the wrap overflow modes is used, children may be arranged onto multiple lines. How these lines are arranged can be controlled with the 'line gravity' property. By default, lines are arranged using the same gravity as the layout itself. For example, given a linear layout set with a 'horizontal' orientation, a 'bottom-right' gravity, and enough items to fill two rows, the lines would be aligned to the bottom of the composition (with items within each individual lines being aligned to the right of the composition.)

Warning
The 'Hide' and 'Wrap and hide' overflow modes can manipulate the visibility of items in a composition. Manually hiding/showing children when using one of those overflow modes may result in unexpected behaviour (e.g. nodes that should be visible getting hidden, and nodes that should be hidden getting shown).

Lines can also be aligned to the start of the container, the middle of the container, or the end of the container. A 'justify' mode is available to position the lines such that they take up the full height or width of the container, with the amount of space between each pair of lines being equal.

Warning
Using items configured with a minimum size and 'fill parent' in the layout direction results in undefined behaviour when the 'minimum size' of the items differs between items and items are being wrapped onto new rows. Using items configured with a minimum size and 'fill parent' in the layout direction works correctly when all items have the same minimum size.

#include <layout/YiLinearLayout.h>

Inheritance diagram for CYILinearLayout:

Public Types

enum  Orientation {
  Orientation::Horizontal,
  Orientation::Vertical,
  Orientation::Shaft
}
 
enum  Overflow {
  Overflow::Ignore,
  Overflow::Hide,
  Overflow::Wrap,
  Overflow::WrapAndHide
}
 
enum  LineGravity {
  LineGravity::Default,
  LineGravity::Start,
  LineGravity::Middle,
  LineGravity::End,
  LineGravity::Justify
}
 
- Public Types inherited from CYILayout
enum  PositioningMode {
  PositioningMode::SetPositionDirectly,
  PositioningMode::DoNotSetPositionDirectly
}
 
typedef CYILayoutConfig::CubeOffset Padding
 

Public Member Functions

 CYILinearLayout ()
 
virtual ~CYILinearLayout ()
 
void SetSpacing (float spacing)
 
float GetSpacing () const
 
void SetJustify (bool justify)
 
bool IsUsingJustify () const
 
void SetOrientation (Orientation orientation)
 
Orientation GetOrientation () const
 
void SetOverflowMode (Overflow mode)
 
Overflow GetOverflowMode () const
 
void SetLineGravity (LineGravity lineGravity)
 
LineGravity GetLineGravity () const
 
- Public Member Functions inherited from CYIAnimatingLayout
 CYIAnimatingLayout ()
 
virtual ~CYIAnimatingLayout ()
 
void DisableAnimationsOnNextLayout (bool disable=true)
 
void DisableAnimationsOnNextLayoutFor (CYISceneNode *pChild, bool disable=true)
 
virtual void ChildAdded (CYISceneNode *pChild) override
 
virtual void ChildRemoved (CYISceneNode *pChild) override
 
virtual void ChildVisibilityChanged (CYISceneNode *pChild) override
 
void SetMovingTime (uint32_t movingTimeMs)
 
uint32_t GetMovingTimeMs () const
 
void SetSizingTime (uint32_t sizingTimeMs)
 
uint32_t GetSizingTimeMs () const
 
void SetTimeInterpolator (std::unique_ptr< CYITimeInterpolator > pInterpolator)
 
CYITimeInterpolatorGetTimeInterpolator ()
 
const CYITimeInterpolatorGetTimeInterpolator () const
 
- Public Member Functions inherited from CYILayout
 CYILayout ()
 
virtual ~CYILayout ()
 
void AttachTo (CYISceneView *pView)
 
void ConfigureFromAttachedNode ()
 
void DetachFromNode ()
 
CYISceneNodeGetAssociatedSceneNode () const
 
void Measure (const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec)
 
void ApplyMeasurements ()
 
void SetPositioningMode (PositioningMode positioningMode)
 
PositioningMode GetPositioningMode () const
 
void SetPadding (const Padding &padding)
 
const PaddingGetPadding () const
 
void SetUseReverseChildrenOrder (bool useReverseChildrenOrder)
 
bool IsUsingReverseChildrenOrder () const
 
void SetGravity (const glm::vec3 &layoutGravity)
 
void SetGravity (CYILayoutConfig::Gravity gravity)
 
const glm::vec3 & GetGravity () const
 

Protected Member Functions

virtual void Configure () override
 
virtual void OnMeasure (const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec) override
 
virtual void OnApplyMeasurements () override
 
- Protected Member Functions inherited from CYIAnimatingLayout
virtual void OnMeasurementsApplied () override
 
virtual const CYIRuntimeTypeInfoGetLayoutConfigType () const override
 
virtual void ApplyPosition (CYISceneNode *pChild, const glm::vec3 &position) override
 
virtual void ApplySize (CYISceneNode *pChild, const glm::vec3 &size) override
 
- Protected Member Functions inherited from CYILayout
virtual void OnSceneViewAttached ()
 
virtual void OnMeasurementsCalculated (const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec)
 
virtual std::unique_ptr< CYILayoutStateCreateLayoutStateInstance () const
 
void CreateLayoutObjectsFor (CYISceneNode *pNode) const
 
CYISceneNodeGetChild (size_t index) const
 
void ApplyMeasurementsToBackgroundChildren ()
 
const PaddingGetPaddingForChild (const CYISceneNode *pChild) const
 

Protected Attributes

float m_spacing
 
bool m_justify
 
Orientation m_orientation
 
Overflow m_overflowMode
 
LineGravity m_lineGravity
 
- Protected Attributes inherited from CYILayout
CYISceneViewm_pNode
 In most cases, this variable is used as a node (thus the name m_pNode ) More...
 
Padding m_padding
 
bool m_reverseChildrenOrder
 
glm::vec3 m_gravity
 
PositioningMode m_positioningMode
 

Additional Inherited Members

- Static Public Member Functions inherited from CYILayout
static void RegisterAllLayouts ()
 
static bool IsLayoutable (const CYISceneNode *pNode)
 
static glm::vec3 GetDefaultSize (const CYISceneNode *pNode, const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec)
 
static void UpdateMeasuredSizeForFitContent (const CYISceneNode *pNode, glm::vec3 *pMeasuredSize, const glm::vec3 &contentSize, const Padding &padding, const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec)
 
static void UnscaleMeasureSpecs (const glm::vec3 &scale, CYISceneNode::MeasureSpec *pWidthSpec, CYISceneNode::MeasureSpec *pHeightSpec, CYISceneNode::MeasureSpec *pDepthSpec)
 
static float CalculateDimension (const CYISceneNode::MeasureSpec &spec, const CYILayoutConfig::SizeConstraint &constraint, float currentValue)
 
- Protected Types inherited from CYILayout
enum  Dimensions {
  Dimensions::None = 0x0,
  Dimensions::X = 0x1,
  Dimensions::Y = 0x2,
  Dimensions::Z = 0x4,
  Dimensions::AllButX = Y | Z,
  Dimensions::AllButY = X | Z,
  Dimensions::AllButZ = X | Y,
  Dimensions::All = X | Y | Z
}
 
- Static Protected Member Functions inherited from CYILayout
static void MeasureChildWithMargins (CYISceneNode *pChild, const CYISceneNode::MeasureSpec &parentWidthSpec, const CYISceneNode::MeasureSpec &parentHeightSpec, const CYISceneNode::MeasureSpec &parentDepthSpec, const Padding &padding)
 
static void MeasureChildWithMargins (CYISceneNode *pChild, const CYISceneNode::MeasureSpec &parentWidthSpec, const CYISceneNode::MeasureSpec &parentHeightSpec, const CYISceneNode::MeasureSpec &parentDepthSpec, const Padding &padding, const glm::vec3 &childScale)
 
static CYISceneNode::MeasureSpec CalculateChildMeasureSpec (const CYISceneNode::MeasureSpec &parentMeasureSpec, float padding, const CYILayoutConfig::SizeConstraint &childConstraint, float childScale)
 
static bool UpdateMeasureSpecsForFitContent (const CYISceneNode *pNode, CYISceneNode::MeasureSpec *widthSpec, CYISceneNode::MeasureSpec *heightSpec, CYISceneNode::MeasureSpec *depthSpec)
 
static void RemeasureChildrenForFillParent (const CYISceneNode *pNode, const glm::vec3 &parentMeasuredSize, const Padding &padding, Dimensions dimensionsToRemeasure)
 
static glm::vec3 GetAdjustedPosition (const glm::vec3 &desiredTopLeftPosition, const CYISceneNode *pChild)
 
static glm::vec3 GetUnadjustedPosition (const glm::vec3 &currentTopLeftPosition, const CYISceneNode *pChild)
 
static glm::vec3 GetAdjustedMeasuredSize (const CYISceneNode *pChild)
 
static glm::vec3 GetTopLeftPositionWithGravity (const glm::vec3 &layoutGravity, const glm::vec3 &childGravity, const glm::vec3 &containerTopLeft, const glm::vec3 &containerSize, const CYILayout::Padding &padding, const glm::vec3 &childSize, const CYILayoutConfig::Margin &margin, const glm::vec3 &currentChildPosition)
 
static void MeasureBackgroundChildren (CYISceneNode *pNode, const glm::vec3 &size)
 

Member Enumeration Documentation

◆ LineGravity

Enumerator
Default 

Lines are aligned as indicated in the view's gravity value (in the non-layout direction)

Start 

Lines are aligned at the 'start' of the view (e.g. top for horizontal orientations and left for vertical orientations)

Middle 

Lines are aligned at the centre of the view.

End 

Lines are aligned at the 'end' of the view (e.g. bottom for horizontal orientations and right for vertical orientations)

Justify 

Lines are justified within the view (in the non-layout direction)

◆ Orientation

Enumerator
Horizontal 

Align children side-by-side along the x axis.

Vertical 

Align children along the y axis.

Shaft 

Align children on top of one another along the z axis.

◆ Overflow

Enumerator
Ignore 

Items are laid out in a single line. No consideration is made for items that overflow the view in the layout direction.

Hide 

Items are laid out in a single line. Items that overflow the view in the layout direction are hidden.

Wrap 

Items are laid out in one or more lines. Items that overflow the view in the layout direction are wrapped onto additional lines. No consideration is made for items that overflow the view in the non-layout direction.

WrapAndHide 

Items are laid out in one or more lines. Items that overflow the view in the layout direction are wrapped onto additional lines. Items that overflow the view in the non-layout direction are hidden.

Constructor & Destructor Documentation

◆ CYILinearLayout()

CYILinearLayout::CYILinearLayout ( )

◆ ~CYILinearLayout()

virtual CYILinearLayout::~CYILinearLayout ( )
virtual

Member Function Documentation

◆ Configure()

virtual void CYILinearLayout::Configure ( )
overrideprotectedvirtual

Extracts relevant properties the associated scene node and configures this layout with said properties.

Note
Subclasses should override this method if they have custom configuration values. Remember to call the parent Configure function.

Reimplemented from CYIAnimatingLayout.

Reimplemented in CYIAutoLinearLayout, CYIColumnLayout, CYIRowLayout, and CYIShaftLayout.

◆ GetLineGravity()

LineGravity CYILinearLayout::GetLineGravity ( ) const

◆ GetOrientation()

Orientation CYILinearLayout::GetOrientation ( ) const

◆ GetOverflowMode()

Overflow CYILinearLayout::GetOverflowMode ( ) const

◆ GetSpacing()

float CYILinearLayout::GetSpacing ( ) const

◆ IsUsingJustify()

bool CYILinearLayout::IsUsingJustify ( ) const

◆ OnApplyMeasurements()

virtual void CYILinearLayout::OnApplyMeasurements ( )
overrideprotectedvirtual

Applies the measured sizes of the associate scene node's children.

Warning
Implementations of this function are required to ensure that the ApplyMeasurements function of each child node is called at least once, even if those children are hidden or are non-laid-out.
Note
Typically, if OnApplyMeasurements is overridden then OnMeasure must also be overridden.
See also
CYILayout::ApplyMeasurements

Implements CYILayout.

◆ OnMeasure()

virtual void CYILinearLayout::OnMeasure ( const CYISceneNode::MeasureSpec widthSpec,
const CYISceneNode::MeasureSpec heightSpec,
const CYISceneNode::MeasureSpec depthSpec 
)
overrideprotectedvirtual

Measures the associated scene node, considering its layout configuration constraints (if available) and the provided measure specifications.

Warning
Implementations of this function are required to ensure that the Measure function of each child scene node is called at least once, even if those children are hidden or are non-laid-out.
Note
Typically, if OnMeasure is overridden then OnApplyMeasurements must also be overridden.
See also
CYILayout::Measure

Implements CYILayout.

Reimplemented in CYIAutoLinearLayout.

◆ SetJustify()

void CYILinearLayout::SetJustify ( bool  justify)

Enables or disables justification of laid-out items. By default, justification is disabled.

If enabled, laid-out items will fill the full width (or the full height for vertical layouts, or the full depth for shaft layouts) of the container. The amount of space between each pair of child will be kept equal, and will not be smaller than the value of the 'spacing' property.

◆ SetLineGravity()

void CYILinearLayout::SetLineGravity ( LineGravity  lineGravity)

Sets the line gravity to lineGravity.

The line gravity determines how individual lines get aligned in the non-layout direction. The default line gravity is 'default', which indicates that the gravity from the layout itself should be used as the line gravity.

Note
The line gravity has no effect when the overflow mode is CYILinearLayout::Overflow::Ignore

◆ SetOrientation()

void CYILinearLayout::SetOrientation ( Orientation  orientation)

Sets the orientation of this layout. The default orientation is horizontal.

Note
Alternatively, the layout classes CYIRowLayout, CYIColumnLayout and CYIShaftLayout can be used. These classes have their orientation pre-set to Horizontal, Vertical and Shaft respectively.
See also
CYILinearLayout::Orientation

◆ SetOverflowMode()

void CYILinearLayout::SetOverflowMode ( Overflow  mode)

Sets the overflow mode to mode. The default overflow mode is CYILinearLayout::Overflow::Ignore.

The overflow mode is used to determine how items should be aligned when the layout runs out of room in the layout direction. For more details, see CYILinearLayout.

◆ SetSpacing()

void CYILinearLayout::SetSpacing ( float  spacing)

Sets the spacing value to spacing. The default spacing is 10.0f.

The spacing is extra 'space' that will be added between laid-out items by the linear layout.

Note
Negative values are supported, and will result in the children overlapping each other.

Member Data Documentation

◆ m_justify

bool CYILinearLayout::m_justify
protected

◆ m_lineGravity

LineGravity CYILinearLayout::m_lineGravity
protected

◆ m_orientation

Orientation CYILinearLayout::m_orientation
protected

◆ m_overflowMode

Overflow CYILinearLayout::m_overflowMode
protected

◆ m_spacing

float CYILinearLayout::m_spacing
protected

The documentation for this class was generated from the following file: