==============
ui.termcontrol
==============

.. toctree::
   :hidden:



.. index:: ui.termcontrol
.. module:: ui.termcontrol
   :noindex:

Terminal control support.

This module provides mechanisms for prettied up output to a terminal. It uses
curses to to the heavy lifting.


Module Members
==============

| :class:`~CursesBase`
| :class:`~Options`
| :class:`~PTYRedirector`
| :class:`~TermOutput`


Classes
-------


.. class:: Options()

   This is a temporary hack.


.. property:: colours
   :noindex:

   This is a temporary hack.


.. property:: darkbg
   :noindex:

   This is a temporary hack.


.. class:: CursesBase(themeName="default")

   Base class for UI classes that make some use of curses.

   Subclasses need not necessarily provide a typicla curses UI. For example
   the `TermOutput` class only uses this to get colour and highlighting
   sequences.

   .. graphviz::

         digraph foo {
         rankdir=BT;
         ranksep=0.3;
         node[fontsize=10 margin=0.01 height=0.2 width=0.4];
         edge[arrowsize=0.6 arrowhead=onormal];
         "cstest.ui.termcontrol.CursesBase" [color=blue height=0.4 width=0.6];
             "cstest.ui.termcontrol.CursesBase" -> "cstest.ui.colours.ThemedUI";
             "cstest.ui.termcontrol.TermOutput" -> "cstest.ui.termcontrol.CursesBase";
         }

   Base class: cstest.ui.colours.ThemedUI

   Subclass: :class:`~cstest.ui.termcontrol.TermOutput`


.. class:: PTYRedirector()

   Context manager: Use pseudo terminal to capture terminal stdout.

   On entry this creates a master/slave pseudo terminal pair. The slave is
   used to replace the FD=1 (the process's stdout). While the context exists
   the :meth:`read` method provides all text writtent to FD=1 since the last
   call.

   The original stdout is restored when the context is exited.

   This is used by the `TermOutput` class to 'capture' colour and other
   escapes sequences using ``curses``.


   .. method:: read()
      :noindex:

      Read any buffered input from the master pseudo terminal.


.. class:: TermOutput(\*args, \*\*kwargs)

   Abstract layer around sys.stdout supporting colour, bold. *etc*.

   This provides a very small subset of a curses window's methods.

   TODO: Actually this is not emulating cursed, see comment for ``addstr``.

   .. graphviz::

         digraph foo {
         rankdir=BT;
         ranksep=0.3;
         node[fontsize=10 margin=0.01 height=0.2 width=0.4];
         edge[arrowsize=0.6 arrowhead=onormal];
         "cstest.ui.termcontrol.TermOutput" [color=blue height=0.4 width=0.6];
             "cstest.ui.termcontrol.TermOutput" -> "cstest.ui.termcontrol.CursesBase";
         }

   Base class: :class:`~cstest.ui.termcontrol.CursesBase`


   .. method:: addstr(s, style=None)
      :noindex:

      Add a string using a particular named style.


   .. method:: flush(\*\*kwargs)
      :noindex:

      Flush the underlying standard out file.


   .. method:: setupColours(stdscr, redirector)
      :noindex:

      Collect escape sequences.

      Uses curses to write text in the various styles and extract the escape
      sequences from captured output.


   .. method:: write(text)
      :noindex:

      Write a plain string.

      This is provided to support the standard file API.


   .. method:: writeLines(lines, lmargin=0, style=None, finalEOL=True)
      :noindex:

      Write a sequence of lines, all with the same style.


      **Arguments**

        *lines*
          A sequenceof the lines to write.

        *lmargin*
          A number os spaces to add as the left marging for each line.

        *style*
          The name of the style to apply.

        *finalEOL*
          Whether to add a newline o the final line. By defalt this is
          ``True``.