LogoLogo
  • Gum Tool
    • Introduction
    • Setup
      • Running from Source
    • Showcase
    • Tutorials and Examples
      • Intro Tutorials
        • 1 - The Basics
        • 2 - Variables Tab
        • 3 - Files
        • 4 - Components
        • 5 - Exposing Variables
        • 6 - Parent
        • 7 - States
        • 8 - State Categories
      • Animation Tutorials
        • 1 - Introduction to Animation
        • 2 - Creating an Animation
        • 3 - Playing Animations inside other Animations
        • 4 - Combining Multiple Categories
      • Examples
        • Bottom-Up Stack
        • Centering
        • Custom NineSlice
        • Health Bar
        • Padding
    • Gum Elements
      • General Properties
        • Alpha
        • Base Type (Inheritance)
        • Blend
        • Clips Children
        • Has Events
        • Height Units
        • Ignored By Parent Size
        • Locked
        • Max Height
        • Max Width
        • Min Height
        • Min Width
        • Order
        • Parent
        • Rotation
        • Visible
        • Variable References
        • Width Units
        • X
        • X Origin
        • X Units
        • Y
        • Y Origin
        • Y Units
      • Behaviors
        • Default Implementation
      • Circle
      • ColoredRectangle
      • Component
        • Default Child Container
      • Container
        • Children Layout
        • Contained Type
        • Is Render Target
        • Stack Spacing
        • Wraps Children
      • NineSlice
        • Blend
        • Custom Frame Texture Coordinate Width
        • Texture Address
        • Texture Left
        • Texture Top
      • Polygon
        • Points
      • Skia Standard Elements
        • General Properties
          • Has Dropshadow
          • Is Filled
          • Use Gradient
        • Arc
          • Start Angle
          • Sweep Angle
          • Thickness
        • Canvas
        • ColoredCircle
        • LottieAnimation
        • RoundedRectangle
          • Corner Radius
        • Svg
      • Sprite
        • Color
        • Source File
        • Texture Address
        • Wrap
      • States
        • Categories
      • Text
        • Blue
        • Color
        • Font
        • Font Scale
        • Font Size
        • Green
        • Is Bold
        • Is Italic
        • MaxLettersToShow
        • Outline Thickness
        • Red
        • Text
        • Text Overflow Horizontal Mode
        • Text Overflow Vertical Mode
        • Use Custom Font
        • Use Font Smoothing
    • Project Tab
    • Code Tab
      • Runtime Generation Details
      • Generation Scope
      • Inheritance Location
      • Is CodeGen Plugin Enabled
      • Show CodeGen Preview
    • Localization
    • Menu
      • Content
      • Project Properties
    • Plugins
      • AddAndRemoveVariablesForType
      • AddMenuItem
      • Export
      • Setting Up Post Build Events
    • Variables
      • Add Variable
    • Bitmap font generator (.fnt)
    • Upgrading
      • Migrating 2025 April 27 to Preview
      • Breaking Changes
        • Removal of Variable Spaces
  • Code
    • Gum Code Reference
      • AnimationRuntime
      • BitmapCharacterInfo
      • BitmapFont
      • Camera
      • CircleRuntime
      • ColoredRectangleRuntime
      • Component Runtimes
      • ContainerRuntime
      • Cursor
      • Gum Class Overview
      • DataUiGrid
        • Reflection
        • Categories
      • ElementSave
        • ToGraphicalUiElement
      • GraphicalUiElement
        • Absolute Values
        • AddToManagers
        • AnimateSelf
        • ApplyState
        • BlendState
        • CanvasHeight
        • CanvasWidth
        • Children
        • ContainedElements
        • Font Values
        • GetAbsoluteHeight
        • GetAbsoluteWidth
        • GetChildByNameRecursively
        • GetFrameworkElementByName
        • IsAllLayoutSuspended
        • Parent
        • RemoveFromManagers
        • UpdateLayout
      • GumProjectSave
      • IDataUi
      • InstanceMember
      • InstanceSave
      • InteractiveGue
        • CurrentInputReceiver
        • RaiseChildrenEventsOutsideOfBounds
        • RollOverBubbling
      • IPositionedSizedObject
      • Layer
      • NineSliceRuntime
      • RectangleRuntime
      • Renderer
        • SinglePixelTexture
      • SelectedState
      • SpriteRenderer
        • LastFrameDrawStates
      • SpriteRuntime
        • TextureAddress
        • TextureHeight
        • TextureLeft
        • TextureTop
        • TextureWidth
      • TextRuntime
        • Color
        • FontScale
        • FontSize
        • HorizontalAlignment
        • Text Wrapping
        • VerticalAlignment
      • VariableSave
    • FNA
    • Kni
    • Meadow
    • MonoGame
      • Setup
        • Linking Game Project to Source (Optional)
      • Tutorials
        • Gum Project Forms Tutorial
          • Setup
          • Gum Screens
          • Common Component Types
          • Styling
          • Multiple Screens
        • Code-Only Gum Forms Tutorial
          • Setup
          • Forms Controls
          • ListBox Items
          • Input in Forms
        • [Deprecated] Gum Project (.gumx) Tutorial
          • Setup
          • Gum Screens
          • Gum Forms
          • Customizing Forms
          • Strongly Typed Components Using Code Generation
          • Multiple Screens
      • Setup for GumBatch (Optional)
      • Loading a Gum Project (Optional)
      • async Programming
      • Custom Runtimes
      • GumBatch
      • Gum Forms
        • Binding (ViewModels)
        • Controls
          • Button
          • CheckBox
          • FrameworkElement
            • BindingContext
            • IsEnabled
            • IsFocused
            • ModalRoot and PopupRoot
            • SetBinding
          • ListBox
          • ListBoxItem
          • MenuItem
          • PasswordBox
          • RadioButton
          • ScrollViewer
            • VerticalScrollBarValue
          • StackPanel
          • Slider
          • TextBox
        • Control Customization In Code
          • MenuItem
        • Control Customization in Gum Tool
        • Gamepad Support
        • Keyboard Support
        • Troubleshooting
      • File Loading
      • Resizing the Game Window
      • Known Issues
      • Samples
        • MonoGameGumFormsSample
    • Nez
    • Silk.NET
    • SkiaGum
      • Setup
        • WPF
    • .NET MAUI
      • Setup
