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