Configuration

Configuration is handled by set and get functions and by configuration file.

set

This is probably the most complex function in BearLibTerminal API. Configuring library options and mechanics, managing fonts, tilesets and even configuration file is performed with it:

terminal_set("window: size=80x25; font: ./UbuntuMono-R.ttf, size=12");

The function returns a boolean value indicating success or failure.

It is possible to set several options at once. However, this function tries to behave in transaction-like way: in case of error, it does not change anything and return false.

Configuration string format

A string passed to the function specifies a set of key-value parameters separated by semicolons:

window.title='foo'; window.size=80x25;

Related parameters can be grouped together:

window: title='foo', size=80x25;

Extra spaces, commas and semicolons are ignored. For now, all newline characters are also ignored, even inside quoted values, but this may change.

Quoting of string values is mostly optional and required only if value contains some delimiter characters like semicolons or you want to preserve leading/trailing whitespaces. Quoting may be done with both single and double quotes. There is no escape sequences besides Pascal-like double-quote escaping:

window.title='I''m feeling lucky!';

Library configuration

There is a number of options directly affecting library behavior and/or window appearance:

Group	Option	Default	Description
terminal	encoding	utf8	The encoding/codepage used for unibyte strings. It may be set to some ANSI codepage, e. g. Windows-1251.
window	size	80×25	The size of a window in cells.
	cellsize	auto	The size of a cell in pixels or “auto” if the size should be selected based on the font.
	title	'BearLibTerminal'	The title of the library window.
	icon	-	The name of an *.ico file to use for the library window. For Windows, default icon is built into the library.
	resizeable	false	The flag controlling window resizeability. If set, user can change window size and the application will receive a TK_RESIZED event.
	fullscreen	false	The virtual flag allowing to manually set fullscreen mode.
input	filter	'keyboard'	The list of events the application is interested in. All other will be silently processed by the library (more...).
	precise-mouse	false	When false, TK_MOUSE_MOVE event will be generated only when cursor is moved from one cell to another. When true, any mouse movement will generate the event.
	mouse-cursor	true	The flag controlling mouse cursor visibility.
	cursor-symbol	0x5F	The character used as a cursor symbol by read_str function.
	cursor-blink-rate	500	The rate cursor symbol blinks at in read_str function, in milliseconds.
	alt-functions	true	If set, the library will intercept some Alt-key combinations, e. g.
output	postformatting	true	Enables processing of special tags by print function.
	vsync	true	Switches on an off vertical synchronization used by OpenGL.
	tab-width	4	The width of a tab space in a text output by print function.
log	file	'bearlibterminal.log'	The name of a log file. Default is “bearlibterminal.log”.
	level	error	The logging level, one of “none”, “fatal”, “error”, “warning”, “info”, “debug”, “trace”.
	mode	truncate	The log writing mode: “truncate” will restart log each time, “append” will continue to write to a single file.