> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ss14.art/llms.txt
> Use this file to discover all available pages before exploring further.
# User Interface
The information in this page is likely outdated and may no longer be relevant.
I can't be bothered to think of an elegant opening paragraph for this page. This is the UI tutorial.
Code completion can help a lot with finding what controls and attributes you can use
## The `Control`
The game's UI is made up of a ton of `Control`s. Each `Control` is one element of the UI system. Controls have various functions, some being obvious things like text labels and buttons, while others serve to lay stuff out automatically.
Here we have a basic UI in the game. As you can see, it is a window made up of multiple buttons. There is one more control at play here, however, and that is `BoxContainer` to automatically lay the buttons out on top of eachother.
The actual layout XAML code for this UI looks like this (at the time of writing). You don't have to understand exactly what's going on here yet, of course:
```xml theme={null}
```
The `DefaultWindow` contains a `BoxContainer` to automatically lay the `Button`s out vertically, and the `Button`s contain a `Label` to show the text (the `Label` is automatically created to make the code shorter). In this way, the UI controls effectively form a tree:
```mermaid theme={null}
flowchart TD
DefaultWindow --> BoxContainer
BoxContainer --> Button1[Button] --> Label1[Label]
BoxContainer --> Button2[Button] --> Label2[Label]
BoxContainer --> Button3[Button] --> Label3[Label]
BoxContainer --> Button4[Button] --> Label4[Label]
BoxContainer --> Button5[Button] --> Label5[Label]
```
### Core Layout
Laying your controls out properly is perhaps one of the most important parts of UI. Laying out controls manually (as in, specifying positions and sizes manually) is annoying, problematic for resizing, etc... As such, the UI system is designed so that you can easily compose layout based on helper controls, such as the aforementioned `BoxContainer`.
This section describes how layout works for a *single* control. Below sections will go into details for layout controls such as `BoxContainer`.
All controls are effectively laid out as a bunch of rectangles. They have a size and a position relative to their parent. In the next screenshot you can see the effective rectangle of one of these buttons:
(if you're wondering, this is with the `devwindow` UI viewer, type `devwindow` in the game console and go to the UI tab.)
And the parent `BoxContainer` which contains all the buttons:
To properly understand the layout system, there are a few concepts that need to be explained:
Every control has a `DesiredSize`. This is effectively the "minimum" space that a control wants to be able to lay itself out correctly without being cut off or such. Controls calculate this based on their contents, and these contents can of course include *other* controls, depending on which control we're talking about. Some examples:
* `Label` (a text label): the actual text size laid out.
* `TextureRect` (an image): assuming it can't shrink, the size of the image.
* `BoxContainer`: the combined size of its contents, laid out sequentially.
* `Button`: the size of its contents + some padding for the button's border.
* base `Control` itself: the maximum of the sizes of its children
As stated however, the `DesiredSize` is only the *minimum*. In practice controls often get much more space than they "need". Even in the escape menu there is tons of spare horizontal space inside the buttons, but the text itself doesn't take the full width. Conceptually, while the UI system is laying out controls, the parent control (such as `BoxContainer`) *arranges* or *gives* space to its child controls. The controls then choose how they should occupy this space themselves. In the case of the escape menu, `BoxContainer` gives the full width to the control. The default behavior of most controls is to *stretch* to fill that space. The result is that the button "stretches" to fit the full width of the menu.
This behavior is governed by `HorizontalAlignment` and `VerticalAlignment` on the control, which effectively says "what do we do if we have more space than we need". The default for both is `Stretch`, which is "take as much space as we can". You can also `Center` which centers the control while keeping it as small as possible. And there's also `Left`/`Top` and `Right`/`Bottom` to align the control to one side. Let's try messing around with the `HorizontalAlignment` on various things in the escape menu:
`HorizontalAlignment="Center"` on each of the buttons individually:
```xml theme={null}
```
`HorizontalAlignment="Left"` on each of the buttons individually:
```xml theme={null}
```
`HorizontalAlignment="Left"` only on the `BoxContainer` itself. This means we are changing the `BoxContainer` itself to shrink, so it takes the width of the largest button. All the other buttons still expand to fill the space of the `BoxContainer`, so they all have the same size, that of the largest button:
Note: to actually make this example work, we need to move the `MinSize` declaration onto a containing control. In the normal menu, the `BoxContainer`'s `MinWidth` is solely responsible for the width of the menu, so it itself has no extra space. Wrapping it in a parent control which has the `MinSize` fixes that.
```xml theme={null}
```
There are other useful layout properties you can use to influence layout of an individual control:
* `MinSize`/`MinWidth`/`MinHeight`: Allows you to set a custom minimum size for the control, which is used on top of the existing size calculated based on children.
* `MaxSize`/`MaxWidth`/`MaxHeight`: Allows you to limit the size of a control.
* `SetSize`/`SetWidth`/`SetHeight`: Allows you to set a specific size for a control.
* `Margin`: Allows you to set a margin of blank space around a control.
## Common Attributes
These attributes are present on most layout controls.
### Margin
Sets the margin of the control this attribute is put on.
Example:
```xml theme={null}
```
This example sets an even margin of 4. You also can define the sides separately:
* `Margin=""`
* `Margin=""`
* `Margin=""`
### Horizontal/VerticalExpand
Controls have two rather confusing properties. We already went over the `HorizontalAlignment` and `VerticalAlignment` above, but there's another similar-sounding property: `HorizontalExpand` and `VerticalExpand`. These properties are very weird. Truth be told, if the UI system was more well-developed, these wouldn't be here in the first place. **People often use them without understanding what they actually do, so read up, nerd.**
These two properties influence the layout of your control **only in a few specific containers**: `BoxContainer`, `SplitContainer`, and `GridContainer`. If your controls is not in one of these and you set `*Expand`, your code is automatically wrong.
So what does it do exactly? I'll use `BoxContainer` as an example. Suppose I edit the escape menu so that there's more space than the buttons need:
Oh look, the escape menu has grown since the last time I edited this guide!
```xml theme={null}
```
`BoxContainer` always gives its children as little space as necessary along its primary axis. This means that unused space is not filled! In the example above, we could make the window horizontally bigger, and the buttons would get wider. But giving the window vertically bigger just adds empty space.
This is where `VerticalExpand` comes in. If we give a control `VerticalExpand="True"`, watch what happens:
```xml theme={null}
```
Aha. Now we're making use of that space! The `BoxContainer` is actually giving the rest of the space to the rules button. This is what `Expand` does.
You can give multiple controls `Expand`, and then the expansion will be proportionate to their `SizeFlagsStretchRatio` property:
```xml theme={null}
```
To reiterate: `Horizontal/VerticalAlignment` and such changes the behavior of the control within its alloted space. `Horizontal/VerticalExpand` changes how the parent container decides how much space to give in the first place. Only select parent containers respect `Horizontal/VerticalExpand`.
## XAML UI
Complex UIs can involve quite a lot of controls. Previously, most UIs were made by manually constructing these deep control trees in C#. This sucked. Nowadays we have The Technology(tm) and thanks to XamlUI, things don't suck as much. Yay!
XAML allows you to specify control trees in, well, XML. To recap, if you somehow skipped the top half of this page, it looks something like this:
```xml theme={null}
```
### Syntax
At its core, XAML is just a fancy way to specify .NET objects in XML. Just most XAML frameworks (like ours) wrap it in a bunch of stuff to make it particularly suited for UI stuff. This makes it both relatively straightforward to map to anything, but also not exactly the concise or pleasing way to write UI code in more complex scenarios. Oh well.
#### XML Basics
You can skip this bit if you have the most basic understanding of what XML is. Since basically every programmer knows HTML nowadays and that's almost the same thing you probably already do. But anyways here goes:
Your XML document is made up of a bunch of **tags**. This is an example of a tag:
```xml theme={null}
```
Comments look like this:
```xml theme={null}
```
Note the funny angle brackets denotating the parts of the tag, and the funny slash at the end (we'll come back to this later).
XML tags can have **attributes**. These are additional properties that go onto the tags. Here's an example:
```xml theme={null}
```
XML tags can contain things (in our case: other tags). This brings us to the distinction between "open" and "closed" tags. Up until now I only showed closed tags (ending with a `/>`) which can contain no content. You can also make an open tag like so:
```xml theme={null}
```
If you are experienced with HTML, in XML any tag can be either open or closed. Also XML does not allow the various parser edge cases based on tag name (` `, `
`, ...), it's much more consistent.
The contents of the tag go between the two bits there. Contents can be other tags or simply plain text (but plain text currently is not used in our engine):
```xml theme={null}
```
#### Namespaces
Because XAML maps to actual .NET types (mostly), you need to actually import namespaces for it to resolve types. This is done by putting an `xmlns` attribute on the top tag in the document. `xmlns="..."` is the namespace used by default (e.g. `
Here we have a basic UI in the game. As you can see, it is a window made up of multiple buttons. There is one more control at play here, however, and that is `BoxContainer` to automatically lay the buttons out on top of eachother.
The actual layout XAML code for this UI looks like this (at the time of writing). You don't have to understand exactly what's going on here yet, of course:
```xml theme={null}
(if you're wondering, this is with the `devwindow` UI viewer, type `devwindow` in the game console and go to the UI tab.)
And the parent `BoxContainer` which contains all the buttons:
To properly understand the layout system, there are a few concepts that need to be explained:
Every control has a `DesiredSize`. This is effectively the "minimum" space that a control wants to be able to lay itself out correctly without being cut off or such. Controls calculate this based on their contents, and these contents can of course include *other* controls, depending on which control we're talking about. Some examples:
* `Label` (a text label): the actual text size laid out.
* `TextureRect` (an image): assuming it can't shrink, the size of the image.
* `BoxContainer`: the combined size of its contents, laid out sequentially.
* `Button`: the size of its contents + some padding for the button's border.
* base `Control` itself: the maximum of the sizes of its children
As stated however, the `DesiredSize` is only the *minimum*. In practice controls often get much more space than they "need". Even in the escape menu there is tons of spare horizontal space inside the buttons, but the text itself doesn't take the full width. Conceptually, while the UI system is laying out controls, the parent control (such as `BoxContainer`) *arranges* or *gives* space to its child controls. The controls then choose how they should occupy this space themselves. In the case of the escape menu, `BoxContainer` gives the full width to the control. The default behavior of most controls is to *stretch* to fill that space. The result is that the button "stretches" to fit the full width of the menu.
This behavior is governed by `HorizontalAlignment` and `VerticalAlignment` on the control, which effectively says "what do we do if we have more space than we need". The default for both is `Stretch`, which is "take as much space as we can". You can also `Center` which centers the control while keeping it as small as possible. And there's also `Left`/`Top` and `Right`/`Bottom` to align the control to one side. Let's try messing around with the `HorizontalAlignment` on various things in the escape menu:
`HorizontalAlignment="Center"` on each of the buttons individually:
