UI¶

User interface, built from the game's own widgets so it looks like part of the game. A plugin creates footer buttons, panels above the footer, and windows. The handles it gets back stay valid for the plugin's whole life: when the game rebuilds its menus or loads a map, the host rebuilds the widgets behind them. Build the UI once in Main(); in Update() read what the player did and change what's shown. See Windows and widgets.

Functions¶

SetCursorVisible¶

void UI::SetCursorVisible(bool)

Asks for the mouse cursor to be shown (true) or releases that request (false). The cursor shows while any plugin asks for it.

Example

// A window you can click while it's open
window.visible = open;
UI::SetCursorVisible(open);

ScreenSize¶

bool UI::ScreenSize(float &out, float &out)

How big the game's screen is, in the units windows are placed in (Window.SetRect, Input::MousePosition). False before there is a screen. Requires host 0.14.0.

Example

float w, h;
if (UI::ScreenSize(w, h))
    panel.SetRect(16, 16, 440, h - 120);    // down the left, stopping above a bar at the bottom

FooterHeight¶

float UI::FooterHeight()

How tall the game's footer bar (the one plugin buttons sit in) is on screen, in the same units as UI::ScreenSize; 0 when there is no footer. For keeping a window at the bottom of the screen clear of it.

Example

float footerHeight = UI::FooterHeight();
dock.SetRect(0, screenH - footerHeight - 200, screenW, 200);

CursorShown¶

bool UI::CursorShown()

Whether the mouse cursor is on screen at all: because a plugin asked, or because the game shows it (pause menu, menus).

Example

// Only show the buttons when they can be clicked
pauseButton.visible = UI::CursorShown();

ResetPositions¶

void UI::ResetPositions(const string &in pluginId)

Puts every movable window of a plugin back where the plugin placed it, forgetting where the player dragged it.

Example

if (resetPositionButton.Clicked())
    UI::ResetPositions("grind-timer");

HasMovable¶

bool UI::HasMovable(const string &in pluginId)

Whether a plugin has any window the player can drag.

Example

resetPositionButton.visible = UI::HasMovable(Settings::Plugin(i));

AddFooterButton¶

FooterButton@ UI::AddFooterButton(const string &in)

Adds a button to the game's footer bar, the one at the bottom of the main menu, the in-race menus and the track editor. It stays there in every menu.

Example

UI::FooterButton@ button;

void Main()
{
    @button = UI::AddFooterButton("timer");
}

void Update(float dt)
{
    if (button.Clicked())
        panel.visible = !panel.visible;
}

AddMenuButton¶

FooterButton@ UI::AddMenuButton(const string &in)

Adds an entry to the main menu's own list (play, create, customize, ...), under "play", in the game's menu button. It is the same type as a footer button: read its clicks with Clicked(). Requires host 0.26.0.

Example

UI::FooterButton@ menuButton;

void Main()
{
    @menuButton = UI::AddMenuButton("my campaign");
}

void Update(float dt)
{
    if (menuButton.Clicked())
        page.visible = true;
}

MainMenuShown¶

bool UI::MainMenuShown()

True while the main menu's list (play, create, ...) is on screen. Requires host 0.26.0.

Example

page.visible = page.visible && UI::MainMenuShown();

CreatePanel¶

Panel@ UI::CreatePanel()

Creates a panel: a small box of lines and buttons that opens above the footer. It starts hidden.

Example

UI::Panel@ panel = UI::CreatePanel();
panel.title = "grind timer";
panel.AddLine("0:42:17 on this track");
UI::FooterButton@ resetButton = panel.AddButton("reset");

CreateWindow¶

Window@ UI::CreateWindow()

Creates a window: a box on screen that holds rows of widgets. It starts visible, centred at the bottom of the screen 40 pixels above the edge, with a black background at 65% opacity.

Example

UI::Window@ window = UI::CreateWindow();
window.SetAnchor(1, 0);        // top right of the screen
window.SetPivot(1, 0);         // ... by the window's own top right corner
window.SetOffset(-40, 40);     // 40 pixels in from the edges
window.AddText("hello", 24);

UI::FooterButton¶

A button in the footer bar (from UI::AddFooterButton), or in a panel (from Panel.AddButton).

Clicked¶

bool UI::FooterButton.Clicked()

True once per click. Reading it clears it, so check it in one place each frame.

Example

if (button.Clicked())
    panel.visible = !panel.visible;

hovered¶

bool hovered    // property of UI::FooterButton, read only

Read only. Whether the mouse is over the button.

Example

// Show a hint while hovering
hintText.visible = button.hovered;

