Width Units

Introduction

The Width Units variable controls how a unit is horizontally sized, which may be relative to its parent. By default elements uses Absolute width, where each unit represents 1 pixel of width in absolute terms. When using Absolute, an object ignores its parents' effective width.

Absolute

The following shows a child ColoredRectangle with 50 Absolute Width:

Relative to Parent

The following image shows a child ColoredRectangle with -10 Relative to Parent Width, so it sizes itself 10 pixels less wide than its parent.

If an instance does not have a parent, then it uses the canvas size when using a Width Units of Relative to Parent.

Percentage of Parent

The following shows a child ColoredRectangle with 100 Percentage of Parent Width, which means it has 100% of the effective width of its parent. Note that 100 Percentage of Parent is the same as 0 Relative to Parent:

If an object does not have a parent, then the width of the canvas is used.

Ratio of Parent

Ratio of Parent can be used to fill available space or to share available space with other objects using a ratio. It behaves similar to a Height Units of Ratio of Parent, but operates horizontally rather than vertically.

Ratio of Parent is usually used with a parent that has its Children Layout set to Left to Right Stack or Top to Bottom Stack. For more information, see the Children Layout page.

Relative to Children

The following image shows a child ColoredRectangle with 50 Relative to Children Width, which means that it is sized 50 pixels wider than is necessary to contain its children. Since the rectangle has no children, this is the same as having 50 Absolute Width:

Relative to Children can be used to size an object based on the position and sizes of a parent's children. The following animation shows a container with 0 Relative to Children Width, which means that its effective width is set just large enough to contain its children. Notice that if the children are moved, the parent's effective width adjusts. Both children are considered so the container adjusts its width according to the right-most side of either child:

A non-zero Width when using Relative to Children can be used to add additional padding to a parent container. The following animation shows how changing the Width variable can adjust the absolute width relative to children:

Relative to Children results in effective width dynamically adjusting in response to changes on a container's children. The following animation shows a container with Children Layout of Left to Right Stack. Adding additional children expands the container automatically:

Ignored Width Values

A parent container can ignore its children when it determines its absolute width when using a Width Units of Relative to Children if any of the following are true:

1. The child's Ignored By Parent Size is true.

2. The child's width depends on its parent's width. This circular dependency is resolved by the parent ignoring this child.

3. The child is explicitly positioned outside of the parent's bounds

4. The child's X Units is Percentage of Parent Width

Child's Ignored By Parent Size is True (1)

If a child has its Ignored By Parent Size set to true, then the parent ignores this child when calculating its own size. For more information, see the Ignored By Parent Size page.

Child Width Depends on its Parent's Width (2)

If a child's width depends on the parent, then the child is ignored by the parent. Once the parent has determined its own width, then the child is sized according to the parent. This type of circular dependency is common when adding background visuals to a container.

For example consider a container with two children - BlueRectangle and YellowRectangle - with the following variables:

• BlueRectangle X = Pixels from Left

• BlueRectangle Width Units = Absolute

• YellowRectangle Width Units = Relative to Parent

Only YellowRectangle depends on its parent.

Since BlueRectangle's absolute width value does not depend on the parent, the parent can use BlueRectangle's absolute width when calculating its own absolute width. Since YellowRectangle depends on the parent, the parent ignores the YellowRectangle. Instead, YellowRectangle depends on the parent container's absolute width for calculating its own absolute width. This in effect creates a situation where BlueRectangle affects the width of both its parent and also its YellowRectangle sibling.

Child is Explicitly Positioned Outside of Parent's Bounds (3)

A parent does not consider a child if the child is explicitly positioned outside of the parent's bounds. This can happen if the child's X Units and X values result in the child being drawn outside of the parent's bounds

If a child has X Units of Pixels from Left and its X value pushes the child out of the left of the parent, then the portion that is outside of the left of the parent is ignored. The BlueRectangle in the following image has an absolute width of 50. Its X value is -20, so only 30 pixels are used to determine the parent's effective height.

