UI and You

​

Okay, but how do I make it fancy?

​

FancyWindow

• Nanotrasen - The default stylesheet. Used for any standard player-facing Uis
• System - Primarily used for admin and sandbox UIs (currently not implemented)

​

StyleClass

• OpenLeft: Makes the button flat on its left side
• OpenRight: Makes the button flat on its right side
• OpenBoth: Makes the button flat on both sides; square
• LabelSubtext: Makes the label smaller and a more muted color
• LabelKeyText: Makes the label bold and a highlight color
• LabelWeak: Weak is the opposite of strong; makes the label a more muted color

​

Writing Styles

​

All hail the mighty Sheetlet

• Generic Sheetlets: These go in Content.Client/Stylesheets/Sheetlets. These sheetlets concern generic UI elements used in many different UIs, and should be written generically to work with any stylesheet.
• Specific Sheetlets: These go along with the *.xaml files they are associated with. These sheetlets concern UI elements that are specific to a single UI, and should be written to work with the specific sheetlets they are associated with.

​

Style Rules

• Type: The type of element this rule affects. Anything inheriting from this type will also be affected by this rule.
• StyleClasses: The classes that the element must have to be affected by this rule. The element must have all of the classes specified by the rule to be affected by it. This is specified in the XML with the StyleClasses property.
• StyleIdentifier: The identifier of the element. This is a unique identifier that can be used to target a specific element. This should be used when there is only one instance of the element that needs to be styled in a highly specific manner. An element may only have one identifier, which is specified in the XML with the StyleIdentifier property.
• PseudoClasses: These are special classes that can be used to target elements in a specific state. For example, this is used to style buttons differently when hovered or pressed or whatever. These are triggered automatically through user interaction.
• Elements may also be styled based on their parent element, and all their style properties. In the style rule definition, this is done with the .ParentOf(...) method, which takes in another selector describing the child element which the styles will be applied to.

// you need this using statement to use the helper methods
using static Content.Client.Stylesheets.Redux.StylesheetHelpers;

var rules =
[
    // select any element...
    E()
        // ...with the class "negative"
        .Class(StyleClass.Negative)
        // ...and set its font color to the text color from the negative palette
        .FontColor(sheet.NegativePalette.Text),

    // select any `Label`...
    E<Label>()
        // ...with the class "LabelHeading"
        .Class(StyleClass.LabelHeading)
        // ...and set its font to a bold 16pt font
        .Font(sheet.BaseFont.GetFont(16, FontKind.Bold))
        // ...and its font color to the text color from the highlight palette
        .FontColor(sheet.HighlightPalette.Text)

    // select any `ContainerButton`...
     E<ContainerButton>()
        // ...with the class "button"
        .Class(ContainerButton.StyleClassButton)
        // ...and the class "ButtonSmall"
        .Class(StyleClass.ButtonSmall)
        // ...that is the parent of a `Label`,
        .ParentOf(E<Label>())
        // ...and set that `Label`'s font to an 8pt font
        .Font(sheet.BaseFont.GetFont(8))
];

​

Death to Hardcoding!

​

ColorPalette

• PrimaryPalette: Used for foreground elements
• SecondaryPalette: Used for background elements
• PositivePalette: A traditionally green palette used to represent success / good / full
• NegativePalette: A traditionally red palette used to represent errors / bad / empty
• HighlightPalette: Used to highlight headings or important elements

• +0: Text Base
• -1: TextDark, Element
• -2: BackgroundLight, PressedElement
• -3: Background
• -4: BackgroundDark, DisabledElement

​

ISheetletConfig

[CommonSheetlet] // don't forget `[CommonSheetlet]`!
public sealed class ExampleSheetlet<T> : Sheetlet<T> where T : PalettedStylesheet, IExampleConfig

​

Resource Access

​

Generic Sheetlets

