BearLibTerminal — различия между версиями

Материал из Клуб любителей рогаликов
Перейти к: навигация, поиск
Строка 56: Строка 56:
 
Симметричный <code>terminal_open</code> вызов, закрывающий терминал и освобождающий используемые библиотекой ресурсы. Поведение программы, не вызвавшей terminal_open перед своим завершением, неопределено.
 
Симметричный <code>terminal_open</code> вызов, закрывающий терминал и освобождающий используемые библиотекой ресурсы. Поведение программы, не вызвавшей terminal_open перед своим завершением, неопределено.
 
=== terminal_set ===
 
=== terminal_set ===
 +
Данная функция представляет собой универсальный способ задания разнообразных настроек библиотеки и описания используемых тайлсетов. Опции задаются в виде строки с группами значений в следующем формате: <code>group1.option1=value1; group1.option2=value2; ...</code> Эта запись может быть сокращена до: <code>group1: [option1=]value1, option2=value2; ...</code> Например:
 +
<source lang="cpp">
 +
terminal_set("window.size=80x25; window.title='Заголовок'");
 +
terminal_set("window: size=80x25, title='Заголовок'");
 +
</source>
 +
 +
Динамическая библиотека предоставляет три варианта для строки из 8, 16 и 32-битных символов: terminal_set8, terminal_set16 и terminal_set32. Детали о разрядности символов должны быть скрыты хедером для конкретного языка программирования с учетом разрядности исрользуемых в языке строк. Например, для С/С++ этот вызов доступен в виде следующих функций:
 
<source lang="cpp">
 
<source lang="cpp">
 
int terminal_set(const char* s);
 
int terminal_set(const char* s);
 +
int terminal_wset(const wchar_t* s);
 +
</source>
 +
Кроме того, хедер для C/C++ предоставляет варианты с printf-подобным форматированием строки:
 +
<source lang="cpp">
 +
int terminal_setf(const char* s, ...);
 +
int terminal_wsetf(const wchar_t* s, ...);
 
</source>
 
</source>
Данная функция представляет собой универсальный способ задания разнообразных настроек библиотеки. Опции задаются в виде строки с парами параметр-значение, разделенными точкой с запятой:<br/>
 
<code>option1=value1; option2=value2; ...</code>
 
 
В библиотеке имеются два варианта функции, с суффиксом "noformat" и без. Вариант без суффикса (с переменным числом аргументов) позволяет использовать в С/С++ привычное форматирование передаваемой строки:
 
<syntaxhighlight lang="cpp">
 
terminal_options("size=%dx%d", width, height);
 
</syntaxhighlight>
 
Вариант с суффиксом "noformat" не производит подобного форматирования и может быть использован при вызове функций из программы, написанной на других языках программирования, предоставляющих собственные механизмы форматирования строк.
 
 
==== Перечень доступных параметров ====
 
==== Перечень доступных параметров ====
 
