Scripting API

Scripting API

UiElement

Class in Abyss.Core, from Abyss.Core.

An element of a shown UI document: the entity its document's element became, found by the identity the document gave it. What a document's class names each of its elements as.

public sealed class UiElement

Remarks

One for each element of each document shown, made as it is shown, so a class's Title.Text = "Paused"; is the element's own text set.

Properties

Entity

public ulong Entity { get; }

The entity it is; zero for none — an element its document no longer has.

Exists

public bool Exists { get; }

Whether it is there.

Material

public MaterialId? Material { get; set; }

The material it is drawn with — above its background and its image, below its text — or null for none. Set, it is drawn with that one: a material running a UI shader, which one shared by several elements draws for all of them; World.CopyMaterial gives one element values of its own.

Exceptions

  • InvalidOperationException: The element is not there.
  • ArgumentException: The material runs Bevy's own surface, which draws no UI element.

Text

public string Text { get; set; }

What it says; empty for one with no text. Set, it says that, and an element with no text is given some.

Exceptions

  • InvalidOperationException: It is not there.

Read, it is a string made for the asking; to set text that changes every frame, see UiElement.SetText.

Items

public IReadOnlyList<UiView> Items { get; }

The template instances made under this element, in the order they were made; see UiElement.Add.

WasClicked

public bool WasClicked { get; }

Whether it was clicked since the frame before: asked from a system as a key is.

WasPressed

public bool WasPressed { get; }

Whether it was pressed down by the mouse since the frame before, let go of or not: asked from a system as a key is.

Focused

public bool Focused { get; }

Whether it has the interface's focus: what the keyboard and the gamepad press.

Checked

public bool Checked { get; set; }

Whether it is on, for a toggle: set, it is turned on or off, and its class is not told — the code setting it knows. False for what is no toggle, which setting leaves as it is.

Exceptions

  • InvalidOperationException: It is not there, as it is set.

Value

public float Value { get; set; }

A slider's value: set, it is moved there, kept in its range, and its class is not told — the code setting it knows. Zero for what is no slider, which setting leaves as it is.

Exceptions

  • InvalidOperationException: It is not there, as it is set.

Picked

public int Picked { get; set; }

A dropdown's picked option, by its place among its options from zero: set, that option is picked — the first for a place below zero, the last where it has fewer — and its class is not told, the code setting it knows. Zero for what is no dropdown, which setting leaves as it is.

Exceptions

  • InvalidOperationException: It is not there, as it is set.

PickedText

public string PickedText { get; }

The words of a dropdown's picked option, as its label says them; empty for what is no dropdown, or has no options.

Options

public IReadOnlyList<string> Options { get; }

The words of each of a dropdown's options, in order; none for what is no dropdown.

IsOpen

public bool IsOpen { get; }

Whether a dropdown's list is open; false for what is no dropdown.

Methods

SetText

public void SetText(ref UiTextHandler text)

Gives it text written as an interpolated string, and makes no string to do it: Score.SetText($"Score: {score}"), Timer.SetText($"{seconds:F1} s").

Parameters

  • text

Exceptions

  • InvalidOperationException: It is not there.

The compiler hands each piece to UiTextHandler, which writes it into a buffer it borrows and gives back — a number formatted where it goes, as ISpanFormattable formats one, with its format and alignment — and the engine is given the buffer's text once. A text that changes every frame costs no garbage.

Text the element already says is no change: the engine leaves it, and lays nothing out again.

SetText

public void SetText(scoped ReadOnlySpan<char> text)

Gives it the text in text, from a buffer of the caller's: no string is made.

Parameters

  • text

Exceptions

  • InvalidOperationException: It is not there.

Localize

public void Localize(StringKey key, params ReadOnlySpan<LocalizedArgument> arguments)

Makes what it says a string of the game's, in the player's language: Title.Localize(Strings.Menu.Play), Coins.Localize(Strings.Hud.Coins, ("count", coins)). The engine fills it now, and again as the language changes, with no code of the game's; given other arguments, it is filled with them. Text given it after, by UiElement.Text or SetText, is its own again; in a game that is not localized it keeps what it said. See Localization.

Parameters

  • key
  • arguments

