# 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](https://docs.flatredball.com/gum/gum-tool/gum-elements/coloredrectangle) with `50` `Absolute` `Width`: ![Rectangle with an Absolute Width of 50](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-321788828e504b9b166fdeaca3f833569ee72d45%2F11_05%2035%2001.png?alt=media) ## 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](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-0de7bcb20fdac3eaf58d9cdc696e55127f2aecf0%2F11_05%2036%2016.png?alt=media) 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

{% hint style="info" %} 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](https://docs.flatredball.com/gum/gum-tool/gum-elements/parent#children-outside-of-parent-bounds) page. {% endhint %} ## 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](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-5455994698791d62caf362e604204fc855c9ffe1%2F02_10%2009%2001.png?alt=media) 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](https://docs.flatredball.com/gum/gum-tool/gum-elements/height-units#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](https://docs.flatredball.com/gum/gum-tool/gum-elements/container/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](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-53ea665582d00585bd8e90454a37fb28f5f05042%2F11_05%2046%2044.png?alt=media) `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.](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2F39G7spk4LEbU6wp4bc6c%2F16_08%2045%2050.gif?alt=media\&token=30672a55-4c7e-4d63-8cb1-9aaec668ffa5) ### 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](https://docs.flatredball.com/gum/gum-tool/gum-elements/general-properties/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](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-e22b8f5f931bad7880fc3538bc56a02ca45fb1af%2F11_05%2052%2048.png?alt=media) ## Relative to Max of Children or Parent `Relative to Max of Children or Parent` sizes an element to whichever is larger — its parent's width or the width needed to contain its children. The `Width` value acts as padding on the children side, the same as `Relative to Children`. A `Width` of `0` means the element is exactly the larger of its parent's width or its children's bounds. This unit is most useful when multiple siblings all use `Relative to Max of Children or Parent`. In this case, the sibling with the widest content drives the parent's width, which in turn sets the width of all narrower siblings. This creates a column of elements that always match each other's width regardless of their individual content.

The bottom blue rectangle's effective width is controlled by the wider of its parent (red rectangle) or child (white rectangle)

For example, consider a vertical menu where each menu item contains a Text instance. Each menu item uses `Relative to Max of Children or Parent` for its `Width Units`. When one menu item has longer text, that item grows to fit its content. Because the wider item pushes the parent to grow, all other menu items also grow to match — keeping the menu uniform.

Changes to the white rectangle cause size changes in the blue and ultimately red rectangle, which affects the size of sibling blue rectangles

Without this unit, you would need to either set a fixed width on all menu items (which cannot adapt to content) or use `Relative to Children` on each item (which makes each item a different width based on its own text). ## 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](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-f19ed2a835e7fcff054b98f5b52168c689e73920%2F11_05%2055%2015.png?alt=media) ## Percentage of File Width [Sprites](https://docs.flatredball.com/gum/gum-tool/gum-elements/sprite) 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](https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-eef2826ad8c16ed10ac3790b0bf3220fb486fc4a%2F11_05%2058%2009.png?alt=media) 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](https://docs.flatredball.com/gum/gum-tool/gum-elements/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. {% hint style="info" %} Svgs also support using `Maintain File Aspect Ratio Width`. For more information on using Svgs see the [Skia Standard Elements](https://docs.flatredball.com/gum/gum-tool/gum-elements/skia-standard-elements) page. {% endhint %} 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 an object's `Width` value by the global Font Scale value. This can be used to create widths which are responsive to font scales for devices which may have variable text sizes. The Font Scale value can be adjusted in the Editor tab to preview different global Font Scale values. When a Gum project is loaded at runtime, the runtime may apply a `Font Scale` value such as using the **Text size** from Windows. The global Font Scale value is set to 4, so the rectangle in the following image is drawn at an effective width of 200 pixels.