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