Віджет - це один мінімальний елемент інтерфейсу (панель, кнопка, текстовий елемент, поле введення і т.п.). Є кілька типів віджетів (описані нижче), але їх реалізація завжди успадкованою від базового класу Widget, описаного на цій сторінці. Об'єкти базового класу Widget створювати не можна.
Система віджетів - це система, що займається візуалізацією інтерфейсу і обробкою користувальницького введення. Кожен віджет може бути представлений його ресурсом у ресурсній системі (файл xdb) і реальним екземпляром (з полями, методами і реакціями) під час роботи програми.
Один віджет фізично представлений на диску ресурсом цього віджета у вигляді xdb файлу. Файл віджета має вигляд:
"<путь к аддону>\<Название виджета>.(Тип віджета) .xdb "
Примірник віджета створюється на основі його файлу ресурсу (тобто ресурс - це не віджет, а шаблон майбутнього віджета).
Під час роботи програми ресурс представлений у вигляді описателя WidgetDesc
Примірник віджета представлений типом WidgetSafe (див. LuaApiTypes)
На поведінку і відображення віджетів можна впливати, використовуючи методи WidgetSafe, перераховані в CategoryWidget
Під час роботи програми можна отримати описувач WidgetDesc наявного віджета WidgetSafe, використовуючи
Під час роботи програми можна отримати WidgetSafe дочірнього віджета, будь-якого батьківського віджета, використовуючи
На основі одного ресурсу може бути створено кілька фізичних віджетів (наприклад елементи контейнера-списку) за допомогою
Такий новий віджет треба додати будь-якому батькові чи матері, використовуючи
ВАЖЛИВО! Такі динамічно створені віджети необхідно видаляти, коли необхідно, використовуючи
DestroyWidget (self). для запобігання зайвого використання пам'яті.
У віджета можна визначити кілька реакцій (натискання, наведення і т.п.) і реалізувати в скрипті аддона обробники цих реакцій. Див. нижче.
типи віджетів
Існує кілька типів віджетів і відповідних типів ресурсів:
Прості віджети:
WidgetEditLine - рядок введення
WidgetEditBox - многострочное поле введення
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
Для віджета можна оголосити реакції, а потім підписати на них обробники в скрипті аддона.
В цьому випадку при виникненні події, що ініціює реакцію, в сріпте буде викликаний підписаний обробник з параметрами params. Див. OnReaction
Реакції можуть бути мишачі (натискання, наведення і т.п.) і клавіатурні.
Клавіатурні реакції Widget
Клавіатурні реакції можуть бути реалізовані тільки для клавіш забаіндених в файлі input.cfg. Для призначених для користувача аддонів клавіатурні реакції не передбачені. клавіатурні реакції оголошуються тільки в WidgetForm і WidgetButton.
bindSections: table of BindSection - список реакцій на клавіатурні натискання. поля:
bindSection: string - назва секції
bindedReactions: table of string - список реакцій
Мишачі реакції Widget
Можливі реакції для базового класу Widget:
reactionOnPointing: string - повідомлення про наведення на віджет. (Крім віджетів зі спеціальною обробкою - кнопок і т.д.)
forceReactionOnPointing: string - повідомлення про наведення на віджет незалежно від його доступності для кліків. (Використовувати тільки при сильній необхідності - споживає багато ресурсів.)
reactionWheelUp: string - повідомлення про прокрутку коліщатка миші вгору
reactionWheelDown: string - повідомлення про прокрутку коліщатка миші вниз
Є методи (див. CategoryAllowedInReactions), які можна використовувати в призначених для користувача аддонах тільки в обробниках мишачих кліків.
Якийсь віджет "MyWidget. (WidgetPanel) .xdb":
При прокручуванні колеса миші над цим віджетом в скрипт аддона будуть надсилатися реакції "wheel_up" і "wheel_down", навіть якщо курсор миші буде в даний момент знаходитися над клікабельним дочірнім віджетом "Slider. (WidgetButton) .xdb".