Development

This page discusses features to be implemented. Take with a grain of salt.

Information Hiding Policy

  • are there thing we want to hide/remove from the public interface?
  • Candidates:
    • callbacks
    • child widgets
  • use Properties
    • needs Python >= 2.2 (trunk already requires this)
    • allow better access control without changing current interfaces that expose imple attributes

Cleanup class hierarchy

  • MOSTLY DONE
  • make every widget fit in the inheritance graph
  • WidgetWrap and AttrWrap don't fit
  • use new style classes and multiple inheritance
  • Patch: attachment:urwid-class_hierarchy.patch
    • Adds .__super via meta class
    • sample callback handling interface (unused)
    • still some old style superclass calls left

Cleanup API

  • get_focus(), set_focus()
    • .set_focus() does accept either a widget or a number for some classes (GridFlow, Pile, Columns)
    • There is Column.set_focus_column(), Column.get_focus_column()
    • Frame.set_focus() accepts one of 'header', 'footer', 'body' - keep and implement new properties?
    • .get_focus is not always implemented
    • -> .focus property (GET) that is the widget that has the focus. None for leaves.
    • -> .focus_position property (GET/SET) property that is a position value that this widget understands. Undefined for leaves (need to check .focus is None because position None shouldn't have a special meaning).
    • -> .selectable_iter(reverse=False) iterator over selectable values for tuples (widget, position), starting from the current focus. (a regular list won't work for a ListBox? that doesn't have access to all its content)
    • -> .focus_path property (GET/SET) list of focus settings down to the leaf widget (dynamically calculated and set)
  • Pile and Columns should be more similar
    • .focus_item (widget) <-> .focus_col (int)
    • .item_types <-> .column_types
    • .get_item_rows() <-> .column_widths()

List Walker Interface

Dropping Python 2.1 support now allows use of iterators. Possible change to list walker interface http://excess.org/urwid/reference.html#List_Walker_interface_definition

This interface is intended to be used only by ListBox and this suggested interface covers exactly what ListBox requires. Think of it as a view on some data that might not actually be a flat list. Someone that creates a custom list walker class will already have a better way to access their particular data structure with the knowledge they have about it.

  • get_focus(self) -> (widget, position, prev_iter, next_iter)

prev_iter is an iterator that will return (widget, position) tuples starting from the widget above the focus and moving up.

next_iter is an iterator that will return (widget, position) tuples starting from the widget below the focus and moving down.

  • set_focus(self, position) - unchanged
  • get_next and get_prev - removed

Alternative implementation:

  • get_focus(self) -> position_object

  • pos.widget() -> widget
  • pos.iter() -> self
  • pos.next() -> widget # start with focus widget or with the adjacent?
  • pos.reversed() -> pos_obj / pos.reverse()

Alternative with properties:

  • for widget in listwalker.focus.reversed():
  • listwalker.focus = f

Current Plan for Development:

  • defer. there is no need for a change at this time

Parent attribute

Currently a widget may have 0..many parents, so a .parent attribute won't work. For example, it is valid to use the same Divider widget in many places.

A .parent attribute is possible for rendered widgets, which will be represented as CompositeCanvas objects with pointers to the widget object and a copy of the parameters used for rendering.

What is the use case for the parent attribute of widgets? Is it needed simply because users of other popular GUI toolkits will expect it? Is it worth breaking backwards compatibility?

  • Ehm, .... true.
  • I still have some feature in mind where I guess something treelike would be useful, but I need to elaborate that further. So we forget about this for now.
    • There's nothing wrong with using this type of doubly-linked tree structure if it is something like a node in a tree view. In fact, it is likely that the widgets displayed in a tree view would all be rendered at the same level (not nested), so the tree structure would be disconnected from the widget nesting.
  • ehmm, mompl... see below

Current Plan for Development: NewBaseClasses

Short cut handling

For menus (and perhaps for other widgets too) it is very handy to have short cuts (like alt F for the File menu entry). For the API it would be nice if the widget itself could decide which short cuts it wants to register for. We could even use something like Menu(['_File', '_View', 'F_orget'], underscore_shortcuts=True) and make the widget do the work.

Problems:

  • The widgets that should recieve the short cut are not in the focus and don't get a keypress call.
  • The right place to handle these keys may vary (top level, dialog, menu (not menu item)).
  • We don't know where the widget is and how to switch the focus in all the surrounding widgets

Current plan for Development:

  • Include shortcut keys in the Canvas objects rendered by widgets.
  • Include position information and shortcut information in the CompositeCanvas object's "child" list.
  • Overlays would drop shortcuts from their background widget (since they can't focus background)
  • Implement container interface for all composite widgets.
  • All shortcuts and a way to set focus is now available from the topmost composite widget.
  • Would not allow shortcuts from widgets that are not visible (IMHO a good thing)

Attachments