.. _coloring:

Color Module
------------

`tacotui` contains two objects for setting the color of text on the screen.
`tacotui.color` is used for setting specific colors, such as 'red', or 'blue',
and `tacotui.theme` for setting colors based on a theme.

Preset colors
*************

The `tacotui.color` object has several predefined color
attributes for printing. Each attribute is a string ANSI escape code
that, when printed to the terminal, sets either the background or
foreground color. Python f-strings work great for changing the color
mid-line.

.. code-block:: python

    from tacotui import screen, color
    screen.sprint(f'{color.RED}This is red. {color.BLUE}This is blue.')
    screen.sprint(f'{color.RESET}This is the default terminal color.')

The colors are RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE,
BLACK, BRIGHTRED, BRIGHTGREEN, BRIGHTYELLOW, BRIGHTBLUE, BRIGHTMAGENTA,
BRIGHTCYAN, BRIGHTWHITE, BRIGHTBLACK. Note the actual color
displayed will depend on the terminal settings.

The background color is set by prepending `BG` to the color attribute:

.. code-block:: python

    screen.sprint(f'{color.BGRED}{color.YELLOW}Yellow on red{color.RESET}')

Colors can be bolded or underlined by adding `_BOLD` and `_UNDERLINE`
to the attribute name:

.. code-block:: python

    screen.sprint(f'{color.RED_UNDERLINE}Red and underlined.{color.RESET}')


Custom RGB colors
*****************

The ANSI code for a specific RGB color can be accessed using
the `color.rgb` and `color.bgrgb` functions:

.. code-block:: python

    screen.sprint(color.rgb(173, 216, 230))
    screen.sprint(color.bgrgb(69, 69, 69))
    screen.sprint('Light blue on dim gray')

.. _themes:

Theme colors
************

The `tacotui.theme` object contains colors named by function
which can be set to different themes. Theme colors are used
extensively with the :ref:`widgets`.
Theme color names are

- NORM: Normal text
- BORDER: Borders for boxes, messages, etc.
- HLIGHT: Text that is highlighted by the cursor
- SELECT: Text that is selected or enabled, but not highlighted
- HSELECT: Text that is selected or enabled AND highlighted
- NAME: Names, titles
- MSG: Message text
- BUTTON: Button text
- ERROR: Color for error messages

Three themes are included: `blue`, `sand`, and `default`.
They can be enabled using `theme.settheme(name)`.
Clear the screen immediately after setting the theme
to pick up the background color.

.. code-block:: python

    from tacotui import theme
    theme.settheme('sand')
    screen.clear()
    screen.sprint(f'{theme.MSG}Message color{theme.NORM}')