GUI
===

## Введение

GUI — это возможность Suika3 для создания UI/UX.

В Suika3 кнопки определяются в специальном режиме GUI и работают
синхронно: вызов GUI завершается щелчком по кнопке или отменой.

Асинхронные обратные вызовы, например показ кнопок во время
выполнения текстовых тегов, намеренно не используются, потому что
начинающим программистам может быть трудно понимать их и управлять ими.

Файл GUI содержит список определений кнопок. Каждая кнопка включает
тип поведения, изображения idle и hover, а также дополнительные
свойства. Кнопки сопоставляются со слоями анимации, а файлы анимации
могут запускаться при изменении состояния кнопки.

---

## Пример GUI

```
# Раздел глобальных настроек.
global {
    fadein:       0.2;            # Время появления в секундах.
    fadeout:      0.2;            # Время исчезновения в секундах.
}

# Блок описывает кнопку.
# Имя блока может быть любым и ни на что не влияет.
button1 {
    # ID слоя (`1`-`32`)
    # `1` означает самый верхний слой, а `32` — самый нижний слой среди слоев GUI.
    id: 1;
 
    # Тип поведения (`goto` означает переход к метке при щелчке.)
    type: goto;

    # Метка, к которой нужно перейти.
    label: button1_clicked;

    # Позиция
    x: 39;
    y: 99;

    # `width:` и `height:` можно опустить, так как они выводятся из размера изображения.

    # Изображения
    image-idle:  gui/item-idle.png;    # Показывается, когда указатель не наведен на кнопку.
    image-hover: gui/item-hover.png;   # Показывается, когда указатель наведен на кнопку.
    image-press: gui/item-press.png;   # Показывается при нажатии кнопки.

    # Анимации
    anime-idle:  gui/item-idle.anime;   # Выполняется, когда состояние кнопки меняется на `idle`.
    anime-hover: gui/item-hover.anime;  # Выполняется, когда состояние кнопки меняется на `hover`.
    anime-press: gui/item-press.anime;  # Выполняется при нажатии кнопки.

    # Обратите внимание, что `press` не является самостоятельным состоянием, это дополнительный флаг к состоянию `hover`.
    # При запуске анимации `hover` анимация `idle` будет отменена.
    # А при запуске анимации `idle` анимация `hover` будет отменена.
    # Однако анимация `press` ничего не отменяет.
}
```

В разделе `global` можно указать параметры GUI.

Остальные разделы интерпретируются как определения кнопок.
Здесь `button1` создает кнопку в позиции `(39, 99)`.
Если по кнопке щелкнуть, произойдет переход типа `goto`.

---

## Типы кнопок

| Описание                        | Значение                                                   |
|---------------------------------|------------------------------------------------------------|
| type: noaction;                 | Некликабельное изображение.                                |
| type: goto;                     | Переход к метке при щелчке.                                |
| type: gui;                      | Переход к GUI при щелчке.                                  |
| type: mastervol;                | Отображается как ползунок общей громкости.                 |
| type: bgmvol;                   | Отображается как ползунок громкости BGM.                   |
| type: sevol;                    | Отображается как ползунок громкости SE.                    |
| type: voicevol;                 | Отображается как ползунок громкости голоса.                |
| type: charactervol;             | Отображается как ползунок громкости персонажа.             |
| type: textspeed;                | Отображается как ползунок скорости текста.                 |
| type: autospeed;                | Отображается как ползунок скорости авторежима.             |
| type: preview;                  | Отображается как область предварительного просмотра текста. |
| type: fullscreen;               | Отображается как кнопка полноэкранного режима.             |
| type: window;                   | Отображается как кнопка оконного режима.                   |
| type: default;                  | Сбрасывает настройки при нажатии.                          |
| type: savepage;                 | Отображается как кнопка страницы сохранения/загрузки.      |
| type: save;                     | Отображается как слот сохранения.                          |
| type: load;                     | Отображается как слот загрузки.                            |
| type: auto;                     | Отображается как кнопка авторежима.                        |
| type: skip;                     | Отображается как кнопка режима пропуска.                   |
| type: title;                    | Отображается как кнопка возврата к титульному экрану.      |
| type: history;                  | Отображается как кнопка истории.                           |
| type: historyscroll;            | Отображается как вертикальный ползунок прокрутки истории.  |
| type: historyscroll-horizontal; | Отображается как горизонтальный ползунок прокрутки истории.|
| type: cancel;                   | Отображается как кнопка отмены.                            |
| type: namevar;                  | Отображается как область просмотра значения переменной имени. |
| type: char;                     | Отображается как кнопка для ввода символа.                 |
| type: language                  | Меняет язык при щелчке.                                    |

