interface/wx/treebase.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        treebase.h
   3 // Purpose:     interface of wxTreeItemId
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxTreeItemId
  11
  12     An opaque reference to a tree item.
  13
  14     @library{wxcore}
  15     @category{data}
  16
  17     @see wxTreeCtrl, wxTreeItemData, @ref overview_treectrl
  18 */
  19 class wxTreeItemId
  20 {
  21 public:
  22     /**
  23         Default constructor. A wxTreeItemId is not meant to be constructed
  24         explicitly by the user; only those returned by the wxTreeCtrl functions
  25         should be used.
  26     */
  27     wxTreeItemId();
  28
  29     /**
  30         Returns @true if this instance is referencing a valid tree item.
  31     */
  32     bool IsOk() const;
  33
  34     //@{
  35     /**
  36          Operators for comparison between wxTreeItemId objects.
  37     */
  38     bool operator ==(const wxTreeItemId& item) const;
  39     bool operator !=(const wxTreeItemId& item) const;
  40     //@}
  41
  42     /**
  43         Antonym of IsOk(), i.e. returns @true only if the item is not valid.
  44     */
  45     bool operator !() const;
  46 };
  47
  48 /**
  49     @class wxTreeItemData
  50
  51     wxTreeItemData is some (arbitrary) user class associated with some item. The
  52     main advantage of having this class is that wxTreeItemData objects are
  53     destroyed automatically by the tree and, as this class has virtual
  54     destructor, it means that the memory and any other resources associated with
  55     a tree item will be automatically freed when it is deleted. Note that we
  56     don't use wxObject as the base class for wxTreeItemData because the size of
  57     this class is critical: in many applications, each tree leaf will have
  58     wxTreeItemData associated with it and the number of leaves may be quite big.
  59
  60     Also please note that because the objects of this class are deleted by the
  61     tree using the operator @c delete, they must always be allocated on the heap
  62     using @c new.
  63
  64     @library{wxcore}
  65     @category{containers}
  66
  67     @see wxTreeCtrl
  68 */
  69 class wxTreeItemData : public wxClientData
  70 {
  71 public:
  72     /**
  73         Default constructor.
  74
  75         @beginWxPythonOnly
  76         The following methods are added in wxPython for accessing the object:
  77         - GetData(): Returns a reference to the Python Object.
  78         - SetData(obj): Associates a new Python Object with the wxTreeItemData.
  79         @endWxPythonOnly
  80
  81         @beginWxPerlOnly
  82         In wxPerl the constructor accepts a scalar as an optional parameter
  83         and stores it as client data; use
  84         - GetData() to retrieve the value.
  85         - SetData(data) to set it.
  86         @endWxPerlOnly
  87     */
  88     wxTreeItemData();
  89
  90     /**
  91         Virtual destructor.
  92     */
  93     virtual ~wxTreeItemData();
  94
  95     /**
  96         Returns the item associated with this node.
  97     */
  98     const wxTreeItemId& GetId() const;
  99
 100     /**
 101         Sets the item associated with this node.
 102
 103         Notice that this function is automatically called by wxTreeCtrl methods
 104         associating an object of this class with a tree control item such as
 105         wxTreeCtrl::AppendItem(), wxTreeCtrl::InsertItem() and
 106         wxTreeCtrl::SetItemData() so there is usually no need to call it
 107         yourself.
 108     */
 109     void SetId(const wxTreeItemId& id);
 110 };
 111
 112 /**
 113     Indicates which type to associate an image with a wxTreeCtrl item.
 114
 115     @see wxTreeCtrl::GetItemImage(), wxTreeCtrl::SetItemImage()
 116 */
 117 enum wxTreeItemIcon
 118 {
 119     /**
 120         To get/set the item image for when the item is
 121         @b not selected and @b not expanded.
 122     */
 123     wxTreeItemIcon_Normal,
 124     /**
 125         To get/set the item image for when the item is
 126         @b selected and @b not expanded.
 127     */
 128     wxTreeItemIcon_Selected,
 129     /**
 130         To get/set the item image for when the item is
 131         @b not selected and @b expanded.
 132     */
 133     wxTreeItemIcon_Expanded,
 134     /**
 135         To get/set the item image for when the item is
 136         @b selected and @b expanded.
 137     */
 138     wxTreeItemIcon_SelectedExpanded,
 139     wxTreeItemIcon_Max
 140 };