tmpl_tutorial.html

Urwid is a Python library for making text console applications. It has many features including fluid

The easiest way to change the current ListBox focus is to call the
<a href="reference.html#ListBox-set_focus">set_focus</a> method.
This method doesn't require that you know the ListBox's
current dimensions (maxcol, maxrow).  It will wait until the next call to
either keypress or render to complete setting the offset and inset values 
using the dimensions passed to that method.
<br><br>
The position object passed to set_focus must be compatible with the List
Walker object that the ListBox is using. For SimpleListWalker the position
is the integer index of the widget within the list.
<br><br>
The coming_from parameter should be set if you know that the old position
is "above" or "below" the previous position.  When the ListBox completes
setting the offset and inset values it tries to find the old widget among
the visible widgets. If the old widget is still visible, if will try to
avoid causing the ListBox contents to scroll up or down from its previous
position. If the widget is not visible, then the ListBox will:
<ul>
<li>Display the new focus at the bottom of the ListBox if coming_from is
"above".
<li>Display the new focus at the top of the ListBox if coming_from is "below".
<li>Display the new focus in the middle of the ListBox if coming_from is None.
</ul>
If you know exactly where you want to display the new focus widget within
the ListBox you may call 
<a href="reference.html#ListBox-set_focus_valign">set_focus_valign</a>. 
This method lets you specify the
"top", "bottom", "middle", a relative position or the exact number of rows
from the top or bottom of the ListBox.
{/body[lbfocus]}

<br clear="left"><hr>

{body[pile]}
<a href="reference.html#Pile">Pile</a>
 widgets are used to combine multiple widgets by stacking them
vertically. A Pile can manage selectable widgets by keeping track of which
widget is in focus and it can handle moving the focus between widgets when
the user presses the UP and DOWN keys. A Pile will also work well when used 
within a ListBox.
<br><br>
A Pile is selectable only if its focus widget is selectable. If you create
a Pile containing one Text widget and one Edit widget the Pile will
choose the Edit widget as its default focus widget.
To change the pile's focus widget you can call
<a href="reference.html#Pile-set_focus">set_focus</a>.
{/body[pile]}

<br clear="left"><hr>

{body[cols]}
<a href="reference.html#Columns">Columns</a>
widgets may be used to arrange either flow widgets or box widgets
horizontally into columns. Columns widgets will manage selectable widgets
by keeping track of which column is in focus and it can handle moving the
focus between columns when the user presses the LEFT and RIGHT keys.
Columns widgets also work well when used within a ListBox.
<br><br>
Columns widgets are selectable only if the column in focus is selectable.
If a focus column is not specified the first selectable widget will be
chosen as the focus column. The 
<a href="reference.html#Columns-set_focus">set_focus</a>
method may be used to select the focus column.
{/body[cols]}

<br clear="left"><hr>

{body[grid]}
The 
<a href="reference.html#GridFlow">GridFlow</a>
widget is a flow widget designed for use with
<a href="reference.html#Button">Button</a>,
<a href="reference.html#CheckBox">CheckBox</a> and
<a href="reference.html#RadioButton">RadioButton</a> widgets.
It renders all the widgets it contains the same width and it arranges them
from left to right and top to bottom.
<br><br>
The GridFlow widget uses Pile, Columns, Padding and Divider widgets to build
a display widget that will handle the keyboard input and rendering. When the
GridFlow widget is resized it regenerates the display widget to accommodate
the new space.
{/body[grid]}

<br clear="left"><hr>

{body[overlay]}
The <a href="reference.html#Overlay">Overlay</a> widget is a box widget that
contains two other box widgets.  The bottom widget is rendered the full size
of the Overlay widget and the top widget is placed on top, obscuring an area
of the bottom widget. This widget can be used to create effects such as
overlapping "windows" or pop-up menus.
<br><br>
The Overlay widget always treats the top widget as the one in focus. All
keyboard input will be passed to the top widget. 
<br><br>
If you want to use a flow
flow widget for the top widget, first wrap the flow widget with a
<a href="reference.html#Filler">Filler</a> widget.
{/body[overlay]}

<br clear="left"><hr>

{body[wmod]}
The easiest way to create a custom widget is to modify an existing widget.
This can be done by either subclassing the original widget or by wrapping it.
Subclassing is appropriate when you need to interact at a very low level
with the original widget, such as if you are creating a custom edit widget
with different behavior than the usual Edit widgets.  If you are creating
a custom widget that doesn't need tight coupling with the original widget,
such as a widget that displays customer address information, then wrapping
is more appropriate.
<br><br>
The <a href="reference.html#WidgetWrap">WidgetWrap</a> class simplifies
wrapping existing widgets.  You can create a custom widget simply by 
creating a subclass of WidgetWrap and passing a widget into WidgetWrap's 
constructor. 
<br><br>
This is an example of a custom widget that uses WidgetWrap:

