Screen Module
-------------

The `tacotui.screen` module contains functions and attributes for manipulating
the terminal screen and setting the cursor position.
The functions set control the screen directly, where the `screen.pos` object
has string attributes containing `ANSI Codes <https://en.wikipedia.org/wiki/ANSI_escape_code escape codes>`_
that, when printed to the terminal, control the display.


Basic screen functions
**********************

.. autofunction:: tacotui.screen.clear

.. autofunction:: tacotui.screen.clearline

.. autofunction:: tacotui.screen.hide_cursor

Attributes `screen.scrwidth` and `screen.scrheight` provide the character
width and height of the screen. These are set on startup, so manually resizing the
terminal while the program is running may give weird results.


Printing
********

A few functions are included that wrap the builtin print method,
allowing for printing in a specific color or centering text, without printing a newline.

.. autofunction:: tacotui.screen.sprint

.. autofunction:: tacotui.screen.write

.. autofunction:: tacotui.screen.centertext


Curosr Positioning
******************

There are two ways to set cursor position. First is the `setxy` function.

.. autofunction:: tacotui.screen.setxy

The second method uses the `screen.pos` object which has attributes
that can be directly printed to the terminal. Attribues `screen.pos.x*`,
`screen.pos.y*` and `screen.pos.xy*_*` are available, where the asterisk
is replaced with an integer indicating screen position. The attribute
value is a string ANSI escape code that will set the terminal position.
Note that 

Typical usage in an f-string:

.. code-block:: python

    screen.sprint(f'{screen.pos.xy5_3}This text starts at x=5, y=3.')


The `screen.pos` object also has attributes `push` and `pop` that push the
current screen position onto a stack.

.. code-block:: python

    screen.sprint(f'{screen.pos.x4}{screen.push}{screen.pos.x15}x=15')
    screen.sprint(f'{screen.pos.pop}x=4 again')


Coloring functions
******************

The color functions set or reset the color applied to all subsequent prints.
See :ref:`coloring` for how to specify the colors.

.. autofunction:: tacotui.screen.setcolor

.. autofunction:: tacotui.screen.resetcolor