Глава 3.2: Формат файлов макетов (.layout)

Главная | << Предыдущая: Типы виджетов | Формат файлов макетов | Следующая: Размеры и позиционирование >>

Базовая структура

Файл .layout определяет дерево виджетов. Каждый файл имеет ровно один корневой виджет, содержащий вложенные дочерние элементы.

 WidgetTypeClass WidgetName {
 attribute value
 attribute "quoted value"
 {
  ChildWidgetTypeClass ChildName {
   attribute value
  }
 }
}

Ключевые правила:

Корневой элемент --- всегда один виджет (обычно FrameWidgetClass).
Имена типов виджетов используют имя класса макета, которое всегда заканчивается на Class (например, FrameWidgetClass, TextWidgetClass, ButtonWidgetClass).
Каждый виджет имеет уникальное имя после своего типа класса.
Атрибуты --- это пары ключ значение, по одному на строку.
Имена атрибутов, содержащие пробелы, должны быть в кавычках: "text halign" center.
Строковые значения заключаются в кавычки: text "Hello World".
Числовые значения без кавычек: size 0.5 0.3.
Дочерние элементы вложены внутри блоков { } после атрибутов родителя.

Справочник атрибутов

Позиционирование и размеры

Атрибут	Значения	Описание
`position`	`x y`	Позиция виджета (пропорциональная 0-1 или пиксельные значения)
`size`	`w h`	Размеры виджета (пропорциональные 0-1 или пиксельные значения)
`halign`	`left_ref`, `center_ref`, `right_ref`	Горизонтальная точка привязки
`valign`	`top_ref`, `center_ref`, `bottom_ref`	Вертикальная точка привязки
`hexactpos`	`0` или `1`	0 = пропорциональная позиция X, 1 = пиксельная позиция X
`vexactpos`	`0` или `1`	0 = пропорциональная позиция Y, 1 = пиксельная позиция Y
`hexactsize`	`0` или `1`	0 = пропорциональная ширина, 1 = пиксельная ширина
`vexactsize`	`0` или `1`	0 = пропорциональная высота, 1 = пиксельная высота
`fixaspect`	`fixwidth`, `fixheight`	Сохранять пропорции, ограничивая одно измерение
`scaled`	`0` или `1`	Масштабировать с настройкой масштаба UI DayZ
`priority`	целое число	Z-порядок (более высокие значения отрисовываются поверх)

Флаги hexactpos, vexactpos, hexactsize и vexactsize --- самые важные атрибуты во всей системе макетов. Они контролируют, использует ли каждое измерение пропорциональные (0.0 - 1.0 относительно родителя) или пиксельные (абсолютные пиксели экрана) единицы. См. 3.3 Размеры и позиционирование для подробного объяснения.

Визуальные атрибуты

Атрибут	Значения	Описание
`visible`	`0` или `1`	Начальная видимость (0 = скрыт)
`color`	`r g b a`	Цвет в виде четырёх float, каждый 0.0 до 1.0
`style`	имя стиля	Предопределённый визуальный стиль (напр., `Default`, `Colorable`)
`draggable`	`0` или `1`	Виджет может быть перетащен пользователем
`clipchildren`	`0` или `1`	Обрезать дочерние виджеты по границам этого виджета
`inheritalpha`	`0` или `1`	Дочерние наследуют значение альфа этого виджета
`keepsafezone`	`0` или `1`	Удерживать виджет в безопасной зоне экрана

Поведенческие атрибуты

Атрибут	Значения	Описание
`ignorepointer`	`0` или `1`	Виджет игнорирует ввод мыши (клики проходят сквозь)
`disabled`	`0` или `1`	Виджет отключён
`"no focus"`	`0` или `1`	Виджет не может получить фокус клавиатуры

Текстовые атрибуты

Применяются к TextWidgetClass, RichTextWidgetClass, MultilineTextWidgetClass, ButtonWidgetClass и другим виджетам с текстом.

Атрибут	Значения	Описание
`text`	`"строка"`	Текстовое содержимое по умолчанию
`font`	`"путь/к/шрифту"`	Путь к файлу шрифта
`"text halign"`	`left`, `center`, `right`	Горизонтальное выравнивание текста внутри виджета
`"text valign"`	`top`, `center`, `bottom`	Вертикальное выравнивание текста внутри виджета
`"bold text"`	`0` или `1`	Жирное отображение
`"italic text"`	`0` или `1`	Курсивное отображение
`"exact text"`	`0` или `1`	Использовать точный пиксельный размер шрифта вместо пропорционального
`"exact text size"`	целое число	Размер шрифта в пикселях (требует `"exact text" 1`)
`"size to text h"`	`0` или `1`	Изменить ширину виджета под текст
`"size to text v"`	`0` или `1`	Изменить высоту виджета под текст
`"text sharpness"`	float	Резкость отрисовки текста
`wrap`	`0` или `1`	Включить перенос слов

