interface/wx/dataview.h

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