.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2018 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc

.. module:: wx.lib.agw.customtreectrl

.. currentmodule:: wx.lib.agw.customtreectrl

.. highlight:: python



.. _wx.lib.agw.customtreectrl:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.customtreectrl**
==========================================================================================================================================

:class:`~wx.lib.agw.customtreectrl.CustomTreeCtrl` is a class that mimics the behaviour of :class:`TreeCtrl`, with some more
enhancements.


Description
===========

:class:`CustomTreeCtrl` is a class that mimics the behaviour of :class:`TreeCtrl`, with almost the
same base functionalities plus some more enhancements. This class does not rely on
the native control, as it is a full owner-drawn tree control.
Apart of the base functionalities of :class:`CustomTreeCtrl` (described below), in addition
to the standard :class:`TreeCtrl` behaviour 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:`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 (**note**: to add a newline character in a multiline item, press
  ``Shift`` + ``Enter`` as the ``Enter`` key alone is consumed by :class:`CustomTreeCtrl` to finish
  the editing and ``Ctrl`` + ``Enter`` is consumed by the platform for tab navigation);
* Enabling/disabling items (together with their plain or grayed out icons);
* Whatever non-toplevel widget can be attached next to an item;
* Possibility to horizontally align the widgets attached to tree items on the
  same tree level.
* Possibility to align the widgets attached to tree items to the rightmost edge of :class:`CustomTreeCtrl`;
* Default selection style, gradient (horizontal/vertical) selection style and Windows
  Vista selection style;
* Customized drag and drop images built on the fly;
* Setting the :class:`CustomTreeCtrl` item buttons to a personalized imagelist;
* Setting the :class:`CustomTreeCtrl` 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:`CustomTreeCtrl` background (currently only in "tile" mode);
* Adding images to any item in the leftmost area of the :class:`CustomTreeCtrl` client window.
* Separator-type items which are simply visual indicators that are meant to set apart
  or divide tree items, with the following caveats:

  - Separator items should not have children, labels, data or an associated window;
  - You can change the color of individual separators by using :meth:`~CustomTreeCtrl.SetItemTextColour`, or you can use
    :meth:`~CustomTreeCtrl.SetSeparatorColour` to change the color of all separators. The default separator colour
    is that returned by `SystemSettings.GetColour(wx.SYS_COLOUR_GRAYTEXT)`;
  - Separators can be selected just like any other tree item;
  - Separators cannot have text;
  - Separators cannot have children;
  - Separators cannot be edited via the ``EVT_TREE_BEGIN_LABEL_EDIT`` event.

* Ellipsization of long items when the horizontal space is low, via the ``TR_ELLIPSIZE_LONG_ITEMS``
  style (`New in version 0.9.3`);
* Tooltips on long items when the horizontal space is low, via the ``TR_TOOLTIP_ON_LONG_ITEMS``
  style (`New in version 0.9.3`).

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


Base Functionalities
====================

:class:`CustomTreeCtrl` supports all the :class:`TreeCtrl` 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 two styles you can use to force the horizontal alignment of all the widgets
attached to the tree items:

- ``TR_ALIGN_WINDOWS``: aligns horizontally the windows belonging to the item on the
  same tree level.
- ``TR_ALIGN_WINDOWS_RIGHT``: aligns to the rightmost position the windows belonging
  to the item on the same tree level.

And two styles related to long items (with a lot of text in them), which can be
ellipsized and/or highlighted with a tooltip:

- ``TR_ELLIPSIZE_LONG_ITEMS``: ellipsizes long items when the horizontal space for
  :class:`CustomTreeCtrl` is low (`New in version 0.9.3`);
- ``TR_TOOLTIP_ON_LONG_ITEMS``: shows tooltips on long items when the horizontal space
  for :class:`CustomTreeCtrl` is low (`New in version 0.9.3`);.

All the methods available in :class:`TreeCtrl` are also available in :class:`CustomTreeCtrl`.


Usage
=====

Usage example::

    import wx
    import wx.lib.agw.customtreectrl as CT

    class MyFrame(wx.Frame):

        def __init__(self, parent):

            wx.Frame.__init__(self, parent, -1, "CustomTreeCtrl Demo")

            # Create a CustomTreeCtrl instance
            custom_tree = CT.CustomTreeCtrl(self, agwStyle=wx.TR_DEFAULT_STYLE)

            # Add a root node to it
            root = custom_tree.AddRoot("The Root Item")

            # Create an image list to add icons next to an item
            il = wx.ImageList(16, 16)
            fldridx     = il.Add(wx.ArtProvider.GetBitmap(wx.ART_FOLDER,      wx.ART_OTHER, (16, 16)))
            fldropenidx = il.Add(wx.ArtProvider.GetBitmap(wx.ART_FILE_OPEN,   wx.ART_OTHER, (16, 16)))
            fileidx     = il.Add(wx.ArtProvider.GetBitmap(wx.ART_NORMAL_FILE, wx.ART_OTHER, (16, 16)))

            custom_tree.SetImageList(il)

            custom_tree.SetItemImage(root, fldridx, wx.TreeItemIcon_Normal)
            custom_tree.SetItemImage(root, fldropenidx, wx.TreeItemIcon_Expanded)

            for x in range(15):
                child = custom_tree.AppendItem(root, "Item %d" % x)
                custom_tree.SetItemImage(child, fldridx, wx.TreeItemIcon_Normal)
                custom_tree.SetItemImage(child, fldropenidx, wx.TreeItemIcon_Expanded)

                for y in range(5):
                    last = custom_tree.AppendItem(child, "item %d-%s" % (x, chr(ord("a")+y)))
                    custom_tree.SetItemImage(last, fldridx, wx.TreeItemIcon_Normal)
                    custom_tree.SetItemImage(last, fldropenidx, wx.TreeItemIcon_Expanded)

                    for z in range(5):
                        item = custom_tree.AppendItem(last,  "item %d-%s-%d" % (x, chr(ord("a")+y), z))
                        custom_tree.SetItemImage(item, fileidx, wx.TreeItemIcon_Normal)

            custom_tree.Expand(root)


    # our normal wxApp-derived class, as usual

    app = wx.App(0)

    frame = MyFrame(None)
    app.SetTopWindow(frame)
    frame.Show()

    app.MainLoop()



Events
======

All the events supported by :class:`TreeCtrl` are also available in :class:`CustomTreeCtrl`, 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:`CustomTreeCtrl` 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:`CustomTreeCtrl` has been tested on the following platforms:
  * Windows (Windows XP);
  * GTK (Thanks to Michele Petrazzo);
  * Mac OS (Thanks to John Jackson).


Window Styles
=============

This class supports the following window styles:

============================== =========== ==================================================
Window Styles                  Hex Value   Description
============================== =========== ==================================================
``TR_NO_BUTTONS``                      0x0 For convenience to document that no buttons are to be drawn.
``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.
``TR_HAS_BUTTONS``                     0x1 Use this style to show + and - buttons to the left of parent items.
``TR_NO_LINES``                        0x4 Use this style to hide vertical level connectors.
``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.
``TR_DEFAULT_STYLE``                   0x9 The set of flags that are closest to the defaults for the native control for a particular toolkit.
``TR_TWIST_BUTTONS``                  0x10 Use old Mac-twist style buttons.
``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.
``TR_EXTENDED``                       0x40 Use this style to allow disjoint items to be selected. (Only partially implemented; may not work in all cases).
``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.
``TR_EDIT_LABELS``                   0x200 Use this style if you wish the user to be able to edit labels in the tree control.
``TR_ROW_LINES``                     0x400 Use this style to draw a contrasting border between displayed rows.
``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.
``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.
``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 Flag used to align windows (in items with windows) at the same horizontal position.
``TR_ALIGN_WINDOWS_RIGHT``         0x40000 Flag used to align windows (in items with windows) to the rightmost edge of :class:`CustomTreeCtrl`.
``TR_ELLIPSIZE_LONG_ITEMS``        0x80000 Flag used to ellipsize long items when the horizontal space for :class:`CustomTreeCtrl` is low.
``TR_TOOLTIP_ON_LONG_ITEMS``      0x100000 Flag used to show tooltips on long items when the horizontal space for :class:`CustomTreeCtrl` is low.
============================== =========== ==================================================


Events Processing
=================

This class processes the following events:

============================== ==================================================
Event Name                     Description
============================== ==================================================
``EVT_TREE_BEGIN_DRAG``        Begin dragging with the left mouse button.
``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:`CustomTreeCtrl`).
``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.
``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 `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:`CustomTreeCtrl`).
``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:`CustomTreeCtrl`).
``EVT_TREE_STATE_IMAGE_CLICK`` The state image has been clicked (not implemented in :class:`CustomTreeCtrl`).
============================== ==================================================


