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