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