Add widget and listbox reference doc

--HG--
branch : feature-sphinx

4 files changed, 486 insertions, 17 deletions

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index bc129e9..b284119 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -7,3 +7,5 @@ Under costructions
 .. toctree::
 
    main_loop
+   listbox
+   widget
diff --git a/docs/reference/listbox.rst b/docs/reference/listbox.rst
new file mode 100644
index 0000000..90d5ba9
--- /dev/null
+++ b/docs/reference/listbox.rst
@@ -0,0 +1,169 @@
+:mod:`urwid.listbox` --- Listbox
+================================
+
+.. module:: urwid.listbox
+   :synopsis: Listbox
+
+.. exception:: ListWalkerError
+
+   todo
+
+.. class:: ListWalker
+
+   todo
+
+.. class:: SimpleListWalker(contents)
+
+   *contents* -- list to copy into this object
+   
+   Changes made to this object (when it is treated as a list) are detected
+   automatically and will cause ListBox objects using this list walker to be
+   updated.
+
+   .. method:: set_modified_callback(callback)
+
+      This function inherited from MonitoredList is not implemented in
+      SimleListWalker.
+      
+      Use connect_signal(list_walker, "modified", ...) instead.
+
+   .. method:: get_focus()
+
+      Return (focus widget, focus position).
+
+   .. method:: set_focus(position)
+
+      Set focus position.
+
+   .. method:: get_next(start_from)
+
+      Return (widget after start_from, position after start_from).
+
+   .. method:: get_prev(start_from)
+
+      Return (widget before start_from, position before start_from).
+
+
+.. exception:: ListBoxError
+
+   todo
+
+.. class:: ListBox(body)
+
+   *body* is a :class:`ListWalker`-like object that contains widgets to be
+   displayed inside the list box
+
+
+   .. method:: calculate_visible(size[, focus=False])
+
+      Return ``(middle, top, bottom)`` or ``None, None, None``.
+
+      *middle* -- (row offset (when +ve) or inset (when -ve), focus widget,
+      focus position, focus rows, cursor coords or None )
+
+      *top* -- ( # lines to trim off top, list of (widget, position, rows)
+      tuples above focus in order from bottom to top )
+
+      *bottom* -- ( # lines to trim off bottom, list of (widget, position,
+      rows) tuples below focus in order from top to bottom )
+
+   .. method:: render(size[, focus=False])
+
+      Render listbox and return canvas.
+
+   .. method:: get_cursor_coords(size)
+
+      todo
+
+   .. method:: set_focus_valign(valign)
+
+      Set the focus widget's display offset and inset.
+
+      *valign* -- one of:
+          'top', 'middle', 'bottom'
+          ('fixed top', rows)
+          ('fixed bottom', rows)
+          ('relative', percentage 0=top 100=bottom)
+
+   .. method:: set_focus(position[, coming_from=None])
+
+      Set the focus position and try to keep the old focus in view.
+
+      *position* -- a position compatible with ``self.body.set_focus``
+
+      *coming_from* -- set to 'above' or 'below' if you know that old position
+      is above or below the new position.
+
+   .. method:: get_focus()
+
+      Return a ``(focus widget, focus position)`` tuple.
+
+   .. method:: shift_focus(size, offset_inset)
+
+      Move the location of the current focus relative to the top.
+
+      *offset_inset* -- either the number of rows between the top of the
+      listbox and the start of the focus widget (+ve value) or the number of
+      lines of the focus widget hidden off the top edge of the listbox (-ve
+      value) or 0 if the top edge of the focus widget is aligned with the top
+      edge of the listbox
+
+   .. method:: update_pref_col_from_focus(size)
+
+      Update ``self.pref_col`` from the focus widget.
+
+   .. method:: change_focus(size, position[, offset_inset=0, \
+                            coming_from=None, cursor_coords=None, \
+                            snap_rows=None])
+
+      Change the current focus widget.
+      
+      *position* -- a position compatible with ``self.body.set_focus``.
+
+      *offset_inset* -- either the number of rows between the top of the
+      listbox and the start of the focus widget (+ve value) or the number of
+      lines of the focus widget hidden off the top edge of the listbox (-ve
+      value) or 0 if the top edge of the focus widget is aligned with the top
+      edge of the listbox (default if unspecified)
+
+      *coming_from* -- eiter 'above', 'below' or unspecified (``None``).
+
+      *cursor_coords* -- ``(x, y)`` tuple indicating the desired column and row
+      for the cursor, a ``(x,)`` tuple indicating only the column for the cursor,
+      or unspecified (``None``).
+
+      *snap_rows* -- the maximum number of extra rows to scroll when trying to
+      "snap" a selectable focus into the view.
+
+   .. method:: get_focus_offset_inset(size)
+
+      Return ``(offset rows, inset rows)`` for focus widget.
+
+   .. method:: make_cursor_visible(size)
+
+      Shift the focus widget so that its cursor is visible.
+
+   .. method:: keypress(size, key)
+
+      Move selection through the list elements scrolling when necessary. 'up'
+      and 'down' are first passed to widget in focus in case that widget can
+      handle them. 'page up' and 'page down' are always handled by the ListBox.
+      
+      Keystrokes handled by this widget are:
+      'up'        up one line (or widget)
+      'down'      down one line (or widget)
+      'page up'   move cursor up one listbox length
+      'page down' move cursor down one listbox length
+
+
+   .. method:: mouse_event(size, event, button, col, row, focus)
+
+      Pass the event to the contained widgets. May change focus on button 1
+      press.
+
+   .. method:: ends_visible(size[, focus=False])
+
+      Return a list that may contain 'top' and/or 'bottom'.
+ 
+      Convenience function for checking whether the top and bottom of the
+      list are visible
diff --git a/docs/reference/main_loop.rst b/docs/reference/main_loop.rst
index b66d401..889e4f7 100755
--- a/docs/reference/main_loop.rst
+++ b/docs/reference/main_loop.rst
@@ -8,26 +8,36 @@
 
    When this exception is not handled, the main loop exits.
 
