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