You.i Engine
CYILayout Class Referenceabstract

Detailed Description

This class defines a layout that can be applied to a scene view. The layout class determines how objects should be laid out, and can apply that layout configuration.

Layout configuration can be done either through setters, or automatically through the CYILayout::Configure method.

Note
Changing the configuration of a layout object (for example by using setters) does NOT cause an automatic dirtying of the associated scene view. If desired, you should manually call CYISceneNode::RequestLayout on the associated scene view.

This class is expected to be subclassed to implement actual layouts.

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
padding 0.0 floating point A value subtracted from the container's size when layout out children. The padding effectively reduces the size of the container. Padding can be used to leave an 'empty' border around laid-out elements. Using this property sets the padding-front and padding-back values to 0.
padding-top 0.0 floating point The container's top padding value.
padding-bottom 0.0 floating point The container's bottom padding value.
padding-left 0.0 floating point The container's left padding value.
padding-right 0.0 floating point The container's right padding value.
padding-front 0.0 floating point The container's front padding value.
padding-back 0.0 floating point The container's back padding value.
reverse-order true true, false Reverses the order in which children are laid out: if set to false, the first laid-out child will be the last layer.
gravity top-left-front special* Specifies the direction that children should align when the layout does not specify an alignment. See Gravity Values further down for details. Can be overridden in children by using the 'item-gravity' property.

Children View Template Comments Specification

These values are applied to the comment field of the to-be-laid-out children. All properties are optional.

Label Default value Accepted values Description
layoutable true true, false If set to false, the child will be ignored by the layout and its size/position will not be changed.
margin 0.0 floating point A value that increases the space left around a specific child in its parent when laying out elements. Similar to padding, but controls the space left 'outside' of the child. Using this property sets the margin-front and margin-back values to 0.
margin-top 0.0 floating point The child's top margin value.
margin-bottom 0.0 floating point The child's bottom margin value.
margin-left 0.0 floating point The child's left margin value.
margin-right 0.0 floating point The child's right margin value.
margin-front 0.0 floating point The child's front margin value. Used for 3D layouts.
margin-back 0.0 floating point The child's back margin value. Used for 3D layouts.
width actual (see notes) The child's preferred width. Cannot be negative.
min-width none (see notes) The child's minimum width. Cannot be negative.
max-width none (see notes) The child's maximum width. Cannot be negative.
height actual (see notes) The child's preferred height. Cannot be negative.
min-height none (see notes) The child's minimum height. Cannot be negative
max-height none (see notes) The child's maximum height. Cannot be negative.
depth actual (see notes) The child's preferred depth. Cannot be negative.
min-depth none (see notes) The child's minimum depth. Cannot be negative.
max-depth none (see notes) The child's maximum depth. Cannot be negative.
maintain-aspect-ratio false true, false If true, the layout system will try to preserve the child's width/height aspect ratio. See Maintain Aspect Ratio further down for details.
fill-parent false true, false Setting to true is the equivalent to width=fill; height=fill; depth=fill. Setting to false has no effect.
fit-content false true, false Setting to true is the equivalent of width=fit; height=fit; depth=fit. Setting to false has no effect.
item-gravity none (see gravity values section) Specifies the direction that an object should align when the associated layout does not specify an alignment. See Gravity Values further down for details.
background false true, false If set to true, this child will not be considered part of the layout but will be laid out to fill its parent. The padding value of the layout will be ignored.
Note
The margin values are specified in the parent's coordinate space, and thus the effective margin will not be affected by the individual child's scale.
The width, height and depth fields (as well as the min-* and max-* versions) do not support negative values. The actual size of the child will be affected by the child's scale.
The width, height and depth fields can take the following special values:
  • 'fill-parent' (or 'fill'): indicates that the child should get its size from its parent composition.
  • 'fit-content' (or 'fit'): indicates that the child should get its size from its own children. This value can only be used on children that also have a layout assigned to them.

Gravity Values

Note
Values other than none and center can be combined to form combined gravity values. For example: gravity:top-left or gravity:bottom-front-right

