Navigation

phoenix_title wx.lib.agw.hypertreelist

The hypertreelist module contains the HyperTreeList class that combines the multicolumn features of a wx.ListCtrl in report mode with the hierarchical features of a wx.TreeCtrl. Although it looks more like a wx.ListCtrl, the API tends to follow the API of wx.TreeCtrl.

The HyperTreeList class actually consists of two sub-windows:

These widgets can be obtained by the GetHeaderWindow and GetMainWindow methods respectively although this shouldn’t be needed in normal usage because most of the methods of the sub-windows are monkey-patched and can be called directly from the HyperTreeList itself.

Description

HyperTreeList was originally inspired from the wx.gizmos.TreeListCtrl class from Classic wxPython. Now in Phoenix the old wrapped C++ wxTreeListCtrl class is gone and this class can be used in its place. In addition to the features of the old wx.gizmos.TreeListCtrl this class supports:

  • CheckBox-type items: checkboxes are easy to handle, just selected or unselected state with no particular issues in handling the item’s children;

  • Added support for 3-state value checkbox items;

  • RadioButton-type items: since I elected to put radiobuttons in CustomTreeCtrl, I needed some way to handle them that made sense. So, I used the following approach:

    • All peer-nodes that are radiobuttons will be mutually exclusive. In other words, only one of a set of radiobuttons that share a common parent can be checked at once. If a radiobutton node becomes checked, then all of its peer radiobuttons must be unchecked.

    • If a radiobutton node becomes unchecked, then all of its child nodes will become inactive.

  • Hyperlink-type items: they look like an hyperlink, with the proper mouse cursor on hovering;

  • Multiline text items;

  • Enabling/disabling items (together with their plain or grayed out icons);

  • Whatever non-toplevel widget can be attached next to a tree item;

  • Whatever non-toplevel widget can be attached next to a list item;

  • Column headers are fully customizable in terms of icons, colour, font, alignment etc…;

  • Default selection style, gradient (horizontal/vertical) selection style and Windows Vista selection style;

  • Customized drag and drop images built on the fly (see customtreectrl for more info);

  • Setting the HyperTreeList item buttons to a personalized imagelist;

  • Setting the HyperTreeList check/radio item icons to a personalized imagelist;

  • Changing the style of the lines that connect the items (in terms of wx.Pen styles);

  • Using an image as a HyperTreeList background (currently only in “tile” mode);

  • Ellipsization of long items when the horizontal space is low, via the TR_ELLIPSIZE_LONG_ITEMS style (New in version 0.9.3).

  • Hiding items

  • Change background colours for each column individually.

And a lot more. Check the demo for an almost complete review of the functionalities.

Base Functionalities

HyperTreeList supports all the customtreectrl styles, except:

  • TR_EXTENDED: supports for this style is on the todo list (Am I sure of this?).

Plus it has 3 more styles to handle checkbox-type items:

  • TR_AUTO_CHECK_CHILD: automatically checks/unchecks the item children;

  • TR_AUTO_CHECK_PARENT: automatically checks/unchecks the item parent;

  • TR_AUTO_TOGGLE_CHILD: automatically toggles the item children.

And a style useful to hide the TreeListCtrl header:

And a style related to long items (with a lot of text in them), which can be ellipsized:

  • TR_ELLIPSIZE_LONG_ITEMS: ellipsizes long items when the horizontal space for HyperTreeList is low (New in version 0.9.3).

  • TR_VIRTUAL: support is mostly experimental. A TreeCtrl cannot be made virtual as easily as a ListCtrl. In a ListCtrl the visible items can be determined directly from the scrollbars because all rows are the same height and are always visible. In a TreeCtrl the topology of the tree can be very complex. Each item can be expanded, collapsed, hidden, and even different heights if the wx.TR_HAS_VARIABLE_ROW_HEIGHT style is used.

Please note that most TreeCtrl-like APIs are available in this class, although they may not be visible to IDEs or other tools as they are automatically delegated to the CustomTreeCtrl or other helper classes.

Usage

Usage example:

import wx
import wx.lib.agw.hypertreelist as HTL

class MyFrame(wx.Frame):

    def __init__(self):
        wx.Frame.__init__(self, None, title="HyperTreeList Demo")

        tree = HTL.HyperTreeList(self, agwStyle=wx.TR_DEFAULT_STYLE |
                                 HTL.TR_ELLIPSIZE_LONG_ITEMS)
        tree.AddColumn("Tree Column", width=200)
        tree.AddColumn("Column 1", width=200, flag=wx.ALIGN_LEFT)
        root = tree.AddRoot("Root")

        parent = tree.AppendItem(root, "First child")
        tree.SetItemText(parent, "Child of root", column=1)

        child = tree.AppendItem(parent, "First Grandchild")
        tree.SetItemText(child, "Column1 Text", column=1)

        child2 = tree.AppendItem(root, "Second child")
        button = wx.Button(tree.GetMainWindow(), label="Button1")
        tree.SetItemWindow(child2, button, column=1)


# our normal wxApp-derived class, as usual
app = wx.App(redirect=False)
locale = wx.Locale(wx.LANGUAGE_DEFAULT)
frame = MyFrame()
app.SetTopWindow(frame)
frame.Show()
app.MainLoop()

Events