Exceptions

  • InvalidOperationException: It is not there.

Unlocalize

public void Unlocalize()

Stops filling it from the game's strings (Localize): it says its own words again, what it was written as.

Exceptions

  • InvalidOperationException: It is not there.

SetText

public void SetText(scoped ReadOnlySpan<byte> utf8)

Gives it the text utf8 says, as UTF-8 — what Utf8.TryWrite writes.

Parameters

  • utf8

Exceptions

  • InvalidOperationException: It is not there.
  • AbyssException: It is not UTF-8.

SetImage

public void SetImage(ImageId image, ImageRegion? region = null)

Draws image in it — one the game made (CreateImage) or loaded — or the rectangle region of it in the image's pixels: a block's icon from a sheet of them, a cell of an atlas. An element with no image is given one, drawn as its sheet draws an image, stretched to its size unless it says otherwise. What it draws already is no change. Drawn over its stylesheets, as a style a browser's script sets is: a card given its icon as it is shown keeps it, rather than the image its document gave it.

Parameters

  • image
  • region

Exceptions

  • InvalidOperationException: It is not there.
  • AbyssException: AbyssStatus.InvalidUiRequest for a region that is no rectangle — a number that is not one, a corner left of or above the image, or one past the other — and the image's own for an id that names none.

ClearImage

public void ClearImage()

Draws no image in it: Bevy's transparent one, as an element given none draws.

Exceptions

  • InvalidOperationException: It is not there.

MoveTo

public void MoveTo(Vector2 at)

Puts it at at from its parent's top-left, in its document's units — the reference resolution's, as GameUi.Pointer gives a place — as its left and top: where its sheet places it absolutely, as a stack carried under the pointer or a tooltip by what it tells of is placed. Where it is already is no change. Set over its stylesheets, as UiElement.SetImage's image is: a rule that places it gives way.

Parameters

  • at

Exceptions

  • InvalidOperationException: It is not there.
  • AbyssException: AbyssStatus.InvalidUiRequest for a place that is no number.

AddClass

public void AddClass(string name)

Gives it the class name, which a stylesheet's .name selects, as an HTML element is given one: Health.AddClass("low"). A class it has already is no change.

Parameters

  • name

Exceptions

  • InvalidOperationException: It is not there.
  • AbyssException: The name is no class: empty, or holding a space.

Its other classes stay. The engine restyles it in the frame, with the sheet's transitions.

RemoveClass

public void RemoveClass(string name)

Takes the class name away from it; one it has not is no change.

Parameters

  • name

Exceptions

  • InvalidOperationException: It is not there.
  • AbyssException: The name is no class: empty, or holding a space.

ToggleClass

public bool ToggleClass(string name)

Gives it the class name where it has it not, takes it away where it has, and says whether it has it now.

Parameters

  • name

Exceptions

  • InvalidOperationException: It is not there.
  • AbyssException: The name is no class: empty, or holding a space.

ToggleClass

public void ToggleClass(string name, bool on)

Gives it the class name where on, and takes it away where not: Door.ToggleClass("open", isOpen).

Parameters

  • name
  • on

Exceptions

  • InvalidOperationException: It is not there.
  • AbyssException: The name is no class: empty, or holding a space.

HasClass

public bool HasClass(string name)

Whether it has the class name, its own or one the engine gives it as its state is — rtl and touch on a document's top, open on an open dropdown; an element that is not there has none.

Parameters

  • name

Exceptions

  • AbyssException: The name is no class: empty, or holding a space.

Add<T>

public T Add<T>() where T : UiView

Makes an instance of the UI document whose class is T under this element, after what is in it: a template — a card in a panel of cards — that is part of this element's document from then on, styled by its sheets and then its own, and its own class, given back, hearing what its elements do. Shown at once where its document has loaded, as one loaded with the game has; otherwise once it has, its class told it is shown.

Type parameters

  • T: The template's class, which the build makes of its document.

Exceptions

  • InvalidOperationException: This element is not there, nor part of a document shown; or T is no UI document's class.

Clear

public void Clear()

Takes every template instance made under this element away, each class told it is hidden.

Bind

public void Bind(Func<float> read, Action<float>? write = null)