Атрибуты изображения

Применяются к ImageWidgetClass.

Атрибут	Значения	Описание
`image0`	`"set:имя image:имя"`	Основное изображение из imageset
`mode`	`blend`, `additive`, `stretch`	Режим смешивания изображения
`"src alpha"`	`0` или `1`	Использовать исходный альфа-канал
`stretch`	`0` или `1`	Растянуть изображение для заполнения виджета
`filter`	`0` или `1`	Включить фильтрацию текстур
`"flip u"`	`0` или `1`	Отразить изображение по горизонтали
`"flip v"`	`0` или `1`	Отразить изображение по вертикали
`"clamp mode"`	`clamp`, `wrap`	Поведение краёв текстуры
`"stretch mode"`	`stretch_w_h`, и т.д.	Режим растягивания

Атрибуты спейсеров

Применяются к WrapSpacerWidgetClass и GridSpacerWidgetClass.

Атрибут	Значения	Описание
`Padding`	целое число	Внутренний отступ в пикселях
`Margin`	целое число	Расстояние между дочерними элементами в пикселях
`"Size To Content H"`	`0` или `1`	Изменить ширину под содержимое
`"Size To Content V"`	`0` или `1`	Изменить высоту под содержимое
`content_halign`	`left`, `center`, `right`	Горизонтальное выравнивание содержимого
`content_valign`	`top`, `center`, `bottom`	Вертикальное выравнивание содержимого
`Columns`	целое число	Столбцы сетки (только GridSpacer)
`Rows`	целое число	Строки сетки (только GridSpacer)

Атрибуты кнопок

Атрибут	Значения	Описание
`switch`	`toggle`	Делает кнопку переключаемой (остаётся нажатой)
`style`	имя стиля	Визуальный стиль кнопки

Атрибуты ползунков

Атрибут	Значения	Описание
`"fill in"`	`0` или `1`	Показывать заполненную дорожку за ручкой ползунка
`"listen to input"`	`0` или `1`	Реагировать на ввод мыши

Атрибуты прокрутки

Атрибут	Значения	Описание
`"Scrollbar V"`	`0` или `1`	Показать вертикальную полосу прокрутки
`"Scrollbar H"`	`0` или `1`	Показать горизонтальную полосу прокрутки

Интеграция со скриптами

Атрибут `scriptclass`

Атрибут scriptclass привязывает виджет к классу Enforce Script. При загрузке макета движок создаёт экземпляр этого класса и вызывает его метод OnWidgetScriptInit(Widget w).

FrameWidgetClass MyPanel {
 size 1 1
 scriptclass "MyPanelHandler"
}

Класс скрипта должен наследовать от Managed и реализовать OnWidgetScriptInit:

class MyPanelHandler : Managed
{
    Widget m_Root;

    void OnWidgetScriptInit(Widget w)
    {
        m_Root = w;
    }
}

Блок ScriptParamsClass

Параметры могут быть переданы из макета в scriptclass через блок ScriptParamsClass. Этот блок появляется как второй дочерний блок { } после дочерних элементов виджета.

ImageWidgetClass Logo {
 image0 "set:dayz_gui image:DayZLogo"
 scriptclass "Bouncer"
 {
  ScriptParamsClass {
   amount 0.1
   speed 1
  }
 }
}

Класс скрипта считывает эти параметры в OnWidgetScriptInit, используя систему параметров скрипта виджета.

Привязка ViewBinding в DabsFramework

В модах, использующих DabsFramework MVC, паттерн scriptclass "ViewBinding" подключает виджеты к свойствам данных ViewController:

TextWidgetClass StatusLabel {
 scriptclass "ViewBinding"
 "text halign" center
 {
  ScriptParamsClass {
   Binding_Name "StatusText"
   Two_Way_Binding 0
  }
 }
}

Параметр	Описание
`Binding_Name`	Имя свойства ViewController для привязки
`Two_Way_Binding`	`1` = изменения UI передаются обратно в контроллер
`Relay_Command`	Имя функции контроллера для вызова при клике/изменении виджета
`Selected_Item`	Свойство для привязки выбранного элемента (для списков)
`Debug_Logging`	`1` = включить подробное логирование для этой привязки

Вложение дочерних элементов

Дочерние элементы помещаются внутри блока { } после атрибутов родителя. В одном блоке может быть несколько дочерних элементов.

FrameWidgetClass Parent {
 size 1 1
 {
  TextWidgetClass Child1 {
   position 0 0
   size 1 0.1
   text "First"
  }
  TextWidgetClass Child2 {
   position 0 0.1
   size 1 0.1
   text "Second"
  }
 }
}

