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     /**
1774         @name Selection handling functions
1775      */
1776
1777     /**
1778         Returns index of the selected row or wxNOT_FOUND.
1779
1780         @see wxDataViewCtrl::GetSelection()
1781
1782         @since 2.9.2
1783      */
1784     int GetSelectedRow() const;
1785
1786     /**
1787         Selects given row.
1788
1789         @see wxDataViewCtrl::Select()
1790
1791         @since 2.9.2
1792      */
1793     void SelectRow(unsigned row);
1794
1795     /**
1796         Unselects given row.
1797
1798         @see wxDataViewCtrl::Unselect()
1799
1800         @since 2.9.2
1801      */
1802     void UnselectRow(unsigned row);
1803
1804     /**
1805         Returns true if @a row is selected.
1806
1807         @see wxDataViewCtrl::IsSelected()
1808
1809         @since 2.9.2
1810      */
1811     bool IsRowSelected(unsigned row) const;
1812
1813     //@}
1814
1815     /**
1816         @name Column management functions
1817     */
1818     //@{
1819
1820     /**
1821         Appends a column to the control and additionally appends a
1822         column to the store with the type string.
1823     */
1824     virtual void AppendColumn( wxDataViewColumn *column );
1825
1826     /**
1827         Appends a column to the control and additionally appends a
1828         column to the list store with the type @a varianttype.
1829     */
1830     void AppendColumn( wxDataViewColumn *column, const wxString &varianttype );
1831
1832     /**
1833         Appends a text column to the control and the store.
1834
1835         See wxDataViewColumn::wxDataViewColumn for more info about
1836         the parameters.
1837     */
1838     wxDataViewColumn *AppendTextColumn( const wxString &label,
1839           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1840           int width = -1, wxAlignment align = wxALIGN_LEFT,
1841           int flags = wxDATAVIEW_COL_RESIZABLE );
1842
1843     /**
1844         Appends a toggle column to the control and the store.
1845
1846         See wxDataViewColumn::wxDataViewColumn for more info about
1847         the parameters.
1848     */
1849     wxDataViewColumn *AppendToggleColumn( const wxString &label,
1850           wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1851           int width = -1, wxAlignment align = wxALIGN_LEFT,
1852           int flags = wxDATAVIEW_COL_RESIZABLE );
1853
1854     /**
1855         Appends a progress column to the control and the store.
1856
1857         See wxDataViewColumn::wxDataViewColumn for more info about
1858         the parameters.
1859     */
1860     wxDataViewColumn *AppendProgressColumn( const wxString &label,
1861           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1862           int width = -1, wxAlignment align = wxALIGN_LEFT,
1863           int flags = wxDATAVIEW_COL_RESIZABLE );
1864
1865     /**
1866         Appends an icon-and-text column to the control and the store.
1867
1868         See wxDataViewColumn::wxDataViewColumn for more info about
1869         the parameters.
1870     */
1871     wxDataViewColumn *AppendIconTextColumn( const wxString &label,
1872           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1873           int width = -1, wxAlignment align = wxALIGN_LEFT,
1874           int flags = wxDATAVIEW_COL_RESIZABLE );
1875
1876     /**
1877         Inserts a column to the control and additionally inserts a
1878         column to the store with the type string.
1879     */
1880     virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column );
1881
1882     /**
1883         Inserts a column to the control and additionally inserts a
1884         column to the list store with the type @a varianttype.
1885     */
1886     void InsertColumn( unsigned int pos, wxDataViewColumn *column,
1887                        const wxString &varianttype );
1888
1889     /**
1890         Prepends a column to the control and additionally prepends a
1891         column to the store with the type string.
1892     */
1893     virtual void PrependColumn( wxDataViewColumn *column );
1894
1895     /**
1896         Prepends a column to the control and additionally prepends a
1897         column to the list store with the type @a varianttype.
1898     */
1899     void PrependColumn( wxDataViewColumn *column, const wxString &varianttype );
1900
1901     //@}
1902
1903
1904     /**
1905         @name Item management functions
1906     */
1907     //@{
1908
1909     /**
1910         Appends an item (=row) to the control and store.
1911     */
1912     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
1913
1914     /**
1915         Prepends an item (=row) to the control and store.
1916     */
1917     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
1918
1919     /**
1920         Inserts an item (=row) to the control and store.
1921     */
1922     void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
1923
1924     /**
1925         Delete the row at position @a row.
1926     */
1927     void DeleteItem( unsigned row );
1928
1929     /**
1930         Delete all items (= all rows).
1931     */
1932     void DeleteAllItems();
1933
1934     /**
1935          Sets the value in the store and update the control.
1936     */
1937     void SetValue( const wxVariant &value, unsigned int row, unsigned int col );
1938
1939     /**
1940          Returns the value from the store.
1941     */
1942     void GetValue( wxVariant &value, unsigned int row, unsigned int col );
1943
1944     /**
1945          Sets the value in the store and update the control.
1946
1947          This method assumes that the a string is stored in respective
1948          column.
1949     */
1950     void SetTextValue( const wxString &value, unsigned int row, unsigned int col );
1951
1952     /**
1953          Returns the value from the store.
1954
1955          This method assumes that the a string is stored in respective
1956          column.
1957     */
1958     wxString GetTextValue( unsigned int row, unsigned int col ) const;
1959
1960     /**
1961          Sets the value in the store and update the control.
1962
1963          This method assumes that the a boolean value is stored in
1964          respective column.
1965     */
1966     void SetToggleValue( bool value, unsigned int row, unsigned int col );
1967
1968     /**
1969          Returns the value from the store.
1970
1971          This method assumes that the a boolean value is stored in
1972          respective column.
1973     */
1974     bool GetToggleValue( unsigned int row, unsigned int col ) const;
1975
1976     //@}
1977 };
1978
1979
1980 /**
1981     @class wxDataViewTreeCtrl
1982
1983     This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
1984     and forwards most of its API to that class.
1985     Additionally, it uses a wxImageList to store a list of icons.
1986
1987     The main purpose of this class is to provide a simple upgrade path for code
1988     using wxTreeCtrl.
1989
1990     @beginStyleTable
1991     See wxDataViewCtrl for the list of supported styles.
1992     @endStyleTable
1993
1994     @beginEventEmissionTable
1995     See wxDataViewCtrl for the list of events emitted by this class.
1996     @endEventTable
1997
1998     @library{wxadv}
1999     @category{ctrl,dvc}
2000     @appearance{dataviewtreectrl.png}
2001 */
2002 class wxDataViewTreeCtrl : public wxDataViewCtrl
2003 {
2004 public:
2005     /**
2006         Default ctor.
2007     */
2008     wxDataViewTreeCtrl();
2009
2010     /**
2011         Constructor.
2012
2013         Calls Create().
2014     */
2015     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
2016                        const wxPoint& pos = wxDefaultPosition,
2017                        const wxSize& size = wxDefaultSize,
2018                        long style = wxDV_NO_HEADER | wxDV_ROW_LINES,
2019                        const wxValidator& validator = wxDefaultValidator);
2020
2021     /**
2022         Destructor. Deletes the image list if any.
2023     */
2024     virtual ~wxDataViewTreeCtrl();
2025
2026     /**
2027         Appends a container to the given @a parent.
2028     */
2029     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
2030                                    const wxString& text,
2031                                    int icon = -1,
2032                                    int expanded = -1,
2033                                    wxClientData* data = NULL);
2034
2035     /**
2036         Appends an item to the given @a parent.
2037     */
2038     wxDataViewItem AppendItem(const wxDataViewItem& parent,
2039                               const wxString& text,
2040                               int icon = -1,
2041                               wxClientData* data = NULL);
2042
2043     /**
2044         Creates the control and a wxDataViewTreeStore as its internal model.
2045
2046         The default tree column created by this method is an editable column
2047         using wxDataViewIconTextRenderer as its renderer.
2048     */
2049     bool Create(wxWindow* parent, wxWindowID id,
2050                 const wxPoint& pos = wxDefaultPosition,
2051                 const wxSize& size = wxDefaultSize,
2052                 long style = wxDV_NO_HEADER | wxDV_ROW_LINES,
2053                 const wxValidator& validator = wxDefaultValidator);
2054
2055     /**
2056         Calls the identical method from wxDataViewTreeStore.
2057     */
2058     void DeleteAllItems();
2059
2060     /**
2061         Calls the identical method from wxDataViewTreeStore.
2062     */
2063     void DeleteChildren(const wxDataViewItem& item);
2064
2065     /**
2066         Calls the identical method from wxDataViewTreeStore.
2067     */
2068     void DeleteItem(const wxDataViewItem& item);
2069
2070     /**
2071         Calls the identical method from wxDataViewTreeStore.
2072     */
2073     int GetChildCount(const wxDataViewItem& parent) const;
2074
2075     /**
2076         Returns the image list.
2077     */
2078     wxImageList* GetImageList();
2079
2080     /**
2081         Calls the identical method from wxDataViewTreeStore.
2082     */
2083     wxClientData* GetItemData(const wxDataViewItem& item) const;
2084
2085     /**
2086         Calls the identical method from wxDataViewTreeStore.
2087     */
2088     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
2089
2090     /**
2091         Calls the identical method from wxDataViewTreeStore.
2092     */
2093     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
2094
2095     /**
2096         Calls the identical method from wxDataViewTreeStore.
2097     */
2098     wxString GetItemText(const wxDataViewItem& item) const;
2099
2100     /**
2101         Calls the identical method from wxDataViewTreeStore.
2102     */
2103     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
2104                                unsigned int pos) const;
2105
2106     //@{
2107     /**
2108         Returns the store.
2109     */
2110     wxDataViewTreeStore* GetStore();
2111     const wxDataViewTreeStore* GetStore() const;
2112     //@}
2113
2114     /**
2115         Calls the same method from wxDataViewTreeStore but uses
2116         an index position in the image list instead of a wxIcon.
2117     */
2118     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
2119                                    const wxDataViewItem& previous,
2120                                    const wxString& text,
2121                                    int icon = -1,
2122                                    int expanded = -1,
2123                                    wxClientData* data = NULL);
2124
2125     /**
2126         Calls the same method from wxDataViewTreeStore but uses
2127         an index position in the image list instead of a wxIcon.
2128     */
2129     wxDataViewItem InsertItem(const wxDataViewItem& parent,
2130                               const wxDataViewItem& previous,
2131                               const wxString& text,
2132                               int icon = -1,
2133                               wxClientData* data = NULL);
2134
2135     /**
2136         Returns true if item is a container.
2137     */
2138     bool IsContainer( const wxDataViewItem& item );
2139
2140     /**
2141         Calls the same method from wxDataViewTreeStore but uses
2142         an index position in the image list instead of a wxIcon.
2143     */
2144     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
2145                                     const wxString& text,
2146                                     int icon = -1,
2147                                     int expanded = -1,
2148                                     wxClientData* data = NULL);
2149
2150     /**
2151         Calls the same method from wxDataViewTreeStore but uses
2152         an index position in the image list instead of a wxIcon.
2153     */
2154     wxDataViewItem PrependItem(const wxDataViewItem& parent,
2155                                const wxString& text,
2156                                int icon = -1,
2157                                wxClientData* data = NULL);
2158
2159     /**
2160         Sets the image list.
2161     */
2162     void SetImageList(wxImageList* imagelist);
2163
2164     /**
2165         Calls the identical method from wxDataViewTreeStore.
2166     */
2167     void SetItemData(const wxDataViewItem& item, wxClientData* data);
2168
2169     /**
2170         Calls the identical method from wxDataViewTreeStore.
2171     */
2172     void SetItemExpandedIcon(const wxDataViewItem& item,
2173                              const wxIcon& icon);
2174
2175     /**
2176         Calls the identical method from wxDataViewTreeStore.
2177     */
2178     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
2179
2180     /**
2181         Calls the identical method from wxDataViewTreeStore.
2182     */
2183     void SetItemText(const wxDataViewItem& item,
2184                      const wxString& text);
2185 };
2186
2187
2188 /**
2189     @class wxDataViewListStore
2190
2191     wxDataViewListStore is a specialised wxDataViewModel for storing
2192     a simple table of data. Since it derives from wxDataViewIndexListModel
2193     its data is be accessed by row (i.e. by index) instead of only
2194     by wxDataViewItem.
2195
2196     This class actually stores the values (therefore its name)
2197     and implements all virtual methods from the base classes so it can be
2198     used directly without having to derive any class from it, but it is
2199     mostly used from within wxDataViewListCtrl.
2200
2201     @library{wxadv}
2202     @category{dvc}
2203 */
2204
2205 class wxDataViewListStore: public wxDataViewIndexListModel
2206 {
2207 public:
2208     /**
2209         Constructor
2210     */
2211     wxDataViewListStore();
2212
2213     /**
2214         Destructor
2215     */
2216     ~wxDataViewListStore();
2217
2218     /**
2219         Prepends a data column.
2220
2221         @a variantype indicates the type of values store in the column.
2222
2223         This does not automatically fill in any (default) values in
2224         rows which exist in the store already.
2225     */
2226     void PrependColumn( const wxString &varianttype );
2227
2228     /**
2229         Inserts a data column before @a pos.
2230
2231         @a variantype indicates the type of values store in the column.
2232
2233         This does not automatically fill in any (default) values in
2234         rows which exist in the store already.
2235     */
2236     void InsertColumn( unsigned int pos, const wxString &varianttype );
2237
2238     /**
2239         Appends a data column.
2240
2241         @a variantype indicates the type of values store in the column.
2242
2243         This does not automatically fill in any (default) values in
2244         rows which exist in the store already.
2245     */
2246     void AppendColumn( const wxString &varianttype );
2247
2248     /**
2249         Appends an item (=row) and fills it with @a values.
2250
2251         The values must match the values specifies in the column
2252         in number and type. No (default) values are filled in
2253         automatically.
2254     */
2255     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2256
2257     /**
2258         Prepends an item (=row) and fills it with @a values.
2259
2260         The values must match the values specifies in the column
2261         in number and type. No (default) values are filled in
2262         automatically.
2263     */
2264     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2265
2266     /**
2267         Inserts an item (=row) and fills it with @a values.
2268
2269         The values must match the values specifies in the column
2270         in number and type. No (default) values are filled in
2271         automatically.
2272     */
2273     void InsertItem(  unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
2274
2275     /**
2276         Delete the item (=row) at position @a pos.
2277     */
2278     void DeleteItem( unsigned pos );
2279
2280     /**
2281         Delete all item (=all rows) in the store.
2282     */
2283     void DeleteAllItems();
2284
2285     /**
2286         Overriden from wxDataViewModel
2287     */
2288     virtual unsigned int GetColumnCount() const;
2289
2290     /**
2291         Overriden from wxDataViewModel
2292     */
2293     virtual wxString GetColumnType( unsigned int col ) const;
2294
2295     /**
2296         Overriden from wxDataViewIndexListModel
2297     */
2298     virtual void GetValueByRow( wxVariant &value,
2299                            unsigned int row, unsigned int col ) const;
2300
2301     /**
2302         Overriden from wxDataViewIndexListModel
2303     */
2304     virtual bool SetValueByRow( const wxVariant &value,
2305                            unsigned int row, unsigned int col );
2306 };
2307
2308
2309 /**
2310     @class wxDataViewTreeStore
2311
2312     wxDataViewTreeStore is a specialised wxDataViewModel for stroing simple
2313     trees very much like wxTreeCtrl does and it offers a similar API.
2314
2315     This class actually stores the entire tree and the values (therefore its name)
2316     and implements all virtual methods from the base class so it can be used directly
2317     without having to derive any class from it, but it is mostly used from within
2318     wxDataViewTreeCtrl.
2319
2320     @library{wxadv}
2321     @category{dvc}
2322 */
2323 class wxDataViewTreeStore : public wxDataViewModel
2324 {
2325 public:
2326     /**
2327         Constructor. Creates the invisible root node internally.
2328     */
2329     wxDataViewTreeStore();
2330
2331     /**
2332         Destructor.
2333     */
2334     virtual ~wxDataViewTreeStore();
2335
2336     /**
2337         Append a container.
2338     */
2339     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
2340                                    const wxString& text,
2341                                    const wxIcon& icon = wxNullIcon,
2342                                    const wxIcon& expanded = wxNullIcon,
2343                                    wxClientData* data = NULL);
2344
2345     /**
2346         Append an item.
2347     */
2348     wxDataViewItem AppendItem(const wxDataViewItem& parent,
2349                               const wxString& text,
2350                               const wxIcon& icon = wxNullIcon,
2351                               wxClientData* data = NULL);
2352
2353     /**
2354         Delete all item in the model.
2355     */
2356     void DeleteAllItems();
2357
2358     /**
2359         Delete all children of the item, but not the item itself.
2360     */
2361     void DeleteChildren(const wxDataViewItem& item);
2362
2363     /**
2364         Delete this item.
2365     */
2366     void DeleteItem(const wxDataViewItem& item);
2367
2368     /**
2369         Return the number of children of item.
2370     */
2371     int GetChildCount(const wxDataViewItem& parent) const;
2372
2373     /**
2374         Returns the client data asoociated with the item.
2375     */
2376     wxClientData* GetItemData(const wxDataViewItem& item) const;
2377
2378     /**
2379         Returns the icon to display in expanded containers.
2380     */
2381     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
2382
2383     /**
2384         Returns the icon of the item.
2385     */
2386     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
2387
2388     /**
2389         Returns the text of the item.
2390     */
2391     wxString GetItemText(const wxDataViewItem& item) const;
2392
2393     /**
2394         Returns the nth child item of item.
2395     */
2396     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
2397                                unsigned int pos) const;
2398
2399     /**
2400         Inserts a container after @a previous.
2401     */
2402     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
2403                                    const wxDataViewItem& previous,
2404                                    const wxString& text,
2405                                    const wxIcon& icon = wxNullIcon,
2406                                    const wxIcon& expanded = wxNullIcon,
2407                                    wxClientData* data = NULL);
2408
2409     /**
2410         Inserts an item after @a previous.
2411     */
2412     wxDataViewItem InsertItem(const wxDataViewItem& parent,
2413                               const wxDataViewItem& previous,
2414                               const wxString& text,
2415                               const wxIcon& icon = wxNullIcon,
2416                               wxClientData* data = NULL);
2417
2418     /**
2419         Inserts a container before the first child item or @a parent.
2420     */
2421     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
2422                                     const wxString& text,
2423                                     const wxIcon& icon = wxNullIcon,
2424                                     const wxIcon& expanded = wxNullIcon,
2425                                     wxClientData* data = NULL);
2426
2427     /**
2428         Inserts an item before the first child item or @a parent.
2429     */
2430     wxDataViewItem PrependItem(const wxDataViewItem& parent,
2431                                const wxString& text,
2432                                const wxIcon& icon = wxNullIcon,
2433                                wxClientData* data = NULL);
2434
2435     /**
2436         Sets the client data associated with the item.
2437     */
2438     void SetItemData(const wxDataViewItem& item, wxClientData* data);
2439
2440     /**
2441         Sets the expanded icon for the item.
2442     */
2443     void SetItemExpandedIcon(const wxDataViewItem& item,
2444                              const wxIcon& icon);
2445
2446     /**
2447         Sets the icon for the item.
2448     */
2449     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
2450 };
2451
2452
2453 /**
2454     @class wxDataViewIconText
2455
2456     wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
2457     This class can be converted to and from a wxVariant.
2458
2459     @library{wxadv}
2460     @category{dvc}
2461 */
2462 class wxDataViewIconText : public wxObject
2463 {
2464 public:
2465     //@{
2466     /**
2467         Constructor.
2468     */
2469     wxDataViewIconText(const wxString& text = wxEmptyString,
2470                        const wxIcon& icon = wxNullIcon);
2471     wxDataViewIconText(const wxDataViewIconText& other);
2472     //@}
2473
2474     /**
2475         Gets the icon.
2476     */
2477     const wxIcon& GetIcon() const;
2478
2479     /**
2480         Gets the text.
2481     */
2482     wxString GetText() const;
2483
2484     /**
2485         Set the icon.
2486     */
2487     void SetIcon(const wxIcon& icon);
2488
2489     /**
2490         Set the text.
2491     */
2492     void SetText(const wxString& text);
2493 };
2494
2495
2496
2497 /**
2498     @class wxDataViewEvent
2499
2500     This is the event class for the wxDataViewCtrl notifications.
2501
2502     @beginEventTable{wxDataViewEvent}
2503     @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
2504            Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
2505     @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
2506            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
2507     @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
2508            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
2509     @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
2510            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
2511     @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
2512            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
2513     @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
2514            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
2515     @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
2516            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
2517     @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
2518            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
2519     @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
2520            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
2521     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
2522            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
2523     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
2524            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
2525     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
2526            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
2527     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
2528            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
2529     @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
2530            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
2531     @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
2532            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
2533     @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
2534            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
2535     @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
2536            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
2537     @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
2538            Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
2539     @endEventTable
2540
2541     @library{wxadv}
2542     @category{events,dvc}
2543 */
2544 class wxDataViewEvent : public wxNotifyEvent
2545 {
2546 public:
2547     /**
2548         Constructor. Typically used by wxWidgets internals only.
2549     */
2550     wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
2551                     int winid = 0);
2552
2553     /**
2554         Returns the position of the column in the control or -1
2555         if no column field was set by the event emitter.
2556     */
2557     int GetColumn() const;
2558
2559     /**
2560         Returns a pointer to the wxDataViewColumn from which
2561         the event was emitted or @NULL.
2562     */
2563     wxDataViewColumn* GetDataViewColumn() const;
2564
2565     /**
2566         Returns the wxDataViewModel associated with the event.
2567     */
2568     wxDataViewModel* GetModel() const;
2569
2570     /**
2571         Returns a the position of a context menu event in screen coordinates.
2572     */
2573     wxPoint GetPosition() const;
2574
2575     /**
2576         Returns a reference to a value.
2577     */
2578     const wxVariant& GetValue() const;
2579
2580     /**
2581         Sets the column index associated with this event.
2582     */
2583     void SetColumn(int col);
2584
2585     /**
2586         For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
2587     */
2588     void SetDataViewColumn(wxDataViewColumn* col);
2589
2590     /**
2591         Sets the dataview model associated with this event.
2592     */
2593     void SetModel(wxDataViewModel* model);
2594
2595     /**
2596         Sets the value associated with this event.
2597     */
2598     void SetValue(const wxVariant& value);
2599
2600     /**
2601         Set wxDataObject for data transfer within a drag operation.
2602     */
2603     void SetDataObject( wxDataObject *obj );
2604
2605     /**
2606         Used internally. Gets associated wxDataObject for data transfer
2607         within a drag operation.
2608     */
2609     wxDataObject *GetDataObject() const;
2610
2611     /**
2612         Used internally. Sets the wxDataFormat during a drop operation.
2613     */
2614     void SetDataFormat( const wxDataFormat &format );
2615
2616     /**
2617         Gets the wxDataFormat during a drop operation.
2618     */
2619     wxDataFormat GetDataFormat() const;
2620
2621     /**
2622         Used internally. Sets the data size for a drop data transfer.
2623     */
2624     void SetDataSize( size_t size );
2625
2626     /**
2627         Gets the data size for a drop data transfer.
2628     */
2629     size_t GetDataSize() const;
2630
2631     /**
2632         Used internally. Sets the data buffer for a drop data transfer.
2633     */
2634     void SetDataBuffer( void* buf );
2635
2636     /**
2637         Gets the data buffer for a drop data transfer.
2638     */
2639     void *GetDataBuffer() const;
2640
2641     /**
2642         Return the first row that will be displayed.
2643     */
2644     int GetCacheFrom() const;
2645
2646     /**
2647         Return the last row that will be displayed.
2648     */
2649     int GetCacheTo() const;
2650 };
2651