Глава 3.1: Типы виджетов

Главная | Типы виджетов | Далее: Файлы Layout >>

---

Система GUI в DayZ построена на виджетах — переиспользуемых UI-компонентах, начиная от простых контейнеров и заканчивая сложными интерактивными элементами управления. Каждый видимый элемент на экране — это виджет, и знание полного каталога необходимо для создания UI модов.

Эта глава содержит полный справочник по всем типам виджетов, доступным в Enforce Script.

---

Как работают виджеты

Каждый виджет в DayZ наследует от базового класса Widget. Виджеты организованы в дерево «родитель-потомок», где корнем обычно является WorkspaceWidget, получаемый через GetGame().GetWorkspace().

У каждого типа виджета есть три связанных идентификатора:

Идентификатор	Пример	Используется для
Класс скрипта	TextWidget	Ссылки в коде, приведение типов
Класс layout	TextWidgetClass	Объявления в файлах .layout
Константа TypeID	TextWidgetTypeID	Программное создание через CreateWidget()

В файлах .layout всегда используется имя класса layout (заканчивающееся на Class). В скриптах вы работаете с именем класса скрипта.

---

Виджеты-контейнеры / Компоновка

Виджеты-контейнеры содержат и организуют дочерние виджеты. Они сами не отображают контент (за исключением PanelWidget, который рисует цветной прямоугольник).

Класс скрипта	Класс Layout	Назначение
Widget	WidgetClass	Абстрактный базовый класс для всех виджетов. Никогда не создавайте экземпляр напрямую.
WorkspaceWidget	WorkspaceWidgetClass	Корневое рабочее пространство. Получается через GetGame().GetWorkspace(). Используется для программного создания виджетов.
FrameWidget	FrameWidgetClass	Универсальный контейнер. Самый часто используемый виджет в DayZ.
PanelWidget	PanelWidgetClass	Цветной прямоугольник. Используйте для фонов, разделителей, разграничителей.
WrapSpacerWidget	WrapSpacerWidgetClass	Поточная компоновка. Располагает дочерние элементы последовательно с переносом, отступами и полями.
GridSpacerWidget	GridSpacerWidgetClass	Сеточная компоновка. Располагает дочерние элементы в сетке, определяемой Columns и Rows.
ScrollWidget	ScrollWidgetClass	Прокручиваемая область. Включает вертикальную/горизонтальную прокрутку дочернего контента.
SpacerBaseWidget	--	Абстрактный базовый класс для WrapSpacerWidget и GridSpacerWidget.

FrameWidget

Рабочая лошадка UI DayZ. Используйте FrameWidget как контейнер по умолчанию, когда нужно сгруппировать виджеты. Он не имеет визуального представления — он чисто структурный.

Ключевые методы:

• Все базовые методы Widget (позиция, размер, цвет, дочерние элементы, флаги)

Когда использовать: Практически везде. Оборачивайте группы связанных виджетов. Используйте как корень диалогов, панелей и элементов HUD.

// Найти frame-виджет по имени
FrameWidget panel = FrameWidget.Cast(root.FindAnyWidget("MyPanel"));
panel.Show(true);

PanelWidget

Видимый прямоугольник с заливкой цветом. В отличие от FrameWidget, PanelWidget действительно отображает что-то на экране.

Ключевые методы:

• SetColor(int argb) — Установить цвет фона
• SetAlpha(float alpha) — Установить прозрачность

Когда использовать: Фон за текстом, цветные разделители, прямоугольники наложения, тонирующие слои.

PanelWidget bg = PanelWidget.Cast(root.FindAnyWidget("Background"));
bg.SetColor(ARGB(200, 0, 0, 0));  // Полупрозрачный чёрный

WrapSpacerWidget

Автоматически располагает дочерние элементы в поточной компоновке. Дочерние элементы размещаются один за другим с переносом на следующую строку, когда место заканчивается.

Ключевые атрибуты компоновки:

• Padding — Внутренние отступы (пиксели)
• Margin — Внешние отступы (пиксели)
• "Size To Content H" 1 — Изменить ширину под содержимое
• "Size To Content V" 1 — Изменить высоту под содержимое
• content_halign — Горизонтальное выравнивание содержимого (left, center, right)
• content_valign — Вертикальное выравнивание содержимого (top, center, bottom)

Когда использовать: Динамические списки, облака тегов, ряды кнопок, любая компоновка с элементами разного размера.

GridSpacerWidget

Располагает дочерние элементы в фиксированной сетке. Каждая ячейка имеет одинаковый размер.

Ключевые атрибуты компоновки:

• Columns — Количество столбцов
• Rows — Количество строк
• Margin — Расстояние между ячейками
• "Size To Content V" 1 — Изменить высоту под содержимое

Когда использовать: Сетки инвентаря, галереи иконок, панели настроек с однородными строками.

