# Свойства и методы 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 | да     | да     | курсор, отображаемый при наведении        |

Общие методы элементов:

| Метод               | Описание                                                                |
| ------------------- | ----------------------------------------------------------------------- |
| moveInto(container) | перемещает элемент в указанный контейнер (указывается элемент, а не id) |
| destruct()          | удаляет элемент                                                         |
| reposition()        | обновляет позицию элемента на основе функции позиционирования           |

## Контейнеры

Общие для контейнеров методы (элементы: container, panel, button, pagebox):

| Метод                           | Описание                                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------- |
| clear()                         | очищает контент                                                                             |
| add(xml)                        | добавляет элемент, создавая его по xml коду. Пример: `container:add("<image src='test'/>")` |
| 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 | да     | да     | отображаемая текстура |


## Холст (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<int>)                          | заменяет данные пикселей (ширина * высота * 4 чисел) |
| data:create_texture(name: str)                           | создаёт и делится текстурой с рендерером             |

## Inventory (inventory)

Свойства:

| Название  | Тип | Чтение | Запись | Описание                                  |
| --------- | --- | ------ | ------ | ----------------------------------------- |
| inventory | int | да     | да     | id инвентаря, к которому привязан элемент |

