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