CYILayout Class Reference

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 ()
CYISceneNode *	GetAssociatedSceneNode () 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 Padding &	GetPadding () 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 CYIRuntimeTypeInfo &	GetLayoutConfigType () const
virtual std::unique_ptr< CYILayoutState >	CreateLayoutStateInstance () const
virtual void	ApplyPosition (CYISceneNode *pChild, const glm::vec3 &position)
virtual void	ApplySize (CYISceneNode *pChild, const glm::vec3 &size)
void	CreateLayoutObjectsFor (CYISceneNode *pNode) const
CYISceneNode *	GetChild (size_t index) const
void	ApplyMeasurementsToBackgroundChildren ()
const Padding &	GetPaddingForChild (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
CYISceneView *	m_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

typedef CYILayoutConfig::CubeOffset CYILayout::Padding

Member Enumeration Documentation

Dimensions

enum CYILayout::Dimensions

strongprotected

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

Enumerator
None
X
Y
Z
AllButX
AllButY
AllButZ
All

PositioningMode

enum CYILayout::PositioningMode

strong

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:

• layout/YiLayout.h