voxelcore/doc/ru/scripting/builtins/libgui.md

Содержание

• Основное
• Локализация
• Окно и окружение
• Разметка
• Диалоговые окна
• Документы и шаблоны
• Корневой документ

Основное

• Библиотека содержит функции для доступа к свойствам UI элементов.
• В макетных скриптах доступна переменная document (класс Document).
• Вместо gui следует использовать объектную обертку:

print(document.some_button.text)
document.some_button.text = "новый текст"

Локализация

-- Возвращает переведённый текст.
gui.str(text: string, context: string) -> string

Окно и окружение

-- Возвращает размер главного контейнера (окна).
gui.get_viewport() -> {number, number}

-- Возвращает текущий масштаб интерфейса: пикселей окна в одной единице UI (1..4).
-- Задаётся настройкой display.gui-scale и ограничивается размером окна.
gui.get_scale() -> int

-- Возвращает максимальный масштаб интерфейса, помещающийся в текущее окно.
gui.get_max_scale() -> int

-- Возвращает позицию курсора в единицах UI (в отличие от input.get_mouse_pos,
-- возвращающей пиксели окна). Используйте для позиционирования элементов UI.
gui.get_cursor_pos() -> {number, number}

-- Возвращает окружение (глобальные переменные) указанного документа.
gui.get_env(document: string) -> table

-- Возвращает информацию о всех загруженных локалях.
-- Ключ - id локали в формате isolangcode_ISOCOUNTRYCODE
-- Значение - таблица { name: string }
gui.get_locales_info() -> table

Фреймы

-- Замена для menu:reset() для закрытия меню паузы, деактивирующая основной фрейм UI.
gui.close_menu()

-- Создаёт фрейм.
gui.create_frame(
    -- Глобальный id фрейма (не связан с UI свойством 'id').
    id: str,
    -- Текстура, в которую будет производиться рендер фрейма.
    -- В случае пустой строки рендер производится на экран.
    output_texture: str,
    -- Размер фрейма. Например: {640, 480}
    size: vec2
) -> Element, Document

-- Возвращает id активного фрейма (не id элемента).
gui.get_active_frame() -> str

-- Устанавливает активный фрейм, получающий пользовательский ввод.
-- Пустая строка указывает null-фрейм, при котором захватывается курсор.
gui.set_active_frame(
    -- id фрейма, созданного через gui.create_frame
    id: str,
    -- Функция-поставщик позиции курсора во фрейме.
    -- Используется для пользовательской проекции (например в 3D)
    [опционально] cursorLocator: function() -> number, number
)

-- Создаёт снимок фрейма в виде объекта Canvas если указан id фрейма, или всего окна, в случае nil.
gui.screenshot(
    -- id фрейма, созданного через gui.create_frame
    [опционально] frameId: str
) -> Canvas | nil

Разметка

-- Удаляет разметку из текста.
gui.clear_markup(
    language: string, -- язык разметки ("md" - Markdown)
    text: string      -- текст с разметкой
) -> string

-- Экранирует разметку в тексте.
gui.escape_markup(
    language: string, -- язык разметки ("md" - Markdown)
    text: string      -- текст с разметкой
) -> string

Диалоговые окна

-- Выводит окно с сообщением. Не останавливает выполнение кода.
gui.show_message(
    message: string                 -- сообщение (не переводится автоматически, используйте gui.str(...))
    on_ok: function() -> nil        -- вызывается при закрытии
)

-- Запрашивает подтверждение действия. Не останавливает выполнение кода.
gui.ask(
    -- сообщение (не переводится автоматически, используйте gui.str(...))
    message: string,
    -- функция, вызываемая при подтвержении
    on_confirm: function() -> nil,
    -- функция, вызываемая при отказе/отмене
    [опционально] on_deny: function() -> nil,
    -- текст кнопки подтвержения (по-умолчанию: "Да")
    -- используйте пустую строку для значения по-умолчанию, если нужно указать no_text.
    [опционально] yes_text: string
    -- текст кнопки отказа (по-умолчанию: "Нет")
    [опционально] no_text: string
)

Диалоговые страницы меню (устаревший подход)

-- Выводит окно с сообщением в виде страницы меню. Не останавливает выполнение кода.
gui.alert(
    message: string,                -- сообщение (не переводится автоматически, используйте gui.str(...))
    on_ok: function() -> nil        -- вызывается при закрытии
)

-- Запрашивает подтверждение действия в виде страницы меню. Не останавливает выполнение кода.
gui.confirm(
    -- сообщение (не переводится автоматически, используйте gui.str(...))
    message: string,
    -- функция, вызываемая при подтвержении
    on_confirm: function() -> nil,
    -- функция, вызываемая при отказе/отмене
    [опционально] on_deny: function() -> nil,
    -- текст кнопки подтвержения (по-умолчанию: "Да")
    -- используйте пустую строку для значения по-умолчанию, если нужно указать no_text.
    [опционально] yes_text: string
    -- текст кнопки отказа (по-умолчанию: "Нет")
    [опционально] no_text: string
)

Документы и шаблоны

-- Загружает UI документ и его скрипт. Возвращает пространство имён документа
gui.load_document(
    path: string,  -- путь к xml файлу, например: core:layouts/pages/main.xml
    name: string,  -- id документа, например: core:pages/main
    args: table -- параметры для события on_open
) -> table

-- Обрабатывает xml шаблон макета из файла
gui.template(
    -- имя шаблона в /layouts/templates без пути и расширения 
    name: string,
    -- таблица переменных (может быть использована в разметке)
    -- * Пр: <label>%{text}</label>
    -- * text в данном случае, это значение из params по ключу text
    params: table
) -> string

-- Обрабатывает xml шаблон макета из строки
gui.process_template(
    -- шаблон в виде строки
    source: string,
    -- таблица переменных, как в gui.template
    params: table
)

Корневой документ

-- Корневой UI документ.
gui.root: Document