interface/wx/dataview.h

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