Powered by GitBook
On this page
  • Introduction
  • Absolute
  • Relative to Parent
  • Percentage of Parent
  • Ratio of Parent
  • Relative to Children
  • Ignored Width Values
  • Relative to Children and Auto Grid Horizontal
  • Relative to Children and Text
  • Percentage of Height
  • Percentage of File Width
  • Maintain File Aspect Ratio Width
  • Absolute Multiplied by Font Scale

Was this helpful?

Edit on GitHub
Export as PDF
  1. Gum Tool
  2. Gum Elements
  3. General Properties

Width Units

PreviousVariable ReferencesNextX

Last updated 2 months ago

Was this helpful?

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 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

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)

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

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.

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.

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 page.

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 , 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 page.

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 page.

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.

For more information, see the Sprite page.

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

Children Layout
Ignored By Parent Size
Sprites
Texture Address
Skia Standard Elements
ColoredRectangle
Parent
Ratio of Parent
Rectangle with an Absolute Width of 50
Rectangle using a Relative to Parent Width value of -10
Rectangle using 0 Relative to Parent with no direct parent
Rectangle using 100% of its parent
Rectangle using 100% of the screen when it has no direct parent
Blue rectangle using a ratio value of 2, next to siblings each using a ratio value of 1
Rectangle with a width of 50 Relative to Children, but since it has no children it is 50 units wide
Moving children can adjust the absolute width of the parent if the parent is using a Width Units of Relative to Children
Width is relative to the right-most child when using Relative to Children
Adding children expands the effective width of the parent if the children are positioned in a horizontal stack.
Moving BlueRectangle changes the width of both its parent and also YellowRectangle
Parent absolute width is 30 since the BlueRectangle explicitly has 20 of its width set outside of the parent's bounds
RedRectangle not affecting the absolute width of its parent since it is placed outside of the parent's bounds
Moving a child which uses Pixels from Right can make the parent grow to accommodate the child's X value
X Units of Percentage of Parent Width result in the child ignored
The largest child determines the width of the cell when the parent uses Relative to Children width
Resizing or moving a child can result in all cells growing or shrinking
Auto Grid vertical with Width Units Relative To Children
Removed children do not shrink the container beyond its minimum number of columns
Container expanding as more children are added to the grid
Text with Relative to Children width results in the contents of the Text instance controlling its size
Rectangle displaying a width 200% of its height
Sprite using 200 Percentage of File width
Changing a Sprite's Texture Width adjusts its absolute height when using Percentage of File Width
Changing the Height when using Maintain File Aspect Ratio Width also adjusts absolute width
Changing either Height or Texture Width affects the Sprite's effective width
Width of 100 using Absolute Multiplied by Font Scale results in an absolute width of 100 in the Gum tool