PulseStudio/VoxelEngine
PulseStudio/VoxelEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

add doc/*/scripting/ui.md

Browse Source
This commit is contained in:
MihailRis 2024-06-16 16:36:30 +03:00
parent 41b5c5acfc
commit 7b694d4819
6 changed files with 315 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/en/scripting.md
View File

@ -6,6 +6,7 @@ Subsections:
- [Engine events](scripting/events.md)
- [User input](scripting/user-input.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:data_buffer](scripting/modules/core_data_buffer.md)
- [Module core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)

154
doc/en/scripting/ui.md Normal file
View File

@ -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 |

2
doc/en/xml-ui-layouts.md
View File

@ -1,5 +1,7 @@
# XML UI Building
See also [ui elements in scripting](scripting/ui.md).
# Specific types
**2D vector** - pair of numbers separated with comma.

1
doc/ru/scripting.md
View File

@ -6,6 +6,7 @@
- [События движка](scripting/events.md)
- [Пользовательский ввод](scripting/user-input.md)
- [Файловая система и сериализация](scripting/filesystem.md)
- [Свойства и методы UI элементов](scripting/ui.md)
- [Модуль core:bit_converter](scripting/modules/core_bit_converter.md)
- [Модуль core:data_buffer](scripting/modules/core_data_buffer.md)
- [Модули core:vector2, core:vector3](scripting/modules/core_vector2_vector3.md)

155
doc/ru/scripting/ui.md Normal file
View File

@ -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 инвентаря, к которому привязан элемент |

2
doc/ru/xml-ui-layouts.md
View File

@ -1,5 +1,7 @@
# XML разметка интерфейса
См. также [ui элементы в скриптинге](scripting/ui.md).
# Специфические типы
**2D вектор** - пара чисел, разделенная запятой.