Terminal manipulation functions.

Macros
#define	t3_term_get_caps(caps)
	Get terminal capabilities. More...

Functions
void	_t3_do_cup (int line, int col)
	Move cursor to screen position. More...
void	_t3_trigger_terminal_size_detection (void)
	Trigger the detection of the terminal size.
t3_bool	t3_term_acs_available (int idx)
	Check if a character is available in the alternate character set (internal use mostly). More...
t3_bool	t3_term_can_draw (const char *str, size_t str_len)
	Determine if the terminal can draw a character. More...
t3_attr_t	t3_term_combine_attrs (t3_attr_t a, t3_attr_t b)
	Combine attributes, with priority. More...
void	t3_term_get_caps_internal (t3_term_caps_t *caps, int version)
	Get the terminal capabilities. More...
const char *	t3_term_get_codeset (void)
	Get the string describing the current character set used by the library. More...
int	t3_term_get_keychar (int msec)
	Get a key char from stdin with timeout. More...
int	t3_term_get_modifiers_hack (void)
	Retrieve the state of the modifiers using terminal specific hacks. More...
t3_attr_t	t3_term_get_ncv (void)
	Get the set of non-color video attributes. More...
void	t3_term_get_size (int *height, int *width)
	Retrieve the terminal size. More...
void	t3_term_hide_cursor (void)
	Hide the cursor. More...
t3_bool	t3_term_putc (char c)
	Add a charater to the output buffer. More...
t3_bool	t3_term_putn (const char *s, size_t n)
	Add a string to the output buffer. More...
void	t3_term_putp (const char *str)
	Send a terminal control string to the terminal, with correct padding. More...
t3_bool	t3_term_puts (const char *s)
	Add a string to the output buffer. More...
void	t3_term_redraw (void)
	Redraw the entire terminal from scratch.
t3_bool	t3_term_resize (void)
	Handle resizing of the terminal. More...
void	t3_term_set_attrs (t3_attr_t new_attrs)
	Set terminal drawing attributes. More...
void	t3_term_set_cursor (int y, int x)
	Move cursor. More...
void	t3_term_set_replacement_char (int c)
	Set the replacement character used for undrawable characters. More...
void	t3_term_set_user_callback (t3_attr_user_callback_t callback)
	Set callback for drawing characters with T3_ATTR_USER attribute. More...
void	t3_term_show_cursor (void)
	Show the cursor. More...
size_t	t3_term_strcwidth (const char *str)
	Calculate the cell width of a string. More...
size_t	t3_term_strncwidth (const char *str, size_t n)
	Calculate the cell width of a string. More...
int	t3_term_strnwidth (const char *str, size_t n)
	Calculate the cell width of a string. More...
int	t3_term_strwidth (const char *str)
	Calculate the cell width of a string. More...
int	t3_term_unget_keychar (int c)
	Push a char back for later retrieval with t3_term_get_keychar. More...
void	t3_term_update (void)
	Update the terminal, drawing all changes since last refresh. More...
void	t3_term_update_cursor (void)
	Update the cursor, not drawing anything.

Variables
fd_set	_t3_inset
	File-descriptor set used for select in t3_term_get_keychar.

Detailed Description

Macro Definition Documentation

t3_term_get_caps

#define t3_term_get_caps

(

caps

)

Get terminal capabilities.

Parameters

caps	The location to store the capabilites.

This function can be used to obtain the supported video attributes and other information about the capabilities of the terminal. This define calls t3_term_get_caps_internal with the correct version argument.

Function Documentation

_t3_do_cup()

void _t3_do_cup	(	int	line,
		int	col
	)

Move cursor to screen position.

Parameters

line	The screen line to move the cursor to.
col	The screen column to move the cursor to. This function uses the @c _t3_cup terminfo string if available, and emulates it through other means if necessary.

t3_term_acs_available()

t3_bool t3_term_acs_available

(

int

idx

)

Check if a character is available in the alternate character set (internal use mostly).

Parameters

idx	The character to check.

Returns

t3_true if the character is available in the alternate character set.

Characters for which an alternate character is generally available are documented in terminfo(5), but most are encoded in T3_ACS_* constants.

t3_term_can_draw()

t3_bool t3_term_can_draw	(	const char *	str,
		size_t	str_len
	)