• You should always select elements with .Class and not .Identifier.
• When accessing resources, use the GetTextureOr method to get the texture and provide a fallback root to use if the texture is not found within the stylesheets roots.
• Avoid manual hardcoding of classes. When referencing classes, you should only use classes defined on the element being styled (in StyleClass* properties) or define your own in StyleClass.cs.
• If you need to access a resource that is not provided already, you should add the path to the relevant ISheetletConfig or create a new one entirely.

using Content.Client.Stylesheets.Redux.SheetletConfigs;
using Content.Client.Stylesheets.Redux.Stylesheets;
using Robust.Client.UserInterface;
using Robust.Client.UserInterface.Controls;
// you need to add this line manually to access the helper methods
using static Content.Client.Stylesheets.Redux.StylesheetHelpers;

namespace Content.Client.Stylesheets.Sheetlets;

// MAKE SURE TO INCLUDE THE [CommonSheetlet] ATTRIBUTE
[CommonSheetlet]
// define the sheetlet and its dependencies
public sealed class CheckboxSheetlet<T> : Sheetlet<T> where T : PalettedStylesheet, ICheckboxConfig
{
    public override StyleRule[] GetRules(T sheet, object config)
    {
        // cast the sheet into any of its required dependencies here
        ICheckboxConfig checkboxCfg = sheet;

        // get any textures / construct any complicated resources here
        var uncheckedTex = sheet.GetTextureOr(checkboxCfg.CheckboxUncheckedPath, NanotrasenStylesheet.TextureRoot);
        var checkedTex = sheet.GetTextureOr(checkboxCfg.CheckboxCheckedPath, NanotrasenStylesheet.TextureRoot);

        // and finally, define all the style rules and return a big 'ol list of them
        return
        [
            E<TextureRect>()
                .Class(CheckBox.StyleClassCheckBox)
                .Prop(TextureRect.StylePropertyTexture, uncheckedTex),
            E<TextureRect>()
                .Class(CheckBox.StyleClassCheckBox)
                .Class(CheckBox.StyleClassCheckBoxChecked)
                .Prop(TextureRect.StylePropertyTexture, checkedTex),
            E<BoxContainer>()
                .Class(CheckBox.StyleClassCheckBox)
                .Prop(BoxContainer.StylePropertySeparation, 10),
        ];
    }
}

​

Specific Sheetlets

• You should prefer to select elements with .Identifier and not .Class.
• Any styles that COULD be used by another UI should be moved to a generic sheetlet.
• Hardcoding is more relaxed, you should still try and avoid it when possible, but hardcoding StyleIdentifiers is probably fine.
• If you REALLY need a specific resource and its not worth adding it to an ISheetletConfig you can access it through ResCache as normal.
• You don’t need to do the generic type constraints thing since the sheetlet should be specific to a single UI, and thus a single stylesheet.

using Content.Client.Resources;
using Content.Client.Stylesheets.Redux;
using Content.Client.Stylesheets.Redux.SheetletConfigs;
using Content.Client.Stylesheets.Redux.Stylesheets;
using Robust.Client.Graphics;
using Robust.Client.UserInterface;
using Robust.Client.UserInterface.Controls;
// you need to add this line manually to access the helper methods
using static Content.Client.Stylesheets.Redux.StylesheetHelpers;

namespace Content.Client.Paper.UI;

// MAKE SURE TO INCLUDE THE [CommonSheetlet] ATTRIBUTE
[CommonSheetlet]
// which stylesheet is this sheetlet for
public sealed class PaperSheetlet : Sheetlet<NanotrasenStylesheet>
{
    public override StyleRule[] GetRules(NanotrasenStylesheet sheet, object config)
    {
        // define any IConfigs you need here
        IWindowConfig windowCfg = sheet;

        // get any textures / construct any complicated resources here
        var paperBackground = ResCache.GetTexture("/Textures/Interface/Paper/paper_background_default.svg.96dpi.png")
            .IntoPatch(StyleBox.Margin.All, 16);
        var paperBox = new StyleBoxTexture
            { Texture = sheet.GetTexture(windowCfg.TransparentWindowBackgroundBorderedPath) };
        paperBox.SetPatchMargin(StyleBox.Margin.All, 2);

        // and finally, define all the style rules and return a big 'ol list of them
        return
        [
            E<PanelContainer>().Identifier("PaperContainer").Panel(paperBox),
            E<PanelContainer>()
                .Identifier("PaperDefaultBorder")
                .Prop(PanelContainer.StylePropertyPanel, paperBackground),
        ];
    }
}