Дочерние элементы всегда позиционируются относительно родителя. Дочерний с position 0 0 и size 1 1 (пропорционально) заполняет родителя полностью.

Полный аннотированный пример

Вот полностью аннотированный файл макета для панели уведомлений --- такого типа UI, который вы можете создать для мода:

// Корневой контейнер -- невидимый фрейм, занимающий 30% ширины экрана
// Центрирован по горизонтали, расположен вверху экрана
FrameWidgetClass NotificationPanel {

 // Начать скрытым (скрипт покажет его)
 visible 0

 // Не блокировать клики мыши по объектам за этой панелью
 ignorepointer 1

 // Синий оттенок (R=0.2, G=0.6, B=1.0, A=0.9)
 color 0.2 0.6 1.0 0.9

 // Позиция: 0 пикселей от левого, 0 пикселей от верхнего края
 position 0 0
 hexactpos 1
 vexactpos 1

 // Размер: 30% ширины родителя, 30 пикселей высотой
 size 0.3 30
 hexactsize 0
 vexactsize 1

 // Центрировать по горизонтали внутри родителя
 halign center_ref

 // Блок дочерних элементов
 {
  // Текстовая метка заполняет всю панель уведомлений
  TextWidgetClass NotificationText {

   // Также игнорировать ввод мыши
   ignorepointer 1

   // Позиция в начале координат относительно родителя
   position 0 0
   hexactpos 1
   vexactpos 1

   // Заполнить родителя полностью (пропорционально)
   size 1 1
   hexactsize 0
   vexactsize 0

   // Центрировать текст в обоих направлениях
   "text halign" center
   "text valign" center

   // Использовать жирный шрифт
   font "gui/fonts/Metron-Bold"

   // Текст по умолчанию (будет переопределён скриптом)
   text "Notification"
  }
 }
}

А вот более сложный пример --- диалог с заголовком, прокручиваемым содержимым и кнопкой закрытия:

WrapSpacerWidgetClass MyDialog {
 clipchildren 1
 color 0.7059 0.7059 0.7059 0.7843
 size 0.35 0
 halign center_ref
 valign center_ref
 priority 998
 style Outline_1px_BlackBackground
 Padding 5
 "Size To Content H" 1
 "Size To Content V" 1
 content_halign center
 {
  // Строка заголовка
  FrameWidgetClass TitleBarRow {
   size 1 26
   hexactsize 0
   vexactsize 1
   draggable 1
   {
    PanelWidgetClass TitleBar {
     color 0.4196 0.6471 1 0.9412
     size 1 25
     style rover_sim_colorable
     {
      TextWidgetClass TitleText {
       size 0.85 0.9
       text "My Dialog"
       font "gui/fonts/Metron"
       "text halign" center
       "text valign" center
      }
      ButtonWidgetClass CloseBtn {
       size 0.15 0.9
       halign right_ref
       text "X"
      }
     }
    }
   }
  }

  // Прокручиваемая область содержимого
  ScrollWidgetClass ContentScroll {
   size 0.97 235
   hexactsize 0
   vexactsize 1
   "Scrollbar V" 1
   {
    WrapSpacerWidgetClass ContentItems {
     size 1 0
     hexactsize 0
     "Size To Content V" 1
    }
   }
  }
 }
}

Распространённые ошибки

Забыт суффикс Class --- в макетах пишите TextWidgetClass, а не TextWidget.
Смешивание пропорциональных и пиксельных значений --- если hexactsize 0, значения размера 0.0-1.0 пропорциональны. Если hexactsize 1, они пиксельные. Использование 300 с пропорциональным режимом означает 300x ширины родителя.
Кавычки не заключены у многословных атрибутов --- пишите "text halign" center, а не text halign center.
Размещение ScriptParamsClass в неправильном блоке --- он должен быть в отдельном блоке { } после блока дочерних элементов, а не внутри него.

Следующие шаги

3.3 Размеры и позиционирование --- освойте систему пропорциональных и пиксельных координат
3.4 Виджеты-контейнеры --- подробный разбор виджетов-спейсеров и прокрутки

Глава 3.2: Формат файлов макетов (.layout) ​

Базовая структура ​

Справочник атрибутов ​

Позиционирование и размеры ​

Визуальные атрибуты ​

Поведенческие атрибуты ​

Текстовые атрибуты ​

Атрибуты изображения ​

Атрибуты спейсеров ​

Атрибуты кнопок ​

Атрибуты ползунков ​

Атрибуты прокрутки ​

Интеграция со скриптами ​

Атрибут scriptclass ​

Блок ScriptParamsClass ​

Привязка ViewBinding в DabsFramework ​

Вложение дочерних элементов ​

Полный аннотированный пример ​

Распространённые ошибки ​

Следующие шаги ​