UI Toolkit Tablet Backend¶

Overview¶

UI Elements Records¶

The records reference the UI Toolkit elements of each document. There is no way to automatically find them so you must rely on string queries. This is handled in the Document Query Ultility which works as a Visual Element extension.

Records are used in the system since they provided Getters, Setters, and Equality Operators by default. They are a relatively new feature in C# and a custom script is needed to get them working in Unity but they are great to work with and the new standard.

Common Contents¶

Labels
Buttons
Visual Elements
Images

Sample Record¶

Here is the record for the module selection screen. You can see it is just a declaration of the elements which can be modified by the backend. Sealed is just a code security decleration in C# to ensure that no classes extend from or inherit it.

Since they contain all of the needed visual references for displaying data, the back end and front end are cleanly seperated with the record acting as the middle layer.

public sealed record ModuleSelectionElements(
    Label ModuleNameLabel,
    VisualElement ModulePreviewImage,
    VisualElement DemonstrationTick,
    VisualElement ExplainerTick,
    VisualElement PracticeTick,
    VisualElement ExaminationTick,
    Label LeaderboardNameGold,
    Label LeaderboardNameSilver,
    Label LeaderboardNameBronze,
    Label LeaderboardScoreGold,
    Label LeaderboardScoreSilver,
    Label LeaderboardScoreBronze
);

Sample Record Query Extension¶

The Document Query Ulitity is used to extract all of the elements from the UXML Document in a single line of code. It extends the visual element and returns the record. Since the queries are string based, the UI Elements constants class is used to reference the elements from the document. To do this,, everything needs a unique name.

UI Elements Constants¶

// Module Selection Panel Constants
public const string ModuleTitleLabel = "module-title-lbl";
public const string ModulePreviewImage = "module-preview-img";

public const string TickDemonstration = "tick-demonstration";
public const string TickExplainer = "tick-explainer";
public const string TickPractice = "tick-practice";
public const string TickExamination = "tick-examination";

public const string LeaderboardNameGold = "ldr-name-gold";
public const string LeaderboardNameSilver = "ldr-name-silver";
public const string LeaderboardNameBronze = "ldr-name-bronze";

public const string LeaderboardScoreGold = "ldr-score-gold";
public const string LeaderboardScoreSilver = "ldr-score-silver";
public const string LeaderboardScoreBronze = "ldr-score-bronze";

Document Query Utility Getter¶

public static ModuleSelectionElements GetModuleSelectionElements(this VisualElement root)
{
    return new ModuleSelectionElements(
        ModuleNameLabel: root.Q<Label>(UIElements.ModuleTitleLabel),
        ModulePreviewImage: root.Q<VisualElement>(UIElements.ModulePreviewImage),
        DemonstrationTick: root.Q<VisualElement>(UIElements.TickDemonstration),
        ExplainerTick: root.Q<VisualElement>(UIElements.TickExplainer),
        PracticeTick: root.Q<VisualElement>(UIElements.TickPractice),
        ExaminationTick: root.Q<VisualElement>(UIElements.TickExamination),
        LeaderboardNameGold: root.Q<Label>(UIElements.LeaderboardNameGold),
        LeaderboardNameSilver: root.Q<Label>(UIElements.LeaderboardNameSilver),
        LeaderboardNameBronze: root.Q<Label>(UIElements.LeaderboardNameBronze),
        LeaderboardScoreGold: root.Q<Label>(UIElements.LeaderboardScoreGold),
        LeaderboardScoreSilver: root.Q<Label>(UIElements.LeaderboardScoreSilver),
        LeaderboardScoreBronze: root.Q<Label>(UIElements.LeaderboardScoreBronze)
    );
}

Get Elements Call in Panel Host¶

// Elements is unique for each host so must be declared
private ModuleSelectionElements _elements;

// Gets the elements from the Document Root which is declared in the base host class
protected override void GetElements() => _elements = Root.GetModuleSelectionElements();

UI Panel Host¶

Overview¶

The host is the Unity exposed layer of the panel. It contains the references to the UI Document and 3D Elements. Right now it also handles the data and setting data but this should be split on a bigger scale if wanted.

Base Host¶

The base host has a serialized reference to the UI Document, the Root visual element of the UI Document, and a function called get elements. All panels will need this elements.

The get elements function is empty because each panel will have its own unique elements record.

Panel Hosts¶

The panel hosts imherit from the base and have a private field in their elements record. This is then gotten in the required function as shown above. The example screens show how properties can be done, unique panel functions etc.