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