-.. class:: MainLoop(widget, palette=[], screen=None, handle_mouse=True, input_filter=None, unhandled_input=None, event_loop=None, pop_ups=False)
+.. class:: MainLoop(widget[, palette=[], screen=None, handle_mouse=True, \
+                    input_filter=None, unhandled_input=None, event_loop=None, \
+                    pop_ups=False])
 
    This is the standard main loop implementation with a single screen.
 
    *widget* is the topmost widget used for painting the screen, stored as
    self.widget and may be modified. Must be a box widget.
+
    *palette* -- initial palette for screen.
+
    *screen* -- screen object or None to use raw_display.Screen, stored as
    self.screen
-   *handle_mouse* -- True to process mouse events, passed to self.screen
-   *input_filter* -- a function to filter input before sending
-   it to self.widget, called from self.input_filter
-   unhandled_input -- a function called when input is not
-   handled by self.widget, called from self.unhandled_input
-   *event_loop* -- if screen supports external an event loop it
-   may be given here, or leave as None to use
-   *SelectEventLoop*, stored as self.event_loop
-   *pop_ups* -- True to wrap self.widget with a PopUpTarget
-   instance to allow any widget to open a pop-up anywhere on
-   the screen
+
+   *handle_mouse* -- ``True`` to process mouse events, passed to
+   ``self.screen``
+
+   *input_filter* -- a function to filter input before sending it to
+   ``self.widget``, called from ``self.input_filter``
+
+   *unhandled_input* -- a function called when input is not handled by
+   ``self.widget``, called from ``self.unhandled_input``
+
+   *event_loop* -- if screen supports external an event loop it may be given
+   here, or leave as None to use
+
+   *SelectEventLoop*, stored as ``self.event_loop``
+
+   *pop_ups* -- ``True`` to wrap ``self.widget`` with a ``PopUpTarget``
+   instance to allow any widget to open a pop-up anywhere on the screen
 
    .. attribute:: widget
 
@@ -64,7 +74,7 @@
         Create a pipe for use by a subprocess or thread to trigger a callback
         in the process/thread running the *MainLoop*.
 
-        *callback* -- function to call MainLoop.run thread/process
+        *callback* -- function to call :meth:`MainLoop.run` thread/process
 
         This function returns a file descriptor attached to the write end of a
         pipe. The read end of the pipe is added to the list of files the event
@@ -79,7 +89,7 @@
         that the callback will be triggered just once with the complete value
         of data passed in.
 
