Window manipulation functions.

Functions
uint32_t	_t3_get_value_int (const char *src, size_t *size)
	Get the first UTF-8 value encoded in a string. More...
size_t	_t3_put_value (uint32_t c, char *dst)
	Write a UTF-8 encoded value. More...
t3_bool	_t3_win_is_shown (t3_window_t *win)
	Check whether a window is show, both by the direct setting of the shown flag, as well as the parents.
int	t3_win_addch (t3_window_t *win, char c, t3_attr_t attr)
	Add a single character to a t3_window_t with specified attributes. More...
int	t3_win_addchrep (t3_window_t *win, char c, t3_attr_t attr, int rep)
	Add a character to a t3_window_t with specified attributes and repetition. More...
int	t3_win_addnstr (t3_window_t *win, const char *str, size_t n, t3_attr_t attrs)
	Add a string with explicitly specified size to a t3_window_t with specified attributes. More...
int	t3_win_addnstrrep (t3_window_t *win, const char *str, size_t n, t3_attr_t attr, int rep)
	Add a string with explicitly specified size to a t3_window_t with specified attributes and repetition. More...
int	t3_win_addstr (t3_window_t *win, const char *str, t3_attr_t attr)
	Add a nul-terminated string to a t3_window_t with specified attributes. More...
int	t3_win_addstrrep (t3_window_t *win, const char *str, t3_attr_t attr, int rep)
	Add a nul-terminated string to a t3_window_t with specified attributes and repetition. More...
t3_window_t *	t3_win_at_location (int search_y, int search_x)
	Find the top-most window at a location. More...
int	t3_win_box (t3_window_t *win, int y, int x, int height, int width, t3_attr_t attr)
	Draw a box on a t3_window_t. More...
void	t3_win_clrtobot (t3_window_t *win)
	Clear current t3_window_t painting line to end and all subsequent lines fully.
void	t3_win_clrtoeol (t3_window_t *win)
	Clear current t3_window_t painting line to end.
void	t3_win_del (t3_window_t *win)
	Discard a t3_window_t. More...
int	t3_win_get_abs_x (const t3_window_t *win)
	Get a t3_window_t's absolute horizontal position.
int	t3_win_get_abs_y (const t3_window_t *win)
	Get a t3_window_t's absolute vertical position.
int	t3_win_get_depth (const t3_window_t *win)
	Get a t3_window_t's depth.
int	t3_win_get_height (const t3_window_t *win)
	Get a t3_window_t's height.
t3_window_t *	t3_win_get_parent (const t3_window_t *win)
	Get a t3_window_t's parent window.
int	t3_win_get_relation (const t3_window_t *win, t3_window_t **anchor)
	Get a t3_window_t's relative positioning information. More...
int	t3_win_get_width (const t3_window_t *win)
	Get a t3_window_t's width.
int	t3_win_get_x (const t3_window_t *win)
	Get a t3_window_t's horizontal position. More...
int	t3_win_get_y (const t3_window_t *win)
	Get a t3_window_t's vertical position. More...
void	t3_win_hide (t3_window_t *win)
	Make a t3_window_t invisible.
t3_bool	t3_win_is_shown (t3_window_t *win)
	Returns whether the t3_window_t is visible.
void	t3_win_move (t3_window_t *win, int y, int x)
	Change a t3_window_t's position. More...
t3_window_t *	t3_win_new (t3_window_t *parent, int height, int width, int y, int x, int depth)
	Create a new t3_window_t. More...
t3_window_t *	t3_win_new_unbacked (t3_window_t *parent, int height, int width, int y, int x, int depth)
	Create a new t3_window_t with relative position without backing store. More...
t3_bool	t3_win_resize (t3_window_t *win, int height, int width)
	Change a t3_window_t's size. More...
t3_bool	t3_win_set_anchor (t3_window_t *win, t3_window_t *anchor, int relation)
	Link a t3_window_t's position to the position of another t3_window_t. More...
void	t3_win_set_cursor (t3_window_t *win, int y, int x)
	Position the cursor relative to a t3_window_t. More...
void	t3_win_set_default_attrs (t3_window_t *win, t3_attr_t attrs)
	Set default attributes for a window. More...
void	t3_win_set_depth (t3_window_t *win, int depth)
	Change the depth of a t3_window_t. More...
void	t3_win_set_paint (t3_window_t *win, int y, int x)
	Change the position where characters are written to the t3_window_t.
t3_bool	t3_win_set_parent (t3_window_t *win, t3_window_t *parent)
	Change a t3_window_t's parent. More...
t3_bool	t3_win_set_restrict (t3_window_t *win, t3_window_t *restrictw)
	Set the restrictw window. More...
void	t3_win_show (t3_window_t *win)
	Make a t3_window_t visible.

Detailed Description

Function Documentation

_t3_get_value_int()

uint32_t _t3_get_value_int	(	const char *	src,
		size_t *	size
	)

Get the first UTF-8 value encoded in a string.

Parameters

src	The UTF-8 string to parse.
size	The location to store the size of the character.

Returns

