UI и вы

​

Хорошо, но как сделать его красивым?

​

FancyWindow

• Nanotrasen — stylesheet по умолчанию. Используется для любых стандартных UI, предназначенных для игроков.
• System — В основном используется для UI администраторов и sandbox (в настоящее время не реализован).

​

StyleClass

• OpenLeft: Делает кнопку плоской с левой стороны.
• OpenRight: Делает кнопку плоской с правой стороны.
• OpenBoth: Делает кнопку плоской с обеих сторон; квадратной.
• LabelSubtext: Делает Label меньше и более приглушённого цвета.
• LabelKeyText: Делает Label жирным и цвета выделения.
• LabelWeak: Weak — противоположность strong; делает Label более приглушённого цвета.

​

Написание стилей

​

Да здравствует могучий Sheetlet

• Общие Sheetlets (Generic Sheetlets): Они находятся в Content.Client/Stylesheets/Sheetlets. Эти sheetlets касаются общих элементов UI, используемых во многих разных UI, и должны быть написаны обобщённо, чтобы работать с любым stylesheet.
• Специфические Sheetlets (Specific Sheetlets): Они находятся вместе с файлами *.xaml, с которыми они связаны. Эти sheetlets касаются элементов UI, специфичных для одного UI, и должны быть написаны для работы с конкретными sheetlets, с которыми они связаны.

​

Правила стиля

• Type: Тип элемента, на который влияет это правило. Всё, что наследуется от этого типа, также будет подвержено влиянию этого правила.
• StyleClasses: Классы, которые должен иметь элемент, чтобы на него повлияло это правило. Элемент должен иметь все классы, указанные правилом, чтобы на него повлияло это правило. Это задаётся в XML с помощью свойства StyleClasses.
• StyleIdentifier: Идентификатор элемента. Это уникальный идентификатор, который можно использовать для нацеливания на конкретный элемент. Он должен использоваться, когда существует только один экземпляр элемента, который нужно стилизовать очень специфическим образом. Элемент может иметь только один идентификатор, который задаётся в XML с помощью свойства StyleIdentifier.
• PseudoClasses: Это специальные классы, которые можно использовать для нацеливания на элементы в определённом состоянии. Например, это используется для стилизации кнопок по-разному при наведении или нажатии. Они срабатывают автоматически при взаимодействии пользователя.
• Элементы также могут быть стилизованы на основе их родительского элемента и всех их свойств стиля. В определении правила стиля это делается с помощью метода .ParentOf(...), который принимает другой селектор, описывающий дочерний элемент, к которому будут применены стили.

// 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))
];

​

Смерть Хардкодингу!

​

ColorPalette

• PrimaryPalette: Используется для элементов переднего плана.
• SecondaryPalette: Используется для фоновых элементов.
• PositivePalette: Традиционно зелёная палитра, используемая для обозначения успеха / хорошо / полно.
• NegativePalette: Традиционно красная палитра, используемая для обозначения ошибок / плохо / пусто.
• HighlightPalette: Используется для выделения заголовков или важных элементов.

• +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

​

Доступ к ресурсам

​

Общие Sheetlets

• Вы всегда должны выбирать элементы с помощью .Class, а не .Identifier.
• При доступе к ресурсам используйте метод GetTextureOr, чтобы получить текстуру и указать запасной корень, который будет использован, если текстура не найдена в корнях stylesheet.
• Избегайте ручного хардкодинга классов. При ссылке на классы вы должны использовать только классы, определённые на стилизуемом элементе (в свойствах StyleClass*), или определять свои собственные в StyleClass.cs.
• Если вам нужно получить доступ к ресурсу, который ещё не предоставлен, вы должны добавить путь к соответствующему ISheetletConfig или создать новый.

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),
        ];
    }
}

​

Специфические Sheetlets

• Вы должны предпочитать выбирать элементы с помощью .Identifier, а не .Class.
• Любые стили, которые МОГУТ быть использованы другим UI, должны быть перемещены в общий sheetlet.
• Хардкодинг допускается более свободно; вы всё равно должны стараться избегать его, когда это возможно, но хардкодинг StyleIdentifier-ов, вероятно, нормален.
• Если вам ДЕЙСТВИТЕЛЬНО нужен специфический ресурс, и нет смысла добавлять его в ISheetletConfig, вы можете получить к нему доступ через ResCache как обычно.
• Вам не нужно делать ограничение обобщённого типа, так как sheetlet должен быть специфичен для одного UI, а значит, и для одного 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),
        ];
    }
}

​

Создание собственного Stylesheet

​

Написание C# для UI

TODO: Я недостаточно уверен в своих знаниях, чтобы подробно описать, что делать, а чего не делать. Это всего лишь общий обзор на данный момент, и его следует обновить. Также это, вероятно, должно быть отдельной страницей.

• 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: кто-то более знакомый с BUI, чем я, должен написать о том, как писать хорошие BUI. Я просто вставлю заметки из #codebase-changes от Bard в дискорде:

Predicted BUIs are in:

Для передачи данных по сети: Вариант 1 (Предпочтительный). Переместите состояние BUI в component states. Используйте существующую клиентскую систему / создайте новую для обработки обновления BUI при обновлении состояния (используйте TryGetOpenUi) и при вызове Open в BoundUserInterface. См. JukeboxSystem в качестве примера, например

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

    bui.Reload();
}

Вариант 2. Сделайте элемент управления BUI заглушкой до получения состояния. Для UI: вызывайте TryOpenUi в shared, где это возможно, и клиент должен просто обработать это. Вызов с сервера также будет работать, как и раньше. Для сообщений: используйте SendPredictedMessage, где это возможно, в BUI. В какой-то момент это, вероятно, станет поведением по умолчанию вместо SendMessage. В целом: предпочитайте использовать перегрузки, принимающие EntityUid вместо ICommonSession — это упростит программирование NPC, которые смогут взаимодействовать с UI в будущем.

• Существует вспомогательный метод this.CreateWindow<TWindow>() для BUI, который обрабатывает удаление + открытие + подписку на закрытие за вас.
• Существует метод OnProtoReload, который вызывается на BUI, так что вы можете переопределить его и обработать без необходимости вручную подписываться на другой системе.
• Я добавил поддержку перезагрузки прототипов для некоторых вещей.
• Я почистил много кода BUI. Windows теперь просто вызывают события, а сам BUI обрабатывает отправку сообщений.

Некоторые заметки на будущее:

• Вы должны создавать / удалять control entities внутри EnteredTree и ExitedTree, а не внутри Dispose.
• Элементы управления должны иметь возможность быть созданными с пустым конструктором и не должны вызывать методы BUI напрямую. Это значительно упрощает повторное использование.
• Все новые элементы управления должны обрабатывать перезагрузку прототипов, если это применимо.
• Все новые элементы управления должны предпочитать использование component states, а не BUI states, где это возможно. Они лучше работают с prediction и проще в использовании.
• Элементы управления должны уметь обрабатывать исчезновение компонентов и не полагаться на GetComponent<T> везде, так как нет гарантии, что компонент существует.