-        If the callback returns False then the watch will be removed and the
+        If the callback returns ``False`` then the watch will be removed and the
         read end of the pipe will be closed. You are responsible for closing
         the write end of the pipe.
 
@@ -174,7 +184,6 @@
 
    Event loop based on :func:`select.select`
 
-
 .. class:: GLibEventLoop()
 
       Event loop based on :class:`gobject.MainLoop`
@@ -212,8 +221,9 @@
       so the best we can do for now is to set a timer event in a very
       short time to approximate an enter-idle callback.
 
-      XXX: This will perform worse than the other event loops until we
-      can find a fix or workaround
+      .. WARNING::
+         This will perform worse than the other event loops until we can find a
+         fix or workaround
 
    .. method:: handle_exit(f, enable_idle=True)
 
diff --git a/docs/reference/widget.rst b/docs/reference/widget.rst
new file mode 100644
index 0000000..e9ceb27
--- /dev/null
+++ b/docs/reference/widget.rst
@@ -0,0 +1,288 @@
+:mod:`urwid.widget` --- Widgets
+===============================
+
+.. module:: urwid.widget
+   :synopsis: Widgets
+
+..
+   # Widget sizing methods
+   # (use the same string objects to make some comparisons faster)
+   FLOW = 'flow'
+   BOX = 'box'
+   FIXED = 'fixed'
+   
+   # Text alignment modes 
+   LEFT = 'left'
+   RIGHT = 'right'
+   CENTER = 'center'
+   
+   # Filler alignment modes 
+   TOP = 'top'
+   MIDDLE = 'middle'
+   BOTTOM = 'bottom'
+   
+   # Text wrapping modes
+   SPACE = 'space'
+   ANY = 'any'
+   CLIP = 'clip'
+   
+   # Extras for Padding
+   PACK = 'pack'
+   GIVEN = 'given'
+   RELATIVE = 'relative'
+   RELATIVE_100 = (RELATIVE, 100)
+
+
+.. class:: WidgetMeta
+
+    Automatic caching of render and rows methods.
+
+    Class variable ``no_cache`` is a list of names of methods to not cache.
+    Class variable ``ignore_focus`` if defined and ``True`` indicates that this
+    widget is not affected by the focus parameter, so it may be ignored when
+    caching.
+
+.. exception:: WidgetError
+
+   todo
+
+.. function:: validate_size(widget, size, canv)
+
+   Raise a WidgetError if a canv does not match size size.
+
+.. function:: update_wrapper(new_fn, fn)
+
+   Copy as much of the function detail from fn to new_fn as we can.
+
+.. function:: cache_widget_render(cls)
+
+   Return a function that wraps the cls.render() method and fetches and stores
+   canvases with CanvasCache.
+
+.. function:: nocache_widget_render(cls)
+
+   Return a function that wraps the cls.render() method and finalizes the
+   canvas that it returns.
+
+.. function:: nocache_widget_render_instance(self)
+
+   Return a function that wraps the cls.render() method and finalizes the
+   canvas that it returns, but does not cache the canvas.
+
+.. function:: cache_widget_rows(cls)
+
+   Return a function that wraps the cls.rows() method and returns rows from the
+   CanvasCache if available.
+
+
+.. class:: Widget
+    
+   base class of widgets
+
+   .. attribute:: _sizing
+    
+      Default to ``set([])``.
+
+   .. attribute:: _command_map
+    
+      Default to the single shared :class:`~urwid.command_map.CommandMap`.
+
+   .. method:: _emit(name, *args)
+
+      Convenience function to emit signals with self as first argument.
+    
+   .. method:: selectable()
+
+      Return ``True`` if this widget should take focus. Default implementation
+      returns the value of ``self._selectable``.
+    
+   .. method:: sizing()
+
+      Return a set including one or more of ``box``, ``flow`` and ``fixed``.
+      Default implementation returns the value of ``self._sizing``.
+
+   .. method:: pack(size[, focus=False])
+
+      Return a "packed" ``(maxcol, maxrow)`` for this widget. Default
+      implementation (no packing defined) returns size, and calculates maxrow
+      if not given.
+
+   .. attribute:: base_widget
+
+      This property returns the widget without any decorations, default
+      implementation returns self.
+
+
+.. class:: FlowWidget
+
+   Base class of widgets that determine their rows from the number of columns
+   available.
+    
+   .. method:: rows(size[, focus=False])
+
+      All flow widgets must implement this function.
+
+   .. method:: render(size[, focus=False])
+
+      All widgets must implement this function.
+
+
+.. class:: BoxWidget
+
+   Base class of width and height constrained widgets such as the top level
+   widget attached to the display object.
+
+.. function:: fixed_size(size)
+
+   raise ValueError if size != ().
+    
+   Used by FixedWidgets to test size parameter.
+
+
+.. class:: FixedWidget
+
+   Base class of widgets that know their width and height and cannot be resized
+
+    
+   .. method:: pack([size=None, focus=False])
+
+      All fixed widgets must implement this function.
+
+.. class:: Divider([div_char=u" ", top=0, bottom=0])
+
+   Horizontal divider widget
+
+   Create a horizontal divider widget.
+
+   *div_char* -- character to repeat across line
+
+   *top* -- number of blank lines above
+
+   *bottom* -- number of blank lines below
+
+   ignore_focus = True
+
+
+.. class:: SolidFill([fill_char=" "])
+
+   Create a box widget that will fill an area with a single character.
+
+   *fill_char* -- character to fill area with
+
+
+.. exception:: TextError
+
+   todo
+
+
+.. class:: Text(self, markup[, align=LEFT, wrap=SPACE, layout=None])
+
+   A horizontally resizeable text widget.
+
+   *markup* -- content of text widget, one of:
+
+       * plain string -- string is displayed
+
+       * ``(attr, markup2)`` -- markup2 is given attribute attr
+
+       * ``[markupA, markupB, ...]`` -- list items joined together
+
+   *align* -- align mode for text layout
+
+   *wrap* -- wrap mode for text layout
+
+   *layout* -- layout object to use, defaults to StandardTextLayout
+
+   .. method:: def set_text(markup)
+
+      Set content of text widget.
+
+   .. method:: get_text()
+
+      Returns ``(text, attributes)``.
+
+      *text* -- complete string content (unicode) of text widget
+
+      *attributes* -- run length encoded attributes for text
+
+   .. attribute:: text
+
+   .. attribute:: attrib
+
+   .. method:: set_align_mode(mode)
+
+      Set text alignment/justification. Valid modes for StandardTextLayout are:
+      ``'left'``, ``'center'`` and ``'right'``.
+
+   .. method:: set_wrap_mode(mode)
+      
+      Set wrap mode.
+
+   .. method:: set_layout(align, wrap[, layout=None])
+
+      Set layout object, align and wrap modes:
+
+      *align* -- align mode for text layout
+
+      *wrap* -- wrap mode for text layout
+
+      *layout* -- layout object to use, defaults to StandardTextLayout
+
+   .. attribute:: align
+
+   .. attribute:: wrap
+
+   .. attribute:: layout
+
+   .. method:: get_line_translation(maxcol[, ta=None])
+
+      Return layout structure used to map self.text to a canvas. This method
+      is used internally, but may be useful for debugging custom layout
+      classes.
+
+
+.. exception:: EditError
+
+   todo
+
+
+.. class:: Edit([caption=u"", edit_text=u"", multiline=False, align=LEFT, \
+                wrap=SPACE, allow_tab=False, edit_pos=None, layout=None, \
+                mask=None])
+
+   Text editing widget implements cursor movement, text insertion and deletion.
+   A caption may prefix the editing area. Uses text class for text layout.
+
+   *caption* -- markup for caption preceeding edit_text
+
+   *edit_text* -- text string for editing
+
+   *multiline* -- True: 'enter' inserts newline False: return it
+
+   *align* -- align mode
+
+   *wrap* -- wrap mode
+
+   *allow_tab* -- True: 'tab' inserts 1-8 spaces False: return it
+
+   *edit_pos* -- initial position for cursor, None:at end
+
+   *layout* -- layout object
+
+   *mask* -- character to mask away text with, None means no masking
+
+   signals = ["change"]
+
+   .. method:: valid_char(ch)
+
+      Return true for printable characters.
+    
+   .. method:: update_text()
+
+      No longer supported.
+
+   .. method:: set_caption(caption)
+
+      Set the caption markup for this widget.
+
+      *caption* -- see ``Text.__init__()`` for description of markup