1TICKIT_PEN(7) Miscellaneous Information Manual TICKIT_PEN(7)
2
6 TickitPen - store a collection of terminal rendering attributes
7
9 #include <tickit.h>
10 typedef struct TickitPen;
12
15 A TickitPen instance stores a collection of terminal rendering at‐
16 tributes. For each known attribute, a pen instance may store a value
17 for this attribute. A pen instance is used in the tickit_term_chpen(3)
18 and tickit_term_setpen(3) functions.
19
21 A new TickitPen instance is created using the tickit_pen_new(3) func‐
22 tion. A pen instance stores a reference count to make it easier for ap‐
23 plications to manage the lifetime of pens. A new pen starts with a
24 count of one, and it can be adjusted using tickit_pen_ref(3) and
25 tickit_pen_unref(3). When the count reaches zero the instance is de‐
26 stroyed.
27
29 The TickitPenAttr enumeration lists the attributes known by a pen. Each
30 attribute has a type, as given by the TickitPenAttrType enumeration.
31 The tickit_pen_attrtype(3) function gives the type of a given attri‐
32 bute. The tickit_pen_attrname(3) function gives the name of a given at‐
33 tribute, which is also given below in parentheses. The
34 tickit_pen_lookup_attr(3) function looks up an attribute constant from
35 a string containing the name.
36 TICKIT_PEN_FG ("fg"), TICKIT_PEN_BG ("bg")
38 foreground and background colours. These are of type TICKIT_PEN‐
39 TYPE_COLOUR. This gives an integer from 0 to 255 to use as the
40 colour index. It may also be set to the value -1, which sets the
41 terminal's default, which may be a colour distinct from any of
42 the others. Some terminals may not support more than 8 or 16
43 colours, however. When setting a pen colour on a terminal, it
44 may be converted to one that is supported by the terminal
45 tickit_term_setpen(3) or tickit_term_chpen(3) functions.
46 These colour attributes also support a secondary RGB8 (24-bit) specifi‐
48 cation, which some terminal drivers may prefer over the indexed ver‐
49 sion.
50 TICKIT_PEN_BOLD ("b"), TICKIT_PEN_ITALIC ("i"), TICKIT_PEN_REVERSE
52 ("rv"), TICKIT_PEN_STRIKE ("strike"), TICKIT_PEN_BLINK ("blink")
53 boolean rendering attributes. These are of type TICKIT_PEN‐
54 TYPE_BOOL. They are either true or false. Most terminals should
55 support at least bold, underline, reverse and blink, though
56 italic and strikethrough are less commonly supported. Applica‐
57 tions are advised not to use these two alone to distinguish sig‐
58 nificant parts of the user interface.
59 TICKIT_PEN_UNDER ("u")
61 underline. This is of type TICKIT_PENTYPE_INT. Its value is one
62 of the values from the TickitPenUnderline enumeration. Most ter‐
63 minals should support the single underline value, however other
64 values are less commonly supported, and may be drawn instead as
65 a single underline. Applications are advised not to make use of
66 underline style alone to distinguish significant parts of the
67 user interface.
68 Valid values are:
70 TICKIT_PEN_UNDER_NONE
72 No underline.
73 TICKIT_PEN_UNDER_SINGLE
75 Single underline.
76 TICKIT_PEN_UNDER_DOUBLE
78 Double underline.
79 TICKIT_PEN_UNDER_WAVY
81 Single wavy underline, sometimes called "undercurl".
82 For backward-compatibility this attribute will also behave like
84 a boolean-typed attribute. When set to any value other than
85 none, it appears true as a boolean. Setting it to true as a
86 booelan will set its value to single.
87 TICKIT_PEN_ALTFONT ("af")
89 alternate font index. This is of type TICKIT_PENTYPE_INT. It is
90 a value 0 to 9, which selects from the terminal's available
91 fonts. Few terminals actually support this in practice.
92
94 The values of attributes are set or queried on a pen instance by using
95 functions depending on the type of the attribute. Boolean attributes
96 use tickit_pen_set_bool_attr(3) and tickit_pen_get_bool_attr(3). Inte‐
97 ger attributes use tickit_pen_set_int_attr(3) and
98 tickit_pen_get_int_attr(3). Colour attributes use
99 tickit_pen_set_colour_attr(3), tickit_pen_set_colour_attr_desc(3) and
100 tickit_pen_get_colour_attr(3). The RGB8 secondary field for colours can
101 be set with tickit_pen_set_colour_attr_rgb8(3), and queried with
102 tickit_pen_has_colour_attr_rgb8(3) and
103 tickit_pen_get_colour_attr_rgb8(3).
104 To test if an attribute has a value set, use tickit_pen_has_attr(3),
106 and to remove the attribute entirely use tickit_pen_clear_attr(3). To
107 test if a pen has any attributes set at all, use
108 tickit_pen_is_nonempty(3), and to test if it has any attributes set to
109 a non-default value use tickit_pen_is_nondefault(3). To remove all the
110 attributes use tickit_pen_clear(3). To copy the value of one attribute
111 from a pen into another pen use tickit_pen_copy_attr(3), to copy the
112 entire pen use tickit_pen_copy(3), and to compare two pens for equality
113 use tickit_pen_equiv_attr(3).
114
116 A pen instance stores a list of event handlers. Each event handler is
117 associated with one event type and stores a function pointer, and an
118 arbitrary pointer containing user data. Event handlers may be installed
119 using tickit_pen_bind_event(3) and removed using tickit_pen_un‐
120 bind_event_id(3).
121 The event types recognised are:
123 TICKIT_PEN_ON_DESTROY
125 The pen instance is being destroyed.
126 TICKIT_PEN_ON_CHANGE
128 The stored attributes on the pen have changed. The info pointer
129 will be NULL.
130 TICKIT_PEN(7)