Input

functions

Input in the BearLibTerminal is handled with read, read str, has input, state and check functions.

read

This function returns the next event from input queue:

int key = terminal_read();

if (key == TK_ESCAPE) { // Quit }

If there is no more events in the queue, read will wait for an event to come. If this blocking behaviour is not desirable, you can check has input before calling read.

peek

Similar to read but does not remove the event from the internal queue. The next peek or read call will return the same value. This is non-blocking function: if the queue is empty, it will not wait and return 0.

read_str

This function does a simple blocking read of a string without any parsing. User input is displayed at specified coordinates and also limited to specified length so it can be used in game interface. The function displays user input within current layer and restores the scene before return. It is an application's responsibility to keep the result on screen.

The function returns the size of a string if user has confirmed input by pressing Enter, or TK_INPUT_CANCELLED if operation was cancelled by pressing ESCAPE or closing the window.

wchar_t s[32] = L"Hello";

if (terminal_read_wstr(2, 1, s, sizeof(s)-1) >= 0) { terminal_wprintf(L"You entered: "%ls"", s); }

If read_str does not fit your needs, see TK CHAR/TK WCHAR states allowing for manual text input.

has_input

This function returns a boolean value indicating immediate input availability. If has_input returns true, the next call to read is guaranteed not to block.

while (terminal_has_input()) { int key = terminal_read(); }

state

This function queries the current numeric value of a library property. For input it is used to get different event properties, see the table below.

int key = terminal_read();

if (key == TK_MOUSE_MOVE) { int x = terminal_state(TK_MOUSE_X); int y = terminal_state(TK_MOUSE_Y); }

Note that values returned by state function may not reflect the exact real-time value of a property, but the “current” one in respect to the input queue and already dequeued events. More...

check

This is a simple wrapper around state function. In a lot of programming languages numerical and boolean types are not compatible so checking logically boolean properties with state may become unnecessary verbose. So you can use check to test some property.

int key = terminal_read();

if (key == TK_Z) { if (terminal_check(TK_SHIFT)) { // 'Z': zap a wand } else { // 'z': cast a spell } }

Input options

These options are configured by the set function:

terminal_set ( "input:" "cursor-symbol = 0x1F," "cursor-blink-rate = 500," "precise-mouse = false," "mouse-cursor = true," "filter=[keyboard];" );

input.cursor-symbol

Character/tile used as a cursor by read str function. Default is “_” (underscore) and can be changed to match application design, e. g. to full square or vertical bar.

input.cursor-blink-rate

Speed at which read str's cursor blinks, in milliseconds. Default is 500, i. e. twice a second.

input.precise-mouse

A boolean flag controlling how mouse movement events are generated. When false, an event is generated only when cursor is moved from one cell to another. When true, any mouse movement generates an event. Default is false.

input.mouse-cursor

A boolean flag controlling mouse cursor visibility. Default is true.

input.filter

It is a list of events the application is interested in. All other will be silently processed by the library, thus read will return only events from this list:

input.filter = [keyboard, mouse+]

A name in the list may specify:

• an event group: 'keyboard', 'mouse', 'keypad', 'arrows'.
• a single event (name as in the table below, but without 'TK_' prefix; case-insensitive).
• a set of alphanumeric keys, e. g. 'wasd' or '0123456789'; obviously it must differ from event group names.

Mentioning the events enables reading them. If there is a '+' (plus sign) added to the name, both keypresses and keyreleases will be read.

Default filter is 'keyboard'. To enable the mouse support, set the filter to 'keyboard, mouse'. System events like TK_CLOSE and TK_RESIZED are always enabled.

There is no input filtering if the list is empty. Therefore filtering is disabled by assigning 'none' or an empty list to the input.filter option.

Event and state constants

Group	Group	Description
Alphanumeric	TK_A … TK_Z	Event : indicates that corresponding key was pressed or released. If key was released, its code is combined with TK_KEY_RELEASED flag (more...). State: current state of the key (see input queue).
	TK_0 … TK_9
	TK_SPACE
	TK_MINUS	-
	TK_EQUALS	=
	TK_LBRACKET	[
	TK_RBRACKET	]
	TK_BACKSLASH	/
	TK_SEMICOLON	;
	TK_APOSTROPHE	'
	TK_GRAVE	`
	TK_COMMA	,
	TK_PERIOD	.
	TK_SLASH	\
Functional, navigation, modifiers	TK_F1 … TK_F12
	TK_RETURN
	TK_ESCAPE
	TK_BACKSPACE
	TK_TAB
	TK_PAUSE
	TK_INSERT
	TK_HOME
	TK_PAGEUP
	TK_DELETE
	TK_END
	TK_PAGEDOWN
	TK_RIGHT
	TK_LEFT
	TK_DOWN
	TK_UP
	TK_SHIFT
	TK_CONTROL
Keypad	TK_KP_0 … TK_KP_9
	TK_KP_DIVIDE	/
	TK_KP_MULTIPLY	*
	TK_KP_MINUS	-
	TK_KP_PLUS	+
	TK_KP_PERIOD	.
	TK_KP_ENTER
Mouse	TK_MOUSE_LEFT
	TK_MOUSE_RIGHT
	TK_MOUSE_MIDDLE
	TK_MOUSE_X1
	TK_MOUSE_X2
	TK_MOUSE_MOVE	Event : generated when mouse coordinates are changed by at least one cell. If input.precise-mouse option is set, this event is generated for any mouse movement, even within single cell.
	TK_MOUSE_SCROLL	Event : generated when mouse wheel is turned.
	TK_MOUSE_WHEEL	State : returns scroll delta of the last wheel event (more...).
	TK_MOUSE_X	State : current mouse coordinates in cells.
	TK_MOUSE_Y	State : current mouse coordinates in cells.
	TK_MOUSE_PIXEL_X	State : current mouse coordinates in pixels. These states are available regardless of input.precise-mouse option.
	TK_MOUSE_PIXEL_Y	State : current mouse coordinates in pixels. These states are available regardless of input.precise-mouse option.
	TK_MOUSE_CLICKS	State : number of fast consecutive clicks for last mouse button event, i. e. 1 for regular click, 2 for double click, etc. (more...)