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: treectrl.h 49563 2007-10-31 20:46:21Z VZ $ 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 27class WXDLLIMPEXP_FWD_CORE wxImageList; 28 29// ---------------------------------------------------------------------------- 30// wxTreeCtrlBase 31// ---------------------------------------------------------------------------- 32 33class WXDLLEXPORT wxTreeCtrlBase : public wxControl 34{ 35public: 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 // get 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#if wxABI_VERSION >= 20801 176 // is the control empty? 177 bool IsEmpty() const; 178#endif // wxABI 2.8.1+ 179 180 181 // number of children 182 // ------------------ 183 184 // if 'recursively' is false, only immediate children count, otherwise 185 // the returned number is the number of all items in this branch 186 virtual size_t GetChildrenCount(const wxTreeItemId& item, 187 bool recursively = true) const = 0; 188 189 // navigation 190 // ---------- 191 192 // wxTreeItemId.IsOk() will return false if there is no such item 193 194 // get the root tree item 195 virtual wxTreeItemId GetRootItem() const = 0; 196 197 // get the item currently selected (may return NULL if no selection) 198 virtual wxTreeItemId GetSelection() const = 0; 199 200 // get the items currently selected, return the number of such item 201 // 202 // NB: this operation is expensive and can take a long time for a 203 // control with a lot of items (~ O(number of items)). 204 virtual size_t GetSelections(wxArrayTreeItemIds& selections) const = 0; 205 206 // get the parent of this item (may return NULL if root) 207 virtual wxTreeItemId GetItemParent(const wxTreeItemId& item) const = 0; 208 209 // for this enumeration function you must pass in a "cookie" parameter 210 // which is opaque for the application but is necessary for the library 211 // to make these functions reentrant (i.e. allow more than one 212 // enumeration on one and the same object simultaneously). Of course, 213 // the "cookie" passed to GetFirstChild() and GetNextChild() should be 214 // the same! 215 216 // get the first child of this item 217 virtual wxTreeItemId GetFirstChild(const wxTreeItemId& item, 218 wxTreeItemIdValue& cookie) const = 0; 219 // get the next child 220 virtual wxTreeItemId GetNextChild(const wxTreeItemId& item, 221 wxTreeItemIdValue& cookie) const = 0; 222 // get the last child of this item - this method doesn't use cookies 223 virtual wxTreeItemId GetLastChild(const wxTreeItemId& item) const = 0; 224 225 // get the next sibling of this item 226 virtual wxTreeItemId GetNextSibling(const wxTreeItemId& item) const = 0; 227 // get the previous sibling 228 virtual wxTreeItemId GetPrevSibling(const wxTreeItemId& item) const = 0; 229 230 // get first visible item 231 virtual wxTreeItemId GetFirstVisibleItem() const = 0; 232 // get the next visible item: item must be visible itself! 233 // see IsVisible() and wxTreeCtrl::GetFirstVisibleItem() 234 virtual wxTreeItemId GetNextVisible(const wxTreeItemId& item) const = 0; 235 // get the previous visible item: item must be visible itself! 236 virtual wxTreeItemId GetPrevVisible(const wxTreeItemId& item) const = 0; 237 238 // operations 239 // ---------- 240 241 // add the root node to the tree 242 virtual wxTreeItemId AddRoot(const wxString& text, 243 int image = -1, int selImage = -1, 244 wxTreeItemData *data = NULL) = 0; 245 246 // insert a new item in as the first child of the parent 247 wxTreeItemId PrependItem(const wxTreeItemId& parent, 248 const wxString& text, 249 int image = -1, int selImage = -1, 250 wxTreeItemData *data = NULL) 251 { 252 return DoInsertItem(parent, 0u, text, image, selImage, data); 253 } 254 255 // insert a new item after a given one 256 wxTreeItemId InsertItem(const wxTreeItemId& parent, 257 const wxTreeItemId& idPrevious, 258 const wxString& text, 259 int image = -1, int selImage = -1, 260 wxTreeItemData *data = NULL) 261 { 262 return DoInsertAfter(parent, idPrevious, text, image, selImage, data); 263 } 264 265 // insert a new item before the one with the given index 266 wxTreeItemId InsertItem(const wxTreeItemId& parent, 267 size_t pos, 268 const wxString& text, 269 int image = -1, int selImage = -1, 270 wxTreeItemData *data = NULL) 271 { 272 return DoInsertItem(parent, pos, text, image, selImage, data); 273 } 274 275 // insert a new item in as the last child of the parent 276 wxTreeItemId AppendItem(const wxTreeItemId& parent, 277 const wxString& text, 278 int image = -1, int selImage = -1, 279 wxTreeItemData *data = NULL) 280 { 281 return DoInsertItem(parent, (size_t)-1, text, image, selImage, data); 282 } 283 284 // delete this item and associated data if any 285 virtual void Delete(const wxTreeItemId& item) = 0; 286 // delete all children (but don't delete the item itself) 287 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events 288 virtual void DeleteChildren(const wxTreeItemId& item) = 0; 289 // delete all items from the tree 290 // NB: this won't send wxEVT_COMMAND_TREE_ITEM_DELETED events 291 virtual void DeleteAllItems() = 0; 292 293 // expand this item 294 virtual void Expand(const wxTreeItemId& item) = 0; 295 // expand the item and all its childs and thats childs 296 void ExpandAllChildren(const wxTreeItemId& item); 297 // expand all items 298 void ExpandAll(); 299 // collapse the item without removing its children 300 virtual void Collapse(const wxTreeItemId& item) = 0; 301#if wxABI_VERSION >= 20801 302 // collapse the item and all its childs and thats childs 303 void CollapseAllChildren(const wxTreeItemId& item); 304 // collapse all items 305 void CollapseAll(); 306#endif // wxABI 2.8.1+ 307 // collapse the item and remove all children 308 virtual void CollapseAndReset(const wxTreeItemId& item) = 0; 309 // toggles the current state 310 virtual void Toggle(const wxTreeItemId& item) = 0; 311 312 // remove the selection from currently selected item (if any) 313 virtual void Unselect() = 0; 314 // unselect all items (only makes sense for multiple selection control) 315 virtual void UnselectAll() = 0; 316 // select this item 317 virtual void SelectItem(const wxTreeItemId& item, bool select = true) = 0; 318 // unselect this item 319 void UnselectItem(const wxTreeItemId& item) { SelectItem(item, false); } 320 // toggle item selection 321 void ToggleItemSelection(const wxTreeItemId& item) 322 { 323 SelectItem(item, !IsSelected(item)); 324 } 325 326 // make sure this item is visible (expanding the parent item and/or 327 // scrolling to this item if necessary) 328 virtual void EnsureVisible(const wxTreeItemId& item) = 0; 329 // scroll to this item (but don't expand its parent) 330 virtual void ScrollTo(const wxTreeItemId& item) = 0; 331 332 // start editing the item label: this (temporarily) replaces the item 333 // with a one line edit control. The item will be selected if it hadn't 334 // been before. textCtrlClass parameter allows you to create an edit 335 // control of arbitrary user-defined class deriving from wxTextCtrl. 336 virtual wxTextCtrl *EditLabel(const wxTreeItemId& item, 337 wxClassInfo* textCtrlClass = CLASSINFO(wxTextCtrl)) = 0; 338 // returns the same pointer as StartEdit() if the item is being edited, 339 // NULL otherwise (it's assumed that no more than one item may be 340 // edited simultaneously) 341 virtual wxTextCtrl *GetEditControl() const = 0; 342 // end editing and accept or discard the changes to item label 343 virtual void EndEditLabel(const wxTreeItemId& item, 344 bool discardChanges = false) = 0; 345 346 // sorting 347 // ------- 348 349 // this function is called to compare 2 items and should return -1, 0 350 // or +1 if the first item is less than, equal to or greater than the 351 // second one. The base class version performs alphabetic comparaison 352 // of item labels (GetText) 353 virtual int OnCompareItems(const wxTreeItemId& item1, 354 const wxTreeItemId& item2) 355 { 356 return wxStrcmp(GetItemText(item1), GetItemText(item2)); 357 } 358 359 // sort the children of this item using OnCompareItems 360 // 361 // NB: this function is not reentrant and not MT-safe (FIXME)! 362 virtual void SortChildren(const wxTreeItemId& item) = 0; 363 364 // items geometry 365 // -------------- 366 367 // determine to which item (if any) belongs the given point (the 368 // coordinates specified are relative to the client area of tree ctrl) 369 // and, in the second variant, fill the flags parameter with a bitmask 370 // of wxTREE_HITTEST_xxx constants. 371 wxTreeItemId HitTest(const wxPoint& point) const 372 { int dummy; return DoTreeHitTest(point, dummy); } 373 wxTreeItemId HitTest(const wxPoint& point, int& flags) const 374 { return DoTreeHitTest(point, flags); } 375 376 // get the bounding rectangle of the item (or of its label only) 377 virtual bool GetBoundingRect(const wxTreeItemId& item, 378 wxRect& rect, 379 bool textOnly = false) const = 0; 380 381 382 // implementation 383 // -------------- 384 385 virtual bool ShouldInheritColours() const { return false; } 386 387 // hint whether to calculate best size quickly or accurately 388 void SetQuickBestSize(bool q) { m_quickBestSize = q; } 389 bool GetQuickBestSize() const { return m_quickBestSize; } 390 391protected: 392 virtual wxSize DoGetBestSize() const; 393 394 // common part of Append/Prepend/InsertItem() 395 // 396 // pos is the position at which to insert the item or (size_t)-1 to append 397 // it to the end 398 virtual wxTreeItemId DoInsertItem(const wxTreeItemId& parent, 399 size_t pos, 400 const wxString& text, 401 int image, int selImage, 402 wxTreeItemData *data) = 0; 403 404 // and this function implements overloaded InsertItem() taking wxTreeItemId 405 // (it can't be called InsertItem() as we'd have virtual function hiding 406 // problem in derived classes then) 407 virtual wxTreeItemId DoInsertAfter(const wxTreeItemId& parent, 408 const wxTreeItemId& idPrevious, 409 const wxString& text, 410 int image = -1, int selImage = -1, 411 wxTreeItemData *data = NULL) = 0; 412 413 // real HitTest() implementation: again, can't be called just HitTest() 414 // because it's overloaded and so the non-virtual overload would be hidden 415 // (and can't be called DoHitTest() because this is already in wxWindow) 416 virtual wxTreeItemId DoTreeHitTest(const wxPoint& point, 417 int& flags) const = 0; 418 419 420 wxImageList *m_imageListNormal, // images for tree elements 421 *m_imageListState; // special images for app defined states 422 bool m_ownsImageListNormal, 423 m_ownsImageListState; 424 425 // spacing between left border and the text 426 unsigned int m_spacing; 427 428 // whether full or quick calculation is done in DoGetBestSize 429 bool m_quickBestSize; 430 431 432 DECLARE_NO_COPY_CLASS(wxTreeCtrlBase) 433}; 434 435// ---------------------------------------------------------------------------- 436// include the platform-dependent wxTreeCtrl class 437// ---------------------------------------------------------------------------- 438 439#if defined(__WXUNIVERSAL__) 440 #include "wx/generic/treectlg.h" 441#elif defined(__WXPALMOS__) 442 #include "wx/palmos/treectrl.h" 443#elif defined(__WXMSW__) 444 #include "wx/msw/treectrl.h" 445#elif defined(__WXMOTIF__) 446 #include "wx/generic/treectlg.h" 447#elif defined(__WXGTK__) 448 #include "wx/generic/treectlg.h" 449#elif defined(__WXMAC__) 450 #include "wx/generic/treectlg.h" 451#elif defined(__WXCOCOA__) 452 #include "wx/generic/treectlg.h" 453#elif defined(__WXPM__) 454 #include "wx/generic/treectlg.h" 455#endif 456 457#endif // wxUSE_TREECTRL 458 459#endif // _WX_TREECTRL_H_BASE_ 460