Allowed 'raw' values:

  • center (centers the child in the parent vertically and horizontally)
  • top (centers horizontally)
  • bottom (centers horizontally)
  • left (centers vertically)
  • right (centers vertically)
  • front (centers horizontally and vertically)
  • back (centers horizontally and vertically)
  • none (for the 'gravity' property only – indicates that the existing position of the child will be retained)
  • parent (for the 'item-gravity' property only – indicates that the gravity value of the parent layout should be used)

Common combined values:

  • top-left
  • top-right
  • bottom-left
  • bottom-right

Maintain Aspect Ratio

The maintainAspectRatio from CYILayoutConfig::SizeConstraints (and from the 'maintain-aspect-ratio' child comment) can be used to indicate to the layout system that the width/height aspect ratio of the child should be constrainted to a specific aspect ratio.

In most cases, the current size of the child is used to determine this aspect ratio, but other values can be used. The following list indicates the order in which alternate values are used:

  1. If the child has both a preferred width and preferred height, those values are used to determine the target aspect ratio.
  2. If the child has both a minimum width and a minimum height, those values are used to determined the target aspect ratio.
  3. If the child has both a maximum width and a maximum height, those values are used to determined the target aspect ratio.
  4. If the initial width and height of the child are non-zero (as obtained from the child's size at initialization), those values are used to determine the target aspect ratio.
  5. Otherwise, the aspect ratio is not maintained.

If either of the examined width and height is zero or negative, that pair of values is rejected for calculation of the target aspect ratio and the next entry in the list is used.

During layout, the target aspect ratio is used to decrease the 'default size' of measured scene nodes to respect the target aspect ratio. For scene views configured to 'fit content' in width and/or height, the content size is subsequently increased to respect the target aspect ratio.

Note
While the 'preferred width' and 'preferred height' properties seem like the logical properties to use to specify a custom aspect ratio, those values cannot be specified at the same time as the 'fill parent' or 'fit content' properties. As a result, those values are often not usable.
The application of a target aspect ratio to a child's size further constraints the possible sizes, and may result in the minimum and maximum width/height to not be respected.
The size of text scene nodes depends on what text is rendered into them. Because of this, usage of the 'maintain aspect ratio' flag on text scene node is not supported.

Writing Custom Layouts

In some cases, it may be necessary or desired to write a custom CYILayout class. This section gives an overview of things that must or should be done to do this.

If animations are desired, the CYIAnimatingLayout class should be used as base class for custom layouts instead of CYILayout. This is because many of the animation features are implemented only in CYIAnimatingLayout.

When anything happens to a scene node that would cause it to need to be relaid out, that node (and potentially its children and/or parent) will be flagged as 'layout dirty'. Things that would cause a node be be 'layout dirty'ed include, but is not limited to, having children added or removed, being added to the scene tree, having its size or scale changed, having a layout assigned to the node, or having the node shown or hidden. Users can also manually request a relayout.

The actual laying out of children happens during the 'update' cycle. First, the system 'updates' the scene tree. Once that's done, the system checks if any of the nodes are flagged as 'layout dirty'. If so, those nodes are measured, and then the measurements are applied. If any of the nodes are dirtied during that process, the system 'updates' the scene tree again.

Two types of layout configuration exists: per-layout configuration, and per-child configuration. The latter is set directly on the layout itself (or as properties on the associated node). The former is set in CYILayoutConfig objects on the children of the node associated with the layout. For example, the padding is a layout configuration value (since it applies to all children of the layout's associated node), while the margin is a per-child configuration value (since each child of the associate node could have a different margin value).

When a layout is associated with a node, the layout is configured from properties present in the node. This is done by calling the Configure function. Custom layouts that add custom configuration values should override the Configure function. It is important that the parent class' Configure function be called. Failure to do so will result in some layout configuration values not being read properly.

If a custom layout needs to provide custom per-child configuration values, a few steps are required. First, a new sub-class of CYILayoutConfig must be made for the custom layout. That sub-class must use as parent the layout config class associated with the parent layout. For example, if a custom layout subclasses CYIAnimatingLayout, then the custom layout's layout config class must subclass CYIAnimatingLayoutConfig . The CYILayoutConfig::ConfigureFrom function should be overridden. Do not forget to call the parent class' ConfigureFrom function. Finally, the CYILayout::GetLayoutConfigType function must be overridden to return the type of CYILayoutConfig object to create for the layout if the layout uses a different layout config type.

In some cases, a layout may need to save per-child layout state. This is similar to providing custom per-child configuration values: a custom CYILayoutState class must be created, and the CYILayout::CreateLayoutStateInstance function must be overridden to create an instance of the proper type. Instances will automatically be created and assigned to all children of the associated scene node.

Custom layouts will typically want to implement both the OnMeasure and OnApplyMeasurements functions. OnMeasure is used to measure a node and all of its children. OnApplyMeasurements is used to 'apply' the measured sizes positions to the child nodes. Both functions are recursive.

Most of the 'work' in a layout is performed in the OnMeasure function. The implementation of that function is responsible for analyzing the provided width, height and depth MeasureSpec values, combining it with the layout constraints, and coming up with a measured size for the associated node. The measured size may also depend on the measured size of the children of the associated node. Whether it does or not, the OnMeasure function is required to call the CYISceneNode::Measure function of all of the associated node's children.

The implementation of the OnApplyMeasurements function is used to 'apply' the measured sizes. This involves setting the size and position of the children of the associated node. Note that the OnApplyMeasurements function is not responsible for setting its own size. This is done in the parent layout (or parent node) in order to allow for animating sizes.

The base layout class provides configuration for padding, margin and gravity. Whenever possible, custom layouts should respect those configuration values in order to provide a consistent API.

Some child nodes can be marked as 'non-layoutable'. This should be checked for and respected by custom layouts. These non-layoutable nodes still need to be measured and have their measurements applied, but they should not have a size or position set by the layout. The IsLayoutable utility function can be used to check if a node is layoutable.

Some child nodes can be marked as 'background' nodes. This can be checked by using the CYILayoutConfig::IsBackground function on the child node's layout configuration. Background nodes are nodes whose size will match that of their parent, ignoring the parent's padding values. The MeasureBackgroundChildren function can be used to facilitate measurement of background nodes. When measurements are applied, all configuration values of the layout and child node (except for padding) should be used.

Some of the layout constraints need special handling. One of these is the 'fit content' constraint: when this is enabled, the MeasureSpec that is passed down to children should be marked as CYISceneNode::MeasureMode::MeasureMode::Unspecified . Once all children have been measured, the measured size of the associated node would be calculated based on the measured size of the children.

Another constraint that needs special handling is the 'fill parent' property of children. If a child has one of its size constraints set to 'fill parent', then that child will typically be measured 'last' and will get however much space remains after all other children have been measured.

Multiple utility functions are available to facilitate implementation of custom layouts.

#include <layout/YiLayout.h>

Inheritance diagram for CYILayout:

Public Types

enum  PositioningMode {
  PositioningMode::SetPositionDirectly,
  PositioningMode::DoNotSetPositionDirectly
}
 
typedef CYILayoutConfig::CubeOffset Padding
 

Public Member Functions

 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
 
virtual void ChildAdded (CYISceneNode *pChild)
 
virtual void ChildRemoved (CYISceneNode *pChild)
 
virtual void ChildVisibilityChanged (CYISceneNode *pChild)
 
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
 

Static Public Member Functions

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

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
}
 

Protected Member Functions

virtual void Configure ()
 
virtual void OnSceneViewAttached ()
 
virtual void OnMeasure (const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec)=0
 
virtual void OnApplyMeasurements ()=0
 
virtual void OnMeasurementsCalculated (const CYISceneNode::MeasureSpec &widthSpec, const CYISceneNode::MeasureSpec &heightSpec, const CYISceneNode::MeasureSpec &depthSpec)
 
virtual void OnMeasurementsApplied ()
 
virtual const CYIRuntimeTypeInfoGetLayoutConfigType () const
 
virtual std::unique_ptr< CYILayoutStateCreateLayoutStateInstance () const
 
virtual void ApplyPosition (CYISceneNode *pChild, const glm::vec3 &position)
 
virtual void ApplySize (CYISceneNode *pChild, const glm::vec3 &size)
 
void CreateLayoutObjectsFor (CYISceneNode *pNode) const
 
CYISceneNodeGetChild (size_t index) const
 
void ApplyMeasurementsToBackgroundChildren ()
 
const PaddingGetPaddingForChild (const CYISceneNode *pChild) const
 

Static Protected Member Functions

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)
 

