add doc/*/scripting/ui.md
This commit is contained in:
MihailRis
@@ -6,6 +6,7 @@ Subsections:
|
|||||||
- [Engine events](scripting/events.md)
|
- [Engine events](scripting/events.md)
|
||||||
- [User input](scripting/user-input.md)
|
- [User input](scripting/user-input.md)
|
||||||
- [Filesystem and serialization](scripting/filesystem.md)
|
- [Filesystem and serialization](scripting/filesystem.md)
|
||||||
|
- [UI properties and methods](scripting/ui.md)
|
||||||
- [Module core:bit_converter](scripting/modules/core_bit_converter.md)
|
- [Module core:bit_converter](scripting/modules/core_bit_converter.md)
|
||||||
- [Module core:data_buffer](scripting/modules/core_data_buffer.md)
|
- [Module core:data_buffer](scripting/modules/core_data_buffer.md)
|
||||||
- [Module core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)
|
- [Module core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)
|
||||||
|
|||||||
@@ -0,0 +1,154 @@
|
|||||||
|
# UI properties and methods
|
||||||
|
|
||||||
|
UI elements in scripts are accessed through a Document instance
|
||||||
|
(*document* variable) by id specified in xml.
|
||||||
|
|
||||||
|
Example: print the pos property of an element with id: "worlds-panel" to the console:
|
||||||
|
```lua
|
||||||
|
print(document["worlds-panel"].pos)
|
||||||
|
-- or
|
||||||
|
local worldsPanel = document["worlds-panel"]
|
||||||
|
print(worldsPanel.pos)
|
||||||
|
```
|
||||||
|
|
||||||
|
The IDs of the elements are global for the document, that is, *worlds-panel* can be located either in the root element,
|
||||||
|
and in a nested container.
|
||||||
|
|
||||||
|
The element id cannot be changed from a script.
|
||||||
|
|
||||||
|
The following tables will use abbreviated type descriptions, such as:
|
||||||
|
- vec2 - an array of two numbers.
|
||||||
|
- ivec2 - an array of two integers.
|
||||||
|
- rgba - an array of four integers in the range *\[0..255\]* denoting RGBA constituent colors.
|
||||||
|
|
||||||
|
Element methods, according to OOP features in Lua, are called using the `:` operator instead of `.`
|
||||||
|
|
||||||
|
For example:
|
||||||
|
```lua
|
||||||
|
document["worlds-panel"]:clear()
|
||||||
|
```
|
||||||
|
|
||||||
|
## General properties and methods
|
||||||
|
|
||||||
|
Properties that apply to all elements:
|
||||||
|
|
||||||
|
| Title | Type | Reading | Record | Description |
|
||||||
|
| ------------ | ------ | ------- | ------ | ------------------------------------------- |
|
||||||
|
| id | string | yes | *no* | element id |
|
||||||
|
| pos | vec2 | yes | yes | element position inside a container |
|
||||||
|
| wpos | vec2 | yes | yes | element position inside the window |
|
||||||
|
| size | vec2 | yes | yes | element size |
|
||||||
|
| interactive | bool | yes | yes | ability to interact with the element |
|
||||||
|
| enabled | bool | yes | yes | visually indicated version of *interactive* |
|
||||||
|
| visible | bool | yes | yes | element visibility |
|
||||||
|
| focused | bool | yes | yes | focus on element |
|
||||||
|
| color | rgba | yes | yes | element color |
|
||||||
|
| hoverColor | rgba | yes | yes | hover color |
|
||||||
|
| pressedColor | rgba | yes | yes | color when pressed |
|
||||||
|
| tooltip | string | yes | yes | tooltip text |
|
||||||
|
| tooltipDelay | float | yes | yes | tooltip delay |
|
||||||
|
|
||||||
|
Common element methods:
|
||||||
|
|
||||||
|
| Method | Description |
|
||||||
|
| ------------------- | ----------------------------------------------------------------------- |
|
||||||
|
| moveInto(container) | moves the element to the specified container (the element is specified, not the id) |
|
||||||
|
| destruct() | removes element |
|
||||||
|
|
||||||
|
## Containers
|
||||||
|
|
||||||
|
Common methods for containers (elements: container, panel, button, pagebox):
|
||||||
|
|
||||||
|
| Method | Description |
|
||||||
|
| ------------------------------- | ------------------------------------------------------------------ |
|
||||||
|
| clear() | clears content |
|
||||||
|
| add(xml) | adds an element, creating it using xml code. Example: `container:add("<image src='test'/>")` |
|
||||||
|
| setInterval(interval, callback) | assigns a function to be executed repeatedly at an interval specified in milliseconds |
|
||||||
|
|
||||||
|
## Textbox
|
||||||
|
|
||||||
|
Properties:
|
||||||
|
|
||||||
|
| Title | Type | Reading | Record | Description |
|
||||||
|
| ----------- | ------ | ------- | ------ | ------------------------------------------------------------------------------------ |
|
||||||
|
| text | string | yes | yes | entered text or placeholder |
|
||||||
|
| placeholder | string | yes | yes | placeholder (used if nothing has been entered) |
|
||||||
|
| caret | int | yes | yes | carriage position. `textbox.caret = -1` will set the position to the end of the text |
|
||||||
|
| editable | bool | yes | yes | text mutability |
|
||||||
|
| multiline | bool | yes | yes | multiline support |
|
||||||
|
| textWrap | bool | yes | yes | automatic text wrapping (only with multiline: "true") |
|
||||||
|
| valid | bool | yes | no | is the entered text correct |
|
||||||
|
|
||||||
|
Methods:
|
||||||
|
|
||||||
|
| Method | Description |
|
||||||
|
| ----------- | -------------------------------------------- |
|
||||||
|
| paste(text) | inserts the specified text at the caret position |
|
||||||
|
|
||||||
|
## Slider (trackbar)
|
||||||
|
|
||||||
|
Properties:
|
||||||
|
|
||||||
|
| Title | Type | Reading | Record | Description |
|
||||||
|
| ---------- | ----- | ------- | ------ | --------------------- |
|
||||||
|
| value | float | yes | yes | current value |
|
||||||
|
| min | float | yes | yes | minimum value |
|
||||||
|
| max | float | yes | yes | maximum value |
|
||||||
|
| step | float | yes | yes | division step |
|
||||||
|
| trackWidth | float | yes | yes | control element width |
|
||||||
|
| trackColor | rgba | yes | yes | control element color |
|
||||||
|
|
||||||
|
## Menu (pagebox)
|
||||||
|
|
||||||
|
Properties:
|
||||||
|
|
||||||
|
| Title | Type | Reading | Record | Description |
|
||||||
|
| -------- | ------ | ------ | ------ | ---------------- |
|
||||||
|
| page | string | yes | yes | current page |
|
||||||
|
|
||||||
|
Methods:
|
||||||
|
|
||||||
|
| Method | Description |
|
||||||
|
| ------- | ------------------------------------------ |
|
||||||
|
| back() | switches to previous page |
|
||||||
|
| reset() | resets page and switching history |
|
||||||
|
|
||||||
|
## Checkbox
|
||||||
|
|
||||||
|
Properties:
|
||||||
|
|
||||||
|
| Title | Type | Reading | Record | Description |
|
||||||
|
| -------- | ---- | ------ | ------ | ----------------- |
|
||||||
|
| checked | bool | yes | yes | mark status |
|
||||||
|
|
||||||
|
## Button
|
||||||
|
|
||||||
|
Properties:
|
||||||
|
|
||||||
|
| Title | Type | Reading | Record | Description |
|
||||||
|
| -------- | ------ | ------ | ------ | ------------ |
|
||||||
|
| text | string | yes | yes | button text |
|
||||||
|
|
||||||
|
## Label
|
||||||
|
|
||||||
|
Properties:
|
||||||
|
|
||||||
|
| Title | Type | Reading | Record | Description |
|
||||||
|
| -------- | ------ | ------ | ------ | ----------- |
|
||||||
|
| text | string | yes | yes | label text |
|
||||||
|
|
||||||
|
## Image
|
||||||
|
|
||||||
|
Properties:
|
||||||
|
|
||||||
|
| Title | Type | Reading | Record | Description |
|
||||||
|
| ----- | ------ | ------- | ------ | ------------ |
|
||||||
|
| src | string | yes | yes | texture name |
|
||||||
|
|
||||||
|
## Inventory
|
||||||
|
|
||||||
|
Properties:
|
||||||
|
|
||||||
|
| Title | Type | Reading | Record | Description |
|
||||||
|
| --------- | ---- | ------- | ------ | ------------------------------------------------- |
|
||||||
|
| inventory | int | yes | yes | id of the inventory to which the element is bound |
|
||||||
@@ -1,5 +1,7 @@
|
|||||||
# XML UI Building
|
# XML UI Building
|
||||||
|
|
||||||
|
See also [ui elements in scripting](scripting/ui.md).
|
||||||
|
|
||||||
# Specific types
|
# Specific types
|
||||||
|
|
||||||
**2D vector** - pair of numbers separated with comma.
|
**2D vector** - pair of numbers separated with comma.
|
||||||
|
|||||||
@@ -6,6 +6,7 @@
|
|||||||
- [События движка](scripting/events.md)
|
- [События движка](scripting/events.md)
|
||||||
- [Пользовательский ввод](scripting/user-input.md)
|
- [Пользовательский ввод](scripting/user-input.md)
|
||||||
- [Файловая система и сериализация](scripting/filesystem.md)
|
- [Файловая система и сериализация](scripting/filesystem.md)
|
||||||
|
- [Свойства и методы UI элементов](scripting/ui.md)
|
||||||
- [Модуль core:bit_converter](scripting/modules/core_bit_converter.md)
|
- [Модуль core:bit_converter](scripting/modules/core_bit_converter.md)
|
||||||
- [Модуль core:data_buffer](scripting/modules/core_data_buffer.md)
|
- [Модуль core:data_buffer](scripting/modules/core_data_buffer.md)
|
||||||
- [Модули core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)
|
- [Модули core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)
|
||||||
|
|||||||
@@ -0,0 +1,155 @@
|
|||||||
|
# Свойства и методы UI элементов
|
||||||
|
|
||||||
|
Обращение к UI элементов в скриптах произодится через экземпляр Document
|
||||||
|
(переменная document) по id, указанному в xml.
|
||||||
|
|
||||||
|
Пример: вывод в консоль свойства pos элемента с id: "worlds-panel":
|
||||||
|
```lua
|
||||||
|
print(document["worlds-panel"].pos)
|
||||||
|
-- или
|
||||||
|
local worldsPanel = document["worlds-panel"]
|
||||||
|
print(worldsPanel.pos)
|
||||||
|
```
|
||||||
|
|
||||||
|
Id элементов глобальны для документа, то есть worlds-panel может находиться как в корневом элементе,
|
||||||
|
так и в многократно вложенном контейнере.
|
||||||
|
|
||||||
|
Id элемента не может быть изменен из скрипта.
|
||||||
|
|
||||||
|
В таблицах далее будут использоваться сокращенные описания типов, такие как:
|
||||||
|
- vec2 - массив из двух дробных чисел.
|
||||||
|
- ivec2 - массив из двух целых чисел.
|
||||||
|
- rgba - массив из четырех дробных чисел в диапазоне *\[0..255\]* обозначающий RGBA состовляющие цвета.
|
||||||
|
|
||||||
|
Методы элементов, согласно особенностям ООП в Lua вызываются с использованием оператора `:` вместо `.`
|
||||||
|
|
||||||
|
Например:
|
||||||
|
```lua
|
||||||
|
document["worlds-panel"]:clear()
|
||||||
|
```
|
||||||
|
|
||||||
|
## Общие свойства и методы
|
||||||
|
|
||||||
|
Свойства, относящиеся ко всем элементам:
|
||||||
|
|
||||||
|
| Название | Тип | Чтение | Запись | Описание |
|
||||||
|
| ------------ | ------ | ------ | ------ | ----------------------------------------- |
|
||||||
|
| id | string | да | *нет* | идентификатор элемента |
|
||||||
|
| pos | vec2 | да | да | позиция элемента внутри контейнера |
|
||||||
|
| wpos | vec2 | да | да | позиция элемента в окне |
|
||||||
|
| size | vec2 | да | да | размер элемента |
|
||||||
|
| interactive | bool | да | да | возможность взаимодействия с элементом |
|
||||||
|
| enabled | bool | да | да | визуально обозначаемая версия interactive |
|
||||||
|
| visible | bool | да | да | видимость элемента |
|
||||||
|
| focused | bool | да | да | фокус на элементе |
|
||||||
|
| color | rgba | да | да | цвет элемента |
|
||||||
|
| hoverColor | rgba | да | да | цвет при наведении |
|
||||||
|
| pressedColor | rgba | да | да | цвет при нажатии |
|
||||||
|
| tooltip | string | да | да | текст всплывающей подсказки |
|
||||||
|
| tooltipDelay | float | да | да | задержка всплывающей подсказки |
|
||||||
|
|
||||||
|
Общие методы элементов:
|
||||||
|
|
||||||
|
| Метод | Описание |
|
||||||
|
| ------------------- | ----------------------------------------------------------------------- |
|
||||||
|
| moveInto(container) | перемещает элемент в указанный контейнер (указывается элемент, а не id) |
|
||||||
|
| destruct() | удаляет элемент |
|
||||||
|
|
||||||
|
## Контейнеры
|
||||||
|
|
||||||
|
Общие для контейнеров методы (элементы: container, panel, button, pagebox):
|
||||||
|
|
||||||
|
| Метод | Описание |
|
||||||
|
| ------------------------------- | ------------------------------------------------------------------------------------------- |
|
||||||
|
| clear() | очищает контент |
|
||||||
|
| add(xml) | добавляет элемент, создавая его по xml коду. Пример: `container:add("<image src='test'/>")` |
|
||||||
|
| setInterval(interval, callback) | назначает функцию на повторяющееся выполнение с заданным в миллисекундах интервалом |
|
||||||
|
|
||||||
|
## Текстовое поле (textbox)
|
||||||
|
|
||||||
|
Свойства:
|
||||||
|
|
||||||
|
| Название | Тип | Чтение | Запись | Описание |
|
||||||
|
| ----------- | ------ | ------ | ------ | ---------------------------------------------------------------------- |
|
||||||
|
| text | string | да | да | введенный текст или заполнитель |
|
||||||
|
| placeholder | string | да | да | заполнитель (используется если ничего не было введено) |
|
||||||
|
| caret | int | да | да | позиция каретки. `textbox.caret = -1` установит позицию в конец текста |
|
||||||
|
| editable | bool | да | да | изменяемость текста |
|
||||||
|
| multiline | bool | да | да | поддержка многострочности |
|
||||||
|
| textWrap | bool | да | да | автоматический перенос текста (только при multiline: "true") |
|
||||||
|
| valid | bool | да | нет | является ли введенный текст корректным |
|
||||||
|
|
||||||
|
Методы:
|
||||||
|
|
||||||
|
| Метод | Описание |
|
||||||
|
| ----------- | -------------------------------------------- |
|
||||||
|
| paste(text) | вставляет указанный текст на позицию каретки |
|
||||||
|
|
||||||
|
## Ползунок (trackbar)
|
||||||
|
|
||||||
|
Свойства:
|
||||||
|
|
||||||
|
| Название | Тип | Чтение | Запись | Описание |
|
||||||
|
| ---------- | ----- | ------ | ------ | ---------------------------- |
|
||||||
|
| value | float | да | да | выбранное значение |
|
||||||
|
| min | float | да | да | минимальное значение |
|
||||||
|
| max | float | да | да | максимальное значение |
|
||||||
|
| step | float | да | да | шаг деления |
|
||||||
|
| trackWidth | float | да | да | ширина управляющего элемента |
|
||||||
|
| trackColor | rgba | да | да | цвет управляющего элемента |
|
||||||
|
|
||||||
|
## Меню (pagebox)
|
||||||
|
|
||||||
|
Свойства:
|
||||||
|
|
||||||
|
| Название | Тип | Чтение | Запись | Описание |
|
||||||
|
| -------- | ------ | ------ | ------ | ---------------- |
|
||||||
|
| page | string | да | да | текущая страница |
|
||||||
|
|
||||||
|
Методы:
|
||||||
|
|
||||||
|
| Метод | Описание |
|
||||||
|
| ------- | ------------------------------------------ |
|
||||||
|
| back() | переключает на прошлую страницу |
|
||||||
|
| reset() | сбрасывает страницу и историю переключений |
|
||||||
|
|
||||||
|
## Отметка (checkbox)
|
||||||
|
|
||||||
|
Свойства:
|
||||||
|
|
||||||
|
| Название | Тип | Чтение | Запись | Описание |
|
||||||
|
| -------- | ---- | ------ | ------ | ----------------- |
|
||||||
|
| checked | bool | да | да | состояние отметки |
|
||||||
|
|
||||||
|
## Кнопка (button)
|
||||||
|
|
||||||
|
Свойства:
|
||||||
|
|
||||||
|
| Название | Тип | Чтение | Запись | Описание |
|
||||||
|
| -------- | ------ | ------ | ------ | ------------ |
|
||||||
|
| text | string | да | да | текст кнопки |
|
||||||
|
|
||||||
|
## Метка (label)
|
||||||
|
|
||||||
|
Свойства:
|
||||||
|
|
||||||
|
| Название | Тип | Чтение | Запись | Описание |
|
||||||
|
| -------- | ------ | ------ | ------ | ----------- |
|
||||||
|
| text | string | да | да | текст метки |
|
||||||
|
|
||||||
|
## Изображение (image)
|
||||||
|
|
||||||
|
Свойства:
|
||||||
|
|
||||||
|
| Название | Тип | Чтение | Запись | Описание |
|
||||||
|
| -------- | ------ | ------ | ------ | --------------------- |
|
||||||
|
| src | string | да | да | отображаемая текстура |
|
||||||
|
|
||||||
|
## Inventory (inventory)
|
||||||
|
|
||||||
|
Свойства:
|
||||||
|
|
||||||
|
| Название | Тип | Чтение | Запись | Описание |
|
||||||
|
| --------- | --- | ------ | ------ | ----------------------------------------- |
|
||||||
|
| inventory | int | да | да | id инвентаря, к которому привязан элемент |
|
||||||
|
|
||||||
@@ -1,5 +1,7 @@
|
|||||||
# XML разметка интерфейса
|
# XML разметка интерфейса
|
||||||
|
|
||||||
|
См. также [ui элементы в скриптинге](scripting/ui.md).
|
||||||
|
|
||||||
# Специфические типы
|
# Специфические типы
|
||||||
|
|
||||||
**2D вектор** - пара чисел, разделенная запятой.
|
**2D вектор** - пара чисел, разделенная запятой.
|
||||||
|
|||||||
Reference in New Issue
Block a user