<pre class="code">%example[0]%</pre>

The above code creates a group of RadioButtons and provides a method to
query the state of the buttons.
<br><br>
Wrapped widgets may also override the standard widget methods. These methods
are described in following sections.
{/body[wmod]}

<br clear="left"><hr>

{body[wanat]}
Any object that follows the 
<a href="reference.html#Widget_interface_definition">Widget interface definition</a>
may be used as a widget.  Box widgets must implement 
<a href="reference.html#Widget_interface_definition-selectable">selectable</a>
and 
<a href="reference.html#Widget_interface_definition-render">render</a>
methods, and flow widgets must implement selectable, render and 
<a href="reference.html#Widget_interface_definition-rows">rows</a>
methods.

<pre class="code">%example[0]%</pre>

The above code implements two widget classes. Pudding is a flow widget and 
BoxPudding is a box widget. Pudding will render as much "Pudding" as will
fit in a single row, and BoxPudding will render as much "Pudding" as will
fit into the entire area given.
<br><br>
It is not strictly necessary to inherit from
<a href="reference.html#FlowWidget">BoxWidget</a> or 
<a href="reference.html#FlowWidget">FlowWidget</a>, but doing so does add
some documentation to your code.  
<br><br>
Note that the rows and render methods' focus parameter must have a default
value of False.  Also note that for flow widgets the number of rows returned 
by the rows method must match the number of rows rendered by the render
method.
<br><br>
In most cases it is easier to let other widgets handle the rendering and 
row calculations for you:

<pre class="code">%example[1]%</pre>

The NewPudding class behaves the same way as the Pudding class above, but in
NewPudding you can change the way the widget appears by modifying only the
display_widget method, whereas in the Pudding class you may have to modify both
the render and rows methods.
<br><br>
To improve the efficiency of your Urwid application you should be careful
of how long your rows methods take to execute.  The rows methods may be called
many times as part of input handling and rendering operations.  If you are
using a display widget that is time consuming to create you should consider
caching it to reduce its impact on performance.
<br><br>
It is possible to create a widget that will behave as either a flow widget
or box widget depending on what is required:

<pre class="code">%example[2]%</pre>

MultiPudding will work in place of either Pudding or BoxPudding above. The
number of elements in the size tuple determines whether the containing widget
is expecting a flow widget or a box widget.
{/body[wanat]}

<br clear="left"><hr>

{body[wsel]}
Selectable widgets such as Edit and Button widgets allow the user to
interact with the application.  A widget is selectable if its selectable
method returns True.  Selectable widgets must implement the
<a href="reference.html#Widget_interface_definition-keypress">keypress</a>
method to handle keyboard input.

<pre class="code">%example[0]%</pre>

The SelectablePudding widget will display its contents in uppercase when it
is in focus, and it allows the user to "eat" the pudding by pressing each of
the letters P, U, D, D, I, N and G on the keyboard.  When the user has "eaten"
all the pudding the widget will reset to its initial state.
<br><br>
Note that keys that are unhandled in the keypress method are returned so that
another widget may be able to handle them.  This is a good convention to follow
unless you have a very good reason not to.  In this case the UP and DOWN keys
are returned so that if this widget is in a ListBox the ListBox will behave as
the user expects and change the focus or scroll the ListBox.
{/body[wsel]}

<br clear="left"><hr>

{body[wcur]}
Widgets that display the cursor must implement the
<a href="reference.html#Widget_interface_definition-get_cursor_coords">get_cursor_coords</a> 
method. Similar to the rows method for flow widgets, this method lets other
widgets make layout decisions without rendering the entire widget.  The
ListBox widget in particular uses get_cursor_coords to make sure that the
cursor is visible within its focus widget.

<pre class="code">%example[0]%</pre>

CursorPudding will let the user move the cursor through the widget by 
pressing LEFT and RIGHT. The cursor must only be added to the canvas when
the widget is in focus. The get_cursor_coords method must always return
the same cursor coordinates that render does.

<br><br>A widget displaying a cursor may choose to implement
<a href="reference.html#Widget_interface_definition-get_pref_col">get_pref_col</a>.
This method returns the preferred column for the cursor, and is called when
the focus is moving up or down off this widget.
<br><br>
Another optional method is 
<a href="reference.html#Widget_interface_definition-move_cursor_to_coords">move_cursor_to_coords</a>.
This method allows other widgets to try to position the cursor within this
widget. The ListBox widget uses move_cursor_to_coords when changing focus and
when the user pressed PAGE UP or PAGE DOWN. This method must return True on
success and False on failure. If the cursor may be placed at any position
within the row specified (not only at the exact column specified) then this
method must move the cursor to that position and return True.


<pre class="code">%example[1]%</pre>
{/body[wcur]}

<br clear="left"><hr>

{/contents}

</body>
</html>