ScrollWidget

Обеспечивает прокручиваемую область для контента, превышающего видимую область.

Ключевые атрибуты компоновки:

• "Scrollbar V" 1 — Включить вертикальную полосу прокрутки
• "Scrollbar H" 1 — Включить горизонтальную полосу прокрутки

Ключевые методы:

• VScrollToPos(float pos) — Прокрутить до вертикальной позиции
• GetVScrollPos() — Получить текущую позицию вертикальной прокрутки
• GetContentHeight() — Получить полную высоту содержимого
• VScrollStep(int step) — Прокрутить на величину шага

Когда использовать: Длинные списки, панели конфигурации, окна чата, просмотрщики логов.

---

Виджеты отображения

Виджеты отображения показывают контент пользователю, но не являются интерактивными.

Класс скрипта	Класс Layout	Назначение
TextWidget	TextWidgetClass	Однострочное отображение текста
MultilineTextWidget	MultilineTextWidgetClass	Многострочный текст только для чтения
RichTextWidget	RichTextWidgetClass	Текст со встроенными изображениями (теги <image>)
ImageWidget	ImageWidgetClass	Отображение изображений (из imageset-ов или файлов)
CanvasWidget	CanvasWidgetClass	Программируемая поверхность рисования
VideoWidget	VideoWidgetClass	Воспроизведение видеофайлов
RTTextureWidget	RTTextureWidgetClass	Поверхность рендера в текстуру
RenderTargetWidget	RenderTargetWidgetClass	Цель рендера 3D-сцены
ItemPreviewWidget	ItemPreviewWidgetClass	3D-превью предмета DayZ
PlayerPreviewWidget	PlayerPreviewWidgetClass	3D-превью модели персонажа
MapWidget	MapWidgetClass	Интерактивная карта мира

TextWidget

Самый распространённый виджет отображения. Показывает одну строку текста.

Ключевые методы:

TextWidget tw;
tw.SetText("Hello World");
tw.GetText();                           // Возвращает string
tw.GetTextSize(out int w, out int h);   // Размеры отрисованного текста в пикселях
tw.SetTextExactSize(float size);        // Установить размер шрифта в пикселях
tw.SetOutline(int size, int color);     // Добавить обводку текста
tw.GetOutlineSize();                    // Возвращает int
tw.GetOutlineColor();                   // Возвращает int (ARGB)
tw.SetColor(int argb);                  // Цвет текста

Ключевые атрибуты layout: text, font, "text halign", "text valign", "exact text", "exact text size", "bold text", "size to text h", "size to text v", wrap.

MultilineTextWidget

Отображает несколько строк текста только для чтения. Текст автоматически переносится по ширине виджета.

Когда использовать: Панели описания, текст справки, отображение логов.

RichTextWidget

Поддерживает встроенные изображения внутри текста с помощью тегов <image>. Также поддерживает перенос текста.

Ключевые атрибуты layout:

• wrap 1 — Включить перенос слов

Использование в тексте:

"Health: <image set:dayz_gui image:iconHealth0 /> OK"

Когда использовать: Текст со статусом и иконками, форматированные сообщения, чат со встроенными изображениями.

ImageWidget

Отображает изображения из imageset-ов (атласов спрайтов) или загруженные из файлов.

Ключевые методы:

ImageWidget iw;
iw.SetImage(int index);                    // Переключение между image0, image1 и т.д.
iw.LoadImageFile(int slot, string path);   // Загрузить изображение из файла
iw.LoadMaskTexture(string path);           // Загрузить текстуру маски
iw.SetMaskProgress(float progress);        // 0-1 для переходов стирания/раскрытия

Ключевые атрибуты layout:

• image0 "set:dayz_gui image:icon_refresh" — Изображение из imageset-а
• mode blend — Режим смешивания (blend, additive, stretch)
• "src alpha" 1 — Использовать альфа-канал исходника
• stretch 1 — Растянуть изображение для заполнения виджета
• "flip u" 1 — Отразить горизонтально
• "flip v" 1 — Отразить вертикально

Когда использовать: Иконки, логотипы, фоны, маркеры на карте, индикаторы состояния.

CanvasWidget

Поверхность для рисования, где можно программно отрисовывать линии.

Ключевые методы:

CanvasWidget cw;
cw.DrawLine(float x1, float y1, float x2, float y2, float width, int color);
cw.Clear();

Когда использовать: Пользовательские графики, линии связи между узлами, отладочные оверлеи.

MapWidget

Полная интерактивная карта мира. Поддерживает панорамирование, масштабирование и преобразование координат.

Ключевые методы:

MapWidget mw;
mw.SetMapPos(vector pos);              // Центрировать на мировой позиции
mw.GetMapPos();                        // Текущая центральная позиция
mw.SetScale(float scale);             // Уровень масштабирования
mw.GetScale();                        // Текущий масштаб
mw.MapToScreen(vector world_pos);     // Мировые координаты в экранные
mw.ScreenToMap(vector screen_pos);    // Экранные координаты в мировые

