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