Виджет - это один минимальный элемент интерфейса (панель, кнопка, текстовый элемент, поле ввода и т.п.). Есть несколько типов виджетов (описаны ниже), но их реализация всегда наследована от базового класса Widget, описанного на этой странице. Объекты базового класса Widget создавать нельзя.
Система виджетов - это система, занимающаяся визуализацией интерфейса и обработкой пользовательского ввода. Каждый виджет может быть представлен его ресурсом в ресурсной системе (файл xdb) и реальным экземпляром (с полями, методами и реакциями) во время работы программы.
Один виджет физически представлен на диске ресурсом этого виджета в виде xdb файла. Имя файла виджета имеет вид:
"<путь к аддону>\<Название виджета>.(тип виджета).xdb"
Экземпляр виджета создаётся на основе его файла ресурса (то есть ресурс - это не виджет, а шаблон будущего виджета).
Во время работы приложения ресурс представлен в виде описателя WidgetDesc
Экземпляр виджета представлен типом WidgetSafe (см. LuaApiTypes)
На поведение и отображение виджетов можно влиять, используя методы WidgetSafe, перечисленные в CategoryWidget
Во время работы приложения можно получить описатель WidgetDesc имеющегося виджета WidgetSafe, используя
Во время работы приложения можно получить WidgetSafe дочернего виджета, какого либо родительского виджета, используя
На основе одного ресурса может быть создано несколько физических виджетов (например элементы контейнера-списка) с помощью
Такой новый виджет надо добавить какому-либо родителю, используя
ВАЖНО! Такие динамически созданные виджеты необходимо удалять, когда необходимо, используя
DestroyWidget( self ), для предотвращения лишнего использования памяти.
У виджета можно определить несколько реакций (нажатие, наведение и т.п.) и реализовать в скрипте аддона обработчики этих реакций. См. ниже.
Существует несколько типов виджетов и соответствующих типов ресурсов:
WidgetButton - кнопка
WidgetEditLine - строка ввода
WidgetEditBox - многострочное поле ввода
WidgetForm - форма
WidgetPanel - панель
WidgetTextView - контрол для показа текстов
WidgetContainer - базовый скроллируемый контейнер и его реализации:
WidgetScrollableContainer - скроллируемый контейнер виджетов
WidgetTextContainer - скроллируемый контейнер текстов
WidgetScrollBar - базовый скроллбар для скроллируемых контейнеров и его реализации:
WidgetDiscreteScrollBar - дискретный скроллбар
WidgetGlideScrollBar - плавный скроллбар
WidgetSlider - базовый слайдер для скроллбара и его реализации
WidgetDiscreteSlider - дискретный слайдер
WidgetGlideSlider - плавный слайдер
WidgetControl3D - контрол для показа 3D-объектов
Все эти типы ресурсов наследуют, то есть содержат поля базового класса Widget. То есть, например, поле BackLayer есть и в WidgetPanel и в WidgetTextView. Также все типы виджетов могут посылать перечисленные ниже реакции.
Можно создавать только виджеты конкретных реализаций, перечисленные выше. То есть нельзя создать виджет типа Widget, WidgetContainer, WidgetScrollBar, WidgetSlider.
ВАЖНО! Названия полей чувствительны к регистру букв.
Существующие поля в базовом классе Widget:
Name: string - системное название виджета
Visible: boolean - виден ли виджет. По умолчанию true. если виджет не виден, то он недоступен и для реакций
Enabled: boolean - доступен ли виджет и все его дочерние виджеты для реакций. Может влиять на внешний вид (виджет "засеривается"). По умолчанию true
Priority: number (integer) - приоритет отображения (также влияет на обработку мышиных событий) виджета в списке виджетов своего родителя. То есть с помощью этого поля можно сформировать иерархию отображения виджетов всего аддона.
Placement: ["WidgetPlacementXY"] - описание расположение виджета.
Children: table of Widget - дочерние виджеты. Почти каждый виджет может содержать дочерние виджеты, за исключением особых случаев типа слайдера и т.п. Дочерние виджеты отображаются поверх родителя и перехватывают реакции (если они объявлены и на них подписаны обработчики) раньше родительского виджета за исключением особых случаев, оговоренных ниже.
clipContent: boolean - Нужно ли обрезать содержимое, включая дочерние виджеты, по границам данного. По умолчанию false
BackLayer, FrontLayer: WidgetLayer - слои для отображения какой-либо текстуры. Могут отсутствовать. BackLayer - нижний слой, FrontLayer - верхний слой.
textureMask: UISingleTexture - Текстура с альфой. Используется для задания маски, по которой будет обрезана основная текстура данного контрола и всех его детей
fade: number ([0.0f, 1.0f]) - визуальная прозрачность виджета. По умолчанию 1.0f - непрозрачен.
pickMask: UISingleTexture - черно-белая текстура (по степеням 2) для задания активной (белые пиксели) области для кликов мышью. Нужно вручную выставлять mipSW = 0 при экспорте
PickChildrenOnly - Обрабатывать мышиные реакции только для детей этого виджета, игнорируя сам виджет
forceWheel - Игнорировать PickChildrenOnly при скролировании колесом мыши и наведении. Всегда обрабатывать реакцию скролла колесом мыши
IgnoreDblClick - Игнорировать двойной клик мышью для виджета и для его детей
TransparentInput: boolean - является ли виджет прозрачным для ввода. По умолчанию false
isProtected: boolean - Запрещать ли пользовательским аддонам операции с виджетом. По умолчанию false. См. также AttachWidget2D.
TabOrder: number (integer) - задаёт порядок обхода контролов по клавише Tab. По умолчанию 0(не учавствует в обходе). Для участия в обходе значение должно быть больше 0.
soundShow, soundHide: WidgetSoundBase - звуки на показывание и скрытие виджета.
Для виджета можно объявить реакции, а потом подписать на них обработчики в скрипте аддона.
Для этого надо объявить реакцию (её имя) в файле ресурса виджета и подписаться на её обработчик (функцию Lua) в скрипте аддона, используя common.RegisterReactionHandler( reactionFunction, sysReactionName ).
В этом случае при возникновении события, инициирующего реакцию, в срипте будет вызван подписанный обработчик с параметрами params. См. OnReaction<ReactionName>( params ).
Реакции могут быть мышиные (нажатие, наведение и т.п.) и клавиатурные.
Клавиатурные реакции могут быть реализованы только для клавиш забаинденых в файле input.cfg. Для пользовательских аддонов клавиатурные реакции не предусмотренны. клавиатурные реакции объявляются только в WidgetForm и WidgetButton.
bindSections: table of BindSection - список реакций на клавиатурные нажатия. Поля:
bindSection: string - название секции
bindedReactions: table of string - список реакций
Чтобы обработать мышиное событие с помощью виджета, нужно объявить реакцию в соответствующем поле ресурса, а потом подписаться на реакцию в скрипте аддона с помощью common.RegisterReactionHandler( reactionFunction, sysReactionName ).
Возможные реакции для базового класса Widget:
reactionOnPointing: string - уведомление о наведении на виджет. (Кроме виджетов со специальной обработкой - кнопок и т.д.)
forceReactionOnPointing: string - уведомление о наведении на виджет вне зависимости от его доступности для кликов. (Использовать только при сильной необходимости - потребляет много ресурсов.)
reactionWheelUp: string - уведомление о прокрутке колёсика мыши вверх
reactionWheelDown: string - уведомление о прокрутке колёсика мыши вниз
Имеются методы (см. CategoryAllowedInReactions), которые можно использовать в пользовательских аддонах только в обработчиках мышиных кликов.
Некий виджет "MyWidget.(WidgetPanel).xdb":
При прокручивании колеса мыши над этим виджетом в скрипт аддона будут присылаться реакции "wheel_up" и "wheel_down", даже если курсор мыши будет в данный момент находиться над кликабельным дочерним виджетом "Slider.(WidgetButton).xdb".