License And Version
===================

:class:`CustomTreeCtrl` is distributed under the wxPython license.

Latest Revision: Helio Guilherme @ 09 Aug 2018, 21.35 GMT

Version 2.7


|function_summary| Functions Summary
====================================

================================================================================ ================================================================================
:func:`~wx.lib.agw.customtreectrl.ChopText`                                      Chops the input `text` if its size does not fit in `max_size`, by cutting the
:func:`~wx.lib.agw.customtreectrl.DrawTreeItemButton`                            Draw the expanded/collapsed icon for a tree control item.
:func:`~wx.lib.agw.customtreectrl.EventFlagsToSelType`                           Translate the key or mouse event flag to the type of selection we
:func:`~wx.lib.agw.customtreectrl.MakeDisabledBitmap`                            Creates a disabled-looking bitmap starting from the input one.
================================================================================ ================================================================================


|


|class_summary| Classes Summary
===============================

================================================================================ ================================================================================
:ref:`~wx.lib.agw.customtreectrl.CommandTreeEvent`                               :class:`CommandTreeEvent` is a special subclassing of :class:`CommandEvent`.
:ref:`~wx.lib.agw.customtreectrl.CustomTreeCtrl`                                 :class:`CustomTreeCtrl` is a class that mimics the behaviour of :class:`TreeCtrl`, with almost the
:ref:`~wx.lib.agw.customtreectrl.DragImage`                                      This class handles the creation of a custom image in case of item drag
:ref:`~wx.lib.agw.customtreectrl.GenericTreeItem`                                This class holds all the information and methods for every single item in
:ref:`~wx.lib.agw.customtreectrl.TreeEditTimer`                                  Timer used for enabling in-place edit.
:ref:`~wx.lib.agw.customtreectrl.TreeEvent`                                      :class:`CommandTreeEvent` is a special class for all events associated with tree controls.
:ref:`~wx.lib.agw.customtreectrl.TreeFindTimer`                                  Timer used to clear the :class:`CustomTreeCtrl` `_findPrefix` attribute if no
:ref:`~wx.lib.agw.customtreectrl.TreeItemAttr`                                   Creates the item attributes (text colour, background colour and font).
:ref:`~wx.lib.agw.customtreectrl.TreeTextCtrl`                                   Control used for in-place edit.
================================================================================ ================================================================================


