| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: wx/treectrl.h |
| 3 | // Purpose: wxTreeCtrl base header |
| 4 | // Author: Karsten Ballueder |
| 5 | // Modified by: |
| 6 | // Created: |
| 7 | // Copyright: (c) Karsten Ballueder |
| 8 | // RCS-ID: $Id$ |
| 9 | // Licence: wxWindows licence |
| 10 | ///////////////////////////////////////////////////////////////////////////// |
| 11 | |
| 12 | #ifndef _WX_TREECTRL_H_BASE_ |
| 13 | #define _WX_TREECTRL_H_BASE_ |
| 14 | |
| 15 | // ---------------------------------------------------------------------------- |
| 16 | // headers |
| 17 | // ---------------------------------------------------------------------------- |
| 18 | |
| 19 | #include "wx/defs.h" |
| 20 | |
| 21 | #if wxUSE_TREECTRL |
| 22 | |
| 23 | #include "wx/control.h" |
| 24 | #include "wx/treebase.h" |
| 25 | #include "wx/textctrl.h" // wxTextCtrl::ms_classinfo used through CLASSINFO macro |
| 26 | |
| 27 | class WXDLLIMPEXP_FWD_CORE wxImageList; |
| 28 | |
| 29 | // ---------------------------------------------------------------------------- |
| 30 | // wxTreeCtrlBase |
| 31 | // ---------------------------------------------------------------------------- |
| 32 | |
| 33 | class WXDLLEXPORT wxTreeCtrlBase : public wxControl |
| 34 | { |
| 35 | public: |
| 36 | wxTreeCtrlBase() |
| 37 | { |
| 38 | m_imageListNormal = |
| 39 | m_imageListState = NULL; |
| 40 | m_ownsImageListNormal = |
| 41 | m_ownsImageListState = false; |
| 42 | |
| 43 | // arbitrary default |
| 44 | m_spacing = 18; |
| 45 | |
| 46 | // quick DoGetBestSize calculation |
| 47 | m_quickBestSize = true; |
| 48 | } |
| 49 | |
| 50 | virtual ~wxTreeCtrlBase(); |
| 51 | |
| 52 | // accessors |
| 53 | // --------- |
| 54 | |
| 55 | // get the total number of items in the control |
| 56 | virtual unsigned int GetCount() const = 0; |
| 57 | |
| 58 | // indent is the number of pixels the children are indented relative to |
| 59 | // the parents position. SetIndent() also redraws the control |
| 60 | // immediately. |
| 61 | virtual unsigned int GetIndent() const = 0; |
| 62 | virtual void SetIndent(unsigned int indent) = 0; |
| 63 | |
| 64 | // spacing is the number of pixels between the start and the Text |
| 65 | // (has no effect under wxMSW) |
| 66 | unsigned int GetSpacing() const { return m_spacing; } |
| 67 | void SetSpacing(unsigned int spacing) { m_spacing = spacing; } |
| 68 | |
| 69 | // image list: these functions allow to associate an image list with |
| 70 | // the control and retrieve it. Note that the control does _not_ delete |
| 71 | // the associated image list when it's deleted in order to allow image |
| 72 | // lists to be shared between different controls. |
| 73 | // |
| 74 | // The normal image list is for the icons which correspond to the |
| 75 | // normal tree item state (whether it is selected or not). |
| 76 | // Additionally, the application might choose to show a state icon |
| 77 | // which corresponds to an app-defined item state (for example, |
| 78 | // checked/unchecked) which are taken from the state image list. |
| 79 | wxImageList *GetImageList() const { return m_imageListNormal; } |
| 80 | wxImageList *GetStateImageList() const { return m_imageListState; } |
| 81 | |
| 82 | virtual void SetImageList(wxImageList *imageList) = 0; |
| 83 | virtual void SetStateImageList(wxImageList *imageList) = 0; |
| 84 | void AssignImageList(wxImageList *imageList) |
| 85 | { |
| 86 | SetImageList(imageList); |
| 87 | m_ownsImageListNormal = true; |
| 88 | } |
| 89 | void AssignStateImageList(wxImageList *imageList) |
| 90 | { |
| 91 | SetStateImageList(imageList); |
| 92 | m_ownsImageListState = true; |
| 93 | } |
| 94 | |
| 95 | |
| 96 | // Functions to work with tree ctrl items. Unfortunately, they can _not_ be |
| 97 | // member functions of wxTreeItem because they must know the tree the item |
| 98 | // belongs to for Windows implementation and storing the pointer to |
| 99 | // wxTreeCtrl in each wxTreeItem is just too much waste. |
| 100 | |
| 101 | // accessors |
| 102 | // --------- |
| 103 | |
| 104 | // retrieve items label |
| 105 | virtual wxString GetItemText(const wxTreeItemId& item) const = 0; |
| 106 | // get one of the images associated with the item (normal by default) |
| 107 | virtual int GetItemImage(const wxTreeItemId& item, |
| 108 | wxTreeItemIcon which = wxTreeItemIcon_Normal) const = 0; |
| 109 | // get the data associated with the item |
| 110 | virtual wxTreeItemData *GetItemData(const wxTreeItemId& item) const = 0; |
| 111 | |
| 112 | // get the item's text colour |
| 113 | virtual wxColour GetItemTextColour(const wxTreeItemId& item) const = 0; |
| 114 | |
| 115 | // get the item's background colour |
| 116 | virtual wxColour GetItemBackgroundColour(const wxTreeItemId& item) const = 0; |
| 117 | |
| 118 | // get the item's font |
| 119 | virtual wxFont GetItemFont(const wxTreeItemId& item) const = 0; |
| 120 | |
| 121 | // modifiers |
| 122 | // --------- |
| 123 | |
| 124 | // set items label |
| 125 | virtual void SetItemText(const wxTreeItemId& item, const wxString& text) = 0; |
| 126 | // set one of the images associated with the item (normal by default) |
| 127 | virtual void SetItemImage(const wxTreeItemId& item, |
| 128 | int image, |
| 129 | wxTreeItemIcon which = wxTreeItemIcon_Normal) = 0; |
| 130 | // associate some data with the item |
| 131 | virtual void SetItemData(const wxTreeItemId& item, wxTreeItemData *data) = 0; |
| 132 | |
| 133 | // force appearance of [+] button near the item. This is useful to |
| 134 | // allow the user to expand the items which don't have any children now |
| 135 | // - but instead add them only when needed, thus minimizing memory |
| 136 | // usage and loading time. |
| 137 | virtual void SetItemHasChildren(const wxTreeItemId& item, |
| 138 | bool has = true) = 0; |
| 139 | |
| 140 | // the item will be shown in bold |
| 141 | virtual void SetItemBold(const wxTreeItemId& item, bool bold = true) = 0; |
| 142 | |
| 143 | // the item will be shown with a drop highlight |
| 144 | virtual void SetItemDropHighlight(const wxTreeItemId& item, |
| 145 | bool highlight = true) = 0; |
| 146 | |
| 147 | // set the items text colour |
| 148 | virtual void SetItemTextColour(const wxTreeItemId& item, |
| 149 | const wxColour& col) = 0; |
| 150 | |
| 151 | // set the items background colour |
| 152 | virtual void SetItemBackgroundColour(const wxTreeItemId& item, |
| 153 | const wxColour& col) = 0; |
| 154 | |
| 155 | // set the items font (should be of the same height for all items) |
| 156 | virtual void SetItemFont(const wxTreeItemId& item, |
| 157 | const wxFont& font) = 0; |
| 158 | |
| 159 | // item status inquiries |
| 160 | // --------------------- |
| 161 | |
| 162 | // is the item visible (it might be outside the view or not expanded)? |
| 163 | virtual bool IsVisible(const wxTreeItemId& item) const = 0; |
| 164 | // does the item has any children? |
| 165 | virtual bool ItemHasChildren(const wxTreeItemId& item) const = 0; |
| 166 | // same as above |
| 167 | bool HasChildren(const wxTreeItemId& item) const |
| 168 | { return ItemHasChildren(item); } |
| 169 | // is the item expanded (only makes sense if HasChildren())? |
| 170 | virtual bool IsExpanded(const wxTreeItemId& item) const = 0; |
| 171 | // is this item currently selected (the same as has focus)? |
| 172 | virtual bool IsSelected(const wxTreeItemId& item) const = 0; |
| 173 | // is item text in bold font? |
| 174 | virtual bool IsBold(const wxTreeItemId& item) const = 0; |
| 175 | // is the control empty? |
| 176 | bool IsEmpty() const; |
| 177 | |
| 178 | |
| 179 | // number of children |
| 180 | // ------------------ |
| 181 | |
| 182 | // if 'recursively' is false, only immediate children count, otherwise |
| 183 | // the returned number is the number of all items in this branch |
| 184 | virtual size_t GetChildrenCount(const wxTreeItemId& item, |
| 185 | bool recursively = true) const = 0; |
| 186 | |
| 187 | // navigation |
| 188 | // ---------- |
| 189 | |
| 190 | // wxTreeItemId.IsOk() will return false if there is no such item |
| 191 | |
| 192 | // get the root tree item |
| 193 | virtual wxTreeItemId GetRootItem() const = 0; |
| 194 | |
| 195 | // get the item currently selected (may return NULL if no selection) |
| 196 | virtual wxTreeItemId GetSelection() const = 0; |
| 197 | |
| 198 | // get the items currently selected, return the number of such item |
| 199 | // |
| 200 | // NB: this operation is expensive and can take a long time for a |
| 201 | // control with a lot of items (~ O(number of items)). |
| 202 | virtual size_t GetSelections(wxArrayTreeItemIds& selections) const = 0; |
| 203 | |
| 204 | // get the parent of this item (may return NULL if root) |
| 205 | virtual wxTreeItemId GetItemParent(const wxTreeItemId& item) const = 0; |
| 206 | |
| 207 | // for this enumeration function you must pass in a "cookie" parameter |
| 208 | // which is opaque for the application but is necessary for the library |
| 209 | // to make these functions reentrant (i.e. allow more than one |
| 210 | // enumeration on one and the same object simultaneously). Of course, |
| 211 | // the "cookie" passed to GetFirstChild() and GetNextChild() should be |
| 212 | // the same! |
| 213 | |
| 214 | // get the first child of this item |
| 215 | virtual wxTreeItemId GetFirstChild(const wxTreeItemId& item, |
| 216 | wxTreeItemIdValue& cookie) const = 0; |
| 217 | // get the next child |
| 218 | virtual wxTreeItemId GetNextChild(const wxTreeItemId& item, |
| 219 | wxTreeItemIdValue& cookie) const = 0; |
| 220 | // get the last child of this item - this method doesn't use cookies |
| 221 | virtual wxTreeItemId GetLastChild(const wxTreeItemId& item) const = 0; |
| 222 | |
| 223 | // get the next sibling of this item |
| 224 | virtual wxTreeItemId GetNextSibling(const wxTreeItemId& item) const = 0; |
| 225 | // get the previous sibling |
| 226 | virtual wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const = 0; |
| 227 | |
| 228 | // get first visible item |
| 229 | virtual wxTreeItemId GetFirstVisibleItem() const = 0; |
| 230 | // get the next visible item: item must be visible itself! |
| 231 | // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem() |
| 232 | virtual wxTreeItemId GetNextVisible(const wxTreeItemId& item) const = 0; |
| 233 | // get the previous visible item: item must be visible itself! |
| 234 | virtual wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const = 0; |
| 235 | |
| 236 | // operations |
| 237 | // ---------- |
| 238 | |
| 239 | // add the root node to the tree |
| 240 | virtual wxTreeItemId AddRoot(const wxString& text, |
| 241 | int image = -1, int selImage = -1, |
| 242 | wxTreeItemData *data = NULL) = 0; |
| 243 | |
| 244 | // insert a new item in as the first child of the parent |
| 245 | wxTreeItemId PrependItem(const wxTreeItemId& parent, |
| 246 | const wxString& text, |
| 247 | int image = -1, int selImage = -1, |
| 248 | wxTreeItemData *data = NULL) |
| 249 | { |
| 250 | return DoInsertItem(parent, 0u, text, image, selImage, data); |
| 251 | } |
| 252 | |
| 253 | // insert a new item after a given one |
| 254 | wxTreeItemId InsertItem(const wxTreeItemId& parent, |
| 255 | const wxTreeItemId& idPrevious, |
| 256 | const wxString& text, |
| 257 | int image = -1, int selImage = -1, |
| 258 | wxTreeItemData *data = NULL) |
| 259 | { |
| 260 | return DoInsertAfter(parent, idPrevious, text, image, selImage, data); |
| 261 | } |
| 262 | |
| 263 | // insert a new item before the one with the given index |
| 264 | wxTreeItemId InsertItem(const wxTreeItemId& parent, |
| 265 | size_t pos, |
| 266 | const wxString& text, |
| 267 | int image = -1, int selImage = -1, |
| 268 | wxTreeItemData *data = NULL) |
| 269 | { |
| 270 | return DoInsertItem(parent, pos, text, image, selImage, data); |
| 271 | } |
| 272 | |
| 273 | // insert a new item in as the last child of the parent |
| 274 | wxTreeItemId AppendItem(const wxTreeItemId& parent, |
| 275 | const wxString& text, |
| 276 | int image = -1, int selImage = -1, |
| 277 | wxTreeItemData *data = NULL) |
| 278 | { |
| 279 | return DoInsertItem(parent, (size_t)-1, text, image, selImage, data); |
| 280 | } |
| 281 | |
| 282 | // delete this item and associated data if any |
| 283 | virtual void Delete(const wxTreeItemId& item) = 0; |
| 284 | // delete all children (but don't delete the item itself) |
| 285 | // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events |
| 286 | virtual void DeleteChildren(const wxTreeItemId& item) = 0; |
| 287 | // delete all items from the tree |
| 288 | // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events |
| 289 | virtual void DeleteAllItems() = 0; |
| 290 | |
| 291 | // expand this item |
| 292 | virtual void Expand(const wxTreeItemId& item) = 0; |
| 293 | // expand the item and all its childs and thats childs |
| 294 | void ExpandAllChildren(const wxTreeItemId& item); |
| 295 | // expand all items |
| 296 | void ExpandAll(); |
| 297 | // collapse the item without removing its children |
| 298 | virtual void Collapse(const wxTreeItemId& item) = 0; |
| 299 | // collapse the item and all its childs and thats childs |
| 300 | void CollapseAllChildren(const wxTreeItemId& item); |
| 301 | // collapse all items |
| 302 | void CollapseAll(); |
| 303 | // collapse the item and remove all children |
| 304 | virtual void CollapseAndReset(const wxTreeItemId& item) = 0; |
| 305 | // toggles the current state |
| 306 | virtual void Toggle(const wxTreeItemId& item) = 0; |
| 307 | |
| 308 | // remove the selection from currently selected item (if any) |
| 309 | virtual void Unselect() = 0; |
| 310 | // unselect all items (only makes sense for multiple selection control) |
| 311 | virtual void UnselectAll() = 0; |
| 312 | // select this item |
| 313 | virtual void SelectItem(const wxTreeItemId& item, bool select = true) = 0; |
| 314 | // unselect this item |
| 315 | void UnselectItem(const wxTreeItemId& item) { SelectItem(item, false); } |
| 316 | // toggle item selection |
| 317 | void ToggleItemSelection(const wxTreeItemId& item) |
| 318 | { |
| 319 | SelectItem(item, !IsSelected(item)); |
| 320 | } |
| 321 | |
| 322 | // make sure this item is visible (expanding the parent item and/or |
| 323 | // scrolling to this item if necessary) |
| 324 | virtual void EnsureVisible(const wxTreeItemId& item) = 0; |
| 325 | // scroll to this item (but don't expand its parent) |
| 326 | virtual void ScrollTo(const wxTreeItemId& item) = 0; |
| 327 | |
| 328 | // start editing the item label: this (temporarily) replaces the item |
| 329 | // with a one line edit control. The item will be selected if it hadn't |
| 330 | // been before. textCtrlClass parameter allows you to create an edit |
| 331 | // control of arbitrary user-defined class deriving from wxTextCtrl. |
| 332 | virtual wxTextCtrl *EditLabel(const wxTreeItemId& item, |
| 333 | wxClassInfo* textCtrlClass = CLASSINFO(wxTextCtrl)) = 0; |
| 334 | // returns the same pointer as StartEdit() if the item is being edited, |
| 335 | // NULL otherwise (it's assumed that no more than one item may be |
| 336 | // edited simultaneously) |
| 337 | virtual wxTextCtrl *GetEditControl() const = 0; |
| 338 | // end editing and accept or discard the changes to item label |
| 339 | virtual void EndEditLabel(const wxTreeItemId& item, |
| 340 | bool discardChanges = false) = 0; |
| 341 | |
| 342 | // sorting |
| 343 | // ------- |
| 344 | |
| 345 | // this function is called to compare 2 items and should return -1, 0 |
| 346 | // or +1 if the first item is less than, equal to or greater than the |
| 347 | // second one. The base class version performs alphabetic comparaison |
| 348 | // of item labels (GetText) |
| 349 | virtual int OnCompareItems(const wxTreeItemId& item1, |
| 350 | const wxTreeItemId& item2) |
| 351 | { |
| 352 | return wxStrcmp(GetItemText(item1), GetItemText(item2)); |
| 353 | } |
| 354 | |
| 355 | // sort the children of this item using OnCompareItems |
| 356 | // |
| 357 | // NB: this function is not reentrant and not MT-safe (FIXME)! |
| 358 | virtual void SortChildren(const wxTreeItemId& item) = 0; |
| 359 | |
| 360 | // items geometry |
| 361 | // -------------- |
| 362 | |
| 363 | // determine to which item (if any) belongs the given point (the |
| 364 | // coordinates specified are relative to the client area of tree ctrl) |
| 365 | // and, in the second variant, fill the flags parameter with a bitmask |
| 366 | // of wxTREE_HITTEST_xxx constants. |
| 367 | wxTreeItemId HitTest(const wxPoint& point) const |
| 368 | { int dummy; return DoTreeHitTest(point, dummy); } |
| 369 | wxTreeItemId HitTest(const wxPoint& point, int& flags) const |
| 370 | { return DoTreeHitTest(point, flags); } |
| 371 | |
| 372 | // get the bounding rectangle of the item (or of its label only) |
| 373 | virtual bool GetBoundingRect(const wxTreeItemId& item, |
| 374 | wxRect& rect, |
| 375 | bool textOnly = false) const = 0; |
| 376 | |
| 377 | |
| 378 | // implementation |
| 379 | // -------------- |
| 380 | |
| 381 | virtual bool ShouldInheritColours() const { return false; } |
| 382 | |
| 383 | // hint whether to calculate best size quickly or accurately |
| 384 | void SetQuickBestSize(bool q) { m_quickBestSize = q; } |
| 385 | bool GetQuickBestSize() const { return m_quickBestSize; } |
| 386 | |
| 387 | protected: |
| 388 | virtual wxSize DoGetBestSize() const; |
| 389 | |
| 390 | // common part of Append/Prepend/InsertItem() |
| 391 | // |
| 392 | // pos is the position at which to insert the item or (size_t)-1 to append |
| 393 | // it to the end |
| 394 | virtual wxTreeItemId DoInsertItem(const wxTreeItemId& parent, |
| 395 | size_t pos, |
| 396 | const wxString& text, |
| 397 | int image, int selImage, |
| 398 | wxTreeItemData *data) = 0; |
| 399 | |
| 400 | // and this function implements overloaded InsertItem() taking wxTreeItemId |
| 401 | // (it can't be called InsertItem() as we'd have virtual function hiding |
| 402 | // problem in derived classes then) |
| 403 | virtual wxTreeItemId DoInsertAfter(const wxTreeItemId& parent, |
| 404 | const wxTreeItemId& idPrevious, |
| 405 | const wxString& text, |
| 406 | int image = -1, int selImage = -1, |
| 407 | wxTreeItemData *data = NULL) = 0; |
| 408 | |
| 409 | // real HitTest() implementation: again, can't be called just HitTest() |
| 410 | // because it's overloaded and so the non-virtual overload would be hidden |
| 411 | // (and can't be called DoHitTest() because this is already in wxWindow) |
| 412 | virtual wxTreeItemId DoTreeHitTest(const wxPoint& point, |
| 413 | int& flags) const = 0; |
| 414 | |
| 415 | |
| 416 | wxImageList *m_imageListNormal, // images for tree elements |
| 417 | *m_imageListState; // special images for app defined states |
| 418 | bool m_ownsImageListNormal, |
| 419 | m_ownsImageListState; |
| 420 | |
| 421 | // spacing between left border and the text |
| 422 | unsigned int m_spacing; |
| 423 | |
| 424 | // whether full or quick calculation is done in DoGetBestSize |
| 425 | bool m_quickBestSize; |
| 426 | |
| 427 | |
| 428 | DECLARE_NO_COPY_CLASS(wxTreeCtrlBase) |
| 429 | }; |
| 430 | |
| 431 | // ---------------------------------------------------------------------------- |
| 432 | // include the platform-dependent wxTreeCtrl class |
| 433 | // ---------------------------------------------------------------------------- |
| 434 | |
| 435 | #if defined(__WXUNIVERSAL__) |
| 436 | #include "wx/generic/treectlg.h" |
| 437 | #elif defined(__WXPALMOS__) |
| 438 | #include "wx/palmos/treectrl.h" |
| 439 | #elif defined(__WXMSW__) |
| 440 | #include "wx/msw/treectrl.h" |
| 441 | #elif defined(__WXMOTIF__) |
| 442 | #include "wx/generic/treectlg.h" |
| 443 | #elif defined(__WXGTK__) |
| 444 | #include "wx/generic/treectlg.h" |
| 445 | #elif defined(__WXMAC__) |
| 446 | #include "wx/generic/treectlg.h" |
| 447 | #elif defined(__WXCOCOA__) |
| 448 | #include "wx/generic/treectlg.h" |
| 449 | #elif defined(__WXPM__) |
| 450 | #include "wx/generic/treectlg.h" |
| 451 | #endif |
| 452 | |
| 453 | #endif // wxUSE_TREECTRL |
| 454 | |
| 455 | #endif // _WX_TREECTRL_H_BASE_ |