The value at the start of src.

Note

This function assumes that the input is a valid UTF-8 encoded value.

_t3_put_value()

size_t _t3_put_value	(	uint32_t	c,
		char *	dst
	)

Write a UTF-8 encoded value.

Parameters

c	The codepoint to convert.
dst	The location to store the result.

Returns

The number of bytes stored in dst.

The value must be lower than 0x80000000 (i.e. at most 31 bits may be used). No check is made for this however, so the calling code must ensure that this is the case.

t3_win_addch()

int t3_win_addch	(	t3_window_t *	win,
		char	c,
		t3_attr_t	attr
	)

Add a single character to a t3_window_t with specified attributes.

Parameters

win	The t3_window_t to add the string to.
c	The character to add.
attr	The attributes to use.

Returns

See t3_win_addnstr.

@p c must be an ASCII character. See ::t3_win_addnstr for further information.

t3_win_addchrep()

int t3_win_addchrep	(	t3_window_t *	win,
		char	c,
		t3_attr_t	attr,
		int	rep
	)

Add a character to a t3_window_t with specified attributes and repetition.

Parameters

win	The t3_window_t to add the string to.
c	The character to add.
attr	The attributes to use.
rep	The number of times to repeat c.

Returns

See t3_win_addnstr.

See t3_win_addnstrrep for further information.

t3_win_addnstr()

int t3_win_addnstr	(	t3_window_t *	win,
		const char *	str,
		size_t	n,
		t3_attr_t	attrs
	)

Add a string with explicitly specified size to a t3_window_t with specified attributes.

Parameters

win	The t3_window_t to add the string to.
str	The string to add.
n	The size of str.
attrs	The attributes to use.

Return values

T3_ERR_SUCCESS	on succes
T3_ERR_NONPRINT	if a control character was encountered.
T3_ERR_ERRNO	otherwise.

The default attributes are combined with the specified attributes, with attr used as the priority attributes. All other t3_win_add* functions are (indirectly) implemented using this function.

It is important that combining characters are provided in the same string as the characters they are to combine with. In particular, this function does not check for conjoining Jamo in the existing window data and explicitly prevents joining.

t3_win_addnstrrep()

int t3_win_addnstrrep	(	t3_window_t *	win,
		const char *	str,
		size_t	n,
		t3_attr_t	attr,
		int	rep
	)

Add a string with explicitly specified size to a t3_window_t with specified attributes and repetition.

Parameters

win	The t3_window_t to add the string to.
str	The string to add.
n	The size of str.
attr	The attributes to use.
rep	The number of times to repeat str.

Returns

See t3_win_addnstr.

All other t3_win_add*rep functions are (indirectly) implemented using this

function. See t3_win_addnstr for further information.

t3_win_addstr()

int t3_win_addstr	(	t3_window_t *	win,
		const char *	str,
		t3_attr_t	attr
	)

Add a nul-terminated string to a t3_window_t with specified attributes.

Parameters

win	The t3_window_t to add the string to.
str	The nul-terminated string to add.
attr	The attributes to use.

Returns

See t3_win_addnstr.

See ::t3_win_addnstr for further information.

t3_win_addstrrep()

int t3_win_addstrrep	(	t3_window_t *	win,
		const char *	str,
		t3_attr_t	attr,
		int	rep
	)

Add a nul-terminated string to a t3_window_t with specified attributes and repetition.

Parameters

win	The t3_window_t to add the string to.
str	The nul-terminated string to add.
attr	The attributes to use.
rep	The number of times to repeat str.

Returns

See t3_win_addnstr.

See t3_win_addnstrrep for further information.

t3_win_at_location()

t3_window_t* t3_win_at_location	(	int	search_y,
		int	search_x
	)

Find the top-most window at a location.

Returns

The top-most window at the specified location, or NULL if no window covers the specified location.

t3_win_box()

int t3_win_box	(	t3_window_t *	win,
		int	y,
		int	x,
		int	height,
		int	width,
		t3_attr_t	attr
	)

Draw a box on a t3_window_t.

Parameters

win	The t3_window_t to draw on.
y	The line of the t3_window_t to start drawing on.
x	The column of the t3_window_t to start drawing on.
height	The height of the box to draw.
width	The width of the box to draw.
attr	The attributes to use for drawing.

Returns

See t3_win_addnstr.

t3_win_del()

void t3_win_del

(

t3_window_t *

win

)

Discard a t3_window_t.

Parameters

win	The t3_window_t to discard.

Note that child windows are not automatically discarded as well. All child windows have their parent attribute set to NULL.

t3_win_get_relation()

int t3_win_get_relation	(	const t3_window_t *	win,
		t3_window_t **	anchor
	)

Get a t3_window_t's relative positioning information.

Parameters

	win	The t3_window_t to get the relative positioning information for.
[out]	anchor	The location to store the pointer to the t3_window_t relative to which the position is specified.

Returns

The relative positioning method.

To retrieve the separate parts of the relative positioning information, use T3_GETPARENT and T3_GETCHILD.

t3_win_get_x()

int t3_win_get_x

