BearLibTerminal / API / Конфигурация

===== ==== Функции ==== Конфигурирование и работа с настройками выполняется при помощи функций [[#set]] и [[#get]], а также посредством [[#конфигурационный_файл|конфигурационного файла]]. === set === Это, вероятно, самая сложная функция в 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 |80x25 |Размер окна в знакоместах. | |::: |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” будет дописывать в конец файла. | {{anchor:font_and_tileset_management:}} == Управление шрифтами и тайлсетами == Помимо нескольких фиксированных групп параметров библиотеки, может быть сконфигурировано неопределенное количество групп параметров, описывающих отдельный шрифт, тайл или тайлсет (см. [[..:design#tiles_and_slots|дизайн: тайлы и слоты]]) в следующем формате: [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;

== name == Строка, опциональное и произвольное наименование альтернативного шрифта, например 'italic' или 'runic'. Такие именованные шрифты будут доступны в функции print посредством тега ''[font=name]'': terminal_print(2, 1, "Its eyes are [font=italic]glowing[/font]."); == offset == Число, код одиночного тайла или точка отсчета для кодов в тайлсете (при offset равном 0xE000 первый тайл будет иметь код 0xE000, второй 0xE001 и т. д.). Все "символы", "тайлы" и "спрайты" находятся в одном кодовом пространстве: библиотека оперирует кодами символов Юникода и не учитывает что именно изображено на соответствующей коду символа картинке, будь то буква, пиктограмма или фон для экрана меню. Таким образом, можно осознанно или нечаянно переопределить внешний вид символов: terminal_set("0x40: at.png, align=center"); // Replace '@' (ASCII code 0x40) with a better version. Если такое переопределение нежелательно, то рекомендуется использовать для пиктограмм и прочей несимвольной графики специально выделенный блок Юникода: [[https://en.wikipedia.org/wiki/Private_Use_Areas|Unicode Private Use Area]] (коды 0xE000-0xEFFF). == resource == Строка, описывающая источник данных шрифта или тайлсета. Это может быть имя файла шрифта или картинки или дескриптор блока памяти в формате ''адрес:размер'': 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); == params == Состав параметров в группе и их смысл отличается в зависимости от типа шрифта/тайлсета: ^Тип ^Параметр ^По умолчанию ^Краткое описание ^ |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 |1''x''1 |Размер ячейки выравнивания, в знакоместах. | |::: |transparent |auto |Цвет фона для форматов/изображений, не поддерживающих прозрачность. | |TrueType |size | |Размер шрифта или тайла, под который будет подогнан размер шрифта; это обязательный параметр. | |::: |size-reference |'@' |Символ, используемый в качестве основы при подгонке размера шрифта под размер тайла. | |::: |mode |normal |Режим растеризации шрифта: "monochrome", "normal" или "lcd". | |::: |codepage | |Инвертированная кодовая таблица для загрузки только конкретных глифов. | |::: |align |center |Выравнивание тайла в ячейке, то же самое, что и для растровых тайлсетов. | |::: |spacing |1''x''1 |Размер ячейки выравнивания, то же самое, что и для растровых тайлсетов. | Параметры шрифта/тайлсета устанавливаются и заменяются все разом. Все необходимые параметры конкретного тайлсета должны быть указаны в одном вызове функции **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" конфигурационного файла: Если указанного параметра или секции в файле нет, они будут добавлены. Для того, чтобы удалить параметр из файла, нужно указать пустое значение. Как следствие, программно установить пустое значение невозможно; вместо этого используйте осмысленное значение по умолчанию для соответствущего параметра. === get === Эта функция возвращает значение параметра (опция библиотеки или из конфигурационного файла). Если такой параметр не найден, возвращается переданное в функцию значение-заглушка: const char* tile_size = terminal_get("ini.game.tile-size", "24"); На данный момент только опции библиотеки и параметры из конфигурационного файла могут быть прочитаны таким образом. Чтение свойств шрифтов и тайлсетов пока не поддерживается. В интерфейсе С/С++, память возвращаемой строки принадлежит библиотеке и указатель на нее останется валидным до следующего вызова **get** с тем же именем параметра. Возвращаемое значение всегда будет корректной строкой, даже если значение-заглушка не было указано (в этом случае будет возвращена пустая строка). ==== Конфигурационный файл ==== С версии 0.12, возможно использование специального конфигурационного файла для задания некоторой начальной конфигурации библиотеки, а также в качестве хранилища произвольных параметров приложения. Файл должен быть в обычном [[http://en.wikipedia.org/wiki/INI_file|INI-формате]] с некоторыми особенностями: * Для комментирования могут использоваться символы ''#'' и '';''. Строки, начинающиеся с пробела/табуляции также игнорируются. * Имена секций и свойств нечуствительны к регистру (но библиотека сохранит регистр при модификации значений). * Допускается повтор секций. * Библиотека не понимает привычное экранирование посредством слеша: "\n" это строка из двух обычных символов. * Пробелы вокруг имени свойства и его значения игнорируются. * Строка может содержать группу параметров в стиле вызова **set** (см. [[#формат_конфигурационной_строки|формат конфигурационной строки]]). Примером конфигурационного файла может быть:

# Комментарий
; Еще один комментарий
  Это строка тоже будет считаться комментарием

[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] === Параметры из секции "BearLibTerminal" применяются в качестве общей конфигурации, как будто бы они были указаны в вызове функции [[#set]]. Параметры логгирования применяются первыми, остальные параметры группируются и каждая группа применяется отдельно (таким образом, если в процессе возникает ошибка, это не приводит к отмене всей конфигурации). === [Palette] === Параметры секции "Palette" будут добавлены к списку именованных цветов. Значения цвета разбираются функцией [[ru:bearlibterminal:reference#color_from_name|color from name]].