libt3window
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Modules
Data Structures | Macros | Typedefs | Enumerations | Functions
Contants, data types and miscellaneous functions.

Data Structures

struct  t3_term_caps_t
 Data structure to store information about the capabilities of the terminal. More...
 

Macros

#define T3_CHILD(_x)
 Define a child anchor point a relation (see t3_win_anchor_t). More...
 
#define T3_GETCHILD(_x)
 Get a child anchor point from a relation (see t3_win_anchor_t). More...
 
#define T3_GETPARENT(_x)
 Get a parent anchor point from a relation (see t3_win_anchor_t). More...
 
#define T3_PARENT(_x)
 Define a parent anchor point for a relation (see t3_win_anchor_t). More...
 
#define T3_TERM_CAP_BG
 Terminal capability flag: terminal can set foreground. More...
 
#define T3_TERM_CAP_CP
 Terminal capability flag: terminal uses color pairs for setting color. More...
 
#define T3_TERM_CAP_FG
 Terminal capability flag: terminal can set foreground. More...
 
#define T3_UTF8_CONTROL_MASK
 Category mask for libunistring's uc_is_general_category_withtable for finding control characters. More...
 

Typedefs

typedef long t3_attr_t
 Type to hold attributes used for terminal display. More...
 
typedef void(* t3_attr_user_callback_t )(const char *str, int length, int width, t3_attr_t attr)
 User callback type. More...
 
typedef char t3_bool
 A boolean type that does not clash with C++ or C99 bool. More...
 

Enumerations

enum  {
  T3_ACS_TTEE, T3_ACS_RTEE, T3_ACS_LTEE, T3_ACS_BTEE,
  T3_ACS_ULCORNER, T3_ACS_URCORNER, T3_ACS_LLCORNER, T3_ACS_LRCORNER,
  T3_ACS_HLINE, T3_ACS_VLINE, T3_ACS_UARROW, T3_ACS_DARROW,
  T3_ACS_LARROW, T3_ACS_RARROW, T3_ACS_BOARD, T3_ACS_CKBOARD,
  T3_ACS_BULLET, T3_ACS_DIAMOND, T3_ACS_BLOCK
}
 Alternate character set symbolic constants. More...
 
enum  { t3_false, t3_true }
 Values for t3_bool, a boolean type that does not clash with C++ or C99 bool. More...
 
enum  t3_win_anchor_t
 Anchor points for defining relations between the positions of two windows. More...
 

Functions

uint32_t t3_utf8_get (const char *src, size_t *size)
 Get the first codepoint represented by a UTF-8 string. More...
 
size_t t3_utf8_put (uint32_t c, char *dst)
 Convert a codepoint to a UTF-8 string. More...
 
int t3_utf8_wcwidth (uint32_t c)
 Get the width of a Unicode codepoint. More...
 
const char * t3_window_strerror (int error)
 Get a string description for an error code. More...
 

Version information

long t3_window_get_version (void)
 Get the value of T3_WINDOW_VERSION corresponding to the actually used library. More...
 
#define T3_WINDOW_VERSION
 The version of libt3window encoded as a single integer. More...
 

Attributes

#define T3_ATTR_USER
 Use callback for drawing the characters. More...
 
#define T3_ATTR_UNDERLINE
 Draw characters with underlining. More...
 
#define T3_ATTR_BOLD
 Draw characters with bold face/bright appearance. More...
 
#define T3_ATTR_REVERSE
 Draw characters with reverse video. More...
 
#define T3_ATTR_BLINK
 Draw characters blinking. More...
 
#define T3_ATTR_DIM
 Draw characters with dim appearance. More...
 
#define T3_ATTR_ACS
 Draw characters with alternate character set (for line drawing etc). More...
 
#define T3_ATTR_FALLBACK_ACS
 Draw characters with fallback alternate character set (for line drawing etc). More...
 
#define T3_ATTR_COLOR_SHIFT
 Bit number of the least significant color attribute bit. More...
 
#define T3_ATTR_FG(x)
 Convert a color number to a foreground color attribute. More...
 
#define T3_ATTR_BG(x)
 Convert a color number to a background color attribute. More...
 
