Package wx :: Package lib :: Package agw :: Module customtreectrl
[frames | no frames]

Module wx.lib.agw.customtreectrl

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

CustomTreeCtrl is a class that mimics the behaviour of wx.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 CustomTreeCtrl (described below), in addition
to the standard wx.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;

* 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 (NOTE: to add a newline character in a multiline item, press
  Shift+Enter as the Enter key alone is consumed by CustomTreeCtrl to finish the editing
  and Ctr++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.

* Default selection style, gradient (horizontal/vertical) selection style and Windows
  Vista selection style.

* Customized drag and drop images built on the fly.

* Setting the CustomTreeCtrl item buttons to a personalized imagelist.

* Setting the CustomTreeCtrl 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 CustomTreeCtrl background (currently only in "tile" mode).

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


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

CustomTreeCtrl supports all the wx.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 a style you can use to force the horizontal alignment of all the widgets
attached to the tree items:
  - TR_ALIGN_WINDOWS: aligns horizontally the windows belongiing to the item
    on the same tree level.
    
All the methods available in wx.TreeCtrl are also available in CustomTreeCtrl.


Events
======

All the events supported by wx.TreeCtrl are also available in 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, 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
===================

CustomTreeCtrl has been tested on the following platforms:
  * Windows (Windows XP);
  * GTK (Thanks to Michele Petrazzo);
  * Mac OS (Thanks to John Jackson).


Latest Revision: Andrea Gavana @ 15 Oct 2008, 10.00 GMT
Version 1.8

Classes
CommandTreeEvent CommandTreeEvent is a special subclassing of wx.PyCommandEvent.
CustomTreeCtrl  
DragImage This class handles the creation of a custom image in case of item drag and drop.
GenericTreeItem This class holds all the information and methods for every single item in CustomTreeCtrl.
TreeEvent  
TreeFindTimer Timer used to clear CustomTreeCtrl._findPrefix if no key was pressed for a sufficiently long time.
TreeItemAttr Creates the item attributes (text colour, background colour and font).
TreeRenameTimer Timer used for enabling in-place edit.
TreeTextCtrl Control used for in-place edit.

Function Summary
  DrawTreeItemButton(win, dc, rect, flags)
A simple replacement of wx.RendererNative.DrawTreeItemButton.
  EventFlagsToSelType(style, shiftDown, ctrlDown)
Translate the key or mouse event flag to the type of selection we are dealing with.
  GrayOut(anImage)
Convert the given image (in place) to a grayed-out version, appropriate for a 'disabled' appearance.
  MakeGray((r, g, b), factor, maskColor)
Make a pixel grayed-out.

Function Details

DrawTreeItemButton(win, dc, rect, flags)

A simple replacement of wx.RendererNative.DrawTreeItemButton.

EventFlagsToSelType(style, shiftDown=False, ctrlDown=False)

Translate the key or mouse event flag to the type of selection we are dealing with.

GrayOut(anImage)

Convert the given image (in place) to a grayed-out version, appropriate for a 'disabled' appearance.

MakeGray((r, g, b), factor, maskColor)

Make a pixel grayed-out. If the pixel matches the maskcolor, it won't be changed.


Generated by Epydoc 2.1.20050511.rpd on Mon Feb 16 12:55:35 2009 http://epydoc.sf.net