| 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 WXDLLIMPEXP_CORE 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 | // get the items state |
| 122 | int GetItemState(const wxTreeItemId& item) const |
| 123 | { |
| 124 | return DoGetItemState(item); |
| 125 | } |
| 126 | |
| 127 | // modifiers |
| 128 | // --------- |
| 129 | |
| 130 | // set items label |
| 131 | virtual void SetItemText(const wxTreeItemId& item, const wxString& text) = 0; |
| 132 | // set one of the images associated with the item (normal by default) |
| 133 | virtual void SetItemImage(const wxTreeItemId& item, |
| 134 | int image, |
| 135 | wxTreeItemIcon which = wxTreeItemIcon_Normal) = 0; |
| 136 | // associate some data with the item |
| 137 | virtual void SetItemData(const wxTreeItemId& item, wxTreeItemData *data) = 0; |
| 138 | |
| 139 | // force appearance of [+] button near the item. This is useful to |
| 140 | // allow the user to expand the items which don't have any children now |
| 141 | // - but instead add them only when needed, thus minimizing memory |
| 142 | // usage and loading time. |
| 143 | virtual void SetItemHasChildren(const wxTreeItemId& item, |
| 144 | bool has = true) = 0; |
| 145 | |
| 146 | // the item will be shown in bold |
| 147 | virtual void SetItemBold(const wxTreeItemId& item, bool bold = true) = 0; |
| 148 | |
| 149 | // the item will be shown with a drop highlight |
| 150 | virtual void SetItemDropHighlight(const wxTreeItemId& item, |
| 151 | bool highlight = true) = 0; |
| 152 | |
| 153 | // set the items text colour |
| 154 | virtual void SetItemTextColour(const wxTreeItemId& item, |
| 155 | const wxColour& col) = 0; |
| 156 | |
| 157 | // set the items background colour |
| 158 | virtual void SetItemBackgroundColour(const wxTreeItemId& item, |
| 159 | const wxColour& col) = 0; |
| 160 | |
| 161 | // set the items font (should be of the same height for all items) |
| 162 | virtual void SetItemFont(const wxTreeItemId& item, |
| 163 | const wxFont& font) = 0; |
| 164 | |
| 165 | // set the items state (special state values: wxTREE_ITEMSTATE_NONE/NEXT/PREV) |
| 166 | void SetItemState(const wxTreeItemId& item, int state); |
| 167 | |
| 168 | // item status inquiries |
| 169 | // --------------------- |
| 170 | |
| 171 | // is the item visible (it might be outside the view or not expanded)? |
| 172 | virtual bool IsVisible(const wxTreeItemId& item) const = 0; |
| 173 | // does the item has any children? |
| 174 | virtual bool ItemHasChildren(const wxTreeItemId& item) const = 0; |
| 175 | // same as above |
| 176 | bool HasChildren(const wxTreeItemId& item) const |
| 177 | { return ItemHasChildren(item); } |
| 178 | // is the item expanded (only makes sense if HasChildren())? |
| 179 | virtual bool IsExpanded(const wxTreeItemId& item) const = 0; |
| 180 | // is this item currently selected (the same as has focus)? |
| 181 | virtual bool IsSelected(const wxTreeItemId& item) const = 0; |
| 182 | // is item text in bold font? |
| 183 | virtual bool IsBold(const wxTreeItemId& item) const = 0; |
| 184 | // is the control empty? |
| 185 | bool IsEmpty() const; |
| 186 | |
| 187 | |
| 188 | // number of children |
| 189 | // ------------------ |
| 190 | |
| 191 | // if 'recursively' is false, only immediate children count, otherwise |
| 192 | // the returned number is the number of all items in this branch |
| 193 | virtual size_t GetChildrenCount(const wxTreeItemId& item, |
| 194 | bool recursively = true) const = 0; |
| 195 | |
| 196 | // navigation |
| 197 | // ---------- |
| 198 | |
| 199 | // wxTreeItemId.IsOk() will return false if there is no such item |
| 200 | |
| 201 | // get the root tree item |
| 202 | virtual wxTreeItemId GetRootItem() const = 0; |
| 203 | |
| 204 | // get the item currently selected (may return NULL if no selection) |
| 205 | virtual wxTreeItemId GetSelection() const = 0; |
| 206 | |
| 207 | // get the items currently selected, return the number of such item |
| 208 | // |
| 209 | // NB: this operation is expensive and can take a long time for a |
| 210 | // control with a lot of items (~ O(number of items)). |
| 211 | virtual size_t GetSelections(wxArrayTreeItemIds& selections) const = 0; |
| 212 | |
| 213 | // get the last item to be clicked when the control has wxTR_MULTIPLE |
| 214 | // equivalent to GetSelection() if not wxTR_MULTIPLE |
| 215 | virtual wxTreeItemId GetFocusedItem() const = 0; |
| 216 | |
| 217 | |
| 218 | // Clears the currently focused item |
| 219 | virtual void ClearFocusedItem() = 0; |
| 220 | // Sets the currently focused item. Item should be valid |
| 221 | virtual void SetFocusedItem(const wxTreeItemId& item) = 0; |
| 222 | |
| 223 | |
| 224 | // get the parent of this item (may return NULL if root) |
| 225 | virtual wxTreeItemId GetItemParent(const wxTreeItemId& item) const = 0; |
| 226 | |
| 227 | // for this enumeration function you must pass in a "cookie" parameter |
| 228 | // which is opaque for the application but is necessary for the library |
| 229 | // to make these functions reentrant (i.e. allow more than one |
| 230 | // enumeration on one and the same object simultaneously). Of course, |
| 231 | // the "cookie" passed to GetFirstChild() and GetNextChild() should be |
| 232 | // the same! |
| 233 | |
| 234 | // get the first child of this item |
| 235 | virtual wxTreeItemId GetFirstChild(const wxTreeItemId& item, |
| 236 | wxTreeItemIdValue& cookie) const = 0; |
| 237 | // get the next child |
| 238 | virtual wxTreeItemId GetNextChild(const wxTreeItemId& item, |
| 239 | wxTreeItemIdValue& cookie) const = 0; |
| 240 | // get the last child of this item - this method doesn't use cookies |
| 241 | virtual wxTreeItemId GetLastChild(const wxTreeItemId& item) const = 0; |
| 242 | |
| 243 | // get the next sibling of this item |
| 244 | virtual wxTreeItemId GetNextSibling(const wxTreeItemId& item) const = 0; |
| 245 | // get the previous sibling |
| 246 | virtual wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const = 0; |
| 247 | |
| 248 | // get first visible item |
| 249 | virtual wxTreeItemId GetFirstVisibleItem() const = 0; |
| 250 | // get the next visible item: item must be visible itself! |
| 251 | // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem() |
| 252 | virtual wxTreeItemId GetNextVisible(const wxTreeItemId& item) const = 0; |
| 253 | // get the previous visible item: item must be visible itself! |
| 254 | virtual wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const = 0; |
| 255 | |
| 256 | // operations |
| 257 | // ---------- |
| 258 | |
| 259 | // add the root node to the tree |
| 260 | virtual wxTreeItemId AddRoot(const wxString& text, |
| 261 | int image = -1, int selImage = -1, |
| 262 | wxTreeItemData *data = NULL) = 0; |
| 263 | |
| 264 | // insert a new item in as the first child of the parent |
| 265 | wxTreeItemId PrependItem(const wxTreeItemId& parent, |
| 266 | const wxString& text, |
| 267 | int image = -1, int selImage = -1, |
| 268 | wxTreeItemData *data = NULL) |
| 269 | { |
| 270 | return DoInsertItem(parent, 0u, text, image, selImage, data); |
| 271 | } |
| 272 | |
| 273 | // insert a new item after a given one |
| 274 | wxTreeItemId InsertItem(const wxTreeItemId& parent, |
| 275 | const wxTreeItemId& idPrevious, |
| 276 | const wxString& text, |
| 277 | int image = -1, int selImage = -1, |
| 278 | wxTreeItemData *data = NULL) |
| 279 | { |
| 280 | return DoInsertAfter(parent, idPrevious, text, image, selImage, data); |
| 281 | } |
| 282 | |
| 283 | // insert a new item before the one with the given index |
| 284 | wxTreeItemId InsertItem(const wxTreeItemId& parent, |
| 285 | size_t pos, |
| 286 | const wxString& text, |
| 287 | int image = -1, int selImage = -1, |
| 288 | wxTreeItemData *data = NULL) |
| 289 | { |
| 290 | return DoInsertItem(parent, pos, text, image, selImage, data); |
| 291 | } |
| 292 | |
| 293 | // insert a new item in as the last child of the parent |
| 294 | wxTreeItemId AppendItem(const wxTreeItemId& parent, |
| 295 | const wxString& text, |
| 296 | int image = -1, int selImage = -1, |
| 297 | wxTreeItemData *data = NULL) |
| 298 | { |
| 299 | return DoInsertItem(parent, (size_t)-1, text, image, selImage, data); |
| 300 | } |
| 301 | |
| 302 | // delete this item and associated data if any |
| 303 | virtual void Delete(const wxTreeItemId& item) = 0; |
| 304 | // delete all children (but don't delete the item itself) |
| 305 | // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events |
| 306 | virtual void DeleteChildren(const wxTreeItemId& item) = 0; |
| 307 | // delete all items from the tree |
| 308 | // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events |
| 309 | virtual void DeleteAllItems() = 0; |
| 310 | |
| 311 | // expand this item |
| 312 | virtual void Expand(const wxTreeItemId& item) = 0; |
| 313 | // expand the item and all its children recursively |
| 314 | void ExpandAllChildren(const wxTreeItemId& item); |
| 315 | // expand all items |
| 316 | void ExpandAll(); |
| 317 | // collapse the item without removing its children |
| 318 | virtual void Collapse(const wxTreeItemId& item) = 0; |
| 319 | // collapse the item and all its children |
| 320 | void CollapseAllChildren(const wxTreeItemId& item); |
| 321 | // collapse all items |
| 322 | void CollapseAll(); |
| 323 | // collapse the item and remove all children |
| 324 | virtual void CollapseAndReset(const wxTreeItemId& item) = 0; |
| 325 | // toggles the current state |
| 326 | virtual void Toggle(const wxTreeItemId& item) = 0; |
| 327 | |
| 328 | // remove the selection from currently selected item (if any) |
| 329 | virtual void Unselect() = 0; |
| 330 | // unselect all items (only makes sense for multiple selection control) |
| 331 | virtual void UnselectAll() = 0; |
| 332 | // select this item |
| 333 | virtual void SelectItem(const wxTreeItemId& item, bool select = true) = 0; |
| 334 | // selects all (direct) children for given parent (only for |
| 335 | // multiselection controls) |
| 336 | virtual void SelectChildren(const wxTreeItemId& parent) = 0; |
| 337 | // unselect this item |
| 338 | void UnselectItem(const wxTreeItemId& item) { SelectItem(item, false); } |
| 339 | // toggle item selection |
| 340 | void ToggleItemSelection(const wxTreeItemId& item) |
| 341 | { |
| 342 | SelectItem(item, !IsSelected(item)); |
| 343 | } |
| 344 | |
| 345 | // make sure this item is visible (expanding the parent item and/or |
| 346 | // scrolling to this item if necessary) |
| 347 | virtual void EnsureVisible(const wxTreeItemId& item) = 0; |
| 348 | // scroll to this item (but don't expand its parent) |
| 349 | virtual void ScrollTo(const wxTreeItemId& item) = 0; |
| 350 | |
| 351 | // start editing the item label: this (temporarily) replaces the item |
| 352 | // with a one line edit control. The item will be selected if it hadn't |
| 353 | // been before. textCtrlClass parameter allows you to create an edit |
| 354 | // control of arbitrary user-defined class deriving from wxTextCtrl. |
| 355 | virtual wxTextCtrl *EditLabel(const wxTreeItemId& item, |
| 356 | wxClassInfo* textCtrlClass = CLASSINFO(wxTextCtrl)) = 0; |
| 357 | // returns the same pointer as StartEdit() if the item is being edited, |
| 358 | // NULL otherwise (it's assumed that no more than one item may be |
| 359 | // edited simultaneously) |
| 360 | virtual wxTextCtrl *GetEditControl() const = 0; |
| 361 | // end editing and accept or discard the changes to item label |
| 362 | virtual void EndEditLabel(const wxTreeItemId& item, |
| 363 | bool discardChanges = false) = 0; |
| 364 | |
| 365 | // sorting |
| 366 | // ------- |
| 367 | |
| 368 | // this function is called to compare 2 items and should return -1, 0 |
| 369 | // or +1 if the first item is less than, equal to or greater than the |
| 370 | // second one. The base class version performs alphabetic comparaison |
| 371 | // of item labels (GetText) |
| 372 | virtual int OnCompareItems(const wxTreeItemId& item1, |
| 373 | const wxTreeItemId& item2) |
| 374 | { |
| 375 | return wxStrcmp(GetItemText(item1), GetItemText(item2)); |
| 376 | } |
| 377 | |
| 378 | // sort the children of this item using OnCompareItems |
| 379 | // |
| 380 | // NB: this function is not reentrant and not MT-safe (FIXME)! |
| 381 | virtual void SortChildren(const wxTreeItemId& item) = 0; |
| 382 | |
| 383 | // items geometry |
| 384 | // -------------- |
| 385 | |
| 386 | // determine to which item (if any) belongs the given point (the |
| 387 | // coordinates specified are relative to the client area of tree ctrl) |
| 388 | // and, in the second variant, fill the flags parameter with a bitmask |
| 389 | // of wxTREE_HITTEST_xxx constants. |
| 390 | wxTreeItemId HitTest(const wxPoint& point) const |
| 391 | { int dummy; return DoTreeHitTest(point, dummy); } |
| 392 | wxTreeItemId HitTest(const wxPoint& point, int& flags) const |
| 393 | { return DoTreeHitTest(point, flags); } |
| 394 | |
| 395 | // get the bounding rectangle of the item (or of its label only) |
| 396 | virtual bool GetBoundingRect(const wxTreeItemId& item, |
| 397 | wxRect& rect, |
| 398 | bool textOnly = false) const = 0; |
| 399 | |
| 400 | |
| 401 | // implementation |
| 402 | // -------------- |
| 403 | |
| 404 | virtual bool ShouldInheritColours() const { return false; } |
| 405 | |
| 406 | // hint whether to calculate best size quickly or accurately |
| 407 | void SetQuickBestSize(bool q) { m_quickBestSize = q; } |
| 408 | bool GetQuickBestSize() const { return m_quickBestSize; } |
| 409 | |
| 410 | protected: |
| 411 | virtual wxSize DoGetBestSize() const; |
| 412 | |
| 413 | // common part of Get/SetItemState() |
| 414 | virtual int DoGetItemState(const wxTreeItemId& item) const = 0; |
| 415 | virtual void DoSetItemState(const wxTreeItemId& item, int state) = 0; |
| 416 | |
| 417 | // common part of Append/Prepend/InsertItem() |
| 418 | // |
| 419 | // pos is the position at which to insert the item or (size_t)-1 to append |
| 420 | // it to the end |
| 421 | virtual wxTreeItemId DoInsertItem(const wxTreeItemId& parent, |
| 422 | size_t pos, |
| 423 | const wxString& text, |
| 424 | int image, int selImage, |
| 425 | wxTreeItemData *data) = 0; |
| 426 | |
| 427 | // and this function implements overloaded InsertItem() taking wxTreeItemId |
| 428 | // (it can't be called InsertItem() as we'd have virtual function hiding |
| 429 | // problem in derived classes then) |
| 430 | virtual wxTreeItemId DoInsertAfter(const wxTreeItemId& parent, |
| 431 | const wxTreeItemId& idPrevious, |
| 432 | const wxString& text, |
| 433 | int image = -1, int selImage = -1, |
| 434 | wxTreeItemData *data = NULL) = 0; |
| 435 | |
| 436 | // real HitTest() implementation: again, can't be called just HitTest() |
| 437 | // because it's overloaded and so the non-virtual overload would be hidden |
| 438 | // (and can't be called DoHitTest() because this is already in wxWindow) |
| 439 | virtual wxTreeItemId DoTreeHitTest(const wxPoint& point, |
| 440 | int& flags) const = 0; |
| 441 | |
| 442 | |
| 443 | wxImageList *m_imageListNormal, // images for tree elements |
| 444 | *m_imageListState; // special images for app defined states |
| 445 | bool m_ownsImageListNormal, |
| 446 | m_ownsImageListState; |
| 447 | |
| 448 | // spacing between left border and the text |
| 449 | unsigned int m_spacing; |
| 450 | |
| 451 | // whether full or quick calculation is done in DoGetBestSize |
| 452 | bool m_quickBestSize; |
| 453 | |
| 454 | |
| 455 | wxDECLARE_NO_COPY_CLASS(wxTreeCtrlBase); |
| 456 | }; |
| 457 | |
| 458 | // ---------------------------------------------------------------------------- |
| 459 | // include the platform-dependent wxTreeCtrl class |
| 460 | // ---------------------------------------------------------------------------- |
| 461 | |
| 462 | #if defined(__WXUNIVERSAL__) |
| 463 | #include "wx/generic/treectlg.h" |
| 464 | #elif defined(__WXPALMOS__) |
| 465 | #include "wx/generic/treectlg.h" |
| 466 | #elif defined(__WXMSW__) |
| 467 | #include "wx/msw/treectrl.h" |
| 468 | #elif defined(__WXMOTIF__) |
| 469 | #include "wx/generic/treectlg.h" |
| 470 | #elif defined(__WXGTK__) |
| 471 | #include "wx/generic/treectlg.h" |
| 472 | #elif defined(__WXMAC__) |
| 473 | #include "wx/generic/treectlg.h" |
| 474 | #elif defined(__WXCOCOA__) |
| 475 | #include "wx/generic/treectlg.h" |
| 476 | #elif defined(__WXPM__) |
| 477 | #include "wx/generic/treectlg.h" |
| 478 | #endif |
| 479 | |
| 480 | #endif // wxUSE_TREECTRL |
| 481 | |
| 482 | #endif // _WX_TREECTRL_H_BASE_ |