#define T3_ATTR_FG_MASK
 Bitmask to leave only the foreground color in a t3_attr_t value. More...
 
#define T3_ATTR_BG_MASK
 Bitmask to leave only the background color in a t3_attr_t value. More...
 
#define T3_ATTR_FG_UNSPEC
 Foreground color unspecified. More...
 
#define T3_ATTR_FG_DEFAULT
 Foreground color default. More...
 
#define T3_ATTR_FG_BLACK
 Foreground color black. More...
 
#define T3_ATTR_FG_RED
 Foreground color red. More...
 
#define T3_ATTR_FG_GREEN
 Foreground color green. More...
 
#define T3_ATTR_FG_YELLOW
 Foreground color yellow. More...
 
#define T3_ATTR_FG_BLUE
 Foreground color blue. More...
 
#define T3_ATTR_FG_MAGENTA
 Foreground color magenta. More...
 
#define T3_ATTR_FG_CYAN
 Foreground color cyan. More...
 
#define T3_ATTR_FG_WHITE
 Foreground color white. More...
 
#define T3_ATTR_BG_UNSPEC
 Background color unspecified. More...
 
#define T3_ATTR_BG_DEFAULT
 Background color default. More...
 
#define T3_ATTR_BG_BLACK
 Background color black. More...
 
#define T3_ATTR_BG_RED
 Background color red. More...
 
#define T3_ATTR_BG_GREEN
 Background color green. More...
 
#define T3_ATTR_BG_YELLOW
 Background color yellow. More...
 
#define T3_ATTR_BG_BLUE
 Background color blue. More...
 
#define T3_ATTR_BG_MAGENTA
 Background color magenta. More...
 
#define T3_ATTR_BG_CYAN
 Background color cyan. More...
 
#define T3_ATTR_BG_WHITE
 Background color white. More...
 

Error codes (libt3window specific)

#define T3_ERR_NOT_A_TTY
 Error code: the file descriptor is not a terminal. More...
 
#define T3_ERR_TIMEOUT
 Error code: a timeout occured. More...
 
#define T3_ERR_NO_SIZE_INFO
 Error code: could not retrieve information about the size of the terminal window. More...
 
#define T3_ERR_NONPRINT
 Error code: input contains non-printable characters. More...
 
#define T3_ERR_CHARSET_ERROR
 Error code: could not open character-set conversion. More...
 
#define T3_WARN_UPDATE_TERMINAL
 Error code: terminal feature detection has finished and the terminal should be updated. More...
 

Error codes (T3 generic)

#define T3_ERR_SUCCESS
 Error code: success.
 
#define T3_ERR_ERRNO
 Error code: see errno. More...
 
#define T3_ERR_EOF
 Error code: end of file reached. More...
 
#define T3_ERR_UNKNOWN
 Error code: unkown error. More...
 
#define T3_ERR_BAD_ARG
 Error code: bad argument. More...
 
#define T3_ERR_OUT_OF_MEMORY
 Error code: out of memory. More...
 
#define T3_ERR_TERMINFODB_NOT_FOUND
 Error code: no information found for the terminal in the terminfo database. More...
 
#define T3_ERR_HARDCOPY_TERMINAL
 Error code: the file descriptor is a hard-copy terminal. More...
 
#define T3_ERR_TERMINAL_TOO_LIMITED
 Error code: terminal provides too limited possibilities for the library to function. More...
 
#define T3_ERR_NO_TERM
 Error code: no terminal given and TERM environment variable not set. More...
 
#define T3_ERR_INTERNAL
 Error code: internal error in the library. More...
 
#define T3_WARN_MIN
 Warning code: the smallest value returned as warning. More...
 

Detailed Description

Macro Definition Documentation

#define T3_ATTR_ACS

Draw characters with alternate character set (for line drawing etc).

#define T3_ATTR_BG (   x)

Convert a color number to a background color attribute.

#define T3_ATTR_BG_BLACK

Background color black.

#define T3_ATTR_BG_BLUE

Background color blue.

#define T3_ATTR_BG_CYAN

Background color cyan.

#define T3_ATTR_BG_DEFAULT

Background color default.

#define T3_ATTR_BG_GREEN

Background color green.

#define T3_ATTR_BG_MAGENTA

Background color magenta.

