include/wx/treelist.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/treelist.h
   3 // Purpose:     wxTreeListCtrl class declaration.
   4 // Author:      Vadim Zeitlin
   5 // Created:     2011-08-17
   6 // Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
   7 // Licence:     wxWindows licence
   8 ///////////////////////////////////////////////////////////////////////////////
   9
  10 #ifndef _WX_TREELIST_H_
  11 #define _WX_TREELIST_H_
  12
  13 #include "wx/defs.h"
  14
  15 #if wxUSE_TREELISTCTRL
  16
  17 #include "wx/compositewin.h"
  18 #include "wx/containr.h"
  19 #include "wx/headercol.h"
  20 #include "wx/itemid.h"
  21 #include "wx/vector.h"
  22 #include "wx/window.h"
  23 #include "wx/withimages.h"
  24
  25 class WXDLLIMPEXP_FWD_ADV wxDataViewCtrl;
  26 class WXDLLIMPEXP_FWD_ADV wxDataViewEvent;
  27
  28 extern WXDLLIMPEXP_DATA_ADV(const char) wxTreeListCtrlNameStr[];
  29
  30 class wxTreeListCtrl;
  31 class wxTreeListModel;
  32 class wxTreeListModelNode;
  33
  34 // ----------------------------------------------------------------------------
  35 // Constants.
  36 // ----------------------------------------------------------------------------
  37
  38 // wxTreeListCtrl styles.
  39 //
  40 // Notice that using wxTL_USER_3STATE implies wxTL_3STATE and wxTL_3STATE in
  41 // turn implies wxTL_CHECKBOX.
  42 enum
  43 {
  44     wxTL_SINGLE         = 0x0000,       // This is the default anyhow.
  45     wxTL_MULTIPLE       = 0x0001,       // Allow multiple selection.
  46     wxTL_CHECKBOX       = 0x0002,       // Show checkboxes in the first column.
  47     wxTL_3STATE         = 0x0004,       // Allow 3rd state in checkboxes.
  48     wxTL_USER_3STATE    = 0x0008,       // Allow user to set 3rd state.
  49     wxTL_NO_HEADER      = 0x0010,       // Column titles not visible.
  50
  51     wxTL_DEFAULT_STYLE  = wxTL_SINGLE,
  52     wxTL_STYLE_MASK     = wxTL_SINGLE |
  53                           wxTL_MULTIPLE |
  54                           wxTL_CHECKBOX |
  55                           wxTL_3STATE |
  56                           wxTL_USER_3STATE
  57 };
  58
  59 // ----------------------------------------------------------------------------
  60 // wxTreeListItem: unique identifier of an item in wxTreeListCtrl.
  61 // ----------------------------------------------------------------------------
  62
  63 // Make wxTreeListItem a forward-declarable class even though it's simple
  64 // enough to possibly be declared as a simple typedef.
  65 class wxTreeListItem : public wxItemId<wxTreeListModelNode*>
  66 {
  67 public:
  68     wxTreeListItem(wxTreeListModelNode* item = NULL)
  69         : wxItemId<wxTreeListModelNode*>(item)
  70     {
  71     }
  72 };
  73
  74 // Container of multiple items.
  75 typedef wxVector<wxTreeListItem> wxTreeListItems;
  76
  77 // Some special "items" that can be used with InsertItem():
  78 extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_FIRST;
  79 extern WXDLLIMPEXP_DATA_ADV(const wxTreeListItem) wxTLI_LAST;
  80
  81 // ----------------------------------------------------------------------------
  82 // wxTreeListItemComparator: defines order of wxTreeListCtrl items.
  83 // ----------------------------------------------------------------------------
  84
  85 class wxTreeListItemComparator
  86 {
  87 public:
  88     wxTreeListItemComparator() { }
  89
  90     // The comparison function should return negative, null or positive value
  91     // depending on whether the first item is less than, equal to or greater
  92     // than the second one. The items should be compared using their values for
  93     // the given column.
  94     virtual int
  95     Compare(wxTreeListCtrl* treelist,
  96             unsigned column,
  97             wxTreeListItem first,
  98             wxTreeListItem second) = 0;
  99
 100     // Although this class is not used polymorphically by wxWidgets itself,
 101     // provide virtual dtor in case it's used like this in the user code.
 102     virtual ~wxTreeListItemComparator() { }
 103
 104 private:
 105     wxDECLARE_NO_COPY_CLASS(wxTreeListItemComparator);
 106 };
 107
 108 // ----------------------------------------------------------------------------
 109 // wxTreeListCtrl: a control combining wxTree- and wxListCtrl features.
 110 // ----------------------------------------------------------------------------
 111
 112 // This control also provides easy to use high level interface. Although the
 113 // implementation uses wxDataViewCtrl internally, this class is intentionally
 114 // simpler than wxDataViewCtrl and doesn't provide all of its functionality.
 115 //
 116 // If you need extra features you can always use GetDataView() accessor to work
 117 // with wxDataViewCtrl directly but doing this makes your unportable to possible
 118 // future non-wxDataViewCtrl-based implementations of this class.
 119
 120 class WXDLLIMPEXP_ADV wxTreeListCtrl
 121     : public wxCompositeWindow< wxNavigationEnabled<wxWindow> >,
 122       public wxWithImages
 123 {
 124 public:
 125     // Constructors and such
 126     // ---------------------
 127
 128     wxTreeListCtrl() { Init(); }
 129     wxTreeListCtrl(wxWindow* parent,
 130                    wxWindowID id,
 131                    const wxPoint& pos = wxDefaultPosition,
 132                    const wxSize& size = wxDefaultSize,
 133                    long style = wxTL_DEFAULT_STYLE,
 134                    const wxString& name = wxTreeListCtrlNameStr)
 135     {
 136         Init();
 137
 138         Create(parent, id, pos, size, style, name);
 139     }
 140
 141     bool Create(wxWindow* parent,
 142                 wxWindowID id,
 143                 const wxPoint& pos = wxDefaultPosition,
 144                 const wxSize& size = wxDefaultSize,
 145                 long style = wxTL_DEFAULT_STYLE,
 146                 const wxString& name = wxTreeListCtrlNameStr);
 147
 148
 149     virtual ~wxTreeListCtrl();
 150
 151     // Columns methods
 152     // ---------------
 153
 154     // Add a column with the given title and attributes, returns the index of
 155     // the new column or -1 on failure.
 156     int AppendColumn(const wxString& title,
 157                      int width = wxCOL_WIDTH_AUTOSIZE,
 158                      wxAlignment align = wxALIGN_LEFT,
 159                      int flags = wxCOL_RESIZABLE)
 160     {
 161         return DoInsertColumn(title, -1, width, align, flags);
 162     }
 163
 164     // Return the total number of columns.
 165     unsigned GetColumnCount() const;
 166
 167     // Delete the column with the given index, returns false if index is
 168     // invalid or deleting the column failed for some other reason.
 169     bool DeleteColumn(unsigned col);
 170
 171     // Delete all columns.
 172     void ClearColumns();
 173
 174     // Set column width to either the given value in pixels or to the value
 175     // large enough to fit all of the items if width == wxCOL_WIDTH_AUTOSIZE.
 176     void SetColumnWidth(unsigned col, int width);
 177
 178     // Get the current width of the given column in pixels.
 179     int GetColumnWidth(unsigned col) const;
 180
 181     // Get the width appropriate for showing the given text. This is typically
 182     // used as second argument for AppendColumn() or with SetColumnWidth().
 183     int WidthFor(const wxString& text) const;
 184
 185
 186     // Item methods
 187     // ------------
 188
 189     // Adding items. The parent and text of the first column of the new item
 190     // must always be specified, the rest is optional.
 191     //
 192     // Each item can have two images: one used for closed state and another for
 193     // opened one. Only the first one is ever used for the items that don't
 194     // have children. And both are not set by default.
 195     //
 196     // It is also possible to associate arbitrary client data pointer with the
 197     // new item. It will be deleted by the control when the item is deleted
 198     // (either by an explicit DeleteItem() call or because the entire control
 199     // is destroyed).
 200
 201     wxTreeListItem AppendItem(wxTreeListItem parent,
 202                               const wxString& text,
 203                               int imageClosed = NO_IMAGE,
 204                               int imageOpened = NO_IMAGE,
 205                               wxClientData* data = NULL)
 206     {
 207         return DoInsertItem(parent, wxTLI_LAST, text,
 208                             imageClosed, imageOpened, data);
 209     }
 210
 211     wxTreeListItem InsertItem(wxTreeListItem parent,
 212                               wxTreeListItem previous,
 213                               const wxString& text,
 214                               int imageClosed = NO_IMAGE,
 215                               int imageOpened = NO_IMAGE,
 216                               wxClientData* data = NULL)
 217     {
 218         return DoInsertItem(parent, previous, text,
 219                             imageClosed, imageOpened, data);
 220     }
 221
 222     wxTreeListItem PrependItem(wxTreeListItem parent,
 223                                const wxString& text,
 224                                int imageClosed = NO_IMAGE,
 225                                int imageOpened = NO_IMAGE,
 226                                wxClientData* data = NULL)
 227     {
 228         return DoInsertItem(parent, wxTLI_FIRST, text,
 229                             imageClosed, imageOpened, data);
 230     }
 231
 232     // Deleting items.
 233     void DeleteItem(wxTreeListItem item);
 234     void DeleteAllItems();
 235
 236
 237     // Tree navigation
 238     // ---------------
 239
 240     // Return the (never shown) root item.
 241     wxTreeListItem GetRootItem() const;
 242
 243     // The parent item may be invalid for the root-level items.
 244     wxTreeListItem GetItemParent(wxTreeListItem item) const;
 245
 246     // Iterate over the given item children: start by calling GetFirstChild()
 247     // and then call GetNextSibling() for as long as it returns valid item.
 248     wxTreeListItem GetFirstChild(wxTreeListItem item) const;
 249     wxTreeListItem GetNextSibling(wxTreeListItem item) const;
 250
 251     // Return the first child of the root item, which is also the first item of
 252     // the tree in depth-first traversal order.
 253     wxTreeListItem GetFirstItem() const { return GetFirstChild(GetRootItem()); }
 254
 255     // Get item after the given one in the depth-first tree-traversal order.
 256     // Calling this function starting with the result of GetFirstItem() allows
 257     // iterating over all items in the tree.
 258     wxTreeListItem GetNextItem(wxTreeListItem item) const;
 259
 260
 261     // Items attributes
 262     // ----------------
 263
 264     const wxString& GetItemText(wxTreeListItem item, unsigned col = 0) const;
 265
 266     // The convenience overload below sets the text for the first column.
 267     void SetItemText(wxTreeListItem item, unsigned col, const wxString& text);
 268     void SetItemText(wxTreeListItem item, const wxString& text)
 269     {
 270         SetItemText(item, 0, text);
 271     }
 272
 273     // By default the opened image is the same as the normal, closed one (if
 274     // it's used at all).
 275     void SetItemImage(wxTreeListItem item, int closed, int opened = NO_IMAGE);
 276
 277     // Retrieve or set the data associated with the item.
 278     wxClientData* GetItemData(wxTreeListItem item) const;
 279     void SetItemData(wxTreeListItem item, wxClientData* data);
 280
 281
 282     // Expanding and collapsing
 283     // ------------------------
 284
 285     void Expand(wxTreeListItem item);
 286     void Collapse(wxTreeListItem item);
 287     bool IsExpanded(wxTreeListItem item) const;
 288
 289
 290     // Selection handling
 291     // ------------------
 292
 293     // This function can be used with single selection controls, use
 294     // GetSelections() with the multi-selection ones.
 295     wxTreeListItem GetSelection() const;
 296
 297     // This one can be used with either single or multi-selection controls.
 298     unsigned GetSelections(wxTreeListItems& selections) const;
 299
 300     // In single selection mode Select() deselects any other selected items, in
 301     // multi-selection case it adds to the selection.
 302     void Select(wxTreeListItem item);
 303
 304     // Can be used in multiple selection mode only, single selected item in the
 305     // single selection mode can't be unselected.
 306     void Unselect(wxTreeListItem item);
 307
 308     // Return true if the item is selected, can be used in both single and
 309     // multiple selection modes.
 310     bool IsSelected(wxTreeListItem item) const;
 311
 312     // Select or unselect all items, only valid in multiple selection mode.
 313     void SelectAll();
 314     void UnselectAll();
 315
 316
 317     // Checkbox handling
 318     // -----------------
 319
 320     // Methods in this section can only be used with the controls created with
 321     // wxTL_CHECKBOX style.
 322
 323     // Simple set, unset or query the checked state.
 324     void CheckItem(wxTreeListItem item, wxCheckBoxState state = wxCHK_CHECKED);
 325     void UncheckItem(wxTreeListItem item) { CheckItem(item, wxCHK_UNCHECKED); }
 326
 327     // The same but do it recursively for this item itself and its children.
 328     void CheckItemRecursively(wxTreeListItem item,
 329                               wxCheckBoxState state = wxCHK_CHECKED);
 330
 331     // Update the parent of this item recursively: if this item and all its
 332     // siblings are checked, the parent will become checked as well. If this
 333     // item and all its siblings are unchecked, the parent will be unchecked.
 334     // And if the siblings of this item are not all in the same state, the
 335     // parent will be switched to indeterminate state. And then the same logic
 336     // will be applied to the parents parent and so on recursively.
 337     //
 338     // This is typically called when the state of the given item has changed
 339     // from EVT_TREELIST_ITEM_CHECKED() handler in the controls which have
 340     // wxTL_3STATE flag. Notice that without this flag this function can't work
 341     // as it would be unable to set the state of a parent with both checked and
 342     // unchecked items so it's only allowed to call it when this flag is set.
 343     void UpdateItemParentStateRecursively(wxTreeListItem item);
 344
 345     // Return the current state.
 346     wxCheckBoxState GetCheckedState(wxTreeListItem item) const;
 347
 348     // Return true if all item children (if any) are in the given state.
 349     bool AreAllChildrenInState(wxTreeListItem item,
 350                                wxCheckBoxState state) const;
 351
 352
 353
 354     // Sorting.
 355     // --------
 356
 357     // Sort by the given column, either in ascending (default) or descending
 358     // sort order.
 359     //
 360     // By default, simple alphabetical sorting is done by this column contents
 361     // but SetItemComparator() may be called to perform comparison in some
 362     // other way.
 363     void SetSortColumn(unsigned col, bool ascendingOrder = true);
 364
 365     // If the control contents is sorted, return true and fill the output
 366     // parameters with the column which is currently used for sorting and
 367     // whether we sort using ascending or descending order. Otherwise, i.e. if
 368     // the control contents is unsorted, simply return false.
 369     bool GetSortColumn(unsigned* col, bool* ascendingOrder = NULL);
 370
 371     // Set the object to use for comparing the items. It will be called when
 372     // the control is being sorted because the user clicked on a sortable
 373     // column.
 374     //
 375     // The provided pointer is stored by the control so the object it points to
 376     // must have a life-time equal or greater to that of the control itself. In
 377     // addition, the pointer can be NULL to stop using custom comparator and
 378     // revert to the default alphabetical comparison.
 379     void SetItemComparator(wxTreeListItemComparator* comparator);
 380
 381
 382     // View window functions.
 383     // ----------------------
 384
 385     // This control itself is entirely covered by the "view window" which is
 386     // currently a wxDataViewCtrl but if you want to avoid relying on this to
 387     // allow your code to work with later versions which might not be
 388     // wxDataViewCtrl-based, use the first function only and only use the
 389     // second one if you really need to call wxDataViewCtrl methods on it.
 390     wxWindow* GetView() const;
 391     wxDataViewCtrl* GetDataView() const { return m_view; }
 392
 393 private:
 394     // Common part of all ctors.
 395     void Init();
 396
 397     // Pure virtual method inherited from wxCompositeWindow.
 398     virtual wxWindowList GetCompositeWindowParts() const;
 399
 400     // Implementation of AppendColumn().
 401     int DoInsertColumn(const wxString& title,
 402                        int pos,     // May be -1 meaning "append".
 403                        int width,
 404                        wxAlignment align,
 405                        int flags);
 406
 407     // Common part of {Append,Insert,Prepend}Item().
 408     wxTreeListItem DoInsertItem(wxTreeListItem parent,
 409                                 wxTreeListItem previous,
 410                                 const wxString& text,
 411                                 int imageClosed,
 412                                 int imageOpened,
 413                                 wxClientData* data);
 414
 415     // Send wxTreeListEvent corresponding to the given wxDataViewEvent for an
 416     // item (as opposed for column-oriented events).
 417     //
 418     // Also updates the original event "skipped" and "vetoed" flags.
 419     void SendItemEvent(wxEventType evt, wxDataViewEvent& event);
 420
 421     // Send wxTreeListEvent corresponding to the given column wxDataViewEvent.
 422     void SendColumnEvent(wxEventType evt, wxDataViewEvent& event);
 423
 424
 425     // Called by wxTreeListModel when an item is toggled by the user.
 426     void OnItemToggled(wxTreeListItem item, wxCheckBoxState stateOld);
 427
 428     // Event handlers.
 429     void OnSelectionChanged(wxDataViewEvent& event);
 430     void OnItemExpanding(wxDataViewEvent& event);
 431     void OnItemExpanded(wxDataViewEvent& event);
 432     void OnItemActivated(wxDataViewEvent& event);
 433     void OnItemContextMenu(wxDataViewEvent& event);
 434     void OnColumnSorted(wxDataViewEvent& event);
 435     void OnSize(wxSizeEvent& event);
 436
 437     wxDECLARE_EVENT_TABLE();
 438
 439
 440     wxDataViewCtrl* m_view;
 441     wxTreeListModel* m_model;
 442
 443     wxTreeListItemComparator* m_comparator;
 444
 445
 446     // It calls our inherited protected wxWithImages::GetImage() method.
 447     friend class wxTreeListModel;
 448
 449     wxDECLARE_NO_COPY_CLASS(wxTreeListCtrl);
 450 };
 451
 452 // ----------------------------------------------------------------------------
 453 // wxTreeListEvent: event generated by wxTreeListCtrl.
 454 // ----------------------------------------------------------------------------
 455
 456 class WXDLLIMPEXP_ADV wxTreeListEvent : public wxNotifyEvent
 457 {
 458 public:
 459     // Default ctor is provided for wxRTTI needs only but should never be used.
 460     wxTreeListEvent() { Init(); }
 461
 462     // The item affected by the event. Valid for all events except
 463     // column-specific ones such as COLUMN_SORTED.
 464     wxTreeListItem GetItem() const { return m_item; }
 465
 466     // The previous state of the item checkbox for ITEM_CHECKED events only.
 467     wxCheckBoxState GetOldCheckedState() const { return m_oldCheckedState; }
 468
 469     // The index of the column affected by the event. Currently only used by
 470     // COLUMN_SORTED event.
 471     unsigned GetColumn() const { return m_column; }
 472
 473     virtual wxEvent* Clone() const { return new wxTreeListEvent(*this); }
 474
 475 private:
 476     // Common part of all ctors.
 477     void Init()
 478     {
 479         m_column = static_cast<unsigned>(-1);
 480
 481         m_oldCheckedState = wxCHK_UNDETERMINED;
 482     }
 483
 484     // Ctor is private, only wxTreeListCtrl can create events of this type.
 485     wxTreeListEvent(wxEventType evtType,
 486                     wxTreeListCtrl* treelist,
 487                     wxTreeListItem item)
 488         : wxNotifyEvent(evtType, treelist->GetId()),
 489           m_item(item)
 490     {
 491         SetEventObject(treelist);
 492
 493         Init();
 494     }
 495
 496     // Set the checkbox state before this event for ITEM_CHECKED events.
 497     void SetOldCheckedState(wxCheckBoxState state)
 498     {
 499         m_oldCheckedState = state;
 500     }
 501
 502     // Set the column affected by this event for COLUMN_SORTED events.
 503     void SetColumn(unsigned column)
 504     {
 505         m_column = column;
 506     }
 507
 508
 509     const wxTreeListItem m_item;
 510
 511     wxCheckBoxState m_oldCheckedState;
 512
 513     unsigned m_column;
 514
 515     friend class wxTreeListCtrl;
 516
 517     wxDECLARE_DYNAMIC_CLASS_NO_ASSIGN(wxTreeListEvent);
 518 };
 519
 520 // Event types and event table macros.
 521
 522 typedef void (wxEvtHandler::*wxTreeListEventFunction)(wxTreeListEvent&);
 523
 524 #define wxTreeListEventHandler(func) \
 525     wxEVENT_HANDLER_CAST(wxTreeListEventFunction, func)
 526
 527 #define wxEVT_TREELIST_GENERIC(name, id, fn) \
 528     wx__DECLARE_EVT1(wxEVT_TREELIST_##name, id, wxTreeListEventHandler(fn))
 529
 530 #define wxDECLARE_TREELIST_EVENT(name) \
 531     wxDECLARE_EXPORTED_EVENT( WXDLLIMPEXP_ADV, \
 532                               wxEVT_TREELIST_##name, \
 533                               wxTreeListEvent)
 534
 535 wxDECLARE_TREELIST_EVENT(SELECTION_CHANGED);
 536 #define EVT_TREELIST_SELECTION_CHANGED(id, fn) \
 537     wxEVT_TREELIST_GENERIC(SELECTION_CHANGED, id, fn)
 538
 539 wxDECLARE_TREELIST_EVENT(ITEM_EXPANDING);
 540 #define EVT_TREELIST_ITEM_EXPANDING(id, fn) \
 541     wxEVT_TREELIST_GENERIC(ITEM_EXPANDING, id, fn)
 542
 543 wxDECLARE_TREELIST_EVENT(ITEM_EXPANDED);
 544 #define EVT_TREELIST_ITEM_EXPANDED(id, fn) \
 545     wxEVT_TREELIST_GENERIC(ITEM_EXPANDED, id, fn)
 546
 547 wxDECLARE_TREELIST_EVENT(ITEM_CHECKED);
 548 #define EVT_TREELIST_ITEM_CHECKED(id, fn) \
 549     wxEVT_TREELIST_GENERIC(ITEM_CHECKED, id, fn)
 550
 551 wxDECLARE_TREELIST_EVENT(ITEM_ACTIVATED);
 552 #define EVT_TREELIST_ITEM_ACTIVATED(id, fn) \
 553     wxEVT_TREELIST_GENERIC(ITEM_ACTIVATED, id, fn)
 554
 555 wxDECLARE_TREELIST_EVENT(ITEM_CONTEXT_MENU);
 556 #define EVT_TREELIST_ITEM_CONTEXT_MENU(id, fn) \
 557     wxEVT_TREELIST_GENERIC(ITEM_CONTEXT_MENU, id, fn)
 558
 559 wxDECLARE_TREELIST_EVENT(COLUMN_SORTED);
 560 #define EVT_TREELIST_COLUMN_SORTED(id, fn) \
 561     wxEVT_TREELIST_GENERIC(COLUMN_SORTED, id, fn)
 562
 563 #undef wxDECLARE_TREELIST_EVENT
 564
 565 // old wxEVT_COMMAND_* constants
 566 #define wxEVT_COMMAND_TREELIST_SELECTION_CHANGED   wxEVT_TREELIST_SELECTION_CHANGED
 567 #define wxEVT_COMMAND_TREELIST_ITEM_EXPANDING      wxEVT_TREELIST_ITEM_EXPANDING
 568 #define wxEVT_COMMAND_TREELIST_ITEM_EXPANDED       wxEVT_TREELIST_ITEM_EXPANDED
 569 #define wxEVT_COMMAND_TREELIST_ITEM_CHECKED        wxEVT_TREELIST_ITEM_CHECKED
 570 #define wxEVT_COMMAND_TREELIST_ITEM_ACTIVATED      wxEVT_TREELIST_ITEM_ACTIVATED
 571 #define wxEVT_COMMAND_TREELIST_ITEM_CONTEXT_MENU   wxEVT_TREELIST_ITEM_CONTEXT_MENU
 572 #define wxEVT_COMMAND_TREELIST_COLUMN_SORTED       wxEVT_TREELIST_COLUMN_SORTED
 573
 574 #endif // wxUSE_TREELISTCTRL
 575
 576 #endif // _WX_TREELIST_H_