### `noaction`

Некликабельное изображение.

```
background {
    type: noaction;
    x: 0;
    y: 0;
    image-idle: idle.png;
}
```

### `goto`

Кликабельная кнопка. При щелчке выполнение тегов переходит к метке, указанной параметром `label:`.

```
button1 {
    type: goto;
    label: label_clicked_button1;
    x: 0;
    y: 0;
    image-idle:  idle.png;
    image-hover: hover.png;
}
```

### `gui`

Кликабельная кнопка. При щелчке выполнение GUI цепочкой переходит к новому GUI, указанному параметром `file:`.

```
button1 {
    type: gui;
    label: gui2.gui;
    x: 0;
    y: 0;
    image-idle:  idle.png;
    image-hover: hover.png;
}
```

### `mastervol`

Ползунок для установки общей громкости.

```
slider1 {
    type: mastervol;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Базовая полоса ползунка
    image-hover: hover.png;  # Базовая полоса ползунка (яркая)
    image-knob:  knob.png;   # Ручка ползунка
}
```

### `bgmvol`

Ползунок для установки громкости BGM.

Этот ползунок задает громкость, которая сохраняется в глобальном файле данных сохранения.
Это отличается от громкости, задаваемой тегом `[volume]` и сохраняемой в локальных данных сохранения.

```
slider1 {
    type: bgmvol;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Базовая полоса ползунка
    image-hover: hover.png;  # Базовая полоса ползунка (яркая)
    image-knob:  knob.png;   # Ручка ползунка
}
```

### `sevol`

Ползунок для установки громкости SE.

Этот ползунок задает громкость, которая сохраняется в глобальном файле данных сохранения.
Это отличается от громкости, задаваемой тегом `[volume]` и сохраняемой в локальных данных сохранения.

```
slider1 {
    type: bgmvol;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Базовая полоса ползунка
    image-hover: hover.png;  # Базовая полоса ползунка (яркая)
    image-knob:  knob.png;   # Ручка ползунка
}
```

### `voicevol`

Ползунок для установки громкости SE.

Этот ползунок задает громкость, которая сохраняется в глобальном файле данных сохранения.
Это отличается от громкости, задаваемой тегом `[volume]` и сохраняемой в локальных данных сохранения.

```
slider1 {
    type: bgmvol;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Базовая полоса ползунка
    image-hover: hover.png;  # Базовая полоса ползунка (яркая)
    image-knob:  knob.png;   # Ручка ползунка
}
```

### `charactervol`

Ползунок для установки громкости отдельного персонажа.

Индекс персонажа передается параметром `index:`.
Индекс 0 используется для неопределенного персонажа, а 1-32 — для определенных персонажей.

```
slider1 {
    type: charactervol;
    index: 1;  # Индекс персонажа
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Базовая полоса ползунка
    image-hover: hover.png;  # Базовая полоса ползунка (яркая)
    image-knob:  knob.png;   # Ручка ползунка
}
```

### `textspeed`

Ползунок для установки скорости текста.

```
slider1 {
    type: textspeed;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Базовая полоса ползунка
    image-hover: hover.png;  # Базовая полоса ползунка (яркая)
    image-knob:  knob.png;   # Ручка ползунка
}
```

### `autospeed`

Ползунок для установки скорости авторежима.

```
slider1 {
    type: textspeed;
    x: 0;
    y: 0;
    image-idle:  idle.png;   # Базовая полоса ползунка
    image-hover: hover.png;  # Базовая полоса ползунка (яркая)
    image-knob:  knob.png;   # Ручка ползунка
}
```

### `preview`

Текстовая область для предварительного просмотра шрифта, языка и скорости.

```
preview1 {
    type: preview;
    x: 0;
    y: 0;
    image-idle: idle.png;
}
```

### `fullscreen`

Кликабельная кнопка.
При щелчке движок перейдет в полноэкранный режим.

```
fullscreen1 {
    type: fullscreen;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
    image-disable: disable.png;  # Для случая, когда активен полноэкранный режим.
}
```

### `window`

Кликабельная кнопка.
При щелчке движок перейдет в оконный режим.

```
window1 {
    type: window;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
    image-disable: disable.png;  # Для случая, когда активен оконный режим.
}
```

### `default`

Кликабельная кнопка.
При щелчке она сбрасывает все настройки.

```
reset1 {
    type: default;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}
```

### `savepage`

Кликабельная кнопка.
При щелчке она переключает страницу экрана сохранения.

```
savepage1 {
    type: savepage;
    index: 0; # Индекс страницы (0-)
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
    image-active:  active.png;  # Для случая, когда страница активна.
}
```

