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