interface/wx/treelist.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        interface/wx/treelist.h
   3 // Purpose:     wxTreeListCtrl class documentation
   4 // Author:      Vadim Zeitlin
   5 // Created:     2011-08-17
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2011 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12     Unique identifier of an item in wxTreeListCtrl.
  13
  14     This is an opaque class which can't be used by the application in any other
  15     way than receiving or passing it to wxTreeListCtrl and checking for
  16     validity.
  17
  18     @see wxTreeListCtrl
  19
  20     @library{wxadv}
  21     @category{ctrl}
  22
  23     @since 2.9.3
  24  */
  25 class wxTreeListItem
  26 {
  27 public:
  28     /**
  29         Only the default constructor is publicly accessible.
  30
  31         Default constructing a wxTreeListItem creates an invalid item.
  32      */
  33     wxTreeListItem();
  34
  35     /**
  36         Return true if the item is valid.
  37      */
  38     bool IsOk() const;
  39 };
  40
  41 /**
  42     Container of multiple items.
  43  */
  44 typedef wxVector<wxTreeListItem> wxTreeListItems;
  45
  46 /**
  47     Special wxTreeListItem value meaning "insert before the first item".
  48
  49     This value can be passed to wxTreeListCtrl::InsertItem() to achieve the
  50     same effect as calling wxTreeListCtrl::PrependItem().
  51  */
  52 extern const wxTreeListItem wxTLI_FIRST;
  53
  54 /**
  55     Special wxTreeListItem value meaning "insert after the last item".
  56
  57     This value can be passed to wxTreeListCtrl::InsertItem() to achieve the
  58     same effect as calling wxTreeListCtrl::AppendItem().
  59  */
  60 extern const wxTreeListItem wxTLI_LAST;
  61
  62 /**
  63     A control combining wxTreeCtrl and wxListCtrl features.
  64
  65     This is a multi-column tree control optionally supporting images and
  66     checkboxes for the items in the first column.
  67
  68     It is currently implemented using wxDataViewCtrl internally but provides a
  69     much simpler interface for the common use case it addresses. Thus, one of
  70     the design principles for this control is simplicity and intentionally
  71     doesn't provide all the features of wxDataViewCtrl. Most importantly, this
  72     class stores all its data internally and doesn't require you to define a
  73     custom model for it.
  74
  75     Instead, this controls works like wxTreeCtrl or non-virtual wxListCtrl and
  76     allows you to simply add items to it using wxTreeListCtrl::AppendItem() and
  77     related methods. Typically, you start by setting up the columns (you must
  78     have at least one) by calling wxTreeListCtrl::AppendColumn() and then add
  79     the items. While only the text of the first column can be specified when
  80     adding them, you can use wxTreeListCtrl::SetItemText() to set the text of
  81     the other columns.
  82
  83
  84     Here are the styles supported by this control. Notice that using
  85     wxTL_USER_3STATE implies wxTL_3STATE and wxTL_3STATE in turn implies
  86     wxTL_CHECKBOX.
  87
  88     @beginStyleTable
  89     @style{wxTL_SINGLE}
  90         Single selection, this is the default.
  91     @style{wxTL_MULTIPLE}
  92         Allow multiple selection, see GetSelections().
  93     @style{wxTL_CHECKBOX}
  94         Show the usual, 2 state, checkboxes for the items in the first column.
  95     @style{wxTL_3STATE}
  96         Show the checkboxes that can possibly be set by the program, but not
  97         the user, to a third, undetermined, state, for the items in the first
  98         column. Implies wxTL_CHECKBOX.
  99     @style{wxTL_USER_3STATE}
 100         Same as wxTL_3STATE but the user can also set the checkboxes to the
 101         undetermined state. Implies wxTL_3STATE.
 102     @style{wxTL_DEFAULT_STYLE}
 103         Style used by the control by default, just wxTL_SINGLE currently.
 104     @endStyleTable
 105
 106     @beginEventTable{wxTreeListEvent}
 107     @event{EVT_TREELIST_SELECTION_CHANGED(id, func)}
 108         Process @c wxEVT_COMMAND_TREELIST_SELECTION_CHANGED event and notifies
 109         about the selection change in the control. In the single selection case
 110         the item indicated by the event has been selected and previously
 111         selected item, if any, was deselected. In multiple selection case, the
 112         selection of this item has just changed (it may have been either
 113         selected or deselected) but notice that the selection of other items
 114         could have changed as well, use wxTreeListCtrl::GetSelections() to
 115         retrieve the new selection if necessary.
 116     @event{EVT_TREELIST_ITEM_EXPANDING(id, func)}
 117         Process @c wxEVT_COMMAND_TREELIST_ITEM_EXPANDING event notifying about
 118         the given branch being expanded. This event is sent before the
 119         expansion occurs and can be vetoed to prevent it from happening.
 120     @event{EVT_TREELIST_ITEM_EXPANDED(id, func)}
 121         Process @c wxEVT_COMMAND_TREELIST_ITEM_EXPANDED event notifying about
 122         the expansion of the given branch. This event is sent after the
 123         expansion occurs and can't be vetoed.
 124     @event{EVT_TREELIST_ITEM_CHECKED(id, func)}
 125         Process @c wxEVT_COMMAND_TREELIST_ITEM_CHeCKED event notifying about
 126         the user checking or unchecking the item. You can use
 127         wxTreeListCtrl::GetCheckedState() to retrieve the new item state and
 128         wxTreeListEvent::GetOldCheckedState() to get the previous one.
 129     @event{EVT_TREELIST_ITEM_ACTIVATED(id, func)}
 130         Process @c wxEVT_COMMAND_TREELIST_ITEM_ACTIVATED event notifying about
 131         the user double clicking the item or activating it from keyboard.
 132     @event{EVT_TREELIST_ITEM_CONTEXT_MENU(id, func)}
 133         Process @c wxEVT_COMMAND_TREELIST_ITEM_CONTEXT_MENU event indicating
 134         that the popup menu for the given item should be displayed.
 135     @endEventTable
 136
 137     @library{wxadv}
 138     @category{ctrl}
 139
 140     @since 2.9.3
 141
 142     @see wxTreeCtrl, wxDataViewCtrl
 143  */
 144 class wxTreeListCtrl : public wxWindow
 145 {
 146 public:
 147     /**
 148         Default constructor, call Create() later.
 149
 150         This constructor is used during two-part construction process when it
 151         is impossible or undesirable to create the window when constructing the
 152         object.
 153      */
 154     wxTreeListCtrl();
 155
 156     /**
 157         Full constructing, creating the object and its window.
 158
 159         See Create() for the parameters description.
 160      */
 161     wxTreeListCtrl(wxWindow* parent,
 162                    wxWindowID id,
 163                    const wxPoint& pos = wxDefaultPosition,
 164                    const wxSize& size = wxDefaultSize,
 165                    long style = wxTL_DEFAULT_STYLE,
 166                    const wxString& name = wxTreeListCtrlNameStr);
 167
 168     /**
 169         Create the control window.
 170
 171         Can be only called for the objects created using the default
 172         constructor and exactly once.
 173
 174         @param parent
 175             The parent window, must be non-NULL.
 176         @param id
 177             The window identifier, may be ::wxID_ANY.
 178         @param pos
 179             The initial window position, usually unused.
 180         @param size
 181             The initial window size, usually unused.
 182         @param style
 183             The window style, see their description in the class documentation.
 184         @param name
 185             The name of the window.
 186      */
 187     bool Create(wxWindow* parent,
 188                 wxWindowID id,
 189                 const wxPoint& pos = wxDefaultPosition,
 190                 const wxSize& size = wxDefaultSize,
 191                 long style = wxTL_DEFAULT_STYLE,
 192                 const wxString& name = wxTreeListCtrlNameStr);
 193
 194
 195     /**
 196         Image list methods.
 197
 198         Like wxTreeCtrl and wxListCtrl this class uses wxImageList so if you
 199         intend to use item icons with it, you must construct wxImageList
 200         containing them first and then specify the indices of the icons in this
 201         image list when adding the items later.
 202      */
 203     //@{
 204
 205     /// A constant indicating that no image should be used for an item.
 206     static const int NO_IMAGE = -1;
 207
 208     /**
 209         Sets the image list and gives its ownership to the control.
 210
 211         The image list assigned with this method will be automatically deleted
 212         by wxTreeCtrl as appropriate (i.e. it takes ownership of the list).
 213
 214         @see SetImageList().
 215     */
 216     void AssignImageList(wxImageList* imageList);
 217
 218     /**
 219         Sets the image list.
 220
 221         The image list assigned with this method will @b not be deleted by the
 222         control itself and you will need to delete it yourself, use
 223         AssignImageList() to give the image list ownership to the control.
 224
 225         @param imageList
 226             Image list to use, may be @NULL to not show any images any more.
 227     */
 228     void SetImageList(wxImageList* imageList);
 229
 230     //@}
 231
 232
 233     /**
 234         Column methods.
 235      */
 236     //@{
 237
 238     /**
 239         Add a column with the given title and attributes.
 240
 241         @param title
 242             The column label.
 243         @param width
 244             The width of the column in pixels or the special
 245             wxCOL_WIDTH_AUTOSIZE value indicating that the column should adjust
 246             to its contents.
 247         @param align
 248             Alignment of both the column header and its items.
 249         @param flags
 250             Column flags, currently can only include wxCOL_RESIZABLE to allow
 251             the user to resize the column.
 252         @return
 253             Index of the new column or -1 on failure.
 254      */
 255     int AppendColumn(const wxString& title,
 256                      int width = wxCOL_WIDTH_AUTOSIZE,
 257                      wxAlignment align = wxALIGN_LEFT,
 258                      int flags = wxCOL_RESIZABLE);
 259
 260     /// Return the total number of columns.
 261     unsigned GetColumnCount() const;
 262
 263     /**
 264         Delete the column with the given index.
 265
 266         @param col
 267             Column index in 0 to GetColumnCount() (exclusive) range.
 268         @return
 269             True if the column was deleted, false if index is invalid or
 270             deleting the column failed for some other reason.
 271      */
 272     bool DeleteColumn(unsigned col);
 273
 274     /**
 275         Delete all columns.
 276
 277         @see DeleteAllItems()
 278      */
 279     void ClearColumns();
 280
 281     /**
 282         Change the width of the given column.
 283
 284         Set column width to either the given value in pixels or to the value
 285         large enough to fit all of the items if width is wxCOL_WIDTH_AUTOSIZE.
 286      */
 287     void SetColumnWidth(unsigned col, int width);
 288
 289     /// Get the current width of the given column in pixels.
 290     int GetColumnWidth(unsigned col) const;
 291
 292     /**
 293         Get the width appropriate for showing the given text.
 294
 295         This is typically used as second argument for AppendColumn() or with
 296         SetColumnWidth().
 297      */
 298     int WidthFor(const wxString& text) const;
 299
 300     //@}
 301
 302
 303     /**
 304         Adding and removing items.
 305
 306         When adding items, the parent and text of the first column of the new item
 307         must always be specified, the rest is optional.
 308
 309         Each item can have two images: one used for closed state and another
 310         for opened one. Only the first one is ever used for the items that
 311         don't have children. And both are not set by default.
 312
 313         It is also possible to associate arbitrary client data pointer with the
 314         new item. It will be deleted by the control when the item is deleted
 315         (either by an explicit DeleteItem() call or because the entire control
 316         is destroyed).
 317      */
 318     //@{
 319
 320     /// Same as InsertItem() with wxTLI_LAST.
 321     wxTreeListItem AppendItem(wxTreeListItem parent,
 322                               const wxString& text,
 323                               int imageClosed = NO_IMAGE,
 324                               int imageOpened = NO_IMAGE,
 325                               wxClientData* data = NULL);
 326
 327     /**
 328         Insert a new item into the tree.
 329
 330         @param parent
 331             The item parent. Must be valid, may be GetRootItem().
 332         @param previous
 333             The previous item that this one should be inserted immediately
 334             after. It must be valid but may be one of the special values
 335             wxTLI_FIRST or wxTLI_LAST indicating that the item should be either
 336             inserted before the first child of its parent (if any) or after the
 337             last one.
 338         @param imageClosed
 339             The normal item image, may be NO_IMAGE to not show any image.
 340         @param imageOpened
 341             The item image shown when it's in the expanded state.
 342         @param data
 343             Optional client data pointer that can be later retrieved using
 344             GetItemData() and will be deleted by the tree when the item itself
 345             is deleted.
 346      */
 347     wxTreeListItem InsertItem(wxTreeListItem parent,
 348                               wxTreeListItem previous,
 349                               const wxString& text,
 350                               int imageClosed = NO_IMAGE,
 351                               int imageOpened = NO_IMAGE,
 352                               wxClientData* data = NULL);
 353
 354     /// Same as InsertItem() with wxTLI_FIRST.
 355     wxTreeListItem PrependItem(wxTreeListItem parent,
 356                                const wxString& text,
 357                                int imageClosed = NO_IMAGE,
 358                                int imageOpened = NO_IMAGE,
 359                                wxClientData* data = NULL);
 360
 361     /// Delete the specified item.
 362     void DeleteItem(wxTreeListItem item);
 363
 364     /// Delete all tree items.
 365     void DeleteAllItems();
 366
 367     //@}
 368
 369
 370     /**
 371         Methods for the tree navigation.
 372
 373         The tree has an invisible root item which is the hidden parent of all
 374         top-level items in the tree. Starting from it it is possible to iterate
 375         over all tree items using GetNextItem().
 376
 377         It is also possible to iterate over just the children of the given item
 378         by using GetFirstChild() to get the first of them and then calling
 379         GetNextSibling() to retrieve all the others.
 380      */
 381     //@{
 382
 383     /// Return the (never shown) root item.
 384     wxTreeListItem GetRootItem() const;
 385
 386     /**
 387         Return the parent of the given item.
 388
 389         All the tree items visible in the tree have valid parent items, only
 390         the never shown root item has no parent.
 391      */
 392     wxTreeListItem GetItemParent(wxTreeListItem item) const;
 393
 394     /**
 395         Return the first child of the given item.
 396
 397         Item may be the root item.
 398
 399         Return value may be invalid if the item doesn't have any children.
 400      */
 401     wxTreeListItem GetFirstChild(wxTreeListItem item) const;
 402
 403     /**
 404         Return the next sibling of the given item.
 405
 406         Return value may be invalid if there are no more siblings.
 407      */
 408     wxTreeListItem GetNextSibling(wxTreeListItem item) const;
 409
 410     /**
 411         Return the first item in the tree.
 412
 413         This is the first child of the root item.
 414
 415         @see GetNextItem()
 416      */
 417     wxTreeListItem GetFirstItem() const;
 418
 419     /**
 420         Get item after the given one in the depth-first tree-traversal order.
 421
 422         Calling this function starting with the result of GetFirstItem() allows
 423         iterating over all items in the tree.
 424
 425         The iteration stops when this function returns an invalid item, i.e.
 426         @code
 427             for ( wxTreeListItem item = tree->GetFirstItem();
 428                   item.IsOk();
 429                   item = tree->GetNextItem(item) )
 430             {
 431                 ... Do something with every tree item ...
 432             }
 433         @endcode
 434      */
 435     wxTreeListItem GetNextItem(wxTreeListItem item) const;
 436
 437     //@}
 438
 439
 440     /**
 441         Items attributes
 442      */
 443     //@{
 444
 445     /**
 446         Return the text of the given item.
 447
 448         By default, returns the text of the first column but any other one can
 449         be specified using @a col argument.
 450      */
 451     const wxString& GetItemText(wxTreeListItem item, unsigned col = 0) const;
 452
 453     /**
 454         Set the text of the specified column of the given item.
 455      */
 456     void SetItemText(wxTreeListItem item, unsigned col, const wxString& text);
 457
 458     /**
 459         Set the text of the first column of the given item.
 460      */
 461     void SetItemText(wxTreeListItem item, const wxString& text);
 462
 463     /**
 464         Set the images for the given item.
 465
 466         See InsertItem() for the images parameters descriptions.
 467      */
 468     void SetItemImage(wxTreeListItem item, int closed, int opened = NO_IMAGE);
 469
 470     /**
 471         Get the data associated with the given item.
 472
 473         The returned pointer may be @NULL.
 474
 475         It must not be deleted by the caller as this will be done by the
 476         control itself.
 477      */
 478     wxClientData* GetItemData(wxTreeListItem item) const;
 479
 480     /**
 481         Set the data associated with the given item.
 482
 483         Previous client data, if any, is deleted when this function is called
 484         so it may be used to delete the current item data object and reset it
 485         by passing @NULL as @a data argument.
 486      */
 487     void SetItemData(wxTreeListItem item, wxClientData* data);
 488
 489     //@}
 490
 491
 492     /**
 493         Expanding and collapsing tree branches.
 494
 495         Notice that calling neither Expand() nor Collapse() method generates
 496         any events.
 497      */
 498     //@{
 499
 500     /**
 501         Expand the given tree branch.
 502      */
 503     void Expand(wxTreeListItem item);
 504
 505     /**
 506         Collapse the given tree branch.
 507      */
 508     void Collapse(wxTreeListItem item);
 509
 510     /**
 511         Return whether the given item is expanded.
 512      */
 513     bool IsExpanded(wxTreeListItem item) const;
 514
 515     //@}
 516
 517
 518     /**
 519         Selection methods.
 520
 521         The behaviour of the control is different in single selection mode (the
 522         default) and multi-selection mode (if @c wxTL_MULTIPLE was specified
 523         when creating it). Not all methods can be used in both modes and some
 524         of those that can don't behave in the same way in two cases.
 525      */
 526     //@{
 527
 528     /**
 529         Return the currently selected item.
 530
 531         This method can't be used with multi-selection controls, use
 532         GetSelections() instead.
 533
 534         The return value may be invalid if no item has been selected yet. Once
 535         an item in a single selection control was selected, it will keep a
 536         valid selection.
 537      */
 538     wxTreeListItem GetSelection() const;
 539
 540     /**
 541         Fill in the provided array with all the selected items.
 542
 543         This method can be used in both single and multi-selection case.
 544
 545         The previous array contents is destroyed.
 546
 547         Returns the number of selected items.
 548      */
 549     unsigned GetSelections(wxTreeListItems& selections) const;
 550
 551     /**
 552         Select the given item.
 553
 554         In single selection mode, deselects any other selected items, in
 555         multi-selection case it adds to the selection.
 556      */
 557     void Select(wxTreeListItem item);
 558
 559     /**
 560         Deselect the given item.
 561
 562         This method can be used in multiple selection mode only.
 563      */
 564     void Unselect(wxTreeListItem item);
 565
 566     /**
 567         Return true if the item is selected.
 568
 569         This method can be used in both single and multiple selection modes.
 570      */
 571     bool IsSelected(wxTreeListItem item) const;
 572
 573     /**
 574         Select all the control items.
 575
 576         Can be only used in multi-selection mode.
 577      */
 578     void SelectAll();
 579
 580     /**
 581         Deselect all the control items.
 582
 583         Can be only used in multi-selection mode.
 584      */
 585     void UnselectAll();
 586
 587     //@}
 588
 589
 590     /**
 591         Checkbox handling
 592
 593         Methods in this section can only be used with the controls created with
 594         wxTL_CHECKBOX style.
 595      */
 596     //@{
 597
 598     /**
 599         Change the item checked state.
 600
 601         @param item
 602             Valid non-root tree item.
 603         @param state
 604             One of wxCHK_CHECKED, wxCHK_UNCHECKED or, for the controls with
 605             wxTL_3STATE or wxTL_USER_3STATE styles, wxCHK_UNDETERMINED.
 606      */
 607     void CheckItem(wxTreeListItem item, wxCheckBoxState state = wxCHK_CHECKED);
 608
 609     /**
 610         Change the checked state of the given item and all its children.
 611
 612         This is the same as CheckItem() but checks or unchecks not only this
 613         item itself but all its children recursively as well.
 614      */
 615     void CheckItemRecursively(wxTreeListItem item,
 616                               wxCheckBoxState state = wxCHK_CHECKED);
 617
 618     /**
 619         Uncheck the given item.
 620
 621         This is synonymous with CheckItem(wxCHK_UNCHECKED).
 622      */
 623     void UncheckItem(wxTreeListItem item);
 624
 625     /**
 626         Update the state of the parent item to reflect the checked state of its
 627         children.
 628
 629         This method updates the parent of this item recursively: if this item
 630         and all its siblings are checked, the parent will become checked as
 631         well. If this item and all its siblings are unchecked, the parent will
 632         be unchecked. And if the siblings of this item are not all in the same
 633         state, the parent will be switched to indeterminate state. And then the
 634         same logic will be applied to the parents parent and so on recursively.
 635
 636         This is typically called when the state of the given item has changed
 637         from EVT_TREELIST_ITEM_CHECKED() handler in the controls which have
 638         wxTL_3STATE flag. Notice that without this flag this function can't
 639         work as it would be unable to set the state of a parent with both
 640         checked and unchecked items so it's only allowed to call it when this
 641         flag is set.
 642      */
 643     void UpdateItemParentStateRecursively(wxTreeListItem item);
 644
 645     /**
 646         Return the checked state of the item.
 647
 648         The return value can be wxCHK_CHECKED, wxCHK_UNCHECKED or
 649         wxCHK_UNDETERMINED.
 650      */
 651     wxCheckBoxState GetCheckedState(wxTreeListItem item) const;
 652
 653     /**
 654         Return true if all children of the given item are in the specified
 655         state.
 656
 657         This is especially useful for the controls with @c wxTL_3STATE style to
 658         allow to decide whether the parent effective state should be the same
 659         @a state, if all its children are in it, or ::wxCHK_UNDETERMINED.
 660
 661         @see UpdateItemParentStateRecursively()
 662      */
 663     bool AreAllChildrenInState(wxTreeListItem item,
 664                                wxCheckBoxState state) const;
 665
 666     //@}
 667 };
 668
 669 /**
 670     Event generated by wxTreeListCtrl.
 671
 672     @since 2.9.3
 673  */
 674 class wxTreeListEvent : public wxNotifyEvent
 675 {
 676 public:
 677     /**
 678         Return the item affected by the event.
 679
 680         This is the item being selected, expanded, checked or activated
 681         (depending on the event type).
 682      */
 683     wxTreeListItem GetItem() const;
 684
 685     /**
 686         Return the previous state of the item checkbox.
 687
 688         This method can be used with @c wxEVT_COMMAND_TREELIST_ITEM_CHeCKED
 689         events only.
 690
 691         Notice that the new state of the item can be retrieved using
 692         wxTreeListCtrl::GetCheckedState().
 693      */
 694     wxCheckBoxState GetOldCheckedState() const;
 695 };
 696
 697
 698 /**
 699     Type of wxTreeListEvent event handlers.
 700
 701     This macro should be used with wxEvtHandler::Connect() when connecting to
 702     wxTreeListCtrl events.
 703  */
 704 #define wxTreeListEventHandler(func) \
 705     wxEVENT_HANDLER_CAST(wxTreeListEventFunction, func)
 706
 707 #endif // _WX_TREELIST_H_