Determine if the terminal can draw a character.

These are implemented in convert_output.c.

Parameters

str	The UTF-8 string representing the character to be displayed.
str_len	The length of str.

Returns

A boolean indicating to whether the terminal is able to correctly draw the character.

Note that str may contain combining characters, which will only be drawn correctly if a precomposed character is available or the terminal supports them. And even if the terminal supports combining characters they may not be correctly rendered, depending on the combination of combining marks.

Moreover, the font the terminal is using may not have a glyph available for the requested character. Therefore, if this function determines that the character can be drawn, it may still not be correctly represented on screen.

t3_term_combine_attrs()

t3_attr_t t3_term_combine_attrs	(	t3_attr_t	a,
		t3_attr_t	b
	)

Combine attributes, with priority.

Parameters

a	The first set of attributes to combine (priority).
b	The second set of attributes to combine (no priority).

Returns

The combined attributes.

This function combines a and b, with the color attributes from a overriding the color attributes from b if both specify colors. Note that if b has an attribute that was explicitly set (indicated by the corresponding _SET value), and a does not have the corresponding _SET bit, the value of b will be taken. The background is that this allows distinction between "the default should be used" (without the _SET bit) and "this bit is explicitly cleared" (with the _SET bit).

t3_term_get_caps_internal()

void t3_term_get_caps_internal	(	t3_term_caps_t *	caps,
		int	version
	)

Get the terminal capabilities.

Parameters

caps	The location to store the capabilities.
version	The version of the library used when compiling (should be T3_WINDOW_VERSION).

Note

Do not call this function directly, but use t3_term_get_caps which automatically uses T3_WINDOW_VERSION as the second argument.

This function can be used to obtain the supported video attributes and other information about the capabilities of the terminal. To allow different ABI versions to live together, the version number of the library used when compiling the call to this function must be passed.

t3_term_get_codeset()

const char* t3_term_get_codeset

(

void

)

Get the string describing the current character set used by the library.

The reason this function is provided, is that although the library initially will use the result of transcript_get_codeset, the terminal-capabilities detection may result in a different character set being used. After receiving T3_WARN_UPDATE_TERMINAL from t3_term_get_keychar, this routine may return a different value.

t3_term_get_keychar()

int t3_term_get_keychar

(

int

msec

)

Get a key char from stdin with timeout.

Parameters

msec	The timeout in miliseconds, or a value <= 0 for indefinite wait.

Return values

>=0	A char read from stdin.
T3_ERR_ERRNO	on error, with errno set to the error.
T3_ERR_EOF	on end of file.
T3_ERR_TIMEOUT	if there was no character to read within the specified timeout.
T3_WARN_UPDATE_TERMINAL	if the terminal-feature detection has finished and requires that the terminal is updated. Note: this is not an error, but a signal to update the terminal. To check for errors, use: t3_term_get_keychar(msec) < T3_WARN_MIN

t3_term_get_modifiers_hack()

int t3_term_get_modifiers_hack

(

void

)

Retrieve the state of the modifiers using terminal specific hacks.

This function can be used to retrieve the modifier state from the terminal, if the terminal provides a method for querying the corrent modifier state. One example of such a terminal is the linux console. Using this function is basically a hack to get at state that is not encoded in the key sequence, and is not the prefered way of accessing this data. For some terminals this is however the only way to get at this data.

t3_term_get_ncv()

t3_attr_t t3_term_get_ncv

(

void

)

Get the set of non-color video attributes.

Returns

Attributes bits from the T3_ATTR_* set indicating which attributes can not be combined with video attributes.

Non-color video attributes are attributes that can not be combined with the color attributes. It is unspecified what will happen when the are combined.

t3_term_get_size()

void t3_term_get_size	(	int *	height,
		int *	width
	)

Retrieve the terminal size.

Parameters

height	The location to store the terminal height in lines.
width	The location to store the terminal height in columns.

Neither height nor width may be NULL.

t3_term_hide_cursor()

void t3_term_hide_cursor

(

void

)

Hide the cursor.

Instructs the terminal to make the cursor invisible. If the terminal does not provide the required functionality, the cursor is moved to the bottom right.

t3_term_putc()

t3_bool t3_term_putc

