Controls

Each control is an element in a view file, placed inside a layout. This page lists the controls and their main attributes. Attributes that take a colour accept any of the colour formats in Styles and themes, and {Resource id}.

Attributes every control has

Attribute	What it does
`Id`	A name for the control, for code that finds it by name.
`HoverKey`	A name for what the pointer rests on when it is over this control, which the game reads to show a tooltip. See Toasts and tooltips.
`Visible`	`true` or `false`, or `{Binding Name}` for a bool property. Default `true`.
`Disabled`	`true` or `false`, or `{Binding Name}`. A disabled control does not respond. Default `false`.
`Margin`	The space its parent reserves around it. See Layout.
`Dock`	Its edge in a dock layout. See Layout.
`Style`	The name of a `Style` resource to take its states and text settings from. See Styles and themes.
`IsInitialFocus`	`true` marks the control that gets focus when the view opens. See Navigation and panels.
`PanelTitle`	`true` marks a panel's drag handle. See Navigation and panels.

In C# the same attributes are set with WithId, WithPosition, WithVisibility or BindVisibility, WithEnabledState or BindDisabled, WithHoverKey or BindHoverKey, WithStyle, WithMargin, WithIsInitialFocus and WithPanelTitle. Every control and layout builder has them. See Views and view-models.

Text on a control can be a literal, or {Localize key}, which shows that key's text in the current language. The key is looked up when the view is built. See Localization.

Label

A Label shows text. It does not respond to input.

Attribute	Default	What it does
`Text`		The text. Also accepts `{Binding}` and `{Localize}`.
`Size`		The size.
`Font`	Built-in Boogaloo	A font path, or the name of a built-in font. See Styles and themes.
`FontSize`	`18`	The point size.
`LetterSpacing`	`0`	Extra space between glyphs, in pixels.
`Color`		The text colour.
`Alignment`	`Left`	`Left`, `Center` or `Right`.
`WrapText`	`false`	Wraps the text to the width of `Size`.
`FillColor`, `FillGradient`		A background.
`BorderColor`, `BorderThickness`		A border. The thickness defaults to 1.

Button

A Button runs a command when it is pressed. It has four states, described in Styles and themes: NormalState, HoverState, ClickedState and FocusedState.

Attribute	Default	What it does
`Text`		The text. Also accepts `{Binding}` and `{Localize}`.
`Size`		Required.
`Command`		The name of an `ICommand` property on the view-model, without braces. See Bindings and commands.
`IsDefault`	`false`	`true` makes this the view's default button. Enter presses it, unless the focused control needs Enter for itself.
`Font`, `FontSize`, `LetterSpacing`		As for `Label`.

<Button Id="play" Text="Play" Size="{240,40}" Command="PlayCommand" IsDefault="true">
  <NormalState FillColor="#2f6fbf" FontColor="#ffffff" />
  <HoverState FillColor="#4a8ad8" FontColor="#ffffff" />
</Button>

TextBox and PasswordBox

A TextBox takes typed text. Its Text is two-way: what the player types is written back to the view-model property it is bound to.

Attribute	Default	What it does
`Text`		The starting text. Also accepts `{Binding}`.
`Size`		Required.
`Label`		Text shown beside the box.
`Font`, `FontSize`		As for `Label`.
`RestrictToNumbers`	`false`	Allows only numeric characters.

A PasswordBox is a text box that shows each character as a mask:

Attribute	Default	What it does
`PasswordCharacter`	`9679` (●)	The character code shown for each typed character.

It takes the other text box attributes as well.

CheckBox and RadioButton

A CheckBox is ticked or unticked. Its Checked is two-way when it is bound.

Attribute	Default	What it does
`Checked`	`false`	`true` or `false`, or `{Binding Name}` for a bool property.
`Text`		The label beside the box. Also accepts `{Localize}`.
`BoxSize`	`0`	The side of the box, in pixels. Used when the states set a flat colour instead of a texture. `0` uses the font size.
`CheckMarkColor`		The colour of the tick.
`Font`, `FontSize`		As for `Label`.

Its Size is ignored: the box is sized from BoxSize and the text.

A RadioButton takes the same attributes. Clicking one ticks it and unticks the other radio buttons in the same layout. Its Checked and Text take a literal or a {Binding}, as a check box's do.

<CheckBox Id="remember" Text="Remember me" Checked="{Binding RememberMe}" />
<RadioButton Id="easy" Text="Easy" Checked="true" />
<RadioButton Id="hard" Text="Hard" />

ComboBox

A ComboBox picks one option from a list. Its options come from <Options> in the file, from a binding named by OptionsSource, or both: OptionsSource replaces <Options> when both are given. Either one must supply options.

Attribute	Default	What it does
`Size`		Required.
`SelectedKey`		The key of the selected option, as a literal or `{Binding Name}`. Two-way.
`OptionsSource`		`{Binding Name}` to a list of key and display-text pairs.
`Label`		Text shown beside the box.
`Font`		As for `Label`.
`MaxDropdownHeight`	`0`	The most the open list may grow, in pixels. `0` sizes it to the contents.