Protected Attributes

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
 

Member Typedef Documentation

◆ Padding

Member Enumeration Documentation

◆ Dimensions

enum CYILayout::Dimensions
strongprotected

An enum used to specify which dimensions a function should be working on.

Enumerator
None 
AllButX 
AllButY 
AllButZ 
All 

◆ PositioningMode

Declares the possible positioning modes for a layout.

Enumerator
SetPositionDirectly 

The position should be set directly by calling CYISceneNode::SetPosition

DoNotSetPositionDirectly 

The position should not be set by calling CYISceneNode::SetPosition

Constructor & Destructor Documentation

◆ CYILayout()

CYILayout::CYILayout ( )

◆ ~CYILayout()

virtual CYILayout::~CYILayout ( )
virtual

Member Function Documentation

◆ ApplyMeasurements()

void CYILayout::ApplyMeasurements ( )

Applies the measured sizes of the associated node's children.

See also
CYISceneNode::ApplyMeasurements

◆ ApplyMeasurementsToBackgroundChildren()

void CYILayout::ApplyMeasurementsToBackgroundChildren ( )
protected

Applies the measurements for all of the background children of the node associated with this layout. Non-background children are ignored. This function ignores the configured layout padding.

This function can be used to simplify the implementation of the OnApplyMeasurements function on some layouts. On some layout implementations, it is more efficient to apply measurements to background children in the same 'pass', while other children have their measurements applied. For those cases, the use of this function is not recommended.

◆ ApplyPosition()

virtual void CYILayout::ApplyPosition ( CYISceneNode pChild,
const glm::vec3 &  position 
)
protectedvirtual

Applies the position position to the scene node pChild. This function, by default, simply calls CYISceneNode::SetPosition. It can be overridden in subclasses to support animating position changes for child scene nodes.

Reimplemented in CYIAnimatingLayout, and CYIAutoLayout.

◆ ApplySize()

virtual void CYILayout::ApplySize ( CYISceneNode pChild,
const glm::vec3 &  size 
)
protectedvirtual

Applies the size size to the scene node pChild. This function, by default, simply calls CYISceneNode::SetSize. It can be overridden in subclasses to support animating size changes for child scene nodes.

Reimplemented in CYIAnimatingLayout.

◆ AttachTo()

void CYILayout::AttachTo ( CYISceneView pView)

'Attaches' this layout to pView. Calling this function will save a reference to pView in this layout object and will create (if necessary) CYILayoutConfig and CYILayoutState objects in pView's children.

Note
If one of the children of pView already has an assigned CYILayoutConfig or CYILayoutState object, those objects will be left as is. However, if the assigned CYILayoutConfig object is of an unexpected type then that object will be deleted and recreated.
See also
CYILayout::Configure

◆ CalculateChildMeasureSpec()

static CYISceneNode::MeasureSpec CYILayout::CalculateChildMeasureSpec ( const CYISceneNode::MeasureSpec parentMeasureSpec,
float  padding,
const CYILayoutConfig::SizeConstraint childConstraint,
float  childScale 
)
staticprotected

Creates an adjusted measure specification for a single dimension, given an existing measure specification parentMeasureSpec, a padding value padding and a size constraint childConstraint.

◆ CalculateDimension()

