1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
|
.TH TICKIT_PEN 7
.SH NAME
TickitPen \- store a collection of terminal rendering attributes
.SH SYNOPSIS
.EX
.B #include <tickit.h>
.sp
.BI "typedef struct " TickitPen ;
.EE
.sp
.SH DESCRIPTION
A \fBTickitPen\fP instance stores a collection of terminal rendering attributes. For each known attribute, a pen instance may store a value for this attribute. A pen instance is used in the \fBtickit_term_chpen\fP(3) and \fBtickit_term_setpen\fP(3) functions.
.SH FUNCTIONS
A new \fBTickitPen\fP instance is created using the \fBtickit_pen_new\fP(3) function, and destroyed using \fBtickit_pen_destroy\fP(3). A pen instance stores a reference count, to make it easier for applications to manage the lifetime of pens. A new pen starts with a count of one, and it can be adjusted using \fBtickit_pen_ref\fP(3) and \fBtickit_pen_unref\fP(3). When it reaches zero it is destroyed.
.SH ATTRIBUTES
The \fBTickitPenAttr\fP enumeration lists the attributes known by a pen. Each attribute has a type, as given by the \fBTickitPenAttrType\fP enumeration. The \fBtickit_pen_attrtype\fP(3) function gives the type of a given attribute. The \fBtickit_pen_attrname\fP(3) function gives the name of a given attribute, which is also given below in parentheses. The \fBtickit_pen_lookup_attr\fP(3) function looks up an attribute constant from a string containing the name.
.TP
\fBTICKIT_PEN_FG\fP ("fg"), \fBTICKIT_PEN_BG\fP ("bg")
foreground and background colours. These are of type \fBTICKIT_PENTYPE_COLOUR\fP. This gives an integer from 0 to 255 to use as the colour index. It may also be set to the value -1, which sets the terminal's default, which may be a colour distinct from any of the others. Some terminals may not support more than 8 or 16 colours, however. When setting a pen colour on a terminal, it may be converted to one that is supported by the terminal \fBtickit_term_setpen\fP(3) or \fBtickit_term_chpen\fP(3) functions.
.TP
\fBTICKIT_PEN_BOLD\fP ("b"), \fBTICKIT_PEN_UNDER\fP ("u"), \fBTICKIT_PEN_ITALIC\fP ("i"), \fBTICKIT_PEN_REVERSE\fP ("rv"), \fBTICKIT_PEN_STRIKE\fP ("strike"), \fBTICKIT_PEN_BLINK\fP ("blink")
boolean rendering attributes. These are of type \fBTICKIT_PENTYPE_BOOL\fP. They are either true or false. Most terminals should support at least bold, underline, reverse and blink, though italic and strikethrough are less commonly supported. Applications are advised not to use these two alone to distinguish significant parts of the user interface.
.TP
\fBTICKIT_PEN_ALTFONT\fP ("af")
alternate font index. This is of type \fBTICKIT_PENTYPE_INT\fP. It is a value 0 to 9, which selects from the terminal's available fonts. Few terminals actually support this in practice.
.SH FUNCTIONS
The values of attributes are set or queried on a pen instance by using functions depending on the type of the attribute. Boolean attributes use \fBtickit_pen_set_bool_attr\fP(3) and \fBtickit_pen_get_bool_attr\fP(3). Integer attributes use \fBtickit_pen_set_int_attr\fP(3) and \fBtickit_pen_get_int_attr\fP(3). Colour attributes use \fBtickit_pen_set_colour_attr\fP(3), \fBtickit_pen_set_colour_attr_desc\fP(3) and \fBtickit_pen_get_colour_attr\fP(3).
.PP
To test if an attribute has a value set, use \fBtickit_pen_has_attr\fP(3), and to remove the attribute entirely use \fBtickit_pen_clear_attr\fP(3). To test if a pen has any attributes set at all, use \fBtickit_pen_is_nonempty\fP(3), and to test if it has any attributes set to a non-default value use \fBtickit_pen_is_nondefault\fP(3). To remove all the attributes use \fBtickit_pen_clear\fP(3). To copy the value of one attribute from a pen into another pen use \fBtickit_pen_copy_attr\fP(3), to copy the entire pen use \fBtickit_pen_copy\fP(3), and to compare two pens for equallity use \fBtickit_pen_equiv_attr\fP(3).
.SH EVENTS
A pen instance stores a set of event handlers. Each event handler consists of a bitmask of one or more event types it is interested in, a function pointer, and an arbitrary pointer containing user data. Event handlers may be installed using \fBtickit_pen_bind_event\fP(3) and removed using \fBtickit_pen_unbind_event_id\fP(3).
.PP
The event types recognised are:
.TP
.B TICKIT_EV_CHANGE
The stored attributes on the pen have changed. The \fIinfo\fP pointer will be \fBNULL\fP.
|
