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