static float CYILayout::CalculateDimension ( const CYISceneNode::MeasureSpec spec,
const CYILayoutConfig::SizeConstraint constraint,
float  currentValue 
)
static

Calculates a desired size (in a single dimension), given the measure specification spec, the constraint constraint and the current size currentValue.

◆ ChildAdded()

virtual void CYILayout::ChildAdded ( CYISceneNode pChild)
virtual

Called when a child (pChild) is added to the scene node associated with this layout instance.

Note
Subclasses that override this method must call the parent class' ChildAdded method.

Reimplemented in CYIAnimatingLayout, and CYIAutoLayout.

◆ ChildRemoved()

virtual void CYILayout::ChildRemoved ( CYISceneNode pChild)
virtual

Called when a child (pChild) is removed from the scene node associated with this layout instance.

Note
Subclasses that override this method must call the parent class' ChildRemoved method.

Reimplemented in CYIAnimatingLayout.

◆ ChildVisibilityChanged()

virtual void CYILayout::ChildVisibilityChanged ( CYISceneNode pChild)
virtual

Called when the local visibility of a child (pChild) has changed in the scene node associated with this layout instance.

Note
Subclasses that override this method must call the parent class' ChildVisibilityChanged method.

Reimplemented in CYIAnimatingLayout.

◆ Configure()

virtual void CYILayout::Configure ( )
protectedvirtual

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 in CYIGridLayout, CYILinearLayout, CYIAnimatingLayout, CYIAutoLinearLayout, CYIAutoLayout, CYIScalingLayout, CYIColumnLayout, CYIRowLayout, and CYIShaftLayout.

◆ ConfigureFromAttachedNode()

void CYILayout::ConfigureFromAttachedNode ( )

Configures this layout using the properties contained in the attached node. If this layout currently does not have an attached node, an error is logged.

Note
If the attached node has no properties, this function has no effect.
See also
IYIPropertiesSource::HasProperties()

◆ CreateLayoutObjectsFor()

void CYILayout::CreateLayoutObjectsFor ( CYISceneNode pNode) const
protected

Creates instances of subclasses of CYILayoutConfig and CYILayoutState and assigns them to pNode (if necessary).

◆ CreateLayoutStateInstance()

virtual std::unique_ptr<CYILayoutState> CYILayout::CreateLayoutStateInstance ( ) const
protectedvirtual

Creates a 'blank' layout state object.

Note
Subclasses should override this method if they require per-node state. Remember to base the new class on the parent class's CYILayoutState class.
May return null if the layout implementation (and all of its parents) does not make use of per-node layout state objects.

◆ DetachFromNode()

void CYILayout::DetachFromNode ( )

'Detaches' this layout from its associated scene node. This involves deleting layout config and layout state objects from the associated scene node's children, and clearing the associated scene node in this layout object.

◆ GetAdjustedMeasuredSize()

glm::vec3 CYILayout::GetAdjustedMeasuredSize ( const CYISceneNode pChild)
inlinestaticprotected

Calculates the actual measured size of pChild in its parent space. This is simply the result of the multiplication of the child's measured size and scale.

◆ GetAdjustedPosition()

static glm::vec3 CYILayout::GetAdjustedPosition ( const glm::vec3 &  desiredTopLeftPosition,
const CYISceneNode pChild 
)
staticprotected

Calculates the position that, when assigned to child pChild, results in the top-left-front of the child to be at position desiredTopLeftPosition.

◆ GetAssociatedSceneNode()

CYISceneNode * CYILayout::GetAssociatedSceneNode ( ) const
inline

Returns the scene node associated with this layout. May be nullptr if this layout currently does not have an associated scene node.

◆ GetChild()

CYISceneNode* CYILayout::GetChild ( size_t  index) const
protected

Fetches and returns the child of the associated scene node at index index. If this layout is configured to use the reverse children order, this function will instead return the item at index (m_pNode->GetChildCount() - index - 1).

◆ GetDefaultSize()

