.. wxPython Phoenix documentation This file was generated by Phoenix's sphinx generator and associated tools, do not edit by hand. Copyright: (c) 2011-2020 by Total Control Software License: wxWindows License .. include:: headings.inc .. module:: wx.lib.agw.hypertreelist .. currentmodule:: wx.lib.agw.hypertreelist .. highlight:: python .. _wx.lib.agw.hypertreelist: ========================================================================================================================================== |phoenix_title| **wx.lib.agw.hypertreelist** ========================================================================================================================================== The ``hypertreelist`` module contains the :class:`~wx.lib.agw.hypertreelist.HyperTreeList` class that combines the multicolumn features of a :class:`wx.ListCtrl` in report mode with the hierarchical features of a :class:`wx.TreeCtrl`. Although it looks more like a :class:`wx.ListCtrl`, the API tends to follow the API of :class:`wx.TreeCtrl`. The :class:`~wx.lib.agw.hypertreelist.HyperTreeList` class actually consists of two sub-windows: * :class:`TreeListHeaderWindow` displays the column headers. * :class:`TreeListMainWindow` is the main tree list based off :class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl`. These widgets can be obtained by the :meth:`~HyperTreeList.GetHeaderWindow` and :meth:`~HyperTreeList.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 :class:`~wx.lib.agw.hypertreelist.HyperTreeList` itself. Description =========== :class:`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 :class:`~wx.lib.agw.customtreectrl.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 :mod:`~wx.lib.agw.customtreectrl` for more info); * Setting the :class:`HyperTreeList` item buttons to a personalized imagelist; * Setting the :class:`HyperTreeList` check/radio item icons to a personalized imagelist; * Changing the style of the lines that connect the items (in terms of :class:`wx.Pen` styles); * Using an image as a :class:`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 And a lot more. Check the demo for an almost complete review of the functionalities. Base Functionalities ==================== :class:`HyperTreeList` supports all the :mod:`~wx.lib.agw.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: - ``TR_NO_HEADER``: hides the :class:`HyperTreeList` 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 :class:`HyperTreeList` is low (`New in version 0.9.3`). 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 :class:`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 :mod:`~wx.lib.agw.customtreectrl` are also available in :class:`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, :class:`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 =================== :class:`HyperTreeList` has been tested on the following platforms: * Windows * Linux * Mac Window Styles ============= The :class:`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: ================================= =========== ================================================== Window agwStyle Flags Hex Value Description ================================= =========== ================================================== **wx.TR_DEFAULT_STYLE** *varies* The set of flags that are closest to the defaults for the native control for a particular toolkit. Should always be used. ``wx.TR_NO_BUTTONS`` 0x0 For convenience to document that no buttons are to be drawn. ``wx.TR_SINGLE`` 0x0 For convenience to document that only one item may be selected at a time. Selecting another item causes the current selection, if any, to be deselected. This is the default. ``wx.TR_HAS_BUTTONS`` 0x1 Use this style to show + and - buttons to the left of parent items. ``wx.TR_NO_LINES`` 0x4 Use this style to hide vertical level connectors. ``wx.TR_LINES_AT_ROOT`` 0x8 Use this style to show lines between root nodes. Only applicable if ``TR_HIDE_ROOT`` is set and ``TR_NO_LINES`` is not set. ``wx.TR_TWIST_BUTTONS`` 0x10 Use old Mac-twist style buttons. ``wx.TR_MULTIPLE`` 0x20 Use this style to allow a range of items to be selected. If a second range is selected, the current range, if any, is deselected. ``wx.TR_HAS_VARIABLE_ROW_HEIGHT`` 0x80 Use this style to cause row heights to be just big enough to fit the content. If not set, all rows use the largest row height. The default is that this flag is unset. ``wx.TR_EDIT_LABELS`` 0x200 Use this style if you wish the user to be able to edit labels in the tree control. ``wx.TR_ROW_LINES`` 0x400 Use this style to draw a contrasting border between displayed rows. ``wx.TR_HIDE_ROOT`` 0x800 Use this style to suppress the display of the root node, effectively causing the first-level nodes to appear as a series of root nodes. ``wx.TR_FULL_ROW_HIGHLIGHT`` 0x2000 Use this style to have the background colour and the selection highlight extend over the entire horizontal row of the tree control window. **Styles from hypertreelist:** ``TR_EXTENDED`` 0x40 Use this style to allow disjoint items to be selected. (Only partially implemented; may not work in all cases). ``TR_COLUMN_LINES`` 0x1000 Use this style to draw a contrasting border between displayed columns. ``TR_AUTO_CHECK_CHILD`` 0x4000 Only meaningful for checkbox-type items: when a parent item is checked/unchecked its children are checked/unchecked as well. ``TR_AUTO_TOGGLE_CHILD`` 0x8000 Only meaningful for checkbox-type items: when a parent item is checked/unchecked its children are toggled accordingly. ``TR_AUTO_CHECK_PARENT`` 0x10000 Only meaningful for checkbox-type items: when a child item is checked/unchecked its parent item is checked/unchecked as well. ``TR_ALIGN_WINDOWS`` 0x20000 Has no effect in HyperTreeList. ``TR_NO_HEADER`` 0x40000 Use this style to hide the columns header. ``TR_ELLIPSIZE_LONG_ITEMS`` 0x80000 Flag used to ellipsize long items when the horizontal space for :class:`HyperTreeList` columns is low. ``TR_VIRTUAL`` 0x100000 :class:`HyperTreeList` will have virtual behaviour. ================================= =========== ================================================== See :mod:`~wx.lib.agw.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 :mod:`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 :meth:`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 :meth:`TreeEvent.Veto() `. ``EVT_TREE_GET_INFO`` Request information from the application (not implemented in :class:`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 :meth:`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 :meth:`TreeEvent.Veto() `. ``EVT_TREE_ITEM_GETTOOLTIP`` The opportunity to set the item tooltip is being given to the application (call :meth:`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 :class:`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 :meth:`TreeEvent.Veto() `. ``EVT_TREE_SET_INFO`` Information is being supplied to the application (not implemented in :class:`HyperTreeList`). ``EVT_TREE_STATE_IMAGE_CLICK`` The state image has been clicked (not implemented in :class:`HyperTreeList`). ============================== ================================================== License And Version =================== :class:`HyperTreeList` is distributed under the wxPython license. Latest Revision: Andrea Gavana @ 30 Jul 2014, 21.00 GMT Version 1.4 |function_summary| Functions Summary ==================================== ================================================================================ ================================================================================ :func:`~wx.lib.agw.hypertreelist.create_delegator_for` Creates a method that forwards calls to `self._main_win` (an instance of :class:`TreeListMainWindow`). :func:`~wx.lib.agw.hypertreelist.IsBufferingSupported` Utility function which checks if a platform handles correctly double ================================================================================ ================================================================================ | |class_summary| Classes Summary =============================== ================================================================================ ================================================================================ `~wx.lib.agw.hypertreelist.EditCtrl` Base class for controls used for in-place edit. `~wx.lib.agw.hypertreelist.EditTextCtrl` Text control used for in-place edit. `~wx.lib.agw.hypertreelist.HyperTreeList` :class:`HyperTreeList` is a generic widget that combines the multicolumn `~wx.lib.agw.hypertreelist.TreeListColumnInfo` Class used to store information (width, alignment flags, colours, etc...) about a `~wx.lib.agw.hypertreelist.TreeListHeaderWindow` A window which holds the header of :class:`HyperTreeList`. `~wx.lib.agw.hypertreelist.TreeListItem` This class holds all the information and methods for every single item in `~wx.lib.agw.hypertreelist.TreeListMainWindow` This class represents the main window (and thus the main column) in :class:`HyperTreeList`. ================================================================================ ================================================================================ | .. toctree:: :maxdepth: 1 :hidden: wx.lib.agw.hypertreelist.EditCtrl wx.lib.agw.hypertreelist.EditTextCtrl wx.lib.agw.hypertreelist.HyperTreeList wx.lib.agw.hypertreelist.TreeListColumnInfo wx.lib.agw.hypertreelist.TreeListHeaderWindow wx.lib.agw.hypertreelist.TreeListItem wx.lib.agw.hypertreelist.TreeListMainWindow Functions ------------ .. function:: create_delegator_for(method) Creates a method that forwards calls to `self._main_win` (an instance of :class:`TreeListMainWindow`). :param `method`: one method inside the :class:`TreeListMainWindow` local scope. .. function:: IsBufferingSupported() Utility function which checks if a platform handles correctly double buffering for the header. Currently returns ``False`` for all platforms except Windows XP.