interface/wx/dataview.h

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