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