## Содержание

* [Основное](#основное)
* [Локализация](#локализация)
* [Окно и окружение](#окно-и-окружение)
* [Разметка](#разметка)
* [Диалоговые окна](#диалоговые-окна)
* [Документы и шаблоны](#документы-и-шаблоны)
* [Корневой документ](#корневой-документ)

## Основное

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

## Локализация

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

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

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

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

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

## Фреймы

```lua
-- Замена для 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
)
```

## Разметка

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

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

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

```lua
-- Выводит окно с сообщением. Не останавливает выполнение кода.
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
)
```

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

```lua
-- Выводит окно с сообщением в виде страницы меню. Не останавливает выполнение кода.
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
)
```

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

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

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

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

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