#define T3_ATTR_BG_MASK

Bitmask to leave only the background color in a t3_attr_t value.

#define T3_ATTR_BG_RED

Background color red.

#define T3_ATTR_BG_UNSPEC

Background color unspecified.

#define T3_ATTR_BG_WHITE

Background color white.

#define T3_ATTR_BG_YELLOW

Background color yellow.

#define T3_ATTR_BLINK

Draw characters blinking.

#define T3_ATTR_BOLD

Draw characters with bold face/bright appearance.

#define T3_ATTR_COLOR_SHIFT

Bit number of the least significant color attribute bit.

#define T3_ATTR_DIM

Draw characters with dim appearance.

#define T3_ATTR_FALLBACK_ACS

Draw characters with fallback alternate character set (for line drawing etc).

This attribute will result if the terminal can not combine color video with drawing characters with the alternate character set. This attribute should not be used directly.

#define T3_ATTR_FG (   x)

Convert a color number to a foreground color attribute.

#define T3_ATTR_FG_BLACK

Foreground color black.

#define T3_ATTR_FG_BLUE

Foreground color blue.

#define T3_ATTR_FG_CYAN

Foreground color cyan.

#define T3_ATTR_FG_DEFAULT

Foreground color default.

#define T3_ATTR_FG_GREEN

Foreground color green.

#define T3_ATTR_FG_MAGENTA

Foreground color magenta.

#define T3_ATTR_FG_MASK

Bitmask to leave only the foreground color in a t3_attr_t value.

#define T3_ATTR_FG_RED

Foreground color red.

#define T3_ATTR_FG_UNSPEC

Foreground color unspecified.

#define T3_ATTR_FG_WHITE

Foreground color white.

#define T3_ATTR_FG_YELLOW

Foreground color yellow.

#define T3_ATTR_REVERSE

Draw characters with reverse video.

#define T3_ATTR_UNDERLINE

Draw characters with underlining.

#define T3_ATTR_USER

Use callback for drawing the characters.

When T3_ATTR_USER is set all other attribute bits are ignored. These can be used by the callback to determine the drawing style. The callback is set with t3_term_set_user_callback. Note that the callback is responsible for outputing the characters as well (using t3_term_putc).

#define T3_CHILD (   _x)

Define a child anchor point a relation (see t3_win_anchor_t).

#define T3_ERR_BAD_ARG

Error code: bad argument.

#define T3_ERR_CHARSET_ERROR

Error code: could not open character-set conversion.

#define T3_ERR_EOF

Error code: end of file reached.

#define T3_ERR_ERRNO

Error code: see errno.

#define T3_ERR_HARDCOPY_TERMINAL

Error code: the file descriptor is a hard-copy terminal.

#define T3_ERR_INTERNAL

Error code: internal error in the library.

#define T3_ERR_NO_SIZE_INFO

Error code: could not retrieve information about the size of the terminal window.

#define T3_ERR_NO_TERM

Error code: no terminal given and TERM environment variable not set.

#define T3_ERR_NONPRINT

Error code: input contains non-printable characters.

#define T3_ERR_NOT_A_TTY

Error code: the file descriptor is not a terminal.

#define T3_ERR_OUT_OF_MEMORY

Error code: out of memory.

#define T3_ERR_TERMINAL_TOO_LIMITED

Error code: terminal provides too limited possibilities for the library to function.

#define T3_ERR_TERMINFODB_NOT_FOUND

Error code: no information found for the terminal in the terminfo database.

#define T3_ERR_TIMEOUT

Error code: a timeout occured.

#define T3_ERR_UNKNOWN

Error code: unkown error.

#define T3_GETCHILD (   _x)

Get a child anchor point from a relation (see t3_win_anchor_t).

#define T3_GETPARENT (   _x)

Get a parent anchor point from a relation (see t3_win_anchor_t).

#define T3_PARENT (   _x)

Define a parent anchor point for a relation (see t3_win_anchor_t).

#define T3_TERM_CAP_BG

Terminal capability flag: terminal can set foreground.

#define T3_TERM_CAP_CP

Terminal capability flag: terminal uses color pairs for setting color.

#define T3_TERM_CAP_FG

Terminal capability flag: terminal can set foreground.

