VoxelEngine/doc/ru/scripting/ui.md

Свойства и методы UI элементов

Обращение к UI элементов в скриптах произодится через экземпляр Document (переменная document) по id, указанному в xml.

Пример: вывод в консоль свойства pos элемента с id: "worlds-panel":

print(document["worlds-panel"].pos)
-- или
local worldsPanel = document["worlds-panel"]
print(worldsPanel.pos)

Id элементов глобальны для документа, то есть worlds-panel может находиться как в корневом элементе, так и в многократно вложенном контейнере.

Id элемента не может быть изменен из скрипта.

В таблицах далее будут использоваться сокращенные описания типов, такие как:

• vec2 - массив из двух дробных чисел.
• ivec2 - массив из двух целых чисел.
• rgba - массив из четырех дробных чисел в диапазоне [0..255] обозначающий RGBA состовляющие цвета.

Методы элементов, согласно особенностям ООП в 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("<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	да	да	отображаемая текстура
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)	создаёт и делится текстурой с рендерером

Рамка встраивания (iframe)

Название	Тип	Чтение	Запись	Описание
src	string	да	да	id встраиваемого документа

Инвентарь (inventory)

Свойства:

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