From 7b694d4819da78aec1e90ff4bf480a3833035f19 Mon Sep 17 00:00:00 2001
From: MihailRis <mexaruc@gmail.com>
Date: Sun, 16 Jun 2024 16:36:30 +0300
Subject: [PATCH] add doc/*/scripting/ui.md

---
 doc/en/scripting.md      |   1 +
 doc/en/scripting/ui.md   | 154 ++++++++++++++++++++++++++++++++++++++
 doc/en/xml-ui-layouts.md |   2 +
 doc/ru/scripting.md      |   1 +
 doc/ru/scripting/ui.md   | 155 +++++++++++++++++++++++++++++++++++++++
 doc/ru/xml-ui-layouts.md |   2 +
 6 files changed, 315 insertions(+)
 create mode 100644 doc/en/scripting/ui.md
 create mode 100644 doc/ru/scripting/ui.md

diff --git a/doc/en/scripting.md b/doc/en/scripting.md
index f9467336..18b1e762 100644
--- a/doc/en/scripting.md
+++ b/doc/en/scripting.md
@@ -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)
diff --git a/doc/en/scripting/ui.md b/doc/en/scripting/ui.md
new file mode 100644
index 00000000..c5bc44cc
--- /dev/null
+++ b/doc/en/scripting/ui.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 |
diff --git a/doc/en/xml-ui-layouts.md b/doc/en/xml-ui-layouts.md
index 5fe0efdb..cdd13aa3 100644
--- a/doc/en/xml-ui-layouts.md
+++ b/doc/en/xml-ui-layouts.md
@@ -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.
diff --git a/doc/ru/scripting.md b/doc/ru/scripting.md
index a6834591..80a6f3c6 100644
--- a/doc/ru/scripting.md
+++ b/doc/ru/scripting.md
@@ -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)
diff --git a/doc/ru/scripting/ui.md b/doc/ru/scripting/ui.md
new file mode 100644
index 00000000..956278fa
--- /dev/null
+++ b/doc/ru/scripting/ui.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 инвентаря, к которому привязан элемент |
+
diff --git a/doc/ru/xml-ui-layouts.md b/doc/ru/xml-ui-layouts.md
index 93c23c93..6707f93c 100644
--- a/doc/ru/xml-ui-layouts.md
+++ b/doc/ru/xml-ui-layouts.md
@@ -1,5 +1,7 @@
 # XML разметка интерфейса
 
+См. также [ui элементы в скриптинге](scripting/ui.md).
+
 # Специфические типы
 
 **2D вектор** - пара чисел, разделенная запятой.