Each option is a ComboBoxOption:

Attribute	What it does
`Key`	The value written to `SelectedKey` when the option is chosen.
`DisplayValue`	The text shown. Also accepts `{Localize}`.
`SortIndex`	Required. The order of the options, lowest first.

<ComboBox Id="class" Size="{240,32}" SelectedKey="{Binding ClassKey}">
  <Options>
    <ComboBoxOption Key="warrior" DisplayValue="Warrior" SortIndex="0" />
    <ComboBoxOption Key="mage" DisplayValue="{Localize class.mage}" SortIndex="1" />
  </Options>
</ComboBox>

The view-model property for OptionsSource is an IEnumerable<KeyValuePair<string, string>>, so a Dictionary<string, string> works too.

Slider

A Slider picks a number between Minimum and Maximum. Its Value is two-way when it is bound.

Attribute	Default	What it does
`Value`	`0`	The value, as a number or `{Binding Name}`.
`Minimum`	`0`	The value at the left end.
`Maximum`	`1`	The value at the right end.
`Step`	`0`	The increment the value snaps to. `0` does not snap, and the arrow keys move a twentieth of the range.
`LiveUpdate`	`true`	Writes the value as the handle is dragged. `false` writes it only when the handle is let go. Arrow keys always write each step.
`Size`		The size of the whole slider.
`TrackHeight`, `ThumbWidth`	`6`, `10`	The height of the track and the width of the handle, in pixels.
`TrackColor`, `FillColor`, `FillGradient`, `ThumbColor`, `FocusColor`, `BorderColor`, `BorderThickness`		The parts' colours.

ProgressBar

A ProgressBar shows how far along something is. It only displays a value.

Attribute	Default	What it does
`Value`	`0`	A number between 0 and `Maximum`, or `{Binding Name}`.
`Maximum`	`100`	The value that fills the bar.
`Size`		The size of the whole bar, track included.
`TrackColor`, `FillColor`, `FillGradient`, `BorderColor`, `BorderThickness`		The parts' colours.

Image

An Image draws a picture. It takes the picture in one of two ways:

A texture file, given as a child element. Src is a path under the game's content root. The texture's Id names it for later use in the view.
A Source attribute, a name that the view's scope turns into a picture. A scope is set up in code with a ViewScope (see Views from data). When the scope gives no picture for the name, the image draws nothing.

Attribute	Default	What it does
`Size`		Required.
`Source`		A picture by name, or `{Binding Name}`.
`Color`		A tint for the picture.

<Image Id="logo" Size="{256,64}">
  <TextureFile Id="logoTexture" Src="ui/logo.png" />
</Image>

Textures declared in a template are referred to by a reference element instead. See Styles and themes.

Repeater

A Repeater draws one copy of its item template for each item in a collection. Each row's bindings read the item's own properties: Text="{Binding Name}" shows each item's Name.

Attribute	Default	What it does
`ItemsSource`		Required. `{Binding Name}` to an `IEnumerable` property.
`SelectedItem`		`{Binding Name}` to a property the selected item is written back to. Setting it makes rows selectable. Two-way.
`ActivateCommand`		The name of an `ICommand` property, run when a row is double-clicked.
`Size`		The size of the list. A height here caps how tall the list grows.
`Orientation`	`Vertical`	The direction the rows are laid out in.
`Stretch`	`false`	Takes the size the parent layout gives it, rather than its own.
`MaxExtent`	`0`	The most the list may grow along its orientation, in pixels.
`ItemSpacing`	`0`	The gap between rows.
`Padding`	`0`	The space inside the list, around the rows.
`SelectionColor`, `HoverColor`, `SelectionMarkerColor`, `FocusColor`, `ScrollIndicatorColor`		The list's colours.
`SelectionMarkerThickness`	`2`	The width of the marker on the selected row.
`FillColor`, `BorderColor`, `BorderThickness`		The list's background and border.

The <ItemTemplate> holds exactly one StackLayout, DockLayout or GridLayout:

<Repeater Id="items" Size="{300,240}" ItemsSource="{Binding Items}" SelectedItem="{Binding Selected}"
          ActivateCommand="UseItemCommand" ItemSpacing="4">
  <ItemTemplate>
    <StackLayout Orientation="Horizontal" HorizontalSpacing="8">
      <Label Size="{200,24}" Text="{Binding Name}" />
      <Label Size="{80,24}" Text="{Binding Count}" />
    </StackLayout>
  </ItemTemplate>
</Repeater>

The list is rebuilt when it is given a new collection. Changing the contents of the same collection does not rebuild it, so the view-model should set a new list when the items change. A row's own properties update on their own when the item raises PropertyChanged.

Layouts

StackLayout, DockLayout and GridLayout are described in Layout.

Table of Contents