{| class="wikitable"
 
{| class="wikitable"
Строка 74: Строка 79:
 
|Описание
 
|Описание
 
|-
 
|-
|colspan="3" style="background-color: #dddddd;"|''Настройки окна''
+
|colspan="3" style="background-color: #dddddd;"|''Настройки окна, группа атрибутов '''window'''''
 
|-
 
|-
 
|size
 
|size
 
|80x25
 
|80x25
|Размер окна терминала в знакоместах, в формате ''ШИРИНА''x''ВЫСОТА''.
+
|Размер окна терминала в знакоместах в формате <ширина>x<высота>.
 +
|-
 +
|cellsize
 +
|auto
 +
|Размер ячейки знакоместа, в пикселях в формате <ширина>x<высота> или auto
 
|-
 
|-
 
|title
 
|title
Строка 88: Строка 97:
 
|Имя <tt>.ico</tt>-файла с иконкой, которая будет использована для окна.
 
|Имя <tt>.ico</tt>-файла с иконкой, которая будет использована для окна.
 
|-
 
|-
|colspan="3" style="background-color: #dddddd;"|''Настройки шрифта''
+
|colspan="3" style="background-color: #dddddd;"|''Настройки ввода, группа атрибутов '''input'''''
|-
 
|font.name
 
|default
 
|Имя файла шрифта, векторного <tt>.ttf</tt> или тайлового <tt>.bmp</tt>/<tt>.png</tt>
 
|-
 
|font.size
 
|10
 
|Размер шрифта: высота символа для векторного шрифта, размер одного тайла для тайлового шрифта.
 
|-
 
|font.mode
 
|normal
 
|Режим растеризации при использовании векторного шрифта: <tt>monochrome</tt>, <tt>normal</tt> или <tt>lcd</tt>.
 
|-
 
|font.codepage
 
|utf-8
 
|Кодовая страница тайлового шрифта.
 
|-
 
|colspan="3" style="background-color: #dddddd;"|''Настройки ввода''
 
 
|-
 
|-
|input.events
+
|events
 
|keypress
 
|keypress
 
|Фильтр событий ввода, комбинация из флагов <tt>none</tt>, <tt>keypress</tt>, <tt>keyrelease</tt>, <tt>mousemove</tt>, <tt>mousescroll</tt>, <tt>all</tt>.
 
|Фильтр событий ввода, комбинация из флагов <tt>none</tt>, <tt>keypress</tt>, <tt>keyrelease</tt>, <tt>mousemove</tt>, <tt>mousescroll</tt>, <tt>all</tt>.
 
|-
 
|-
|input.timeout
+
|nonblocking
|infinite
+
|false
|Таймаут ожидания события ввода: <tt>infinite</tt>, <tt>immediate</tt> или численное значение в миллисекундах.
+
|Если выставлен в true, вызовы terminal_read[_xxx] не приостанавливают выполнение программы, если очередь ввода пуста.
 
|-
 
|-
|input.precise_mousemove
+
|precise-mousemove
 
|false
 
|false
 
|Флаг, указывающий, будет ли считаться движением мыши попиксельное (true) или познакоместное (false) перемещение указателя.
 
|Флаг, указывающий, будет ли считаться движением мыши попиксельное (true) или познакоместное (false) перемещение указателя.
 
|-
 
|-
|input.cursor_symbol
+
|sticky-close
 +
|true
 +
|Если выставлен в false, то по закрытию окна событие VK_CLOSE генерируется однократно. Если выставлен в true, то по закрытию окна terminal_read будет постоянно возвращать VK_CLOSE.
 +
|-
 +
|cursor-symbol
 
|95 (ASCII 0x5F, подчеркивание)
 
|95 (ASCII 0x5F, подчеркивание)
|Код символа, используемого в качестве курсора в terminal_get_str.
+
|Код символа, используемого в качестве курсора в terminal_read_str.
 
|-
 
|-
|input.cursor_blink_rate
+
|cursor-blink-rate
 
|500
 
|500
|Скорость мерцания курсора в terminal_get_str, в миллисекундах.
+
|Скорость мерцания курсора в terminal_read_str, в миллисекундах.
 
|-
 
|-
|colspan="3" style="background-color: #dddddd;"|''Настройки вывода''
+
|colspan="3" style="background-color: #dddddd;"|''Настройки вывода, группа атрибутов '''output'''''
 
|-
 
|-
|output.postformat
+
|postformatting
 
|true
 
|true
 
|Флаг, включающий или выключающий постформатирование при выводе текста.
 
|Флаг, включающий или выключающий постформатирование при выводе текста.
 
|-
 
|-
|colspan="3" style="background-color: #dddddd;"|''Настройки логгирования''
+
|vsync
 +
|true
 +
|Флаг, включающий или выключающий вертикальную синхронизацию при отрисовке.
 +
|-
 +
|colspan="3" style="background-color: #dddddd;"|''Настройки растрового тайлсета, группа атрибутов '''font''' или '''U+xxxx'''''
 +
|-
 +
|name
 +
|
 +
|Описательное имя растрового ресурса: имя файла или адрес памяти.
 +
|-
 +
|size
 +
|
 +
|Размер одиночного тайла в пикселях в формате <ширина>x<высота>. Необязательный атрибут, если он не указан, считается что все изображение это один тайл.
 +
|-
 +
|resize
 +
|
 +
|Размер, до которого нужно переразмерить растровое изображение. Необязательный атрибут.
 +
|-
 +
|resize-filter
 +
|bilinear
 +
|Фильтр, который будет использован при переразмерении изображения. Возможные варианты: nearest, bilinear, bicubic.
 
|-
 
|-
|log.file
+
|resize-mode
 +
|stretch
 +
|Режим переразмерения. Возможные варианты: stretch (растянуть), fit (вписать по большей стороне), crop (вписать по меньшей стороне).
 +
|-
 +
|raw-size
 +
|
 +
|Размер исходного изображения в случае загрузки из памяти. Если этот атрибут не указан, используется значение атрибута ''size'' (и считается, что все изображение это один тайл).
 +
|-
 +
|codepage
 +
|ascii
 +
|Кодовая таблица соответствия отдельных тайлов в тайлсете кодам Unicode. Возможные варианты: ascii, utf8, 437, 866, 1250, 1251 или имя файла с таблицей.
 +
|-
 +
|align
 +
|
 +
|Точка отсчета координат для центрирования тайла в ячейке. Возможные значения: center, top-left, top-right, bottom-left, bottom-right. Необязательный атрибут, для тайлсетов из одного тайла (спрайтов) используется top-left, для тайлсетов из нескольких тайлов (шрифтов) используется center.
 +
|-
 +
|bbox
 +
|1x1
 +
|Размер логической ячейки, в которой выполняется центрирование тайла, в знакоместах.
 +
|-
 +
|transparent
 +
|
 +
|Цвет прозрачного фона для изображений без альфа-канала. Необязательный атрибут (и вообще используйте PNG).
 +
|-
 +
|colspan="3" style="background-color: #dddddd;"|''Настройки TrueType тайлсета, группа атрибутов '''font''' или '''U+xxxx'''''
 +
|-
 +
|name
 +
|
 +
|Имя .ttf-файла шрифта
 +
|-
 +
|size
 +
|
 +
|Размер шрифта: либо средняя высота строчного символа в пикселях, либо размер ячейки в пикселях для автоматического подбора размера шрифта.
 +
|-
 +
|size-reference
 +
|@
 +
|Необязательный атрибут. Код символа, используемого для оценки/подбора размера шрифта.
 +
|-
 +
|mode
 +
|normal
 +
|Режим растеризации. Возможные варианты: <tt>monochrome</tt>, <tt>normal</tt> или <tt>lcd</tt>.
 +
|-
 +
|codepage
 +
|utf-8
 +
|Кодовая таблица нестандартного соответствия кодов Юникода и символов шрифта.
 +
|-
 +
|align
 +
|center
 +
|Точка отсчета координат для центрирования символа в ячейке. Возможные значения: center, top-left, top-right, bottom-left, bottom-right.
 +
|-
 +
|bbox
 +
|1x1
 +
|Размер логической ячейки, в которой выполняется центрирование тайла, в знакоместах.
 +
|-
 +
|colspan="3" style="background-color: #dddddd;"|''Настройки логгирования, группа атрибутов '''log'''''
 +
|-
 +
|file
 
|bearlibterminal.log
 
|bearlibterminal.log
|Имя файла, куда в библиотека будет писать свой лог. Файл не ротируется, логгирование попросту производится в конец указанного файла.
+
|Имя файла, куда в библиотека будет писать свой лог.
 
|-
 
|-
|log.level
+
|level
 
|error
 
|error
 
|Уровень важности логгирования: <tt>none</tt>, <tt>fatal</tt>, <tt>error</tt>, <tt>warning</tt>, <tt>info</tt>, <tt>debug</tt>, <tt>trace</tt>
 
|Уровень важности логгирования: <tt>none</tt>, <tt>fatal</tt>, <tt>error</tt>, <tt>warning</tt>, <tt>info</tt>, <tt>debug</tt>, <tt>trace</tt>
 +
|-
 +
|mode
 +
|truncate
 +
|Режим ведения лога. Возможные варианты: truncate (начинать файл заново при каждом новом старте) и append (дописывать в конец файла).
 
|}
 
|}
==== Настройки окна ====
 
''<подробно про настройки окна>''
 
==== Настройки шрифта ====
 
''<подробно про настройки шрифта>''
 
==== Настройки ввода ====
 
''<подробно про настройки ввода>''
 
 
 
=== terminal_put ===
 
=== terminal_put ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
 
void terminal_put(int x, int y, int code);
 