label¶

string label    // property of UI::FooterButton, write only

Write only. The button's text.

Example

button.label = paused ? "start" : "pause";

UI::Panel¶

A box of lines and buttons above the footer (from UI::CreatePanel).

Clear¶

void UI::Panel.Clear()

Removes every line (buttons stay).

Example

// Rebuild the lines when something changes
panel.Clear();
for (uint i = 0; i < names.length(); i++)
    panel.AddLine(names[i]);

AddLine¶

void UI::Panel.AddLine(const string &in)

Adds a line of text under the ones already there.

Example

panel.AddLine("restarts: " + restarts);

title¶

string title    // property of UI::Panel, write only

Write only. The heading at the top of the panel.

Example

panel.title = "plugins";

visible¶

bool visible    // property of UI::Panel, read and write

Whether the panel is open.

Example

if (button.Clicked())
    panel.visible = !panel.visible;

AddButton¶

FooterButton@ UI::Panel.AddButton(const string &in)

Adds a button at the bottom of the panel. It's the same type as a footer button.

Example

UI::FooterButton@ openButton = panel.AddButton("open");
// later, in Update:
if (openButton.Clicked())
    window.visible = true;

UI::Window¶

A box on screen holding widgets in rows (from UI::CreateWindow). Widgets are added left to right; NewRow() starts the next row. A window can also have a header, cards, a sidebar and several views (one shown at a time), like the plugin manager's menu.

SetAnchor¶

void UI::Window.SetAnchor(float, float)

The point of the screen the window is placed from, as fractions: (0, 0) top left, (0.5, 0.5) centre, (1, 1) bottom right.

Example

window.SetAnchor(0.5, 0);      // top centre of the screen

SetPivot¶

void UI::Window.SetPivot(float, float)

The point of the window that sits on the anchor, as fractions of the window's size.

Example

// Centred horizontally at the top of the screen
window.SetAnchor(0.5, 0);
window.SetPivot(0.5, 0);

SetOffset¶

void UI::Window.SetOffset(float, float)

Moves the window from its anchor, in pixels.

Example

window.SetAnchor(0, 0);
window.SetOffset(40, 40);      // 40 pixels from the top left corner

SetBackground¶

void UI::Window.SetBackground(float, float, float, float)

The window's background colour, red, green, blue and opacity from 0 to 1. Opacity 0 removes the background.

Example

window.SetBackground(0, 0, 0, 0.35f);   // a light dark tint

SetCornerRadius¶

void UI::Window.SetCornerRadius(float)

Rounds the window's corners, radius in the units windows are placed in (0, the default, is square). Requires host 0.14.0.

Example

bar.SetCornerRadius(20);    // a pill

SetPadding¶

void UI::Window.SetPadding(float x, float y)

The space between the window's edges and its rows: x on the left and right, y at the top and bottom. Without it, a window has 12 x 8 (16 all round when it covers part of the screen with SetScreenSize); a negative value puts that back. Requires host 0.23.6.

Example

window.SetPadding(14, 8);

SetRowGap¶

void UI::Window.SetRowGap(float)

Pixels between one row and the next, and between rows inside a card. Without it, rows are 8 apart (4 inside a card); 0 stacks them with no space, for a compact readout, and a negative value puts the default back. The 8 between cards and the 12 under a header stay as they are. Requires host 0.23.6.

Example

window.SetRowGap(0);

SetFont¶

void UI::Window.SetFont(const string &in font, const string &in typeface = "")

The font for the window's texts, buttons and dropdowns: one of the game's fonts by asset path, and a typeface of it ("" for its default). A widget's own SetFont wins over it. "" goes back to the default font. A path that isn't a font of the game's is ignored, with one warning in the host log. The game's menu font is /Game/UI/Fonts/CocogoosePro.CocogoosePro, with the typefaces Regular and Semilight. Requires host 0.25.0.

Example

window.SetFont("/Game/UI/Fonts/CocogoosePro.CocogoosePro", "Regular");

visible¶

bool visible    // property of UI::Window, read and write

Whether the window is shown.

Example

// Only on a track
window.visible = Race::OnTrack();

AddText¶

Text@ UI::Window.AddText(const string &in, float size = 16)

Adds a text. size is the font height in pixels (16 if left out).

Example

UI::Text@ timeText = window.AddText("0:00:00", 56);
timeText.SetColor(0.24f, 1, 0.35f, 1);

AddTextAt¶

Text@ UI::Window.AddTextAt(const string &in, float size, float x, float y)

