Table of Contents

Редактирование разметки и инструменты дизайна

Пакет IcyUI.Design позволяет редактировать разметку игры во время её работы: выбрать элемент на экране, передвинуть его, изменить свойства, добавить элементы управления и сохранить результат обратно в файлы .xml. Это инструмент разработки. Подключайте его только в отладочных сборках; выпущенной игре он не нужен и ничего ей не стоит.

Что в нём есть

Часть Что делает
DesignSession После подключения отслеживает каждую страницу разметки, которую загружает конфигурация, — по документу на страницу.
DesignDocument Текст разметки одной страницы, связанный с построенными из него элементами. Правка меняет текст и живые элементы вместе, её можно отменить, а сохраняет её Save.
EditorOverlay Встроенный в игру редактор поверх работающего интерфейса: Outline и Toolbox слева, Properties справа, панель команд сверху. F4 показывает и скрывает его.
EditorWorkspace Тот же редактор в виде страницы — с выбором документа и предпросмотром открытой страницы, для отладочного меню.
EditorSession, EditorFrame Части, из которых собраны оба редактора: выделение и правки, рамка выделения. Для собственных инструментов.

Настройка

Добавьте пакет и сделайте ссылку только отладочной, чтобы его не было в выпускных сборках. После dotnet add package IcyUI.Design --prerelease добавьте к созданному PackageReference Condition="'$(Configuration)' == 'Debug'".

Затем при запуске подключите сеанс дизайна и редактор внутри #if DEBUG:

// Call it before the first screen loads, inside #if DEBUG: pages loaded earlier can't be edited.
public static void AttachEditor(IIcyHost ui)
{
    DesignSession design = DesignSession.Attach(ui.Configuration);
    if (DesignSession.FindSourceRoot("MyGame.csproj", "Assets/UI") is { } root)
        design.UseSourceRoot(root);               // Save writes your project's files, not the build output's
    EditorOverlay.Attach(ui.MainCanvas, design);  // F4 shows and hides the editor
}
  • Подключайте до загрузки экранов. Сеанс видит только страницы, загруженные после его подключения.
  • Укажите исходные файлы. Страница загружается из папки сборки, поэтому без UseSourceRoot сохранение перезапишет копию там, и изменение пропадёт при следующей сборке. FindSourceRoot поднимается от папки игры к проекту и возвращает папку, где лежит разметка.

Для отладочного меню вместо оверлея поместите EditorWorkspace на одну из его страниц:

// The same editor as a page, for a debug menu.
public static void ShowEditorPage(Icy.UI.Controls.ContentControl debugPage, DesignSession design)
{
    debugPage.Content = new EditorWorkspace { Design = design };
}

Canvas работает с одним редактором за раз: пока показан оверлей, рабочее пространство ждёт, и наоборот.

Редактирование

У редактора два режима, они переключаются по Ctrl+Shift+E или с панели команд: в режиме Edit щелчок выделяет элемент под указателем; в режиме Interact интерфейс работает как в игре, так что можно открыть меню или вкладку, а затем править то, что на них показано.

  • Выделяйте щелчком или в Outline. Alt+стрелки переводят выделение на родителя, первый дочерний элемент или соседа.
  • Перемещайте и меняйте размер, перетаскивая выделение или его маркеры. В Grid элемент встаёт в ячейку под указателем и меняет размер через объединение строк и столбцов; в StackPanel — в ближайший промежуток между соседями; в остальных случаях он двигается за счёт внешнего отступа. Стрелки сдвигают его (с Shift — на больший шаг); Delete удаляет.
  • Меняйте свойства в панели Properties. Она показывает значения, видимые на экране (в том числе из стилей и привязок), а правка задаёт атрибут в разметке. Быстрые последовательные правки одного свойства отменяются одним шагом.
  • Добавляйте элементы управления щелчком в Toolbox: внутрь выделенного элемента, если это панель или пустой элемент с содержимым, иначе сразу после него.
  • Отменяйте и повторяйте через Ctrl+Z и Ctrl+Y (или Ctrl+Shift+Z). У каждого документа своя история.
  • Сохраняйте кнопками Save или Save all на панели команд. Сохранение записывает текст документа как есть: ваше форматирование и комментарии остаются.

Большинство правок видны сразу. Правка внутри стиля, шаблона или элемента свойства (<Button.Content>) меняет текст, но не живую страницу; документ сообщает NeedsReload, и изменение проявится при следующей загрузке страницы.

Можно и править файл .xml в текстовом редакторе во время работы игры: ReloadFromSource() у документа читает файл и применяет текст одной правкой, которую можно отменить. DesignSession.WatchSourceFiles() вызывает его сам при сохранении файла; см. Горячая перезагрузка и редактор в игре.

Производительность

Ничего из IcyUI.Design не выполняется, пока вы его не подключили, а с отладочной ссылкой в выпускной сборке его нет вовсе. Пока сеанс подключён, он хранит текст каждой отслеживаемой страницы и соответствие её разметки элементам. Скрытие оверлея отключает его рамку и панели; панели не работают каждый кадр, а обновляются при изменении документа.

Типичные ошибки

  • Элемент нельзя выделить. Он создан в коде, или его страница загружена до подключения сеанса. Править можно только элементы, построенные из отслеживаемой разметки.
  • Сохранение недоступно. Документ не знает, в какой файл писать: задайте UseSourceRoot или SourcePathResolver, сопоставляющий пути ресурсов с файлами. Причину показывает панель команд.
  • Изменение не видно. Оно внутри стиля или шаблона; перезагрузите страницу.

См. также