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     void* GetID() const;
  35     void Unset();
  36 };
  37
  38 bool operator==(const wxTreeItemId& left, const wxTreeItemId& right);
  39 bool operator!=(const wxTreeItemId& left, const wxTreeItemId& right);
  40
  41
  42
  43 /**
  44     @class wxTreeItemData
  45
  46     wxTreeItemData is some (arbitrary) user class associated with some item. The
  47     main advantage of having this class is that wxTreeItemData objects are
  48     destroyed automatically by the tree and, as this class has virtual
  49     destructor, it means that the memory and any other resources associated with
  50     a tree item will be automatically freed when it is deleted. Note that we
  51     don't use wxObject as the base class for wxTreeItemData because the size of
  52     this class is critical: in many applications, each tree leaf will have
  53     wxTreeItemData associated with it and the number of leaves may be quite big.
  54
  55     Also please note that because the objects of this class are deleted by the
  56     tree using the operator @c delete, they must always be allocated on the heap
  57     using @c new.
  58
  59     @library{wxcore}
  60     @category{containers}
  61
  62     @see wxTreeCtrl
  63 */
  64 class wxTreeItemData : public wxClientData
  65 {
  66 public:
  67     /**
  68         Default constructor.
  69
  70         @beginWxPythonOnly
  71         The following methods are added in wxPython for accessing the object:
  72         - GetData(): Returns a reference to the Python Object.
  73         - SetData(obj): Associates a new Python Object with the wxTreeItemData.
  74         @endWxPythonOnly
  75
  76         @beginWxPerlOnly
  77         In wxPerl the constructor accepts a scalar as an optional parameter
  78         and stores it as client data; use
  79         - GetData() to retrieve the value.
  80         - SetData(data) to set it.
  81         @endWxPerlOnly
  82     */
  83     wxTreeItemData();
  84
  85     /**
  86         Virtual destructor.
  87     */
  88     virtual ~wxTreeItemData();
  89
  90     /**
  91         Returns the item associated with this node.
  92     */
  93     const wxTreeItemId& GetId() const;
  94
  95     /**
  96         Sets the item associated with this node.
  97
  98         Notice that this function is automatically called by wxTreeCtrl methods
  99         associating an object of this class with a tree control item such as
 100         wxTreeCtrl::AppendItem(), wxTreeCtrl::InsertItem() and
 101         wxTreeCtrl::SetItemData() so there is usually no need to call it
 102         yourself.
 103     */
 104     void SetId(const wxTreeItemId& id);
 105 };
 106
 107 /**
 108     Indicates which type to associate an image with a wxTreeCtrl item.
 109
 110     @see wxTreeCtrl::GetItemImage(), wxTreeCtrl::SetItemImage()
 111 */
 112 enum wxTreeItemIcon
 113 {
 114     /**
 115         To get/set the item image for when the item is
 116         @b not selected and @b not expanded.
 117     */
 118     wxTreeItemIcon_Normal,
 119     /**
 120         To get/set the item image for when the item is
 121         @b selected and @b not expanded.
 122     */
 123     wxTreeItemIcon_Selected,
 124     /**
 125         To get/set the item image for when the item is
 126         @b not selected and @b expanded.
 127     */
 128     wxTreeItemIcon_Expanded,
 129     /**
 130         To get/set the item image for when the item is
 131         @b selected and @b expanded.
 132     */
 133     wxTreeItemIcon_SelectedExpanded,
 134     wxTreeItemIcon_Max
 135 };
 136
 137
 138 /// special values for the 'state' parameter of wxTreeCtrl::SetItemState()
 139 static const int wxTREE_ITEMSTATE_NONE  = -1;   // not state (no display state image)
 140 static const int wxTREE_ITEMSTATE_NEXT  = -2;   // cycle to the next state
 141 static const int wxTREE_ITEMSTATE_PREV  = -3;   // cycle to the previous state
 142
 143 #define wxTR_NO_BUTTONS              0x0000     // for convenience
 144 #define wxTR_HAS_BUTTONS             0x0001     // draw collapsed/expanded btns
 145 #define wxTR_NO_LINES                0x0004     // don't draw lines at all
 146 #define wxTR_LINES_AT_ROOT           0x0008     // connect top-level nodes
 147 #define wxTR_TWIST_BUTTONS           0x0010     // still used by wxTreeListCtrl
 148
 149 #define wxTR_SINGLE                  0x0000     // for convenience
 150 #define wxTR_MULTIPLE                0x0020     // can select multiple items
 151
 152 #define wxTR_HAS_VARIABLE_ROW_HEIGHT 0x0080     // what it says
 153
 154 #define wxTR_EDIT_LABELS             0x0200     // can edit item labels
 155 #define wxTR_ROW_LINES               0x0400     // put border around items
 156 #define wxTR_HIDE_ROOT               0x0800     // don't display root node
 157
 158 #define wxTR_FULL_ROW_HIGHLIGHT      0x2000     // highlight full horz space
 159
 160 // make the default control appearance look more native-like depending on the
 161 // platform
 162 #define wxTR_DEFAULT_STYLE       (wxTR_HAS_BUTTONS | wxTR_LINES_AT_ROOT)
 163
 164
 165 // values for the `flags' parameter of wxTreeCtrl::HitTest() which determine
 166 // where exactly the specified point is situated:
 167
 168 static const int wxTREE_HITTEST_ABOVE            = 0x0001;
 169 static const int wxTREE_HITTEST_BELOW            = 0x0002;
 170 static const int wxTREE_HITTEST_NOWHERE          = 0x0004;
 171     // on the button associated with an item.
 172 static const int wxTREE_HITTEST_ONITEMBUTTON     = 0x0008;
 173     // on the bitmap associated with an item.
 174 static const int wxTREE_HITTEST_ONITEMICON       = 0x0010;
 175     // on the indent associated with an item.
 176 static const int wxTREE_HITTEST_ONITEMINDENT     = 0x0020;
 177     // on the label (string) associated with an item.
 178 static const int wxTREE_HITTEST_ONITEMLABEL      = 0x0040;
 179     // on the right of the label associated with an item.
 180 static const int wxTREE_HITTEST_ONITEMRIGHT      = 0x0080;
 181     // on the label (string) associated with an item.
 182 static const int wxTREE_HITTEST_ONITEMSTATEICON  = 0x0100;
 183     // on the left of the wxTreeCtrl.
 184 static const int wxTREE_HITTEST_TOLEFT           = 0x0200;
 185     // on the right of the wxTreeCtrl.
 186 static const int wxTREE_HITTEST_TORIGHT          = 0x0400;
 187     // on the upper part (first half) of the item.
 188 static const int wxTREE_HITTEST_ONITEMUPPERPART  = 0x0800;
 189     // on the lower part (second half) of the item.
 190 static const int wxTREE_HITTEST_ONITEMLOWERPART  = 0x1000;
 191
 192     // anywhere on the item
 193 static const int wxTREE_HITTEST_ONITEM  = wxTREE_HITTEST_ONITEMICON |
 194                                           wxTREE_HITTEST_ONITEMLABEL;
 195
 196