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:

Rectangle with an Absolute Width of 50

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.

Rectangle using a Relative to Parent Width value of -10

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

Rectangle using 0 Relative to Parent with no direct parent

All relationships between parent and children depend only on the direct parent or child. Grandchildren and grandparents are not considered when performing calculations. For more information, see the Parent page.

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:

Rectangle using 100% of its parent

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

Rectangle using 100% of the screen when it has no direct parent

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.

Blue rectangle using a ratio value of 2, next to siblings each using a ratio value of 1

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:

Rectangle with a width of 50 Relative to Children, but since it has no children it is 50 units wide

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:

Moving children can adjust the absolute width of the parent if the parent is using a Width Units of Relative to Children

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:

Width is relative to the right-most child when using 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:

Adding children expands the effective width of the parent if the children are positioned in a horizontal stack.

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.

Moving BlueRectangle changes the width of both its parent and also YellowRectangle

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.

Parent absolute width is 30 since the BlueRectangle explicitly has 20 of its width set outside of the parent's bounds

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.

RedRectangle not affecting the absolute width of its parent since it is placed outside of the parent's bounds

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.

Moving a child which uses Pixels from Right can make the parent grow to accommodate the child's 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).

X Units of Percentage of Parent Width result in the child ignored

Relative to Children and Auto Grid Horizontal

If a parent sets its Width Units to Relative to Children, then it resizes 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 width of the cell when the parent uses Relative to Children width

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.

Resizing or moving a child can result in all cells growing or shrinking

The width of a container is determined by the width of the largest cell multiplied by the number of columns. 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.

Auto Grid vertical with Width Units Relative To Children

If children are removed from the container, the container's width does not change - the Auto Grid Horizontal Cells value determines the number of columns when calculating width, whether the cells contain children or are empty.

Removed children do not shrink the container beyond its 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.

Container expanding as more children are added to the grid

Setting a grid's Width value to a non-zero value increases the width of the container on top of what is needed to contain its children. This additional width is distributed evenly to all cells, resulting in additional spacing between each child.

For example, the following 3x3 grid contains children with an absolute width of 50. The grid's Width Units is set to Relative To Children. Notice that as the grid's Width increases, it grows horizontally. This horizontal growth results in a larger cell size, so each child is spaced apart.

Increasing Width Relative to Children spreads the larger size across all cells

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.

Text with Relative to Children width results in the contents of the Text instance controlling its size

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:

Rectangle displaying a width 200% of its height

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:

Sprite using 200 Percentage of File width

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

Changing a Sprite's Texture Width adjusts its absolute height when using Percentage of File Width

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.

Svgs also support using Maintain File Aspect Ratio Width. For more information on using Svgs see the Skia Standard Elements page.

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

Changing the Height when using Maintain File Aspect Ratio Width also adjusts absolute width

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

Changing either Height or Texture Width affects the Sprite's effective width

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.

Width of 100 using Absolute Multiplied by Font Scale results in an absolute width of 100 in the Gum tool