Widgets
Screen elements, main building blocks of Prefabs
Links
Common Predefined Widgets
- ButtonWidget
- ImageWidget
- ListPanel
- RichTextWidget
- ScrollablePanel
- ScrollBarWidget
- TextWidget
- TooltipWidget
- Widget
Common Predefined Attributes for Widgets
- WidthSizePolicy / HeightSizePolicy
- HorizontalAlignment / VerticalAlignment
- MarginLeft / MarginRight / MarginTop / MarginBottom
- PositionXOffset / PositionYOffset
- ScaledPositionXOffset / ScaledPositionYOffset
- Brush
- IsVisible / IsHidden
- AlphaFactor
- Command.Click (Command.YourKeyHere)
- DataSource (Properties with DataSourceProperty Attribute in C#)
- DoNotAcceptEvents
- Id
- Sprite
- Text (Text Widgets only)
WidthSizePolicy / HeightSizePolicy
Examples
- Fixed - fixed size (width/height)
- SuggestedWidth - sets the width in pixels
- SuggestedHeight - sets the height in pixels
- StretchToParent - the size (width/height) of the widget will be adjusted to match the size of its parent container. It means the widget will stretch horizontally or vertically to fill the available space provided by the parent. This option is useful when you want a widget to occupy the entire width of its parent container.
- CoverChildren - the size (width/height) of the widget will be determined by the size of its children. In this case, the widget will adjust its width to cover the entire area occupied by its children elements. This option is useful when you want a widget to automatically adjust its width based on the size and position of its children elements.
HorizontalAlignment / VerticalAlignment
Examples
These attributes allow to specify how the UI element should be positioned horizontally and vertically within its parent container.
HorizontalAlignment: Specifies the horizontal alignment of the UI element within its parent container. It can have the following values:
- Center: The UI element is horizontally centered within its parent container.
- Left: The UI element is aligned to the left edge of its parent container.
- Right: The UI element is aligned to the right edge of its parent container.
VerticalAlignment: Specifies the vertical alignment of the UI element within its parent container. It can have the following values:
- Center: The UI element is vertically centered within its parent container.
- Top: The UI element is aligned to the top edge of its parent container.
- Bottom: The UI element is aligned to the bottom edge of its parent container.
<Widget HorizontalAlignment="Center" VerticalAlignment="Top">
<!-- Child elements or content here -->
</Widget>
In this example, the Widget element will be horizontally centered within its parent container and aligned to the top edge of the container.
MarginLeft / MarginRight / MarginTop / MarginBottom
Examples
These attributes are used to define the margins or spacing around a UI element within its parent container. These attributes allow you to control the placement and positioning of the UI element within its layout.
- MarginLeft: Specifies the left margin or spacing of the UI element from its parent container's left edge.
- MarginRight: Specifies the right margin
- MarginTop: Specifies the top margin
- MarginBottom: Specifies the bottom margin
These attributes accept numeric values that represent the distance in pixels. You can set them to positive values to create space between the UI element and its parent container's edges, or set them to zero if you want the UI element to touch the edges. Negative values can also be used to create overlapping effects.
In this example, the Widget element will be positioned with a left margin of 10 pixels and a top margin of 20 pixels within its parent container. The MarginRight and MarginBottom attributes are not specified, so the widget will not have any spacing from the right and bottom edges of its parent.
PositionXOffset / PositionYOffset
The PositionXOffset and PositionYOffset attributes are used to adjust the position of a prefab element relative to its parent or reference point.
-
PositionXOffset: This attribute specifies the horizontal offset of the prefab element from its parent or reference point. A positive value moves the element to the right, while a negative value moves it to the left.
-
PositionYOffset: This attribute determines the vertical offset of the prefab element from its parent or reference point. A positive value moves the element downwards, while a negative value moves it upwards.
By adjusting these offsets, you can fine-tune the placement of elements within the user interface (UI). These attributes are particularly useful when you want to align or position elements precisely according to your design or gameplay requirements.
In this example, the button element will be shifted 10 units to the right and 5 units upwards from its parent or reference point.X and Y here are not measured in the screen pixels. This is something else. On my screen with resolution 3440x1440 X and Y for this measurement system is ~2200x1000. Use 'scaled' versions of the attributed to operate in real screen pixels.
ScaledPositionXOffset / ScaledPositionYOffset
Same as PositionXOffset / PositionYOffset but measured in real screen pixels. Can be used with MBWindowManager.WorldToScreen.
IsVisible / IsHidden
The attributes IsVisible and IsHidden are used to control the visibility of UI elements.
IsVisible: This attribute determines whether an element is visible on the screen. When set to true, the element will be displayed, and when set to false, the element will be hidden. It affects the visibility of the element itself as well as any child elements it may contain.
IsHidden: This attribute also controls the visibility of an element, similar to IsVisible. However, it is usually used in conjunction with conditions or triggers. The IsHidden attribute allows you to dynamically control the visibility of an element based on certain conditions or events. It can be bound to a script or other mechanisms to determine when the element should be hidden.
AlphaFactor
AlphaFactor="0.7"
This attribute is used to control the transparency or opacity of a UI element. The AlphaFactor specifies a value between 0 and 1, where 0 represents complete transparency (invisible) and 1 represents full opacity (completely visible).
When applied to a UI element, the AlphaFactor attribute determines the overall transparency level of that element and its children (if any). By adjusting the AlphaFactor value, you can make the UI element partially or completely transparent.
Note: For Brushes use Brush.GlobalAlphaFactor
Notes
Using the same Attribute twice in the same Widget will crash the game
Using wrong/non-existant Attribute will crash the game
It seems it's not allowed to use the same variable on the several attributes (in the same widget):
<Widget WidthSizePolicy="Fixed" HeightSizePolicy="Fixed" SuggestedWidth="@IconSize" SuggestedHeight="@IconSize" ...
Using the same variable in the separate widgets is ok.