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     - wxDataViewIconTextRenderer,
1037     - wxDataViewToggleRenderer,
1038     - wxDataViewProgressRenderer,
1039     - wxDataViewBitmapRenderer,
1040     - wxDataViewDateRenderer,
1041     - wxDataViewSpinRenderer.
1042
1043     Additionally, the user can write own renderers by deriving from
1044     wxDataViewCustomRenderer.
1045
1046     The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1047     by the constructors respectively controls what actions the cell data allows
1048     and how the renderer should display its contents in a cell.
1049
1050     @library{wxadv}
1051     @category{dvc}
1052 */
1053 class wxDataViewRenderer : public wxObject
1054 {
1055 public:
1056     /**
1057         Constructor.
1058     */
1059     wxDataViewRenderer(const wxString& varianttype,
1060                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1061                        int align = wxDVR_DEFAULT_ALIGNMENT );
1062
1063     /**
1064         Returns the alignment. See SetAlignment()
1065     */
1066     virtual int GetAlignment() const;
1067
1068     /**
1069         Returns the cell mode.
1070     */
1071     virtual wxDataViewCellMode GetMode() const;
1072
1073     /**
1074         Returns pointer to the owning wxDataViewColumn.
1075     */
1076     wxDataViewColumn* GetOwner() const;
1077
1078     /**
1079         This methods retrieves the value from the renderer in order to
1080         transfer the value back to the data model.
1081
1082         Returns @false on failure.
1083     */
1084     virtual bool GetValue(wxVariant& value) const = 0;
1085
1086     /**
1087         Returns a string with the type of the wxVariant supported by this renderer.
1088     */
1089     wxString GetVariantType() const;
1090
1091     /**
1092         Sets the alignment of the renderer's content.
1093         The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1094         should have the same alignment as the column header.
1095
1096         The method is not implemented under OS X and the renderer always aligns
1097         its contents as the column header on that platform. The other platforms
1098         support both vertical and horizontal alignment.
1099     */
1100     virtual void SetAlignment( int align );
1101     /**
1102         Sets the owning wxDataViewColumn.
1103         This is usually called from within wxDataViewColumn.
1104     */
1105     void SetOwner(wxDataViewColumn* owner);
1106
1107     /**
1108         Set the value of the renderer (and thus its cell) to @a value.
1109         The internal code will then render this cell with this data.
1110     */
1111     virtual bool SetValue(const wxVariant& value) = 0;
1112
1113     /**
1114         Before data is committed to the data model, it is passed to this
1115         method where it can be checked for validity. This can also be
1116         used for checking a valid range or limiting the user input in
1117         a certain aspect (e.g. max number of characters or only alphanumeric
1118         input, ASCII only etc.). Return @false if the value is not valid.
1119
1120         Please note that due to implementation limitations, this validation
1121         is done after the editing control already is destroyed and the
1122         editing process finished.
1123     */
1124     virtual bool Validate(wxVariant& value);
1125 };
1126
1127
1128
1129 /**
1130     @class wxDataViewTextRenderer
1131
1132     wxDataViewTextRenderer is used for rendering text.
1133     It supports in-place editing if desired.
1134
1135     @library{wxadv}
1136     @category{dvc}
1137 */
1138 class wxDataViewTextRenderer : public wxDataViewRenderer
1139 {
1140 public:
1141     /**
1142         The ctor.
1143     */
1144     wxDataViewTextRenderer(const wxString& varianttype = "string",
1145                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1146                            int align = wxDVR_DEFAULT_ALIGNMENT );
1147 };
1148
1149
1150
1151 /**
1152     @class wxDataViewIconTextRenderer
1153
1154     The wxDataViewIconTextRenderer class is used to display text with
1155     a small icon next to it as it is typically done in a file manager.
1156
1157     This classes uses the wxDataViewIconText helper class to store its data.
1158     wxDataViewIonText can be converted to and from a wxVariant using the left shift
1159     operator.
1160
1161     @library{wxadv}
1162     @category{dvc}
1163 */
1164 class wxDataViewIconTextRenderer : public wxDataViewRenderer
1165 {
1166 public:
1167     /**
1168         The ctor.
1169     */
1170     wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
1171                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1172                                int align = wxDVR_DEFAULT_ALIGNMENT );
1173 };
1174
1175
1176
1177 /**
1178     @class wxDataViewProgressRenderer
1179
1180     This class is used by wxDataViewCtrl to render progress bars.
1181
1182     @library{wxadv}
1183     @category{dvc}
1184 */
1185 class wxDataViewProgressRenderer : public wxDataViewRenderer
1186 {
1187 public:
1188     /**
1189         The ctor.
1190     */
1191     wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
1192                                const wxString& varianttype = "long",
1193                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1194                                int align = wxDVR_DEFAULT_ALIGNMENT );
1195 };
1196
1197
1198
1199 /**
1200     @class wxDataViewSpinRenderer
1201
1202     This is a specialized renderer for rendering integer values.
1203     It supports modifying the values in-place by using a wxSpinCtrl.
1204     The renderer only support variants of type @e long.
1205
1206     @library{wxadv}
1207     @category{dvc}
1208 */
1209 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
1210 {
1211 public:
1212     /**
1213         Constructor.
1214         @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1215     */
1216     wxDataViewSpinRenderer(int min, int max,
1217                            wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1218                            int align = wxDVR_DEFAULT_ALIGNMENT);
1219 };
1220
1221
1222
1223 /**
1224     @class wxDataViewToggleRenderer
1225
1226     This class is used by wxDataViewCtrl to render toggle controls.
1227
1228     @library{wxadv}
1229     @category{dvc}
1230 */
1231 class wxDataViewToggleRenderer : public wxDataViewRenderer
1232 {
1233 public:
1234     /**
1235         The ctor.
1236     */
1237     wxDataViewToggleRenderer(const wxString& varianttype = "bool",
1238                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1239                              int align = wxDVR_DEFAULT_ALIGNMENT);
1240 };
1241
1242
1243
1244 /**
1245     @class wxDataViewDateRenderer
1246
1247     This class is used by wxDataViewCtrl to render calendar controls.
1248
1249     @library{wxadv}
1250     @category{dvc}
1251 */
1252 class wxDataViewDateRenderer : public wxDataViewRenderer
1253 {
1254 public:
1255     /**
1256         The ctor.
1257     */
1258     wxDataViewDateRenderer(const wxString& varianttype = "datetime",
1259                            wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1260                            int align = wxDVR_DEFAULT_ALIGNMENT);
1261 };
1262
1263
1264
1265 /**
1266     @class wxDataViewCustomRenderer
1267
1268     You need to derive a new class from wxDataViewCustomRenderer in
1269     order to write a new renderer.
1270
1271     You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
1272     wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
1273
1274     If you want your renderer to support in-place editing then you also need to override
1275     wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
1276     and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1277
1278     Note that a special event handler will be pushed onto that editor control
1279     which handles @e \<ENTER\> and focus out events in order to end the editing.
1280
1281     @library{wxadv}
1282     @category{dvc}
1283 */
1284 class wxDataViewCustomRenderer : public wxDataViewRenderer
1285 {
1286 public:
1287     /**
1288         Constructor.
1289     */
1290     wxDataViewCustomRenderer(const wxString& varianttype = "string",
1291                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1292                              int align = -1, bool no_init = false);
1293
1294     /**
1295         Destructor.
1296     */
1297     virtual ~wxDataViewCustomRenderer();
1298
1299     /**
1300         Override this to react to double clicks or ENTER.
1301         This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1302     */
1303     virtual bool Activate( wxRect cell,
1304                            wxDataViewModel* model,
1305                            const wxDataViewItem & item,
1306                            unsigned int col );
1307
1308     /**
1309         Override this to create the actual editor control once editing
1310         is about to start.
1311
1312         @a parent is the parent of the editor control, @a labelRect indicates the
1313         position and size of the editor control and @a value is its initial value:
1314         @code
1315         {
1316             long l = value;
1317             return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
1318                         labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
1319         }
1320         @endcode
1321     */
1322     virtual wxControl* CreateEditorCtrl(wxWindow* parent,
1323                                         wxRect labelRect,
1324                                         const wxVariant& value);
1325
1326     /**
1327         Create DC on request. Internal.
1328     */
1329     virtual wxDC* GetDC();
1330
1331     /**
1332         Return size required to show content.
1333     */
1334     virtual wxSize GetSize() const = 0;
1335
1336     /**
1337         Overrride this so that the renderer can get the value from the editor
1338         control (pointed to by @a editor):
1339         @code
1340         {
1341             wxSpinCtrl *sc = (wxSpinCtrl*) editor;
1342             long l = sc->GetValue();
1343             value = l;
1344             return true;
1345         }
1346         @endcode
1347     */
1348     virtual bool GetValueFromEditorCtrl(wxControl* editor,
1349                                         wxVariant& value);
1350
1351     /**
1352         Override this and make it return @true in order to
1353         indicate that this renderer supports in-place editing.
1354     */
1355     virtual bool HasEditorCtrl() const;
1356
1357     /**
1358         Overrride this to react to a left click.
1359         This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
1360     */
1361     virtual bool LeftClick( wxPoint cursor,
1362                             wxRect cell,
1363                             wxDataViewModel * model,
1364                             const wxDataViewItem & item,
1365                             unsigned int col );
1366
1367     /**
1368         Override this to render the cell.
1369         Before this is called, wxDataViewRenderer::SetValue was called
1370         so that this instance knows what to render.
1371     */
1372     virtual bool Render(wxRect cell, wxDC* dc, int state) = 0;
1373
1374     /**
1375         This method should be called from within Render() whenever you need to
1376         render simple text.
1377         This will ensure that the correct colour, font and vertical alignment will
1378         be chosen so the text will look the same as text drawn by native renderers.
1379     */
1380     void RenderText(const wxString& text, int xoffset, wxRect cell,
1381                     wxDC* dc, int state);
1382
1383     /**
1384         Overrride this to start a drag operation. Not yet supported.
1385     */
1386     virtual bool StartDrag(wxPoint cursor, wxRect cell,
1387                            wxDataViewModel* model,
1388                            const wxDataViewItem & item,
1389                            unsigned int col);
1390 };
1391
1392
1393
1394 /**
1395     @class wxDataViewBitmapRenderer
1396
1397     This class is used by wxDataViewCtrl to render bitmap controls.
1398
1399     @library{wxadv}
1400     @category{dvc}
1401 */
1402 class wxDataViewBitmapRenderer : public wxDataViewRenderer
1403 {
1404 public:
1405     /**
1406         The ctor.
1407     */
1408     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
1409                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1410                              int align = wxDVR_DEFAULT_ALIGNMENT);
1411 };
1412
1413
1414 /**
1415     The flags used by wxDataViewColumn.
1416     Can be combined together.
1417 */
1418 enum wxDataViewColumnFlags
1419 {
1420     wxDATAVIEW_COL_RESIZABLE     = 1,
1421     wxDATAVIEW_COL_SORTABLE      = 2,
1422     wxDATAVIEW_COL_REORDERABLE   = 4,
1423     wxDATAVIEW_COL_HIDDEN        = 8
1424 };
1425
1426 /**
1427     @class wxDataViewColumn
1428
1429     This class represents a column in a wxDataViewCtrl.
1430     One wxDataViewColumn is bound to one column in the data model to which the
1431     wxDataViewCtrl has been associated.
1432
1433     An instance of wxDataViewRenderer is used by this class to render its data.
1434
1435     @library{wxadv}
1436     @category{dvc}
1437 */
1438 class wxDataViewColumn : public wxSettableHeaderColumn
1439 {
1440 public:
1441     /**
1442         Constructs a text column.
1443
1444         @param title
1445             The title of the column.
1446         @param renderer
1447             The class which will render the contents of this column.
1448         @param model_column
1449             The index of the model's column which is associated with this object.
1450         @param width
1451             The width of the column.
1452             The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1453         @param align
1454             The alignment of the column title.
1455         @param flags
1456             One or more flags of the ::wxDataViewColumnFlags enumeration.
1457     */
1458     wxDataViewColumn(const wxString& title,
1459                      wxDataViewRenderer* renderer,
1460                      unsigned int model_column,
1461                      int width = wxDVC_DEFAULT_WIDTH,
1462                      wxAlignment align = wxALIGN_CENTER,
1463                      int flags = wxDATAVIEW_COL_RESIZABLE);
1464
1465     /**
1466         Constructs a bitmap column.
1467
1468         @param bitmap
1469             The bitmap of the column.
1470         @param renderer
1471             The class which will render the contents of this column.
1472         @param model_column
1473             The index of the model's column which is associated with this object.
1474         @param width
1475             The width of the column.
1476             The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1477         @param align
1478             The alignment of the column title.
1479         @param flags
1480             One or more flags of the ::wxDataViewColumnFlags enumeration.
1481     */
1482     wxDataViewColumn(const wxBitmap& bitmap,
1483                      wxDataViewRenderer* renderer,
1484                      unsigned int model_column,
1485                      int width = wxDVC_DEFAULT_WIDTH,
1486                      wxAlignment align = wxALIGN_CENTER,
1487                      int flags = wxDATAVIEW_COL_RESIZABLE);
1488
1489     /**
1490         Returns the index of the column of the model, which this
1491         wxDataViewColumn is displaying.
1492     */
1493     unsigned int GetModelColumn() const;
1494
1495     /**
1496         Returns the owning wxDataViewCtrl.
1497     */
1498     wxDataViewCtrl* GetOwner() const;
1499
1500     /**
1501         Returns the renderer of this wxDataViewColumn.
1502
1503         @see wxDataViewRenderer.
1504     */
1505     wxDataViewRenderer* GetRenderer() const;
1506 };
1507
1508
1509
1510 /**
1511     @class wxDataViewListCtrl
1512
1513     This class is a wxDataViewCtrl which internally uses a wxDataViewListStore
1514     and forwards most of its API to that class.
1515
1516     The purpose of this class is to offer a simple way to display and
1517     edit a small table of data without having to write your own wxDataViewModel.
1518
1519     @code
1520        wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY );
1521
1522        listctrl->AppendToggleColumn( "Toggle" );
1523        listctrl->AppendTextColumn( "Text" );
1524
1525        wxVector<wxVariant> data;
1526        data.push_back( wxVariant(true) );
1527        data.push_back( wxVariant("row 1") );
1528        listctrl->AppendItem( data );
1529
1530        data.clear();
1531        data.push_back( wxVariant(false) );
1532        data.push_back( wxVariant("row 3") );
1533        listctrl->AppendItem( data );
1534     @endcode
1535
1536     @beginStyleTable
1537     See wxDataViewCtrl for the list of supported styles.
1538     @endStyleTable
1539
1540     @beginEventEmissionTable
1541     See wxDataViewCtrl for the list of events emitted by this class.
1542     @endEventTable
1543
1544     @library{wxadv}
1545     @category{ctrl,dvc}
1546 */
1547 class wxDataViewListCtrl: public wxDataViewCtrl
1548 {
1549 public:
1550     /**
1551         Default ctor.
1552     */
1553     wxDataViewListCtrl();
1554
1555     /**
1556         Constructor. Calls Create().
1557     */
1558     wxDataViewListCtrl( wxWindow *parent, wxWindowID id,
1559            const wxPoint& pos = wxDefaultPosition,
1560            const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES,
1561            const wxValidator& validator = wxDefaultValidator );
1562
1563     /**
1564         Destructor. Deletes the image list if any.
1565     */
1566     ~wxDataViewListCtrl();
1567
1568     /**
1569         Creates the control and a wxDataViewListStore as its internal model.
1570     */
1571     bool Create( wxWindow *parent, wxWindowID id,
1572            const wxPoint& pos = wxDefaultPosition,
1573            const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES,
1574            const wxValidator& validator = wxDefaultValidator );
1575
1576     //@{
1577     /**
1578         Returns the store.
1579     */
1580     wxDataViewListStore *GetStore();
1581     const wxDataViewListStore *GetStore() const;
1582     //@}
1583
1584     /**
1585         @name Column management functions
1586     */
1587     //@{
1588
1589     /**
1590         Appends a column to the control and additionally appends a
1591         column to the store with the type string.
1592     */
1593     virtual void AppendColumn( wxDataViewColumn *column );
1594
1595     /**
1596         Appends a column to the control and additionally appends a
1597         column to the list store with the type @a varianttype.
1598     */
1599     void AppendColumn( wxDataViewColumn *column, const wxString &varianttype );
1600
1601     /**
1602         Appends a text column to the control and the store.
1603
1604         See wxDataViewColumn::wxDataViewColumn for more info about
1605         the parameters.
1606     */
1607     wxDataViewColumn *AppendTextColumn( const wxString &label,
1608           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1609           int width = -1, wxAlignment align = wxALIGN_LEFT,
1610           int flags = wxDATAVIEW_COL_RESIZABLE );
1611
1612     /**
1613         Appends a toggle column to the control and the store.
1614
1615         See wxDataViewColumn::wxDataViewColumn for more info about
1616         the parameters.
1617     */
1618     wxDataViewColumn *AppendToggleColumn( const wxString &label,
1619           wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1620           int width = -1, wxAlignment align = wxALIGN_LEFT,
1621           int flags = wxDATAVIEW_COL_RESIZABLE );
1622
1623     /**
1624         Appends a progress column to the control and the store.
1625
1626         See wxDataViewColumn::wxDataViewColumn for more info about
1627         the parameters.
1628     */
1629     wxDataViewColumn *AppendProgressColumn( const wxString &label,
1630           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1631           int width = -1, wxAlignment align = wxALIGN_LEFT,
1632           int flags = wxDATAVIEW_COL_RESIZABLE );
1633
1634     /**
1635         Appends an icon-and-text column to the control and the store.
1636
1637         See wxDataViewColumn::wxDataViewColumn for more info about
1638         the parameters.
1639     */
1640     wxDataViewColumn *AppendIconTextColumn( const wxString &label,
1641           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1642           int width = -1, wxAlignment align = wxALIGN_LEFT,
1643           int flags = wxDATAVIEW_COL_RESIZABLE );
1644
1645     /**
1646         Inserts a column to the control and additionally inserts a
1647         column to the store with the type string.
1648     */
1649     virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column );
1650
1651     /**
1652         Inserts a column to the control and additionally inserts a
1653         column to the list store with the type @a varianttype.
1654     */
1655     void InsertColumn( unsigned int pos, wxDataViewColumn *column,
1656                        const wxString &varianttype );
1657
1658     /**
1659         Prepends a column to the control and additionally prepends a
1660         column to the store with the type string.
1661     */
1662     virtual void PrependColumn( wxDataViewColumn *column );
1663
1664     /**
1665         Prepends a column to the control and additionally prepends a
1666         column to the list store with the type @a varianttype.
1667     */
1668     void PrependColumn( wxDataViewColumn *column, const wxString &varianttype );
1669
1670     //@}
1671
1672
1673     /**
1674         @name Item management functions
1675     */
1676     //@{
1677
1678     /**
1679         Appends an item (=row) to the control and store.
1680     */
1681     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
1682
1683     /**
1684         Prepends an item (=row) to the control and store.
1685     */
1686     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
1687
1688     /**
1689         Inserts an item (=row) to the control and store.
1690     */
1691     void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
1692
1693     /**
1694         Delete the row at position @a row.
1695     */
1696     void DeleteItem( unsigned row );
1697
1698     /**
1699         Delete all items (= all rows).
1700     */
1701     void DeleteAllItems();
1702
1703     /**
1704          Sets the value in the store and update the control.
1705     */
1706     void SetValue( const wxVariant &value, unsigned int row, unsigned int col );
1707
1708     /**
1709          Returns the value from the store.
1710     */
1711     void GetValue( wxVariant &value, unsigned int row, unsigned int col );
1712
1713     /**
1714          Sets the value in the store and update the control.
1715
1716          This method assumes that the a string is stored in respective
1717          column.
1718     */
1719     void SetTextValue( const wxString &value, unsigned int row, unsigned int col );
1720
1721     /**
1722          Returns the value from the store.
1723
1724          This method assumes that the a string is stored in respective
1725          column.
1726     */
1727     wxString GetTextValue( unsigned int row, unsigned int col ) const;
1728
1729     /**
1730          Sets the value in the store and update the control.
1731
1732          This method assumes that the a boolean value is stored in
1733          respective column.
1734     */
1735     void SetToggleValue( bool value, unsigned int row, unsigned int col );
1736
1737     /**
1738          Returns the value from the store.
1739
1740          This method assumes that the a boolean value is stored in
1741          respective column.
1742     */
1743     bool GetToggleValue( unsigned int row, unsigned int col ) const;
1744
1745     //@}
1746 };
1747
1748
1749 /**
1750     @class wxDataViewTreeCtrl
1751
1752     This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
1753     and forwards most of its API to that class.
1754     Additionally, it uses a wxImageList to store a list of icons.
1755
1756     The main purpose of this class is to represent a possible replacement for
1757     wxTreeCtrl.
1758
1759     @beginStyleTable
1760     See wxDataViewCtrl for the list of supported styles.
1761     @endStyleTable
1762
1763     @beginEventEmissionTable
1764     See wxDataViewCtrl for the list of events emitted by this class.
1765     @endEventTable
1766
1767     @library{wxadv}
1768     @category{ctrl,dvc}
1769     @appearance{dataviewtreectrl.png}
1770 */
1771 class wxDataViewTreeCtrl : public wxDataViewCtrl
1772 {
1773 public:
1774     /**
1775         Default ctor.
1776     */
1777     wxDataViewTreeCtrl();
1778
1779     /**
1780         Constructor. Calls Create().
1781     */
1782     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
1783                        const wxPoint& pos = wxDefaultPosition,
1784                        const wxSize& size = wxDefaultSize,
1785                        long style = wxDV_NO_HEADER,
1786                        const wxValidator& validator = wxDefaultValidator);
1787
1788     /**
1789         Destructor. Deletes the image list if any.
1790     */
1791     virtual ~wxDataViewTreeCtrl();
1792
1793     /**
1794         Appends a container to the given @a parent.
1795     */
1796     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1797                                    const wxString& text,
1798                                    int icon = -1,
1799                                    int expanded = -1,
1800                                    wxClientData* data = NULL);
1801
1802     /**
1803         Appends an item to the given @a parent.
1804     */
1805     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1806                               const wxString& text,
1807                               int icon = -1,
1808                               wxClientData* data = NULL);
1809
1810     /**
1811         Creates the control and a wxDataViewTreeStore as its internal model.
1812     */
1813     bool Create(wxWindow* parent, wxWindowID id,
1814                 const wxPoint& pos = wxDefaultPosition,
1815                 const wxSize& size = wxDefaultSize,
1816                 long style = wxDV_NO_HEADER,
1817                 const wxValidator& validator = wxDefaultValidator);
1818
1819     /**
1820         Calls the identical method from wxDataViewTreeStore.
1821     */
1822     void DeleteAllItems();
1823
1824     /**
1825         Calls the identical method from wxDataViewTreeStore.
1826     */
1827     void DeleteChildren(const wxDataViewItem& item);
1828
1829     /**
1830         Calls the identical method from wxDataViewTreeStore.
1831     */
1832     void DeleteItem(const wxDataViewItem& item);
1833
1834     /**
1835         Calls the identical method from wxDataViewTreeStore.
1836     */
1837     int GetChildCount(const wxDataViewItem& parent) const;
1838
1839     /**
1840         Returns the image list.
1841     */
1842     wxImageList* GetImageList();
1843
1844     /**
1845         Calls the identical method from wxDataViewTreeStore.
1846     */
1847     wxClientData* GetItemData(const wxDataViewItem& item) const;
1848
1849     /**
1850         Calls the identical method from wxDataViewTreeStore.
1851     */
1852     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
1853
1854     /**
1855         Calls the identical method from wxDataViewTreeStore.
1856     */
1857     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
1858
1859     /**
1860         Calls the identical method from wxDataViewTreeStore.
1861     */
1862     wxString GetItemText(const wxDataViewItem& item) const;
1863
1864     /**
1865         Calls the identical method from wxDataViewTreeStore.
1866     */
1867     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1868                                unsigned int pos) const;
1869
1870     //@{
1871     /**
1872         Returns the store.
1873     */
1874     wxDataViewTreeStore* GetStore();
1875     const wxDataViewTreeStore* GetStore() const;
1876     //@}
1877
1878     /**
1879         Calls the same method from wxDataViewTreeStore but uses
1880         an index position in the image list instead of a wxIcon.
1881     */
1882     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1883                                    const wxDataViewItem& previous,
1884                                    const wxString& text,
1885                                    int icon = -1,
1886                                    int expanded = -1,
1887                                    wxClientData* data = NULL);
1888
1889     /**
1890         Calls the same method from wxDataViewTreeStore but uses
1891         an index position in the image list instead of a wxIcon.
1892     */
1893     wxDataViewItem InsertItem(const wxDataViewItem& parent,
1894                               const wxDataViewItem& previous,
1895                               const wxString& text,
1896                               int icon = -1,
1897                               wxClientData* data = NULL);
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 PrependContainer(const wxDataViewItem& parent,
1904                                     const wxString& text,
1905                                     int icon = -1,
1906                                     int expanded = -1,
1907                                     wxClientData* data = NULL);
1908
1909     /**
1910         Calls the same method from wxDataViewTreeStore but uses
1911         an index position in the image list instead of a wxIcon.
1912     */
1913     wxDataViewItem PrependItem(const wxDataViewItem& parent,
1914                                const wxString& text,
1915                                int icon = -1,
1916                                wxClientData* data = NULL);
1917
1918     /**
1919         Sets the image list.
1920     */
1921     void SetImageList(wxImageList* imagelist);
1922
1923     /**
1924         Calls the identical method from wxDataViewTreeStore.
1925     */
1926     void SetItemData(const wxDataViewItem& item, wxClientData* data);
1927
1928     /**
1929         Calls the identical method from wxDataViewTreeStore.
1930     */
1931     void SetItemExpandedIcon(const wxDataViewItem& item,
1932                              const wxIcon& icon);
1933
1934     /**
1935         Calls the identical method from wxDataViewTreeStore.
1936     */
1937     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1938
1939     /**
1940         Calls the identical method from wxDataViewTreeStore.
1941     */
1942     void SetItemText(const wxDataViewItem& item,
1943                      const wxString& text);
1944 };
1945
1946
1947 /**
1948     @class wxDataViewListStore
1949
1950     wxDataViewListStore is a specialised wxDataViewModel for storing
1951     a simple table of data. Since it derives from wxDataViewIndexListModel
1952     its data is be accessed by row (i.e. by index) instead of only
1953     by wxDataViewItem.
1954
1955     This class actually stores the values (therefore its name)
1956     and implements all virtual methods from the base classes so it can be
1957     used directly without having to derive any class from it, but it is
1958     mostly used from within wxDataViewListCtrl.
1959
1960     @library{wxadv}
1961     @category{dvc}
1962 */
1963
1964 class wxDataViewListStore: public wxDataViewIndexListModel
1965 {
1966 public:
1967     /**
1968         Constructor
1969     */
1970     wxDataViewListStore();
1971
1972     /**
1973         Destructor
1974     */
1975     ~wxDataViewListStore();
1976
1977     /**
1978         Prepends a data column.
1979
1980         @a variantype indicates the type of values store in the column.
1981
1982         This does not automatically fill in any (default) values in
1983         rows which exist in the store already.
1984     */
1985     void PrependColumn( const wxString &varianttype );
1986
1987     /**
1988         Inserts a data column before @a pos.
1989
1990         @a variantype indicates the type of values store in the column.
1991
1992         This does not automatically fill in any (default) values in
1993         rows which exist in the store already.
1994     */
1995     void InsertColumn( unsigned int pos, const wxString &varianttype );
1996
1997     /**
1998         Appends a data column.
1999
2000         @a variantype indicates the type of values store in the column.
2001
2002         This does not automatically fill in any (default) values in
2003         rows which exist in the store already.
2004     */
2005     void AppendColumn( const wxString &varianttype );
2006
2007     /**
2008         Appends an item (=row) and fills it with @a values.
2009
2010         The values must match the values specifies in the column
2011         in number and type. No (default) values are filled in
2012         automatically.
2013     */
2014     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2015
2016     /**
2017         Prepends an item (=row) and fills it with @a values.
2018
2019         The values must match the values specifies in the column
2020         in number and type. No (default) values are filled in
2021         automatically.
2022     */
2023     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2024
2025     /**
2026         Inserts an item (=row) and fills it with @a values.
2027
2028         The values must match the values specifies in the column
2029         in number and type. No (default) values are filled in
2030         automatically.
2031     */
2032     void InsertItem(  unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
2033
2034     /**
2035         Delete the item (=row) at position @a pos.
2036     */
2037     void DeleteItem( unsigned pos );
2038
2039     /**
2040         Delete all item (=all rows) in the store.
2041     */
2042     void DeleteAllItems();
2043
2044     /**
2045         Overriden from wxDataViewModel
2046     */
2047     virtual unsigned int GetColumnCount() const;
2048
2049     /**
2050         Overriden from wxDataViewModel
2051     */
2052     virtual wxString GetColumnType( unsigned int col ) const;
2053
2054     /**
2055         Overriden from wxDataViewIndexListModel
2056     */
2057     virtual void GetValueByRow( wxVariant &value,
2058                            unsigned int row, unsigned int col ) const;
2059
2060     /**
2061         Overriden from wxDataViewIndexListModel
2062     */
2063     virtual bool SetValueByRow( const wxVariant &value,
2064                            unsigned int row, unsigned int col );
2065 };
2066
2067
2068 /**
2069     @class wxDataViewTreeStore
2070
2071     wxDataViewTreeStore is a specialised wxDataViewModel for stroing simple
2072     trees very much like wxTreeCtrl does and it offers a similar API.
2073
2074     This class actually stores the entire tree and the values (therefore its name)
2075     and implements all virtual methods from the base class so it can be used directly
2076     without having to derive any class from it, but it is mostly used from within
2077     wxDataViewTreeCtrl.
2078
2079     @library{wxadv}
2080     @category{dvc}
2081 */
2082 class wxDataViewTreeStore : public wxDataViewModel
2083 {
2084 public:
2085     /**
2086         Constructor. Creates the invisible root node internally.
2087     */
2088     wxDataViewTreeStore();
2089
2090     /**
2091         Destructor.
2092     */
2093     virtual ~wxDataViewTreeStore();
2094
2095     /**
2096         Append a container.
2097     */
2098     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
2099                                    const wxString& text,
2100                                    const wxIcon& icon = wxNullIcon,
2101                                    const wxIcon& expanded = wxNullIcon,
2102                                    wxClientData* data = NULL);
2103
2104     /**
2105         Append an item.
2106     */
2107     wxDataViewItem AppendItem(const wxDataViewItem& parent,
2108                               const wxString& text,
2109                               const wxIcon& icon = wxNullIcon,
2110                               wxClientData* data = NULL);
2111
2112     /**
2113         Delete all item in the model.
2114     */
2115     void DeleteAllItems();
2116
2117     /**
2118         Delete all children of the item, but not the item itself.
2119     */
2120     void DeleteChildren(const wxDataViewItem& item);
2121
2122     /**
2123         Delete this item.
2124     */
2125     void DeleteItem(const wxDataViewItem& item);
2126
2127     /**
2128         Return the number of children of item.
2129     */
2130     int GetChildCount(const wxDataViewItem& parent) const;
2131
2132     /**
2133         Returns the client data asoociated with the item.
2134     */
2135     wxClientData* GetItemData(const wxDataViewItem& item) const;
2136
2137     /**
2138         Returns the icon to display in expanded containers.
2139     */
2140     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
2141
2142     /**
2143         Returns the icon of the item.
2144     */
2145     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
2146
2147     /**
2148         Returns the text of the item.
2149     */
2150     wxString GetItemText(const wxDataViewItem& item) const;
2151
2152     /**
2153         Returns the nth child item of item.
2154     */
2155     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
2156                                unsigned int pos) const;
2157
2158     /**
2159         Inserts a container after @a previous.
2160     */
2161     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
2162                                    const wxDataViewItem& previous,
2163                                    const wxString& text,
2164                                    const wxIcon& icon = wxNullIcon,
2165                                    const wxIcon& expanded = wxNullIcon,
2166                                    wxClientData* data = NULL);
2167
2168     /**
2169         Inserts an item after @a previous.
2170     */
2171     wxDataViewItem InsertItem(const wxDataViewItem& parent,
2172                               const wxDataViewItem& previous,
2173                               const wxString& text,
2174                               const wxIcon& icon = wxNullIcon,
2175                               wxClientData* data = NULL);
2176
2177     /**
2178         Inserts a container before the first child item or @a parent.
2179     */
2180     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
2181                                     const wxString& text,
2182                                     const wxIcon& icon = wxNullIcon,
2183                                     const wxIcon& expanded = wxNullIcon,
2184                                     wxClientData* data = NULL);
2185
2186     /**
2187         Inserts an item before the first child item or @a parent.
2188     */
2189     wxDataViewItem PrependItem(const wxDataViewItem& parent,
2190                                const wxString& text,
2191                                const wxIcon& icon = wxNullIcon,
2192                                wxClientData* data = NULL);
2193
2194     /**
2195         Sets the client data associated with the item.
2196     */
2197     void SetItemData(const wxDataViewItem& item, wxClientData* data);
2198
2199     /**
2200         Sets the expanded icon for the item.
2201     */
2202     void SetItemExpandedIcon(const wxDataViewItem& item,
2203                              const wxIcon& icon);
2204
2205     /**
2206         Sets the icon for the item.
2207     */
2208     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
2209 };
2210
2211
2212 /**
2213     @class wxDataViewIconText
2214
2215     wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
2216     This class can be converted to and from a wxVariant.
2217
2218     @library{wxadv}
2219     @category{dvc}
2220 */
2221 class wxDataViewIconText : public wxObject
2222 {
2223 public:
2224     //@{
2225     /**
2226         Constructor.
2227     */
2228     wxDataViewIconText(const wxString& text = wxEmptyString,
2229                        const wxIcon& icon = wxNullIcon);
2230     wxDataViewIconText(const wxDataViewIconText& other);
2231     //@}
2232
2233     /**
2234         Gets the icon.
2235     */
2236     const wxIcon& GetIcon() const;
2237
2238     /**
2239         Gets the text.
2240     */
2241     wxString GetText() const;
2242
2243     /**
2244         Set the icon.
2245     */
2246     void SetIcon(const wxIcon& icon);
2247
2248     /**
2249         Set the text.
2250     */
2251     void SetText(const wxString& text);
2252 };
2253
2254
2255
2256 /**
2257     @class wxDataViewEvent
2258
2259     This is the event class for the wxDataViewCtrl notifications.
2260
2261     @beginEventTable{wxDataViewEvent}
2262     @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
2263            Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
2264     @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
2265            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
2266     @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
2267            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
2268     @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
2269            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
2270     @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
2271            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
2272     @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
2273            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
2274     @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
2275            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
2276     @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
2277            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
2278     @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
2279            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
2280     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
2281            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
2282     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
2283            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
2284     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
2285            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
2286     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
2287            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
2288     @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
2289            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
2290     @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
2291            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
2292     @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
2293            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
2294     @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
2295            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
2296     @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
2297            Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
2298     @endEventTable
2299
2300     @library{wxadv}
2301     @category{events,dvc}
2302 */
2303 class wxDataViewEvent : public wxNotifyEvent
2304 {
2305 public:
2306     /**
2307         Constructor. Typically used by wxWidgets internals only.
2308     */
2309     wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
2310                     int winid = 0);
2311
2312     /**
2313         Returns the position of the column in the control or -1
2314         if no column field was set by the event emitter.
2315     */
2316     int GetColumn() const;
2317
2318     /**
2319         Returns a pointer to the wxDataViewColumn from which
2320         the event was emitted or @NULL.
2321     */
2322     wxDataViewColumn* GetDataViewColumn() const;
2323
2324     /**
2325         Returns the wxDataViewModel associated with the event.
2326     */
2327     wxDataViewModel* GetModel() const;
2328
2329     /**
2330         Returns a the position of a context menu event in screen coordinates.
2331     */
2332     wxPoint GetPosition() const;
2333
2334     /**
2335         Returns a reference to a value.
2336     */
2337     const wxVariant& GetValue() const;
2338
2339     /**
2340         Sets the column index associated with this event.
2341     */
2342     void SetColumn(int col);
2343
2344     /**
2345         For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
2346     */
2347     void SetDataViewColumn(wxDataViewColumn* col);
2348
2349     /**
2350         Sets the dataview model associated with this event.
2351     */
2352     void SetModel(wxDataViewModel* model);
2353
2354     /**
2355         Sets the value associated with this event.
2356     */
2357     void SetValue(const wxVariant& value);
2358
2359     /**
2360         Set wxDataObject for data transfer within a drag operation.
2361     */
2362     void SetDataObject( wxDataObject *obj );
2363
2364     /**
2365         Used internally. Gets associated wxDataObject for data transfer
2366         within a drag operation.
2367     */
2368     wxDataObject *GetDataObject() const;
2369
2370     /**
2371         Used internally. Sets the wxDataFormat during a drop operation.
2372     */
2373     void SetDataFormat( const wxDataFormat &format );
2374
2375     /**
2376         Gets the wxDataFormat during a drop operation.
2377     */
2378     wxDataFormat GetDataFormat() const;
2379
2380     /**
2381         Used internally. Sets the data size for a drop data transfer.
2382     */
2383     void SetDataSize( size_t size );
2384
2385     /**
2386         Gets the data size for a drop data transfer.
2387     */
2388     size_t GetDataSize() const;
2389
2390     /**
2391         Used internally. Sets the data buffer for a drop data transfer.
2392     */
2393     void SetDataBuffer( void* buf );
2394
2395     /**
2396         Gets the data buffer for a drop data transfer.
2397     */
2398     void *GetDataBuffer() const;
2399
2400     /**
2401         Return the first row that will be displayed.
2402     */
2403     int GetCacheFrom() const;
2404
2405     /**
2406         Return the last row that will be displayed.
2407     */
2408     int GetCacheTo() const;
2409 };
2410