static glm::vec3 CYILayout::GetDefaultSize ( const CYISceneNode pNode,
const CYISceneNode::MeasureSpec widthSpec,
const CYISceneNode::MeasureSpec heightSpec,
const CYISceneNode::MeasureSpec depthSpec 
)
static

Calculates and returns the default size of scene node pNode, given a set of measure specifications. The default size of a node is used when the node does not make any 'intelligent' decisions about what its size should be, and instead relies on its constraints and the provided measure specifications only.

◆ GetGravity()

const glm::vec3& CYILayout::GetGravity ( ) const

◆ GetLayoutConfigType()

virtual const CYIRuntimeTypeInfo& CYILayout::GetLayoutConfigType ( ) const
protectedvirtual

Returns the type of layout config objects used by this layout.

Note
Subclasses should override this method if the laid-out objects can have custom configuration values. Remember to base the new class on the parent class's CYILayoutConfig class.

Reimplemented in CYIGridLayout, and CYIAnimatingLayout.

◆ GetPadding()

const Padding& CYILayout::GetPadding ( ) const

◆ GetPaddingForChild()

const CYILayout::Padding & CYILayout::GetPaddingForChild ( const CYISceneNode pChild) const
inlineprotected

Fetches and returns the padding value to use for child pChild.

Some children ignore the padding value configured in their parent (for example background nodes). To make the code cleaner, this function can be used to fetch the 'proper' padding value to use for a given child.

◆ GetPositioningMode()

PositioningMode CYILayout::GetPositioningMode ( ) const

◆ GetTopLeftPositionWithGravity()

static glm::vec3 CYILayout::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 
)
staticprotected

Calculates the top-left-front position of a child within a container, given a layout gravity value layoutGravity and a child gravity value childGravity.

Padding can be specified for the container by using the padding parameter. Non-zero padding values will result in the containerTopLeft and containerSize values to be modified.

Margin can be specified for the child using the margin parameter, and will result in the child's childSize and position to be modified.

In order to support 'none' gravity values, the current child position currentChildPosition must be provided as well. To compute the 'effective' gravity value, the layoutGravity value is used and each component is replaced by the component from childGravity if that component is non-negative.

◆ GetUnadjustedPosition()

glm::vec3 CYILayout::GetUnadjustedPosition ( const glm::vec3 &  currentTopLeftPosition,
const CYISceneNode pChild 
)
inlinestaticprotected

Performs the opposite of the calculation performed in GetAdjustedPosition.

See also
GetAdjustedPosition

◆ IsLayoutable()

bool CYILayout::IsLayoutable ( const CYISceneNode pNode)
inlinestatic

Checks if scene node pNode can be laid out by the layout system.

◆ IsUsingReverseChildrenOrder()

bool CYILayout::IsUsingReverseChildrenOrder ( ) const

◆ Measure()

void CYILayout::Measure ( const CYISceneNode::MeasureSpec widthSpec,
const CYISceneNode::MeasureSpec heightSpec,
const CYISceneNode::MeasureSpec depthSpec 
)

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

See also
CYISceneNode::Measure

◆ MeasureBackgroundChildren()

static void CYILayout::MeasureBackgroundChildren ( CYISceneNode pNode,
const glm::vec3 &  size 
)
staticprotected

Measures children of the associated scene node that are marked as 'background' nodes in their layout configuration. Uses size size as measure bounds.

Note
This function should be called every time that Measure is called. However, implementations of Measure can omit calling this function if it determines that there are no nodes marked as 'background' nodes in the associated scene node.
Implementations of ApplyMeasurements must ensure that nodes marked as 'background' are laid-out without considering the parent container's padding.

◆ MeasureChildWithMargins() [1/2]

static void CYILayout::MeasureChildWithMargins ( CYISceneNode pChild,
const CYISceneNode::MeasureSpec parentWidthSpec,
const CYISceneNode::MeasureSpec parentHeightSpec,
const CYISceneNode::MeasureSpec parentDepthSpec,
const Padding padding 
)
staticprotected