(

char

c

)

Add a charater to the output buffer.

Parameters

c	The character to add.

The character passed as c is a single char, not a unicode codepoint. This function should not be used outside the callback set with t3_term_set_user_callback.

t3_term_putn()

t3_bool t3_term_putn	(	const char *	s,
		size_t	n
	)

Add a string to the output buffer.

Parameters

s	The string to add.
n	The length of s.

This function should not be used outside the callback set with t3_term_set_user_callback.

t3_term_putp()

void t3_term_putp

(

const char *

str

)

Send a terminal control string to the terminal, with correct padding.

Note

This function should only be called in very special circumstances in a registered user callback (see t3_term_set_user_callback), when you want to do something which the library can not. Make sure that any state changes are undone before returning from the callback.

t3_term_puts()

t3_bool t3_term_puts

(

const char *

s

)

Add a string to the output buffer.

Parameters

s	The string to add.

This function should not be used outside the callback set with t3_term_set_user_callback.

t3_term_resize()

t3_bool t3_term_resize

(

void

)

Handle resizing of the terminal.

Returns

A boolean indicating success of the resizing operation, which depends on memory allocation success.

Should be called after a SIGWINCH. Retrieves the size of the terminal and resizes the backing structures. After calling t3_term_resize, t3_term_get_size can be called to retrieve the new terminal size.

t3_term_set_attrs()

void t3_term_set_attrs

(

t3_attr_t

new_attrs

)

Set terminal drawing attributes.

Parameters

new_attrs

The new attributes that should be used for subsequent character display.

t3_term_set_cursor()

void t3_term_set_cursor	(	int	y,
		int	x
	)

Move cursor.

Parameters

y	The terminal line to move the cursor to.
x	The terminal column to move the cursor to.

If the cursor is invisible the new position is recorded, but not actually moved yet. Moving the cursor takes effect immediately.

t3_term_set_replacement_char()

void t3_term_set_replacement_char

(

int

c

)

Set the replacement character used for undrawable characters.

Parameters

c	The character to draw when an undrawable characters is encountered.

The default character is the question mark ('?'). The character must be a Unicode character representable in the current character set. For terminals capable of Unicode output the Replacement Character is used (codepoint FFFD).

t3_term_set_user_callback()

void t3_term_set_user_callback

(

t3_attr_user_callback_t

callback

)

Set callback for drawing characters with T3_ATTR_USER attribute.

Parameters

callback

The function to call for drawing.

t3_term_show_cursor()

void t3_term_show_cursor

(

void

)

Show the cursor.

Instructs the terminal to make the cursor visible.

t3_term_strcwidth()

size_t t3_term_strcwidth

(

const char *

str

)

Calculate the cell width of a string.

Parameters

str	The string to calculate the width of.

Returns

The width of the string in character cells.

Using strlen on a string will not give one the correct width of a UTF-8 string on the terminal screen. This function is provided to calculate that value.

t3_term_strncwidth()

size_t t3_term_strncwidth	(	const char *	str,
		size_t	n
	)

Calculate the cell width of a string.

Parameters

str	The string to calculate the width of.
n	The length of str.

Returns

The width of the string in character cells.

Using strlen on a string will not give one the correct width of a UTF-8 string on the terminal screen. This function is provided to calculate that value.

t3_term_strnwidth()

int t3_term_strnwidth	(	const char *	str,
		size_t	n
	)

Calculate the cell width of a string.

Deprecated:

Use t3_term_strncwidth instead.

t3_term_strwidth()

int t3_term_strwidth

(

const char *

str

)

Calculate the cell width of a string.

Deprecated:

Use t3_term_strcwidth instead.

t3_term_unget_keychar()

int t3_term_unget_keychar

(

int

c

)

Push a char back for later retrieval with t3_term_get_keychar.

Parameters

c	The char to push back.

Returns

The char pushed back or T3_ERR_BAD_ARG.

Only a char just read from stdin with t3_term_get_keychar can be pushed back.

t3_term_update()

void t3_term_update

(

void

)

Update the terminal, drawing all changes since last refresh.

After changing window contents, this function should be called to make those changes visible on the terminal. The refresh is not done automatically to allow programs to bunch many separate updates. Generally this is called right before t3_term_get_keychar.