​

Making your own Stylesheet

​

Writing C# for UI

TODO: I don’t feel confident enough in my knowledge to describe in detail what to do and what not to do. This is just a general overview for now and should be updated. Also this should probably be another page.

• Robotics Console
• Reagent Dispenser
• BatteryMenu

Content.Server/MyThing/:
    - Systems/:
          - MyThingSystem.cs # Inherits from `SharedMyThingSystem.cs`
            # Takes the messages and makes changes in-world, and takes data from in-world to update the UI state.
Content.Shared/MyThing/:
    - Components/:
          - MyThingComponent.cs # Defines the component for the entity
    - Systems/:
          - SharedMyThingSystem.cs # Controls the appearance data and general shared logic
    - SharedMyThing.cs # Defines the messages that can be sent between server and client, and the UI state

Content.Client/MyThing/:
    - Ui/:
          - MyThingWindow.xaml # The main window, where the main structure of the UI is defined
          - MyThingWindow.xaml.cs # Defines behavior for `MyThingWindow.xaml`, reading in inputs and calling `Action`s
          - MyThingBoundUserInterface.cs # Interfaces with the server, sending messages and updating the UI state
    - Systems/:
          - MyThingSystem.cs # Inherits from `SharedMyThingSystem.cs`
            # Takes appearance data and makes in-world changes to reflect that

​

Bound User Interfaces

TODO: someone more familiar with BUIs than me should write about how to write good BUIs. I’ll just stick the notes from #codebase-changes by Bard in the discord here for now:

Predicted BUIs are in:

For networking data: Option 1 (Preferred). Move the BUI state to component states. Use an existing client system / make one to handle updating the BUI upon the state updating (use TryGetOpenUi) and upon calling Open in the BoundUserInterface. See JukeboxSystem for an example, e.g.

private void OnJukeboxAfterState(Entity<JukeboxComponent> ent, ref AfterAutoHandleStateEvent args)
{
    if (!_uiSystem.TryGetOpenUi<JukeboxBoundUserInterface>(ent.Owner, JukeboxUiKey.Key, out var bui))
        return;

    bui.Reload();
}

Option 2. Have the BUI control be a dummy until the state comes in For UIs: Call TryOpenUi in shared where possible and the client should just handle it. Calling it from server will also still work similar to the old behavior. For messages: Use SendPredictedMessage where possible in BUIs. At some point this will likely become the default over SendMessage. Overall: Prefer to use the overloads that take in EntityUids instead of ICommonSession, this will make it easier to code NPCs who can interact with UIs in future.

• There’s a helper under this.CreateWindow<TWindow>() for BUIs that handles disposing + opening + close subscription for you.
• There’s a method OnProtoReload that gets called on BUIs so you can override and handle it without having to manually subscribe on another system.
• I have added prototype reload support to some stuff.
• I have cleaned up a lot of BUI code. Windows now just raise events and the BUI itself handles message sending.

Some notes for future:

• You should spawn / delete control entities inside of EnteredTree and ExitedTree rather than inside Dispose.
• Controls should be able to be constructed with an empty constructor and should not call BUI methods directly. This makes re-use significantly easier.
• All new controls must handle prototype reloading if applicable.
• All new controls should prefer to use component states and not BUI states where possible. These work better with prediction and are easier to use.
• Controls should be able to handle components disappearing and not rely upon GetComponent<T> everywhere as there are no guarantees the component exists.