# Пользовательские дополнения

На главную

## Widget. Описание виджета.

## Виджет

Виджет - это один минимальный элемент интерфейса (панель, кнопка, текстовый элемент, поле ввода и т.п.). Есть несколько типов виджетов (описаны ниже), но их реализация всегда наследована от базового класса Widget, описанного на этой странице. Объекты базового класса Widget создавать нельзя.

Система виджетов - это система, занимающаяся визуализацией интерфейса и обработкой пользовательского ввода. Каждый виджет может быть представлен его ресурсом в ресурсной системе (файл xdb) и реальным экземпляром (с полями, методами и реакциями) во время работы программы.

- Один виджет физически представлен на диске ресурсом этого виджета в виде xdb файла. Имя файла виджета имеет вид:

- "<путь к аддону>\<Название виджета>.(тип виджета).xdb"

- Экземпляр виджета создаётся на основе его файла ресурса (то есть ресурс - это не виджет, а шаблон будущего виджета).

- Во время работы приложения ресурс представлен в виде описателя WidgetDesc

- Экземпляр виджета представлен типом WidgetSafe (см. LuaApiTypes)

- На поведение и отображение виджетов можно влиять, используя методы WidgetSafe, перечисленные в CategoryWidget

- Во время работы приложения можно получить описатель WidgetDesc имеющегося виджета WidgetSafe, используя

- GetWidgetDesc( self )

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

- GetChildChecked( self, name, recursive )

- GetChildUnchecked( self, name, recursive )

- GetNamedChildren( self )

- На основе одного ресурса может быть создано несколько физических виджетов (например элементы контейнера-списка) с помощью

- CreateWidgetByDesc( self, widgetDesc )

- Такой новый виджет надо добавить какому-либо родителю, используя

- AddChild( self, widget )

- ВАЖНО! Такие динамически созданные виджеты необходимо удалять, когда необходимо, используя

- 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

ВАЖНО! Названия полей чувствительны к регистру букв.

Существующие поля в базовом классе 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 - звуки на показывание и скрытие виджета.

## Реакции Widget

Для виджета можно объявить реакции, а потом подписать на них обработчики в скрипте аддона.

Для этого надо объявить реакцию (её имя) в файле ресурса виджета и подписаться на её обработчик (функцию Lua) в скрипте аддона, используя common.RegisterReactionHandler( reactionFunction, sysReactionName ).

В этом случае при возникновении события, инициирующего реакцию, в срипте будет вызван подписанный обработчик с параметрами params. См. OnReaction<ReactionName>( params ).

Реакции могут быть мышиные (нажатие, наведение и т.п.) и клавиатурные.

### Клавиатурные реакции Widget

Клавиатурные реакции могут быть реализованы только для клавиш забаинденых в файле input.cfg. Для пользовательских аддонов клавиатурные реакции не предусмотренны. клавиатурные реакции объявляются только в WidgetForm и WidgetButton.

- bindSections: table of BindSection - список реакций на клавиатурные нажатия. Поля:

- bindSection: string - название секции

- bindedReactions: table of string - список реакций

### Мышиные реакции Widget

Чтобы обработать мышиное событие с помощью виджета, нужно объявить реакцию в соответствующем поле ресурса, а потом подписаться на реакцию в скрипте аддона с помощью common.RegisterReactionHandler( reactionFunction, sysReactionName ).

Возможные реакции для базового класса Widget:

- reactionOnPointing: string - уведомление о наведении на виджет. (Кроме виджетов со специальной обработкой - кнопок и т.д.)

- forceReactionOnPointing: string - уведомление о наведении на виджет вне зависимости от его доступности для кликов. (Использовать только при сильной необходимости - потребляет много ресурсов.)

- reactionWheelUp: string - уведомление о прокрутке колёсика мыши вверх

- reactionWheelDown: string - уведомление о прокрутке колёсика мыши вниз

Имеются методы (см. CategoryAllowedInReactions), которые можно использовать в пользовательских аддонах только в обработчиках мышиных кликов.

## Пример

Некий виджет "MyWidget.(WidgetPanel).xdb":