void terminal_put(int x, int y, int code);
</syntaxhighlight>
+
</source>
Одна из основных функций библиотеки, позволяет вывести символ в знакоместо с указанными координатами.
+
Одна из основных функций библиотеки, позволяет вывести символ в знакоместо с указанными координатами. В зависимости от выбранного режима смешения, выводимый символ может заменить собой все содержимое указанного знакоместа или быть добавленным поверх уже имеющихся (см. <tt>[[#terminal_composition]]</tt>). Для ячеек первого слоя <tt>terminal_put</tt> применяет цвет фона.
 
 
Диапазон возможных для вывода кодов символов не ограничен выбранной при вызове <code>terminal_open</code> кодировкой (см. [[#Кодировки]]).
 
 
 
В зависимости от выбранного режима смешения, выводимый символ может заменить собой все содержимое указанного знакоместа или быть добавленным поверх уже имеющихся (см. <tt>[[#terminal_blending]]</tt>).
 
 
=== terminal_color ===
 
=== terminal_color ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
 
void terminal_color(color_t color);
 
void terminal_color(color_t color);
</syntaxhighlight>
+
</source>
Устанавливает основной цвет выводимого текста. Параметром функции является целое беззнаковое 32-битное число, представляющее цвет в формате ARGB, например 0xFFFF0000 -- сплошной красный, 0x800000FF -- полупрозрачный синий.
+
Устанавливает основной цвет выводимого текста (тайлов). Функция принимает целое беззнаковое 32-битное число, представляющее цвет в формате 0xAARRGGBB. В хедере для C++ имеется перегруженный вариант, принимающий строку с именем цвета.
  
 
См. [[#color_from_argb]], [[#color_from_name]], [[#Постформатирование]].
 
См. [[#color_from_argb]], [[#color_from_name]], [[#Постформатирование]].
 
=== terminal_bkcolor ===
 
=== terminal_bkcolor ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
 
void terminal_bkcolor(color_t color);
 
void terminal_bkcolor(color_t color);
</syntaxhighlight>
+
</source>
 
Аналогичная <code>terminal_color</code> функция, но устанавливающая цвет фона выводимых символов.
 
Аналогичная <code>terminal_color</code> функция, но устанавливающая цвет фона выводимых символов.
  
В зависимости от режима смешения, цвет фона может применяется к знакоместу только в случае, если символ является первым в знакоместе (см. <tt>[[#terminal_blending]]</tt>).
+
Цвет фона применяется к знакоместам только в первом слое (см. <tt>[[#terminal_layer]]</tt>).
=== terminal_blending ===
+
=== terminal_composition ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
void terminal_blending(int mode);
+
void terminal_composition(int mode);
</syntaxhighlight>
+
</source>
Функция устанавливает режим смешения для вывода символов: <code>BLENDING_NONE</code> или <code>BLENDING_ADDITIVE</code>.
+
Функция устанавливает режим наложения тайлов в одной ячейке: <code>TK_COMPOSITION_ON</code> или <code>TK_COMPOSITION_OFF</code>.
  
В режиме <code>BLENDING_NONE</code> выводимый символ полностью замещает содержимое соответствующего знакоместа, цвет фона устанавливается в выбранный посредством <tt>[[#terminal_bkcolor]]</tt> цвет. Это обычное поведение терминал-подобных приложений.
+
В режиме <code>TK_COMPOSITION_ON</code> выводимый символ полностью замещает содержимое соответствующего знакоместа, цвет фона устанавливается в выбранный посредством <tt>[[#terminal_bkcolor]]</tt> цвет. Это обычное поведение терминал-подобных приложений.
  
В режиме <code>BLENDING_ADDITIVE</code> выводимый символ "накладывается" на уже имеющиеся в ячейке символы, причем каждый отдельный символ в получившейся "стопке" может иметь индивидуальный цвет. Таким образом можно комбинировать глифы и/или тайлы для получения более сложных фигур. Цвет фона знакоместа обновляется только при выводе самого первого символа.
+
В режиме TK_COMPOSITION_OFF выводимый символ "накладывается" на уже имеющиеся в ячейке символы, причем каждый отдельный символ в получившейся "стопке" может иметь индивидуальный цвет. Таким образом можно комбинировать глифы и/или тайлы для получения более сложных фигур.
=== terminal_printf ===
+
=== terminal_print ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
// ANSI/UTF-8
+
int terminal_print(int x, int y, const char* s);
size_t terminal_printf(int x, int y, const char* format, ...);
+
</source>
size_t terminal_printf_noformat(int x, int y, const char* s);
+
Аналогично [[#terminal_set]], библиотека предоставляет несколько вариантов функции для строк различной разрядности, но хедер к С/С++ скрывает это и вызов доступен для char* и wchar_t* строк с форматированием и без: <code>terminal_[w]print[f]</code>
 +
В строке, передаваемой в функцию terminal_print могуть присутствовать теги постформатирования, модифицирующие производимый вывод:
 +
 
 +
Цвет текста и фона:<br />
 +
<code>terminal_print(2, 1, "[color=amber]Amber[/color] letters, [bkcolor=darkest gray]gray background[/bkcolor].");</code>
 +
 
 +
Произвольный символ:<br />
 +
<code>terminal_print(2, 1, "Earth rune: [U+E001]");</code>
  
// UTF-16
+
Комбинация символов:<br />
size_t terminal_wprintf(int x, int y, const wchar_t* format, ...);
+
<code>terminal_print(2, 1, "a[+]^");</code><br />
size_t terminal_wprintf_noformat(int x, int y, const wchar_t* s);
+
Такой тег комбинирует два тайла как будто бы они были положены в одну ячейку с включенным наложением (TK_COMPOSITION_ON).
</syntaxhighlight>
+
 
...
+
Межсимвольный интервал:<br />
 +
<code>terminal_print(2, 1, "[spacing=2x2]sparse text");</code><br />
 +
Межсимвольный/межстрочный интервал необходим для вывода текста тайлами размером более одного знакоместа.
 +
 
 +
Сдвиг кодовой страницы:<br />
 +
<code>terminal_print(2, 1, "[base=0xE000:1251]Русский текст");</code><br />
 +
Сдвиг страницы позволяет выводить текст тайлсетом в произвольной кодировке и загруженным по произвольному коду.
 
=== terminal_clear ===
 
=== terminal_clear ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
 
void terminal_clear();
 
void terminal_clear();
</syntaxhighlight>
+
</source>
Функция очистки экрана. Содержимое всех ячеек-знакомест удаляется, цвет фона устанавливается в выбранный посредством <tt>[[#terminal_bkcolor]]</tt> цвет.
+
Функция очистки экрана. Содержимое всех ячеек-знакомест во всех слоях удаляется, цвет фона устанавливается в выбранный посредством <tt>[[#terminal_bkcolor]]</tt> цвет.
 
=== terminal_clear_area ===
 
=== terminal_clear_area ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
 
void terminal_clear_area(int x, int y, int w, int h);
 
void terminal_clear_area(int x, int y, int w, int h);
</syntaxhighlight>
+
</source>
Функция частичной очистки экрана. Содержимое ячеек-знакомест в указанной области экрана удаляется, цвет фона устанавливается в выбранный посредством <tt>[[#terminal_bkcolor]]</tt> цвет.
+
Функция частичной очистки экрана. Удаляется содержимое ячеек-знакомест в указанной области экрана текущего слоя.
 
=== terminal_refresh ===
 
=== terminal_refresh ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
 
void terminal_refresh();
 
void terminal_refresh();
</syntaxhighlight>
+
</source>
Функция обновления экрана. Эта функция должна быть вызвана, чтобы изменения содержимого терминала на самом деле отобразились на экране.
+
Функция обновления экрана. Эта функция должна быть вызвана, чтобы изменения содержимого терминала на самом деле отобразились на экране. Окно терминала выводится на экран при первом вызове <code>terminal_refresh</code>.
 
 
Окно терминала инициализируется и выводится на экран при первом вызове <code>terminal_refresh</code>.
 
 
=== terminal_has_input ===
 
=== terminal_has_input ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
 
int terminal_has_input();
 
int terminal_has_input();
</syntaxhighlight>
+
</source>
 
Позволяет узнать, есть ли события в очереди ввода. Возвращает 0, если очередь пуста или 1, если есть непрочитанные события.
 
Позволяет узнать, есть ли события в очереди ввода. Возвращает 0, если очередь пуста или 1, если есть непрочитанные события.
 
+
=== terminal_read ===
См. [[#Ввод]]
+
<source lang="cpp">
=== terminal_get ===
+
int terminal_read();
<syntaxhighlight lang="cpp">
+
</source>
int terminal_get();
 
</syntaxhighlight>
 
 
Возвращает код следующего событие из очереди ввода.
 
Возвращает код следующего событие из очереди ввода.
  
Если очередь ввода пуста, поведение зависит от параметра ''input.timeout'':
+
Если очередь ввода пуста, поведение зависит от параметра ''input.nonblocking'':
* ''infinite'': выполнение программы блокируется до поступления следующего события ввода.
+
* ''false'': выполнение программы блокируется до поступления следующего события ввода.
* ''N'' (где N -- некоторое неотрицательное значение): выполнение программы блокируется до поступления события ввода, но не более чем на N миллисекунд, по истечении которых возвращается -1.
+
* ''true'': блокирования выполнения программы не производится, в случае пустой очереди ввода функция немедленно возвращает TK_INPUT_NONE.
 
 
Если ''input.timeout'' равен нулю, блокирования выполнения программы не производится, в случае пустой очереди ввода функция немедленно возвращает -1.
 
  
 
См. [[#Ввод]]
 
См. [[#Ввод]]
=== terminal_get_str ===
+
=== terminal_read_ext ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
int terminal_get_str(int x, int y, char* buffer, int max); // ANSI/UTF-8
+
int terminal_read_ext(int flags);
int terminal_get_wstr(int x, int y, wchar_t* buffer, int max); // UTF-16
+
</source>
</syntaxhighlight>
+
Расширенная версия чтения очереди ввода. Параметр ''flags'' может включать в себя следующие флаги:
Функция чтения текста с клавиатуры с учетом локалей и раскладок пользователя.
+
* TK_READ_CHAR: функция пытается выбрать из очереди текстовый символ. В случае, если следующее событие в очереди ввода не порождает тесктовый ввод, возвращается TK_INPUT_CALL_AGAIN.
 
+
* TK_READ_NOREMOVE: функция не убирает прочитанное событие из очереди. Следующий вызов вернет такое же значение.
В процессе работы функции ввод полностью обрабатывается терминалом. Набираемые пользователем символы добавляются к строке в буфере <code>buffer</code>, при этом максимальный размер получаемой строки ограничивается <code>max</code> символами. В это время содержимое строки и курсор ввода отображается в терминале начиная с позиции (<code>x</code>, <code>y</code>).
+
=== terminal_read_str ===
 
+
<source lang="cpp">
''TODO: картинка-иллюстрация''
+
int terminal_read_str(int x, int y, char* buffer, int max);
 
+
int terminal_read_wstr(int x, int y, wchar_t* buffer, int max);
Чтение очереди ввода функцией <code>terminal_get_str</code> производится до:
+
</source>
* Подтверждения ввода (поступления события VK_RETURN), функция возвращает количество введенных символов (может быть и 0).
+
Функция чтения текста с клавиатуры с учетом локалей и раскладок пользователя. Набираемые пользователем символы добавляются к строке в буфере <code>buffer</code>, при этом максимальный размер получаемой строки ограничивается <code>max</code> символами.
* Отмены ввода (поступления события VK_ESCAPE или VK_CLOSE), функция возвращает -2 (TERMINAL_INPUT_CANCELLED).
 
* Истечения отведенного промежутка времени (таймаута), функция возвращает -1 (TERMINAL_INPUT_TIMED_OUT).
 
 
 
Величина таймаута, в течении которого производится ввод и в течении которого вводимая строка отображается на экране зависит от значения параметра '''input.timeout''':
 
* ''infinite'': неограниченно, до поступления событий VK_RETURN, VK_ESCAPE или VK_CLOSE.
 
* ''N'' (где N -- некоторое неотрицательное значение): N миллисекунд.
 
 
 
Если ''input.timeout'' равен нулю, блокирования ввода и отображения вводимой строки на экране не производится, функция обрабатывает доступные сообщения в очереди ввода и немедленно завершается, возвращая одно из перечисленных выше значений.
 
 
 
По завершении, <code>terminal_get_str</code> убирает введенную строку и курсор ввода с экрана, восстанавливая предыдущее содержимое использованных ячеек-знакомест.
 
  
Иначе говоря, при значении ''input.timeout'' = ''infinite'' (значение по умолчанию), функция <code>terminal_get_str</code> производит чтение строки "до победного конца": до подтверждения или отмены ввода, полностью забирая на себя ответственность по отображению вводимого текста на экране. Пользователю библиотеки остается лишь проверить возвращенное значение и, в случае успешного завершения, использовать готовую строку в буфере <code>buffer</code>.
+
Поведение функции сильно зависит от параметра ''input.nonblocking''. Если он равен ''false'' (по умолчанию), то в процессе работы функции ввод полностью обрабатывается терминалом. В это время содержимое строки и курсор ввода отображается в терминале начиная с позиции (<code>x</code>, <code>y</code>). Чтение ввода функцией <code>terminal_read_str</code> в блокирующем режиме производится до:
 +
* Подтверждения ввода (поступления события TK_RETURN). Функция возвращает количество введенных символов (значение больше либо равное нулю).
 +
* Отмены ввода (поступления события TK_ESCAPE или TK_CLOSE). Функция возвращает TK_INPUT_CANCELLED.
 +
По завершении, <code>terminal_read_str</code> убирает введенную строку и курсор ввода с экрана, восстанавливая предыдущее содержимое использованных ячеек-знакомест.
  
Значение ''input.timeout'', равное или большее нуля, позволяет организовать "неблокирующий" ввод строки. Результат выполнения <code>terminal_getstr</code> появляется на экране на N миллисекунд, по истечении которых можно быстро обновить анимацию и продожить ввод дальше -- и так до тех пор, пока функция не вернет неотрицатильное значение (пользователь завершил ввод) или -2 (пользователь отменил ввод).
+
Если ''input.nonblocking'' равен ''true'' (неблокирующее чтение), функция <code>terminal_read_str</code> не трогает экран, а только производит чтение доступной очереди ввода. В неблокирующем режиме:
 +
* По подтверждению ввода (TK_RETURN) функция возвращает количество введенных символов.
 +
* По отмене ввода (TK_ESCAPE или TK_CLOSE) функция возвращает TK_INPUT_CANCELLED.
 +
* Если очередь ввода пуста, функция возвращает TK_INPUT_CALL_AGAIN.
 +
Задача отрисовки процесса ввода (текст, курсор) ложится на пользователя библиотеки.
  
Размер передаваемого в функцию буфера должен быть достаточно большим, чтобы вместить максимально возможную вводимую строку. Так как параметр max указывается в символах, это означает, что для вызова в кодировке UTF-8 (<code>terminal_get_str</code>) буфер должен быть размером не менее max*3+1 (каждый символ может занять до трех байт + нуль-терминатор), а для UTF-16 вызова (<code>terminal_get_wstr</code>) -- не менее max+1.
+
Размер передаваемого в функцию буфера должен быть достаточно большим, чтобы вместить максимально возможную вводимую строку. Так как параметр max указывается в символах, без учета нуль-терминатора, это означает, что для вызова в кодировке UTF-8 (<code>terminal_read_str</code>) буфер должен быть размером не менее max*3+1 (каждый символ может занять до трех байт + нуль-терминатор), а для UTF-16/32 вызова (<code>terminal_read_wstr</code>) -- не менее max+1.
  
 
См. [[#Ввод]]
 
См. [[#Ввод]]
 
=== terminal_state ===
 
=== terminal_state ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
 
int terminal_state(int code);
 
int terminal_state(int code);
</syntaxhighlight>
+
</source>
Данная функция позволяет получить текущее состояние некоторых переменных терминала. Код переменной берется из перечисления VK_xxx.
+
Данная функция позволяет получить текущее состояние некоторых переменных терминала. Код переменной берется из перечисления TK_xxx.
* Состояние клавиш: коды VK_ESCAPE, VK_0, VK_NUMPAD0, VK_A и т. д. Функция возвращает 1, если клавиша нажата или 0, если отпущена.
+
* Состояние клавиш: коды TK_ESCAPE, TK_0, TK_NUMPAD0, TK_A и т. д. Функция возвращает 1, если клавиша нажата или 0, если отпущена.
* Состояние мыши: VK_MOUSE_X и VK_MOUSE_Y (в знакоместах), VK_MOUSE_PIXEL_X, VK_MOUSE_PIXEL_Y (в пикселях), VK_MOUSE_WHEEL (в шагах колесика).
+
* Состояние мыши: TK_MOUSE_X и TK_MOUSE_Y (в знакоместах), TK_MOUSE_PIXEL_X, TK_MOUSE_PIXEL_Y (в пикселях), TK_MOUSE_WHEEL (в шагах колесика).
* Размеры знакоместа: VK_CELL_WIDTH и VK_CELL_HEIGHT (в пикселях).
+
* Размеры экрана в знакоместах: TK_WIDTH, TK_HEIGHT.
В зависимости от выбранного фильтра событий ввода (''input.events''), состояние клавиш и мыши возвращается не на момент вызова, а соответствующее текущему состоянию очереди ввода. Обновление значений, возвращаемых функцией <code>terminal_state</code>, производится по мере выбора соответствующих событий из очереди ввода посредством <code>terminal_get</code>.
+
* Размеры знакоместа в пикселях: TK_CELL_WIDTH, TK_CELL_HEIGHT.
 +
* Текущие параметры сцены: TK_COMPOSITION, TK_COLOR, TK_BKCOLOR, TK_LAYER.
 +
В зависимости от выбранного фильтра событий ввода (''input.events''), состояние клавиш и мыши возвращается не на момент вызова, а соответствующее текущему состоянию очереди ввода. Обновление значений, возвращаемых функцией <code>terminal_state</code>, производится по мере выбора соответствующих событий из очереди ввода посредством <code>terminal_read</code>.
  
 
Например, если пользователь нажмет сочетание клавиш Shift+Z, в очереди ввода оно будет представлено как Shift(нажато), Z(нажато), Z(отпущено), Shift(отпущено). На момент выбора из очереди ввода события о нажатии клавиши Z, состояние клавиши Shift будет точно "нажато", даже если обработка ввода будет произведена несвоевременно и на самом деле клавиша Shift к тому моменту будет уже отпущена. Это позволяет производить проверку нажатия сочетаний клавиш элементарным образом:
 
Например, если пользователь нажмет сочетание клавиш Shift+Z, в очереди ввода оно будет представлено как Shift(нажато), Z(нажато), Z(отпущено), Shift(отпущено). На момент выбора из очереди ввода события о нажатии клавиши Z, состояние клавиши Shift будет точно "нажато", даже если обработка ввода будет произведена несвоевременно и на самом деле клавиша Shift к тому моменту будет уже отпущена. Это позволяет производить проверку нажатия сочетаний клавиш элементарным образом:
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
int code = terminal_get();
+
int code = terminal_read();
  
if (code == VK_Z)
+
if (code == TK_Z)
 
{
 
{
     if (terminal_state(VK_SHIFT))
+
     if (terminal_state(TK_SHIFT))
 
     {
 
     {
 
         // Нажато Shift+Z
 
         // Нажато Shift+Z
 
     }
 
     }
     else if (terminal_state(VK_CTRL))
+
     else if (terminal_state(TK_CTRL))
 
     {
 
     {
 
         // Нажато Ctrl+Z
 
         // Нажато Ctrl+Z
Строка 291: Строка 361:
 
     }
 
     }
 
}
 
}
</syntaxhighlight>
+
</source>
Однако, если событие не попадает под фильтр событий ввода (''input.events''), оно не может быть выбрано из очереди посредством <code>terminal_get</code> и будет обработано автоматически. Если фильтр равен ''none'', то все события обрабатываются автоматически и <code>terminal_state</code> всегда возвращает текущее состояние.
+
Однако, если событие не попадает под фильтр событий ввода (''input.events''), оно не может быть выбрано из очереди посредством <code>terminal_read</code> и будет обработано автоматически. В пределе, если фильтр равен ''none'', то все события обрабатываются автоматически и <code>terminal_state</code> всегда возвращает текущее (последнее) состояние.
=== terminal_use_image ===
 
<syntaxhighlight lang="cpp">
 
int terminal_use_image(int code, const char* file); // ANSI/UTF-8
 
int terminal_use_wimage(int code, const wchar_t* file); // UTF-16
 
</syntaxhighlight>
 
Функция, позволяющая загрузить и использовать в качестве спрайта произвольное изображение. В параметре ''code'' указывается код "символа", с которым будет ассоциировано изображение, а в параметре -- имя файла с изображением. Допускается загрузка из PNG, BMP и JPEG.
 
Загруженное изображение выводится на экране вместо символа с указанным кодом:
 
<syntaxhighlight lang="cpp">
 
terminal_use_image(0xE000, "tile1.png");
 
terminal_put(10, 10, 0xE000);
 
</syntaxhighlight>
 
В приведенном случае вместо символа с кодом 0xE000 (которого в шрифте все равно нет, так как это код из специально оставленной пустой области Unicode), на экране начиная с позиции (10, 10) будет отрисована картинка из файла "tile1.png".
 
 
 
Следует учитывать порядок отрисовки. Все клетки в BearLibTerminal отрисовываются строго построчно, слева направо, строки сверху вниз. Обычно символы вписываются в границы клеток, не пересекаются и порядок вывода не имеет значения. Однако это может играть роль при выводе спрайтов:
 
<syntaxhighlight lang="cpp">
 
terminal_use_image(0xE001, "tile2.png");
 
terminal_printf(20, 20, "a[uE001]b");
 
</syntaxhighlight>
 
Допустим, что картинка-спрайт из "tile2.png" имеет размер больше одного знакоместа. Тогда в 20 строке сначала будет выведен символ "a" (20 колонка), затем в картинка-спрайт (21 колонка), затем в символ "b" (22 колонка). Спрайт больше одного знакоместа и занял больше одной колонки, но символ "b" был отрисован позже и, тем самым, поверх спрайта.
 
 
 
''TODO: картинка-иллюстрация''
 
 
 
Следует отметить, что спрайт всегда выводится начиная с левого верхнего угла клетки. С версии библиотеки R8, на размер спрайта особых ограничений не накладывается; разработчик должен сам следить, чтобы картинка аккуратно вписывалась в остальное текстовое содержимое на экране.
 
 
=== color_from_argb ===
 
=== color_from_argb ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
 
color_t color_from_argb(int a, int r, int g, int b);
 
color_t color_from_argb(int a, int r, int g, int b);
</syntaxhighlight>
+
</source>
 
Простая вспомогательная функция, собирающая из отдельных R, G, B и A компонент одно 32-битное число, которым представляется цвет в библиотеке (0xAARRGGBB).
 
Простая вспомогательная функция, собирающая из отдельных R, G, B и A компонент одно 32-битное число, которым представляется цвет в библиотеке (0xAARRGGBB).
 
=== color_from_name ===
 
=== color_from_name ===
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
 
color_t color_from_name(const char* name);
 
color_t color_from_name(const char* name);
</syntaxhighlight>
+
</source>
 
Данная функция возвращает цвет (его числовое представление) по имени из встроенной в библиотеку палитры. Эта палитра практически полностью повторяет [http://doryen.eptalys.net/data/libtcod/doc/1.5.2/html2/color.html палитру] из libtcod. Имя указывается в виде "оттенок" или "яркость оттенок", где возможными значениями являются:
 
Данная функция возвращает цвет (его числовое представление) по имени из встроенной в библиотеку палитры. Эта палитра практически полностью повторяет [http://doryen.eptalys.net/data/libtcod/doc/1.5.2/html2/color.html палитру] из libtcod. Имя указывается в виде "оттенок" или "яркость оттенок", где возможными значениями являются:
 
{| class="wikitable"
 
{| class="wikitable"
Строка 335: Строка 382:
 
|}
 
|}
 
Также, по имени цвет можно использовать в тегах ''color'' и ''bkcolor'' функции <code>terminal_printf</code>:
 
Также, по имени цвет можно использовать в тегах ''color'' и ''bkcolor'' функции <code>terminal_printf</code>:
<syntaxhighlight lang="cpp">
+
<source lang="cpp">
terminal_color(color_from_name("lighter gray")); // Основным цветом выбран светло-серый
+
terminal_color("lighter gray"); // Основным цветом выбран светло-серый
 
terminal_printf(1, 1, "You see a [color=dark red]glowing[/color] stone."); // Слово glowing будет темно-красным
 
terminal_printf(1, 1, "You see a [color=dark red]glowing[/color] stone."); // Слово glowing будет темно-красным
</syntaxhighlight>
+
</source>
== Кодировки ==
 
...
 
 
== Ввод ==
 
== Ввод ==
 
...
 
...
 
== Примеры ==
 
== Примеры ==
'''C/C++'''<syntaxhighlight lang="cpp">
+
'''FreePascal'''<source lang="pascal">
#include <bearlibterminal.h>
 
#include <Windows.h>
 
 
 
int CALLBACK WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
 
{
 
    terminal_open(CODEPAGE_DEFAULT);
 
 
 
    // Выводим текст
 
    terminal_printf(1, 1, "Hello, world!");
 
    terminal_refresh();
 
 
 
    // Ждем, пока пользователь не закроет окно
 
    while ( terminal_get() != VK_CLOSE );
 
 
 
    terminal_close();
 
}
 
</syntaxhighlight>
 
BTW, зависимость от Windows.h будет исправлена со временем.
 
 
 
 
 
'''FreePascal'''<syntaxhighlight lang="pascal">
 
 
uses
 
uses
 
   BeaRLibTerminal,
 
   BeaRLibTerminal,
Строка 371: Строка 395:
  
 
begin
 
begin
   terminal_open(CODEPAGE_DEFAULT);
+
   terminal_open();
 
   
 
   
 
   // Выводим текст
 
   // Выводим текст
   terminal_printf(1, 1, 'Hello, world!');
+
   terminal_print(1, 1, 'Hello, world!');
 
   terminal_refresh();
 
   terminal_refresh();
  
 
   // Ждем, пока пользователь не закроет окно
 
   // Ждем, пока пользователь не закроет окно
   while ( terminal_get() <> VK_CLOSE ) do ;  
+
   while (terminal_get() <> TK_CLOSE) do;  
 
   
 
   
 
   terminal_close();
 
   terminal_close();
 
end.
 
end.
</syntaxhighlight>
+
</source>
  
  
'''C#'''<syntaxhighlight lang="csharp">
+
'''C#'''<source lang="csharp">
 
using System;
 
using System;
 
using BearLib;
 
using BearLib;
Строка 408: Строка 432:
 
     }
 
     }
 
}
 
}
</syntaxhighlight>
+
</source>
  
 
[[Category:BeaRLib]]
 
[[Category:BeaRLib]]

Версия 18:11, 25 декабря 2013

BearLibTerminal — это небольшая (в интерфейсном плане) библиотека для организации терминал-подобного окна, вывода текста, обработки простого ввода.

Большое количество roguelike совершенно осознанно используют аскетичное символьное/псевдографическое оформление. Однако, использование стандартных средств вывода (командной строки ОС) сопряжено с досадными ограничениями скорости вывода, цветовой гаммы, используемого шрифта. Нетривиальной задачей оказывается и применение расширенного набора символов, например нескольких языков и псевдографики. BearLibTerminal позволяет обойти упомянутые ограничения оставаясь в рамках простой концепции "терминала": пользователю предоставляется прямоугольная сетка ячеек-знакомест, средства для вывода текста и чтения ввода с клавиатуры.

Достойными внимания особенностями терминала являются:

  • Высокая скорость вывода (в основе лежит OpenGL).
  • Возможность использования тайловых (в виде картинки) и векторных (TrueType) шрифтов.
  • Легкость использования Unicode.
  • Полная TrueColor палитра.
  • Возможность комбинации нескольких символов в одном знакоместе.
  • Поддержка ввода с клавиатуры и мыши.

BearLibTerminal не является:

  • Фреймворком roguelike: в библиотеке нет и никогда не будет генераторов случайных чисел, уровней или имен персонажей, механизмов расчета FOV/LOS и освещения, средств для работы с файлами или сетью.
  • Графическим движком общего назначения: функциональность библиотеки сознательно ограничивается функциональностью псевдотерминала.

Похожие инструменты: Tinycurses, libtcod.

Найти библиотеку можно в соответствующей теме форума (см. первое сообщение).

Элементарный пример использования

C/C++<source lang="cpp">

  1. include <BearLibTerminal.h>
  2. include <Windows.h>

TERMINAL_TAKE_CARE_OF_WINMAIN // Но можно и самостоятельно определить WinMain

int main() {

   terminal_open();
   // Выводим текст
   terminal_printf(1, 1, "Hello, world!");
   terminal_refresh();
   // Ждем, пока пользователь не закроет окно
   while (terminal_read() != VK_CLOSE); 
   terminal_close();

} </source>

Справка по интерфейсу библиотеки

BearLibTerminal оформлен в виде динамически подключаемой библиотеки (.dll). Используемое соглашение вызова — cdecl.

terminal_open

<source lang="cpp"> int terminal_open(); </source> Для начала работы с библиотекой необходимо вызвать функцию terminal_open. До вызова terminal_open все остальные функции библиотеки мгновенно завершаются, не выполняя никаких действий. terminal_open производит инициализацию терминала со "стандартными" параметрами: размер рабочей области 80x25 ячеек, шрифт Fixedsys Excelsior. Вызов terminal_open не приводит к немедленному выводу окна терминала на экран, окно отображается в момент первого вызова функции #terminal_refresh.

terminal_close

<source lang="cpp"> void terminal_close(); </source> Симметричный terminal_open вызов, закрывающий терминал и освобождающий используемые библиотекой ресурсы. Поведение программы, не вызвавшей terminal_open перед своим завершением, неопределено.

terminal_set

Данная функция представляет собой универсальный способ задания разнообразных настроек библиотеки и описания используемых тайлсетов. Опции задаются в виде строки с группами значений в следующем формате: group1.option1=value1; group1.option2=value2; ... Эта запись может быть сокращена до: group1: [option1=]value1, option2=value2; ... Например: <source lang="cpp"> terminal_set("window.size=80x25; window.title='Заголовок'"); terminal_set("window: size=80x25, title='Заголовок'"); </source>

Динамическая библиотека предоставляет три варианта для строки из 8, 16 и 32-битных символов: terminal_set8, terminal_set16 и terminal_set32. Детали о разрядности символов должны быть скрыты хедером для конкретного языка программирования с учетом разрядности исрользуемых в языке строк. Например, для С/С++ этот вызов доступен в виде следующих функций: <source lang="cpp"> int terminal_set(const char* s); int terminal_wset(const wchar_t* s); </source> Кроме того, хедер для C/C++ предоставляет варианты с printf-подобным форматированием строки: <source lang="cpp"> int terminal_setf(const char* s, ...); int terminal_wsetf(const wchar_t* s, ...); </source>

Перечень доступных параметров

Наименование Значение по умолчанию Описание
Настройки окна, группа атрибутов window
size 80x25 Размер окна терминала в знакоместах в формате <ширина>x<высота>.
cellsize auto Размер ячейки знакоместа, в пикселях в формате <ширина>x<высота> или auto
title BearLibTerminal Заголовок окна терминала.
icon app.ico Имя .ico-файла с иконкой, которая будет использована для окна.
Настройки ввода, группа атрибутов input
events keypress Фильтр событий ввода, комбинация из флагов none, keypress, keyrelease, mousemove, mousescroll, all.
nonblocking false Если выставлен в true, вызовы terminal_read[_xxx] не приостанавливают выполнение программы, если очередь ввода пуста.
precise-mousemove false Флаг, указывающий, будет ли считаться движением мыши попиксельное (true) или познакоместное (false) перемещение указателя.
sticky-close true Если выставлен в false, то по закрытию окна событие VK_CLOSE генерируется однократно. Если выставлен в true, то по закрытию окна terminal_read будет постоянно возвращать VK_CLOSE.
cursor-symbol 95 (ASCII 0x5F, подчеркивание) Код символа, используемого в качестве курсора в terminal_read_str.
cursor-blink-rate 500 Скорость мерцания курсора в terminal_read_str, в миллисекундах.
Настройки вывода, группа атрибутов output
postformatting true Флаг, включающий или выключающий постформатирование при выводе текста.
vsync true Флаг, включающий или выключающий вертикальную синхронизацию при отрисовке.
Настройки растрового тайлсета, группа атрибутов font или U+xxxx
name Описательное имя растрового ресурса: имя файла или адрес памяти.
size Размер одиночного тайла в пикселях в формате <ширина>x<высота>. Необязательный атрибут, если он не указан, считается что все изображение это один тайл.
resize Размер, до которого нужно переразмерить растровое изображение. Необязательный атрибут.
resize-filter bilinear Фильтр, который будет использован при переразмерении изображения. Возможные варианты: nearest, bilinear, bicubic.
resize-mode stretch Режим переразмерения. Возможные варианты: stretch (растянуть), fit (вписать по большей стороне), crop (вписать по меньшей стороне).
raw-size Размер исходного изображения в случае загрузки из памяти. Если этот атрибут не указан, используется значение атрибута size (и считается, что все изображение это один тайл).
codepage ascii Кодовая таблица соответствия отдельных тайлов в тайлсете кодам Unicode. Возможные варианты: ascii, utf8, 437, 866, 1250, 1251 или имя файла с таблицей.
align Точка отсчета координат для центрирования тайла в ячейке. Возможные значения: center, top-left, top-right, bottom-left, bottom-right. Необязательный атрибут, для тайлсетов из одного тайла (спрайтов) используется top-left, для тайлсетов из нескольких тайлов (шрифтов) используется center.
bbox 1x1 Размер логической ячейки, в которой выполняется центрирование тайла, в знакоместах.
transparent Цвет прозрачного фона для изображений без альфа-канала. Необязательный атрибут (и вообще используйте PNG).
Настройки TrueType тайлсета, группа атрибутов font или U+xxxx
name Имя .ttf-файла шрифта
size Размер шрифта: либо средняя высота строчного символа в пикселях, либо размер ячейки в пикселях для автоматического подбора размера шрифта.
size-reference @ Необязательный атрибут. Код символа, используемого для оценки/подбора размера шрифта.
mode normal Режим растеризации. Возможные варианты: monochrome, normal или lcd.
codepage utf-8 Кодовая таблица нестандартного соответствия кодов Юникода и символов шрифта.
align center Точка отсчета координат для центрирования символа в ячейке. Возможные значения: center, top-left, top-right, bottom-left, bottom-right.
bbox 1x1 Размер логической ячейки, в которой выполняется центрирование тайла, в знакоместах.
Настройки логгирования, группа атрибутов log
file bearlibterminal.log Имя файла, куда в библиотека будет писать свой лог.
level error Уровень важности логгирования: none, fatal, error, warning, info, debug, trace
mode truncate Режим ведения лога. Возможные варианты: truncate (начинать файл заново при каждом новом старте) и append (дописывать в конец файла).

terminal_put

<source lang="cpp"> void terminal_put(int x, int y, int code); </source> Одна из основных функций библиотеки, позволяет вывести символ в знакоместо с указанными координатами. В зависимости от выбранного режима смешения, выводимый символ может заменить собой все содержимое указанного знакоместа или быть добавленным поверх уже имеющихся (см. #terminal_composition). Для ячеек первого слоя terminal_put применяет цвет фона.

terminal_color

<source lang="cpp"> void terminal_color(color_t color); </source> Устанавливает основной цвет выводимого текста (тайлов). Функция принимает целое беззнаковое 32-битное число, представляющее цвет в формате 0xAARRGGBB. В хедере для C++ имеется перегруженный вариант, принимающий строку с именем цвета.

См. #color_from_argb, #color_from_name, #Постформатирование.

terminal_bkcolor

<source lang="cpp"> void terminal_bkcolor(color_t color); </source> Аналогичная terminal_color функция, но устанавливающая цвет фона выводимых символов.

Цвет фона применяется к знакоместам только в первом слое (см. #terminal_layer).

terminal_composition

<source lang="cpp"> void terminal_composition(int mode); </source> Функция устанавливает режим наложения тайлов в одной ячейке: TK_COMPOSITION_ON или TK_COMPOSITION_OFF.

В режиме TK_COMPOSITION_ON выводимый символ полностью замещает содержимое соответствующего знакоместа, цвет фона устанавливается в выбранный посредством #terminal_bkcolor цвет. Это обычное поведение терминал-подобных приложений.

В режиме TK_COMPOSITION_OFF выводимый символ "накладывается" на уже имеющиеся в ячейке символы, причем каждый отдельный символ в получившейся "стопке" может иметь индивидуальный цвет. Таким образом можно комбинировать глифы и/или тайлы для получения более сложных фигур.

terminal_print

<source lang="cpp"> int terminal_print(int x, int y, const char* s); </source> Аналогично #terminal_set, библиотека предоставляет несколько вариантов функции для строк различной разрядности, но хедер к С/С++ скрывает это и вызов доступен для char* и wchar_t* строк с форматированием и без: terminal_[w]print[f] В строке, передаваемой в функцию terminal_print могуть присутствовать теги постформатирования, модифицирующие производимый вывод:

Цвет текста и фона:
terminal_print(2, 1, "[color=amber]Amber[/color] letters, [bkcolor=darkest gray]gray background[/bkcolor].");

Произвольный символ:
terminal_print(2, 1, "Earth rune: [U+E001]");

Комбинация символов:
terminal_print(2, 1, "a[+]^");
Такой тег комбинирует два тайла как будто бы они были положены в одну ячейку с включенным наложением (TK_COMPOSITION_ON).

Межсимвольный интервал:
terminal_print(2, 1, "[spacing=2x2]sparse text");
Межсимвольный/межстрочный интервал необходим для вывода текста тайлами размером более одного знакоместа.

Сдвиг кодовой страницы:
terminal_print(2, 1, "[base=0xE000:1251]Русский текст");
Сдвиг страницы позволяет выводить текст тайлсетом в произвольной кодировке и загруженным по произвольному коду.

terminal_clear

<source lang="cpp"> void terminal_clear(); </source> Функция очистки экрана. Содержимое всех ячеек-знакомест во всех слоях удаляется, цвет фона устанавливается в выбранный посредством #terminal_bkcolor цвет.

terminal_clear_area

<source lang="cpp"> void terminal_clear_area(int x, int y, int w, int h); </source> Функция частичной очистки экрана. Удаляется содержимое ячеек-знакомест в указанной области экрана текущего слоя.

terminal_refresh

<source lang="cpp"> void terminal_refresh(); </source> Функция обновления экрана. Эта функция должна быть вызвана, чтобы изменения содержимого терминала на самом деле отобразились на экране. Окно терминала выводится на экран при первом вызове terminal_refresh.

terminal_has_input

<source lang="cpp"> int terminal_has_input(); </source> Позволяет узнать, есть ли события в очереди ввода. Возвращает 0, если очередь пуста или 1, если есть непрочитанные события.

terminal_read

<source lang="cpp"> int terminal_read(); </source> Возвращает код следующего событие из очереди ввода.

Если очередь ввода пуста, поведение зависит от параметра input.nonblocking:

  • false: выполнение программы блокируется до поступления следующего события ввода.
  • true: блокирования выполнения программы не производится, в случае пустой очереди ввода функция немедленно возвращает TK_INPUT_NONE.

См. #Ввод

terminal_read_ext

<source lang="cpp"> int terminal_read_ext(int flags); </source> Расширенная версия чтения очереди ввода. Параметр flags может включать в себя следующие флаги:

  • TK_READ_CHAR: функция пытается выбрать из очереди текстовый символ. В случае, если следующее событие в очереди ввода не порождает тесктовый ввод, возвращается TK_INPUT_CALL_AGAIN.
  • TK_READ_NOREMOVE: функция не убирает прочитанное событие из очереди. Следующий вызов вернет такое же значение.

terminal_read_str

<source lang="cpp"> int terminal_read_str(int x, int y, char* buffer, int max); int terminal_read_wstr(int x, int y, wchar_t* buffer, int max); </source> Функция чтения текста с клавиатуры с учетом локалей и раскладок пользователя. Набираемые пользователем символы добавляются к строке в буфере buffer, при этом максимальный размер получаемой строки ограничивается max символами.

Поведение функции сильно зависит от параметра input.nonblocking. Если он равен false (по умолчанию), то в процессе работы функции ввод полностью обрабатывается терминалом. В это время содержимое строки и курсор ввода отображается в терминале начиная с позиции (x, y). Чтение ввода функцией terminal_read_str в блокирующем режиме производится до:

  • Подтверждения ввода (поступления события TK_RETURN). Функция возвращает количество введенных символов (значение больше либо равное нулю).
  • Отмены ввода (поступления события TK_ESCAPE или TK_CLOSE). Функция возвращает TK_INPUT_CANCELLED.

По завершении, terminal_read_str убирает введенную строку и курсор ввода с экрана, восстанавливая предыдущее содержимое использованных ячеек-знакомест.

Если input.nonblocking равен true (неблокирующее чтение), функция terminal_read_str не трогает экран, а только производит чтение доступной очереди ввода. В неблокирующем режиме:

  • По подтверждению ввода (TK_RETURN) функция возвращает количество введенных символов.
  • По отмене ввода (TK_ESCAPE или TK_CLOSE) функция возвращает TK_INPUT_CANCELLED.
  • Если очередь ввода пуста, функция возвращает TK_INPUT_CALL_AGAIN.

Задача отрисовки процесса ввода (текст, курсор) ложится на пользователя библиотеки.

Размер передаваемого в функцию буфера должен быть достаточно большим, чтобы вместить максимально возможную вводимую строку. Так как параметр max указывается в символах, без учета нуль-терминатора, это означает, что для вызова в кодировке UTF-8 (terminal_read_str) буфер должен быть размером не менее max*3+1 (каждый символ может занять до трех байт + нуль-терминатор), а для UTF-16/32 вызова (terminal_read_wstr) -- не менее max+1.

См. #Ввод

terminal_state

<source lang="cpp"> int terminal_state(int code); </source> Данная функция позволяет получить текущее состояние некоторых переменных терминала. Код переменной берется из перечисления TK_xxx.

  • Состояние клавиш: коды TK_ESCAPE, TK_0, TK_NUMPAD0, TK_A и т. д. Функция возвращает 1, если клавиша нажата или 0, если отпущена.
  • Состояние мыши: TK_MOUSE_X и TK_MOUSE_Y (в знакоместах), TK_MOUSE_PIXEL_X, TK_MOUSE_PIXEL_Y (в пикселях), TK_MOUSE_WHEEL (в шагах колесика).
  • Размеры экрана в знакоместах: TK_WIDTH, TK_HEIGHT.
  • Размеры знакоместа в пикселях: TK_CELL_WIDTH, TK_CELL_HEIGHT.
  • Текущие параметры сцены: TK_COMPOSITION, TK_COLOR, TK_BKCOLOR, TK_LAYER.

В зависимости от выбранного фильтра событий ввода (input.events), состояние клавиш и мыши возвращается не на момент вызова, а соответствующее текущему состоянию очереди ввода. Обновление значений, возвращаемых функцией terminal_state, производится по мере выбора соответствующих событий из очереди ввода посредством terminal_read.

Например, если пользователь нажмет сочетание клавиш Shift+Z, в очереди ввода оно будет представлено как Shift(нажато), Z(нажато), Z(отпущено), Shift(отпущено). На момент выбора из очереди ввода события о нажатии клавиши Z, состояние клавиши Shift будет точно "нажато", даже если обработка ввода будет произведена несвоевременно и на самом деле клавиша Shift к тому моменту будет уже отпущена. Это позволяет производить проверку нажатия сочетаний клавиш элементарным образом: <source lang="cpp"> int code = terminal_read();

if (code == TK_Z) {

   if (terminal_state(TK_SHIFT))
   {
       // Нажато Shift+Z
   }
   else if (terminal_state(TK_CTRL))
   {
       // Нажато Ctrl+Z
   }
   else
   {
       // Нажата просто Z
   }

} </source> Однако, если событие не попадает под фильтр событий ввода (input.events), оно не может быть выбрано из очереди посредством terminal_read и будет обработано автоматически. В пределе, если фильтр равен none, то все события обрабатываются автоматически и terminal_state всегда возвращает текущее (последнее) состояние.

color_from_argb

<source lang="cpp"> color_t color_from_argb(int a, int r, int g, int b); </source> Простая вспомогательная функция, собирающая из отдельных R, G, B и A компонент одно 32-битное число, которым представляется цвет в библиотеке (0xAARRGGBB).

color_from_name

<source lang="cpp"> color_t color_from_name(const char* name); </source> Данная функция возвращает цвет (его числовое представление) по имени из встроенной в библиотеку палитры. Эта палитра практически полностью повторяет палитру из libtcod. Имя указывается в виде "оттенок" или "яркость оттенок", где возможными значениями являются:

Яркость 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

Также, по имени цвет можно использовать в тегах color и bkcolor функции terminal_printf: <source lang="cpp"> terminal_color("lighter gray"); // Основным цветом выбран светло-серый terminal_printf(1, 1, "You see a [color=dark red]glowing[/color] stone."); // Слово glowing будет темно-красным </source>

Ввод

...

Примеры

FreePascal<source lang="pascal"> uses

 BeaRLibTerminal,
 Windows;

begin

 terminal_open();

 // Выводим текст
 terminal_print(1, 1, 'Hello, world!');
 terminal_refresh();
 // Ждем, пока пользователь не закроет окно
 while (terminal_get() <> TK_CLOSE) do; 

 terminal_close();

end. </source>


C#<source lang="csharp"> using System; using BearLib;

namespace HelloWorld {

   static class Program
   {
       static void Main()
       {
           Terminal.Open();
           // Выводим текст
           Terminal.Print(1, 1, "Hello, world!");
           Terminal.Refresh();
           // Ждем, пока пользователь не закроет окно
           while (Terminal.Get() != Terminal.Keys.Close);
           Terminal.Close();
       }
   }

} </source>