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