Package: nwid
nwid####A terminal widgets framework for humans.===========================================================.. image:: https://www.quantifiedcode.com/api/v1/project/d817599b176740e49b42d1f8402d4d3e/badge.svg:target: https://www.quantifiedcode.com/app/project/d817599b176740e49b42d1f8402d4d3e:alt: Code issues----Please note that this is a work in progress. The API will likely change manytimes before it becomes stable. Use at your own risk.Nwid is a terminal widgets framework for humans.It is designed to be an easy-to-use, light-weight (no dependencies), terminalwidget library and application framework for building terminal GUIs. It hasintuitive widgets, a simple and recognizable event loop, and a container``App`` that can be extended or used as-is. Its design and components take someinspiration from the well-known web browser DOM as well as the python packages`urwid <http://urwid.org/>`_ and`npyscreen <http://npyscreen.readthedocs.org/index.html>`_.Although there already are a handful of terminal user-interface libraries inpython, I have found them to be either cumbersome to use or difficult to extendbecause of their design. The python curses module is itself unweildly anddesperately needs a layer of abstraction to hide its unique details and oddlynamed functions. Nwid aims to be this intuitive, easy to extend abstractionlayer. The nwid philosophy is to let you create and describe the widgets withintuitive attributes and methods, and the framework will take care of thecumbersome terminal details. The code is pythonic and easy to read, which makesit easy to extend.A low-level knowledge of terminals and tty is not necessary to using thisframework. To get started, check out the examples in the examples directory.Nwid is designed to be conceptually easy to understand, and the examples areintended to exhibit the basic concepts in order to give a helpful overview ofthe capabilities and structure of the framework. After looking at the examples,you can read `Modules and Components`_ for more specific details about theframework.If you have any questions, comments, or suggestions I'd love to hear them:harold (a) bradleystudio.netInstalling and including in projects====================================Installing nwid---------------.. code:: bash$ git clone git@github.com:hbradleyiii/nwid.git$ cd <project directory>$ pip install -e .Running Tests-------------.. code:: bash$ cd <project directory>$ py.testImporting and Basic Usage-------------------------.. code:: python>>> import nwid>>> app = nwid.App()>>> app.window.add( {nwid.Title : { 'text' : 'An nwid App!' },nwid.LabeledTextBox : {'text' : 'Your input:','validator' : App.validate_function,'name' :}nwid.Button : {'text' : 'Click me!','click' : App.callback_function,}})>>> app.run()Modules and Components======================Overview--------The nwid framework is made of three major components, the ``App`` class formanaging windows and running the event loop, the ``Window`` class forcontaining and managing widgets, and the widget module for creating the userinteractive widgets (such as, textfields, labels, and dropdown boxes).The ``App`` is the base controller for the application. Besides controling theevent loop, it is responsible for initializing the curses environment andhandling the screen object. This class can be used as-is or may be extended bya custom class with application-specific controller methods. The ``App`` classhas a special property, the ``App.window_stack``, that keeps track of thecurrent window and any open window that has not yet been closed but is coveredup (partly or completely) by the current window.For instance, the first window may be a form that has a button that opens asecond window with a select box containing a list of options to choose from.The first window hasn't yet closed but is waiting for the second window toprovide the user selected choice. At this point, the second window is thesecond and top-most window on the stack. Any events that are triggered are nowgiven to this window. It may completely cover the first window or might onlycover a portion of it being centered on the screen with the edges revealing thefirst window behind it. This second window may contain a select box with a listof several objects or strings to pass back to the first window. One of theseoptions might be 'new', indicating that the user wishes to create a new stringor object. Selecting this item, might open a third window for this task,putting this third window on top of the stack. This stacking could go onindefinitely with each window appending to the ``App.window_stack``. When thetopmost window is closed, this window is 'popped' from the stack and the nextwindow down in the stack is given back the focus. When an ``App`` no longer hasany windows, the application is closed.The ``Window`` class is the container class for the widgets. It sets the boundsfor where a widget can be drawn. It may have a border and title set. Note thatthis is not the same thing as the curses window object. Although it should havea reference to this object in ``Window.screen``.A widget is a user interface object that can be displayed in a window. It isdefined by its height and width, its location on the window, and its foregroundand background colors. It has contents such as a string of text or a morecomplicated widget may contain other widgets. In fact, a ``Window`` class isactually a special kind of top-level widget. You can create your own customwidgets by extending ``widget.Base``, although nwid comes with a number ofuseful generic widgets such as ``TextBox``, ``LabledTextBox``, ``CheckBox``,``String``, ``Button``, ``Label``, and ``SelectBox``. Widgets can registerevents to callback functions in order to handle keyboard or mouse events.The App Module--------------The ``nwid.app`` module comprisesThe ``App`` controller is also responsible for the event loop that catcheskeyboard and mouse events. It passes these events to the window in focus(``App.window``) for the window to handle.Lastly, the ``App`` is responsible for setting up and tearing down the cursesenvironment. It initializes the curses screen and binds this object to anywindow that is put in the window stack. This is done using a ``CursesManager``object, which is both a context manager and a wrapper for the curses library.This object is part of the nwid internals and generally doesn't need to beaccessed directly. It takes care of the nitty-gritty details.The App Class~~~~~~~~~~~~~The ``nwid.App`` class is the primaryYou can either use it as is or you can inherit from ``App``... code:: python>>>The current window or top-most window is always the window with the focus,meaning that any events that are triggered are given only to that window. The``App.window`` attribute always points to this window. Setting this attributeto a new window will automatically make this new window the window with thefocus and put it on top of the 'window stack'.Attributes``````````Methods```````The CursesManager Context Manager~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~TODOThe Event Loop~~~~~~~~~~~~~~The event loop is inspired by the design of an Internet browser's event loop.Registering Events``````````````````A widget can register an event with a callback function byExample:.. code:: python>>> def widget.callback_function(self):>>>     print 'Event triggered!'>>> widget.register_event('x', widget.callback_function)Event Propagation`````````````````When an event is fired, the main window's trigger function is called with theevent name. It then calls the trigger function of its child that has focus. Ifthis child has a child widget, the process continues down until it gets to thelowest widget in focus that has no children. This widget attempts to run anyregistered callback functions. The function may return as normal and the parentregains control and attempts to run any registered callback function that itmay have. This process continues until the main window regains control or ifthe exception ``PreventDefault`` is raised. A callback function may choose toraise ``PreventDefault`` in order to prevent other callback functions frominterferring. This is very similar to JavaScript's ``Event.preventDefault()``method.Widget Module-------------A Widget is a reusable modular component that is displayed on the screen as abutton, a text field, or other graphical interface. It can be combined to makea more complex widget component. The widgets that make up this more comlpexcomponent are the ``children`` widgets to the ``parent`` widget.The ``parent`` widget is responsible for the layout of its ``children``. The``parent`` controls the vertical and horizontal alignment as well as whether ornot it has the ability to scroll.Base Widget~~~~~~~~~~~The ``nwid.widget.Base`` class is the foundation for all other widgets. If youwish to create your own widget, you should inherit from ``Base``.For example:.. code:: python>>>String Widget~~~~~~~~~~~The ``nwid.widget.String`` class is a basic string widget. This widget is usedfor displaying strings.TextBox Widget~~~~~~~~~~~~~~The ``nwid.widget.TextBox`` class is a textbox widget for accepting user input.ComboBox Widget~~~~~~~~~~~~~~~The ``nwid.widget.ComboBox`` class is a textbox widget for accepting user input.----Soli Deo gloria.