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         Unselect the given item.
1100     */
1101     virtual void Unselect(const wxDataViewItem& item);
1102
1103     /**
1104         Unselect all item.
1105         This method only has effect if multiple selections are allowed.
1106     */
1107     virtual void UnselectAll();
1108 };
1109
1110
1111
1112 /**
1113     @class wxDataViewModelNotifier
1114
1115     A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors
1116     its notification interface.
1117     See the documentation of that class for further information.
1118
1119     @library{wxadv}
1120     @category{dvc}
1121 */
1122 class wxDataViewModelNotifier
1123 {
1124 public:
1125     /**
1126         Constructor.
1127     */
1128     wxDataViewModelNotifier();
1129
1130     /**
1131         Destructor.
1132     */
1133     virtual ~wxDataViewModelNotifier();
1134
1135     /**
1136         Called by owning model.
1137     */
1138     virtual bool Cleared() = 0;
1139
1140     /**
1141         Get owning wxDataViewModel.
1142     */
1143     wxDataViewModel* GetOwner() const;
1144
1145     /**
1146         Called by owning model.
1147     */
1148     virtual bool ItemAdded(const wxDataViewItem& parent,
1149                            const wxDataViewItem& item) = 0;
1150
1151     /**
1152         Called by owning model.
1153     */
1154     virtual bool ItemChanged(const wxDataViewItem& item) = 0;
1155
1156     /**
1157         Called by owning model.
1158     */
1159     virtual bool ItemDeleted(const wxDataViewItem& parent,
1160                              const wxDataViewItem& item) = 0;
1161
1162     /**
1163         Called by owning model.
1164     */
1165     virtual bool ItemsAdded(const wxDataViewItem& parent,
1166                             const wxDataViewItemArray& items);
1167
1168     /**
1169         Called by owning model.
1170     */
1171     virtual bool ItemsChanged(const wxDataViewItemArray& items);
1172
1173     /**
1174         Called by owning model.
1175     */
1176     virtual bool ItemsDeleted(const wxDataViewItem& parent,
1177                               const wxDataViewItemArray& items);
1178
1179     /**
1180         Called by owning model.
1181     */
1182     virtual void Resort() = 0;
1183
1184     /**
1185         Set owner of this notifier. Used internally.
1186     */
1187     void SetOwner(wxDataViewModel* owner);
1188
1189     /**
1190         Called by owning model.
1191     */
1192     virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0;
1193 };
1194
1195
1196 /**
1197     The mode of a data-view cell; see wxDataViewRenderer for more info.
1198 */
1199 enum wxDataViewCellMode
1200 {
1201     wxDATAVIEW_CELL_INERT,
1202
1203     /**
1204         Indicates that the user can double click the cell and something will
1205         happen (e.g. a window for editing a date will pop up).
1206     */
1207     wxDATAVIEW_CELL_ACTIVATABLE,
1208
1209     /**
1210         Indicates that the user can edit the data in-place, i.e. an control
1211         will show up after a slow click on the cell. This behaviour is best
1212         known from changing the filename in most file managers etc.
1213     */
1214     wxDATAVIEW_CELL_EDITABLE
1215 };
1216
1217 /**
1218     The values of this enum controls how a wxDataViewRenderer should display
1219     its contents in a cell.
1220 */
1221 enum wxDataViewCellRenderState
1222 {
1223     wxDATAVIEW_CELL_SELECTED    = 1,
1224     wxDATAVIEW_CELL_PRELIT      = 2,
1225     wxDATAVIEW_CELL_INSENSITIVE = 4,
1226     wxDATAVIEW_CELL_FOCUSED     = 8
1227 };
1228
1229 /**
1230     @class wxDataViewRenderer
1231
1232     This class is used by wxDataViewCtrl to render the individual cells.
1233     One instance of a renderer class is owned by a wxDataViewColumn.
1234     There is a number of ready-to-use renderers provided:
1235     - wxDataViewTextRenderer,
1236     - wxDataViewIconTextRenderer,
1237     - wxDataViewToggleRenderer,
1238     - wxDataViewProgressRenderer,
1239     - wxDataViewBitmapRenderer,
1240     - wxDataViewDateRenderer,
1241     - wxDataViewSpinRenderer.
1242     - wxDataViewChoiceRenderer.
1243
1244     Additionally, the user can write own renderers by deriving from
1245     wxDataViewCustomRenderer.
1246
1247     The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1248     by the constructors respectively controls what actions the cell data allows
1249     and how the renderer should display its contents in a cell.
1250
1251     @library{wxadv}
1252     @category{dvc}
1253 */
1254 class wxDataViewRenderer : public wxObject
1255 {
1256 public:
1257     /**
1258         Constructor.
1259     */
1260     wxDataViewRenderer(const wxString& varianttype,
1261                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1262                        int align = wxDVR_DEFAULT_ALIGNMENT );
1263
1264     /**
1265         Enable or disable replacing parts of the item text with ellipsis to
1266         make it fit the column width.
1267
1268         This method only makes sense for the renderers working with text, such
1269         as wxDataViewTextRenderer or wxDataViewIconTextRenderer.
1270
1271         By default wxELLIPSIZE_MIDDLE is used.
1272
1273         @param mode
1274             Ellipsization mode, use wxELLIPSIZE_NONE to disable.
1275
1276         @since 2.9.1
1277      */
1278     void EnableEllipsize(wxEllipsizeMode mode = wxELLIPSIZE_MIDDLE);
1279
1280     /**
1281         Disable replacing parts of the item text with ellipsis.
1282
1283         If ellipsizing is disabled, the string will be truncated if it doesn't
1284         fit.
1285
1286         This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode.
1287
1288         @since 2.9.1
1289      */
1290     void DisableEllipsize();
1291
1292     /**
1293         Returns the alignment. See SetAlignment()
1294     */
1295     virtual int GetAlignment() const;
1296
1297     /**
1298         Returns the ellipsize mode used by the renderer.
1299
1300         If the return value is wxELLIPSIZE_NONE, the text is simply truncated
1301         if it doesn't fit.
1302
1303         @see EnableEllipsize()
1304      */
1305     wxEllipsizeMode GetEllipsizeMode() const;
1306
1307     /**
1308         Returns the cell mode.
1309     */
1310     virtual wxDataViewCellMode GetMode() const;
1311
1312     /**
1313         Returns pointer to the owning wxDataViewColumn.
1314     */
1315     wxDataViewColumn* GetOwner() const;
1316
1317     /**
1318         This methods retrieves the value from the renderer in order to
1319         transfer the value back to the data model.
1320
1321         Returns @false on failure.
1322     */
1323     virtual bool GetValue(wxVariant& value) const = 0;
1324
1325     /**
1326         Returns a string with the type of the wxVariant supported by this renderer.
1327     */
1328     wxString GetVariantType() const;
1329
1330     /**
1331         Sets the alignment of the renderer's content.
1332         The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1333         should have the same alignment as the column header.
1334
1335         The method is not implemented under OS X and the renderer always aligns
1336         its contents as the column header on that platform. The other platforms
1337         support both vertical and horizontal alignment.
1338     */
1339     virtual void SetAlignment( int align );
1340     /**
1341         Sets the owning wxDataViewColumn.
1342         This is usually called from within wxDataViewColumn.
1343     */
1344     void SetOwner(wxDataViewColumn* owner);
1345
1346     /**
1347         Set the value of the renderer (and thus its cell) to @a value.
1348         The internal code will then render this cell with this data.
1349     */
1350     virtual bool SetValue(const wxVariant& value) = 0;
1351
1352     /**
1353         Before data is committed to the data model, it is passed to this
1354         method where it can be checked for validity. This can also be
1355         used for checking a valid range or limiting the user input in
1356         a certain aspect (e.g. max number of characters or only alphanumeric
1357         input, ASCII only etc.). Return @false if the value is not valid.
1358
1359         Please note that due to implementation limitations, this validation
1360         is done after the editing control already is destroyed and the
1361         editing process finished.
1362     */
1363     virtual bool Validate(wxVariant& value);
1364 };
1365
1366
1367
1368 /**
1369     @class wxDataViewTextRenderer
1370
1371     wxDataViewTextRenderer is used for rendering text.
1372     It supports in-place editing if desired.
1373
1374     @library{wxadv}
1375     @category{dvc}
1376 */
1377 class wxDataViewTextRenderer : public wxDataViewRenderer
1378 {
1379 public:
1380     /**
1381         The ctor.
1382     */
1383     wxDataViewTextRenderer(const wxString& varianttype = "string",
1384                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1385                            int align = wxDVR_DEFAULT_ALIGNMENT );
1386 };
1387
1388
1389
1390 /**
1391     @class wxDataViewIconTextRenderer
1392
1393     The wxDataViewIconTextRenderer class is used to display text with
1394     a small icon next to it as it is typically done in a file manager.
1395
1396     This classes uses the wxDataViewIconText helper class to store its data.
1397     wxDataViewIconText can be converted to and from a wxVariant using the left
1398     shift operator.
1399
1400     @library{wxadv}
1401     @category{dvc}
1402 */
1403 class wxDataViewIconTextRenderer : public wxDataViewRenderer
1404 {
1405 public:
1406     /**
1407         The ctor.
1408     */
1409     wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
1410                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1411                                int align = wxDVR_DEFAULT_ALIGNMENT );
1412 };
1413
1414
1415
1416 /**
1417     @class wxDataViewProgressRenderer
1418
1419     This class is used by wxDataViewCtrl to render progress bars.
1420
1421     @library{wxadv}
1422     @category{dvc}
1423 */
1424 class wxDataViewProgressRenderer : public wxDataViewRenderer
1425 {
1426 public:
1427     /**
1428         The ctor.
1429     */
1430     wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
1431                                const wxString& varianttype = "long",
1432                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1433                                int align = wxDVR_DEFAULT_ALIGNMENT );
1434 };
1435
1436
1437
1438 /**
1439     @class wxDataViewSpinRenderer
1440
1441     This is a specialized renderer for rendering integer values.
1442     It supports modifying the values in-place by using a wxSpinCtrl.
1443     The renderer only support variants of type @e long.
1444
1445     @library{wxadv}
1446     @category{dvc}
1447 */
1448 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
1449 {
1450 public:
1451     /**
1452         Constructor.
1453         @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1454     */
1455     wxDataViewSpinRenderer(int min, int max,
1456                            wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1457                            int align = wxDVR_DEFAULT_ALIGNMENT);
1458 };
1459
1460
1461
1462 /**
1463     @class wxDataViewToggleRenderer
1464
1465     This class is used by wxDataViewCtrl to render toggle controls.
1466
1467     @library{wxadv}
1468     @category{dvc}
1469 */
1470 class wxDataViewToggleRenderer : public wxDataViewRenderer
1471 {
1472 public:
1473     /**
1474         The ctor.
1475     */
1476     wxDataViewToggleRenderer(const wxString& varianttype = "bool",
1477                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1478                              int align = wxDVR_DEFAULT_ALIGNMENT);
1479 };
1480
1481
1482 /**
1483     @class wxDataViewChoiceRenderer
1484
1485     This class is used by wxDataViewCtrl to render choice controls.
1486     It stores a string so that SetValue() and GetValue() operate
1487     on a variant holding a string.
1488
1489     @library{wxadv}
1490     @category{dvc}
1491 */
1492
1493 class wxDataViewChoiceRenderer: public wxDataViewRenderer
1494 {
1495 public:
1496     /**
1497         The ctor.
1498     */
1499     wxDataViewChoiceRenderer( const wxArrayString &choices,
1500                               wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1501                               int alignment = wxDVR_DEFAULT_ALIGNMENT );
1502
1503     /**
1504         Returns the choice referred to by index.
1505     */
1506     wxString GetChoice(size_t index) const;
1507
1508     /**
1509         Returns all choices.
1510     */
1511     const wxArrayString& GetChoices() const;
1512 };
1513
1514
1515 /**
1516     @class wxDataViewDateRenderer
1517
1518     This class is used by wxDataViewCtrl to render calendar controls.
1519
1520     @library{wxadv}
1521     @category{dvc}
1522 */
1523 class wxDataViewDateRenderer : public wxDataViewRenderer
1524 {
1525 public:
1526     /**
1527         The ctor.
1528     */
1529     wxDataViewDateRenderer(const wxString& varianttype = "datetime",
1530                            wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1531                            int align = wxDVR_DEFAULT_ALIGNMENT);
1532 };
1533
1534
1535
1536 /**
1537     @class wxDataViewCustomRenderer
1538
1539     You need to derive a new class from wxDataViewCustomRenderer in
1540     order to write a new renderer.
1541
1542     You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
1543     wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
1544
1545     If you want your renderer to support in-place editing then you also need to override
1546     wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
1547     and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1548
1549     Note that a special event handler will be pushed onto that editor control
1550     which handles @e \<ENTER\> and focus out events in order to end the editing.
1551
1552     @library{wxadv}
1553     @category{dvc}
1554 */
1555 class wxDataViewCustomRenderer : public wxDataViewRenderer
1556 {
1557 public:
1558     /**
1559         Constructor.
1560     */
1561     wxDataViewCustomRenderer(const wxString& varianttype = "string",
1562                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1563                              int align = -1, bool no_init = false);
1564
1565     /**
1566         Destructor.
1567     */
1568     virtual ~wxDataViewCustomRenderer();
1569
1570     /**
1571         Override this to react to double clicks or ENTER.
1572         This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1573     */
1574     virtual bool Activate( const wxRect& cell,
1575                            wxDataViewModel* model,
1576                            const wxDataViewItem & item,
1577                            unsigned int col );
1578
1579     /**
1580         Override this to create the actual editor control once editing
1581         is about to start.
1582
1583         @a parent is the parent of the editor control, @a labelRect indicates the
1584         position and size of the editor control and @a value is its initial value:
1585         @code
1586         {
1587             long l = value;
1588             return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
1589                         labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
1590         }
1591         @endcode
1592     */
1593     virtual wxControl* CreateEditorCtrl(wxWindow* parent,
1594                                         wxRect labelRect,
1595                                         const wxVariant& value);
1596
1597     /**
1598         Return the attribute to be used for rendering.
1599
1600         This function may be called from Render() implementation to use the
1601         attributes defined for the item if the renderer supports them.
1602
1603         Notice that when Render() is called, the wxDC object passed to it is
1604         already set up to use the correct attributes (e.g. its font is set to
1605         bold or italic version if wxDataViewItemAttr::GetBold() or GetItalic()
1606         returns true) so it may not be necessary to call it explicitly if you
1607         only want to render text using the items attributes.
1608
1609         @since 2.9.1
1610      */
1611     const wxDataViewItemAttr& GetAttr() const;
1612
1613     /**
1614         Return size required to show content.
1615     */
1616     virtual wxSize GetSize() const = 0;
1617
1618     /**
1619         Override this so that the renderer can get the value from the editor
1620         control (pointed to by @a editor):
1621         @code
1622         {
1623             wxSpinCtrl *sc = (wxSpinCtrl*) editor;
1624             long l = sc->GetValue();
1625             value = l;
1626             return true;
1627         }
1628         @endcode
1629     */
1630     virtual bool GetValueFromEditorCtrl(wxControl* editor,
1631                                         wxVariant& value);
1632
1633     /**
1634         Override this and make it return @true in order to
1635         indicate that this renderer supports in-place editing.
1636     */
1637     virtual bool HasEditorCtrl() const;
1638
1639     /**
1640         Override this to react to a left click.
1641         This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
1642     */
1643     virtual bool LeftClick( const wxPoint& cursor,
1644                             const wxRect& cell,
1645                             wxDataViewModel * model,
1646                             const wxDataViewItem & item,
1647                             unsigned int col );
1648
1649     /**
1650         Override this to render the cell.
1651         Before this is called, wxDataViewRenderer::SetValue was called
1652         so that this instance knows what to render.
1653     */
1654     virtual bool Render(wxRect cell, wxDC* dc, int state) = 0;
1655
1656     /**
1657         This method should be called from within Render() whenever you need to
1658         render simple text.
1659         This will ensure that the correct colour, font and vertical alignment will
1660         be chosen so the text will look the same as text drawn by native renderers.
1661     */
1662     void RenderText(const wxString& text, int xoffset, wxRect cell,
1663                     wxDC* dc, int state);
1664
1665     /**
1666         Override this to start a drag operation. Not yet supported.
1667     */
1668     virtual bool StartDrag(const wxPoint& cursor,
1669                            const wxRect& cell,
1670                            wxDataViewModel* model,
1671                            const wxDataViewItem & item,
1672                            unsigned int col);
1673 };
1674
1675
1676
1677 /**
1678     @class wxDataViewBitmapRenderer
1679
1680     This class is used by wxDataViewCtrl to render bitmap controls.
1681
1682     @library{wxadv}
1683     @category{dvc}
1684 */
1685 class wxDataViewBitmapRenderer : public wxDataViewRenderer
1686 {
1687 public:
1688     /**
1689         The ctor.
1690     */
1691     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
1692                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1693                              int align = wxDVR_DEFAULT_ALIGNMENT);
1694 };
1695
1696
1697 /**
1698     The flags used by wxDataViewColumn.
1699     Can be combined together.
1700 */
1701 enum wxDataViewColumnFlags
1702 {
1703     wxDATAVIEW_COL_RESIZABLE     = 1,
1704     wxDATAVIEW_COL_SORTABLE      = 2,
1705     wxDATAVIEW_COL_REORDERABLE   = 4,
1706     wxDATAVIEW_COL_HIDDEN        = 8
1707 };
1708
1709 /**
1710     @class wxDataViewColumn
1711
1712     This class represents a column in a wxDataViewCtrl.
1713     One wxDataViewColumn is bound to one column in the data model to which the
1714     wxDataViewCtrl has been associated.
1715
1716     An instance of wxDataViewRenderer is used by this class to render its data.
1717
1718     @library{wxadv}
1719     @category{dvc}
1720 */
1721 class wxDataViewColumn : public wxSettableHeaderColumn
1722 {
1723 public:
1724     /**
1725         Constructs a text column.
1726
1727         @param title
1728             The title of the column.
1729         @param renderer
1730             The class which will render the contents of this column.
1731         @param model_column
1732             The index of the model's column which is associated with this object.
1733         @param width
1734             The width of the column.
1735             The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1736         @param align
1737             The alignment of the column title.
1738         @param flags
1739             One or more flags of the ::wxDataViewColumnFlags enumeration.
1740     */
1741     wxDataViewColumn(const wxString& title,
1742                      wxDataViewRenderer* renderer,
1743                      unsigned int model_column,
1744                      int width = wxDVC_DEFAULT_WIDTH,
1745                      wxAlignment align = wxALIGN_CENTER,
1746                      int flags = wxDATAVIEW_COL_RESIZABLE);
1747
1748     /**
1749         Constructs a bitmap column.
1750
1751         @param bitmap
1752             The bitmap 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 wxBitmap& bitmap,
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         Returns the index of the column of the model, which this
1774         wxDataViewColumn is displaying.
1775     */
1776     unsigned int GetModelColumn() const;
1777
1778     /**
1779         Returns the owning wxDataViewCtrl.
1780     */
1781     wxDataViewCtrl* GetOwner() const;
1782
1783     /**
1784         Returns the renderer of this wxDataViewColumn.
1785
1786         @see wxDataViewRenderer.
1787     */
1788     wxDataViewRenderer* GetRenderer() const;
1789 };
1790
1791
1792
1793 /**
1794     @class wxDataViewListCtrl
1795
1796     This class is a wxDataViewCtrl which internally uses a wxDataViewListStore
1797     and forwards most of its API to that class.
1798
1799     The purpose of this class is to offer a simple way to display and
1800     edit a small table of data without having to write your own wxDataViewModel.
1801
1802     @code
1803        wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY );
1804
1805        listctrl->AppendToggleColumn( "Toggle" );
1806        listctrl->AppendTextColumn( "Text" );
1807
1808        wxVector<wxVariant> data;
1809        data.push_back( wxVariant(true) );
1810        data.push_back( wxVariant("row 1") );
1811        listctrl->AppendItem( data );
1812
1813        data.clear();
1814        data.push_back( wxVariant(false) );
1815        data.push_back( wxVariant("row 3") );
1816        listctrl->AppendItem( data );
1817     @endcode
1818
1819     @beginStyleTable
1820     See wxDataViewCtrl for the list of supported styles.
1821     @endStyleTable
1822
1823     @beginEventEmissionTable
1824     See wxDataViewCtrl for the list of events emitted by this class.
1825     @endEventTable
1826
1827     @library{wxadv}
1828     @category{ctrl,dvc}
1829 */
1830 class wxDataViewListCtrl: public wxDataViewCtrl
1831 {
1832 public:
1833     /**
1834         Default ctor.
1835     */
1836     wxDataViewListCtrl();
1837
1838     /**
1839         Constructor. Calls Create().
1840     */
1841     wxDataViewListCtrl( wxWindow *parent, wxWindowID id,
1842            const wxPoint& pos = wxDefaultPosition,
1843            const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES,
1844            const wxValidator& validator = wxDefaultValidator );
1845
1846     /**
1847         Destructor. Deletes the image list if any.
1848     */
1849     ~wxDataViewListCtrl();
1850
1851     /**
1852         Creates the control and a wxDataViewListStore as its internal model.
1853     */
1854     bool Create( wxWindow *parent, wxWindowID id,
1855            const wxPoint& pos = wxDefaultPosition,
1856            const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES,
1857            const wxValidator& validator = wxDefaultValidator );
1858
1859     //@{
1860     /**
1861         Returns the store.
1862     */
1863     wxDataViewListStore *GetStore();
1864     const wxDataViewListStore *GetStore() const;
1865     //@}
1866
1867     /**
1868         Returns the position of given @e item or wxNOT_FOUND if it's
1869         not a valid item.
1870
1871         @since 2.9.2
1872      */
1873     int ItemToRow(const wxDataViewItem &item) const;
1874
1875     /**
1876         Returns the wxDataViewItem at the given @e row.
1877
1878         @since 2.9.2
1879      */
1880     wxDataViewItem RowToItem(int row) const;
1881
1882     //@{
1883     /**
1884         @name Selection handling functions
1885      */
1886
1887     /**
1888         Returns index of the selected row or wxNOT_FOUND.
1889
1890         @see wxDataViewCtrl::GetSelection()
1891
1892         @since 2.9.2
1893      */
1894     int GetSelectedRow() const;
1895
1896     /**
1897         Selects given row.
1898
1899         @see wxDataViewCtrl::Select()
1900
1901         @since 2.9.2
1902      */
1903     void SelectRow(unsigned row);
1904
1905     /**
1906         Unselects given row.
1907
1908         @see wxDataViewCtrl::Unselect()
1909
1910         @since 2.9.2
1911      */
1912     void UnselectRow(unsigned row);
1913
1914     /**
1915         Returns true if @a row is selected.
1916
1917         @see wxDataViewCtrl::IsSelected()
1918
1919         @since 2.9.2
1920      */
1921     bool IsRowSelected(unsigned row) const;
1922
1923     //@}
1924
1925     /**
1926         @name Column management functions
1927     */
1928     //@{
1929
1930     /**
1931         Appends a column to the control and additionally appends a
1932         column to the store with the type string.
1933     */
1934     virtual void AppendColumn( wxDataViewColumn *column );
1935
1936     /**
1937         Appends a column to the control and additionally appends a
1938         column to the list store with the type @a varianttype.
1939     */
1940     void AppendColumn( wxDataViewColumn *column, const wxString &varianttype );
1941
1942     /**
1943         Appends a text column to the control and the store.
1944
1945         See wxDataViewColumn::wxDataViewColumn for more info about
1946         the parameters.
1947     */
1948     wxDataViewColumn *AppendTextColumn( const wxString &label,
1949           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1950           int width = -1, wxAlignment align = wxALIGN_LEFT,
1951           int flags = wxDATAVIEW_COL_RESIZABLE );
1952
1953     /**
1954         Appends a toggle column to the control and the store.
1955
1956         See wxDataViewColumn::wxDataViewColumn for more info about
1957         the parameters.
1958     */
1959     wxDataViewColumn *AppendToggleColumn( const wxString &label,
1960           wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1961           int width = -1, wxAlignment align = wxALIGN_LEFT,
1962           int flags = wxDATAVIEW_COL_RESIZABLE );
1963
1964     /**
1965         Appends a progress column to the control and the store.
1966
1967         See wxDataViewColumn::wxDataViewColumn for more info about
1968         the parameters.
1969     */
1970     wxDataViewColumn *AppendProgressColumn( const wxString &label,
1971           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1972           int width = -1, wxAlignment align = wxALIGN_LEFT,
1973           int flags = wxDATAVIEW_COL_RESIZABLE );
1974
1975     /**
1976         Appends an icon-and-text column to the control and the store.
1977
1978         See wxDataViewColumn::wxDataViewColumn for more info about
1979         the parameters.
1980     */
1981     wxDataViewColumn *AppendIconTextColumn( const wxString &label,
1982           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1983           int width = -1, wxAlignment align = wxALIGN_LEFT,
1984           int flags = wxDATAVIEW_COL_RESIZABLE );
1985
1986     /**
1987         Inserts a column to the control and additionally inserts a
1988         column to the store with the type string.
1989     */
1990     virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column );
1991
1992     /**
1993         Inserts a column to the control and additionally inserts a
1994         column to the list store with the type @a varianttype.
1995     */
1996     void InsertColumn( unsigned int pos, wxDataViewColumn *column,
1997                        const wxString &varianttype );
1998
1999     /**
2000         Prepends a column to the control and additionally prepends a
2001         column to the store with the type string.
2002     */
2003     virtual void PrependColumn( wxDataViewColumn *column );
2004
2005     /**
2006         Prepends a column to the control and additionally prepends a
2007         column to the list store with the type @a varianttype.
2008     */
2009     void PrependColumn( wxDataViewColumn *column, const wxString &varianttype );
2010
2011     //@}
2012
2013
2014     /**
2015         @name Item management functions
2016     */
2017     //@{
2018
2019     /**
2020         Appends an item (=row) to the control and store.
2021     */
2022     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2023
2024     /**
2025         Prepends an item (=row) to the control and store.
2026     */
2027     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2028
2029     /**
2030         Inserts an item (=row) to the control and store.
2031     */
2032     void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
2033
2034     /**
2035         Delete the row at position @a row.
2036     */
2037     void DeleteItem( unsigned row );
2038
2039     /**
2040         Delete all items (= all rows).
2041     */
2042     void DeleteAllItems();
2043
2044     /**
2045          Sets the value in the store and update the control.
2046     */
2047     void SetValue( const wxVariant &value, unsigned int row, unsigned int col );
2048
2049     /**
2050          Returns the value from the store.
2051     */
2052     void GetValue( wxVariant &value, unsigned int row, unsigned int col );
2053
2054     /**
2055          Sets the value in the store and update the control.
2056
2057          This method assumes that the string is stored in respective
2058          column.
2059     */
2060     void SetTextValue( const wxString &value, unsigned int row, unsigned int col );
2061
2062     /**
2063          Returns the value from the store.
2064
2065          This method assumes that the string is stored in respective
2066          column.
2067     */
2068     wxString GetTextValue( unsigned int row, unsigned int col ) const;
2069
2070     /**
2071          Sets the value in the store and update the control.
2072
2073          This method assumes that the boolean value is stored in
2074          respective column.
2075     */
2076     void SetToggleValue( bool value, unsigned int row, unsigned int col );
2077
2078     /**
2079          Returns the value from the store.
2080
2081          This method assumes that the boolean value is stored in
2082          respective column.
2083     */
2084     bool GetToggleValue( unsigned int row, unsigned int col ) const;
2085
2086     //@}
2087 };
2088
2089
2090 /**
2091     @class wxDataViewTreeCtrl
2092
2093     This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
2094     and forwards most of its API to that class.
2095     Additionally, it uses a wxImageList to store a list of icons.
2096
2097     The main purpose of this class is to provide a simple upgrade path for code
2098     using wxTreeCtrl.
2099
2100     @beginStyleTable
2101     See wxDataViewCtrl for the list of supported styles.
2102     @endStyleTable
2103
2104     @beginEventEmissionTable
2105     See wxDataViewCtrl for the list of events emitted by this class.
2106     @endEventTable
2107
2108     @library{wxadv}
2109     @category{ctrl,dvc}
2110     @appearance{dataviewtreectrl.png}
2111 */
2112 class wxDataViewTreeCtrl : public wxDataViewCtrl
2113 {
2114 public:
2115     /**
2116         Default ctor.
2117     */
2118     wxDataViewTreeCtrl();
2119
2120     /**
2121         Constructor.
2122
2123         Calls Create().
2124     */
2125     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
2126                        const wxPoint& pos = wxDefaultPosition,
2127                        const wxSize& size = wxDefaultSize,
2128                        long style = wxDV_NO_HEADER | wxDV_ROW_LINES,
2129                        const wxValidator& validator = wxDefaultValidator);
2130
2131     /**
2132         Destructor. Deletes the image list if any.
2133     */
2134     virtual ~wxDataViewTreeCtrl();
2135
2136     /**
2137         Appends a container to the given @a parent.
2138     */
2139     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
2140                                    const wxString& text,
2141                                    int icon = -1,
2142                                    int expanded = -1,
2143                                    wxClientData* data = NULL);
2144
2145     /**
2146         Appends an item to the given @a parent.
2147     */
2148     wxDataViewItem AppendItem(const wxDataViewItem& parent,
2149                               const wxString& text,
2150                               int icon = -1,
2151                               wxClientData* data = NULL);
2152
2153     /**
2154         Creates the control and a wxDataViewTreeStore as its internal model.
2155
2156         The default tree column created by this method is an editable column
2157         using wxDataViewIconTextRenderer as its renderer.
2158     */
2159     bool Create(wxWindow* parent, wxWindowID id,
2160                 const wxPoint& pos = wxDefaultPosition,
2161                 const wxSize& size = wxDefaultSize,
2162                 long style = wxDV_NO_HEADER | wxDV_ROW_LINES,
2163                 const wxValidator& validator = wxDefaultValidator);
2164
2165     /**
2166         Calls the identical method from wxDataViewTreeStore.
2167     */
2168     void DeleteAllItems();
2169
2170     /**
2171         Calls the identical method from wxDataViewTreeStore.
2172     */
2173     void DeleteChildren(const wxDataViewItem& item);
2174
2175     /**
2176         Calls the identical method from wxDataViewTreeStore.
2177     */
2178     void DeleteItem(const wxDataViewItem& item);
2179
2180     /**
2181         Calls the identical method from wxDataViewTreeStore.
2182     */
2183     int GetChildCount(const wxDataViewItem& parent) const;
2184
2185     /**
2186         Returns the image list.
2187     */
2188     wxImageList* GetImageList();
2189
2190     /**
2191         Calls the identical method from wxDataViewTreeStore.
2192     */
2193     wxClientData* GetItemData(const wxDataViewItem& item) const;
2194
2195     /**
2196         Calls the identical method from wxDataViewTreeStore.
2197     */
2198     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
2199
2200     /**
2201         Calls the identical method from wxDataViewTreeStore.
2202     */
2203     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
2204
2205     /**
2206         Calls the identical method from wxDataViewTreeStore.
2207     */
2208     wxString GetItemText(const wxDataViewItem& item) const;
2209
2210     /**
2211         Calls the identical method from wxDataViewTreeStore.
2212     */
2213     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
2214                                unsigned int pos) const;
2215
2216     //@{
2217     /**
2218         Returns the store.
2219     */
2220     wxDataViewTreeStore* GetStore();
2221     const wxDataViewTreeStore* GetStore() const;
2222     //@}
2223
2224     /**
2225         Calls the same method from wxDataViewTreeStore but uses
2226         an index position in the image list instead of a wxIcon.
2227     */
2228     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
2229                                    const wxDataViewItem& previous,
2230                                    const wxString& text,
2231                                    int icon = -1,
2232                                    int expanded = -1,
2233                                    wxClientData* data = NULL);
2234
2235     /**
2236         Calls the same method from wxDataViewTreeStore but uses
2237         an index position in the image list instead of a wxIcon.
2238     */
2239     wxDataViewItem InsertItem(const wxDataViewItem& parent,
2240                               const wxDataViewItem& previous,
2241                               const wxString& text,
2242                               int icon = -1,
2243                               wxClientData* data = NULL);
2244
2245     /**
2246         Returns true if item is a container.
2247     */
2248     bool IsContainer( const wxDataViewItem& item );
2249
2250     /**
2251         Calls the same method from wxDataViewTreeStore but uses
2252         an index position in the image list instead of a wxIcon.
2253     */
2254     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
2255                                     const wxString& text,
2256                                     int icon = -1,
2257                                     int expanded = -1,
2258                                     wxClientData* data = NULL);
2259
2260     /**
2261         Calls the same method from wxDataViewTreeStore but uses
2262         an index position in the image list instead of a wxIcon.
2263     */
2264     wxDataViewItem PrependItem(const wxDataViewItem& parent,
2265                                const wxString& text,
2266                                int icon = -1,
2267                                wxClientData* data = NULL);
2268
2269     /**
2270         Sets the image list.
2271     */
2272     void SetImageList(wxImageList* imagelist);
2273
2274     /**
2275         Calls the identical method from wxDataViewTreeStore.
2276     */
2277     void SetItemData(const wxDataViewItem& item, wxClientData* data);
2278
2279     /**
2280         Calls the identical method from wxDataViewTreeStore.
2281     */
2282     void SetItemExpandedIcon(const wxDataViewItem& item,
2283                              const wxIcon& icon);
2284
2285     /**
2286         Calls the identical method from wxDataViewTreeStore.
2287     */
2288     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
2289
2290     /**
2291         Calls the identical method from wxDataViewTreeStore.
2292     */
2293     void SetItemText(const wxDataViewItem& item,
2294                      const wxString& text);
2295 };
2296
2297
2298 /**
2299     @class wxDataViewListStore
2300
2301     wxDataViewListStore is a specialised wxDataViewModel for storing
2302     a simple table of data. Since it derives from wxDataViewIndexListModel
2303     its data is be accessed by row (i.e. by index) instead of only
2304     by wxDataViewItem.
2305
2306     This class actually stores the values (therefore its name)
2307     and implements all virtual methods from the base classes so it can be
2308     used directly without having to derive any class from it, but it is
2309     mostly used from within wxDataViewListCtrl.
2310
2311     @library{wxadv}
2312     @category{dvc}
2313 */
2314
2315 class wxDataViewListStore: public wxDataViewIndexListModel
2316 {
2317 public:
2318     /**
2319         Constructor
2320     */
2321     wxDataViewListStore();
2322
2323     /**
2324         Destructor
2325     */
2326     ~wxDataViewListStore();
2327
2328     /**
2329         Prepends a data column.
2330
2331         @a variantype indicates the type of values store in the column.
2332
2333         This does not automatically fill in any (default) values in
2334         rows which exist in the store already.
2335     */
2336     void PrependColumn( const wxString &varianttype );
2337
2338     /**
2339         Inserts a data column before @a pos.
2340
2341         @a variantype indicates the type of values store in the column.
2342
2343         This does not automatically fill in any (default) values in
2344         rows which exist in the store already.
2345     */
2346     void InsertColumn( unsigned int pos, const wxString &varianttype );
2347
2348     /**
2349         Appends a data column.
2350
2351         @a variantype indicates the type of values store in the column.
2352
2353         This does not automatically fill in any (default) values in
2354         rows which exist in the store already.
2355     */
2356     void AppendColumn( const wxString &varianttype );
2357
2358     /**
2359         Appends an item (=row) and fills it with @a values.
2360
2361         The values must match the values specifies in the column
2362         in number and type. No (default) values are filled in
2363         automatically.
2364     */
2365     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2366
2367     /**
2368         Prepends an item (=row) and fills it with @a values.
2369
2370         The values must match the values specifies in the column
2371         in number and type. No (default) values are filled in
2372         automatically.
2373     */
2374     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2375
2376     /**
2377         Inserts an item (=row) and fills it with @a values.
2378
2379         The values must match the values specifies in the column
2380         in number and type. No (default) values are filled in
2381         automatically.
2382     */
2383     void InsertItem(  unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
2384
2385     /**
2386         Delete the item (=row) at position @a pos.
2387     */
2388     void DeleteItem( unsigned pos );
2389
2390     /**
2391         Delete all item (=all rows) in the store.
2392     */
2393     void DeleteAllItems();
2394
2395     /**
2396         Overridden from wxDataViewModel
2397     */
2398     virtual unsigned int GetColumnCount() const;
2399
2400     /**
2401         Overridden from wxDataViewModel
2402     */
2403     virtual wxString GetColumnType( unsigned int col ) const;
2404
2405     /**
2406         Overridden from wxDataViewIndexListModel
2407     */
2408     virtual void GetValueByRow( wxVariant &value,
2409                            unsigned int row, unsigned int col ) const;
2410
2411     /**
2412         Overridden from wxDataViewIndexListModel
2413     */
2414     virtual bool SetValueByRow( const wxVariant &value,
2415                            unsigned int row, unsigned int col );
2416 };
2417
2418
2419 /**
2420     @class wxDataViewTreeStore
2421
2422     wxDataViewTreeStore is a specialised wxDataViewModel for storing simple
2423     trees very much like wxTreeCtrl does and it offers a similar API.
2424
2425     This class actually stores the entire tree and the values (therefore its name)
2426     and implements all virtual methods from the base class so it can be used directly
2427     without having to derive any class from it, but it is mostly used from within
2428     wxDataViewTreeCtrl.
2429
2430     @library{wxadv}
2431     @category{dvc}
2432 */
2433 class wxDataViewTreeStore : public wxDataViewModel
2434 {
2435 public:
2436     /**
2437         Constructor. Creates the invisible root node internally.
2438     */
2439     wxDataViewTreeStore();
2440
2441     /**
2442         Destructor.
2443     */
2444     virtual ~wxDataViewTreeStore();
2445
2446     /**
2447         Append a container.
2448     */
2449     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
2450                                    const wxString& text,
2451                                    const wxIcon& icon = wxNullIcon,
2452                                    const wxIcon& expanded = wxNullIcon,
2453                                    wxClientData* data = NULL);
2454
2455     /**
2456         Append an item.
2457     */
2458     wxDataViewItem AppendItem(const wxDataViewItem& parent,
2459                               const wxString& text,
2460                               const wxIcon& icon = wxNullIcon,
2461                               wxClientData* data = NULL);
2462
2463     /**
2464         Delete all item in the model.
2465     */
2466     void DeleteAllItems();
2467
2468     /**
2469         Delete all children of the item, but not the item itself.
2470     */
2471     void DeleteChildren(const wxDataViewItem& item);
2472
2473     /**
2474         Delete this item.
2475     */
2476     void DeleteItem(const wxDataViewItem& item);
2477
2478     /**
2479         Return the number of children of item.
2480     */
2481     int GetChildCount(const wxDataViewItem& parent) const;
2482
2483     /**
2484         Returns the client data associated with the item.
2485     */
2486     wxClientData* GetItemData(const wxDataViewItem& item) const;
2487
2488     /**
2489         Returns the icon to display in expanded containers.
2490     */
2491     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
2492
2493     /**
2494         Returns the icon of the item.
2495     */
2496     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
2497
2498     /**
2499         Returns the text of the item.
2500     */
2501     wxString GetItemText(const wxDataViewItem& item) const;
2502
2503     /**
2504         Returns the nth child item of item.
2505     */
2506     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
2507                                unsigned int pos) const;
2508
2509     /**
2510         Inserts a container after @a previous.
2511     */
2512     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
2513                                    const wxDataViewItem& previous,
2514                                    const wxString& text,
2515                                    const wxIcon& icon = wxNullIcon,
2516                                    const wxIcon& expanded = wxNullIcon,
2517                                    wxClientData* data = NULL);
2518
2519     /**
2520         Inserts an item after @a previous.
2521     */
2522     wxDataViewItem InsertItem(const wxDataViewItem& parent,
2523                               const wxDataViewItem& previous,
2524                               const wxString& text,
2525                               const wxIcon& icon = wxNullIcon,
2526                               wxClientData* data = NULL);
2527
2528     /**
2529         Inserts a container before the first child item or @a parent.
2530     */
2531     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
2532                                     const wxString& text,
2533                                     const wxIcon& icon = wxNullIcon,
2534                                     const wxIcon& expanded = wxNullIcon,
2535                                     wxClientData* data = NULL);
2536
2537     /**
2538         Inserts an item before the first child item or @a parent.
2539     */
2540     wxDataViewItem PrependItem(const wxDataViewItem& parent,
2541                                const wxString& text,
2542                                const wxIcon& icon = wxNullIcon,
2543                                wxClientData* data = NULL);
2544
2545     /**
2546         Sets the client data associated with the item.
2547     */
2548     void SetItemData(const wxDataViewItem& item, wxClientData* data);
2549
2550     /**
2551         Sets the expanded icon for the item.
2552     */
2553     void SetItemExpandedIcon(const wxDataViewItem& item,
2554                              const wxIcon& icon);
2555
2556     /**
2557         Sets the icon for the item.
2558     */
2559     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
2560 };
2561
2562
2563 /**
2564     @class wxDataViewIconText
2565
2566     wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
2567     This class can be converted to and from a wxVariant.
2568
2569     @library{wxadv}
2570     @category{dvc}
2571 */
2572 class wxDataViewIconText : public wxObject
2573 {
2574 public:
2575     //@{
2576     /**
2577         Constructor.
2578     */
2579     wxDataViewIconText(const wxString& text = wxEmptyString,
2580                        const wxIcon& icon = wxNullIcon);
2581     wxDataViewIconText(const wxDataViewIconText& other);
2582     //@}
2583
2584     /**
2585         Gets the icon.
2586     */
2587     const wxIcon& GetIcon() const;
2588
2589     /**
2590         Gets the text.
2591     */
2592     wxString GetText() const;
2593
2594     /**
2595         Set the icon.
2596     */
2597     void SetIcon(const wxIcon& icon);
2598
2599     /**
2600         Set the text.
2601     */
2602     void SetText(const wxString& text);
2603 };
2604
2605
2606
2607 /**
2608     @class wxDataViewEvent
2609
2610     This is the event class for the wxDataViewCtrl notifications.
2611
2612     @beginEventTable{wxDataViewEvent}
2613     @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
2614            Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
2615     @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
2616            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
2617     @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
2618            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
2619     @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
2620            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
2621     @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
2622            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
2623     @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
2624            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
2625     @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
2626            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
2627     @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
2628            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
2629     @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
2630            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
2631     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
2632            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
2633     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
2634            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
2635     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
2636            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
2637     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
2638            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
2639     @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
2640            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
2641     @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
2642            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
2643     @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
2644            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
2645     @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
2646            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
2647     @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
2648            Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
2649     @endEventTable
2650
2651     @library{wxadv}
2652     @category{events,dvc}
2653 */
2654 class wxDataViewEvent : public wxNotifyEvent
2655 {
2656 public:
2657     /**
2658         Constructor. Typically used by wxWidgets internals only.
2659     */
2660     wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
2661                     int winid = 0);
2662
2663     /**
2664         Returns the position of the column in the control or -1
2665         if no column field was set by the event emitter.
2666     */
2667     int GetColumn() const;
2668
2669     /**
2670         Returns a pointer to the wxDataViewColumn from which
2671         the event was emitted or @NULL.
2672     */
2673     wxDataViewColumn* GetDataViewColumn() const;
2674
2675     /**
2676         Returns the wxDataViewModel associated with the event.
2677     */
2678     wxDataViewModel* GetModel() const;
2679
2680     /**
2681         Returns the position of a context menu event in screen coordinates.
2682     */
2683     wxPoint GetPosition() const;
2684
2685     /**
2686         Returns a reference to a value.
2687     */
2688     const wxVariant& GetValue() const;
2689
2690     /**
2691         Sets the column index associated with this event.
2692     */
2693     void SetColumn(int col);
2694
2695     /**
2696         For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
2697     */
2698     void SetDataViewColumn(wxDataViewColumn* col);
2699
2700     /**
2701         Sets the dataview model associated with this event.
2702     */
2703     void SetModel(wxDataViewModel* model);
2704
2705     /**
2706         Sets the value associated with this event.
2707     */
2708     void SetValue(const wxVariant& value);
2709
2710     /**
2711         Set wxDataObject for data transfer within a drag operation.
2712     */
2713     void SetDataObject( wxDataObject *obj );
2714
2715     /**
2716         Used internally. Gets associated wxDataObject for data transfer
2717         within a drag operation.
2718     */
2719     wxDataObject *GetDataObject() const;
2720
2721     /**
2722         Used internally. Sets the wxDataFormat during a drop operation.
2723     */
2724     void SetDataFormat( const wxDataFormat &format );
2725
2726     /**
2727         Gets the wxDataFormat during a drop operation.
2728     */
2729     wxDataFormat GetDataFormat() const;
2730
2731     /**
2732         Used internally. Sets the data size for a drop data transfer.
2733     */
2734     void SetDataSize( size_t size );
2735
2736     /**
2737         Gets the data size for a drop data transfer.
2738     */
2739     size_t GetDataSize() const;
2740
2741     /**
2742         Used internally. Sets the data buffer for a drop data transfer.
2743     */
2744     void SetDataBuffer( void* buf );
2745
2746     /**
2747         Gets the data buffer for a drop data transfer.
2748     */
2749     void *GetDataBuffer() const;
2750
2751     /**
2752         Return the first row that will be displayed.
2753     */
2754     int GetCacheFrom() const;
2755
2756     /**
2757         Return the last row that will be displayed.
2758     */
2759     int GetCacheTo() const;
2760 };
2761