|


.. toctree::
   :maxdepth: 1
   :hidden:

   wx.lib.agw.customtreectrl.CommandTreeEvent
   wx.lib.agw.customtreectrl.CustomTreeCtrl
   wx.lib.agw.customtreectrl.DragImage
   wx.lib.agw.customtreectrl.GenericTreeItem
   wx.lib.agw.customtreectrl.TreeEditTimer
   wx.lib.agw.customtreectrl.TreeEvent
   wx.lib.agw.customtreectrl.TreeFindTimer
   wx.lib.agw.customtreectrl.TreeItemAttr
   wx.lib.agw.customtreectrl.TreeTextCtrl





Functions
------------

.. function:: ChopText(dc, text, max_size)

   Chops the input `text` if its size does not fit in `max_size`, by cutting the
   text and adding ellipsis at the end.
   
   :param `dc`: a :class:`wx.DC` device context;
   :param `text`: the text to chop;
   :param `max_size`: the maximum size in which the text should fit.
   
   :note: This method is used exclusively when :class:`CustomTreeCtrl` has the ``TR_ELLIPSIZE_LONG_ITEMS``
    style set.
   
   .. versionadded:: 0.9.3


.. function:: DrawTreeItemButton(win, dc, rect, flags)

   Draw the expanded/collapsed icon for a tree control item.
   
   :param `win`: an instance of :class:`wx.Window`;
   :param `dc`: an instance of :class:`wx.DC`;
   :param wx.Rect `rect`: the client rectangle where to draw the tree item button;
   :param integer `flags`: contains ``wx.CONTROL_EXPANDED`` bit for expanded tree items.
   
   :note: This is a simple replacement of :meth:`RendererNative.DrawTreeItemButton`.
   
   :note: This method is never used in wxPython versions newer than 2.6.2.1.


.. function:: EventFlagsToSelType(style, shiftDown=False, ctrlDown=False)

   Translate the key or mouse event flag to the type of selection we
   are dealing with.
   
   :param integer `style`: the main :class:`CustomTreeCtrl` window style flag;
   :param bool `shiftDown`: ``True`` if the ``Shift`` key is pressed, ``False`` otherwise;
   :param bool `ctrlDown`: ``True`` if the ``Ctrl`` key is pressed, ``False`` otherwise;
   
   :return: A 3-elements tuple, with the following elements:
   
    - `is_multiple`: ``True`` if :class:`CustomTreeCtrl` has the ``TR_MULTIPLE`` flag set, ``False`` otherwise;
    - `extended_select`: ``True`` if the ``Shift`` key is pressend and if :class:`CustomTreeCtrl` has the
      ``TR_MULTIPLE`` flag set, ``False`` otherwise;
    - `unselect_others`: ``True`` if the ``Ctrl`` key is pressend and if :class:`CustomTreeCtrl` has the
      ``TR_MULTIPLE`` flag set, ``False`` otherwise.


.. function:: MakeDisabledBitmap(original)

   Creates a disabled-looking bitmap starting from the input one.
   
   :param `original`: an instance of :class:`wx.Bitmap` to be greyed-out.
   
   :return: An instance of :class:`wx.Bitmap`, containing a disabled-looking
    representation of the original item image.