Когда использовать: Карты миссий, GPS-системы, выбор локаций.

ItemPreviewWidget

Отрисовывает 3D-превью любого предмета инвентаря DayZ.

Когда использовать: Экраны инвентаря, превью лута, интерфейсы магазинов.

PlayerPreviewWidget

Отрисовывает 3D-превью модели персонажа игрока.

Когда использовать: Экраны создания персонажа, превью экипировки, системы гардероба.

RTTextureWidget

Отрисовывает своих потомков в поверхность текстуры, а не напрямую на экран.

Когда использовать: Рендер мини-карты, эффекты «картинка в картинке», компоновка UI вне экрана.

---

Интерактивные виджеты

Интерактивные виджеты реагируют на пользовательский ввод и генерируют события.

Класс скрипта	Класс Layout	Назначение
ButtonWidget	ButtonWidgetClass	Нажимаемая кнопка
CheckBoxWidget	CheckBoxWidgetClass	Булевый флажок
EditBoxWidget	EditBoxWidgetClass	Однострочный ввод текста
MultilineEditBoxWidget	MultilineEditBoxWidgetClass	Многострочный ввод текста
PasswordEditBoxWidget	PasswordEditBoxWidgetClass	Маскированный ввод пароля
SliderWidget	SliderWidgetClass	Горизонтальный ползунок
XComboBoxWidget	XComboBoxWidgetClass	Выпадающий список выбора
TextListboxWidget	TextListboxWidgetClass	Список с выбираемыми строками
ProgressBarWidget	ProgressBarWidgetClass	Индикатор прогресса
SimpleProgressBarWidget	SimpleProgressBarWidgetClass	Минимальный индикатор прогресса

ButtonWidget

Основной интерактивный элемент управления. Поддерживает как мгновенное нажатие, так и режим переключения.

Ключевые методы:

ButtonWidget bw;
bw.SetText("Click Me");
bw.GetState();              // Возвращает bool (только для кнопок-переключателей)
bw.SetState(bool state);    // Установить состояние переключения

Ключевые атрибуты layout:

• text "Label" — Текст метки кнопки
• switch toggle — Сделать кнопку переключателем
• style Default — Визуальный стиль

Генерируемые события: OnClick(Widget w, int x, int y, int button)

CheckBoxWidget

Булевый элемент управления переключением.

Ключевые методы:

CheckBoxWidget cb;
cb.IsChecked();                 // Возвращает bool
cb.SetChecked(bool checked);    // Установить состояние

Генерируемые события: OnChange(Widget w, int x, int y, bool finished)

EditBoxWidget

Однострочное поле ввода текста.

Ключевые методы:

EditBoxWidget eb;
eb.GetText();               // Возвращает string
eb.SetText("default");      // Установить текст

Генерируемые события: OnChange(Widget w, int x, int y, bool finished) — finished равен true, когда нажат Enter.

SliderWidget

Горизонтальный ползунок для числовых значений.

Ключевые методы:

SliderWidget sw;
sw.GetCurrent();            // Возвращает float (0-1)
sw.SetCurrent(float val);   // Установить позицию

Ключевые атрибуты layout:

• "fill in" 1 — Показать заполненную дорожку за ручкой
• "listen to input" 1 — Реагировать на ввод мышью

Генерируемые события: OnChange(Widget w, int x, int y, bool finished) — finished равен true, когда пользователь отпускает ползунок.

XComboBoxWidget

Выпадающий список выбора.

Ключевые методы:

XComboBoxWidget xcb;
xcb.AddItem("Option A");
xcb.AddItem("Option B");
xcb.SetCurrentItem(0);         // Выбрать по индексу
xcb.GetCurrentItem();          // Возвращает выбранный индекс
xcb.ClearAll();                // Удалить все элементы

TextListboxWidget

Прокручиваемый список текстовых строк. Поддерживает выбор и многоколоночные данные.

Ключевые методы:

TextListboxWidget tlb;
tlb.AddItem("Row text", null, 0);   // текст, userData, столбец
tlb.GetSelectedRow();               // Возвращает int (-1 если ничего не выбрано)
tlb.SetRow(int row);                // Выбрать строку
tlb.RemoveRow(int row);
tlb.ClearItems();

Генерируемые события: OnItemSelected

ProgressBarWidget

Отображает индикатор прогресса.

Ключевые методы:

ProgressBarWidget pb;
pb.SetCurrent(float value);    // 0-100

Когда использовать: Полосы загрузки, полосы здоровья, прогресс миссии, индикаторы перезарядки.

---

Полный справочник TypeID

Используйте эти константы с GetGame().GetWorkspace().CreateWidget() для программного создания виджетов:

FrameWidgetTypeID
TextWidgetTypeID
MultilineTextWidgetTypeID
MultilineEditBoxWidgetTypeID
RichTextWidgetTypeID
RenderTargetWidgetTypeID
ImageWidgetTypeID
VideoWidgetTypeID
RTTextureWidgetTypeID
ButtonWidgetTypeID
CheckBoxWidgetTypeID
SimpleProgressBarWidgetTypeID
ProgressBarWidgetTypeID
SliderWidgetTypeID
TextListboxWidgetTypeID
EditBoxWidgetTypeID
PasswordEditBoxWidgetTypeID
WorkspaceWidgetTypeID
GridSpacerWidgetTypeID
WrapSpacerWidgetTypeID
ScrollWidgetTypeID

---

Выбор правильного виджета

Мне нужно...	Используйте этот виджет
Сгруппировать виджеты (невидимо)	FrameWidget
Нарисовать цветной прямоугольник	PanelWidget
Показать текст	TextWidget
Показать многострочный текст	MultilineTextWidget или RichTextWidget с wrap 1
Показать текст со встроенными иконками	RichTextWidget
Отобразить изображение/иконку	ImageWidget
Создать нажимаемую кнопку	ButtonWidget
Создать переключатель (вкл/выкл)	CheckBoxWidget или ButtonWidget с switch toggle
Принять текстовый ввод	EditBoxWidget
Принять многострочный текстовый ввод	MultilineEditBoxWidget
Принять пароль	PasswordEditBoxWidget
Позволить пользователю выбрать число	SliderWidget
Позволить пользователю выбрать из списка	XComboBoxWidget (выпадающий) или TextListboxWidget (видимый список)
Показать прогресс	ProgressBarWidget или SimpleProgressBarWidget
Расположить дочерние элементы потоком	WrapSpacerWidget
Расположить дочерние элементы в сетке	GridSpacerWidget
Сделать контент прокручиваемым	ScrollWidget
Показать 3D-модель предмета	ItemPreviewWidget
Показать модель игрока	PlayerPreviewWidget
Показать карту мира	MapWidget
Рисовать пользовательские линии/фигуры	CanvasWidget
Рендерить в текстуру	RTTextureWidget

---

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

• 3.2 Формат файлов Layout — Узнайте, как определять деревья виджетов в файлах .layout
• 3.5 Программное создание виджетов — Создание виджетов из кода вместо файлов layout

---

Лучшие практики

• Используйте FrameWidget как контейнер по умолчанию. Используйте PanelWidget только когда нужен видимый цветной фон.
• Предпочитайте RichTextWidget вместо TextWidget, если в будущем могут понадобиться встроенные иконки — смена типов в существующем layout утомительна.
• Всегда проверяйте на null после FindAnyWidget() и Cast(). Отсутствующие имена виджетов тихо возвращают null и вызывают крэши при следующем вызове метода.
• Используйте WrapSpacerWidget для динамических списков и GridSpacerWidget для фиксированных сеток. Не позиционируйте дочерние элементы вручную в поточной компоновке.
• Избегайте CanvasWidget для продакшн UI — он перерисовывается каждый кадр и не имеет батчинга. Используйте его только для отладочных оверлеев.

---

Теория и практика

Концепция	Теория	Реальность
ScrollWidget автоматически прокручивается к контенту	Полоса прокрутки появляется, когда контент превышает границы	Вы должны вызывать VScrollToPos() вручную для прокрутки к новому контенту; виджет не прокручивается автоматически при добавлении дочерних элементов
SliderWidget генерирует непрерывные события	OnChange вызывается на каждый пиксель перетаскивания	Параметр finished равен false во время перетаскивания и true при отпускании; обновляйте тяжёлую логику только при finished == true
XComboBoxWidget поддерживает много элементов	Выпадающий список работает с любым количеством	Производительность заметно падает при 100+ элементах; используйте TextListboxWidget для длинных списков
ItemPreviewWidget показывает любой предмет	Передайте любое classname для 3D-превью	Виджету нужна загруженная .p3d модель предмета; для моддированных предметов должен присутствовать их Data PBO
MapWidget — простое отображение	Просто показывает карту	Он перехватывает весь ввод мыши по умолчанию; вы должны аккуратно управлять флагами IGNOREPOINTER, иначе он блокирует клики по перекрывающимся виджетам

---

Совместимость и влияние

• Мультимод: TypeID виджетов — это константы движка, общие для всех модов. Два мода, создающие виджеты с одинаковым именем под одним родителем, столкнутся. Используйте уникальные имена виджетов с префиксом вашего мода.
• Производительность: TextListboxWidget и ScrollWidget с сотнями дочерних элементов вызывают просадки кадров. Используйте пулинг и переиспользование виджетов для списков, превышающих 50 элементов.