diff options
| author | marco giusti <marco.giusti@gmail.com> | 2011-12-02 16:47:29 +0100 |
|---|---|---|
| committer | marco giusti <marco.giusti@gmail.com> | 2011-12-02 16:47:29 +0100 |
| commit | b15d011c7a13c5abaa8dc056c94184d1e72af43e (patch) | |
| tree | 50ec182aa502c0bd4b4376a1693f768174d64742 /docs | |
| parent | 8c13485187ca3db1ebfe7949da5c0eb536f15e4f (diff) | |
| download | urwid-b15d011c7a13c5abaa8dc056c94184d1e72af43e.tar.gz | |
Add widget layout chapter
--HG--
branch : feature-sphinx
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/widgetlayout.txt | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/docs/widgetlayout.txt b/docs/widgetlayout.txt new file mode 100644 index 0000000..b2768c2 --- /dev/null +++ b/docs/widgetlayout.txt @@ -0,0 +1,72 @@ +.. _widget-layout:
+
+Widget Layout
+=============
+
+Urwid uses widgets to divide up the available screen space. This makes it easy
+to create a fluid interface that moves and changes with the user's terminal and
+font size.
+
+.. image:: images/widget_layout.png
+
+The result of rendering a widget is a canvas suitable for displaying on the
+screen. When we render the topmost widget:
+
+1. The topmost widget *(a)* is rendered the full size of the screen
+2. *(a)* renders *(b)* any size up to the full size of the screen
+3. *(b)* renders *(c)*, *(d)* and *(e)* dividing its available screen columns
+ between them
+4. *(e)* renders *(f)* and *(g)* dividing its available screen rows between
+ them
+5. *(e)* combines the canvases from *(f)* and *(g)* and returns them
+6. *(b)* combines the canvases from *(c)*, *(d)* and *(e)* and returns them
+7. *(a)* possibly modifies the canvas from *(b)* and returns it
+
+Widgets *(a)*, *(b)* and *(e)* are called container widgets because they
+contain other widgets. Container widgets choose the size and position their
+contained widgets.
+
+Container widgets must also keep track of which one of their contained widgets
+is in focus. The focus is used when handling keyboard input. If in the above
+example *(b)* 's focus widget is *(e)* and *(e)* 's focus widget is
+*(f)* then keyboard input will be handled this way:
+
+1. The keypress is passed to the topmost widget *(a)*
+2. *(a)* passes the keypress to *(b)*
+3. *(b)* passes the keypress to *(e)*, its focus widget
+4. *(e)* passes the keypress to *(f)*, its focus widget
+5. *(f)* either handles the keypress or returns it
+6. *(e)* has an opportunity to handle the keypress if it was returned from
+ *(f)*
+7. *(b)* has an opportunity to handle the keypress if it was returned from
+ *(e)*
+8. *(a)* has an opportunity to handle the keypress if it was returned from
+ *(b)*
+
+Box, Flow and Fixed Widgets
+---------------------------
+
+The size of a widget is measured in screen columns and rows. Widgets that are
+given an exact number of screen columns and rows are called box widgets. The
+topmost widget is always a box widget.
+
+Much of the information displayed in a console user interface is text and the
+best way to display text is to have it flow from one screen row to the next.
+Widgets like this that require a variable number of screen rows are called flow
+widgets. Flow widgets are given a number of screen columns and can calculate
+how many screen rows they need.
+
+Occasionally it is also useful to have a widget that knows how many screen
+columns and rows it requires, regardless of the space available. This is
+called a fixed widget.
+
+It is an Urwid convention to use the variables `maxcol` and `maxrow` to store a
+widget's size. Box widgets require both of `(maxcol, maxrow)` to be specified.
+
+Flow widgets expect a single-element tuple `(maxcol,)` instead because they
+calculate their `maxrow` based on the `maxcol` value.
+
+Fixed widgets expect the value `None` to be passed in to functions that take a
+size because they know their `maxcol` and `maxrow` values.
+
+.. vim: set ft=rst:
|