Provided by: libtickit-dev_0.3.4-1_amd64 
NAME
TickitPen - store a collection of terminal rendering attributes
SYNOPSIS
#include <tickit.h>
typedef struct TickitPen;
DESCRIPTION
A TickitPen 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 tickit_term_chpen(3) and
tickit_term_setpen(3) functions.
FUNCTIONS
A new TickitPen instance is created using the tickit_pen_new(3) function. 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 tickit_pen_ref(3) and tickit_pen_unref(3). When the count reaches zero the instance is destroyed.
ATTRIBUTES
The TickitPenAttr enumeration lists the attributes known by a pen. Each attribute has a type, as given by
the TickitPenAttrType enumeration. The tickit_pen_attrtype(3) function gives the type of a given
attribute. The tickit_pen_attrname(3) function gives the name of a given attribute, which is also given
below in parentheses. The tickit_pen_lookup_attr(3) function looks up an attribute constant from a string
containing the name.
TICKIT_PEN_FG ("fg"), TICKIT_PEN_BG ("bg")
foreground and background colours. These are of type TICKIT_PENTYPE_COLOUR. 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 tickit_term_setpen(3) or tickit_term_chpen(3)
functions.
These colour attributes also support a secondary RGB8 (24-bit) specification, which some terminal drivers
may prefer over the indexed version.
TICKIT_PEN_BOLD ("b"), TICKIT_PEN_ITALIC ("i"), TICKIT_PEN_REVERSE ("rv"), TICKIT_PEN_STRIKE ("strike"),
TICKIT_PEN_BLINK ("blink")
boolean rendering attributes. These are of type TICKIT_PENTYPE_BOOL. 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.
TICKIT_PEN_UNDER ("u")
underline. This is of type TICKIT_PENTYPE_INT. Its value is one of the values from the
TickitPenUnderline enumeration. Most terminals should support the single underline value, however
other values are less commonly supported, and may be drawn instead as a single underline.
Applications are advised not to make use of underline style alone to distinguish significant parts
of the user interface.
Valid values are:
TICKIT_PEN_UNDER_NONE
No underline.
TICKIT_PEN_UNDER_SINGLE
Single underline.
TICKIT_PEN_UNDER_DOUBLE
Double underline.
TICKIT_PEN_UNDER_WAVY
Single wavy underline, sometimes called "undercurl".
For backward-compatibility this attribute will also behave like a boolean-typed attribute. When
set to any value other than none, it appears true as a boolean. Setting it to true as a booelan
will set its value to single.
TICKIT_PEN_ALTFONT ("af")
alternate font index. This is of type TICKIT_PENTYPE_INT. It is a value 0 to 9, which selects from
the terminal's available fonts. Few terminals actually support this in practice.
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 tickit_pen_set_bool_attr(3) and tickit_pen_get_bool_attr(3).
Integer attributes use tickit_pen_set_int_attr(3) and tickit_pen_get_int_attr(3). Colour attributes use
tickit_pen_set_colour_attr(3), tickit_pen_set_colour_attr_desc(3) and tickit_pen_get_colour_attr(3). The
RGB8 secondary field for colours can be set with tickit_pen_set_colour_attr_rgb8(3), and queried with
tickit_pen_has_colour_attr_rgb8(3) and tickit_pen_get_colour_attr_rgb8(3).
To test if an attribute has a value set, use tickit_pen_has_attr(3), and to remove the attribute entirely
use tickit_pen_clear_attr(3). To test if a pen has any attributes set at all, use
tickit_pen_is_nonempty(3), and to test if it has any attributes set to a non-default value use
tickit_pen_is_nondefault(3). To remove all the attributes use tickit_pen_clear(3). To copy the value of
one attribute from a pen into another pen use tickit_pen_copy_attr(3), to copy the entire pen use
tickit_pen_copy(3), and to compare two pens for equallity use tickit_pen_equiv_attr(3).
EVENTS
A pen instance stores a list of event handlers. Each event handler is associated with one event type and
stores a function pointer, and an arbitrary pointer containing user data. Event handlers may be installed
using tickit_pen_bind_event(3) and removed using tickit_pen_unbind_event_id(3).
The event types recognised are:
TICKIT_PEN_ON_DESTROY
The pen instance is being destroyed.
TICKIT_PEN_ON_CHANGE
The stored attributes on the pen have changed. The info pointer will be NULL.
TICKIT_PEN(7)