Measures scene node pChild using the provided measure specifications, adjusted for the padding value padding (for example the specifications will be reduced, if possible, by the padding amount).

Note
This function uses the scale of pChild as child scale.

◆ MeasureChildWithMargins() [2/2]

static void CYILayout::MeasureChildWithMargins ( CYISceneNode pChild,
const CYISceneNode::MeasureSpec parentWidthSpec,
const CYISceneNode::MeasureSpec parentHeightSpec,
const CYISceneNode::MeasureSpec parentDepthSpec,
const Padding padding,
const glm::vec3 &  childScale 
)
staticprotected

Measures scene node pChild using the provided measure specifications, adjusted for the padding value padding (for example the specifications will be reduced, if possible, by the padding amount).

◆ OnApplyMeasurements()

virtual void CYILayout::OnApplyMeasurements ( )
protectedpure virtual

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

Implemented in CYIGridLayout, CYILinearLayout, CYIScalingLayout, and CYIStackLayout.

◆ OnMeasure()

virtual void CYILayout::OnMeasure ( const CYISceneNode::MeasureSpec widthSpec,
const CYISceneNode::MeasureSpec heightSpec,
const CYISceneNode::MeasureSpec depthSpec 
)
protectedpure virtual

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

Implemented in CYIGridLayout, CYILinearLayout, CYIAutoLinearLayout, CYIScalingLayout, and CYIStackLayout.

◆ OnMeasurementsApplied()

virtual void CYILayout::OnMeasurementsApplied ( )
protectedvirtual

A function called after OnApplyMeasurements has been called. This can be used in abstract classes to do post-measurements-application handling.

Reimplemented in CYIAnimatingLayout.

◆ OnMeasurementsCalculated()

virtual void CYILayout::OnMeasurementsCalculated ( const CYISceneNode::MeasureSpec widthSpec,
const CYISceneNode::MeasureSpec heightSpec,
const CYISceneNode::MeasureSpec depthSpec 
)
protectedvirtual

A function called after OnMeasure has been called. This can be used in abstract classes to do post-measurement handling.

◆ OnSceneViewAttached()

virtual void CYILayout::OnSceneViewAttached ( )
protectedvirtual

A function called after a scene view has been attached to this layout.

Reimplemented in CYIAutoLinearLayout.

◆ RegisterAllLayouts()

static void CYILayout::RegisterAllLayouts ( )
static

Called once by the framework to register all Layout RTTI classes with the linker.

◆ RemeasureChildrenForFillParent()

static void CYILayout::RemeasureChildrenForFillParent ( const CYISceneNode pNode,
const glm::vec3 &  parentMeasuredSize,
const Padding padding,
Dimensions  dimensionsToRemeasure 
)
staticprotected

Remeasures the children of pNode in order to make them 'fill parent' in specified dimensions.

This function is used to remeasure children that have 'fill parent' size constraints. Normally, this is done within the main 'measure' phase of the layout. However, if a child is configured to 'fill parent' while the parent is configured to 'fit children', a second measurement pass is needed.

◆ SetGravity() [1/2]

void CYILayout::SetGravity ( const glm::vec3 &  layoutGravity)

Sets the gravity to gravity. Each component of the provided vector specifies a gravity value for the given dimension. A value of 0.0 means 'align to the start of the container', a value of 1.0 means 'align to the end of the container', and a value of 0.5 means 'center on the container'. The special value -1.0 means 'keep the existing position within the container'.

Note
Some layouts will ignore one or more of the gravity components specified in a scene node. For example, a horizontal layout would ignore the x component of the gravity vector, since that layout's job is to horizontally-align scene nodes. In that case, the role of horizontal gravity is fulfilled by the 'alignment' property.
Gravity values can be overridden in the child nodes' CYILayoutConfig object.
Warning
Component values other than 0.0, 0.5, 1.0 and -1.0 are not supported.
See also
CYILayoutConfig::SetItemGravity(const glm::vec3 &itemGravity)

◆ SetGravity() [2/2]