Binds a slider to what the game holds: moved to what read says, between frames, where it says otherwise; and, given write, each value the player moves it to written — Volume.Bind(() => audio.Volume, value => audio.Volume = value). A setting Preferences.Use gave is saved as the slider is let go of.

Parameters

  • read
  • write

Exceptions

  • InvalidOperationException: It is not there, is part of no document shown, or is no slider.

One binding an element: binding it again lets go of the one before. A binding goes with its document, or with UiElement.Unbind.

Bind

public void Bind(Func<int> read, Action<int>? write = null)

Binds a dropdown to what the game holds: its option at the place read says picked where it says otherwise, and, given write, the place of each option the player picks written — Quality.Bind(() => settings.Quality, picked => settings.Quality = picked), saved as it is picked where it is a setting Preferences.Use gave. A slider is bound to a whole number as to any number, its value rounded as it is written.

Parameters

  • read
  • write

Exceptions

  • InvalidOperationException: It is not there, is part of no document shown, or is neither a dropdown nor a slider.

As Bind.

Bind

public void Bind(Func<bool> read, Action<bool>? write = null)

Binds a toggle to what the game holds: turned to what read says where it says otherwise, and, given write, what the player turns it to written — saved as it is turned, where it is a setting Preferences.Use gave.

Parameters

  • read
  • write

Exceptions

  • InvalidOperationException: It is not there, is part of no document shown, or is no toggle.

As Bind.

Bind

public void Bind(Func<string> read, Action<string>? write = null)

Binds its text to what the game holds: a label's — Score.Bind(() => $"Score: {score}") — or a text field's, which, given write, writes what the player types, a letter at a time, saved as it is typed where it is a setting Preferences.Use gave.

Parameters

  • read
  • write

Exceptions

  • InvalidOperationException: It is not there, or is part of no document shown.

As Bind. What read gives is a string made each frame; text that changes every frame is UiElement.SetText's, which makes none.

Bind<TView, TItem>

public void Bind<TView, TItem>(IReadOnlyList<TItem> items, Action<TView, TItem> show) where TView : UiView

Binds this element to a list: one instance of TView's document under it for each item, in the list's order, each shown its item by show once it is shown — Cards.Bind(items, (ItemCard card, Item item) => card.Show(item)). An item added to the list has a card made for it, one taken out has its card taken away, and the cards follow its order, the list compared between frames.

Type parameters

  • TView: The template's class, which the build makes of its document.
  • TItem: What the list holds.

Parameters

  • items
  • show

Exceptions

  • InvalidOperationException: It is not there, or is part of no document shown; or TView is no UI document's class.

An item is told apart as its type tells two apart — a class by which it is, a record by what it holds — and two alike by their order. A card taken away from code while its item is still in the list is made again: the list says what is shown.

As Bind; unbound, the cards stay as they are.

Unbind

public bool Unbind()

Lets go of its binding, leaving it as it is; whether it had one.

SetOptions

public void SetOptions(IEnumerable<string> options)

Gives a dropdown these options, in this order — Language.SetOptions(languages.Select(each => each.NativeName)): each it has says its word, one more is made for each word past them, a copy of its first option, and the rest are taken away. Each says what it is given, its localized text, where it had one, let go of. The option picked stays where it still is, else the last is picked.

Parameters

  • options

Exceptions

  • InvalidOperationException: It is not there, or is no dropdown.
  • ArgumentException: An option holds U+001E, which ends each option's words as they cross to the engine.

Open

public void Open()

Opens a dropdown's list, where it opens, focus on the picked option, as a click on it would.

Exceptions

  • InvalidOperationException: It is not there, or is no dropdown.

Close

public void Close()

Closes a dropdown's list as it is, nothing picked, focus back on the dropdown.

Exceptions

  • InvalidOperationException: It is not there, or is no dropdown.

SimulateClick

public void SimulateClick()

Presses it as a click on it would — a button clicked, a toggle turned — heard on the next step: for a test of a game's interface.

Exceptions

  • InvalidOperationException: It is not there.

Focus

public void Focus()

Gives it the interface's focus, so Enter presses it where it is a button.

Exceptions

  • InvalidOperationException: It is not there.