Adds a text at x, y from the window's top left (inside its padding) instead of in a row, on a layer over the rows. Move it with Text.SetPosition; moving it doesn't rebuild the window, so it can follow something every frame. Requires host 0.14.0.

Example

UI::Text@ label = window.AddTextAt("5s", 13, 200, 4);

AddRect¶

Rect@ UI::Window.AddRect(float x, float y, float width, float height)

Adds a filled rectangle at x, y, width by height, on the same layer as AddTextAt: for bars, markers and lines. Its colour, position and size change in place (Rect.SetColor, Rect.SetRect), without rebuilding the window. Requires host 0.14.0.

Example

UI::Rect@ playhead = window.AddRect(400, 0, 2, 300);
playhead.SetColor(1, 1, 1, 1);
// every frame:
playhead.SetRect(400 + time * pixelsPerSecond, 0, 2, 300);

AddButton¶

Button@ UI::Window.AddButton(const string &in)

Adds a button with a text label.

Example

UI::Button@ resetButton = window.AddButton("reset");

AddIconButton¶

Button@ UI::Window.AddIconButton(const string &in)

Adds a button that shows a drawn icon: "play", "pause", "down" or "up" (arrows, for showing and hiding more of a window). Change it with icon.

Example

UI::Button@ playButton = window.AddIconButton("pause");
// later: playButton.icon = paused ? "play" : "pause";

AddSlider¶

Slider@ UI::Window.AddSlider(float)

Adds a slider width pixels wide (0: the rest of the row, host 0.14.0). Its value runs from 0 to 1.

Example

UI::Slider@ slider = window.AddSlider(600);

AddDropdown¶

Dropdown@ UI::Window.AddDropdown(float)

Adds a dropdown width pixels wide. Add its choices with AddOption.

Example

UI::Dropdown@ speed = window.AddDropdown(90);
speed.AddOption("1x");
speed.AddOption("2x");
speed.selected = 0;

AddSpace¶

void UI::Window.AddSpace(float)

Adds empty space width pixels wide. 0 takes up all the leftover room in the row, pushing the widgets after it to the right edge.

Example

// Label on the left, button on the right
window.AddText("Show timer");
window.AddSpace(0);
window.AddButton("on");

NewRow¶

void UI::Window.NewRow()

Starts a new row: widgets added afterwards go underneath.

Example

window.AddText("0:42:17", 56);
window.NewRow();
window.AddText("restarts 36", 22);

StartSidebar¶

void UI::Window.StartSidebar(float width)

Widgets added after this stack in a column width pixels wide on the left of the window, until StartMain().

Example

window.StartSidebar(220);
UI::Button@ logNav = window.AddButton("console");
UI::Button@ pluginsNav = window.AddButton("plugins");
window.StartMain();

StartMain¶

void UI::Window.StartMain()

Ends the sidebar: widgets added after this go back into the rows on the right.

Example

window.StartSidebar(220);
window.AddButton("settings");
window.StartMain();
window.AddText("settings", 28);

SetScreenSize¶

void UI::Window.SetScreenSize(float width, float height)

Gives the window a fixed size as fractions of the screen. Without one, the window is as big as its contents.

Example

window.SetScreenSize(0.8f, 0.85f);   // most of the screen, for a menu

SetRect¶

void UI::Window.SetRect(float x, float y, float width, float height)

Places the window at x, y from the top left of the screen and gives it a fixed size, all in the units of SetOffset and Input::MousePosition. On a window already on screen it moves and resizes it in place, so it can follow the mouse every frame. Requires host 0.13.0.

Example

// a box from where the drag started to the mouse
float mx, my;
if (Input::MousePosition(mx, my))
    box.SetRect(startX, startY, mx - startX, my - startY);

StartView¶

int UI::Window.StartView()

Starts a new view and returns its number. Widgets added afterwards belong to it. Only one view shows at a time, chosen with ShowView.

Example

int logView = window.StartView();
window.AddTextArea(900, 600);
int settingsView = window.StartView();
window.AddText("settings");
window.ShowView(logView);

SetBlocksClicks¶

void UI::Window.SetBlocksClicks(bool)

With true, clicks on the window never reach the game underneath it.

Example

menu.SetBlocksClicks(true);    // a menu over the game

AddCheckBox¶

CheckBox@ UI::Window.AddCheckBox(const string &in label, float size = 16)

Adds a tick box with a label next to it. size is the label's font height (16 if left out).

Example

UI::CheckBox@ xAxis = window.AddCheckBox("X", 16);
xAxis.checked = true;

DockInEditorDetails¶

void UI::Window.DockInEditorDetails()

