interface/wx/dataview.h

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