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 wxObjectRefData
  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 wxObjectRefData
  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);
 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_EDITING_STARTED(id, func)}
 534            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
 535     @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
 536            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
 537     @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
 538            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
 539     @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
 540            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
 541     @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
 542            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
 543     @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
 544            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
 545     @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
 546            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
 547     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
 548            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
 549     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
 550            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
 551     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
 552            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
 553     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
 554            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
 555     @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
 556            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
 557     @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
 558            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
 559     @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
 560            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
 561     @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
 562            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
 563     @endEventTable
 564
 565     @library{wxadv}
 566     @category{ctrl,dvc}
 567     @appearance{dataviewctrl.png}
 568 */
 569 class wxDataViewCtrl : public wxControl
 570 {
 571 public:
 572     /**
 573         Default Constructor.
 574     */
 575     wxDataViewCtrl();
 576
 577     /**
 578         Constructor. Calls Create().
 579     */
 580     wxDataViewCtrl(wxWindow* parent, wxWindowID id,
 581                    const wxPoint& pos = wxDefaultPosition,
 582                    const wxSize& size = wxDefaultSize,
 583                    long style = 0,
 584                    const wxValidator& validator = wxDefaultValidator);
 585
 586     /**
 587         Destructor.
 588     */
 589     virtual ~wxDataViewCtrl();
 590
 591     /**
 592         Appends a wxDataViewColumn to the control. Returns @true on success.
 593
 594         Note that there is a number of short cut methods which implicitly create
 595         a wxDataViewColumn and a wxDataViewRenderer for it (see below).
 596     */
 597     virtual bool AppendColumn(wxDataViewColumn* col);
 598
 599     /**
 600         Prepends a wxDataViewColumn to the control. Returns @true on success.
 601
 602         Note that there is a number of short cut methods which implicitly create
 603         a wxDataViewColumn and a wxDataViewRenderer for it.
 604     */
 605     virtual bool PrependColumn(wxDataViewColumn* col);
 606
 607     /**
 608         Inserts a wxDataViewColumn to the control. Returns @true on success.
 609     */
 610     virtual bool InsertColumn(unsigned int pos, wxDataViewColumn* col);
 611
 612     //@{
 613     /**
 614         Appends a column for rendering a bitmap. Returns the wxDataViewColumn
 615         created in the function or @NULL on failure.
 616     */
 617     wxDataViewColumn* AppendBitmapColumn(const wxString& label,
 618                                          unsigned int model_column,
 619                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 620                                          int width = -1,
 621                                          wxAlignment align = wxALIGN_CENTER,
 622                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 623     wxDataViewColumn* AppendBitmapColumn(const wxBitmap& label,
 624                                          unsigned int model_column,
 625                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 626                                          int width = -1,
 627                                          wxAlignment align = wxALIGN_CENTER,
 628                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 629     //@}
 630
 631     //@{
 632     /**
 633         Appends a column for rendering a date. Returns the wxDataViewColumn
 634         created in the function or @NULL on failure.
 635
 636         @note The @a align parameter is applied to both the column header and
 637               the column renderer.
 638     */
 639     wxDataViewColumn* AppendDateColumn(const wxString& label,
 640                                        unsigned int model_column,
 641                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
 642                                        int width = -1,
 643                                        wxAlignment align = wxALIGN_NOT,
 644                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 645     wxDataViewColumn* AppendDateColumn(const wxBitmap& label,
 646                                        unsigned int model_column,
 647                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
 648                                        int width = -1,
 649                                        wxAlignment align = wxALIGN_NOT,
 650                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 651     //@}
 652
 653     //@{
 654     /**
 655         Appends a column for rendering text with an icon. Returns the wxDataViewColumn
 656         created in the function or @NULL on failure.
 657         This method uses the wxDataViewIconTextRenderer class.
 658
 659         @note The @a align parameter is applied to both the column header and
 660               the column renderer.
 661     */
 662     wxDataViewColumn* AppendIconTextColumn(const wxString& label,
 663                                            unsigned int model_column,
 664                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 665                                            int width = -1,
 666                                            wxAlignment align = wxALIGN_NOT,
 667                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 668     wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label,
 669                                            unsigned int model_column,
 670                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 671                                            int width = -1,
 672                                            wxAlignment align = wxALIGN_NOT,
 673                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 674     //@}
 675
 676     //@{
 677     /**
 678         Appends a column for rendering a progress indicator. Returns the
 679         wxDataViewColumn created in the function or @NULL on failure.
 680
 681         @note The @a align parameter is applied to both the column header and
 682               the column renderer.
 683     */
 684     wxDataViewColumn* AppendProgressColumn(const wxString& label,
 685                                            unsigned int model_column,
 686                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 687                                            int width = 80,
 688                                            wxAlignment align = wxALIGN_CENTER,
 689                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 690     wxDataViewColumn* AppendProgressColumn(const wxBitmap& label,
 691                                            unsigned int model_column,
 692                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 693                                            int width = 80,
 694                                            wxAlignment align = wxALIGN_CENTER,
 695                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 696     //@}
 697
 698     //@{
 699     /**
 700         Appends a column for rendering text. Returns the wxDataViewColumn
 701         created in the function or @NULL on failure.
 702
 703         @note The @a align parameter is applied to both the column header and
 704               the column renderer.
 705     */
 706     wxDataViewColumn* AppendTextColumn(const wxString& label,
 707                                        unsigned int model_column,
 708                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 709                                        int width = -1,
 710                                        wxAlignment align = wxALIGN_NOT,
 711                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 712     wxDataViewColumn* AppendTextColumn(const wxBitmap& label,
 713                                        unsigned int model_column,
 714                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 715                                        int width = -1,
 716                                        wxAlignment align = wxALIGN_NOT,
 717                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 718     //@}
 719
 720     //@{
 721     /**
 722         Appends a column for rendering a toggle. Returns the wxDataViewColumn
 723         created in the function or @NULL on failure.
 724
 725         @note The @a align parameter is applied to both the column header and
 726               the column renderer.
 727     */
 728     wxDataViewColumn* AppendToggleColumn(const wxString& label,
 729                                          unsigned int model_column,
 730                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 731                                          int width = 30,
 732                                          wxAlignment align = wxALIGN_CENTER,
 733                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 734     wxDataViewColumn* AppendToggleColumn(const wxBitmap& label,
 735                                          unsigned int model_column,
 736                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 737                                          int width = 30,
 738                                          wxAlignment align = wxALIGN_CENTER,
 739                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 740     //@}
 741
 742     /**
 743         Associates a wxDataViewModel with the control.
 744         This increases the reference count of the model by 1.
 745     */
 746     virtual bool AssociateModel(wxDataViewModel* model);
 747
 748     /**
 749         Removes all columns.
 750     */
 751     virtual bool ClearColumns();
 752
 753     /**
 754         Collapses the item.
 755     */
 756     virtual void Collapse(const wxDataViewItem& item);
 757
 758     /**
 759         Create the control. Useful for two step creation.
 760     */
 761     bool Create(wxWindow* parent, wxWindowID id,
 762                 const wxPoint& pos = wxDefaultPosition,
 763                 const wxSize& size = wxDefaultSize,
 764                 long style = 0,
 765                 const wxValidator& validator = wxDefaultValidator);
 766
 767     /**
 768         Deletes given column.
 769     */
 770     virtual bool DeleteColumn(wxDataViewColumn* column);
 771
 772     /**
 773        Enable drag operations using the given @a format.
 774     */
 775     virtual bool EnableDragSource( const wxDataFormat &format );
 776
 777     /**
 778        Enable drop operations using the given @a format.
 779     */
 780     virtual bool EnableDropTarget( const wxDataFormat &format );
 781
 782     /**
 783         Call this to ensure that the given item is visible.
 784     */
 785     virtual void EnsureVisible(const wxDataViewItem& item,
 786                                const wxDataViewColumn* column = NULL);
 787
 788     /**
 789         Expands the item.
 790     */
 791     virtual void Expand(const wxDataViewItem& item);
 792
 793     /**
 794        Expands all ancestors of the @a item. This method also
 795        ensures that the item itself as well as all ancestor
 796        items have been read from the model by the control.
 797     */
 798     virtual void ExpandAncestors( const wxDataViewItem & item );
 799
 800     /**
 801         Returns pointer to the column. @a pos refers to the position in the
 802         control which may change after reordering columns by the user.
 803     */
 804     virtual wxDataViewColumn* GetColumn(unsigned int pos) const;
 805
 806     /**
 807         Returns the number of columns.
 808     */
 809     virtual unsigned int GetColumnCount() const;
 810
 811     /**
 812         Returns the position of the column or -1 if not found in the control.
 813     */
 814     virtual int GetColumnPosition(const wxDataViewColumn* column) const;
 815
 816     /**
 817         Returns column containing the expanders.
 818     */
 819     wxDataViewColumn* GetExpanderColumn() const;
 820
 821     /**
 822         Returns indentation.
 823     */
 824     int GetIndent() const;
 825
 826     /**
 827         Returns item rect.
 828     */
 829     virtual wxRect GetItemRect(const wxDataViewItem& item,
 830                                const wxDataViewColumn* col = NULL) const;
 831
 832     /**
 833         Returns pointer to the data model associated with the control (if any).
 834     */
 835     wxDataViewModel* GetModel();
 836
 837     /**
 838         Returns first selected item or an invalid item if none is selected.
 839     */
 840     virtual wxDataViewItem GetSelection() const;
 841
 842     /**
 843         Fills @a sel with currently selected items and returns their number.
 844     */
 845     virtual int GetSelections(wxDataViewItemArray& sel) const;
 846
 847     /**
 848         Returns the wxDataViewColumn currently responsible for sorting
 849         or @NULL if none has been selected.
 850     */
 851     virtual wxDataViewColumn* GetSortingColumn() const;
 852
 853     /**
 854         Hittest.
 855     */
 856     virtual void HitTest(const wxPoint& point, wxDataViewItem& item,
 857                          wxDataViewColumn*& col) const;
 858
 859     /**
 860         Return @true if the item is expanded.
 861     */
 862     virtual bool IsExpanded(const wxDataViewItem& item) const;
 863
 864     /**
 865         Return @true if the item is selected.
 866     */
 867     virtual bool IsSelected(const wxDataViewItem& item) const;
 868
 869     /**
 870         Select the given item.
 871     */
 872     virtual void Select(const wxDataViewItem& item);
 873
 874     /**
 875         Select all items.
 876     */
 877     virtual void SelectAll();
 878
 879     /**
 880         Set which column shall contain the tree-like expanders.
 881     */
 882     void SetExpanderColumn(wxDataViewColumn* col);
 883
 884     /**
 885         Sets the indendation.
 886     */
 887     void SetIndent(int indent);
 888
 889     /**
 890         Sets the selection to the array of wxDataViewItems.
 891     */
 892     virtual void SetSelections(const wxDataViewItemArray& sel);
 893
 894     /**
 895         Unselect the given item.
 896     */
 897     virtual void Unselect(const wxDataViewItem& item);
 898
 899     /**
 900         Unselect all item.
 901         This method only has effect if multiple selections are allowed.
 902     */
 903     virtual void UnselectAll();
 904 };
 905
 906
 907
 908 /**
 909     @class wxDataViewModelNotifier
 910
 911     A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors
 912     its notification interface.
 913     See the documentation of that class for further information.
 914
 915     @library{wxadv}
 916     @category{dvc}
 917 */
 918 class wxDataViewModelNotifier
 919 {
 920 public:
 921     /**
 922         Constructor.
 923     */
 924     wxDataViewModelNotifier();
 925
 926     /**
 927         Destructor.
 928     */
 929     virtual ~wxDataViewModelNotifier();
 930
 931     /**
 932         Called by owning model.
 933     */
 934     virtual bool Cleared() = 0;
 935
 936     /**
 937         Get owning wxDataViewModel.
 938     */
 939     wxDataViewModel* GetOwner() const;
 940
 941     /**
 942         Called by owning model.
 943     */
 944     virtual bool ItemAdded(const wxDataViewItem& parent,
 945                            const wxDataViewItem& item) = 0;
 946
 947     /**
 948         Called by owning model.
 949     */
 950     virtual bool ItemChanged(const wxDataViewItem& item) = 0;
 951
 952     /**
 953         Called by owning model.
 954     */
 955     virtual bool ItemDeleted(const wxDataViewItem& parent,
 956                              const wxDataViewItem& item) = 0;
 957
 958     /**
 959         Called by owning model.
 960     */
 961     virtual bool ItemsAdded(const wxDataViewItem& parent,
 962                             const wxDataViewItemArray& items);
 963
 964     /**
 965         Called by owning model.
 966     */
 967     virtual bool ItemsChanged(const wxDataViewItemArray& items);
 968
 969     /**
 970         Called by owning model.
 971     */
 972     virtual bool ItemsDeleted(const wxDataViewItem& parent,
 973                               const wxDataViewItemArray& items);
 974
 975     /**
 976         Called by owning model.
 977     */
 978     virtual void Resort() = 0;
 979
 980     /**
 981         Set owner of this notifier. Used internally.
 982     */
 983     void SetOwner(wxDataViewModel* owner);
 984
 985     /**
 986         Called by owning model.
 987     */
 988     virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0;
 989 };
 990
 991
 992 /**
 993     The mode of a data-view cell; see wxDataViewRenderer for more info.
 994 */
 995 enum wxDataViewCellMode
 996 {
 997     wxDATAVIEW_CELL_INERT,
 998
 999     /**
1000         Indicates that the user can double click the cell and something will
1001         happen (e.g. a window for editing a date will pop up).
1002     */
1003     wxDATAVIEW_CELL_ACTIVATABLE,
1004
1005     /**
1006         Indicates that the user can edit the data in-place, i.e. an control
1007         will show up after a slow click on the cell. This behaviour is best
1008         known from changing the filename in most file managers etc.
1009     */
1010     wxDATAVIEW_CELL_EDITABLE
1011 };
1012
1013 /**
1014     The values of this enum controls how a wxDataViewRenderer should display
1015     its contents in a cell.
1016 */
1017 enum wxDataViewCellRenderState
1018 {
1019     wxDATAVIEW_CELL_SELECTED    = 1,
1020     wxDATAVIEW_CELL_PRELIT      = 2,
1021     wxDATAVIEW_CELL_INSENSITIVE = 4,
1022     wxDATAVIEW_CELL_FOCUSED     = 8
1023 };
1024
1025 /**
1026     @class wxDataViewRenderer
1027
1028     This class is used by wxDataViewCtrl to render the individual cells.
1029     One instance of a renderer class is owned by a wxDataViewColumn.
1030     There is a number of ready-to-use renderers provided:
1031     - wxDataViewTextRenderer,
1032     - wxDataViewTextRendererAttr,
1033     - wxDataViewIconTextRenderer,
1034     - wxDataViewToggleRenderer,
1035     - wxDataViewProgressRenderer,
1036     - wxDataViewBitmapRenderer,
1037     - wxDataViewDateRenderer,
1038     - wxDataViewSpinRenderer.
1039
1040     Additionally, the user can write own renderers by deriving from
1041     wxDataViewCustomRenderer.
1042
1043     The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1044     by the constructors respectively controls what actions the cell data allows
1045     and how the renderer should display its contents in a cell.
1046
1047     @library{wxadv}
1048     @category{dvc}
1049 */
1050 class wxDataViewRenderer : public wxObject
1051 {
1052 public:
1053     /**
1054         Constructor.
1055     */
1056     wxDataViewRenderer(const wxString& varianttype,
1057                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1058                        int align = wxDVR_DEFAULT_ALIGNMENT );
1059
1060     /**
1061         Returns the alignment. See SetAlignment()
1062     */
1063     virtual int GetAlignment() const;
1064
1065     /**
1066         Returns the cell mode.
1067     */
1068     virtual wxDataViewCellMode GetMode() const;
1069
1070     /**
1071         Returns pointer to the owning wxDataViewColumn.
1072     */
1073     wxDataViewColumn* GetOwner() const;
1074
1075     /**
1076         This methods retrieves the value from the renderer in order to
1077         transfer the value back to the data model.
1078
1079         Returns @false on failure.
1080     */
1081     virtual bool GetValue(wxVariant& value) const = 0;
1082
1083     /**
1084         Returns a string with the type of the wxVariant supported by this renderer.
1085     */
1086     wxString GetVariantType() const;
1087
1088     /**
1089         Sets the alignment of the renderer's content.
1090         The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1091         should have the same alignment as the column header.
1092
1093         The method is not implemented under OS X and the renderer always aligns
1094         its contents as the column header on that platform. The other platforms
1095         support both vertical and horizontal alignment.
1096     */
1097     virtual void SetAlignment( int align );
1098     /**
1099         Sets the owning wxDataViewColumn.
1100         This is usually called from within wxDataViewColumn.
1101     */
1102     void SetOwner(wxDataViewColumn* owner);
1103
1104     /**
1105         Set the value of the renderer (and thus its cell) to @a value.
1106         The internal code will then render this cell with this data.
1107     */
1108     virtual bool SetValue(const wxVariant& value) = 0;
1109
1110     /**
1111         Before data is committed to the data model, it is passed to this
1112         method where it can be checked for validity. This can also be
1113         used for checking a valid range or limiting the user input in
1114         a certain aspect (e.g. max number of characters or only alphanumeric
1115         input, ASCII only etc.). Return @false if the value is not valid.
1116
1117         Please note that due to implementation limitations, this validation
1118         is done after the editing control already is destroyed and the
1119         editing process finished.
1120     */
1121     virtual bool Validate(wxVariant& value);
1122 };
1123
1124
1125
1126 /**
1127     @class wxDataViewTextRenderer
1128
1129     wxDataViewTextRenderer is used for rendering text.
1130     It supports in-place editing if desired.
1131
1132     @library{wxadv}
1133     @category{dvc}
1134 */
1135 class wxDataViewTextRenderer : public wxDataViewRenderer
1136 {
1137 public:
1138     /**
1139         The ctor.
1140     */
1141     wxDataViewTextRenderer(const wxString& varianttype = "string",
1142                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1143                            int align = wxDVR_DEFAULT_ALIGNMENT );
1144 };
1145
1146
1147
1148 /**
1149     @class wxDataViewIconTextRenderer
1150
1151     The wxDataViewIconTextRenderer class is used to display text with
1152     a small icon next to it as it is typically done in a file manager.
1153
1154     This classes uses the wxDataViewIconText helper class to store its data.
1155     wxDataViewIonText can be converted to and from a wxVariant using the left shift
1156     operator.
1157
1158     @library{wxadv}
1159     @category{dvc}
1160 */
1161 class wxDataViewIconTextRenderer : public wxDataViewRenderer
1162 {
1163 public:
1164     /**
1165         The ctor.
1166     */
1167     wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
1168                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1169                                int align = wxDVR_DEFAULT_ALIGNMENT );
1170 };
1171
1172
1173
1174 /**
1175     @class wxDataViewProgressRenderer
1176
1177     This class is used by wxDataViewCtrl to render progress bars.
1178
1179     @library{wxadv}
1180     @category{dvc}
1181 */
1182 class wxDataViewProgressRenderer : public wxDataViewRenderer
1183 {
1184 public:
1185     /**
1186         The ctor.
1187     */
1188     wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
1189                                const wxString& varianttype = "long",
1190                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1191                                int align = wxDVR_DEFAULT_ALIGNMENT );
1192 };
1193
1194
1195
1196 /**
1197     @class wxDataViewSpinRenderer
1198
1199     This is a specialized renderer for rendering integer values.
1200     It supports modifying the values in-place by using a wxSpinCtrl.
1201     The renderer only support variants of type @e long.
1202
1203     @library{wxadv}
1204     @category{dvc}
1205 */
1206 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
1207 {
1208 public:
1209     /**
1210         Constructor.
1211         @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1212     */
1213     wxDataViewSpinRenderer(int min, int max,
1214                            wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1215                            int align = wxDVR_DEFAULT_ALIGNMENT);
1216 };
1217
1218
1219
1220 /**
1221     @class wxDataViewToggleRenderer
1222
1223     This class is used by wxDataViewCtrl to render toggle controls.
1224
1225     @library{wxadv}
1226     @category{dvc}
1227 */
1228 class wxDataViewToggleRenderer : public wxDataViewRenderer
1229 {
1230 public:
1231     /**
1232         The ctor.
1233     */
1234     wxDataViewToggleRenderer(const wxString& varianttype = "bool",
1235                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1236                              int align = wxDVR_DEFAULT_ALIGNMENT);
1237 };
1238
1239
1240
1241 /**
1242     @class wxDataViewDateRenderer
1243
1244     This class is used by wxDataViewCtrl to render calendar controls.
1245
1246     @library{wxadv}
1247     @category{dvc}
1248 */
1249 class wxDataViewDateRenderer : public wxDataViewRenderer
1250 {
1251 public:
1252     /**
1253         The ctor.
1254     */
1255     wxDataViewDateRenderer(const wxString& varianttype = "datetime",
1256                            wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1257                            int align = wxDVR_DEFAULT_ALIGNMENT);
1258 };
1259
1260
1261
1262 /**
1263     @class wxDataViewTextRendererAttr
1264
1265     The same as wxDataViewTextRenderer but with support for font attributes.
1266     Font attributes are currently only supported under GTK+ and MSW.
1267
1268     @see wxDataViewModel::GetAttr and wxDataViewItemAttr.
1269
1270     @library{wxadv}
1271     @category{dvc}
1272 */
1273 class wxDataViewTextRendererAttr : public wxDataViewTextRenderer
1274 {
1275 public:
1276     /**
1277         The ctor.
1278     */
1279     wxDataViewTextRendererAttr(const wxString& varianttype = "string",
1280                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1281                                int align = wxDVR_DEFAULT_ALIGNMENT);
1282 };
1283
1284
1285
1286 /**
1287     @class wxDataViewCustomRenderer
1288
1289     You need to derive a new class from wxDataViewCustomRenderer in
1290     order to write a new renderer.
1291
1292     You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
1293     wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
1294
1295     If you want your renderer to support in-place editing then you also need to override
1296     wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
1297     and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1298
1299     Note that a special event handler will be pushed onto that editor control
1300     which handles @e \<ENTER\> and focus out events in order to end the editing.
1301
1302     @library{wxadv}
1303     @category{dvc}
1304 */
1305 class wxDataViewCustomRenderer : public wxDataViewRenderer
1306 {
1307 public:
1308     /**
1309         Constructor.
1310     */
1311     wxDataViewCustomRenderer(const wxString& varianttype = "string",
1312                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1313                              int align = -1, bool no_init = false);
1314
1315     /**
1316         Destructor.
1317     */
1318     virtual ~wxDataViewCustomRenderer();
1319
1320     /**
1321         Override this to react to double clicks or ENTER.
1322         This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1323     */
1324     virtual bool Activate( wxRect cell,
1325                            wxDataViewModel* model,
1326                            const wxDataViewItem & item,
1327                            unsigned int col );
1328
1329     /**
1330         Override this to create the actual editor control once editing
1331         is about to start.
1332
1333         @a parent is the parent of the editor control, @a labelRect indicates the
1334         position and size of the editor control and @a value is its initial value:
1335         @code
1336         {
1337             long l = value;
1338             return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
1339                         labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
1340         }
1341         @endcode
1342     */
1343     virtual wxControl* CreateEditorCtrl(wxWindow* parent,
1344                                         wxRect labelRect,
1345                                         const wxVariant& value);
1346
1347     /**
1348         Create DC on request. Internal.
1349     */
1350     virtual wxDC* GetDC();
1351
1352     /**
1353         Return size required to show content.
1354     */
1355     virtual wxSize GetSize() const = 0;
1356
1357     /**
1358         Overrride this so that the renderer can get the value from the editor
1359         control (pointed to by @a editor):
1360         @code
1361         {
1362             wxSpinCtrl *sc = (wxSpinCtrl*) editor;
1363             long l = sc->GetValue();
1364             value = l;
1365             return true;
1366         }
1367         @endcode
1368     */
1369     virtual bool GetValueFromEditorCtrl(wxControl* editor,
1370                                         wxVariant& value);
1371
1372     /**
1373         Override this and make it return @true in order to
1374         indicate that this renderer supports in-place editing.
1375     */
1376     virtual bool HasEditorCtrl();
1377
1378     /**
1379         Overrride this to react to a left click.
1380         This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
1381     */
1382     virtual bool LeftClick( wxPoint cursor,
1383                             wxRect cell,
1384                             wxDataViewModel * model,
1385                             const wxDataViewItem & item,
1386                             unsigned int col );
1387
1388     /**
1389         Override this to render the cell.
1390         Before this is called, wxDataViewRenderer::SetValue was called
1391         so that this instance knows what to render.
1392     */
1393     virtual bool Render(wxRect cell, wxDC* dc, int state) = 0;
1394
1395     /**
1396         This method should be called from within Render() whenever you need to
1397         render simple text.
1398         This will ensure that the correct colour, font and vertical alignment will
1399         be chosen so the text will look the same as text drawn by native renderers.
1400     */
1401     void RenderText(const wxString& text, int xoffset, wxRect cell,
1402                     wxDC* dc, int state);
1403
1404     /**
1405         Overrride this to start a drag operation. Not yet supported.
1406     */
1407     virtual bool StartDrag(wxPoint cursor, wxRect cell,
1408                            wxDataViewModel* model,
1409                            const wxDataViewItem & item,
1410                            unsigned int col);
1411 };
1412
1413
1414
1415 /**
1416     @class wxDataViewBitmapRenderer
1417
1418     This class is used by wxDataViewCtrl to render bitmap controls.
1419
1420     @library{wxadv}
1421     @category{dvc}
1422 */
1423 class wxDataViewBitmapRenderer : public wxDataViewRenderer
1424 {
1425 public:
1426     /**
1427         The ctor.
1428     */
1429     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
1430                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1431                              int align = wxDVR_DEFAULT_ALIGNMENT);
1432 };
1433
1434
1435 /**
1436     The flags used by wxDataViewColumn.
1437     Can be combined together.
1438 */
1439 enum wxDataViewColumnFlags
1440 {
1441     wxDATAVIEW_COL_RESIZABLE     = 1,
1442     wxDATAVIEW_COL_SORTABLE      = 2,
1443     wxDATAVIEW_COL_REORDERABLE   = 4,
1444     wxDATAVIEW_COL_HIDDEN        = 8
1445 };
1446
1447 /**
1448     @class wxDataViewColumn
1449
1450     This class represents a column in a wxDataViewCtrl.
1451     One wxDataViewColumn is bound to one column in the data model to which the
1452     wxDataViewCtrl has been associated.
1453
1454     An instance of wxDataViewRenderer is used by this class to render its data.
1455
1456     @library{wxadv}
1457     @category{dvc}
1458 */
1459 class wxDataViewColumn : public wxHeaderColumn
1460 {
1461 public:
1462     /**
1463         Constructs a text column.
1464
1465         @param title
1466             The title of the column.
1467         @param renderer
1468             The class which will render the contents of this column.
1469         @param model_column
1470             The index of the model's column which is associated with this object.
1471         @param width
1472             The width of the column.
1473             The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1474         @param align
1475             The alignment of the column title.
1476         @param flags
1477             One or more flags of the ::wxDataViewColumnFlags enumeration.
1478     */
1479     wxDataViewColumn(const wxString& title,
1480                      wxDataViewRenderer* renderer,
1481                      unsigned int model_column,
1482                      int width = wxDVC_DEFAULT_WIDTH,
1483                      wxAlignment align = wxALIGN_CENTER,
1484                      int flags = wxDATAVIEW_COL_RESIZABLE);
1485
1486     /**
1487         Constructs a bitmap column.
1488
1489         @param bitmap
1490             The bitmap of the column.
1491         @param renderer
1492             The class which will render the contents of this column.
1493         @param model_column
1494             The index of the model's column which is associated with this object.
1495         @param width
1496             The width of the column.
1497             The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1498         @param align
1499             The alignment of the column title.
1500         @param flags
1501             One or more flags of the ::wxDataViewColumnFlags enumeration.
1502     */
1503     wxDataViewColumn(const wxBitmap& bitmap,
1504                      wxDataViewRenderer* renderer,
1505                      unsigned int model_column,
1506                      int width = wxDVC_DEFAULT_WIDTH,
1507                      wxAlignment align = wxALIGN_CENTER,
1508                      int flags = wxDATAVIEW_COL_RESIZABLE);
1509
1510     /**
1511         Returns the index of the column of the model, which this
1512         wxDataViewColumn is displaying.
1513     */
1514     unsigned int GetModelColumn() const;
1515
1516     /**
1517         Returns the owning wxDataViewCtrl.
1518     */
1519     wxDataViewCtrl* GetOwner() const;
1520
1521     /**
1522         Returns the renderer of this wxDataViewColumn.
1523
1524         @see wxDataViewRenderer.
1525     */
1526     wxDataViewRenderer* GetRenderer() const;
1527 };
1528
1529
1530
1531 /**
1532     @class wxDataViewListCtrl
1533
1534     This class is a wxDataViewCtrl which internally uses a wxDataViewListStore
1535     and forwards most of its API to that class.
1536
1537     The purpose of this class is to offer a simple way to display and
1538     edit a small table of data without having to write your own wxDataViewModel.
1539
1540     @code
1541        wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY );
1542
1543        listctrl->AppendToggleColumn( "Toggle" );
1544        listctrl->AppendTextColumn( "Text" );
1545
1546        wxVector<wxVariant> data;
1547        data.push_back( wxVariant(true) );
1548        data.push_back( wxVariant("row 1") );
1549        listctrl->AppendItem( data );
1550
1551        data.clear();
1552        data.push_back( wxVariant(false) );
1553        data.push_back( wxVariant("row 3") );
1554        listctrl->AppendItem( data );
1555     @endcode
1556
1557     @beginStyleTable
1558     See wxDataViewCtrl for the list of supported styles.
1559     @endStyleTable
1560
1561     @beginEventEmissionTable
1562     See wxDataViewCtrl for the list of events emitted by this class.
1563     @endEventTable
1564
1565     @library{wxadv}
1566     @category{ctrl,dvc}
1567 */
1568 class wxDataViewListCtrl: public wxDataViewCtrl
1569 {
1570 public:
1571     /**
1572         Default ctor.
1573     */
1574     wxDataViewListCtrl();
1575
1576     /**
1577         Constructor. Calls Create().
1578     */
1579     wxDataViewListCtrl( wxWindow *parent, wxWindowID id,
1580            const wxPoint& pos = wxDefaultPosition,
1581            const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES,
1582            const wxValidator& validator = wxDefaultValidator );
1583
1584     /**
1585         Destructor. Deletes the image list if any.
1586     */
1587     ~wxDataViewListCtrl();
1588
1589     /**
1590         Creates the control and a wxDataViewListStore as its internal model.
1591     */
1592     bool Create( wxWindow *parent, wxWindowID id,
1593            const wxPoint& pos = wxDefaultPosition,
1594            const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES,
1595            const wxValidator& validator = wxDefaultValidator );
1596
1597     //@{
1598     /**
1599         Returns the store.
1600     */
1601     wxDataViewListStore *GetStore();
1602     const wxDataViewListStore *GetStore() const;
1603     //@}
1604
1605     /**
1606         @name Column management functions
1607     */
1608     //@{
1609
1610     /**
1611         Appends a column to the control and additionally appends a
1612         column to the store with the type string.
1613     */
1614     virtual void AppendColumn( wxDataViewColumn *column );
1615
1616     /**
1617         Appends a column to the control and additionally appends a
1618         column to the list store with the type @a varianttype.
1619     */
1620     void AppendColumn( wxDataViewColumn *column, const wxString &varianttype );
1621
1622     /**
1623         Appends a text column to the control and the store.
1624
1625         See wxDataViewColumn::wxDataViewColumn for more info about
1626         the parameters.
1627     */
1628     wxDataViewColumn *AppendTextColumn( const wxString &label,
1629           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1630           int width = -1, wxAlignment align = wxALIGN_LEFT,
1631           int flags = wxDATAVIEW_COL_RESIZABLE );
1632
1633     /**
1634         Appends a toggle column to the control and the store.
1635
1636         See wxDataViewColumn::wxDataViewColumn for more info about
1637         the parameters.
1638     */
1639     wxDataViewColumn *AppendToggleColumn( const wxString &label,
1640           wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1641           int width = -1, wxAlignment align = wxALIGN_LEFT,
1642           int flags = wxDATAVIEW_COL_RESIZABLE );
1643
1644     /**
1645         Appends a progress column to the control and the store.
1646
1647         See wxDataViewColumn::wxDataViewColumn for more info about
1648         the parameters.
1649     */
1650     wxDataViewColumn *AppendProgressColumn( const wxString &label,
1651           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1652           int width = -1, wxAlignment align = wxALIGN_LEFT,
1653           int flags = wxDATAVIEW_COL_RESIZABLE );
1654
1655     /**
1656         Appends an icon-and-text column to the control and the store.
1657
1658         See wxDataViewColumn::wxDataViewColumn for more info about
1659         the parameters.
1660     */
1661     wxDataViewColumn *AppendIconTextColumn( const wxString &label,
1662           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1663           int width = -1, wxAlignment align = wxALIGN_LEFT,
1664           int flags = wxDATAVIEW_COL_RESIZABLE );
1665
1666     /**
1667         Inserts a column to the control and additionally inserts a
1668         column to the store with the type string.
1669     */
1670     virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column );
1671
1672     /**
1673         Inserts a column to the control and additionally inserts a
1674         column to the list store with the type @a varianttype.
1675     */
1676     void InsertColumn( unsigned int pos, wxDataViewColumn *column,
1677                        const wxString &varianttype );
1678
1679     /**
1680         Prepends a column to the control and additionally prepends a
1681         column to the store with the type string.
1682     */
1683     virtual void PrependColumn( wxDataViewColumn *column );
1684
1685     /**
1686         Prepends a column to the control and additionally prepends a
1687         column to the list store with the type @a varianttype.
1688     */
1689     void PrependColumn( wxDataViewColumn *column, const wxString &varianttype );
1690
1691     //@}
1692
1693
1694     /**
1695         @name Item management functions
1696     */
1697     //@{
1698
1699     /**
1700         Appends an item (=row) to the control and store.
1701     */
1702     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
1703
1704     /**
1705         Prepends an item (=row) to the control and store.
1706     */
1707     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
1708
1709     /**
1710         Inserts an item (=row) to the control and store.
1711     */
1712     void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
1713
1714     /**
1715         Delete the row at position @a row.
1716     */
1717     void DeleteItem( unsigned row );
1718
1719     /**
1720         Delete all items (= all rows).
1721     */
1722     void DeleteAllItems();
1723
1724     /**
1725          Sets the value in the store and update the control.
1726     */
1727     void SetValue( const wxVariant &value, unsigned int row, unsigned int col );
1728
1729     /**
1730          Returns the value from the store.
1731     */
1732     void GetValue( wxVariant &value, unsigned int row, unsigned int col );
1733
1734     /**
1735          Sets the value in the store and update the control.
1736
1737          This method assumes that the a string is stored in respective
1738          column.
1739     */
1740     void SetTextValue( const wxString &value, unsigned int row, unsigned int col );
1741
1742     /**
1743          Returns the value from the store.
1744
1745          This method assumes that the a string is stored in respective
1746          column.
1747     */
1748     wxString GetTextValue( unsigned int row, unsigned int col ) const;
1749
1750     /**
1751          Sets the value in the store and update the control.
1752
1753          This method assumes that the a boolean value is stored in
1754          respective column.
1755     */
1756     void SetToggleValue( bool value, unsigned int row, unsigned int col );
1757
1758     /**
1759          Returns the value from the store.
1760
1761          This method assumes that the a boolean value is stored in
1762          respective column.
1763     */
1764     bool GetToggleValue( unsigned int row, unsigned int col ) const;
1765
1766     //@}
1767 };
1768
1769
1770 /**
1771     @class wxDataViewTreeCtrl
1772
1773     This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
1774     and forwards most of its API to that class.
1775     Additionally, it uses a wxImageList to store a list of icons.
1776
1777     The main purpose of this class is to represent a possible replacement for
1778     wxTreeCtrl.
1779
1780     @beginStyleTable
1781     See wxDataViewCtrl for the list of supported styles.
1782     @endStyleTable
1783
1784     @beginEventEmissionTable
1785     See wxDataViewCtrl for the list of events emitted by this class.
1786     @endEventTable
1787
1788     @library{wxadv}
1789     @category{ctrl,dvc}
1790     @appearance{dataviewtreectrl.png}
1791 */
1792 class wxDataViewTreeCtrl : public wxDataViewCtrl
1793 {
1794 public:
1795     /**
1796         Default ctor.
1797     */
1798     wxDataViewTreeCtrl();
1799
1800     /**
1801         Constructor. Calls Create().
1802     */
1803     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
1804                        const wxPoint& pos = wxDefaultPosition,
1805                        const wxSize& size = wxDefaultSize,
1806                        long style = wxDV_NO_HEADER,
1807                        const wxValidator& validator = wxDefaultValidator);
1808
1809     /**
1810         Destructor. Deletes the image list if any.
1811     */
1812     virtual ~wxDataViewTreeCtrl();
1813
1814     /**
1815         Appends a container to the given @a parent.
1816     */
1817     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1818                                    const wxString& text,
1819                                    int icon = -1,
1820                                    int expanded = -1,
1821                                    wxClientData* data = NULL);
1822
1823     /**
1824         Appends an item to the given @a parent.
1825     */
1826     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1827                               const wxString& text,
1828                               int icon = -1,
1829                               wxClientData* data = NULL);
1830
1831     /**
1832         Creates the control and a wxDataViewTreeStore as its internal model.
1833     */
1834     bool Create(wxWindow* parent, wxWindowID id,
1835                 const wxPoint& pos = wxDefaultPosition,
1836                 const wxSize& size = wxDefaultSize,
1837                 long style = wxDV_NO_HEADER,
1838                 const wxValidator& validator = wxDefaultValidator);
1839
1840     /**
1841         Calls the identical method from wxDataViewTreeStore.
1842     */
1843     void DeleteAllItems();
1844
1845     /**
1846         Calls the identical method from wxDataViewTreeStore.
1847     */
1848     void DeleteChildren(const wxDataViewItem& item);
1849
1850     /**
1851         Calls the identical method from wxDataViewTreeStore.
1852     */
1853     void DeleteItem(const wxDataViewItem& item);
1854
1855     /**
1856         Calls the identical method from wxDataViewTreeStore.
1857     */
1858     int GetChildCount(const wxDataViewItem& parent) const;
1859
1860     /**
1861         Returns the image list.
1862     */
1863     wxImageList* GetImageList();
1864
1865     /**
1866         Calls the identical method from wxDataViewTreeStore.
1867     */
1868     wxClientData* GetItemData(const wxDataViewItem& item) const;
1869
1870     /**
1871         Calls the identical method from wxDataViewTreeStore.
1872     */
1873     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
1874
1875     /**
1876         Calls the identical method from wxDataViewTreeStore.
1877     */
1878     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
1879
1880     /**
1881         Calls the identical method from wxDataViewTreeStore.
1882     */
1883     wxString GetItemText(const wxDataViewItem& item) const;
1884
1885     /**
1886         Calls the identical method from wxDataViewTreeStore.
1887     */
1888     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1889                                unsigned int pos) const;
1890
1891     //@{
1892     /**
1893         Returns the store.
1894     */
1895     wxDataViewTreeStore* GetStore();
1896     const wxDataViewTreeStore* GetStore() const;
1897     //@}
1898
1899     /**
1900         Calls the same method from wxDataViewTreeStore but uses
1901         an index position in the image list instead of a wxIcon.
1902     */
1903     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1904                                    const wxDataViewItem& previous,
1905                                    const wxString& text,
1906                                    int icon = -1,
1907                                    int expanded = -1,
1908                                    wxClientData* data = NULL);
1909
1910     /**
1911         Calls the same method from wxDataViewTreeStore but uses
1912         an index position in the image list instead of a wxIcon.
1913     */
1914     wxDataViewItem InsertItem(const wxDataViewItem& parent,
1915                               const wxDataViewItem& previous,
1916                               const wxString& text,
1917                               int icon = -1,
1918                               wxClientData* data = NULL);
1919
1920     /**
1921         Calls the same method from wxDataViewTreeStore but uses
1922         an index position in the image list instead of a wxIcon.
1923     */
1924     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1925                                     const wxString& text,
1926                                     int icon = -1,
1927                                     int expanded = -1,
1928                                     wxClientData* data = NULL);
1929
1930     /**
1931         Calls the same method from wxDataViewTreeStore but uses
1932         an index position in the image list instead of a wxIcon.
1933     */
1934     wxDataViewItem PrependItem(const wxDataViewItem& parent,
1935                                const wxString& text,
1936                                int icon = -1,
1937                                wxClientData* data = NULL);
1938
1939     /**
1940         Sets the image list.
1941     */
1942     void SetImageList(wxImageList* imagelist);
1943
1944     /**
1945         Calls the identical method from wxDataViewTreeStore.
1946     */
1947     void SetItemData(const wxDataViewItem& item, wxClientData* data);
1948
1949     /**
1950         Calls the identical method from wxDataViewTreeStore.
1951     */
1952     void SetItemExpandedIcon(const wxDataViewItem& item,
1953                              const wxIcon& icon);
1954
1955     /**
1956         Calls the identical method from wxDataViewTreeStore.
1957     */
1958     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1959
1960     /**
1961         Calls the identical method from wxDataViewTreeStore.
1962     */
1963     void SetItemText(const wxDataViewItem& item,
1964                      const wxString& text);
1965 };
1966
1967
1968 /**
1969     @class wxDataViewListStore
1970
1971     wxDataViewListStore is a specialised wxDataViewModel for storing
1972     a simple table of data. Since it derives from wxDataViewIndexListModel
1973     its data is be accessed by row (i.e. by index) instead of only
1974     by wxDataViewItem.
1975
1976     This class actually stores the values (therefore its name)
1977     and implements all virtual methods from the base classes so it can be
1978     used directly without having to derive any class from it, but it is
1979     mostly used from within wxDataViewListCtrl.
1980
1981     @library{wxadv}
1982     @category{dvc}
1983 */
1984
1985 class wxDataViewListStore: public wxDataViewIndexListModel
1986 {
1987 public:
1988     /**
1989         Constructor
1990     */
1991     wxDataViewListStore();
1992
1993     /**
1994         Destructor
1995     */
1996     ~wxDataViewListStore();
1997
1998     /**
1999         Prepends a data column.
2000
2001         @a variantype indicates the type of values store in the column.
2002
2003         This does not automatically fill in any (default) values in
2004         rows which exist in the store already.
2005     */
2006     void PrependColumn( const wxString &varianttype );
2007
2008     /**
2009         Inserts a data column before @a pos.
2010
2011         @a variantype indicates the type of values store in the column.
2012
2013         This does not automatically fill in any (default) values in
2014         rows which exist in the store already.
2015     */
2016     void InsertColumn( unsigned int pos, const wxString &varianttype );
2017
2018     /**
2019         Appends a data column.
2020
2021         @a variantype indicates the type of values store in the column.
2022
2023         This does not automatically fill in any (default) values in
2024         rows which exist in the store already.
2025     */
2026     void AppendColumn( const wxString &varianttype );
2027
2028     /**
2029         Appends an item (=row) and fills it with @a values.
2030
2031         The values must match the values specifies in the column
2032         in number and type. No (default) values are filled in
2033         automatically.
2034     */
2035     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2036
2037     /**
2038         Prepends an item (=row) and fills it with @a values.
2039
2040         The values must match the values specifies in the column
2041         in number and type. No (default) values are filled in
2042         automatically.
2043     */
2044     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2045
2046     /**
2047         Inserts an item (=row) and fills it with @a values.
2048
2049         The values must match the values specifies in the column
2050         in number and type. No (default) values are filled in
2051         automatically.
2052     */
2053     void InsertItem(  unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
2054
2055     /**
2056         Delete the item (=row) at position @a pos.
2057     */
2058     void DeleteItem( unsigned pos );
2059
2060     /**
2061         Delete all item (=all rows) in the store.
2062     */
2063     void DeleteAllItems();
2064
2065     /**
2066         Overriden from wxDataViewModel
2067     */
2068     virtual unsigned int GetColumnCount() const;
2069
2070     /**
2071         Overriden from wxDataViewModel
2072     */
2073     virtual wxString GetColumnType( unsigned int col ) const;
2074
2075     /**
2076         Overriden from wxDataViewIndexListModel
2077     */
2078     virtual void GetValueByRow( wxVariant &value,
2079                            unsigned int row, unsigned int col ) const;
2080
2081     /**
2082         Overriden from wxDataViewIndexListModel
2083     */
2084     virtual bool SetValueByRow( const wxVariant &value,
2085                            unsigned int row, unsigned int col );
2086 };
2087
2088
2089 /**
2090     @class wxDataViewTreeStore
2091
2092     wxDataViewTreeStore is a specialised wxDataViewModel for stroing simple
2093     trees very much like wxTreeCtrl does and it offers a similar API.
2094
2095     This class actually stores the entire tree and the values (therefore its name)
2096     and implements all virtual methods from the base class so it can be used directly
2097     without having to derive any class from it, but it is mostly used from within
2098     wxDataViewTreeCtrl.
2099
2100     @library{wxadv}
2101     @category{dvc}
2102 */
2103 class wxDataViewTreeStore : public wxDataViewModel
2104 {
2105 public:
2106     /**
2107         Constructor. Creates the invisible root node internally.
2108     */
2109     wxDataViewTreeStore();
2110
2111     /**
2112         Destructor.
2113     */
2114     virtual ~wxDataViewTreeStore();
2115
2116     /**
2117         Append a container.
2118     */
2119     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
2120                                    const wxString& text,
2121                                    const wxIcon& icon = wxNullIcon,
2122                                    const wxIcon& expanded = wxNullIcon,
2123                                    wxClientData* data = NULL);
2124
2125     /**
2126         Append an item.
2127     */
2128     wxDataViewItem AppendItem(const wxDataViewItem& parent,
2129                               const wxString& text,
2130                               const wxIcon& icon = wxNullIcon,
2131                               wxClientData* data = NULL);
2132
2133     /**
2134         Delete all item in the model.
2135     */
2136     void DeleteAllItems();
2137
2138     /**
2139         Delete all children of the item, but not the item itself.
2140     */
2141     void DeleteChildren(const wxDataViewItem& item);
2142
2143     /**
2144         Delete this item.
2145     */
2146     void DeleteItem(const wxDataViewItem& item);
2147
2148     /**
2149         Return the number of children of item.
2150     */
2151     int GetChildCount(const wxDataViewItem& parent) const;
2152
2153     /**
2154         Returns the client data asoociated with the item.
2155     */
2156     wxClientData* GetItemData(const wxDataViewItem& item) const;
2157
2158     /**
2159         Returns the icon to display in expanded containers.
2160     */
2161     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
2162
2163     /**
2164         Returns the icon of the item.
2165     */
2166     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
2167
2168     /**
2169         Returns the text of the item.
2170     */
2171     wxString GetItemText(const wxDataViewItem& item) const;
2172
2173     /**
2174         Returns the nth child item of item.
2175     */
2176     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
2177                                unsigned int pos) const;
2178
2179     /**
2180         Inserts a container after @a previous.
2181     */
2182     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
2183                                    const wxDataViewItem& previous,
2184                                    const wxString& text,
2185                                    const wxIcon& icon = wxNullIcon,
2186                                    const wxIcon& expanded = wxNullIcon,
2187                                    wxClientData* data = NULL);
2188
2189     /**
2190         Inserts an item after @a previous.
2191     */
2192     wxDataViewItem InsertItem(const wxDataViewItem& parent,
2193                               const wxDataViewItem& previous,
2194                               const wxString& text,
2195                               const wxIcon& icon = wxNullIcon,
2196                               wxClientData* data = NULL);
2197
2198     /**
2199         Inserts a container before the first child item or @a parent.
2200     */
2201     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
2202                                     const wxString& text,
2203                                     const wxIcon& icon = wxNullIcon,
2204                                     const wxIcon& expanded = wxNullIcon,
2205                                     wxClientData* data = NULL);
2206
2207     /**
2208         Inserts an item before the first child item or @a parent.
2209     */
2210     wxDataViewItem PrependItem(const wxDataViewItem& parent,
2211                                const wxString& text,
2212                                const wxIcon& icon = wxNullIcon,
2213                                wxClientData* data = NULL);
2214
2215     /**
2216         Sets the client data associated with the item.
2217     */
2218     void SetItemData(const wxDataViewItem& item, wxClientData* data);
2219
2220     /**
2221         Sets the expanded icon for the item.
2222     */
2223     void SetItemExpandedIcon(const wxDataViewItem& item,
2224                              const wxIcon& icon);
2225
2226     /**
2227         Sets the icon for the item.
2228     */
2229     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
2230 };
2231
2232
2233 /**
2234     @class wxDataViewIconText
2235
2236     wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
2237     This class can be converted to and from a wxVariant.
2238
2239     @library{wxadv}
2240     @category{dvc}
2241 */
2242 class wxDataViewIconText : public wxObject
2243 {
2244 public:
2245     //@{
2246     /**
2247         Constructor.
2248     */
2249     wxDataViewIconText(const wxString& text = wxEmptyString,
2250                        const wxIcon& icon = wxNullIcon);
2251     wxDataViewIconText(const wxDataViewIconText& other);
2252     //@}
2253
2254     /**
2255         Gets the icon.
2256     */
2257     const wxIcon& GetIcon() const;
2258
2259     /**
2260         Gets the text.
2261     */
2262     wxString GetText() const;
2263
2264     /**
2265         Set the icon.
2266     */
2267     void SetIcon(const wxIcon& icon);
2268
2269     /**
2270         Set the text.
2271     */
2272     void SetText(const wxString& text);
2273 };
2274
2275
2276
2277 /**
2278     @class wxDataViewEvent
2279
2280     This is the event class for the wxDataViewCtrl notifications.
2281
2282     @beginEventTable{wxDataViewEvent}
2283     @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
2284            Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
2285     @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
2286            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
2287     @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
2288            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
2289     @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
2290            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
2291     @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
2292            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
2293     @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
2294            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
2295     @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
2296            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
2297     @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
2298            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
2299     @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
2300            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
2301     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
2302            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
2303     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
2304            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
2305     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
2306            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
2307     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
2308            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
2309     @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
2310            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
2311     @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
2312            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
2313     @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
2314            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
2315     @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
2316            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
2317     @endEventTable
2318
2319     @library{wxadv}
2320     @category{events,dvc}
2321 */
2322 class wxDataViewEvent : public wxNotifyEvent
2323 {
2324 public:
2325     /**
2326         Constructor. Typically used by wxWidgets internals only.
2327     */
2328     wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
2329                     int winid = 0);
2330
2331     /**
2332         Returns the position of the column in the control or -1
2333         if no column field was set by the event emitter.
2334     */
2335     int GetColumn() const;
2336
2337     /**
2338         Returns a pointer to the wxDataViewColumn from which
2339         the event was emitted or @NULL.
2340     */
2341     wxDataViewColumn* GetDataViewColumn() const;
2342
2343     /**
2344         Returns the wxDataViewModel associated with the event.
2345     */
2346     wxDataViewModel* GetModel() const;
2347
2348     /**
2349         Returns a the position of a context menu event in screen coordinates.
2350     */
2351     wxPoint GetPosition() const;
2352
2353     /**
2354         Returns a reference to a value.
2355     */
2356     const wxVariant& GetValue() const;
2357
2358     /**
2359         Sets the column index associated with this event.
2360     */
2361     void SetColumn(int col);
2362
2363     /**
2364         For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
2365     */
2366     void SetDataViewColumn(wxDataViewColumn* col);
2367
2368     /**
2369         Sets the dataview model associated with this event.
2370     */
2371     void SetModel(wxDataViewModel* model);
2372
2373     /**
2374         Sets the value associated with this event.
2375     */
2376     void SetValue(const wxVariant& value);
2377
2378     /**
2379         Set wxDataObject for data transfer within a drag operation.
2380     */
2381     void SetDataObject( wxDataObject *obj );
2382
2383     /**
2384         Used internally. Gets associated wxDataObject for data transfer
2385         within a drag operation.
2386     */
2387     wxDataObject *GetDataObject() const;
2388
2389     /**
2390         Used internally. Sets the wxDataFormat during a drop operation.
2391     */
2392     void SetDataFormat( const wxDataFormat &format );
2393
2394     /**
2395         Gets the wxDataFormat during a drop operation.
2396     */
2397     wxDataFormat GetDataFormat() const;
2398
2399     /**
2400         Used internally. Sets the data size for a drop data transfer.
2401     */
2402     void SetDataSize( size_t size );
2403
2404     /**
2405         Gets the data size for a drop data transfer.
2406     */
2407     size_t GetDataSize() const;
2408
2409     /**
2410         Used internally. Sets the data buffer for a drop data transfer.
2411     */
2412     void SetDataBuffer( void* buf );
2413
2414     /**
2415         Gets the data buffer for a drop data transfer.
2416     */
2417     void *GetDataBuffer() const;
2418 };
2419