#define T3_UTF8_CONTROL_MASK

Category mask for libunistring's uc_is_general_category_withtable for finding control characters.

#define T3_WARN_MIN

Warning code: the smallest value returned as warning.

#define T3_WARN_UPDATE_TERMINAL

Error code: terminal feature detection has finished and the terminal should be updated.

#define T3_WINDOW_VERSION

The version of libt3window encoded as a single integer.

The least significant 8 bits represent the patch level. The second 8 bits represent the minor version. The third 8 bits represent the major version.

At runtime, the value of T3_WINDOW_VERSION can be retrieved by calling
::t3_window_get_version.

Typedef Documentation

Type to hold attributes used for terminal display.

The value of a t3_attr_t should be a bitwise or of T3_ATTR_* attribute values. When the terminal only supports setting colors by color pair, the T3_ATTR_FG macro can be used to specify the color pair to activate.

typedef void(* t3_attr_user_callback_t)(const char *str, int length, int width, t3_attr_t attr)

User callback type.

The user callback is passed a pointer to the characters that are is marked with T3_ATTR_USER, the length of the string, the width of the string in display cells and the attributes they are drawn with.

typedef char t3_bool

A boolean type that does not clash with C++ or C99 bool.

Enumeration Type Documentation

anonymous enum

Alternate character set symbolic constants.

Enumerator
T3_ACS_TTEE 

Tee pointing down.

T3_ACS_RTEE 

Tee pointing left.

T3_ACS_LTEE 

Tee pointing right.

T3_ACS_BTEE 

Tee pointing up.

T3_ACS_ULCORNER 

Upper left corner.

T3_ACS_URCORNER 

Upper right corner.

T3_ACS_LLCORNER 

Lower left corner.

T3_ACS_LRCORNER 

Lower right corner.

T3_ACS_HLINE 

Horizontal line.

T3_ACS_VLINE 

Vertical line.

T3_ACS_UARROW 

Arrow pointing up.

T3_ACS_DARROW 

Arrow pointing down.

T3_ACS_LARROW 

Arrow pointing left.

T3_ACS_RARROW 

Arrow pointing right.

T3_ACS_BOARD 

Board of squares.

T3_ACS_CKBOARD 

Checker board pattern (stipple).

T3_ACS_BULLET 

Bullet.

T3_ACS_DIAMOND 

Diamond.

T3_ACS_BLOCK 

Solid block.

anonymous enum

Values for t3_bool, a boolean type that does not clash with C++ or C99 bool.

Enumerator
t3_false 

False.

t3_true 

True.

Anchor points for defining relations between the positions of two windows.

The anchor points can be used to define the relative positioning of two windows. For example, using T3_PARENT(T3_ANCHOR_TOPRIGHT) | T3_CHILD(T3_ANCHOR_TOPLEFT) allows positioning of one window left of another.

Function Documentation

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

Get the first codepoint represented by a UTF-8 string.

Parameters
srcThe UTF-8 string to parse.
sizeThe location to store the number of bytes in the first codepoint, which should contain the number of bytes in src on entry (may be NULL).
Returns
The codepoint at the start of src or FFFD if an invalid codepoint is encountered.
size_t t3_utf8_put ( uint32_t  c,
char *  dst 
)

Convert a codepoint to a UTF-8 string.

Parameters
cThe codepoint to convert.
dstThe location to store the result.
Returns
The number of bytes stored in dst.

If an invalid codepoint is passed in c, the replacement character (FFFD) is stored instead

int t3_utf8_wcwidth ( uint32_t  c)

Get the width of a Unicode codepoint.

This function is a wrapper around uc_width, which takes into account that for some characters uc_width returns a value that is different from what terminals actually use.

long t3_window_get_version ( void  )

Get the value of T3_WINDOW_VERSION corresponding to the actually used library.

Returns
The value of T3_WINDOW_VERSION.

This function can be useful to determine at runtime what version of the library was linked to the program. Although currently there are no known uses for this information, future library additions may prompt library users to want to operate differently depending on the available features.

const char* t3_window_strerror ( int  error)

Get a string description for an error code.

Parameters
errorThe error code returned by a function in libt3window.
Returns
An internationalized string description for the error code.