Makes the window a section of the track editor's details panel, under the game's transform and paint sections, shown while pieces are selected. Call it before adding widgets. SetAnchor, SetOffset and movable don't apply to a docked window.

Example

UI::Window@ section = UI::CreateWindow();
section.DockInEditorDetails();
section.SetBackground(0, 0, 0, 0);
section.AddText("rotated copy", 18);

DockInHub¶

void UI::Window.DockInHub()

Makes the window a row of the game's track hub, under the hub's header and its page row, shown with the hub. The hub's pages get shorter by the row's height, so the hub keeps its size. Call it before adding widgets. SetAnchor, SetOffset and movable don't apply to a docked window. Requires host 0.23.0.

Example

UI::Window@ row = UI::CreateWindow();
row.DockInHub();
UI::TextInput@ search = row.AddTextInput(0, "search maps", 17);

StartHeader¶

void UI::Window.StartHeader()

Widgets added after this go into rows above the views, shown whichever view is open, until the next StartView. Use it for tabs or a toolbar shared by every view.

Example

window.StartHeader();
window.AddText("plugins", 28);
UI::Button@ installedTab = window.AddButton("installed");
UI::Button@ browseTab = window.AddButton("browse");
int installedView = window.StartView();     // the header ends here

StartCard¶

void UI::Window.StartCard()

Rows added after this share one rounded box, a card, until EndCard(). NewRow() inside a card adds another row to the same card.

Example

// A card with a title row and a description row
window.StartCard();
window.AddImage(Plugins::Icon(i), 52, 52);
window.AddText(Plugins::Name(i), 21);
window.AddSpace(0);
UI::Button@ settingsButton = window.AddButton("settings");
window.NewRow();
window.AddText(Plugins::Description(i), 16);
window.EndCard();

EndCard¶

void UI::Window.EndCard()

Ends the card started by StartCard(). Widgets added afterwards go on a new row below it.

Example

window.StartCard();
window.AddText("Show timer", 19);
window.EndCard();
window.StartCard();                     // the next card
window.AddText("Time size", 19);
window.EndCard();

SetCardBackground¶

void UI::Window.SetCardBackground(float, float, float, float)

The colour of this window's cards, red, green, blue and opacity from 0 to 1.

Example

window.SetBackground(0.05f, 0.055f, 0.07f, 0.97f);
window.SetCardBackground(0.11f, 0.12f, 0.15f, 1);    // a little lighter than the window

zOrder¶

int zOrder    // property of UI::Window, read and write

Which windows are in front: higher is in front. Windows start at 100, the plugin manager's menu uses 500, and footer panels are at 1000.

Example

menu.zOrder = 500;    // above other plugins' windows

movable¶

bool movable    // property of UI::Window, read and write

With true, the player can drag the window whenever the cursor is on screen. Where they leave it is saved, and reset position in the settings puts it back. Set it after SetOffset: that's the position reset returns to.

Example

timerWindow.SetOffset(40, 40);
timerWindow.movable = true;

ShowView¶

void UI::Window.ShowView(int)

Shows one view (a number from StartView) and hides the others.

Example

if (logNav.Clicked())
    window.ShowView(logView);

ClearView¶

void UI::Window.ClearView(int)

Removes every widget in a view. Widgets added afterwards go into that view, so it can be rebuilt.

Example

// Rebuild the settings view when the list of settings changes
window.ClearView(settingsView);
for (uint i = 0; i < Settings::Count(); i++)
    AddSettingRow(i);

SetScrolling¶

void UI::Window.SetScrolling(int, bool)

Makes a view scroll (mouse wheel or its scroll bar) when its rows are taller than the window, such as a long list of cards. Not for a view with a text area of height 0 (that one fills the height instead).

Example

int list = window.StartView();
window.SetScrolling(list, true);

AddImage¶

Image@ UI::Window.AddImage(const string &in path, float width, float height)

Adds an image from a PNG file (full path), shown width by height pixels.

Example

window.AddImage(Plugins::Icon(i), 48, 48);

AddTextArea¶

TextArea@ UI::Window.AddTextArea(float width, float height, float size = 14)

Adds a scrolling text box width by height pixels. size is the font height (14 if left out). While it's scrolled to the end, it follows new text.

Example

UI::TextArea@ logArea = window.AddTextArea(900, 520, 14);
logArea.text = "first line\nsecond line";

AddTextInput¶

TextInput@ UI::Window.AddTextInput(float width, const string &in hint = "", float size = 18)

Adds a box the player can type in. width in pixels (0 fills the rest of the row), a grey hint shown while it's empty, and size for the font height.

