.. _sec_attributes: Attributes ========== .. c:type:: termpaint_attr The attributes object contains paint settings used when painting on a :doc:`surface`. It consists of the foreground color, the background color and the decoration color. In addition it has a set of enabled styles. .. _colors: Colors ------ Terminal colors are a bit complicated for historical reasons. Even if colors seem the same they are all distinct and terminals can (and do) act differently depending on how the color was exactly selected. .. _default-colors: Default colors .............. The most basic color is :c:macro:`TERMPAINT_DEFAULT_COLOR`. It's the terminals default color. This color acts differently when used as foreground, background or decoration color. For foreground and background it's the respective default color. For decoration color the default color means that the terminal will use the foreground color of that particular cell. .. _named-colors: Named colors ............ Next there is the set of named colors. The first 8 named colors are also often called ANSI colors. These colors are have constants like ``TERMPAINT_COLOR_RED`` and can also be referred to as :c:macro:`TERMPAINT_NAMED_COLOR` + color number. The first 8 colors are supported by almost all color terminals. The following 8 colors are still very widely supported. The named colors have names like "red", but terminal implementations often allow reconfiguring these colors from easy accessible settings dialogs. Expect named colors to have different concrete color values for many users. .. container:: hidden-references .. c:macro:: TERMPAINT_COLOR_BLACK .. c:macro:: TERMPAINT_COLOR_RED .. c:macro:: TERMPAINT_COLOR_GREEN .. c:macro:: TERMPAINT_COLOR_YELLOW .. c:macro:: TERMPAINT_COLOR_BLUE .. c:macro:: TERMPAINT_COLOR_MAGENTA .. c:macro:: TERMPAINT_COLOR_CYAN .. c:macro:: TERMPAINT_COLOR_LIGHT_GREY .. c:macro:: TERMPAINT_COLOR_DARK_GREY .. c:macro:: TERMPAINT_COLOR_BRIGHT_RED .. c:macro:: TERMPAINT_COLOR_BRIGHT_GREEN .. c:macro:: TERMPAINT_COLOR_BRIGHT_YELLOW .. c:macro:: TERMPAINT_COLOR_BRIGHT_BLUE .. c:macro:: TERMPAINT_COLOR_BRIGHT_MAGENTA .. c:macro:: TERMPAINT_COLOR_BRIGHT_CYAN .. c:macro:: TERMPAINT_COLOR_WHITE .. table:: Named Colors :align: left ====== ============================== ==== Number Constant Name ====== ============================== ==== 0 TERMPAINT_COLOR_BLACK black 1 TERMPAINT_COLOR_RED red 2 TERMPAINT_COLOR_GREEN green 3 TERMPAINT_COLOR_YELLOW yellow 4 TERMPAINT_COLOR_BLUE blue 5 TERMPAINT_COLOR_MAGENTA magenta 6 TERMPAINT_COLOR_CYAN cyan 7 TERMPAINT_COLOR_LIGHT_GREY "white" (on terminals supporting 16 colors this is light gray) 8 TERMPAINT_COLOR_DARK_GREY dark gray 9 TERMPAINT_COLOR_BRIGHT_RED bright red 10 TERMPAINT_COLOR_BRIGHT_GREEN bright green 11 TERMPAINT_COLOR_BRIGHT_YELLOW bright yellow 12 TERMPAINT_COLOR_BRIGHT_BLUE bright blue 13 TERMPAINT_COLOR_BRIGHT_MAGENTA bright magenta 14 TERMPAINT_COLOR_BRIGHT_CYAN bright cyan 15 TERMPAINT_COLOR_WHITE bright white ====== ============================== ==== .. _indexed-colors: Indexed colors .............. The next color space is :c:macro:`TERMPAINT_INDEXED_COLOR`. This is a indexed color space. For most terminals it has 256 colors. Some terminals only implement 88 colors though. Per convention the first 16 colors (0-15) are the same as the named colors. Some terminals handle these differently in combination with the :c:macro:`TERMPAINT_STYLE_BOLD` style. For terminals supporting 256 colors in the default palette the rest of the indices are divided in a 6x6x6 color cube and a 23 step gray ramp (indices 232-255). The defaults are the color cube uses intensity levels of [0, 95, 135, 175, 215, 255] and calculates the components as red is (index-16) / 36, green is (index-16) / 6) % 6 and blue (index-16) % 6. The gray ramp uses the intensity levels of [8, 18, 28, 38, 48, 58, 68, 78, 88, 98, 108, 118, 128, 138, 148, 158, 168, 178, 188, 198, 208, 218, 228, 238]. Of course the index colors are redefinable so users might have a changed palette active. For some terminal implementations using index colors leads to garbled display because not all terminals support parsing the needed control sequences. .. image:: color256.png .. _rgb-colors: RGB colors .......... The last color space is :c:macro:`TERMPAINT_RGB_COLOR`. This is a direct color space which does not allow redefining colors. A color is specified by red, green and blue intensities in the range 0 to 255. For example ``TERMPAINT_RGB_COLOR(255, 128, 64)`` For some terminal implementations using direct rgb colors leads to garbled display because not all terminals support parsing the needed control sequences. Termpaint automatically translates RGB colors to indexed colors using the default palette when terminal capability detection yields that the terminal can not handle them. This detection is not always exact and can be switched to a more conservative mode by disabling the capability ``TERMPAINT_CAPABILITY_TRUECOLOR_MAYBE_SUPPORTED``. In the opposite direction promising the capability ``TERMPAINT_CAPABILITY_TRUECOLOR_SUPPORTED`` disables translation to index colors. .. c:macro:: TERMPAINT_RGB_COLOR_OFFSET(red, green, blue) A macro that returns a rgb color composed of the given values for red, green and blue. The value range is 0 to 255 for each color component Styles ------ Clusters may have one or more styles. The style changes how characters are displayed. The :c:macro:`TERMPAINT_STYLE_INVERSE` style also applies to blank cells. Styles can be enabled and disabled by using the :c:func:`termpaint_attr_set_style()` and :c:func:`termpaint_attr_unset_style()` functions. These functions take one or more of the style macros combined with bitwise or (``|``). Attribute support varies with terminal implementation. .. table:: Available styles :align: left =================== ========= Style Macro =================== ========= bold :c:macro:`TERMPAINT_STYLE_BOLD` inverse :c:macro:`TERMPAINT_STYLE_INVERSE` italic :c:macro:`TERMPAINT_STYLE_ITALIC` blink :c:macro:`TERMPAINT_STYLE_BLINK` underline :c:macro:`TERMPAINT_STYLE_UNDERLINE` double underline :c:macro:`TERMPAINT_STYLE_UNDERLINE_DBL` curly underline :c:macro:`TERMPAINT_STYLE_UNDERLINE_CURLY` strikethrough :c:macro:`TERMPAINT_STYLE_STRIKE` overline :c:macro:`TERMPAINT_STYLE_OVERLINE` =================== ========= Functions --------- See :ref:`safety` for general rules for calling functions in termpaint. .. c:macro:: TERMPAINT_DEFAULT_COLOR A Macro used to denote the terminals default color .. c:macro:: TERMPAINT_NAMED_COLOR A Macro used to denote the first of the named colors. For example use ``TERMPAINT_NAMED_COLOR + 1`` to denote red. .. c:macro:: TERMPAINT_INDEXED_COLOR A Macro used to denote the first indexed color. For example use ``TERMPAINT_NAMED_COLOR + 243`` to denote a mid gray. .. c:macro:: TERMPAINT_RGB_COLOR(r, g, b) A Macro used to denote the rgb direct colors. Parameters are in the range 0 to 255. .. c:function:: termpaint_attr* termpaint_attr_new(unsigned fg, unsigned bg) Creates a new attributes object with the foreground color ``fg`` and background color ``bg``. No styles will be selected. The application has to free this with :c:func:`termpaint_attr_free`. .. c:function:: termpaint_attr* termpaint_attr_clone(termpaint_attr* attr) Creates a new attributes object with the same settings as the attributes object passed in ``attr``. The application has to free this with :c:func:`termpaint_attr_free`. .. c:function:: void termpaint_attr_free(termpaint_attr* attr) Frees a attributes object allocated with :c:func:`termpaint_attr_new()` or :c:func:`termpaint_attr_clone()`. .. c:function:: void termpaint_attr_set_fg(termpaint_attr* attr, unsigned fg) Set the foreground to be used when painting to ``fg``. .. c:function:: void termpaint_attr_set_bg(termpaint_attr* attr, unsigned bg) Set the background to be used when painting to ``bg``. .. c:function:: void termpaint_attr_set_deco(termpaint_attr* attr, unsigned deco_color) Set the decoration color to be used when painting to ``deco_color``. .. c:macro:: TERMPAINT_STYLE_BOLD Style the text in bold. `(widely supported) `__ Some terminal implementations change named colors in the range 0-7 to their bright variants when rendering bold text. .. c:macro:: TERMPAINT_STYLE_ITALIC Style the text in italic. `(widely supported) `__ .. c:macro:: TERMPAINT_STYLE_BLINK Text should blink. `(support varies by terminal implementation) `__ .. c:macro:: TERMPAINT_STYLE_OVERLINE Style the text with a overline. `(limited support in terminal implementations) `__ .. c:macro:: TERMPAINT_STYLE_INVERSE Display the text with inverted foreground and background color. `(widely supported) `__ .. c:macro:: TERMPAINT_STYLE_STRIKE Style the text in strikethrough. `(support varies by terminal implementation) `__ .. c:macro:: TERMPAINT_STYLE_UNDERLINE Style the text with a single underline. `(widely supported) `__ If supported by the terminal emulator the underline uses the decoration color. .. c:macro:: TERMPAINT_STYLE_UNDERLINE_DBL Style the text with a double underline. `(limited support in terminal implementations) `__ If supported by the terminal emulator the underline uses the decoration color. .. c:macro:: TERMPAINT_STYLE_UNDERLINE_CURLY Style the text with a curly underline. `(limited support in terminal implementations) `__ If supported by the terminal emulator the underline uses the decoration color. .. c:function:: void termpaint_attr_set_style(termpaint_attr* attr, int bits) Adds the styles given in ``bits`` to the attributes. .. c:function:: void termpaint_attr_unset_style(termpaint_attr* attr, int bits) Removes the styles given in ``bits`` to the attributes. .. c:function:: void termpaint_attr_reset_style(termpaint_attr* attr) Removes all previously set styles. .. c:function:: void termpaint_attr_set_patch(termpaint_attr* attr, _Bool optimize, const char *setup, const char * cleanup) This function allows to use additional attributes for rendering that are not otherwise explicitly supported. .. warning:: This is a low level feature with potential to garble the whole terminal rendering. Use with care. Allows setting escape sequences to be output before (``setup``) and after (``cleanup``) rendering each cluster with this style. If ``optimize`` is set, do not use ``setup`` and ``cleanup`` between clusters that have the exact same patch. The caller is responsible to ensure that the patches don't break rendering. Setup is output after the "select graphics rendition" escape sequence right before the text of the cluster is output. If ``optimize`` is not set cleanup is output directly following the text of the cluster. If ``optimize`` is true, the setup sequence must not contain "select graphics rendition" sequences because the rendering resets SGR state between clusters if styles change in a display run.