API Reference

Separate pages covering different library parts in greater detail (work in progress):

• Configuration
• Input
• Output

The API consists of ~20 functions and a number of constants.

• Initialization and configuration: open, close, set
• Output state: color, bkcolor, composition, layer
• Output: clear, clear area, crop, refresh, put, pick, pick color, pick bkcolor, put ext, print, measure
• Input: state, check, has input, read, peek, read str
• Utility: delay, color from name, color from argb

Specifying the exact list of functions is tricky as underlying dynamic-link library exports an language-agnostic set of calls. The actual list of functions available to each programming language is slightly different.

For example, strings can be encoded using at least three character sizes: one (UTF-8 or ANSI), two (UTF-16) and four (UTF-32) bytes. Therefore for functions taking string arguments the dynamic-link library provides three separate calls. The C/C++ header file hides this fact by providing functions for more usual char and wchar_t string types, e. g. print and wprint. For some functions there are also variants with printf-like formatting, e. g. printf and wprintf. On the other hand, C# only use UTF-16 strings and formatting support is usually done by overloading the same function. So for C# there is only one printing function while C/C++ gets four.

Here the API is described briefly and mostly from pure C perspective. Language-specific peculiariries are listed on separate pages (not yet done).

open

int terminal_open();

This function initializes BearLibTerminal instance, configuring the window with default parameters: 80×25 cells, Fixedsys Excelsior font, white text on a black background. This function does not bring the window to screen. The window is not shown until the first call to refresh. Note that unless the library is initialized with successful call to open, all other library functions will do nothing but return immediately with return code (if any) indicating an error.

The function returns boolean value where false means initialization has failed. Details may be found in the log file (named bearlibterminal.log by default).

close

void terminal_close();

Symmetric to open, this function closes the window and deinitializes BearLibTerminal instance.