Similarly, if a child uses an X Units of Pixels from Right then the parent does not consider the width of any portion which is outside of its bounds. The following animation shows RedRectangle placed outside of the right of the container's bounds with a X Units of Pixels from Right.

Notice that if RedRectangle is moved so that it is inside the bounds, it can affect the absolute width of the parent. As RedRectangle is moved into the bounds, the parent grows to accommodate the desired RedRectangle X value.

Child's X Units is Percentage of Parent Width (4)

A parent ignores its child if the child uses an X Units of Percentage of Parent Width because this also creates a circular dependency (parent width depends on child position, child position depends on parent width).

Relative to Children and Auto Grid Horizontal

If a parent sets its Width Units to Relative to Children, then it must resize itself to contain its children. Normally the width of the entire parent is determined by the child which needs the most space horizontally. If the parent uses an Auto Grid Horizontal layout, then the children control the size of the cells rather than the entire parent. Since all cells must be the same size, the child which needs the most amount of space horizontally determines the width of all cells.

For example, the following image shows a four by four grid, each containing one white rectangle. The first rectangle has an Absolute Width and Height of 100, so each cell is sized to be 100x100. Note that the other rectangles are 50x50.

The largest child determines the cell size for all other children. Therefore, if a child is moved or resized so it outgrows its cell, then the parent width adjusts in response.

The width of a container is determined by the width of the largest cell multiplied by the number of columns. If the parent contains enough columns to support all of its children, then the Auto Grid Horizontal Cells value is used to determine the number of columns displayed.

For example, the following container has 3 columns and 4 rows, resulting in 12 cells. The width of the grid is based on 3 columns multiplied by the width of the largest cell.

If children are removed from the container, the container's width does not change - Auto Grid Horizontal Cells acts as a minimum number of columns.

Since Auto Grid Horizontal Cells acts only as a minimum and not maximum, more children can be added and the container expands to support the newly-added children.

Relative to Children and Text

Setting a Text instance's Width Units to Relative to Children results in the Text object adjusting according to its text contents. In other words if a Text's Width Units is set to Relative To Children, then the words in the Text do not wrap.

For example, setting the Width Units to Relative to Children and setting the Width to 0 results in the Text object automatically adjusting its actual width according to the text it contains.

Percentage of Height

Percentage of Height adjusts the object's effective width so it remains proportional to the effective height value multiplied by the Width value (as a percentage). For example, if a Width value of 200 is entered, then the effective width is 200% (2x) of the height.

The following image shows a child ColoredRectangle with a Width of 200 Percentage of Height. In this image, the Height value is 50 units, so the effective width is 100 units:

Percentage of File Width

Sprites can select a Width Unit called Percentage of File Width, which sets the width of the Sprite according to the file that it is displaying. This is the default Width Unit for Sprites.

The following image shows a child Sprite with 200 Percentage of Source File Width, which means it draws two times as wide as its source image:

When using Percentage of Source File Width, the Sprite's absolute width depends on the Sprite's Texture Width property.

For more information, see the Sprite Texture Address page.

Maintain File Aspect Ratio Width

Sprites can select a Width Unit called Maintain File Aspect Ratio Width, which sets the effective width of the Sprite so that its aspect ratio matches its source file multiplied by the Width value. Usually Maintain File Aspect Ratio Width is used with a Width value of 100 so that the Sprite shows is source file at the correct aspect ratio.

When this value is used, a Sprite's Height can be changed resulting in its absolute width also changing.

When using Maintain File Aspect Ratio Width, the Sprite's effective width depends on the Sprite's Texture Width property.

Absolute Multiplied by Font Scale

Absolute Multiplied by Font Scale is a value which multiplies the Font Scale property at runtime with the Width value. This can be used to create widths which are responsive to font scales for devices which may have variable text sizes.

At the time of this writing, the Gum tool always uses a Font Scale of 1, so this cannot be previewed in the tool. However, when a Gum project is loaded at runtime, the runtime may apply a Font Scale value such as using the Text size from Windows.