### `save`

Кликабельная кнопка.
При щелчке она выполняет сохранение.

```
save1 {
    type: save;
    index: 0; # Индекс на странице. фактический слот сохранения = page * saveslots + index

    x: 0;
    y: 0;

    image-idle: system/save/save-item-idle.png;
    image-hover: system/save/save-item-hover.png;

    index-x:   10;   # Номер
    index-y:   0;
    date-x:    60;   # Дата
    date-y:    0;
    thumb-x:   27;   # Миниатюра
    thumb-y:   77;
    chapter-x: 260;  # Заголовок главы
    chapter-y: 48;
    msg-x:     260;  # Последнее сообщение
    msg-y:     96;
}
```

### `load`

Кликабельная кнопка.
При щелчке она выполняет загрузку.

```
load1 {
    type: load;
    index: 0; # Индекс на странице. фактический слот сохранения = page * saveslots + index

    x: 0;
    y: 0;

    image-idle: system/load/load-item-idle.png;
    image-hover: system/load/load-item-hover.png;

    index-x:   10;   # Номер
    index-y:   0;
    date-x:    60;   # Дата
    date-y:    0;
    thumb-x:   27;   # Миниатюра
    thumb-y:   77;
    chapter-x: 260;  # Заголовок главы
    chapter-y: 48;
    msg-x:     260;  # Последнее сообщение
    msg-y:     96;
}
```

### `auto`

Кликабельная кнопка.
При щелчке она запускает Auto Mode.

```
auto1 {
    type: auto;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}
```

### `skip`

Кликабельная кнопка.
При щелчке она запускает Skip Mode.

```
skip1 {
    type: skip;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}
```

### `title`

Кликабельная кнопка.
При щелчке движок возвращается к указанному файлу NovelML.

```
title1 {
    type: title;
    file: title.novel;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}
```

### `history`

Кликабельная кнопка.
Она показывает элемент истории сообщений.

```
history {
    type: history;
    index: 0; # Индекс на странице
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;

    name-x: 20;   # Имя
    name-y: 10;
    text-x:  20;  # Текст (когда есть имя)
    text-y:  50;
    msg-x:  20;   # Сообщение (когда имени нет)
    msg-y:  10;
}
```

### `historyscroll`

Вертикальная полоса прокрутки для экрана истории.

```
scroll1 {
    type: historyscroll;
    x: 1200;
    y: 40;

    image-idle:  system/history/history-bar-idle.png;
    image-hover: system/history/history-bar-hover.png;
    image-knob:  system/history/history-bar-knob.png;
}
```

### `historyscroll-horizontal`

Горизонтальная полоса прокрутки для экрана истории с вертикальным письмом.

```
scroll1 {
    type: historyscroll-horizontal;
    x: 40;
    y: 650;

    image-idle:  system/history/history-bar-idle.png;
    image-hover: system/history/history-bar-hover.png;
    image-knob:  system/history/history-bar-knob.png;
}
```

### `cancel`

Кликабельная кнопка.
При щелчке GUI будет отменен.

```
cancel1 {
    type: cancel;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}
```

### `var`

Текстовая область для отображения значения переменной.
Она используется для редактирования имени.

```
var1 {
    type: var;
    variable: variable_name;
    x: 0;
    y: 0;
    image-idle:    idle.png;
}
```

### `char`

Кнопка для добавления символа к переменной.
Она используется для редактирования имени.

```
char1 {
    type: char;
    variable: variable_name; # Имя переменной.
    msg: A;                  # Добавляемый текст.
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
}
```

### `language`

Кнопка для переключения языка.

```
language_english1 {
    type: language;
    langu: en;
    x: 0;
    y: 0;
    image-idle:    idle.png;
    image-hover:   hover.png;
    image-disable: disable.png; # Для случая, когда активен английский язык.
}
```

---

## Общие параметры кнопок

| Описание              | Значение                                                   |
|-----------------------|------------------------------------------------------------|
| type:                 | Тип кнопки.                                                |
| x:                    | Позиция кнопки по X.                                       |
| y:                    | Позиция кнопки по Y.                                       |
| width:                | Ширина кнопки. (по умолчанию задается шириной idle-изображения) |
| height:               | Высота кнопки.                                             |
| pointse:              | Звуковой эффект при наведении указателя на кнопку.         |
| clickse:              | Звуковой эффект при щелчке по кнопке.                      |

### pointse:

`pointse: btn-change.ogg;` указывает, что файл звукового эффекта
воспроизводится, когда курсор мыши входит в область кнопки.

### clickse:

`clickse: click.ogg;` указывает, что файл звукового эффекта воспроизводится
при щелчке по кнопке.
