1TICKIT_PEN(7)          Miscellaneous Information Manual          TICKIT_PEN(7)
2
3
4

NAME

6       TickitPen - store a collection of terminal rendering attributes
7

SYNOPSIS

9       #include <tickit.h>
10
11       typedef struct TickitPen;
12
13

DESCRIPTION

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

FUNCTIONS

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

ATTRIBUTES

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
37       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
47       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
51       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
60       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
69              Valid values are:
70
71              TICKIT_PEN_UNDER_NONE
72                     No underline.
73
74              TICKIT_PEN_UNDER_SINGLE
75                     Single underline.
76
77              TICKIT_PEN_UNDER_DOUBLE
78                     Double underline.
79
80              TICKIT_PEN_UNDER_WAVY
81                     Single wavy underline, sometimes called "undercurl".
82
83              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
88       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

FUNCTIONS

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
105       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

EVENTS

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
122       The event types recognised are:
123
124       TICKIT_PEN_ON_DESTROY
125              The pen instance is being destroyed.
126
127       TICKIT_PEN_ON_CHANGE
128              The stored attributes on the pen have changed. The info  pointer
129              will be NULL.
130
131
132
133                                                                 TICKIT_PEN(7)
Impressum