Конфигурирование и работа с настройками выполняется при помощи функций set и get, а также посредством конфигурационного файла.
Это, вероятно, самая сложная функция в API. Конфигурирование опций библиотеки, управление шрифтами и тайлсетами и даже конфигурационным файлом производится с ее помощью:
terminal_set("window: size=80x25; font: ./UbuntuMono-R.ttf, size=12");
Функция возвращает булево значение, индицирующее успех выполнения.
Можно указывать несколько опций за один вызов. Однако, эта функция работает похожим на транзакцию образом: в случае ошибки все изменения откатываются (или просто не применяются) и функция возвращает false.
Строка, передаваемая в функцию, описывает набор параметров в виде пар имя-значение, разделенных точкой с запятой:
window.title='foo'; window.size=80x25;
Параметры могут быть сгруппированы:
window: title='foo', size=80x25;
Лишние пробелы, запятые и точки с запятой игнорируются. Все переносы строк также игнорируются (на данный момент, даже внутри значений, но это может измениться).
Экранирование строковых значений кавычками опционально и требуется только если значение содержит служебные символы (запятая или точка с запятой) или если необходимо сохранить пробелы в начале или конце. Кавычки внутри строки экранируются в Pascal-стиле (удвоением символа):
window.title='I''m feeling lucky!';
Экранирование спецсимволов (таких как \n или \t) не поддерживается.
Ряд параметров непосредственно влияют на вид окна и поведение библиотеки:
| Группа | Опция | По умолчанию | Краткое описание |
|---|---|---|---|
| terminal | encoding | utf8 | Кодировка/кодовая страница, используемая для однобайтных строк; по умолчанию это “utf-8”, что может быть изменено на какю-нибудь кодовую страницу ANSI, например windows-1251. |
| window | size | 80×25 | Размер окна в знакоместах. |
| cellsize | auto | Размер знакоместа в пикселях или “auto”, если размер должен быть выведен исходя из выбранного шрифта. | |
| title | 'BearLibTerminal' | Заголовок окна. | |
| icon | - | Имя файла *.ico с иконкой; в версии для Windows, стандартная иконка встроена в библиотеку. | |
| resizeable | false | Флаг, контролирующий возможность переразмерения окна пользователем, при изменении размера окна будет сгенерировано событие TK_RESIZED. | |
| fullscreen | false | Флаг, позволяющий программно перевести окно в полноэкранный режим. | |
| input | precise-mouse | false | Флаг контролирующий точность регистрации передвижения мыши: когда он выставлен в “true”, можно отследить любое перемещение курсора мыши, неважно насколько малое. По умолчанию событие TK_MOUSE_MOVE генерируется только если курсор мыши перемещается на другое знакоместо. |
| mouse-cursor | true | Флаг, ответственный за отображение системного указателя мыши. | |
| cursor-symbol | 0x5F | Код символа/тайла, используемого функцией read_str в качестве курсора ввода. | |
| cursor-blink-rate | 500 | Скорость мерцания курсора ввода в функции read str в миллисекундах. | |
| filter | - | События, не попавшие в этот список, будут обработаны библиотекой автоматически и не будут возвращены функцией read. | |
| alt-functions | true | Если задействовано, библиотека перехватывает и обрабатывает некоторые Alt-комбинации, например Alt+Enter (переключение в полноэкранный режим) и Alt+Плюс/Минус/Ноль (масштаб окна). | |
| output | postformatting | true | Флаг, задействующий обработку специальных “тегов” функцией print. |
| vsync | true | Флаг, контролирующий использование вертикальной синхронизации при выводе сцены. | |
| log | file | 'bearlibterminal.log' | Имя файла лога. |
| level | error | Уровень логгирования: “none”, “fatal”, “error”, “warning”, “info”, “debug” или “trace”. | |
| mode | truncate | Режим записи в файл: “truncate” начнет запись в файл заново (очистив предыдущее содержимое), “append” будет дописывать в конец файла. |
Помимо нескольких фиксированных групп параметров библиотеки, может быть сконфигурировано неопределенное количество групп параметров, описывающих отдельный шрифт, тайл или тайлсет (см. дизайн: тайлы и слоты) в следующем формате:
[name ](font|offset): resource, param=value, ...;
Например:
font: UbuntuMono-R.ttf, size=12; runic font: runic.png, size=8x16, codepage=437; 0x5E: curcumflex.png; 0xE000: tileset.png, size=16x16, spacing=2x1;
Строка, опциональное и произвольное наименование альтернативного шрифта, например 'italic' или 'runic'. Такие именованные шрифты будут доступны в функции print посредством тега [font=name]:
terminal_print(2, 1, "Its eyes are [font=italic]glowing[/font].");
Число, код одиночного тайла или точка отсчета для кодов в тайлсете (при offset равном 0xE000 первый тайл будет иметь код 0xE000, второй 0xE001 и т. д.).
Все “символы”, “тайлы” и “спрайты” находятся в одном кодовом пространстве: библиотека оперирует кодами символов Юникода и не учитывает что именно изображено на соответствующей коду символа картинке, будь то буква, пиктограмма или фон для экрана меню. Таким образом, можно осознанно или нечаянно переопределить внешний вид символов:
terminal_set("0x40: at.png, align=center"); // Replace '@' (ASCII code 0x40) with a better version.
Если такое переопределение нежелательно, то рекомендуется использовать для пиктограмм и прочей несимвольной графики специально выделенный блок Юникода: Unicode Private Use Area (коды 0xE000-0xEFFF).
Строка, описывающая источник данных шрифта или тайлсета. Это может быть имя файла шрифта или картинки или дескриптор блока памяти в формате адрес:размер:
terminal_setf("font: %p:%d, size=8x16, codepage=437", buffer, size);
Также возможно загрузить тайлсет непосредственно из блока BGRA пикселей в памяти. В этом случае необходимо указать размер изображения посредством параметра 'raw-size':
terminal_setf("0xE000: %p:%d, raw-size=%dx%d", pixels, W*H*4, W, H);
Состав параметров в группе и их смысл отличается в зависимости от типа шрифта/тайлсета:
| Тип | Параметр | По умолчанию | Краткое описание |
|---|---|---|---|
| Bitmap | size | Размер отдельного тайла в наборе; по умолчанию изображение рассматривается как один большой спрайт. | |
| resize | Размер, до которого необходимо переразмерить тайлы (или спрайт). | ||
| resize-filter | bilinear | Фильтр переразмерения: “nearest”, “bilinear” или “bicubic”. | |
| resize-mode | stretch | Формат переразмерения: “stretch” (растянуть), “fit” (вписать по наибольшей стороне) или “crop” (вписать по наименьшей стороне). | |
| raw-size | Размер исходного изображения в случае загрузке из памяти (по указателю на массив пикселей). | ||
| codepage | ascii | Кодовая страница тайлсета, используемая в основном для загрузки шрифтов; по умолчанию “ascii”. | |
| align | center | Выравнивание тайла в ячейке: “center”, “top-left”, “bottom-left”, “top-right” или “bottom-right”. | |
| spacing | 1x1 | Размер ячейки выравнивания, в знакоместах. | |
| transparent | auto | Цвет фона для форматов/изображений, не поддерживающих прозрачность. | |
| TrueType | size | Размер шрифта или тайла, под который будет подогнан размер шрифта; это обязательный параметр. | |
| size-reference | '@' | Символ, используемый в качестве основы при подгонке размера шрифта под размер тайла. | |
| mode | normal | Режим растеризации шрифта: “monochrome”, “normal” или “lcd”. | |
| codepage | Инвертированная кодовая таблица для загрузки только конкретных глифов. | ||
| align | center | Выравнивание тайла в ячейке, то же самое, что и для растровых тайлсетов. | |
| spacing | 1x1 | Размер ячейки выравнивания, то же самое, что и для растровых тайлсетов. |
Параметры шрифта/тайлсета устанавливаются и заменяются все разом. Все необходимые параметры конкретного тайлсета должны быть указаны в одном вызове функции set.
Примеры описания растровых шрифтов/тайлсетов:
font: somefont.png, size=8x16, codepage=1251; 0xE000: walls.bmp, size=32x32, spacing=4x2; 0xE100: background.jpg, resize=640x400, resize-filter=bicubic, align=top-left;
Примеры описания TrueType шрифтов/тайлсетов:
font: somefont.ttf, size=12; 0xE000: otherfont.ttf, size=8x16, codepage=1251; 0xE100: fontawesome.ttf, size=32x32, spacing=4x2, codepage=fontawesome-cp.txt;
Для того, чтобы выгрузить тайлсет, необходимо установить его “основное значение” в “none”:
0xE000: none
С помощью функции set возможно добавление, изменение и удаление параметров из конфигурационного файла библиотеки, путем указания их в виде ini.section.property:
ini.game.tile-size = 16
В приведенном примере, библиотека обновит значение параметра “tile-size” в секции “game” конфигурационного файла:
Если указанного параметра или секции в файле нет, они будут добавлены. Для того, чтобы удалить параметр из файла, нужно указать пустое значение. Как следствие, программно установить пустое значение невозможно; вместо этого используйте осмысленное значение по умолчанию для соответствущего параметра.
Эта функция возвращает значение параметра (опция библиотеки или из конфигурационного файла). Если такой параметр не найден, возвращается переданное в функцию значение-заглушка:
const char* tile_size = terminal_get("ini.game.tile-size", "24");
На данный момент только опции библиотеки и параметры из конфигурационного файла могут быть прочитаны таким образом. Чтение свойств шрифтов и тайлсетов пока не поддерживается.
В интерфейсе С/С++, память возвращаемой строки принадлежит библиотеке и указатель на нее останется валидным до следующего вызова get с тем же именем параметра. Возвращаемое значение всегда будет корректной строкой, даже если значение-заглушка не было указано (в этом случае будет возвращена пустая строка).
С версии 0.12, возможно использование специального конфигурационного файла для задания некоторой начальной конфигурации библиотеки, а также в качестве хранилища произвольных параметров приложения.
Файл должен быть в обычном INI-формате с некоторыми особенностями:
# и ;. Строки, начинающиеся с пробела/табуляции также игнорируются.Примером конфигурационного файла может быть:
# Комментарий ; Еще один комментарий Это строка тоже будет считаться комментарием [BearLibTerminal] log: file=bt.log, level=trace font: UbuntuMono-R.ttf, size=12 window.title='Configuration file example' [Palette] lush = dark 80,255,37 [Game] tile-size = 16 ; Все после точки с запятой игнорируется.
Имя конфигурационного файла не задано жестко, библиотека постарается найти подходящий файл. Если не получится обнаружить файл, названный так же, как и приложение (game.ini для game.exe), будет использован первый попавшийся INI-файл. Файлы в текущей директории имеют больший приоритет, но поиск производится и в директории с исполняемым файлом приложения.
Если конфигурационный файл был найден в процессе инициализации библиотеки (terminal_open), то параметры некоторых специальных секций могут быть использованы для начальной настройки.
Параметры из секции “BearLibTerminal” применяются в качестве общей конфигурации, как будто бы они были указаны в вызове функции set. Параметры логгирования применяются первыми, остальные параметры группируются и каждая группа применяется отдельно (таким образом, если в процессе возникает ошибка, это не приводит к отмене всей конфигурации).
Параметры секции “Palette” будут добавлены к списку именованных цветов. Значения цвета разбираются функцией color from name.