# Свойства и методы 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 | да | да | задержка всплывающей подсказки |
| contentOffset | vec2 | да | *нет* | смещение содержимого |
| cursor | string | да | да | курсор, отображаемый при наведении |
| parent | Element | да | *нет* | родительский элемент или nil |
Общие методы элементов:
| Метод | Описание |
| ------------------- | ----------------------------------------------------------------------- |
| moveInto(container) | перемещает элемент в указанный контейнер (указывается элемент, а не id) |
| destruct() | удаляет элемент |
| reposition() | обновляет позицию элемента на основе функции позиционирования |
## Контейнеры
Свойства, относящиеся к контейнерам (элементы: container, panel, button, pagebox):
| Название | Тип | Чтение | Запись | Описание |
| ------------- | ------ | ------ | ------ | ----------------------------------------- |
| scroll | string | да | да | прокрутка содержимого |
Методы:
| Метод | Описание |
| ------------------------------- | --------------------------------------------------------------------------------------------- |
| clear() | очищает контент |
| add(xml) | добавляет элемент, создавая его по xml коду. Пример: `container:add("")` |
| add(xml, data) | перегрузка с передачей таблицы, которая в событиях, объявленных в xml будет доступна как DATA |
| setInterval(interval, callback) | назначает функцию на повторяющееся выполнение с заданным в миллисекундах интервалом |
## Текстовое поле (textbox)
Свойства:
| Название | Тип | Чтение | Запись | Описание |
| ----------- | ------ | ------ | ------ | ---------------------------------------------------------------------- |
| text | string | да | да | введенный текст или заполнитель |
| placeholder | string | да | да | заполнитель (используется если ничего не было введено) |
| hint | string | да | да | текст, отображаемый, когда ничего не введено |
| caret | int | да | да | позиция каретки. `textbox.caret = -1` установит позицию в конец текста |
| editable | bool | да | да | изменяемость текста |
| edited | bool | да | да\* | был ли изменён текст с последней установки/сброса свойства |
| multiline | bool | да | да | поддержка многострочности |
| lineNumbers | bool | да | да | отображение номеров строк |
| textWrap | bool | да | да | автоматический перенос текста (только при multiline: "true") |
| valid | bool | да | нет | является ли введенный текст корректным |
| textColor | vec4 | да | да | цвет текста |
| syntax | string | да | да | подсветка синтаксиса ("lua" - Lua) |
| markup | string | да | да | язык разметки текста ("md" - Markdown) |
\* - только false
Методы:
| Метод | Описание |
| ------------------------- | -------------------------------------------- |
| paste(text: str) | вставляет указанный текст на позицию каретки |
| lineAt(pos: int) -> int | определяет номер строки по позиции в тексте |
| linePos(line: int) -> int | определяет позицию начала строки в тексте |
## Ползунок (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 | да | да | текст метки |
| markup | string | да | да | язык разметки текста ("md" - Markdown) |
## Изображение (image)
Свойства:
| Название | Тип | Чтение | Запись | Описание |
| -------- | ------ | ------ | ------ | ---------------------- |
| src | string | да | да | отображаемая текстура |
| region | vec4 | да | да | под-регион изображения |
## Холст (canvas)
Свойства:
| Название | Тип | Чтение | Запись | Описание |
|----------|--------| ------ |--------|----------------|
| data | Canvas | да | нет | пиксели холста |
Методы:
Здесь *цвет* может быть указан следующими способами:
- rgba: int
- r: int, g: int, b: int
- r: int, g: int, b: int, a: int
| Метод | Описание |
|----------------------------------------------------------|------------------------------------------------------|
| data:at(x: int, y: int) | возвращает RGBA пиксель по указанным координатам |
| data:set(x: int, y: int, *цвет*) | изменяет RGBA пиксель по указанным координатам |
| data:line(x1: int, y1: int, x2: int, y2: int, *цвет*) | рисует линию с указанным RGBA цветом |
| data:blit(src: Canvas, dst_x: int, dst_y: int) | рисует src-холст на указанных координатах |
| data:clear() | очищает холст |
| data:clear(*цвет*) | заполняет холст указанным RGBA цветом |
| data:update() | применяет изменения и загружает холст в видеопамять |
| data:set_data(data: table) | заменяет данные пикселей (ширина * высота * 4 чисел) |
| data:create_texture(name: str) | создаёт и делится текстурой с рендерером |
| data:unbind_texture() | отвязывает текстуру от холста |
| data:mul(*цвет* или Canvas) | умножает увет на указанный цвет или холст |
| data:add(*цвет* или Canvas) | прибавляет цвет или другой холст к цвету |
## Рамка встраивания (iframe)
| Название | Тип | Чтение | Запись | Описание |
|----------|--------|--------|--------|----------------------------|
| src | string | да | да | id встраиваемого документа |
## Меню выбора (select)
Является производным от кнопки с доступом к свойствам, таким как отображаемый текст.
Свойства:
| Название | Тип | Чтение | Запись | Описание |
|----------|--------|--------|--------|----------------------------------------------------------------|
| value | string | да | да | Выбранное значение |
| options | table | да | да | Список опций (таблиц `{value=..., text=...}`) |
## Инвентарь (inventory)
Свойства:
| Название | Тип | Чтение | Запись | Описание |
|-----------|-----|--------|--------|-------------------------------------------|
| inventory | int | да | да | id инвентаря, к которому привязан элемент |