########
thurible
########

Tools for creating fullscreen terminal UIs on top of blessed.


What does it do?
================
It provides some tools for creating and managing interactive user
interfaces in the terminal.


Why Did I Make This?
====================
I have a couple of programs that have interactive UIs in a terminal,
and I wanted to consolidate that code. There are probably other packages
that do this better, but I prefer to keep my dependencies to a minimum.
Plus, I like playing with terminal user interfaces. They're neat.


Will It Work with My Terminal?
==============================
It's intended to work with anything that `blessed` works with. Is
that everything? Probably not. Certainly some features, like color,
will only work if your terminal supports it. Some things, like the
frames that can go around the panels rely on Unicode characters that
may not exist in all fonts. If you're using a variable width font in
your terminal… I don't know. Things are probably going to be messed up.

If you run into something should work but isn't, open an issue. I'm
just doing this on my own in my spare time, but I'll try to look at it.


Using `thurible`
================
`Panels` format and display data in a terminal. If you are used
to working with graphical user interfaces, you can think of them like
windows. They are how the application puts data on the screen.

While `thurible` has tools for handling displaying panels for you,
you can display a panel yourself just by using `print`. Let's
say you just want to put the word "SPAM" in the middle of the terminal::

    from thurible import Splash
    
    splash = Splash('spam')
    print(splash, end='', flush=True)

Do you have to add the `end` and `flush` attributes to the
`print`? Yes. Or, at least, it works better if you do. Without
`end`, `print` will add a new line after it prints the panel,
which will cause the top of the panel to scroll up off the top of the
terminal window. Without `flush`, `print` may delay printing
the panel until there is more text to display in the terminal, causing
your panel to be displayed after it is relevant to the user.

Using `print` to display the panel only shows the panel in the
terminal. It won't all users to interact with the panel by, for example
scrolling through its text or selecting a menu option. While it's
possible to create your own code for handling that, the easiest way to
do it is to use a manager.


Managers and Messages
=====================
`Managers` manage displaying panels and retrieving user input, so
you don't have to worry about it. Your code just needs to tell the
manager what you want to display and watch for messages back from the
manager containing input from the user.

`Messages` are the objects you use to send instructions to the
manager, and they are the objects the manager uses to send data back
to you.

Let's expand on the previous example. You still want to put the word
"SPAM" in the middle of the screen. But, now, you want to end the
program after the user presses any key on their keyboard::

    from threading import Thread
    from thurible import get_queues, queued_manager, Splash
    import thurible.messages as tm

    # Set up and run the thread for the manager.
    q_to, q_from = get_queues()
    T = Thread(target=queued_manager, args=(q_to, q_from))
    T.start()

    # Create the panel.
    footer = 'Press any key to continue.'
    splash = Splash('spam', frame_type='heavy', footer=footer)

    # Tell the manager to display the panel.
    store = tm.Store('splash', splash)
    show = tm.Show('splash')
    q_to.put(store)
    q_to.put(show)

    # Watch for input indicating the user has pressed a key or if the
    # manager is ending for some other reason, meaning you'll never get
    # the key pressed by the user.
    data = None
    while not isinstance(data, [tm.Data, tm.Ending]):
        if not q_from.empty():
            data = q_from.get()
    
    # Once the user pressed a key, tell the manager to end gracefully.
    # If the manager sent an Ending message, then you don't need to
    # tell it to end. It's crashed on its own.
    if isinstance(data, tm.Data):
        end = tm.End('Goodbye!')
        q_to.put(end)


Usage Example
=============
Usage examples are found in the `examples/` directory.

examples/eventsplash.py
    A terminal application that uses a `thurible.event_manager`
    to display a simple splash screen.
examples/favword.py
    A terminal application that uses `thurible` to ask the user for
    their favorite word.
examples/filereader.py
    A terminal application that uses `thurible` to navigate the
    filesystem and read files.
examples/tensecs.py
    A terminal application that uses `thurible` to track a ten
    second wait using a progress bar.
examples/showsplash.py
    A terminal application that uses a `thurible.queued_manager`
    to display a simple splash screen.

If you want to run them to see what they do, you need to run them like
modules. For example, to run filereader from the root of the repository,
run the following::

    python3 -m examples.filereader


To-Do List
==========
The following items are likely in future releases:

*   Manager updates:

    *   Add coroutine manager.
    
*   Panel updates:

    *   Fall back frames that only use ASCII characters.
    *   Fall back overflow indicators that only use ASCII characters.
    *   Simplify sizing.
    *   Add a simple table for sequences.
    *   Add a simple table for mappings.
    *   Add a textfield panel.
    *   Add a textform panel.
    *   Add a tableform panel.
    *   Figure out what to do if dialog message overflows.