(

const t3_window_t *

win

)

Get a t3_window_t's horizontal position.

The retrieved position may be relative to another window. Use t3_win_get_abs_x to find the absolute position.

t3_win_get_y()

int t3_win_get_y

(

const t3_window_t *

win

)

Get a t3_window_t's vertical position.

The retrieved position may be relative to another window. Use t3_win_get_abs_y to find the absolute position.

t3_win_move()

void t3_win_move	(	t3_window_t *	win,
		int	y,
		int	x
	)

Change a t3_window_t's position.

Parameters

win	The t3_window_t to change the position of.
y	The desired new vertical position of the t3_window_t in terminal lines.
x	The desired new horizontal position of the t3_window_t in terminal lines.

This function will always succeed as it only updates the internal book keeping.

t3_win_new()

t3_window_t* t3_win_new	(	t3_window_t *	parent,
		int	height,
		int	width,
		int	y,
		int	x,
		int	depth
	)

Create a new t3_window_t.

Parameters

parent	t3_window_t used for clipping and relative positioning.
height	The desired height in terminal lines.
width	The desired width in terminal columns.
y	The vertical location of the window in terminal lines.
x	The horizontal location of the window in terminal columns.
depth	The depth of the window in the stack of windows.

Returns

A pointer to a new t3_window_t struct or NULL if not enough memory could be allocated.

The depth parameter determines the z-order of the windows. Windows with lower depth will hide windows with higher depths. However, this only holds relative to the parent window. The position will be relative to the top-left corner of the parent window, or to the top-left corner of the terminal if parent is NULL.

t3_win_new_unbacked()

t3_window_t* t3_win_new_unbacked	(	t3_window_t *	parent,
		int	height,
		int	width,
		int	y,
		int	x,
		int	depth
	)

Create a new t3_window_t with relative position without backing store.

Parameters

parent	t3_window_t used for clipping.
height	The desired height in terminal lines.
width	The desired width in terminal columns.
y	The vertical location of the window in terminal lines.
x	The horizontal location of the window in terminal columns.
depth	The depth of the window in the stack of windows.

Returns

A pointer to a new t3_window_t struct or NULL if not enough memory could be allocated or an invalid parameter was passed.

Windows without a backing store can not be used for drawing. These are only defined to allow a window for positioning other windows.

The depth parameter determines the z-order of the windows. Windows with lower depth will hide windows with higher depths.

t3_win_resize()

t3_bool t3_win_resize	(	t3_window_t *	win,
		int	height,
		int	width
	)

Change a t3_window_t's size.

Parameters

win	The t3_window_t to change the size of.
height	The desired new height of the t3_window_t in terminal lines.
width	The desired new width of the t3_window_t in terminal columns.

Returns

A boolean indicating succes, depending on the validity of the parameters and whether reallocation of the internal data structures succeeds.

t3_win_set_anchor()

t3_bool t3_win_set_anchor	(	t3_window_t *	win,
		t3_window_t *	anchor,
		int	relation
	)

Link a t3_window_t's position to the position of another t3_window_t.

Parameters

win	The t3_window_t to set the anchor for.
anchor	The t3_window_t to link to.
relation	The relation between this window and anchor (see t3_win_anchor_t).

Returns

A boolean indicating whether the setting was successful.

This function will fail if either the relation is not valid, or setting the anchor will cause a loop in the window tree.

t3_win_set_cursor()

void t3_win_set_cursor	(	t3_window_t *	win,
		int	y,
		int	x
	)

Position the cursor relative to a t3_window_t.

Parameters

win	The t3_window_t to position the cursor in.
y	The line relative to win to position the cursor at.
x	The column relative to win to position the cursor at.

The cursor is only moved if the window is currently shown.

t3_win_set_default_attrs()

void t3_win_set_default_attrs	(	t3_window_t *	win,
		t3_attr_t	attrs
	)

Set default attributes for a window.

Parameters

win	The t3_window_t to set the default attributes for.
attrs	The attributes to set.

This function can be used to set a default background for the entire window, as well as any other attributes.

t3_win_set_depth()

void t3_win_set_depth	(	t3_window_t *	win,
		int	depth
	)

Change the depth of a t3_window_t.

Parameters

win	The t3_window_t to set the depth for.
depth	The new depth for the window.

t3_win_set_parent()

t3_bool t3_win_set_parent	(	t3_window_t *	win,
		t3_window_t *	parent
	)

Change a t3_window_t's parent.

Parameters

win	The t3_window_t to set the parent for.
parent	The t3_window_t to link to.

Returns

A boolean indicating whether the setting was successful.

This function will fail if setting the parent will cause a loop in the window tree.

t3_win_set_restrict()

t3_bool t3_win_set_restrict	(	t3_window_t *	win,
		t3_window_t *	restrictw
	)

Set the restrictw window.

Parameters

win	The t3_window_t to set the restrictw parameter for.
restrictw	The t3_window_t to restrictw win to.

To restrict the window to the terminal, pass NULL in restrictw. To cancel restriction of the window position, pass win in restrictw.