При прокручивании колеса мыши над этим виджетом в скрипт аддона будут присылаться реакции "wheel_up" и "wheel_down", даже если курсор мыши будет в данный момент находиться над кликабельным дочерним виджетом "Slider.(WidgetButton).xdb".

#### Связанные страницы: "CategoryLuaApi" "CategoryWidgetMembers"

CategoryWidgetMembers
TextFileRef
Widget
WidgetButton
WidgetButtonState
WidgetButtonVariant
WidgetContainer
WidgetDiscreteScrollBar
WidgetDiscreteSlider
WidgetEditBase
WidgetEditBox
WidgetEditLine
WidgetForm
WidgetGlideScrollBar
WidgetGlideSlider
WidgetLayer
WidgetPanel
WidgetPlacementXY
WidgetsArrangement
WidgetScrollableContainer
WidgetScrollBar
WidgetSlider
WidgetTextContainer
WidgetTextStyle
WidgetTextView

#### Связанные страницы: "CategoryLuaApi" "CategoryWidget"

CategoryButton
CategoryControl3D
CategoryDiscreteSlider
CategoryEditBase
CategoryEditBox
CategoryEditLine
CategoryForm
CategoryPanel
CategoryScrollableContainer
CategorySimpleTable
CategoryTextContainer
CategoryTextView
CategoryWidget
CategoryWidgetEffects
EnumAlignX
EnumAlignY
EnumColorType
EnumKeyboardFlags
EnumMouseButton
EventEffectFinished
EventUpdateShrinkRatio
EventValuedObjectClicked
EventValuedObjectDoubleClicked
EventValuedObjectMouseOver
EventWidgetShowChanged
FunctionFormCreateWidgetByDesc
FunctionTextContainerInsertText
FunctionTextContainerPushBackRawText
FunctionTextContainerPushBackValuedText
FunctionTextContainerPushFrontRawText
FunctionTextContainerPushFrontValuedText
FunctionTextViewFinishTextScaleEffect
FunctionTextViewPlayTextScaleEffect
FunctionWidgetAddChild
FunctionWidgetDestroyWidget
FunctionWidgetEnable
FunctionWidgetFinishFadeEffect
FunctionWidgetFinishMoveEffect
FunctionWidgetFinishResizeEffect
FunctionWidgetGetAddonType
FunctionWidgetGetBackgroundColor
FunctionWidgetGetChildChecked
FunctionWidgetGetChildUnchecked
FunctionWidgetGetFade
FunctionWidgetGetForegroundColor
FunctionWidgetGetName
FunctionWidgetGetNamedChildren
FunctionWidgetGetParent
FunctionWidgetGetPlacementPlain
FunctionWidgetGetPriority
FunctionWidgetGetRealRect
FunctionWidgetGetTransparentInput
FunctionWidgetGetWidgetDesc
FunctionWidgetIsClipContent
FunctionWidgetIsEnabled
FunctionWidgetIsFocused
FunctionWidgetIsValid
FunctionWidgetIsVisible
FunctionWidgetIsVisibleEx
FunctionWidgetPlayFadeEffect
FunctionWidgetPlayMoveEffect
FunctionWidgetPlayResizeEffect
FunctionWidgetSetBackgroundBlendEffect
FunctionWidgetSetBackgroundClearMaskEffect
FunctionWidgetSetBackgroundColor
FunctionWidgetSetBackgroundTexture
FunctionWidgetSetClipContent
FunctionWidgetSetFade
FunctionWidgetSetFocus
FunctionWidgetSetForegroundBlendEffect
FunctionWidgetSetForegroundClearMaskEffect
FunctionWidgetSetForegroundColor
FunctionWidgetSetForegroundTexture
FunctionWidgetSetName
FunctionWidgetSetOnShowNotification
FunctionWidgetSetPlacementPlain
FunctionWidgetSetPriority
FunctionWidgetSetTransparentInput
FunctionWidgetShow
TypeWidgetDesc
Widget
WidgetControlDescription
WidgetsEffectsAlgorithms
WidgetsEffectsTypes

CategoryLuaApi CategoryWidget CategoryWidgetMembers

На главную