2012-03-07 21:51:52 GMT
I'm happy to announce the containers changes I've been working on for a few months have now landed in the default/master branch. This is a long post but there's lots of good stuff here. If you see a problem with the API or its implementation now's the time to let me know!
1. NEW CONTAINER API
Urwid's container widgets:
All now have a common container API you can use, regardless of the container type. Backwards compatibility is still maintained for the old container-specific ways of accessing and modifying contents, but the new API is now the preferred way of modifying and traversing containers.
is a read-only property that returns the widget in focus for this container. Empty containers and non-container widgets (that inherit from Widget) will return None.
is a read/write property that provides access to the position of the container's widget in focus. This will often be a integer value but may be any object*. Reading this value on an empty container or on any non-container widgets (that inherit from Widget) raises an IndexError. Writing to this property with an invalid position will also raise an IndexError. Writing a new value automatically marks this widget to be redrawn and will be reflected in cont.focus.
* Columns, Pile, GridFlow, Overlay and ListBox with a SimpleListWalker or SimpleFocusListWalker as its body use integer positions; Frame uses 'body', 'header' and 'footer'; ListBox with a custom list walker will use the positions the list walker returns
is a read-only property** that provides access to an mapping- or list-like object that contains the child widgets and the options used for displaying those widgets in this container. The mapping- or list-like object always allows reading from positions with the usual __getitem__ method and may support assignment and deletion*** with __setitem__ and __delitem__ methods. The values are (child widget, option) tuples. When this object or its contents are modified the widget is automatically flagged to be redrawn.
** Columns, Pile and GridFlow also allow assigning an iterable to this property and overwrite the values in their contents list with the ones provided.
*** Columns, Pile, GridFlow, Overlay and Frame support item assignment and deletion
is a method that returns options objects for use in items added to cont.contents. The arguments are specific to the container type, and generally match the __init__ arguments for the container. The objects returned are currently tuples of strings and integers or None for containers without child widget options. This method exists to allow future versions of Urwid to add new options to existing containers. Code that expects the option tuples to remain the same size will fail when new options are added, so defensive programming with options tuples is strongly encouraged.
cont.__getitem__(x) # <=> cont[x]
is a short-cut method behaving identically to: cont.contents[x].base_widget. Which means roughly "give me the child widget at position x and skip all the Decoration widgets wrapping it". Decoration widgets include Padding, Filler, AttrMap etc.
is a method that returns the focus position for this container *and* all child containers along the path defined by their focus settings. This list of positions is the closest thing we have to the singular widget-in-focus in other UI frameworks, because the ultimate widget in focus in Urwid depends on the focus setting of all its parent container widgets.
is a method that assigns to the focus_position property of each container along the path given by the list of positions p. It may be used to restore focus to a widget as returned by a previous call to cont.get_focus_path().
cont.__iter__() and cont.__reversed__()
are methods that allow iteration over the *positions* of this container. Normally the order of the positions generated by __reversed__() will be the opposite of __iter__(). The exception is the case of ListBox with certain custom list walkers, and the reason goes back to the original way list walker interface was defined. Note that a custom list walker might also generate an unbounded number of positions, so care should be used with this interface and ListBoxes.
2. CONTAINER AND DECORATION WIDGET IMPROVEMENTS
I made a number of other improvements to the container and decoration widgets:
* GridFlow child widgets may now be given different widths, and more types of widths will likely be added in the future to make it a much more flexible container
* Overlay now has min_height, min_width, left, right, top and bottom parameters which behave like the same options on Padding and Filler
* Frame now has some better docstrings and a comparison to a similar use of Pile
* Updated tour.py example to use new container/decoration parameters
3. LIST WALKER API V2
The current list walker API ("V1") will remain available and is still the least restrictive option for the programmer. The list walker API V2 is an attempt to remove some of the duplicate code that V1 requires for many users. List walker API V1 will be implemented automatically by subclassing ListWalker and implementing the V2 methods:
_______________________________________________ Urwid mailing list Urwid <at> lists.excess.org http://lists.excess.org/mailman/listinfo/urwid