Example

UI::TextInput@ command = window.AddTextInput(0, "type a command, Enter", 20);

UI::Text¶

A piece of text in a window (from Window.AddText).

SetFont¶

void UI::Text.SetFont(const string &in font, const string &in typeface = "")

Draws the text in one of the game's fonts, by its asset path, and optionally one of its typefaces ("" for the font's default); size and colour stay as they are. "" goes back to the window's font (Window.SetFont) or the default. A path that isn't a font of the game's is ignored, with one warning in the host log. The game's own menu font is /Game/UI/Fonts/CocogoosePro.CocogoosePro, with the typefaces Regular and Semilight. Requires host 0.23.6; the typeface needs 0.25.0.

Example

UI::Text@ label = window.AddText("TOTAL", 12);
label.SetFont("/Game/UI/Fonts/CocogoosePro.CocogoosePro");
label.SetFont("/Game/UI/Fonts/CocogoosePro.CocogoosePro", "Semilight");     // the lighter typeface

text¶

string text    // property of UI::Text, read and write

The text shown.

Example

timeText.text = FormatTime(seconds);

SetColor¶

void UI::Text.SetColor(float, float, float, float)

The text's colour, red, green, blue and opacity from 0 to 1.

Example

// Green while counting, dark green while paused
if (counting)
    timeText.SetColor(0.24f, 1, 0.35f, 1);
else
    timeText.SetColor(0.16f, 0.55f, 0.24f, 1);

SetPosition¶

void UI::Text.SetPosition(float, float)

Moves a text added with AddTextAt, in place. Requires host 0.14.0.

Example

label.SetPosition(x, 4);

visible¶

bool visible    // property of UI::Text, read and write

Whether the widget is shown. A hidden widget takes no space, so the rest of its row closes up (placed items, such as rectangles, are simply not drawn).

Example

// Buttons only while the cursor is on screen
pauseButton.visible = UI::CursorShown();
resetButton.visible = UI::CursorShown();

size¶

float size    // property of UI::Text, read and write

The font height in pixels.

Example

// From a setting
timeText.size = TimeSize;

SetWidth¶

void UI::Text.SetWidth(float)

Gives the text a fixed width, so texts in rows underneath one another line up as columns. 0 goes back to the text's own width.

Example

UI::Text@ label = window.AddText("Retries", 12);
label.SetWidth(110);

SetAlign¶

void UI::Text.SetAlign(int)

Where the text sits in its width (SetWidth): 0 left, 1 centre, 2 right.

Example

UI::Text@ value = window.AddText("0", 12);
value.SetWidth(70);
value.SetAlign(2);          // numbers line up on the right

SetFill¶

void UI::Text.SetFill(bool)

true makes the text take whatever width its row has left, so everything after it in the row is pushed to the row's right edge. Rows of a window are as wide as its widest row, so a label that fills lines every row's values up on the right. It does what AddSpace(0) after the text would, but goes with the text: a row whose widgets are all hidden closes up, which a space would keep open. With SetWidth as well, the width is the least it takes. Requires host 0.23.6.

Example

// TOTAL                1:42:17
// ATTEMPTS          318    +41
UI::Text@ label = window.AddText("ATTEMPTS", 12);
label.SetFill(true);
window.AddText("318", 15).SetGapBefore(18);
window.AddText("+41", 15).SetGapBefore(10);

SetGapBefore¶

void UI::Text.SetGapBefore(float)

Pixels between this widget and the one before it in its row (14 before a text, 8 before anything else); a negative value puts the default back. Has no effect on the first widget of a row. Requires host 0.23.6.

Example

UI::Text@ delta = window.AddText("+3", 15);
delta.SetGapBefore(10);

UI::Button¶

A clickable button in a window (from Window.AddButton or Window.AddIconButton).

SetTextColor¶

void UI::Button.SetTextColor(float, float, float, float)

The colour of the button's label, or of an icon button's icon: red, green, blue and opacity from 0 to 1 (white without it). Requires host 0.25.0.

Example

tab.SetTextColor(0.434f, 0.839f, 0, 1);     // the game's lime

SetCornerRadius¶

void UI::Button.SetCornerRadius(float)

Rounds the button's corners (text and icon buttons), radius in pixels; half its height makes a pill or, with SetSize square, a round button. Its background colour (SetBackground) fills the shape; hovered it's a little brighter and pressed a little darker. 0 (the default) keeps the plain button. Requires host 0.25.0.

Example

playButton.SetSize(40, 40);
playButton.SetCornerRadius(20);             // round

SetSize¶

