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_penattr_type(3) function
       gives the type of a given attribute. The tickit_penattr_name(3) function gives the name of
       a  given attribute, which is also given below in parentheses. The tickit_penattr_lookup(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 equality 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)