All the events supported by customtreectrl are also available in HyperTreeList, with a few exceptions:

  • EVT_TREE_GET_INFO (don’t know what this means);

  • EVT_TREE_SET_INFO (don’t know what this means);

  • EVT_TREE_ITEM_MIDDLE_CLICK (not implemented, but easy to add);

  • EVT_TREE_STATE_IMAGE_CLICK (no need for that, look at the checking events below).

Plus, HyperTreeList supports the events related to the checkbutton-type items:

  • EVT_TREE_ITEM_CHECKING: an item is being checked;

  • EVT_TREE_ITEM_CHECKED: an item has been checked.

And to hyperlink-type items:

  • EVT_TREE_ITEM_HYPERLINK: an hyperlink item has been clicked (this event is sent after the EVT_TREE_SEL_CHANGED event).

Supported Platforms

HyperTreeList has been tested on the following platforms:

  • Windows

  • Linux

  • Mac

Window Styles

The HyperTreeList class takes a regular wxPython style and an extended agwStyle. The style can be used with normal wxPython styles such as wx.WANTS_CHARS while the agwStyle specifies the behavior of the tree itself. It supports the following agwStyle flags:

See customtreectrl for more information on styles.

Events Processing

This class processes the following events, Note that these are the same events as wx.ListCtrl and wx.TreeCtrl:

Event Name

Description

EVT_LIST_COL_BEGIN_DRAG

The user started resizing a column - can be vetoed.

EVT_LIST_COL_CLICK

A column has been left-clicked.

EVT_LIST_COL_DRAGGING

The divider between columns is being dragged.

EVT_LIST_COL_END_DRAG

A column has been resized by the user.

EVT_LIST_COL_RIGHT_CLICK

A column has been right-clicked.

EVT_TREE_BEGIN_DRAG

Begin dragging with the left mouse button. See wx.lib.agw.customtreectrl Drag/Drop section for more information.

EVT_TREE_BEGIN_LABEL_EDIT

Begin editing a label. This can be prevented by calling TreeEvent.Veto().

EVT_TREE_BEGIN_RDRAG

Begin dragging with the right mouse button.

EVT_TREE_DELETE_ITEM

Delete an item.

EVT_TREE_END_DRAG

End dragging with the left or right mouse button.

EVT_TREE_END_LABEL_EDIT

End editing a label. This can be prevented by calling TreeEvent.Veto().

EVT_TREE_GET_INFO

Request information from the application (not implemented in HyperTreeList).

EVT_TREE_ITEM_ACTIVATED

The item has been activated, i.e. chosen by double clicking it with mouse or from keyboard.

EVT_TREE_ITEM_CHECKED

A checkbox or radiobox type item has been checked.

EVT_TREE_ITEM_CHECKING

A checkbox or radiobox type item is being checked.

EVT_TREE_ITEM_COLLAPSED

The item has been collapsed.

EVT_TREE_ITEM_COLLAPSING

The item is being collapsed. This can be prevented by calling TreeEvent.Veto().

EVT_TREE_ITEM_EXPANDED

The item has been expanded.s

EVT_TREE_ITEM_EXPANDING

The item is being expanded. This can be prevented by calling TreeEvent.Veto().

EVT_TREE_ITEM_GETTOOLTIP

The opportunity to set the item tooltip is being given to the application (call TreeEvent.SetToolTip()).

EVT_TREE_ITEM_HYPERLINK

An hyperlink type item has been clicked.

EVT_TREE_ITEM_MENU

The context menu for the selected item has been requested, either by a right click or by using the menu key.

EVT_TREE_ITEM_MIDDLE_CLICK

The user has clicked the item with the middle mouse button (not implemented in HyperTreeList).

EVT_TREE_ITEM_RIGHT_CLICK

The user has clicked the item with the right mouse button.

EVT_TREE_KEY_DOWN

A key has been pressed.

EVT_TREE_SEL_CHANGED

Selection has changed.

EVT_TREE_SEL_CHANGING

Selection is changing. This can be prevented by calling TreeEvent.Veto().

EVT_TREE_SET_INFO

Information is being supplied to the application (not implemented in HyperTreeList).

EVT_TREE_STATE_IMAGE_CLICK

The state image has been clicked (not implemented in HyperTreeList).

License And Version

HyperTreeList is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 30 Jul 2014, 21.00 GMT

Version 1.5

function_summary Functions Summary

create_delegator_for

Creates a method that forwards calls to self._main_win (an instance of TreeListMainWindow).

IsBufferingSupported

Utility function which checks if a platform handles correctly double

class_summary Classes Summary

EditCtrl

Base class for controls used for in-place edit.

EditTextCtrl

Text control used for in-place edit.

HyperTreeList

HyperTreeList is a generic widget that combines the multicolumn

TreeListColumnInfo

Class used to store information (width, alignment flags, colours, etc…) about a

TreeListHeaderWindow

A window which holds the header of HyperTreeList.

TreeListItem

This class holds all the information and methods for every single item in

TreeListMainWindow

This class represents the main window (and thus the main column) in HyperTreeList.

Functions

create_delegator_for(method)

Creates a method that forwards calls to self._main_win (an instance of TreeListMainWindow).

Parameters:

method – one method inside the TreeListMainWindow local scope.


IsBufferingSupported()

Utility function which checks if a platform handles correctly double buffering for the header. Currently returns False for all platforms except Windows XP.