interface/wx/dataview.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dataview.h
   3 // Purpose:     interface of wxDataView* classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxDataViewModel
  12
  13     wxDataViewModel is the base class for all data model to be displayed by a
  14     wxDataViewCtrl.
  15
  16     All other models derive from it and must implement its pure virtual functions
  17     in order to define a complete data model. In detail, you need to override
  18     wxDataViewModel::IsContainer, wxDataViewModel::GetParent, wxDataViewModel::GetChildren,
  19     wxDataViewModel::GetColumnCount, wxDataViewModel::GetColumnType and
  20     wxDataViewModel::GetValue in order to define the data model which acts as an
  21     interface between your actual data and the wxDataViewCtrl.
  22
  23     Note that wxDataViewModel does not define the position or index of any item
  24     in the control because different controls might display the same data differently.
  25     wxDataViewModel does provide a wxDataViewModel::Compare method which the
  26     wxDataViewCtrl may use to sort the data either in conjunction with a column
  27     header or without (see wxDataViewModel::HasDefaultCompare).
  28
  29     wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant
  30     to store data and its type in a generic way. wxVariant can be extended to contain
  31     almost any data without changes to the original class. To a certain extent,
  32     you can use (the somewhat more elegant) wxAny instead of wxVariant as there
  33     is code to convert between the two, but it is unclear what impact this will
  34     have on performance.
  35
  36     Since you will usually allow the wxDataViewCtrl to change your data
  37     through its graphical interface, you will also have to override
  38     wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change
  39     to some data has been committed.
  40
  41     If the data represented by the model is changed by something else than its
  42     associated wxDataViewCtrl, the control has to be notified about the change.
  43     Depending on what happened you need to call one of the following methods:
  44     - wxDataViewModel::ValueChanged,
  45     - wxDataViewModel::ItemAdded,
  46     - wxDataViewModel::ItemDeleted,
  47     - wxDataViewModel::ItemChanged,
  48     - wxDataViewModel::Cleared.
  49
  50     There are plural forms for notification of addition, change or removal of
  51     several item at once. See:
  52     - wxDataViewModel::ItemsAdded,
  53     - wxDataViewModel::ItemsDeleted,
  54     - wxDataViewModel::ItemsChanged.
  55
  56     This class maintains a list of wxDataViewModelNotifier which link this class
  57     to the specific implementations on the supported platforms so that e.g. calling
  58     wxDataViewModel::ValueChanged on this model will just call
  59     wxDataViewModelNotifier::ValueChanged for each notifier that has been added.
  60     You can also add your own notifier in order to get informed about any changes
  61     to the data in the list model.
  62
  63     Currently wxWidgets provides the following models apart from the base model:
  64     wxDataViewIndexListModel, wxDataViewVirtualListModel, wxDataViewTreeStore,
  65     wxDataViewListStore.
  66
  67     Note that wxDataViewModel is reference counted, derives from wxRefCounter
  68     and cannot be deleted directly as it can be shared by several wxDataViewCtrls.
  69     This implies that you need to decrease the reference count after
  70     associating the model with a control like this:
  71
  72     @code
  73         wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY );
  74         wxDataViewModel *musicModel = new MyMusicModel;
  75         m_musicCtrl->AssociateModel( musicModel );
  76         musicModel->DecRef();  // avoid memory leak !!
  77
  78         // add columns now
  79     @endcode
  80
  81     A potentially better way to avoid memory leaks is to use wxObjectDataPtr
  82
  83     @code
  84         wxObjectDataPtr<MyMusicModel> musicModel;
  85
  86         wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY );
  87         musicModel = new MyMusicModel;
  88         m_musicCtrl->AssociateModel( musicModel.get() );
  89
  90         // add columns now
  91     @endcode
  92
  93
  94     @library{wxadv}
  95     @category{dvc}
  96 */
  97 class wxDataViewModel : public wxRefCounter
  98 {
  99 public:
 100     /**
 101         Constructor.
 102     */
 103     wxDataViewModel();
 104
 105     /**
 106         Adds a wxDataViewModelNotifier to the model.
 107     */
 108     void AddNotifier(wxDataViewModelNotifier* notifier);
 109
 110     /**
 111         Change the value of the given item and update the control to reflect
 112         it.
 113
 114         This function simply calls SetValue() and, if it succeeded,
 115         ValueChanged().
 116
 117         @since 2.9.1
 118
 119         @param variant
 120             The new value.
 121         @param item
 122             The item (row) to update.
 123         @param col
 124             The column to update.
 125         @return
 126             @true if both SetValue() and ValueChanged() returned @true.
 127      */
 128     bool ChangeValue(const wxVariant& variant,
 129                      const wxDataViewItem& item,
 130                      unsigned int col);
 131
 132     /**
 133         Called to inform the model that all data has been cleared.
 134         The control will reread the data from the model again.
 135     */
 136     virtual bool Cleared();
 137
 138     /**
 139         The compare function to be used by control. The default compare function
 140         sorts by container and other items separately and in ascending order.
 141         Override this for a different sorting behaviour.
 142
 143         @see HasDefaultCompare().
 144     */
 145     virtual int Compare(const wxDataViewItem& item1,
 146                         const wxDataViewItem& item2,
 147                         unsigned int column,
 148                         bool ascending) const;
 149
 150     /**
 151         Override this to indicate that the item has special font attributes.
 152         This only affects the wxDataViewTextRendererText renderer.
 153
 154         The base class version always simply returns @false.
 155
 156         @see wxDataViewItemAttr.
 157
 158         @param item
 159             The item for which the attribute is requested.
 160         @param col
 161             The column of the item for which the attribute is requested.
 162         @param attr
 163             The attribute to be filled in if the function returns @true.
 164         @return
 165             @true if this item has an attribute or @false otherwise.
 166     */
 167     virtual bool GetAttr(const wxDataViewItem& item, unsigned int col,
 168                          wxDataViewItemAttr& attr) const;
 169
 170     /**
 171         Override this to indicate that the item should be disabled.
 172
 173         Disabled items are displayed differently (e.g. grayed out) and cannot
 174         be interacted with.
 175
 176         The base class version always returns @true, thus making all items
 177         enabled by default.
 178
 179         @param item
 180             The item whose enabled status is requested.
 181         @param col
 182             The column of the item whose enabled status is requested.
 183         @return
 184             @true if this item should be enabled, @false otherwise.
 185
 186         @note Currently disabling items is not supported by the wxOSX/Carbon
 187               implementation.
 188
 189         @since 2.9.2
 190     */
 191     virtual bool IsEnabled(const wxDataViewItem &item,
 192                            unsigned int col) const;
 193
 194     /**
 195         Override this so the control can query the child items of an item.
 196         Returns the number of items.
 197     */
 198     virtual unsigned int GetChildren(const wxDataViewItem& item,
 199                                      wxDataViewItemArray& children) const = 0;
 200
 201     /**
 202         Override this to indicate the number of columns in the model.
 203     */
 204     virtual unsigned int GetColumnCount() const = 0;
 205
 206     /**
 207         Override this to indicate what type of data is stored in the
 208         column specified by @a col.
 209
 210         This should return a string indicating the type of data as reported by wxVariant.
 211     */
 212     virtual wxString GetColumnType(unsigned int col) const = 0;
 213
 214     /**
 215         Override this to indicate which wxDataViewItem representing the parent
 216         of @a item or an invalid wxDataViewItem if the root item is
 217         the parent item.
 218     */
 219     virtual wxDataViewItem GetParent(const wxDataViewItem& item) const = 0;
 220
 221     /**
 222         Override this to indicate the value of @a item.
 223         A wxVariant is used to store the data.
 224     */
 225     virtual void GetValue(wxVariant& variant, const wxDataViewItem& item,
 226                           unsigned int col) const = 0;
 227
 228     /**
 229         Override this method to indicate if a container item merely acts as a
 230         headline (or for categorisation) or if it also acts a normal item with
 231         entries for further columns. By default returns @false.
 232     */
 233     virtual bool HasContainerColumns(const wxDataViewItem& item) const;
 234
 235     /**
 236         Override this to indicate that the model provides a default compare
 237         function that the control should use if no wxDataViewColumn has been
 238         chosen for sorting. Usually, the user clicks on a column header for
 239         sorting, the data will be sorted alphanumerically.
 240
 241         If any other order (e.g. by index or order of appearance) is required,
 242         then this should be used.
 243         See wxDataViewIndexListModel for a model which makes use of this.
 244     */
 245     virtual bool HasDefaultCompare() const;
 246
 247     /**
 248         Return true if there is a value in the given column of this item.
 249
 250         All normal items have values in all columns but the container items
 251         only show their label in the first column (@a col == 0) by default (but
 252         see HasContainerColumns()). So this function always returns true for
 253         the first column while for the other ones it returns true only if the
 254         item is not a container or HasContainerColumns() was overridden to
 255         return true for it.
 256
 257         @since 2.9.1
 258      */
 259     bool HasValue(const wxDataViewItem& item, unsigned col) const;
 260
 261     /**
 262         Override this to indicate of @a item is a container, i.e. if
 263         it can have child items.
 264     */
 265     virtual bool IsContainer(const wxDataViewItem& item) const = 0;
 266
 267     /**
 268         Call this to inform the model that an item has been added to the data.
 269     */
 270     bool ItemAdded(const wxDataViewItem& parent,
 271                            const wxDataViewItem& item);
 272
 273     /**
 274         Call this to inform the model that an item has changed.
 275
 276         This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
 277         event (in which the column fields will not be set) to the user.
 278     */
 279     bool ItemChanged(const wxDataViewItem& item);
 280
 281     /**
 282         Call this to inform the model that an item has been deleted from the data.
 283     */
 284     bool ItemDeleted(const wxDataViewItem& parent,
 285                              const wxDataViewItem& item);
 286
 287     /**
 288         Call this to inform the model that several items have been added to the data.
 289     */
 290     bool ItemsAdded(const wxDataViewItem& parent,
 291                             const wxDataViewItemArray& items);
 292
 293     /**
 294         Call this to inform the model that several items have changed.
 295
 296         This will eventually emit @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
 297         events (in which the column fields will not be set) to the user.
 298     */
 299     bool ItemsChanged(const wxDataViewItemArray& items);
 300
 301     /**
 302         Call this to inform the model that several items have been deleted.
 303     */
 304     bool ItemsDeleted(const wxDataViewItem& parent,
 305                               const wxDataViewItemArray& items);
 306
 307     /**
 308         Remove the @a notifier from the list of notifiers.
 309     */
 310     void RemoveNotifier(wxDataViewModelNotifier* notifier);
 311
 312     /**
 313         Call this to initiate a resort after the sort function has been changed.
 314     */
 315     virtual void Resort();
 316
 317     /**
 318         This gets called in order to set a value in the data model.
 319
 320         The most common scenario is that the wxDataViewCtrl calls this method
 321         after the user changed some data in the view.
 322
 323         This is the function you need to override in your derived class but if
 324         you want to call it, ChangeValue() is usually more convenient as
 325         otherwise you need to manually call ValueChanged() to update the
 326         control itself.
 327     */
 328     virtual bool SetValue(const wxVariant& variant,
 329                           const wxDataViewItem& item,
 330                           unsigned int col) = 0;
 331
 332     /**
 333         Call this to inform this model that a value in the model has been changed.
 334         This is also called from wxDataViewCtrl's internal editing code, e.g. when
 335         editing a text field in the control.
 336
 337         This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
 338         event to the user.
 339     */
 340     virtual bool ValueChanged(const wxDataViewItem& item,
 341                               unsigned int col);
 342
 343 protected:
 344
 345     /**
 346         Destructor. This should not be called directly. Use DecRef() instead.
 347     */
 348     virtual ~wxDataViewModel();
 349 };
 350
 351
 352
 353 /**
 354     @class wxDataViewListModel
 355
 356     Base class with abstract API for wxDataViewIndexListModel and
 357     wxDataViewVirtualListModel.
 358
 359     @library{wxadv}
 360     @category{dvc}
 361 */
 362 class wxDataViewListModel : public wxDataViewModel
 363 {
 364 public:
 365
 366     /**
 367         Destructor.
 368     */
 369     virtual ~wxDataViewIndexListModel();
 370
 371     /**
 372         Compare method that sorts the items by their index.
 373     */
 374     int Compare(const wxDataViewItem& item1,
 375                 const wxDataViewItem& item2,
 376                 unsigned int column, bool ascending);
 377
 378     /**
 379         Override this to indicate that the row has special font attributes.
 380         This only affects the wxDataViewTextRendererText() renderer.
 381
 382         The base class version always simply returns @false.
 383
 384         @see wxDataViewItemAttr.
 385
 386         @param row
 387             The row for which the attribute is requested.
 388         @param col
 389             The column for which the attribute is requested.
 390         @param attr
 391             The attribute to be filled in if the function returns @true.
 392         @return
 393             @true if this item has an attribute or @false otherwise.
 394     */
 395     virtual bool GetAttrByRow(unsigned int row, unsigned int col,
 396                          wxDataViewItemAttr& attr) const;
 397
 398     /**
 399         Override this if you want to disable specific items.
 400
 401         The base class version always returns @true, thus making all items
 402         enabled by default.
 403
 404         @param row
 405             The row of the item whose enabled status is requested.
 406         @param col
 407             The column of the item whose enabled status is requested.
 408         @return
 409             @true if the item at this row and column should be enabled,
 410             @false otherwise.
 411
 412         @note See wxDataViewModel::IsEnabled() for the current status of
 413               support for disabling the items under different platforms.
 414
 415         @since 2.9.2
 416     */
 417     virtual bool IsEnabledByRow(unsigned int row,
 418                                 unsigned int col) const;
 419
 420     /**
 421         Returns the number of items (or rows) in the list.
 422     */
 423     unsigned int GetCount() const;
 424
 425     /**
 426         Returns the wxDataViewItem at the given @e row.
 427     */
 428     wxDataViewItem GetItem(unsigned int row) const;
 429
 430     /**
 431         Returns the position of given @e item.
 432     */
 433     unsigned int GetRow(const wxDataViewItem& item) const;
 434
 435     /**
 436         Override this to allow getting values from the model.
 437     */
 438     virtual void GetValueByRow(wxVariant& variant, unsigned int row,
 439                           unsigned int col) const = 0;
 440
 441     /**
 442         Call this after if the data has to be read again from the model.
 443         This is useful after major changes when calling the methods below
 444         (possibly thousands of times) doesn't make sense.
 445     */
 446     void Reset(unsigned int new_size);
 447
 448     /**
 449         Call this after a row has been appended to the model.
 450     */
 451     void RowAppended();
 452
 453     /**
 454         Call this after a row has been changed.
 455     */
 456     void RowChanged(unsigned int row);
 457
 458     /**
 459         Call this after a row has been deleted.
 460     */
 461     void RowDeleted(unsigned int row);
 462
 463     /**
 464         Call this after a row has been inserted at the given position.
 465     */
 466     void RowInserted(unsigned int before);
 467
 468     /**
 469         Call this after a row has been prepended to the model.
 470     */
 471     void RowPrepended();
 472
 473     /**
 474         Call this after a value has been changed.
 475     */
 476     void RowValueChanged(unsigned int row, unsigned int col);
 477
 478     /**
 479         Call this after rows have been deleted.
 480         The array will internally get copied and sorted in descending order so
 481         that the rows with the highest position will be deleted first.
 482     */
 483     void RowsDeleted(const wxArrayInt& rows);
 484
 485     /**
 486         Called in order to set a value in the model.
 487     */
 488     virtual bool SetValueByRow(const wxVariant& variant, unsigned int row,
 489                           unsigned int col) = 0;
 490 };
 491
 492
 493 /**
 494     @class wxDataViewIndexListModel
 495
 496     wxDataViewIndexListModel is a specialized data model which lets you address
 497     an item by its position (row) rather than its wxDataViewItem (which you can
 498     obtain from this class).
 499     This model also provides its own wxDataViewIndexListModel::Compare
 500     method which sorts the model's data by the index.
 501
 502     This model is not a virtual model since the control stores each wxDataViewItem.
 503     Use wxDataViewVirtualListModel if you need to display millions of items or
 504     have other reason to use a virtual control.
 505
 506     @see wxDataViewListModel for the API.
 507
 508     @library{wxadv}
 509     @category{dvc}
 510 */
 511
 512 class wxDataViewIndexListModel : public wxDataViewListModel
 513 {
 514 public:
 515     /**
 516         Constructor.
 517     */
 518     wxDataViewIndexListModel(unsigned int initial_size = 0);
 519
 520 };
 521
 522 /**
 523     @class wxDataViewVirtualListModel
 524
 525     wxDataViewVirtualListModel is a specialized data model which lets you address
 526     an item by its position (row) rather than its wxDataViewItem and as such offers
 527     the exact same interface as wxDataViewIndexListModel.
 528     The important difference is that under platforms other than OS X, using this
 529     model will result in a truly virtual control able to handle millions of items
 530     as the control doesn't store any item (a feature not supported by OS X).
 531
 532     @see wxDataViewListModel for the API.
 533
 534     @library{wxadv}
 535     @category{dvc}
 536 */
 537
 538 class wxDataViewVirtualListModel : public wxDataViewListModel
 539 {
 540 public:
 541     /**
 542         Constructor.
 543     */
 544     wxDataViewVirtualListModel(unsigned int initial_size = 0);
 545
 546 };
 547
 548
 549
 550 /**
 551     @class wxDataViewItemAttr
 552
 553     This class is used to indicate to a wxDataViewCtrl that a certain item
 554     (see wxDataViewItem) has extra font attributes for its renderer.
 555     For this, it is required to override wxDataViewModel::GetAttr.
 556
 557     Attributes are currently only supported by wxDataViewTextRendererText.
 558
 559     @library{wxadv}
 560     @category{dvc}
 561 */
 562 class wxDataViewItemAttr
 563 {
 564 public:
 565     /**
 566         Constructor.
 567     */
 568     wxDataViewItemAttr();
 569
 570     /**
 571         Call this to indicate that the item shall be displayed in bold text.
 572     */
 573     void SetBold(bool set);
 574
 575     /**
 576         Call this to indicate that the item shall be displayed with that colour.
 577     */
 578     void SetColour(const wxColour& colour);
 579
 580     /**
 581         Call this to set the background colour to use.
 582
 583         Currently this attribute is only supported in the generic version of
 584         wxDataViewCtrl and ignored by the native GTK+ and OS X implementations.
 585
 586         @since 2.9.4
 587     */
 588     void SetBackgroundColour(const wxColour& colour);
 589
 590     /**
 591         Call this to indicate that the item shall be displayed in italic text.
 592     */
 593     void SetItalic(bool set);
 594 };
 595
 596
 597
 598 /**
 599     @class wxDataViewItem
 600
 601     wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl
 602     in a persistent way, i.e. independent of the position of the item in the control
 603     or changes to its contents.
 604
 605     It must hold a unique ID of type @e void* in its only field and can be converted
 606     to and from it.
 607
 608     If the ID is @NULL the wxDataViewItem is invalid and wxDataViewItem::IsOk will
 609     return @false which used in many places in the API of wxDataViewCtrl to
 610     indicate that e.g. no item was found. An ID of @NULL is also used to indicate
 611     the invisible root. Examples for this are wxDataViewModel::GetParent and
 612     wxDataViewModel::GetChildren.
 613
 614     @library{wxadv}
 615     @category{dvc}
 616 */
 617 class wxDataViewItem
 618 {
 619 public:
 620     //@{
 621     /**
 622         Constructor.
 623     */
 624     wxDataViewItem();
 625     wxDataViewItem(const wxDataViewItem& item);
 626     explicit wxDataViewItem(void* id);
 627     //@}
 628
 629     /**
 630         Returns the ID.
 631     */
 632     void* GetID() const;
 633
 634     /**
 635         Returns @true if the ID is not @NULL.
 636     */
 637     bool IsOk() const;
 638 };
 639
 640
 641 // ----------------------------------------------------------------------------
 642 // wxDataViewCtrl flags
 643 // ----------------------------------------------------------------------------
 644
 645 // size of a wxDataViewRenderer without contents:
 646 #define wxDVC_DEFAULT_RENDERER_SIZE     20
 647
 648 // the default width of new (text) columns:
 649 #define wxDVC_DEFAULT_WIDTH             80
 650
 651 // the default width of new toggle columns:
 652 #define wxDVC_TOGGLE_DEFAULT_WIDTH      30
 653
 654 // the default minimal width of the columns:
 655 #define wxDVC_DEFAULT_MINWIDTH          30
 656
 657 // The default alignment of wxDataViewRenderers is to take
 658 // the alignment from the column it owns.
 659 #define wxDVR_DEFAULT_ALIGNMENT         -1
 660
 661 #define wxDV_SINGLE                  0x0000     // for convenience
 662 #define wxDV_MULTIPLE                0x0001     // can select multiple items
 663
 664 #define wxDV_NO_HEADER               0x0002     // column titles not visible
 665 #define wxDV_HORIZ_RULES             0x0004     // light horizontal rules between rows
 666 #define wxDV_VERT_RULES              0x0008     // light vertical rules between columns
 667
 668 #define wxDV_ROW_LINES               0x0010     // alternating colour in rows
 669 #define wxDV_VARIABLE_LINE_HEIGHT    0x0020     // variable line height
 670
 671 // events
 672
 673 wxEventType wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED;
 674
 675 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED;
 676 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING;
 677 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED;
 678 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING;
 679 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED;
 680 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_START_EDITING;
 681 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED;
 682 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE;
 683 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED;
 684
 685 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU;
 686
 687 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICK;
 688 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK;
 689 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED;
 690 wxEventType wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED;
 691 wxEventType wxEVT_COMMAND_DATAVIEW_CACHE_HINT;
 692
 693 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG;
 694 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE;
 695 wxEventType wxEVT_COMMAND_DATAVIEW_ITEM_DROP;
 696
 697 /**
 698     @class wxDataViewCtrl
 699
 700     wxDataViewCtrl is a control to display data either in a tree like fashion or
 701     in a tabular form or both.
 702
 703     If you only need to display a simple tree structure with an API more like the
 704     older wxTreeCtrl class, then the specialized wxDataViewTreeCtrl can be used.
 705     Likewise, if you only want to display simple table structure you can use
 706     the specialized wxDataViewListCtrl class. Both wxDataViewTreeCtrl and
 707     wxDataViewListCtrl can be used without defining  your own wxDataViewModel.
 708
 709     A wxDataViewItem is used to represent a (visible) item in the control.
 710
 711     Unlike wxListCtrl, wxDataViewCtrl doesn't get its data from the user through
 712     virtual functions or by setting it directly. Instead you need to write your own
 713     wxDataViewModel and associate it with this control.
 714     Then you need to add a number of wxDataViewColumn to this control to define
 715     what each column shall display. Each wxDataViewColumn in turn owns 1 instance
 716     of a wxDataViewRenderer to render its cells.
 717
 718     A number of standard renderers for rendering text, dates, images, toggle,
 719     a progress bar etc. are provided. Additionally, the user can write custom
 720     renderers deriving from wxDataViewCustomRenderer for displaying anything.
 721
 722     All data transfer from the control to the model and the user code is done
 723     through wxVariant which can be extended to support more data formats as necessary.
 724     Accordingly, all type information uses the strings returned from wxVariant::GetType.
 725
 726     @beginStyleTable
 727     @style{wxDV_SINGLE}
 728            Single selection mode. This is the default.
 729     @style{wxDV_MULTIPLE}
 730            Multiple selection mode.
 731     @style{wxDV_ROW_LINES}
 732            Use alternating colours for rows if supported by platform and theme.
 733            Currently only supported by the native GTK and OS X implementations
 734            but not by the generic one.
 735     @style{wxDV_HORIZ_RULES}
 736            Display fine rules between row if supported.
 737     @style{wxDV_VERT_RULES}
 738            Display fine rules between columns is supported.
 739     @style{wxDV_VARIABLE_LINE_HEIGHT}
 740            Allow variable line heights.
 741            This can be inefficient when displaying large number of items.
 742     @style{wxDV_NO_HEADER}
 743            Do not show column headers (which are shown by default).
 744     @endStyleTable
 745
 746     @beginEventEmissionTable{wxDataViewEvent}
 747     @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
 748            Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
 749     @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
 750            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
 751     @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)}
 752            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_START_EDITING event. This
 753            event can be vetoed in order to prevent editing on an item by item
 754            basis.
 755     @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
 756            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
 757     @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
 758            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
 759     @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
 760            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
 761     @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
 762            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
 763     @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
 764            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
 765     @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
 766            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
 767     @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
 768            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
 769     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
 770            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event
 771            generated when the user right clicks inside the control. Notice that
 772            this menu is generated even if the click didn't occur on any valid
 773            item, in this case wxDataViewEvent::GetItem() simply returns an
 774            invalid item.
 775     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
 776            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
 777     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
 778            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
 779     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
 780            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
 781     @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
 782            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
 783     @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
 784            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
 785     @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
 786            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
 787     @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
 788            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
 789     @endEventTable
 790
 791     @library{wxadv}
 792     @category{ctrl,dvc}
 793     @appearance{dataviewctrl.png}
 794 */
 795 class wxDataViewCtrl : public wxControl
 796 {
 797 public:
 798     /**
 799         Default Constructor.
 800     */
 801     wxDataViewCtrl();
 802
 803     /**
 804         Constructor. Calls Create().
 805     */
 806     wxDataViewCtrl(wxWindow* parent, wxWindowID id,
 807                    const wxPoint& pos = wxDefaultPosition,
 808                    const wxSize& size = wxDefaultSize,
 809                    long style = 0,
 810                    const wxValidator& validator = wxDefaultValidator,
 811                    const wxString& name = wxDataViewCtrlNameStr);
 812
 813     /**
 814         Destructor.
 815     */
 816     virtual ~wxDataViewCtrl();
 817
 818     /**
 819         Appends a wxDataViewColumn to the control. Returns @true on success.
 820
 821         Note that there is a number of short cut methods which implicitly create
 822         a wxDataViewColumn and a wxDataViewRenderer for it (see below).
 823     */
 824     virtual bool AppendColumn(wxDataViewColumn* col);
 825
 826     /**
 827         Prepends a wxDataViewColumn to the control. Returns @true on success.
 828
 829         Note that there is a number of short cut methods which implicitly create
 830         a wxDataViewColumn and a wxDataViewRenderer for it.
 831     */
 832     virtual bool PrependColumn(wxDataViewColumn* col);
 833
 834     /**
 835         Inserts a wxDataViewColumn to the control. Returns @true on success.
 836     */
 837     virtual bool InsertColumn(unsigned int pos, wxDataViewColumn* col);
 838
 839     //@{
 840     /**
 841         Appends a column for rendering a bitmap. Returns the wxDataViewColumn
 842         created in the function or @NULL on failure.
 843     */
 844     wxDataViewColumn* AppendBitmapColumn(const wxString& label,
 845                                          unsigned int model_column,
 846                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 847                                          int width = -1,
 848                                          wxAlignment align = wxALIGN_CENTER,
 849                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 850     wxDataViewColumn* AppendBitmapColumn(const wxBitmap& label,
 851                                          unsigned int model_column,
 852                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 853                                          int width = -1,
 854                                          wxAlignment align = wxALIGN_CENTER,
 855                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 856     //@}
 857
 858     //@{
 859     /**
 860         Appends a column for rendering a date. Returns the wxDataViewColumn
 861         created in the function or @NULL on failure.
 862
 863         @note The @a align parameter is applied to both the column header and
 864               the column renderer.
 865     */
 866     wxDataViewColumn* AppendDateColumn(const wxString& label,
 867                                        unsigned int model_column,
 868                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
 869                                        int width = -1,
 870                                        wxAlignment align = wxALIGN_NOT,
 871                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 872     wxDataViewColumn* AppendDateColumn(const wxBitmap& label,
 873                                        unsigned int model_column,
 874                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
 875                                        int width = -1,
 876                                        wxAlignment align = wxALIGN_NOT,
 877                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 878     //@}
 879
 880     //@{
 881     /**
 882         Appends a column for rendering text with an icon. Returns the wxDataViewColumn
 883         created in the function or @NULL on failure.
 884         This method uses the wxDataViewIconTextRenderer class.
 885
 886         @note The @a align parameter is applied to both the column header and
 887               the column renderer.
 888     */
 889     wxDataViewColumn* AppendIconTextColumn(const wxString& label,
 890                                            unsigned int model_column,
 891                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 892                                            int width = -1,
 893                                            wxAlignment align = wxALIGN_NOT,
 894                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 895     wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label,
 896                                            unsigned int model_column,
 897                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 898                                            int width = -1,
 899                                            wxAlignment align = wxALIGN_NOT,
 900                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 901     //@}
 902
 903     //@{
 904     /**
 905         Appends a column for rendering a progress indicator. Returns the
 906         wxDataViewColumn created in the function or @NULL on failure.
 907
 908         @note The @a align parameter is applied to both the column header and
 909               the column renderer.
 910     */
 911     wxDataViewColumn* AppendProgressColumn(const wxString& label,
 912                                            unsigned int model_column,
 913                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 914                                            int width = 80,
 915                                            wxAlignment align = wxALIGN_CENTER,
 916                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 917     wxDataViewColumn* AppendProgressColumn(const wxBitmap& label,
 918                                            unsigned int model_column,
 919                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 920                                            int width = 80,
 921                                            wxAlignment align = wxALIGN_CENTER,
 922                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 923     //@}
 924
 925     //@{
 926     /**
 927         Appends a column for rendering text. Returns the wxDataViewColumn
 928         created in the function or @NULL on failure.
 929
 930         @note The @a align parameter is applied to both the column header and
 931               the column renderer.
 932     */
 933     wxDataViewColumn* AppendTextColumn(const wxString& label,
 934                                        unsigned int model_column,
 935                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 936                                        int width = -1,
 937                                        wxAlignment align = wxALIGN_NOT,
 938                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 939     wxDataViewColumn* AppendTextColumn(const wxBitmap& label,
 940                                        unsigned int model_column,
 941                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 942                                        int width = -1,
 943                                        wxAlignment align = wxALIGN_NOT,
 944                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 945     //@}
 946
 947     //@{
 948     /**
 949         Appends a column for rendering a toggle. Returns the wxDataViewColumn
 950         created in the function or @NULL on failure.
 951
 952         @note The @a align parameter is applied to both the column header and
 953               the column renderer.
 954     */
 955     wxDataViewColumn* AppendToggleColumn(const wxString& label,
 956                                          unsigned int model_column,
 957                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 958                                          int width = 30,
 959                                          wxAlignment align = wxALIGN_CENTER,
 960                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 961     wxDataViewColumn* AppendToggleColumn(const wxBitmap& label,
 962                                          unsigned int model_column,
 963                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 964                                          int width = 30,
 965                                          wxAlignment align = wxALIGN_CENTER,
 966                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 967     //@}
 968
 969     /**
 970         Associates a wxDataViewModel with the control.
 971         This increases the reference count of the model by 1.
 972     */
 973     virtual bool AssociateModel(wxDataViewModel* model);
 974
 975     /**
 976         Removes all columns.
 977     */
 978     virtual bool ClearColumns();
 979
 980     /**
 981         Collapses the item.
 982     */
 983     virtual void Collapse(const wxDataViewItem& item);
 984
 985     /**
 986         Create the control. Useful for two step creation.
 987     */
 988     bool Create(wxWindow* parent, wxWindowID id,
 989                 const wxPoint& pos = wxDefaultPosition,
 990                 const wxSize& size = wxDefaultSize,
 991                 long style = 0,
 992                 const wxValidator& validator = wxDefaultValidator,
 993                 const wxString& name = wxDataViewCtrlNameStr);
 994
 995     /**
 996         Deletes given column.
 997     */
 998     virtual bool DeleteColumn(wxDataViewColumn* column);
 999
1000     /**
1001         Programmatically starts editing given cell of @a item.
1002
1003         Doesn't do anything if the item or this column is not editable.
1004
1005         @note Currently not implemented in wxOSX/Carbon.
1006
1007         @since 2.9.4
1008     */
1009     virtual void EditItem(const wxDataViewItem& item, const wxDataViewColumn *column);
1010
1011     /**
1012        Enable drag operations using the given @a format.
1013     */
1014     virtual bool EnableDragSource( const wxDataFormat &format );
1015
1016     /**
1017        Enable drop operations using the given @a format.
1018     */
1019     virtual bool EnableDropTarget( const wxDataFormat &format );
1020
1021     /**
1022         Call this to ensure that the given item is visible.
1023     */
1024     virtual void EnsureVisible(const wxDataViewItem& item,
1025                                const wxDataViewColumn* column = NULL);
1026
1027     /**
1028         Expands the item.
1029     */
1030     virtual void Expand(const wxDataViewItem& item);
1031
1032     /**
1033        Expands all ancestors of the @a item. This method also
1034        ensures that the item itself as well as all ancestor
1035        items have been read from the model by the control.
1036     */
1037     virtual void ExpandAncestors( const wxDataViewItem & item );
1038
1039     /**
1040         Returns pointer to the column. @a pos refers to the position in the
1041         control which may change after reordering columns by the user.
1042     */
1043     virtual wxDataViewColumn* GetColumn(unsigned int pos) const;
1044
1045     /**
1046         Returns the number of columns.
1047     */
1048     virtual unsigned int GetColumnCount() const;
1049
1050     /**
1051         Returns the position of the column or -1 if not found in the control.
1052     */
1053     virtual int GetColumnPosition(const wxDataViewColumn* column) const;
1054
1055     /**
1056         Returns column containing the expanders.
1057     */
1058     wxDataViewColumn* GetExpanderColumn() const;
1059
1060     /**
1061         Returns the currently focused item.
1062
1063         This is the item that the keyboard commands apply to. It may be invalid
1064         if there is no focus currently.
1065
1066         This method is mostly useful for the controls with @c wxDV_MULTIPLE
1067         style as in the case of single selection it returns the same thing as
1068         GetSelection().
1069
1070         Notice that under all platforms except Mac OS X the currently focused
1071         item may be selected or not but under OS X the current item is always
1072         selected.
1073
1074         @see SetCurrentItem(), GetCurrentColumn()
1075
1076         @since 2.9.2
1077      */
1078     wxDataViewItem GetCurrentItem() const;
1079
1080     /**
1081         Returns the column that currently has focus.
1082
1083         If the focus is set to individual cell within the currently focused
1084         item (as opposed to being on the item as a whole), then this is the
1085         column that the focus is on.
1086
1087         Returns NULL if no column currently has focus.
1088
1089         @see GetCurrentItem()
1090
1091         @since 2.9.4
1092      */
1093     wxDataViewColumn *GetCurrentColumn() const;
1094
1095     /**
1096         Returns indentation.
1097     */
1098     int GetIndent() const;
1099
1100     /**
1101         Returns item rectangle.
1102
1103         This method is currently not implemented at all in wxGTK and only
1104         implemented for non-@NULL @a col argument in wxOSX. It is fully
1105         implemented in the generic version of the control.
1106
1107         @param item
1108             A valid item.
1109         @param col
1110             If non-@NULL, the rectangle returned corresponds to the
1111             intersection of the item with the specified column. If @NULL, the
1112             rectangle spans all the columns.
1113     */
1114     virtual wxRect GetItemRect(const wxDataViewItem& item,
1115                                const wxDataViewColumn* col = NULL) const;
1116
1117     /**
1118         Returns pointer to the data model associated with the control (if any).
1119     */
1120     wxDataViewModel* GetModel();
1121
1122     /**
1123         Returns the number of currently selected items.
1124
1125         This method may be called for both the controls with single and
1126         multiple selections and returns the number of selected item, possibly
1127         0, in any case.
1128
1129         @since 2.9.3
1130      */
1131     virtual int GetSelectedItemsCount() const;
1132
1133     /**
1134         Returns first selected item or an invalid item if none is selected.
1135
1136         This method may be called for both the controls with single and
1137         multiple selections but returns an invalid item if more than one item
1138         is selected in the latter case, use HasSelection() to determine if
1139         there are any selected items when using multiple selection.
1140     */
1141     virtual wxDataViewItem GetSelection() const;
1142
1143     /**
1144         Fills @a sel with currently selected items and returns their number.
1145
1146         This method may be called for both the controls with single and
1147         multiple selections. In the single selection case it returns the array
1148         with at most one element in it.
1149
1150         @see GetSelectedItemsCount()
1151     */
1152     virtual int GetSelections(wxDataViewItemArray& sel) const;
1153
1154     /**
1155         Returns the wxDataViewColumn currently responsible for sorting
1156         or @NULL if none has been selected.
1157     */
1158     virtual wxDataViewColumn* GetSortingColumn() const;
1159
1160     /**
1161         Returns true if any items are currently selected.
1162
1163         This method may be called for both the controls with single and
1164         multiple selections.
1165
1166         Calling this method is equivalent to calling GetSelectedItemsCount()
1167         and comparing its result with 0 but is more clear and might also be
1168         implemented more efficiently in the future.
1169
1170         @since 2.9.3
1171      */
1172     bool HasSelection() const;
1173
1174     /**
1175         Hittest.
1176     */
1177     virtual void HitTest(const wxPoint& point, wxDataViewItem& item,
1178                          wxDataViewColumn*& col) const;
1179
1180     /**
1181         Return @true if the item is expanded.
1182     */
1183     virtual bool IsExpanded(const wxDataViewItem& item) const;
1184
1185     /**
1186         Return @true if the item is selected.
1187     */
1188     virtual bool IsSelected(const wxDataViewItem& item) const;
1189
1190     /**
1191         Select the given item.
1192
1193         In single selection mode this changes the (unique) currently selected
1194         item. In multi selection mode, the @a item is selected and the
1195         previously selected items remain selected.
1196     */
1197     virtual void Select(const wxDataViewItem& item);
1198
1199     /**
1200         Select all items.
1201     */
1202     virtual void SelectAll();
1203
1204     /**
1205         Set which column shall contain the tree-like expanders.
1206     */
1207     void SetExpanderColumn(wxDataViewColumn* col);
1208
1209     /**
1210         Changes the currently focused item.
1211
1212         The @a item parameter must be valid, there is no way to remove the
1213         current item from the control.
1214
1215         In single selection mode, calling this method is the same as calling
1216         Select() and is thus not very useful. In multiple selection mode this
1217         method only moves the current item however without changing the
1218         selection except under OS X where the current item is always selected,
1219         so calling SetCurrentItem() selects @a item if it hadn't been selected
1220         before.
1221
1222         @see GetCurrentItem()
1223
1224         @since 2.9.2
1225      */
1226     void SetCurrentItem(const wxDataViewItem& item);
1227
1228     /**
1229         Sets the indentation.
1230     */
1231     void SetIndent(int indent);
1232
1233     /**
1234         Sets the selection to the array of wxDataViewItems.
1235     */
1236     virtual void SetSelections(const wxDataViewItemArray& sel);
1237
1238     /**
1239         Unselect the given item.
1240     */
1241     virtual void Unselect(const wxDataViewItem& item);
1242
1243     /**
1244         Unselect all item.
1245         This method only has effect if multiple selections are allowed.
1246     */
1247     virtual void UnselectAll();
1248
1249     /**
1250         Sets the row height.
1251
1252         This function can only be used when all rows have the same height, i.e.
1253         when wxDV_VARIABLE_LINE_HEIGHT flag is not used.
1254
1255         Currently this is implemented in the generic and native GTK versions
1256         only and nothing is done (and @false returned) when using OS X port.
1257
1258         Also notice that this method can only be used to increase the row
1259         height compared with the default one (as determined by the return value
1260         of wxDataViewRenderer::GetSize()), if it is set to a too small value
1261         then the minimum required by the renderers will be used.
1262
1263         @return @true if the line height was changed or @false otherwise.
1264
1265         @since 2.9.2
1266     */
1267     virtual bool SetRowHeight(int rowHeight);
1268 };
1269
1270
1271
1272 /**
1273     @class wxDataViewModelNotifier
1274
1275     A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors
1276     its notification interface.
1277     See the documentation of that class for further information.
1278
1279     @library{wxadv}
1280     @category{dvc}
1281 */
1282 class wxDataViewModelNotifier
1283 {
1284 public:
1285     /**
1286         Constructor.
1287     */
1288     wxDataViewModelNotifier();
1289
1290     /**
1291         Destructor.
1292     */
1293     virtual ~wxDataViewModelNotifier();
1294
1295     /**
1296         Called by owning model.
1297     */
1298     virtual bool Cleared() = 0;
1299
1300     /**
1301         Get owning wxDataViewModel.
1302     */
1303     wxDataViewModel* GetOwner() const;
1304
1305     /**
1306         Called by owning model.
1307
1308         @return Always return @true from this function in derived classes.
1309     */
1310     virtual bool ItemAdded(const wxDataViewItem& parent,
1311                            const wxDataViewItem& item) = 0;
1312
1313     /**
1314         Called by owning model.
1315
1316         @return Always return @true from this function in derived classes.
1317     */
1318     virtual bool ItemChanged(const wxDataViewItem& item) = 0;
1319
1320     /**
1321         Called by owning model.
1322
1323         @return Always return @true from this function in derived classes.
1324     */
1325     virtual bool ItemDeleted(const wxDataViewItem& parent,
1326                              const wxDataViewItem& item) = 0;
1327
1328     /**
1329         Called by owning model.
1330
1331         @return Always return @true from this function in derived classes.
1332     */
1333     virtual bool ItemsAdded(const wxDataViewItem& parent,
1334                             const wxDataViewItemArray& items);
1335
1336     /**
1337         Called by owning model.
1338
1339         @return Always return @true from this function in derived classes.
1340     */
1341     virtual bool ItemsChanged(const wxDataViewItemArray& items);
1342
1343     /**
1344         Called by owning model.
1345
1346         @return Always return @true from this function in derived classes.
1347     */
1348     virtual bool ItemsDeleted(const wxDataViewItem& parent,
1349                               const wxDataViewItemArray& items);
1350
1351     /**
1352         Called by owning model.
1353     */
1354     virtual void Resort() = 0;
1355
1356     /**
1357         Set owner of this notifier. Used internally.
1358     */
1359     void SetOwner(wxDataViewModel* owner);
1360
1361     /**
1362         Called by owning model.
1363
1364         @return Always return @true from this function in derived classes.
1365     */
1366     virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0;
1367 };
1368
1369
1370 /**
1371     The mode of a data-view cell; see wxDataViewRenderer for more info.
1372 */
1373 enum wxDataViewCellMode
1374 {
1375     /**
1376         The cell only displays information and cannot be manipulated or
1377         otherwise interacted with in any way.
1378
1379         Note that this doesn't mean that the row being drawn can't be selected,
1380         just that a particular element of it cannot be individually modified.
1381      */
1382     wxDATAVIEW_CELL_INERT,
1383
1384     /**
1385         Indicates that the cell can be @em activated by clicking it or using
1386         keyboard.
1387
1388         Activating a cell is an alternative to showing inline editor when the
1389         value can be edited in a simple way that doesn't warrant full editor
1390         control. The most typical use of cell activation is toggling the
1391         checkbox in wxDataViewToggleRenderer; others would be e.g. an embedded
1392         volume slider or a five-star rating column.
1393
1394         The exact means of activating a cell are platform-dependent, but they
1395         are usually similar to those used for inline editing of values.
1396         Typically, a cell would be activated by Space or Enter keys or by left
1397         mouse click.
1398
1399         @note Do not confuse this with item activation in wxDataViewCtrl
1400               and the wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. That one is
1401               used for activating the item (or, to put it differently, the
1402               entire row) similarly to analogous messages in wxTreeCtrl and
1403               wxListCtrl, and the effect differs (play a song, open a file
1404               etc.). Cell activation, on the other hand, is all about
1405               interacting with the individual cell.
1406
1407         @see wxDataViewCustomRenderer::ActivateCell()
1408     */
1409     wxDATAVIEW_CELL_ACTIVATABLE,
1410
1411     /**
1412         Indicates that the user can edit the data in-place in an inline editor
1413         control that will show up when the user wants to edit the cell.
1414
1415         A typical example of this behaviour is changing the filename in a file
1416         managers.
1417
1418         Editing is typically triggered by slowly double-clicking the cell or by
1419         a platform-dependent keyboard shortcut (F2 is typical on Windows, Space
1420         and/or Enter is common elsewhere and supported on Windows too).
1421
1422         @see wxDataViewCustomRenderer::CreateEditorCtrl()
1423     */
1424     wxDATAVIEW_CELL_EDITABLE
1425 };
1426
1427 /**
1428     The values of this enum controls how a wxDataViewRenderer should display
1429     its contents in a cell.
1430 */
1431 enum wxDataViewCellRenderState
1432 {
1433     wxDATAVIEW_CELL_SELECTED    = 1,
1434     wxDATAVIEW_CELL_PRELIT      = 2,
1435     wxDATAVIEW_CELL_INSENSITIVE = 4,
1436     wxDATAVIEW_CELL_FOCUSED     = 8
1437 };
1438
1439 /**
1440     @class wxDataViewRenderer
1441
1442     This class is used by wxDataViewCtrl to render the individual cells.
1443     One instance of a renderer class is owned by a wxDataViewColumn.
1444     There is a number of ready-to-use renderers provided:
1445     - wxDataViewTextRenderer,
1446     - wxDataViewIconTextRenderer,
1447     - wxDataViewToggleRenderer,
1448     - wxDataViewProgressRenderer,
1449     - wxDataViewBitmapRenderer,
1450     - wxDataViewDateRenderer,
1451     - wxDataViewSpinRenderer.
1452     - wxDataViewChoiceRenderer.
1453
1454     Additionally, the user can write own renderers by deriving from
1455     wxDataViewCustomRenderer.
1456
1457     The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1458     by the constructors respectively controls what actions the cell data allows
1459     and how the renderer should display its contents in a cell.
1460
1461     @library{wxadv}
1462     @category{dvc}
1463 */
1464 class wxDataViewRenderer : public wxObject
1465 {
1466 public:
1467     /**
1468         Constructor.
1469     */
1470     wxDataViewRenderer(const wxString& varianttype,
1471                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1472                        int align = wxDVR_DEFAULT_ALIGNMENT );
1473
1474     /**
1475         Enable or disable replacing parts of the item text with ellipsis to
1476         make it fit the column width.
1477
1478         This method only makes sense for the renderers working with text, such
1479         as wxDataViewTextRenderer or wxDataViewIconTextRenderer.
1480
1481         By default wxELLIPSIZE_MIDDLE is used.
1482
1483         @param mode
1484             Ellipsization mode, use wxELLIPSIZE_NONE to disable.
1485
1486         @since 2.9.1
1487      */
1488     void EnableEllipsize(wxEllipsizeMode mode = wxELLIPSIZE_MIDDLE);
1489
1490     /**
1491         Disable replacing parts of the item text with ellipsis.
1492
1493         If ellipsizing is disabled, the string will be truncated if it doesn't
1494         fit.
1495
1496         This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode.
1497
1498         @since 2.9.1
1499      */
1500     void DisableEllipsize();
1501
1502     /**
1503         Returns the alignment. See SetAlignment()
1504     */
1505     virtual int GetAlignment() const;
1506
1507     /**
1508         Returns the ellipsize mode used by the renderer.
1509
1510         If the return value is wxELLIPSIZE_NONE, the text is simply truncated
1511         if it doesn't fit.
1512
1513         @see EnableEllipsize()
1514      */
1515     wxEllipsizeMode GetEllipsizeMode() const;
1516
1517     /**
1518         Returns the cell mode.
1519     */
1520     virtual wxDataViewCellMode GetMode() const;
1521
1522     /**
1523         Returns pointer to the owning wxDataViewColumn.
1524     */
1525     wxDataViewColumn* GetOwner() const;
1526
1527     /**
1528         This methods retrieves the value from the renderer in order to
1529         transfer the value back to the data model.
1530
1531         Returns @false on failure.
1532     */
1533     virtual bool GetValue(wxVariant& value) const = 0;
1534
1535     /**
1536         Returns a string with the type of the wxVariant supported by this renderer.
1537     */
1538     wxString GetVariantType() const;
1539
1540     /**
1541         Sets the alignment of the renderer's content.
1542         The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1543         should have the same alignment as the column header.
1544
1545         The method is not implemented under OS X and the renderer always aligns
1546         its contents as the column header on that platform. The other platforms
1547         support both vertical and horizontal alignment.
1548     */
1549     virtual void SetAlignment( int align );
1550     /**
1551         Sets the owning wxDataViewColumn.
1552         This is usually called from within wxDataViewColumn.
1553     */
1554     void SetOwner(wxDataViewColumn* owner);
1555
1556     /**
1557         Set the value of the renderer (and thus its cell) to @a value.
1558         The internal code will then render this cell with this data.
1559     */
1560     virtual bool SetValue(const wxVariant& value) = 0;
1561
1562     /**
1563         Before data is committed to the data model, it is passed to this
1564         method where it can be checked for validity. This can also be
1565         used for checking a valid range or limiting the user input in
1566         a certain aspect (e.g. max number of characters or only alphanumeric
1567         input, ASCII only etc.). Return @false if the value is not valid.
1568
1569         Please note that due to implementation limitations, this validation
1570         is done after the editing control already is destroyed and the
1571         editing process finished.
1572     */
1573     virtual bool Validate(wxVariant& value);
1574 };
1575
1576
1577
1578 /**
1579     @class wxDataViewTextRenderer
1580
1581     wxDataViewTextRenderer is used for rendering text.
1582     It supports in-place editing if desired.
1583
1584     @library{wxadv}
1585     @category{dvc}
1586 */
1587 class wxDataViewTextRenderer : public wxDataViewRenderer
1588 {
1589 public:
1590     /**
1591         The ctor.
1592     */
1593     wxDataViewTextRenderer(const wxString& varianttype = "string",
1594                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1595                            int align = wxDVR_DEFAULT_ALIGNMENT );
1596 };
1597
1598
1599
1600 /**
1601     @class wxDataViewIconTextRenderer
1602
1603     The wxDataViewIconTextRenderer class is used to display text with
1604     a small icon next to it as it is typically done in a file manager.
1605
1606     This classes uses the wxDataViewIconText helper class to store its data.
1607     wxDataViewIconText can be converted to and from a wxVariant using the left
1608     shift operator.
1609
1610     @library{wxadv}
1611     @category{dvc}
1612 */
1613 class wxDataViewIconTextRenderer : public wxDataViewRenderer
1614 {
1615 public:
1616     /**
1617         The ctor.
1618     */
1619     wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
1620                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1621                                int align = wxDVR_DEFAULT_ALIGNMENT );
1622 };
1623
1624
1625
1626 /**
1627     @class wxDataViewProgressRenderer
1628
1629     This class is used by wxDataViewCtrl to render progress bars.
1630
1631     @library{wxadv}
1632     @category{dvc}
1633 */
1634 class wxDataViewProgressRenderer : public wxDataViewRenderer
1635 {
1636 public:
1637     /**
1638         The ctor.
1639     */
1640     wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
1641                                const wxString& varianttype = "long",
1642                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1643                                int align = wxDVR_DEFAULT_ALIGNMENT );
1644 };
1645
1646
1647
1648 /**
1649     @class wxDataViewSpinRenderer
1650
1651     This is a specialized renderer for rendering integer values.
1652     It supports modifying the values in-place by using a wxSpinCtrl.
1653     The renderer only support variants of type @e long.
1654
1655     @library{wxadv}
1656     @category{dvc}
1657 */
1658 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
1659 {
1660 public:
1661     /**
1662         Constructor.
1663         @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1664     */
1665     wxDataViewSpinRenderer(int min, int max,
1666                            wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1667                            int align = wxDVR_DEFAULT_ALIGNMENT);
1668 };
1669
1670
1671
1672 /**
1673     @class wxDataViewToggleRenderer
1674
1675     This class is used by wxDataViewCtrl to render toggle controls.
1676
1677     @library{wxadv}
1678     @category{dvc}
1679 */
1680 class wxDataViewToggleRenderer : public wxDataViewRenderer
1681 {
1682 public:
1683     /**
1684         The ctor.
1685     */
1686     wxDataViewToggleRenderer(const wxString& varianttype = "bool",
1687                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1688                              int align = wxDVR_DEFAULT_ALIGNMENT);
1689 };
1690
1691
1692 /**
1693     @class wxDataViewChoiceRenderer
1694
1695     This class is used by wxDataViewCtrl to render choice controls.
1696     It stores a string so that SetValue() and GetValue() operate
1697     on a variant holding a string.
1698
1699     @library{wxadv}
1700     @category{dvc}
1701 */
1702
1703 class wxDataViewChoiceRenderer: public wxDataViewRenderer
1704 {
1705 public:
1706     /**
1707         The ctor.
1708     */
1709     wxDataViewChoiceRenderer( const wxArrayString &choices,
1710                               wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1711                               int alignment = wxDVR_DEFAULT_ALIGNMENT );
1712
1713     /**
1714         Returns the choice referred to by index.
1715     */
1716     wxString GetChoice(size_t index) const;
1717
1718     /**
1719         Returns all choices.
1720     */
1721     const wxArrayString& GetChoices() const;
1722 };
1723
1724
1725 /**
1726     @class wxDataViewDateRenderer
1727
1728     This class is used by wxDataViewCtrl to render calendar controls.
1729
1730     @library{wxadv}
1731     @category{dvc}
1732 */
1733 class wxDataViewDateRenderer : public wxDataViewRenderer
1734 {
1735 public:
1736     /**
1737         The ctor.
1738     */
1739     wxDataViewDateRenderer(const wxString& varianttype = "datetime",
1740                            wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1741                            int align = wxDVR_DEFAULT_ALIGNMENT);
1742 };
1743
1744
1745
1746 /**
1747     @class wxDataViewCustomRenderer
1748
1749     You need to derive a new class from wxDataViewCustomRenderer in
1750     order to write a new renderer.
1751
1752     You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
1753     wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
1754
1755     If you want your renderer to support in-place editing then you also need to override
1756     wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
1757     and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1758
1759     Note that a special event handler will be pushed onto that editor control
1760     which handles @e \<ENTER\> and focus out events in order to end the editing.
1761
1762     @library{wxadv}
1763     @category{dvc}
1764 */
1765 class wxDataViewCustomRenderer : public wxDataViewRenderer
1766 {
1767 public:
1768     /**
1769         Constructor.
1770     */
1771     wxDataViewCustomRenderer(const wxString& varianttype = "string",
1772                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1773                              int align = -1, bool no_init = false);
1774
1775     /**
1776         Destructor.
1777     */
1778     virtual ~wxDataViewCustomRenderer();
1779
1780     /**
1781         Override this to react to cell @em activation. Activating a cell is an
1782         alternative to showing inline editor when the value can be edited in a
1783         simple way that doesn't warrant full editor control. The most typical
1784         use of cell activation is toggling the checkbox in
1785         wxDataViewToggleRenderer; others would be e.g. an embedded volume
1786         slider or a five-star rating column.
1787
1788         The exact means of activating a cell are platform-dependent, but they
1789         are usually similar to those used for inline editing of values.
1790         Typically, a cell would be activated by Space or Enter keys or by left
1791         mouse click.
1792
1793         This method will only be called if the cell has the
1794         wxDATAVIEW_CELL_ACTIVATABLE mode.
1795
1796         @param cell
1797             Coordinates of the activated cell's area.
1798         @param model
1799             The model to manipulate in response.
1800         @param item
1801             Activated item.
1802         @param col
1803             Activated column of @a item.
1804         @param mouseEvent
1805             If the activation was triggered by mouse click, contains the
1806             corresponding event. Is @NULL otherwise (for keyboard activation).
1807             Mouse coordinates are adjusted to be relative to the cell.
1808
1809         @since 2.9.3
1810
1811         @note Do not confuse this method with item activation in wxDataViewCtrl
1812               and the wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event. That one is
1813               used for activating the item (or, to put it differently, the
1814               entire row) similarly to analogous messages in wxTreeCtrl and
1815               wxListCtrl, and the effect differs (play a song, open a file
1816               etc.). Cell activation, on the other hand, is all about
1817               interacting with the individual cell.
1818
1819         @see CreateEditorCtrl()
1820     */
1821     virtual bool ActivateCell(const wxRect& cell,
1822                               wxDataViewModel* model,
1823                               const wxDataViewItem & item,
1824                               unsigned int col,
1825                               const wxMouseEvent *mouseEvent);
1826
1827     /**
1828         Override this to create the actual editor control once editing
1829         is about to start.
1830
1831         This method will only be called if the cell has the
1832         wxDATAVIEW_CELL_EDITABLE mode. Editing is typically triggered by slowly
1833         double-clicking the cell or by a platform-dependent keyboard shortcut
1834         (F2 is typical on Windows, Space and/or Enter is common elsewhere and
1835         supported on Windows too).
1836
1837         @param parent
1838             The parent of the editor control.
1839         @param labelRect
1840             Indicates the position and size of the editor control. The control
1841             should be created in place of the cell and @a labelRect should be
1842             respected as much as possible.
1843         @param value
1844             Initial value of the editor.
1845
1846         An example:
1847         @code
1848         {
1849             long l = value;
1850             return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
1851                         labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
1852         }
1853         @endcode
1854
1855         @see ActivateCell()
1856     */
1857     virtual wxWindow* CreateEditorCtrl(wxWindow* parent,
1858                                        wxRect labelRect,
1859                                        const wxVariant& value);
1860
1861     /**
1862         Return the attribute to be used for rendering.
1863
1864         This function may be called from Render() implementation to use the
1865         attributes defined for the item if the renderer supports them.
1866
1867         Notice that when Render() is called, the wxDC object passed to it is
1868         already set up to use the correct attributes (e.g. its font is set to
1869         bold or italic version if wxDataViewItemAttr::GetBold() or GetItalic()
1870         returns true) so it may not be necessary to call it explicitly if you
1871         only want to render text using the items attributes.
1872
1873         @since 2.9.1
1874      */
1875     const wxDataViewItemAttr& GetAttr() const;
1876
1877     /**
1878         Return size required to show content.
1879     */
1880     virtual wxSize GetSize() const = 0;
1881
1882     /**
1883         Override this so that the renderer can get the value from the editor
1884         control (pointed to by @a editor):
1885         @code
1886         {
1887             wxSpinCtrl *sc = (wxSpinCtrl*) editor;
1888             long l = sc->GetValue();
1889             value = l;
1890             return true;
1891         }
1892         @endcode
1893     */
1894     virtual bool GetValueFromEditorCtrl(wxWindow* editor,
1895                                         wxVariant& value);
1896
1897     /**
1898         Override this and make it return @true in order to
1899         indicate that this renderer supports in-place editing.
1900     */
1901     virtual bool HasEditorCtrl() const;
1902
1903     /**
1904         Override this to react to a left click.
1905         This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
1906     */
1907     virtual bool LeftClick( const wxPoint& cursor,
1908                             const wxRect& cell,
1909                             wxDataViewModel * model,
1910                             const wxDataViewItem & item,
1911                             unsigned int col );
1912
1913     /**
1914         Override this to render the cell.
1915         Before this is called, wxDataViewRenderer::SetValue was called
1916         so that this instance knows what to render.
1917     */
1918     virtual bool Render(wxRect cell, wxDC* dc, int state) = 0;
1919
1920     /**
1921         This method should be called from within Render() whenever you need to
1922         render simple text.
1923         This will ensure that the correct colour, font and vertical alignment will
1924         be chosen so the text will look the same as text drawn by native renderers.
1925     */
1926     void RenderText(const wxString& text, int xoffset, wxRect cell,
1927                     wxDC* dc, int state);
1928
1929     /**
1930         Override this to start a drag operation. Not yet supported.
1931     */
1932     virtual bool StartDrag(const wxPoint& cursor,
1933                            const wxRect& cell,
1934                            wxDataViewModel* model,
1935                            const wxDataViewItem & item,
1936                            unsigned int col);
1937 };
1938
1939
1940
1941 /**
1942     @class wxDataViewBitmapRenderer
1943
1944     This class is used by wxDataViewCtrl to render bitmap controls.
1945
1946     @library{wxadv}
1947     @category{dvc}
1948 */
1949 class wxDataViewBitmapRenderer : public wxDataViewRenderer
1950 {
1951 public:
1952     /**
1953         The ctor.
1954     */
1955     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
1956                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1957                              int align = wxDVR_DEFAULT_ALIGNMENT);
1958 };
1959
1960
1961 /**
1962     The flags used by wxDataViewColumn.
1963     Can be combined together.
1964 */
1965 enum wxDataViewColumnFlags
1966 {
1967     wxDATAVIEW_COL_RESIZABLE     = 1,
1968     wxDATAVIEW_COL_SORTABLE      = 2,
1969     wxDATAVIEW_COL_REORDERABLE   = 4,
1970     wxDATAVIEW_COL_HIDDEN        = 8
1971 };
1972
1973 /**
1974     @class wxDataViewColumn
1975
1976     This class represents a column in a wxDataViewCtrl.
1977     One wxDataViewColumn is bound to one column in the data model to which the
1978     wxDataViewCtrl has been associated.
1979
1980     An instance of wxDataViewRenderer is used by this class to render its data.
1981
1982     @library{wxadv}
1983     @category{dvc}
1984 */
1985 class wxDataViewColumn : public wxSettableHeaderColumn
1986 {
1987 public:
1988     /**
1989         Constructs a text column.
1990
1991         @param title
1992             The title of the column.
1993         @param renderer
1994             The class which will render the contents of this column.
1995         @param model_column
1996             The index of the model's column which is associated with this object.
1997         @param width
1998             The width of the column.
1999             The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
2000         @param align
2001             The alignment of the column title.
2002         @param flags
2003             One or more flags of the ::wxDataViewColumnFlags enumeration.
2004     */
2005     wxDataViewColumn(const wxString& title,
2006                      wxDataViewRenderer* renderer,
2007                      unsigned int model_column,
2008                      int width = wxDVC_DEFAULT_WIDTH,
2009                      wxAlignment align = wxALIGN_CENTER,
2010                      int flags = wxDATAVIEW_COL_RESIZABLE);
2011
2012     /**
2013         Constructs a bitmap column.
2014
2015         @param bitmap
2016             The bitmap of the column.
2017         @param renderer
2018             The class which will render the contents of this column.
2019         @param model_column
2020             The index of the model's column which is associated with this object.
2021         @param width
2022             The width of the column.
2023             The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
2024         @param align
2025             The alignment of the column title.
2026         @param flags
2027             One or more flags of the ::wxDataViewColumnFlags enumeration.
2028     */
2029     wxDataViewColumn(const wxBitmap& bitmap,
2030                      wxDataViewRenderer* renderer,
2031                      unsigned int model_column,
2032                      int width = wxDVC_DEFAULT_WIDTH,
2033                      wxAlignment align = wxALIGN_CENTER,
2034                      int flags = wxDATAVIEW_COL_RESIZABLE);
2035
2036     /**
2037         Returns the index of the column of the model, which this
2038         wxDataViewColumn is displaying.
2039     */
2040     unsigned int GetModelColumn() const;
2041
2042     /**
2043         Returns the owning wxDataViewCtrl.
2044     */
2045     wxDataViewCtrl* GetOwner() const;
2046
2047     /**
2048         Returns the renderer of this wxDataViewColumn.
2049
2050         @see wxDataViewRenderer.
2051     */
2052     wxDataViewRenderer* GetRenderer() const;
2053 };
2054
2055
2056
2057 /**
2058     @class wxDataViewListCtrl
2059
2060     This class is a wxDataViewCtrl which internally uses a wxDataViewListStore
2061     and forwards most of its API to that class.
2062
2063     The purpose of this class is to offer a simple way to display and
2064     edit a small table of data without having to write your own wxDataViewModel.
2065
2066     @code
2067        wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY );
2068
2069        listctrl->AppendToggleColumn( "Toggle" );
2070        listctrl->AppendTextColumn( "Text" );
2071
2072        wxVector<wxVariant> data;
2073        data.push_back( wxVariant(true) );
2074        data.push_back( wxVariant("row 1") );
2075        listctrl->AppendItem( data );
2076
2077        data.clear();
2078        data.push_back( wxVariant(false) );
2079        data.push_back( wxVariant("row 3") );
2080        listctrl->AppendItem( data );
2081     @endcode
2082
2083     @beginStyleTable
2084     See wxDataViewCtrl for the list of supported styles.
2085     @endStyleTable
2086
2087     @beginEventEmissionTable
2088     See wxDataViewCtrl for the list of events emitted by this class.
2089     @endEventTable
2090
2091     @library{wxadv}
2092     @category{ctrl,dvc}
2093 */
2094 class wxDataViewListCtrl: public wxDataViewCtrl
2095 {
2096 public:
2097     /**
2098         Default ctor.
2099     */
2100     wxDataViewListCtrl();
2101
2102     /**
2103         Constructor. Calls Create().
2104     */
2105     wxDataViewListCtrl( wxWindow *parent, wxWindowID id,
2106            const wxPoint& pos = wxDefaultPosition,
2107            const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES,
2108            const wxValidator& validator = wxDefaultValidator );
2109
2110     /**
2111         Destructor. Deletes the image list if any.
2112     */
2113     ~wxDataViewListCtrl();
2114
2115     /**
2116         Creates the control and a wxDataViewListStore as its internal model.
2117     */
2118     bool Create( wxWindow *parent, wxWindowID id,
2119            const wxPoint& pos = wxDefaultPosition,
2120            const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES,
2121            const wxValidator& validator = wxDefaultValidator );
2122
2123     //@{
2124     /**
2125         Returns the store.
2126     */
2127     wxDataViewListStore *GetStore();
2128     const wxDataViewListStore *GetStore() const;
2129     //@}
2130
2131     /**
2132         Returns the position of given @e item or wxNOT_FOUND if it's
2133         not a valid item.
2134
2135         @since 2.9.2
2136      */
2137     int ItemToRow(const wxDataViewItem &item) const;
2138
2139     /**
2140         Returns the wxDataViewItem at the given @e row.
2141
2142         @since 2.9.2
2143      */
2144     wxDataViewItem RowToItem(int row) const;
2145
2146     //@{
2147     /**
2148         @name Selection handling functions
2149      */
2150
2151     /**
2152         Returns index of the selected row or wxNOT_FOUND.
2153
2154         @see wxDataViewCtrl::GetSelection()
2155
2156         @since 2.9.2
2157      */
2158     int GetSelectedRow() const;
2159
2160     /**
2161         Selects given row.
2162
2163         @see wxDataViewCtrl::Select()
2164
2165         @since 2.9.2
2166      */
2167     void SelectRow(unsigned row);
2168
2169     /**
2170         Unselects given row.
2171
2172         @see wxDataViewCtrl::Unselect()
2173
2174         @since 2.9.2
2175      */
2176     void UnselectRow(unsigned row);
2177
2178     /**
2179         Returns true if @a row is selected.
2180
2181         @see wxDataViewCtrl::IsSelected()
2182
2183         @since 2.9.2
2184      */
2185     bool IsRowSelected(unsigned row) const;
2186
2187     //@}
2188
2189     /**
2190         @name Column management functions
2191     */
2192     //@{
2193
2194     /**
2195         Appends a column to the control and additionally appends a
2196         column to the store with the type string.
2197     */
2198     virtual void AppendColumn( wxDataViewColumn *column );
2199
2200     /**
2201         Appends a column to the control and additionally appends a
2202         column to the list store with the type @a varianttype.
2203     */
2204     void AppendColumn( wxDataViewColumn *column, const wxString &varianttype );
2205
2206     /**
2207         Appends a text column to the control and the store.
2208
2209         See wxDataViewColumn::wxDataViewColumn for more info about
2210         the parameters.
2211     */
2212     wxDataViewColumn *AppendTextColumn( const wxString &label,
2213           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
2214           int width = -1, wxAlignment align = wxALIGN_LEFT,
2215           int flags = wxDATAVIEW_COL_RESIZABLE );
2216
2217     /**
2218         Appends a toggle column to the control and the store.
2219
2220         See wxDataViewColumn::wxDataViewColumn for more info about
2221         the parameters.
2222     */
2223     wxDataViewColumn *AppendToggleColumn( const wxString &label,
2224           wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
2225           int width = -1, wxAlignment align = wxALIGN_LEFT,
2226           int flags = wxDATAVIEW_COL_RESIZABLE );
2227
2228     /**
2229         Appends a progress column to the control and the store.
2230
2231         See wxDataViewColumn::wxDataViewColumn for more info about
2232         the parameters.
2233     */
2234     wxDataViewColumn *AppendProgressColumn( const wxString &label,
2235           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
2236           int width = -1, wxAlignment align = wxALIGN_LEFT,
2237           int flags = wxDATAVIEW_COL_RESIZABLE );
2238
2239     /**
2240         Appends an icon-and-text column to the control and the store.
2241
2242         See wxDataViewColumn::wxDataViewColumn for more info about
2243         the parameters.
2244     */
2245     wxDataViewColumn *AppendIconTextColumn( const wxString &label,
2246           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
2247           int width = -1, wxAlignment align = wxALIGN_LEFT,
2248           int flags = wxDATAVIEW_COL_RESIZABLE );
2249
2250     /**
2251         Inserts a column to the control and additionally inserts a
2252         column to the store with the type string.
2253     */
2254     virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column );
2255
2256     /**
2257         Inserts a column to the control and additionally inserts a
2258         column to the list store with the type @a varianttype.
2259     */
2260     void InsertColumn( unsigned int pos, wxDataViewColumn *column,
2261                        const wxString &varianttype );
2262
2263     /**
2264         Prepends a column to the control and additionally prepends a
2265         column to the store with the type string.
2266     */
2267     virtual void PrependColumn( wxDataViewColumn *column );
2268
2269     /**
2270         Prepends a column to the control and additionally prepends a
2271         column to the list store with the type @a varianttype.
2272     */
2273     void PrependColumn( wxDataViewColumn *column, const wxString &varianttype );
2274
2275     //@}
2276
2277
2278     /**
2279         @name Item management functions
2280     */
2281     //@{
2282
2283     /**
2284         Appends an item (=row) to the control and store.
2285     */
2286     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2287
2288     /**
2289         Prepends an item (=row) to the control and store.
2290     */
2291     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2292
2293     /**
2294         Inserts an item (=row) to the control and store.
2295     */
2296     void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
2297
2298     /**
2299         Delete the row at position @a row.
2300     */
2301     void DeleteItem( unsigned row );
2302
2303     /**
2304         Delete all items (= all rows).
2305     */
2306     void DeleteAllItems();
2307
2308     /**
2309          Sets the value in the store and update the control.
2310     */
2311     void SetValue( const wxVariant &value, unsigned int row, unsigned int col );
2312
2313     /**
2314          Returns the value from the store.
2315     */
2316     void GetValue( wxVariant &value, unsigned int row, unsigned int col );
2317
2318     /**
2319          Sets the value in the store and update the control.
2320
2321          This method assumes that the string is stored in respective
2322          column.
2323     */
2324     void SetTextValue( const wxString &value, unsigned int row, unsigned int col );
2325
2326     /**
2327          Returns the value from the store.
2328
2329          This method assumes that the string is stored in respective
2330          column.
2331     */
2332     wxString GetTextValue( unsigned int row, unsigned int col ) const;
2333
2334     /**
2335          Sets the value in the store and update the control.
2336
2337          This method assumes that the boolean value is stored in
2338          respective column.
2339     */
2340     void SetToggleValue( bool value, unsigned int row, unsigned int col );
2341
2342     /**
2343          Returns the value from the store.
2344
2345          This method assumes that the boolean value is stored in
2346          respective column.
2347     */
2348     bool GetToggleValue( unsigned int row, unsigned int col ) const;
2349
2350     //@}
2351 };
2352
2353
2354 /**
2355     @class wxDataViewTreeCtrl
2356
2357     This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
2358     and forwards most of its API to that class.
2359     Additionally, it uses a wxImageList to store a list of icons.
2360
2361     The main purpose of this class is to provide a simple upgrade path for code
2362     using wxTreeCtrl.
2363
2364     @beginStyleTable
2365     See wxDataViewCtrl for the list of supported styles.
2366     @endStyleTable
2367
2368     @beginEventEmissionTable
2369     See wxDataViewCtrl for the list of events emitted by this class.
2370     @endEventTable
2371
2372     @library{wxadv}
2373     @category{ctrl,dvc}
2374     @appearance{dataviewtreectrl.png}
2375 */
2376 class wxDataViewTreeCtrl : public wxDataViewCtrl
2377 {
2378 public:
2379     /**
2380         Default ctor.
2381     */
2382     wxDataViewTreeCtrl();
2383
2384     /**
2385         Constructor.
2386
2387         Calls Create().
2388     */
2389     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
2390                        const wxPoint& pos = wxDefaultPosition,
2391                        const wxSize& size = wxDefaultSize,
2392                        long style = wxDV_NO_HEADER | wxDV_ROW_LINES,
2393                        const wxValidator& validator = wxDefaultValidator);
2394
2395     /**
2396         Destructor. Deletes the image list if any.
2397     */
2398     virtual ~wxDataViewTreeCtrl();
2399
2400     /**
2401         Appends a container to the given @a parent.
2402     */
2403     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
2404                                    const wxString& text,
2405                                    int icon = -1,
2406                                    int expanded = -1,
2407                                    wxClientData* data = NULL);
2408
2409     /**
2410         Appends an item to the given @a parent.
2411     */
2412     wxDataViewItem AppendItem(const wxDataViewItem& parent,
2413                               const wxString& text,
2414                               int icon = -1,
2415                               wxClientData* data = NULL);
2416
2417     /**
2418         Creates the control and a wxDataViewTreeStore as its internal model.
2419
2420         The default tree column created by this method is an editable column
2421         using wxDataViewIconTextRenderer as its renderer.
2422     */
2423     bool Create(wxWindow* parent, wxWindowID id,
2424                 const wxPoint& pos = wxDefaultPosition,
2425                 const wxSize& size = wxDefaultSize,
2426                 long style = wxDV_NO_HEADER | wxDV_ROW_LINES,
2427                 const wxValidator& validator = wxDefaultValidator);
2428
2429     /**
2430         Calls the identical method from wxDataViewTreeStore.
2431     */
2432     void DeleteAllItems();
2433
2434     /**
2435         Calls the identical method from wxDataViewTreeStore.
2436     */
2437     void DeleteChildren(const wxDataViewItem& item);
2438
2439     /**
2440         Calls the identical method from wxDataViewTreeStore.
2441     */
2442     void DeleteItem(const wxDataViewItem& item);
2443
2444     /**
2445         Calls the identical method from wxDataViewTreeStore.
2446     */
2447     int GetChildCount(const wxDataViewItem& parent) const;
2448
2449     /**
2450         Returns the image list.
2451     */
2452     wxImageList* GetImageList();
2453
2454     /**
2455         Calls the identical method from wxDataViewTreeStore.
2456     */
2457     wxClientData* GetItemData(const wxDataViewItem& item) const;
2458
2459     /**
2460         Calls the identical method from wxDataViewTreeStore.
2461     */
2462     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
2463
2464     /**
2465         Calls the identical method from wxDataViewTreeStore.
2466     */
2467     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
2468
2469     /**
2470         Calls the identical method from wxDataViewTreeStore.
2471     */
2472     wxString GetItemText(const wxDataViewItem& item) const;
2473
2474     /**
2475         Calls the identical method from wxDataViewTreeStore.
2476     */
2477     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
2478                                unsigned int pos) const;
2479
2480     //@{
2481     /**
2482         Returns the store.
2483     */
2484     wxDataViewTreeStore* GetStore();
2485     const wxDataViewTreeStore* GetStore() const;
2486     //@}
2487
2488     /**
2489         Calls the same method from wxDataViewTreeStore but uses
2490         an index position in the image list instead of a wxIcon.
2491     */
2492     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
2493                                    const wxDataViewItem& previous,
2494                                    const wxString& text,
2495                                    int icon = -1,
2496                                    int expanded = -1,
2497                                    wxClientData* data = NULL);
2498
2499     /**
2500         Calls the same method from wxDataViewTreeStore but uses
2501         an index position in the image list instead of a wxIcon.
2502     */
2503     wxDataViewItem InsertItem(const wxDataViewItem& parent,
2504                               const wxDataViewItem& previous,
2505                               const wxString& text,
2506                               int icon = -1,
2507                               wxClientData* data = NULL);
2508
2509     /**
2510         Returns true if item is a container.
2511     */
2512     bool IsContainer( const wxDataViewItem& item );
2513
2514     /**
2515         Calls the same method from wxDataViewTreeStore but uses
2516         an index position in the image list instead of a wxIcon.
2517     */
2518     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
2519                                     const wxString& text,
2520                                     int icon = -1,
2521                                     int expanded = -1,
2522                                     wxClientData* data = NULL);
2523
2524     /**
2525         Calls the same method from wxDataViewTreeStore but uses
2526         an index position in the image list instead of a wxIcon.
2527     */
2528     wxDataViewItem PrependItem(const wxDataViewItem& parent,
2529                                const wxString& text,
2530                                int icon = -1,
2531                                wxClientData* data = NULL);
2532
2533     /**
2534         Sets the image list.
2535     */
2536     void SetImageList(wxImageList* imagelist);
2537
2538     /**
2539         Calls the identical method from wxDataViewTreeStore.
2540     */
2541     void SetItemData(const wxDataViewItem& item, wxClientData* data);
2542
2543     /**
2544         Calls the identical method from wxDataViewTreeStore.
2545     */
2546     void SetItemExpandedIcon(const wxDataViewItem& item,
2547                              const wxIcon& icon);
2548
2549     /**
2550         Calls the identical method from wxDataViewTreeStore.
2551     */
2552     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
2553
2554     /**
2555         Calls the identical method from wxDataViewTreeStore.
2556     */
2557     void SetItemText(const wxDataViewItem& item,
2558                      const wxString& text);
2559 };
2560
2561
2562 /**
2563     @class wxDataViewListStore
2564
2565     wxDataViewListStore is a specialised wxDataViewModel for storing
2566     a simple table of data. Since it derives from wxDataViewIndexListModel
2567     its data is be accessed by row (i.e. by index) instead of only
2568     by wxDataViewItem.
2569
2570     This class actually stores the values (therefore its name)
2571     and implements all virtual methods from the base classes so it can be
2572     used directly without having to derive any class from it, but it is
2573     mostly used from within wxDataViewListCtrl.
2574
2575     @library{wxadv}
2576     @category{dvc}
2577 */
2578
2579 class wxDataViewListStore: public wxDataViewIndexListModel
2580 {
2581 public:
2582     /**
2583         Constructor
2584     */
2585     wxDataViewListStore();
2586
2587     /**
2588         Destructor
2589     */
2590     ~wxDataViewListStore();
2591
2592     /**
2593         Prepends a data column.
2594
2595         @a variantype indicates the type of values store in the column.
2596
2597         This does not automatically fill in any (default) values in
2598         rows which exist in the store already.
2599     */
2600     void PrependColumn( const wxString &varianttype );
2601
2602     /**
2603         Inserts a data column before @a pos.
2604
2605         @a variantype indicates the type of values store in the column.
2606
2607         This does not automatically fill in any (default) values in
2608         rows which exist in the store already.
2609     */
2610     void InsertColumn( unsigned int pos, const wxString &varianttype );
2611
2612     /**
2613         Appends a data column.
2614
2615         @a variantype indicates the type of values store in the column.
2616
2617         This does not automatically fill in any (default) values in
2618         rows which exist in the store already.
2619     */
2620     void AppendColumn( const wxString &varianttype );
2621
2622     /**
2623         Appends an item (=row) and fills it with @a values.
2624
2625         The values must match the values specifies in the column
2626         in number and type. No (default) values are filled in
2627         automatically.
2628     */
2629     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2630
2631     /**
2632         Prepends an item (=row) and fills it with @a values.
2633
2634         The values must match the values specifies in the column
2635         in number and type. No (default) values are filled in
2636         automatically.
2637     */
2638     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2639
2640     /**
2641         Inserts an item (=row) and fills it with @a values.
2642
2643         The values must match the values specifies in the column
2644         in number and type. No (default) values are filled in
2645         automatically.
2646     */
2647     void InsertItem(  unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
2648
2649     /**
2650         Delete the item (=row) at position @a pos.
2651     */
2652     void DeleteItem( unsigned pos );
2653
2654     /**
2655         Delete all item (=all rows) in the store.
2656     */
2657     void DeleteAllItems();
2658
2659     /**
2660         Overridden from wxDataViewModel
2661     */
2662     virtual unsigned int GetColumnCount() const;
2663
2664     /**
2665         Overridden from wxDataViewModel
2666     */
2667     virtual wxString GetColumnType( unsigned int col ) const;
2668
2669     /**
2670         Overridden from wxDataViewIndexListModel
2671     */
2672     virtual void GetValueByRow( wxVariant &value,
2673                            unsigned int row, unsigned int col ) const;
2674
2675     /**
2676         Overridden from wxDataViewIndexListModel
2677     */
2678     virtual bool SetValueByRow( const wxVariant &value,
2679                            unsigned int row, unsigned int col );
2680 };
2681
2682
2683 /**
2684     @class wxDataViewTreeStore
2685
2686     wxDataViewTreeStore is a specialised wxDataViewModel for storing simple
2687     trees very much like wxTreeCtrl does and it offers a similar API.
2688
2689     This class actually stores the entire tree and the values (therefore its name)
2690     and implements all virtual methods from the base class so it can be used directly
2691     without having to derive any class from it, but it is mostly used from within
2692     wxDataViewTreeCtrl.
2693
2694     @library{wxadv}
2695     @category{dvc}
2696 */
2697 class wxDataViewTreeStore : public wxDataViewModel
2698 {
2699 public:
2700     /**
2701         Constructor. Creates the invisible root node internally.
2702     */
2703     wxDataViewTreeStore();
2704
2705     /**
2706         Destructor.
2707     */
2708     virtual ~wxDataViewTreeStore();
2709
2710     /**
2711         Append a container.
2712     */
2713     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
2714                                    const wxString& text,
2715                                    const wxIcon& icon = wxNullIcon,
2716                                    const wxIcon& expanded = wxNullIcon,
2717                                    wxClientData* data = NULL);
2718
2719     /**
2720         Append an item.
2721     */
2722     wxDataViewItem AppendItem(const wxDataViewItem& parent,
2723                               const wxString& text,
2724                               const wxIcon& icon = wxNullIcon,
2725                               wxClientData* data = NULL);
2726
2727     /**
2728         Delete all item in the model.
2729     */
2730     void DeleteAllItems();
2731
2732     /**
2733         Delete all children of the item, but not the item itself.
2734     */
2735     void DeleteChildren(const wxDataViewItem& item);
2736
2737     /**
2738         Delete this item.
2739     */
2740     void DeleteItem(const wxDataViewItem& item);
2741
2742     /**
2743         Return the number of children of item.
2744     */
2745     int GetChildCount(const wxDataViewItem& parent) const;
2746
2747     /**
2748         Returns the client data associated with the item.
2749     */
2750     wxClientData* GetItemData(const wxDataViewItem& item) const;
2751
2752     /**
2753         Returns the icon to display in expanded containers.
2754     */
2755     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
2756
2757     /**
2758         Returns the icon of the item.
2759     */
2760     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
2761
2762     /**
2763         Returns the text of the item.
2764     */
2765     wxString GetItemText(const wxDataViewItem& item) const;
2766
2767     /**
2768         Returns the nth child item of item.
2769     */
2770     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
2771                                unsigned int pos) const;
2772
2773     /**
2774         Inserts a container after @a previous.
2775     */
2776     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
2777                                    const wxDataViewItem& previous,
2778                                    const wxString& text,
2779                                    const wxIcon& icon = wxNullIcon,
2780                                    const wxIcon& expanded = wxNullIcon,
2781                                    wxClientData* data = NULL);
2782
2783     /**
2784         Inserts an item after @a previous.
2785     */
2786     wxDataViewItem InsertItem(const wxDataViewItem& parent,
2787                               const wxDataViewItem& previous,
2788                               const wxString& text,
2789                               const wxIcon& icon = wxNullIcon,
2790                               wxClientData* data = NULL);
2791
2792     /**
2793         Inserts a container before the first child item or @a parent.
2794     */
2795     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
2796                                     const wxString& text,
2797                                     const wxIcon& icon = wxNullIcon,
2798                                     const wxIcon& expanded = wxNullIcon,
2799                                     wxClientData* data = NULL);
2800
2801     /**
2802         Inserts an item before the first child item or @a parent.
2803     */
2804     wxDataViewItem PrependItem(const wxDataViewItem& parent,
2805                                const wxString& text,
2806                                const wxIcon& icon = wxNullIcon,
2807                                wxClientData* data = NULL);
2808
2809     /**
2810         Sets the client data associated with the item.
2811     */
2812     void SetItemData(const wxDataViewItem& item, wxClientData* data);
2813
2814     /**
2815         Sets the expanded icon for the item.
2816     */
2817     void SetItemExpandedIcon(const wxDataViewItem& item,
2818                              const wxIcon& icon);
2819
2820     /**
2821         Sets the icon for the item.
2822     */
2823     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
2824 };
2825
2826
2827 /**
2828     @class wxDataViewIconText
2829
2830     wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
2831     This class can be converted to and from a wxVariant.
2832
2833     @library{wxadv}
2834     @category{dvc}
2835 */
2836 class wxDataViewIconText : public wxObject
2837 {
2838 public:
2839     //@{
2840     /**
2841         Constructor.
2842     */
2843     wxDataViewIconText(const wxString& text = wxEmptyString,
2844                        const wxIcon& icon = wxNullIcon);
2845     wxDataViewIconText(const wxDataViewIconText& other);
2846     //@}
2847
2848     /**
2849         Gets the icon.
2850     */
2851     const wxIcon& GetIcon() const;
2852
2853     /**
2854         Gets the text.
2855     */
2856     wxString GetText() const;
2857
2858     /**
2859         Set the icon.
2860     */
2861     void SetIcon(const wxIcon& icon);
2862
2863     /**
2864         Set the text.
2865     */
2866     void SetText(const wxString& text);
2867 };
2868
2869
2870
2871 /**
2872     @class wxDataViewEvent
2873
2874     This is the event class for the wxDataViewCtrl notifications.
2875
2876     @beginEventTable{wxDataViewEvent}
2877     @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
2878            Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
2879     @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
2880            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
2881     @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
2882            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
2883     @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
2884            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
2885     @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
2886            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
2887     @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
2888            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
2889     @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
2890            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
2891     @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
2892            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
2893     @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
2894            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
2895     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
2896            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
2897     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
2898            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
2899     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
2900            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
2901     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
2902            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
2903     @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
2904            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
2905     @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
2906            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
2907     @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
2908            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
2909     @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
2910            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
2911     @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
2912            Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
2913     @endEventTable
2914
2915     @library{wxadv}
2916     @category{events,dvc}
2917 */
2918 class wxDataViewEvent : public wxNotifyEvent
2919 {
2920 public:
2921     /**
2922         Constructor. Typically used by wxWidgets internals only.
2923     */
2924     wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
2925                     int winid = 0);
2926
2927     /**
2928         Returns the position of the column in the control or -1
2929         if no column field was set by the event emitter.
2930     */
2931     int GetColumn() const;
2932
2933     /**
2934         Returns a pointer to the wxDataViewColumn from which
2935         the event was emitted or @NULL.
2936     */
2937     wxDataViewColumn* GetDataViewColumn() const;
2938
2939     /**
2940         Returns the wxDataViewModel associated with the event.
2941     */
2942     wxDataViewModel* GetModel() const;
2943
2944     /**
2945         Returns the position of a context menu event in screen coordinates.
2946     */
2947     wxPoint GetPosition() const;
2948
2949     /**
2950         Returns a reference to a value.
2951     */
2952     const wxVariant& GetValue() const;
2953
2954     /**
2955         Can be used to determine whether the new value is going to be accepted
2956         in wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE handler.
2957
2958         Returns @true if editing the item was cancelled or if the user tried to
2959         enter an invalid value (refused by wxDataViewRenderer::Validate()). If
2960         this method returns @false, it means that the value in the model is
2961         about to be changed to the new one.
2962
2963         Notice that wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event handler can
2964         call wxNotifyEvent::Veto() to prevent this from happening.
2965
2966         Currently support for setting this field and for vetoing the change is
2967         only available in the generic version of wxDataViewCtrl, i.e. under MSW
2968         but not GTK nor OS X.
2969
2970         @since 2.9.3
2971      */
2972     bool IsEditCancelled() const;
2973
2974     /**
2975         Sets the column index associated with this event.
2976     */
2977     void SetColumn(int col);
2978
2979     /**
2980         For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
2981     */
2982     void SetDataViewColumn(wxDataViewColumn* col);
2983
2984     /**
2985         Sets the dataview model associated with this event.
2986     */
2987     void SetModel(wxDataViewModel* model);
2988
2989     /**
2990         Sets the value associated with this event.
2991     */
2992     void SetValue(const wxVariant& value);
2993
2994     /**
2995         Set wxDataObject for data transfer within a drag operation.
2996     */
2997     void SetDataObject( wxDataObject *obj );
2998
2999     /**
3000         Used internally. Gets associated wxDataObject for data transfer
3001         within a drag operation.
3002     */
3003     wxDataObject *GetDataObject() const;
3004
3005     /**
3006         Used internally. Sets the wxDataFormat during a drop operation.
3007     */
3008     void SetDataFormat( const wxDataFormat &format );
3009
3010     /**
3011         Gets the wxDataFormat during a drop operation.
3012     */
3013     wxDataFormat GetDataFormat() const;
3014
3015     /**
3016         Used internally. Sets the data size for a drop data transfer.
3017     */
3018     void SetDataSize( size_t size );
3019
3020     /**
3021         Gets the data size for a drop data transfer.
3022     */
3023     size_t GetDataSize() const;
3024
3025     /**
3026         Used internally. Sets the data buffer for a drop data transfer.
3027     */
3028     void SetDataBuffer( void* buf );
3029
3030     /**
3031         Gets the data buffer for a drop data transfer.
3032     */
3033     void *GetDataBuffer() const;
3034
3035     /**
3036         Return the first row that will be displayed.
3037     */
3038     int GetCacheFrom() const;
3039
3040     /**
3041         Return the last row that will be displayed.
3042     */
3043     int GetCacheTo() const;
3044 };
3045