void CYILayout::SetGravity ( CYILayoutConfig::Gravity  gravity)

Sets the gravity to one of the pre-defined gravity values.

See also
SetGravity(const glm::vec3 &gravity)
CYILayoutConfig::Gravity

◆ SetPadding()

void CYILayout::SetPadding ( const Padding padding)

Sets the padding to padding. The padding of a layout is a blank area left around the content. The padding effectively reduces the 'available' area in a container that can be filled with children.

◆ SetPositioningMode()

void CYILayout::SetPositioningMode ( PositioningMode  positioningMode)

Sets the positioning mode for this layout to positioningMode. The positioning mode is used to determine how the position of a laid-out child should be set. By default, the layout will call CYISceneNode::SetPosition on laid-out children. If this function is called with PositioningMode::DoNotSetPositionDirectly, the position of laid-out children will not be set by this layout.

Note
Some sub-classes may have ways of indirectly setting the position of a laid-out child. For example, a sub-class may be setting a position in a timeline instead. In that case, the PositioningMode::DoNotSetPositionDirectly mode would not affect the sub-class' ability to set a position in a timeline. Some sub-classes may also ignore the positioning mode (for instance if the associated scene node has no in/out animation).

◆ SetUseReverseChildrenOrder()

void CYILayout::SetUseReverseChildrenOrder ( bool  useReverseChildrenOrder)

Sets the order in which children are laid out. When useReverseChildrenOrder is true, children will be laid out in the reverse of their natural order in the scene node. For example, the child at index 0 in the scene node will be laid out last, the child at index 1 will be laid out second-to-last, and so on. The reverse order is used by default so that the order of layers in After Effects is the order in which children will be laid out.

◆ UnscaleMeasureSpecs()

static void CYILayout::UnscaleMeasureSpecs ( const glm::vec3 &  scale,
CYISceneNode::MeasureSpec pWidthSpec,
CYISceneNode::MeasureSpec pHeightSpec,
CYISceneNode::MeasureSpec pDepthSpec 
)
static

Unscales the measure specs pWidthSpec, pHeightSpec and pDepthSpec by scale. If one of the provided measure specs is nullptr, it will be ignored. If one of the components of scale is zero, the associated measure spec size will be set to 0. This function is used to transform a set of measure specs into a child's coordinates space.

◆ UpdateMeasuredSizeForFitContent()

static void CYILayout::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

Updates the measured size pMeasuredSize, taking into consideration the constraints of pNode, the padding padding and the content size contentSize.

Note
If pNode doesn't have any size constraints configured as 'fit content', the value of pMeasuredSize will not be modified.
Modified measured sizes will still take the configured minimum/maximum width/height/depth values into consideration.

◆ UpdateMeasureSpecsForFitContent()

static bool CYILayout::UpdateMeasureSpecsForFitContent ( const CYISceneNode pNode,
CYISceneNode::MeasureSpec widthSpec,
CYISceneNode::MeasureSpec heightSpec,
CYISceneNode::MeasureSpec depthSpec 
)
staticprotected

Updates the measure specs widthSpec, heightSpec and depthSpec, considering the 'fit content' constraints of pNode.

If one or more of the components in the size constraints of pNode is set to true, the associated measure spec is set to 'undefined'.

Implementations of CYILayout that make use of 'fit content' should use this function to update their measure specs prior to using them to measure their children.

Note
If one of the provided measure specs is null, it will be ignored.
Calls to this function have no effect if all of the provided measure specs are null, or if pNode has no 'fit content' size constraints.

Member Data Documentation

◆ m_gravity

glm::vec3 CYILayout::m_gravity
protected

◆ m_padding

Padding CYILayout::m_padding
protected

◆ m_pNode

CYISceneView* CYILayout::m_pNode
protected

In most cases, this variable is used as a node (thus the name m_pNode )

◆ m_positioningMode

PositioningMode CYILayout::m_positioningMode
protected

◆ m_reverseChildrenOrder

bool CYILayout::m_reverseChildrenOrder
protected

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