BearLibTerminal / API

===== Некоторые части библиотеки описаны более подробно на отдельных страницах (в процессе): * [[.:reference:configuration|Конфигурирование]] * [[.:reference:input|Ввод]] * [[.:reference:output|Вывод]] API библиотеки состоит из ~20 функций и набора констант. * Инициализация и конфигурирование: [[#open]], [[#close]], [[#set]] * Параметры вывода: [[#color]], [[#bkcolor]], [[#composition]], [[#layer]] * Вывод: [[#clear]], [[#clear area]], [[#crop]], [[#refresh]], [[#put]], [[#pick]], [[#pick color]], [[#pick bkcolor]], [[#put ext]], [[#print]], [[#measure]] * Ввод: [[#state]], [[#check]], [[#has input]], [[#read]], [[#peek]], [[#read str]] * Вспомогательные: [[#delay]], [[#color from name]], [[#color from argb]] Так как библиотека предоставляет по возможности не зависящий от конкретного языка программирования набор вызовов, качественный и количественный состав функций, доступных в том или ином языке, немного отличается. На данной странице API описывается кратко и, в основном, с точки зрения С/С++. Специфичные различным языкам программирования нюансы будут описаны на отдельных страницах (что пока не готово). ==== open ==== int terminal_open(); Эта функция инициализирует библиотеку, применяя настройки по умолчанию: окно размером 80x25 знакомест, растровый шрифт Fixedsys Excelsior (встроенный), белый текст на черном фоне. Вызов этой функции не выводит окно на экран, оно не будет показано до первого вызова функции [[#refresh]]. Функция возвращает логически булево значение, где false (ноль) означает, что инициализация не удалась по той или иной причине. Детали ошибки могут быть найдены в лог-файле (по умолчанию это файл bearlibterminal.log). ==== close ==== void terminal_close(); Симметрично [[#open]], эта функция закрывает окно и деинициализирует библиотеку. ==== set ==== int terminal_set(const char* s); // + варианты setf, wset и wsetf с использованием wchar_t и/или форматирования Это, вероятно, самая сложная функция в API. Конфигурирование опций библиотеки, управление шрифтами и тайлсетами и даже конфигурационным файлом производится с ее помощью. Функция принимает "конфигурационную строку" со списком различных параметров:


window.title='game';
font: UbuntuMono-R.ttf, size=12;
ini.settings.tile-size=16;

Информацию о формате передаваемой строки, списке возможных опций и поведении функции см. на отдельной странице о [[.:reference:configuration|конфигурации]]. ==== color ==== void terminal_color(color_t color); Эта функция устанавливает текущий цвет вывода текста/тайлов. Тип **color_t** -- это 32-битное целое число, представляющее цвет в формате BGRA (0xAARRGGBB). Такое численное представление может быть сконструировано вручную или посредством вызова функций [[#color from argb]] и [[#color from name]]. Для большинства языков программирования включая С++, есть перегруженные варианты функции **color**, принимающие строку с названием цвета (см. [[#color from name]]). Текущий цвета текста может быть получен посредством свойства TK_COLOR (см. [[#state]]). ==== bkcolor ==== void terminal_bkcolor(color_t color); Аналогично [[#color]], эта функция устанавливает текущий цвет фона. Только первый, самый нижний [[#layer|слой]] имеет фон. Текущий цвет фона может быть получен посредством свойства TK_BKCOLOR (см. [[#state]]). ==== composition ==== void terminal_composition(int mode); Эта функция устанавливает режим композиции. Когда композиция отключена (по умолчанию это так), установка нового тайла в ячейку посредством функций [[#put]] или [[#print]], полностью заменяет содержимое этой ячейки. Когда композиция включена, тайл добавляется поверх уже имеющихся в ячейке тайлов, что выглядит как комбинирование нескольких тайлов. Количество тайлов в одной ячейке ничем специально не ограничивается, и каждый тайл в получаемой "стопке" может иметь индивидуальные цвет и смещение (см. [[#put ext]]). Значением параметра **mode** может быть //TK_OFF// или //TK_ON//. Текущее значение режима композиции можно получить посредством свойства TK_COMPOSITION (см. [[#state]]). ==== layer ==== void terminal_layer(int layer); Эта функция устанавливает текущий слой ячеек. Аргументом функции должно являться число от 0 до 255, где 0 -- это самый нижний слой, выбранный по умолчанию. Только этот первый слой имеет фон, для слоев 1 и выше цвет фона, установленный функцией [[#bkcolor]], не учитывается. Нужно помнить, что [[#clear area]] работает с текущим выбранным слоем, тогда как [[#clear]] очищает всю сцену целиком. Слои полезны по нескольким причинам. Одна из них заключается в том, что библиотека BearLibTerminal позволяет использовать тайлы размером больше одной ячейки. Учитывая, что ячейки отрисовываются строго слева направо и сверху вниз, оказывается невозможно расположить больший по размеру тайл таким образом, чтобы он закрывал ячейки правее и ниже, ведь те ячейки гарантированно будут отрисованы позднее. Разделив сцену на несколько слоев, можно обеспечить желаемый порядок отрисовки. Еще одним применением слоев может быть логическое разделение сцены. Слои могут быть очищены и/или изменены независимо друг от друга, что позволяет обновлять части сцены (такие как игровой уровень или интерфейс) независимо друг от друга. Текущий номер слоя может быть получен посредством свойства TK_LAYER (см. [[#state]]). ==== clear ==== void terminal_clear(); Эта функция очищает всю сцену (все [[#layer|слои]]). Она также устанавливает цвет фона каждой ячейки нижнего, нулевого слоя в текущий выбранный цвет фона. ==== clear_area ==== void terminal_clear_area(int x, int y, int w, int h); Эта функция очищает часть текущего выбранного [[#layer|слоя]]. Аргументы функции указывают верхний левый угол и размеры прямоугольной области, которая будет очищена. Будучи вызванной на нулевом слое, функция также устанавливает цвет фона ячеек указанной области в текущий выбранный цвет фона. ==== crop ==== void terminal_crop(int x, int y, int w, int h); Эта функция устанавливает область кропа текущего слоя: все, что выходит за пределы указанной области в соответствующем слое, выведено не будет. Размеры области указываются в знакоместах. Для сброса кропа в слое нужно или установить высоту или ширину области нулевой или очистить всю сцену посредством [[#clear]]. ==== refresh ==== void terminal_refresh(); Эта функция применяет произведенные над сценой изменения и перерисовывает содержимое окна. BearLibTerminal не выводит тайлы на экран немедленно при вызове функций [[#put]] или [[#print]]. Вместо этого сцена конструируется в памяти по аналогии с двойной буферизацией. В случае, если содержимое окна по каким-то причинам будет испорчено и запрошено операционной системой заново, библиотека автоматически отрисует последнюю примененную копию сцены. Первый вызов этой функции с момента инициализации библиотеки выводит на экран окно псевдотерминала. Между вызовом [[#open]] и первым вызовом **refresh** окно на экране не отображается. ==== put ==== void terminal_put(int x, int y, int code); Эта функция помещает тайл, ассоциированный с указанным кодом, в ячейку с координатами **x**, **y**. Если указанный код не соответствует ни одному загруженному тайлу, будет использован тайл "отсутствие символа" в виде прямоугольной рамки. Коды символов должны выбираться из Юникода. Даже если установленный основной шрифт выполнен в кодовой странице ANSI или аналогичной, библиотека сопоставляет отдельные символы кодам Юникода. К примеру знак "евро" (если он вообще присутствует в шрифте) всегда будет иметь код U+20AC, кроме случаев некорректной настройки шрифта при его загрузке. ==== put_ext ==== void terminal_put_ext(int x, int y, int dx, int dy, int code, color_t* corners); Эта функция является расширенной версией [[#put]], позволяя также указать смещение тайла относительно ячейки и/или задать отдельные цвета для каждого из углов тайла. Параметры **dx** и **dy** задают смещение тайла в пикселях относительно его нормального положения в ячейке. При включенной [[#composition|композиции]] в ячейке может быть более одного тайла и каждый из них может иметь свое собственное смещение. Важным моментом является то, что смещение в ячейке никак не влияет на порядок вывода тайлов (ячейка за ячейкой, слева направо, сверху вниз). Даже если визуально тайл находится правее или ниже ячейки, в которой он расположен, он будет отрисован в обычном порядке и будет перекрыт другими тайлами, реально расположенными правее или ниже. Если такое поведение нежелательно, следует использовать [[#layer|слои]]. Параметр **corners** должен указывать на массив из четырех **color_t**, описывающих цвета углов тайла в порядке против часовой стрелки, начиная с верхнего левого. Возможность указать цвета углов позволяет выводить тайлы с плавным градиентом или переходом. Также как и со смещением, каждый тайл в ячейке может иметь свой набор цветов. Если вместо массива передать NULL, для вывода тайла будет использован текущий цвет переднего плана. ==== pick ==== int terminal_pick(int x, int y, int index); Эта функция возвращает код символа или тайла из ячейки с указанными координатами в текущем [[#layer|слое]]. Параметр **index** указывает порядковый номер символа/тайла для случая, если в ячейке их находится несколько. Если в ячейке нет тайла с таким порядковым номером или в ячейке вообще ничего нет, возвращается 0. Таким образом, для того, чтобы выбрать все содержимое ячейки, необходимо увеличивать параметр **index** до тех пор, пока функция **pick** не вернет 0. Функция производит обратную трансляцию кода символа в соответствии с параметром //terminal.encoding//. ==== pick_color === color_t terminal_pick_color(int x, int y, int index); Функция, дополняющая [[#pick]], позволяющая узнать цвет определенного символа или тайла в ячейке. ==== pick_bkcolor === color_t terminal_pick_bkcolor(int x, int y); Функция, дополняющая [[#pick]], позволяющая узнать цвет фона ячейки. ==== print ==== void terminal_print(int x, int y, const char* s); // + варианты printf, wprint and wprintf с использованием wchar_t и/или форматирования Эта функция выводит строку начиная с указанных координат. Каждый отдельный символ помещается на сцену аналогично использованию вызовов [[#put]]([[#put ext|_ext]]), т. е. с учетом выбранных цветов [[#color|переднего]] и [[#bkcolor|заднего]] плана, текущего [[#layer|слоя]] и режима [[#composition|композиции]]. Поведение **print** может быть расширено посредством использования "тегов" в выводимой строке: * Цвета: ''[color=red]'' или ''[bkcolor=gray]'', при этом названия цветов разбираются функцией [[#color from name]]. * Произвольные коды символов: ''[U+E001]'' или ''[0xE001]''. * Комбинирование символов: ''a[+]^'' приведет к выводу, похожему на ''â''. Комбинирование производится размещением обоих тайлов в одной ячейке со временно задействованной композицией. * Пиксельное смещение: ''[offset=4,8]''. Добавляет смещение отдельно к каждому выводимому символу. * Выравнивание: ''[align=bottom-right]''. Задает расположение текста относительно указанной стартовой точки. * Область вывода: ''[bbox=16]'' or ''[bbox=32x5]''. Библиотека постарается вывести строку в указанных пределах, с автопереносом если потребуется. * Альтернативный шрифт: ''[font=0xE000]'' //(потребует отдельного объяснения)//. Теги color, bkcolor, offset и font могут быть отменены размещением симметричного "закрывающего" тега, например ''[/color]'' или ''[/offset]''. Теги могут комбинироваться в произвольном порядке, однако вложенность тегов одного типа не поддерживается: каждый открывающий тег полностью заменяет предыдущие такого же типа, каждый закрывающий -- отменяет все эффекты тега этого типа. Закрывать все использованные в строке теги необязательно, так как их эффекты распространяются только на конкретный вызов функции **print**. terminal_printf("[offset=%d,%d]g[+][color=red]^[/color] (red-hooded goblin)", dx, dy); Для вывода одинарной квадратной скобки следует продублировать ее в строке. Функция возвращает размер выводимой на экран строки с учетом примененного форматирования. По умолчанию **print** вернет ширину строки. Если строка содержит тег bbox, тогда максимальная ширина строки уже известна и **print** вернет высоту выведенной строки с учетом автопереноса. ==== measure ==== void terminal_measure(const char* s); // + варианты terminal_[w]measure[f] Эта функция рассчитывает размер (высоту или ширину в зависимости от присутствия тега bbox, см. [[#print]]), не выводя строку на экран. ==== state ==== int terminal_state(int slot); Эта функция возвращает текущее состояние некоторого свойства или состояния библиотеки: текущий выбранный цвет, размер окна или знакоместа, состояние клавиши и т. д. Значения большинства свойств обновляются в процессе чтения событий ввода посредством функции [[#read]], сохраняя строгую очередность изменения и согласованность во времени. Например, подобная проверка нажатия комбинации клавиш будет работать корректно даже если к моменту выполнения кода клавиши уже были отжаты: int key = terminal_read(); if (key == TK_A) { if (terminal_state(TK_SHIFT)) { // Shift+A } else { // Просто A } } Поведение функции **state** и очереди ввода описано более подробно на отдельной, посвященной вводу [[.:reference:input|странице]]. Там же приведен список всех свойств, которые можно запросить с помощью данной функции. ==== check ==== int terminal_check(int slot); Это простая обертка над функцией [[#state]]. Она возвращает (логически) булево значение, указывающее на ненулевое значение свойства. Во многих языках программирования нельзя непосредственно сравнивать значения численного и булевого типа, из-за чего проверка логически булевых состояний с постоянным приведением типов может быстро надоесть. Вместо этого можно использовать **check** для проверки логических свойств -- таких, как факт нажатия клавиши. Эта обертка добавлена в заголовочный файл С/С++ в основном для большей целостности. ==== has_input ==== int terminal_has_input(); Эта функция возвращает булево значение, сигнализирующее наличие доступных событий ввода в очереди. Возврат //true// функцией **has_input** гарантирует, что следующий вызов [[#read]] вернет результат сразу же, не блокируя выполнение программы. ==== read ==== int terminal_read(); Эта функция возвращает следующее событие из очереди ввода: int key = terminal_read(); if (key == TK_ESCAPE) { // Выход } Если в очередь ввода пуста, вызов заблокирует выполнение до поступления нового события. Если такое блокируещее поведение нежелательно, можно проверить [[#has input]] перед вызовом **read**. ==== peek ==== int terminal_peek(); Эта функция аналогична [[#read]], но не убирает прочитанное событие из внутренней очереди (следующий вызов **peek** или **read** вернет то же значение). Кроме того, вызов этой функции является неблокирующим: если очередь ввода пуста, функция вернет 0. ==== read_str ==== color_t terminal_read_str(int x, int y, char* buffer, int max); // + вариант read_wstr для wchar_t Эта функция выполняет простое блокирующее чтение строки без какого-либо разбора введенного значения. В процессе выполнения вызова, пользовательский ввод отображается по указанным координатам и ограничивается по размеру и может быть легко вписан в интерфейс игры. Функция отображает ввод в текущем выбранном слое и полностью восстанавливает исходное состояние сцены перед выходом, оставляя сохранение введенной строки на экране на усмотрение приложения. Функция возвращает размер строки, введенной пользователем и подтвержденной нажатием на Enter, или константу TK_INPUT_CANCELLED, если ввод был отменен нажатием на Escape или вовсе попыткой закрытия окна. wchar_t s[32] = L"Привет"; if (terminal_read_wstr(2, 1, s, sizeof(s)-1) >= 0) { terminal_wprintf(L"Вы ввели: \"%ls\"", s); } Если поведение **read_str** не удовлетворяет требованиям конкретного приложения, можно использовать свойства [[.:reference:input#свойства_tk_char_tk_wchar|TK CHAR/TK WCHAR]], позволяющие реализовать произвольный ввод строки. ==== delay ==== void terminal_delay(int period); Эта функция предоставляет кроссплатформенный вызов, приостанавливающий выполнение текущего потока на указанное количество миллисекунд. ==== color_from_name ==== color_t color_from_name(const char* name); // + вариант color_from_wname для wchar_t Эта функция возвращает численное представление цвета по его имени во встроенной палитре или текстовому представлению. Имя задается в формате "[яркость ]оттенок", например "red", "light green" или "darker #905025". Возможные значения яркости: lightest, lighter, light, dark, darker, darkest. Оттенок (базовый цвет) может быть указан несколькими способами: * По имени: grey (или gray), red, flame, orange, amber, yellow, lime, chartreuse, green, sea, turquoise, cyan, sky, azure, blue, han, violet, purple, fuchsia, magenta, pink, crimson, transparent. * В шестнадцатиричном формате: #RRGGBB or #AARRGGBB, например #80905025 * В десятичном формате, разделенном запятыми: R,G,B or A,R,G,B например 128,200,150,75 * Как форматированное в строку целое число, например 16744448 Новые именованные цвета могут быть добавлены в палитру вызовом [[#set|set]]: terminal_set("palette.octarine = #50FF25"); Или посредством [[.:reference:configuration_|конфигурационного файла]]:


[Palette]
lush = dark 80,255,37

Функция [[#print]] использует **color_from_name** для разбора названий цветов в тегах. ==== color_from_argb ==== color_t color_from_argb(uint8_t alpha, uint8_t red, uint8_t green, uint8_t blue); Эта функция является простой утилитой для сборки четырех отдельных 8-битных значений в 32-битное.