Decoration — urwidtrees 1.0.4 documentation

# Decoration

Is done by using (subclasses of) `DecoratedTree`. Objects of this type wrap around a given Tree and themselves behave like a (possibly altered) tree. Per default, DecoratedTree just passes every method on to its underlying tree. Decoration is done not by overwriting __getitem__, but by offering two additional methods

> - `DecoratedTree.get_decorated()`

> - `DecoratedTree.decorate()`.

get_decorated(pos) returns the (decorated) content of the original tree at the given position. decorate(pos, widget,..) decorates the given widget assuming its placed at a given position. The former is trivially based on the latter, Containers that display Tree's use get_decorated instead of `__getitem__()` when working on DecoratedTree's.

The reason for this slightly odd design choice is that first it makes it easy to read the original content of a decorated tree: You simply use dtree[pos]. Secondly, this makes it possible to recursively add line decoration when nesting (decorated) Trees.

The module decoration offers a few readily usable `DecoratedTree` subclasses that implement decoration by indentation, arrow shapes and subtree collapsing: `CollapsibleTree`, `IndentedTree`, `CollapsibleIndentedTree`, `ArrowTree` and `CollapsibleArrowTree`. Each can be further customized by constructor parameters.

## API

class urwidtrees.decoration.ArrowTree(walker, indent=3, childbar_offset=0, arrow_hbar_char='─', arrow_hbar_att=None, arrow_vbar_char='│', arrow_vbar_att=None, arrow_tip_char='➤', arrow_tip_att=None, arrow_att=None, arrow_connector_tchar='├', arrow_connector_lchar='└', arrow_connector_att=None, **kwargs)

  Decorates the tree by indenting nodes according to their depth and using the gaps to draw arrows indicate the tree structure.

  decorate(pos, widget, is_first=True)

    builds a list element for given position in the tree. It consists of the original widget taken from the Tree and some decoration columns depending on the existence of parent and sibling positions. The result is a urwid.Columns widget.

class urwidtrees.decoration.CollapseIconMixin(is_collapsed=<function CollapseIconMixin.<lambda>>, icon_collapsed_char='+', icon_expanded_char='-', icon_collapsed_att=None, icon_expanded_att=None, icon_frame_left_char='[', icon_frame_right_char=']', icon_frame_att=None, icon_focussed_att=None, **kwargs)

  Mixin for `Tree` that allows to collapse subtrees and use an indicator icon in line decorations. This Mixin adds the ability to construct collapse-icon for a position, indicating its collapse status to `CollapseMixin`.

class urwidtrees.decoration.CollapseMixin(is_collapsed=<function CollapseMixin.<lambda>>, **kwargs)

  Mixin for `Tree` that allows to collapse subtrees.

  This works by overwriting `[first|last]_child_position`, forcing them to return None if the given position is considered collapsed. We use a (given) callable is_collapsed that accepts positions and returns a boolean to determine which node is considered collapsed.

  is_collapsed(pos)

    checks if given position is currently collapsed

class urwidtrees.decoration.CollapsibleArrowTree(treelistwalker, icon_offset=0, indent=5, **kwargs)

  Arrow-decoration that allows collapsing subtrees

class urwidtrees.decoration.CollapsibleIndentedTree(walker, icon_offset=1, indent=4, **kwargs)

  Indent collapsible tree nodes according to their depth in the tree and display icons indicating collapse-status in the gaps.

  decorate(pos, widget, is_first=True)

    builds a list element for given position in the tree. It consists of the original widget taken from the Tree and some decoration columns depending on the existence of parent and sibling positions. The result is a urwid.Columns widget.

class urwidtrees.decoration.CollapsibleTree(tree, **kwargs)

  Undecorated Tree that allows to collapse subtrees

class urwidtrees.decoration.DecoratedTree(content)

  `Tree` that wraps around another `Tree` and allows to read original content as well as decorated versions thereof.

  decorate(pos, widget, is_first=True)

    decorate widget according to a position pos in the original tree. setting is_first to False indicates that we are decorating a line that is part of the (multi-line) content at this position, but not the first part. This allows to omit incoming arrow heads for example.

  first_child_position(pos)

    returns the position of the first child of the node at pos, or None if none exists.

  get_decorated(pos)

    return widget that consists of the content of original tree at given position plus its decoration.

  last_child_position(pos)

    returns the position of the last child of the node at pos, or None if none exists.

  next_sibling_position(pos)

    returns the position of the next sibling of the node at pos, or None if none exists.

  parent_position(pos)

    returns the position of the parent node of the node at pos or None if none exists.

  prev_sibling_position(pos)

    returns the position of the previous sibling of the node at pos, or None if none exists.

class urwidtrees.decoration.IndentedTree(tree, indent=2)

  Indent tree nodes according to their depth in the tree

  decorate(pos, widget, is_first=True)

    decorate widget according to a position pos in the original tree. setting is_first to False indicates that we are decorating a line that is part of the (multi-line) content at this position, but not the first part. This allows to omit incoming arrow heads for example.

exception urwidtrees.decoration.NoSpaceError

  too little space for requested decoration