void UI::Button.SetSize(float width, float height)

An icon button's size in pixels (the icon is scaled to its height). Text buttons are as large as their label. Requires host 0.25.0.

Example

UI::Button@ play = window.AddIconButton("play");
play.SetSize(40, 40);

SetFont¶

void UI::Button.SetFont(const string &in font, const string &in typeface = "")

The button's label in one of the game's fonts and a typeface of it, as Text.SetFont. Requires host 0.25.0.

Example

playAgain.SetFont("/Game/UI/Fonts/CocogoosePro.CocogoosePro", "Regular");

visible¶

bool visible    // property of UI::Button, read and write

Whether the widget is shown. A hidden widget takes no space, so the rest of its row closes up (placed items, such as rectangles, are simply not drawn).

Example

// Buttons only while the cursor is on screen
pauseButton.visible = UI::CursorShown();
resetButton.visible = UI::CursorShown();

Clicked¶

bool UI::Button.Clicked()

True once per click (a press that's released over the button). Reading it clears it.

Example

if (resetButton.Clicked())
{
    seconds = 0;
    Save();
}

hovered¶

bool hovered    // property of UI::Button, read only

Read only. Whether the mouse is over the button.

Example

tooltip.visible = sourceButton.hovered;

SetBackground¶

void UI::Button.SetBackground(float, float, float, float)

The button's colour, red, green, blue and opacity from 0 to 1.

Example

// Highlight the selected entry in a sidebar
nav.SetBackground(0.30f, 0.30f, 0.36f, 1);

label¶

string label    // property of UI::Button, write only

Write only. A text button's label.

Example

pauseButton.label = paused ? "start timer" : "pause timer";

icon¶

string icon    // property of UI::Button, write only

Write only. An icon button's icon: "play" or "pause".

Example

playButton.icon = paused ? "play" : "pause";

SetGapBefore¶

void UI::Button.SetGapBefore(float)

Pixels between this widget and the one before it in its row (14 before a text, 8 before anything else); a negative value puts the default back. Has no effect on the first widget of a row. Requires host 0.23.6.

Example

UI::Text@ delta = window.AddText("+3", 15);
delta.SetGapBefore(10);

UI::Dropdown¶

A dropdown in a window (from Window.AddDropdown).

SetStyle¶

void UI::Dropdown.SetStyle(float r, float g, float b, float a, float hoverR, float hoverG, float hoverB, float textR, float textG, float textB, float selectedR, float selectedG, float selectedB)

The dropdown's colours: its box and open list (r, g, b, a), a hovered or pressed option or box (hoverR, hoverG, hoverB), the text, and the selected option's text in the list. Colours are linear, 0 to 1. Requires host 0.25.0.

Example

speedBox.SetStyle(0, 0, 0, 0.85f,  0.15f, 0.15f, 0.15f,  1, 1, 1,  0.434f, 0.839f, 0);

hovered¶

bool hovered    // property of UI::Dropdown, read only

Read only. Whether the mouse is over the dropdown. Requires host 0.25.0.

Example

tooltip.visible = speedBox.hovered;

visible¶

bool visible    // property of UI::Dropdown, read and write

Whether the widget is shown. A hidden widget takes no space, so the rest of its row closes up (placed items, such as rectangles, are simply not drawn).

Example

// Buttons only while the cursor is on screen
pauseButton.visible = UI::CursorShown();
resetButton.visible = UI::CursorShown();

AddOption¶

void UI::Dropdown.AddOption(const string &in)

Adds a choice at the end of the list.

Example

array<string> speeds = {".5x", "1x", "2x"};
for (uint i = 0; i < speeds.length(); i++)
    speedBox.AddOption(speeds[i]);

ClearOptions¶

void UI::Dropdown.ClearOptions()

Removes every option, so the list can be filled again (nothing is selected until selected is set). Requires host 0.14.0.

Example

routeList.ClearOptions();
for (uint r = 0; r < routes.length(); r++)
    routeList.AddOption(routes[r]);

selected¶

int selected    // property of UI::Dropdown, read and write

The index of the chosen option. Setting it doesn't count as a change (Changed() stays false). An index outside the list is ignored.

Example

cameraBox.selected = Replay::CameraMode();

Changed¶

bool UI::Dropdown.Changed()

True once after the player picks an option. Reading it clears it.

Example

if (cameraBox.Changed())
    Replay::SetCameraMode(cameraBox.selected);

SetGapBefore¶

void UI::Dropdown.SetGapBefore(float)

Pixels between this widget and the one before it in its row (14 before a text, 8 before anything else); a negative value puts the default back. Has no effect on the first widget of a row. Requires host 0.23.6.

Example

UI::Text@ delta = window.AddText("+3", 15);
delta.SetGapBefore(10);

UI::Rect¶

SetRect¶

void UI::Rect.SetRect(float x, float y, float width, float height)

Moves and resizes a rectangle, in place. Requires host 0.14.0.

Example

progress.SetRect(left, top, width * fraction, 12);

SetColor¶

void UI::Rect.SetColor(float, float, float, float)

The rectangle's colour: red, green, blue and opacity, 0 to 1. Requires host 0.14.0.

Example

bar.SetColor(0.3f, 0.3f, 0.35f, 1);

visible¶

bool visible    // property of UI::Rect, read and write

Whether the widget is shown. A hidden widget takes no space, so the rest of its row closes up (placed items, such as rectangles, are simply not drawn).

Example

// Buttons only while the cursor is on screen
pauseButton.visible = UI::CursorShown();
resetButton.visible = UI::CursorShown();

UI::Slider¶

A slider in a window (from Window.AddSlider). Its value runs from 0 to 1.

visible¶

bool visible    // property of UI::Slider, read and write

Whether the widget is shown. A hidden widget takes no space, so the rest of its row closes up (placed items, such as rectangles, are simply not drawn).

Example

// Buttons only while the cursor is on screen
pauseButton.visible = UI::CursorShown();
resetButton.visible = UI::CursorShown();

value¶

float value    // property of UI::Slider, read and write

The slider's position from 0 to 1. Setting it while the player is dragging does nothing: their drag wins.

Example

// Follow playback unless the player is scrubbing
if (!slider.dragging)
    slider.value = float(Replay::Time() / Replay::Length());

dragging¶

bool dragging    // property of UI::Slider, read only

Read only. Whether the player is dragging the slider right now.

Example

if (slider.dragging)
    Replay::Seek(slider.value * Replay::Length());

SetGapBefore¶

void UI::Slider.SetGapBefore(float)

Pixels between this widget and the one before it in its row (14 before a text, 8 before anything else); a negative value puts the default back. Has no effect on the first widget of a row. Requires host 0.23.6.

Example

UI::Text@ delta = window.AddText("+3", 15);
delta.SetGapBefore(10);

UI::TextArea¶

A scrolling box of text (from Window.AddTextArea).

visible¶

bool visible    // property of UI::TextArea, read and write

Whether the widget is shown. A hidden widget takes no space, so the rest of its row closes up (placed items, such as rectangles, are simply not drawn).

Example

// Buttons only while the cursor is on screen
pauseButton.visible = UI::CursorShown();
resetButton.visible = UI::CursorShown();

text¶

string text    // property of UI::TextArea, read and write

All the text in the box. Use \n for new lines.

Example

logArea.text += Log::Line(i) + "\n";

SetGapBefore¶

void UI::TextArea.SetGapBefore(float)

Pixels between this widget and the one before it in its row (14 before a text, 8 before anything else); a negative value puts the default back. Has no effect on the first widget of a row. Requires host 0.23.6.

Example

UI::Text@ delta = window.AddText("+3", 15);
delta.SetGapBefore(10);

UI::TextInput¶

A box the player can type in (from Window.AddTextInput). While it has focus, the keys go to it: the game doesn't get them, and neither does Input::Pressed.

visible¶

bool visible    // property of UI::TextInput, read and write

Whether the widget is shown. A hidden widget takes no space, so the rest of its row closes up (placed items, such as rectangles, are simply not drawn).

Example

// Buttons only while the cursor is on screen
pauseButton.visible = UI::CursorShown();
resetButton.visible = UI::CursorShown();

Submitted¶

bool UI::TextInput.Submitted()

True once after the player presses Enter in the box, or after Submit(). Reading it clears it. The text is then in text.

Example

if (command.Submitted())
    Console::Run(command.text);

text¶

string text    // property of UI::TextInput, read only

Read only. The text as it was last submitted.

Example

if (nameInput.Submitted())
    Storage::Set("name", nameInput.text);

typed¶

string typed    // property of UI::TextInput, read only

Read only. What's in the box now, as it's typed (without waiting for Enter): for a search that filters as you type. Requires host 0.15.1.

Example

if (search.typed != shownSearch)
    Filter(search.typed);

focused¶

bool focused    // property of UI::TextInput, read only

Read only. Whether the box has keyboard focus (the player is typing in it).

Example

// Don't treat Space as "pause" while typing
if (!command.focused && Input::Pressed(Input::Space))
    TogglePause();

Focus¶

void UI::TextInput.Focus()

Puts the keyboard focus in the box, as if the player had clicked it.

Example

// Ready to type as soon as the console opens
if (consoleNav.Clicked())
{
    window.ShowView(consoleView);
    command.Focus();
}

Submit¶

void UI::TextInput.Submit()

Submits what's typed in the box, as if the player had pressed Enter.

Example

// A button next to the box does the same as Enter
if (goButton.Clicked())
    command.Submit();

value¶

string value    // property of UI::TextInput, write only

Write only. Replaces what's typed in the box.

Example

angleInput.value = "180";

clearOnSubmit¶

bool clearOnSubmit    // property of UI::TextInput, write only

Write only. Whether the box empties after a submit (the default) or keeps its text.

Example

// A number box that keeps showing its value
angleInput.clearOnSubmit = false;

clearButton¶

bool clearButton    // property of UI::TextInput, write only

Write only. Puts an x at the box's right end while it holds text; clicking it empties the box (Cleared() then says so). Set it straight after AddTextInput, before the window is shown. Requires host 0.23.0.

Example

@search = row.AddTextInput(0, "search maps");
search.clearButton = true;

Cleared¶

bool UI::TextInput.Cleared()

True once after the player emptied the box with its x (clearButton). Reading it clears it. Requires host 0.23.0.

Example

if (search.Cleared())
    ShowEverything();

readOnly¶

bool readOnly    // property of UI::TextInput, write only

Write only. Whether the player can change the text (the default) or only select and copy it. Requires host 0.12.0.

Example

// A code the player copies with ctrl+a, ctrl+c but can't edit
codeBox.readOnly = true;
codeBox.value = code;

SetGapBefore¶

void UI::TextInput.SetGapBefore(float)

Pixels between this widget and the one before it in its row (14 before a text, 8 before anything else); a negative value puts the default back. Has no effect on the first widget of a row. Requires host 0.23.6.

Example

UI::Text@ delta = window.AddText("+3", 15);
delta.SetGapBefore(10);

UI::Image¶

A picture in a window (from Window.AddImage).

visible¶

bool visible    // property of UI::Image, read and write

Whether the widget is shown. A hidden widget takes no space, so the rest of its row closes up (placed items, such as rectangles, are simply not drawn).

Example

// Buttons only while the cursor is on screen
pauseButton.visible = UI::CursorShown();
resetButton.visible = UI::CursorShown();

path¶

string path    // property of UI::Image, read and write

The PNG file shown.

Example

icon.path = Registry::Icon(i) != "" ? Registry::Icon(i) : Plugins::DefaultIcon();

SetGapBefore¶

void UI::Image.SetGapBefore(float)

Pixels between this widget and the one before it in its row (14 before a text, 8 before anything else); a negative value puts the default back. Has no effect on the first widget of a row. Requires host 0.23.6.

Example

UI::Text@ delta = window.AddText("+3", 15);
delta.SetGapBefore(10);

UI::CheckBox¶

A tick box with a label (from Window.AddCheckBox).

checked¶

bool checked    // property of UI::CheckBox, read and write

Whether it's ticked. Setting it doesn't count as a change.

Example

float angle = xBox.checked ? parseFloat(xAngle.text) : 0;

Changed¶

bool UI::CheckBox.Changed()

True once after the player ticks or unticks it. Reading it clears it.

Example

if (showBox.Changed())
    timerWindow.visible = showBox.checked;

SetColor¶

void UI::CheckBox.SetColor(float, float, float, float)

The label's colour, red, green, blue and opacity from 0 to 1 (linear, like every colour here).

Example

// Axis labels in the gizmo's colours: X red, Y green, Z blue
xBox.SetColor(0.594f, 0.0197f, 0, 1);
yBox.SetColor(0.1349f, 0.3959f, 0, 1);
zBox.SetColor(0.0251f, 0.207f, 0.85f, 1);

visible¶

bool visible    // property of UI::CheckBox, read and write

Whether the widget is shown. A hidden widget takes no space, so the rest of its row closes up (placed items, such as rectangles, are simply not drawn).

Example

// Buttons only while the cursor is on screen
pauseButton.visible = UI::CursorShown();
resetButton.visible = UI::CursorShown();

SetGapBefore¶

void UI::CheckBox.SetGapBefore(float)

Pixels between this widget and the one before it in its row (14 before a text, 8 before anything else); a negative value puts the default back. Has no effect on the first widget of a row. Requires host 0.23.6.

Example

UI::Text@ delta = window.AddText("+3", 15);
delta.SetGapBefore(10);