interface/wx/dataview.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dataview.h
   3 // Purpose:     interface of wxDataView* classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     @class wxDataViewModel
  12
  13     wxDataViewModel is the base class for all data model to be displayed by a
  14     wxDataViewCtrl.
  15
  16     All other models derive from it and must implement its pure virtual functions
  17     in order to define a complete data model. In detail, you need to override
  18     wxDataViewModel::IsContainer, wxDataViewModel::GetParent, wxDataViewModel::GetChildren,
  19     wxDataViewModel::GetColumnCount, wxDataViewModel::GetColumnType and
  20     wxDataViewModel::GetValue in order to define the data model which acts as an
  21     interface between your actual data and the wxDataViewCtrl.
  22
  23     Since you will usually also allow the wxDataViewCtrl to change your data
  24     through its graphical interface, you will also have to override
  25     wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change
  26     to some data has been committed.
  27
  28     wxDataViewModel (as indeed the entire wxDataViewCtrl code) is using wxVariant
  29     to store data and its type in a generic way. wxVariant can be extended to contain
  30     almost any data without changes to the original class.
  31
  32     The data that is presented through this data model is expected to change at
  33     run-time. You need to inform the data model when a change happened.
  34     Depending on what happened you need to call one of the following methods:
  35     - wxDataViewModel::ValueChanged,
  36     - wxDataViewModel::ItemAdded,
  37     - wxDataViewModel::ItemDeleted,
  38     - wxDataViewModel::ItemChanged,
  39     - wxDataViewModel::Cleared.
  40
  41     There are plural forms for notification of addition, change or removal of
  42     several item at once. See:
  43     - wxDataViewModel::ItemsAdded,
  44     - wxDataViewModel::ItemsDeleted,
  45     - wxDataViewModel::ItemsChanged.
  46
  47     Note that wxDataViewModel does not define the position or index of any item
  48     in the control because different controls might display the same data differently.
  49     wxDataViewModel does provide a wxDataViewModel::Compare method which the
  50     wxDataViewCtrl may use to sort the data either in conjunction with a column
  51     header or without (see wxDataViewModel::HasDefaultCompare).
  52
  53     This class maintains a list of wxDataViewModelNotifier which link this class
  54     to the specific implementations on the supported platforms so that e.g. calling
  55     wxDataViewModel::ValueChanged on this model will just call
  56     wxDataViewModelNotifier::ValueChanged for each notifier that has been added.
  57     You can also add your own notifier in order to get informed about any changes
  58     to the data in the list model.
  59
  60     Currently wxWidgets provides the following models apart from the base model:
  61     wxDataViewIndexListModel, wxDataViewVirtualListModel, wxDataViewTreeStore,
  62     wxDataViewListStore.
  63
  64     Note that wxDataViewModel is reference counted, derives from wxRefCounter
  65     and cannot be deleted directly as it can be shared by several wxDataViewCtrls.
  66     This implies that you need to decrease the reference count after
  67     associating the model with a control like this:
  68
  69     @code
  70         wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY );
  71         wxDataViewModel *musicModel = new MyMusicModel;
  72         m_musicCtrl->AssociateModel( musicModel );
  73         musicModel->DecRef();  // avoid memory leak !!
  74
  75         // add columns now
  76     @endcode
  77
  78     @library{wxadv}
  79     @category{dvc}
  80 */
  81 class wxDataViewModel : public wxRefCounter
  82 {
  83 public:
  84     /**
  85         Constructor.
  86     */
  87     wxDataViewModel();
  88
  89     /**
  90         Adds a wxDataViewModelNotifier to the model.
  91     */
  92     void AddNotifier(wxDataViewModelNotifier* notifier);
  93
  94     /**
  95         Change the value of the given item and update the control to reflect
  96         it.
  97
  98         This function simply calls SetValue() and, if it succeeded,
  99         ValueChanged().
 100
 101         @since 2.9.1
 102
 103         @param variable
 104             The new value.
 105         @param item
 106             The item (row) to update.
 107         @param col
 108             The column to update.
 109         @return
 110             @true if both SetValue() and ValueChanged() returned @true.
 111      */
 112     bool ChangeValue(const wxVariant& variant,
 113                      const wxDataViewItem& item,
 114                      unsigned int col);
 115
 116     /**
 117         Called to inform the model that all data has been cleared.
 118         The control will reread the data from the model again.
 119     */
 120     virtual bool Cleared();
 121
 122     /**
 123         The compare function to be used by control. The default compare function
 124         sorts by container and other items separately and in ascending order.
 125         Override this for a different sorting behaviour.
 126
 127         @see HasDefaultCompare().
 128     */
 129     virtual int Compare(const wxDataViewItem& item1,
 130                         const wxDataViewItem& item2,
 131                         unsigned int column,
 132                         bool ascending) const;
 133
 134     /**
 135         Override this to indicate that the item has special font attributes.
 136         This only affects the wxDataViewTextRendererText renderer.
 137
 138         The base class version always simply returns @false.
 139
 140         @see wxDataViewItemAttr.
 141
 142         @param item
 143             The item for which the attribute is requested.
 144         @param col
 145             The column of the item for which the attribute is requested.
 146         @param attr
 147             The attribute to be filled in if the function returns @true.
 148         @return
 149             @true if this item has an attribute or @false otherwise.
 150     */
 151     virtual bool GetAttr(const wxDataViewItem& item, unsigned int col,
 152                          wxDataViewItemAttr& attr) const;
 153
 154     /**
 155         Override this so the control can query the child items of an item.
 156         Returns the number of items.
 157     */
 158     virtual unsigned int GetChildren(const wxDataViewItem& item,
 159                                      wxDataViewItemArray& children) const = 0;
 160
 161     /**
 162         Override this to indicate the number of columns in the model.
 163     */
 164     virtual unsigned int GetColumnCount() const = 0;
 165
 166     /**
 167         Override this to indicate what type of data is stored in the
 168         column specified by @a col.
 169
 170         This should return a string indicating the type of data as reported by wxVariant.
 171     */
 172     virtual wxString GetColumnType(unsigned int col) const = 0;
 173
 174     /**
 175         Override this to indicate which wxDataViewItem representing the parent
 176         of @a item or an invalid wxDataViewItem if the the root item is
 177         the parent item.
 178     */
 179     virtual wxDataViewItem GetParent(const wxDataViewItem& item) const = 0;
 180
 181     /**
 182         Override this to indicate the value of @a item.
 183         A wxVariant is used to store the data.
 184     */
 185     virtual void GetValue(wxVariant& variant, const wxDataViewItem& item,
 186                           unsigned int col) const = 0;
 187
 188     /**
 189         Override this method to indicate if a container item merely acts as a
 190         headline (or for categorisation) or if it also acts a normal item with
 191         entries for futher columns. By default returns @false.
 192     */
 193     virtual bool HasContainerColumns(const wxDataViewItem& item) const;
 194
 195     /**
 196         Override this to indicate that the model provides a default compare
 197         function that the control should use if no wxDataViewColumn has been
 198         chosen for sorting. Usually, the user clicks on a column header for
 199         sorting, the data will be sorted alphanumerically.
 200
 201         If any other order (e.g. by index or order of appearance) is required,
 202         then this should be used.
 203         See wxDataViewIndexListModel for a model which makes use of this.
 204     */
 205     virtual bool HasDefaultCompare() const;
 206
 207     /**
 208         Return true if there is a value in the given column of this item.
 209
 210         All normal items have values in all columns but the container items
 211         only show their label in the first column (@a col == 0) by default (but
 212         see HasContainerColumns()). So this function always returns true for
 213         the first column while for the other ones it returns true only if the
 214         item is not a container or HasContainerColumns() was overridden to
 215         return true for it.
 216
 217         @since 2.9.1
 218      */
 219     bool HasValue(const wxDataViewItem& item, unsigned col) const;
 220
 221     /**
 222         Override this to indicate of @a item is a container, i.e. if
 223         it can have child items.
 224     */
 225     virtual bool IsContainer(const wxDataViewItem& item) const = 0;
 226
 227     /**
 228         Call this to inform the model that an item has been added to the data.
 229     */
 230     virtual bool ItemAdded(const wxDataViewItem& parent,
 231                            const wxDataViewItem& item);
 232
 233     /**
 234         Call this to inform the model that an item has changed.
 235
 236         This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
 237         event (in which the column fields will not be set) to the user.
 238     */
 239     virtual bool ItemChanged(const wxDataViewItem& item);
 240
 241     /**
 242         Call this to inform the model that an item has been deleted from the data.
 243     */
 244     virtual bool ItemDeleted(const wxDataViewItem& parent,
 245                              const wxDataViewItem& item);
 246
 247     /**
 248         Call this to inform the model that several items have been added to the data.
 249     */
 250     virtual bool ItemsAdded(const wxDataViewItem& parent,
 251                             const wxDataViewItemArray& items);
 252
 253     /**
 254         Call this to inform the model that several items have changed.
 255
 256         This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
 257         events (in which the column fields will not be set) to the user.
 258     */
 259     virtual bool ItemsChanged(const wxDataViewItemArray& items);
 260
 261     /**
 262         Call this to inform the model that several items have been deleted.
 263     */
 264     virtual bool ItemsDeleted(const wxDataViewItem& parent,
 265                               const wxDataViewItemArray& items);
 266
 267     /**
 268         Remove the @a notifier from the list of notifiers.
 269     */
 270     void RemoveNotifier(wxDataViewModelNotifier* notifier);
 271
 272     /**
 273         Call this to initiate a resort after the sort function has been changed.
 274     */
 275     virtual void Resort();
 276
 277     /**
 278         This gets called in order to set a value in the data model.
 279
 280         The most common scenario is that the wxDataViewCtrl calls this method
 281         after the user changed some data in the view.
 282
 283         This is the function you need to override in your derived class but if
 284         you want to call it, ChangeValue() is usually more convenient as
 285         otherwise you need to manually call ValueChanged() to update the
 286         control itself.
 287     */
 288     virtual bool SetValue(const wxVariant& variant,
 289                           const wxDataViewItem& item,
 290                           unsigned int col) = 0;
 291
 292     /**
 293         Call this to inform this model that a value in the model has been changed.
 294         This is also called from wxDataViewCtrl's internal editing code, e.g. when
 295         editing a text field in the control.
 296
 297         This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
 298         event to the user.
 299     */
 300     virtual bool ValueChanged(const wxDataViewItem& item,
 301                               unsigned int col);
 302
 303 protected:
 304
 305     /**
 306         Destructor. This should not be called directly. Use DecRef() instead.
 307     */
 308     virtual ~wxDataViewModel();
 309 };
 310
 311
 312
 313 /**
 314     @class wxDataViewIndexListModel
 315
 316     wxDataViewIndexListModel is a specialized data model which lets you address
 317     an item by its position (row) rather than its wxDataViewItem (which you can
 318     obtain from this class).
 319     This model also provides its own wxDataViewIndexListModel::Compare
 320     method which sorts the model's data by the index.
 321
 322     This model is not a virtual model since the control stores each wxDataViewItem.
 323     Use wxDataViewVirtualListModel if you need to display millions of items or
 324     have other reason to use a virtual control.
 325
 326     @library{wxadv}
 327     @category{dvc}
 328 */
 329 class wxDataViewIndexListModel : public wxDataViewModel
 330 {
 331 public:
 332     /**
 333         Constructor.
 334     */
 335     wxDataViewIndexListModel(unsigned int initial_size = 0);
 336
 337     /**
 338         Destructor.
 339     */
 340     virtual ~wxDataViewIndexListModel();
 341
 342     /**
 343         Compare method that sorts the items by their index.
 344     */
 345     int Compare(const wxDataViewItem& item1,
 346                 const wxDataViewItem& item2,
 347                 unsigned int column, bool ascending);
 348
 349     /**
 350         Override this to indicate that the row has special font attributes.
 351         This only affects the wxDataViewTextRendererText() renderer.
 352
 353         The base class version always simply returns @false.
 354
 355         @see wxDataViewItemAttr.
 356
 357         @param row
 358             The row for which the attribute is requested.
 359         @param col
 360             The column for which the attribute is requested.
 361         @param attr
 362             The attribute to be filled in if the function returns @true.
 363         @return
 364             @true if this item has an attribute or @false otherwise.
 365     */
 366     virtual bool GetAttrByRow(unsigned int row, unsigned int col,
 367                          wxDataViewItemAttr& attr) const;
 368
 369     /**
 370         Returns the number of items (i.e. rows) in the list.
 371     */
 372     unsigned int GetCount() const;
 373
 374     /**
 375         Returns the wxDataViewItem at the given @e row.
 376     */
 377     wxDataViewItem GetItem(unsigned int row) const;
 378
 379     /**
 380         Returns the position of given @e item.
 381     */
 382     unsigned int GetRow(const wxDataViewItem& item) const;
 383
 384     /**
 385         Override this to allow getting values from the model.
 386     */
 387     virtual void GetValueByRow(wxVariant& variant, unsigned int row,
 388                           unsigned int col) const = 0;
 389
 390     /**
 391         Call this after if the data has to be read again from the model.
 392         This is useful after major changes when calling the methods below
 393         (possibly thousands of times) doesn't make sense.
 394     */
 395     void Reset(unsigned int new_size);
 396
 397     /**
 398         Call this after a row has been appended to the model.
 399     */
 400     void RowAppended();
 401
 402     /**
 403         Call this after a row has been changed.
 404     */
 405     void RowChanged(unsigned int row);
 406
 407     /**
 408         Call this after a row has been deleted.
 409     */
 410     void RowDeleted(unsigned int row);
 411
 412     /**
 413         Call this after a row has been inserted at the given position.
 414     */
 415     void RowInserted(unsigned int before);
 416
 417     /**
 418         Call this after a row has been prepended to the model.
 419     */
 420     void RowPrepended();
 421
 422     /**
 423         Call this after a value has been changed.
 424     */
 425     void RowValueChanged(unsigned int row, unsigned int col);
 426
 427     /**
 428         Call this after rows have been deleted.
 429         The array will internally get copied and sorted in descending order so
 430         that the rows with the highest position will be deleted first.
 431     */
 432     void RowsDeleted(const wxArrayInt& rows);
 433
 434     /**
 435         Called in order to set a value in the model.
 436     */
 437     virtual bool SetValueByRow(const wxVariant& variant, unsigned int row,
 438                           unsigned int col) = 0;
 439 };
 440
 441
 442
 443 /**
 444     @class wxDataViewVirtualListModel
 445
 446     wxDataViewVirtualListModel is a specialized data model which lets you address
 447     an item by its position (row) rather than its wxDataViewItem and as such offers
 448     the exact same interface as wxDataViewIndexListModel.
 449     The important difference is that under platforms other than OS X, using this
 450     model will result in a truly virtual control able to handle millions of items
 451     as the control doesn't store any item (a feature not supported by the
 452     Carbon API under OS X).
 453
 454     @see wxDataViewIndexListModel for the API.
 455
 456     @library{wxadv}
 457     @category{dvc}
 458 */
 459 class wxDataViewVirtualListModel : public wxDataViewModel
 460 {
 461 public:
 462     /**
 463         Constructor.
 464     */
 465     wxDataViewVirtualListModel(unsigned int initial_size = 0);
 466
 467     /**
 468         Returns the number of virtual items (i.e. rows) in the list.
 469     */
 470     unsigned int GetCount() const;
 471 };
 472
 473
 474
 475 /**
 476     @class wxDataViewItemAttr
 477
 478     This class is used to indicate to a wxDataViewCtrl that a certain item
 479     (see wxDataViewItem) has extra font attributes for its renderer.
 480     For this, it is required to override wxDataViewModel::GetAttr.
 481
 482     Attributes are currently only supported by wxDataViewTextRendererText.
 483
 484     @library{wxadv}
 485     @category{dvc}
 486 */
 487 class wxDataViewItemAttr
 488 {
 489 public:
 490     /**
 491         Constructor.
 492     */
 493     wxDataViewItemAttr();
 494
 495     /**
 496         Call this to indicate that the item shall be displayed in bold text.
 497     */
 498     void SetBold(bool set);
 499
 500     /**
 501         Call this to indicate that the item shall be displayed with that colour.
 502     */
 503     void SetColour(const wxColour& colour);
 504
 505     /**
 506         Call this to indicate that the item shall be displayed in italic text.
 507     */
 508     void SetItalic(bool set);
 509 };
 510
 511
 512
 513 /**
 514     @class wxDataViewItem
 515
 516     wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl
 517     in a persistent way, i.e. 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
1118     Additionally, the user can write own renderers by deriving from
1119     wxDataViewCustomRenderer.
1120
1121     The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1122     by the constructors respectively controls what actions the cell data allows
1123     and how the renderer should display its contents in a cell.
1124
1125     @library{wxadv}
1126     @category{dvc}
1127 */
1128 class wxDataViewRenderer : public wxObject
1129 {
1130 public:
1131     /**
1132         Constructor.
1133     */
1134     wxDataViewRenderer(const wxString& varianttype,
1135                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1136                        int align = wxDVR_DEFAULT_ALIGNMENT );
1137
1138     /**
1139         Enable or disable replacing parts of the item text with ellipsis to
1140         make it fit the column width.
1141
1142         This method only makes sense for the renderers working with text, such
1143         as wxDataViewTextRenderer or wxDataViewIconTextRenderer.
1144
1145         By default wxELLIPSIZE_MIDDLE is used.
1146
1147         @param mode
1148             Ellipsization mode, use wxELLIPSIZE_NONE to disable.
1149
1150         @since 2.9.1
1151      */
1152     void EnableEllipsize(wxEllipsizeMode mode = wxELLIPSIZE_MIDDLE);
1153
1154     /**
1155         Disable replacing parts of the item text with ellipsis.
1156
1157         If ellipsizing is disabled, the string will be truncated if it doesn't
1158         fit.
1159
1160         This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode.
1161
1162         @since 2.9.1
1163      */
1164     void DisableEllipsize();
1165
1166     /**
1167         Returns the alignment. See SetAlignment()
1168     */
1169     virtual int GetAlignment() const;
1170
1171     /**
1172         Returns the ellipsize mode used by the renderer.
1173
1174         If the return value is wxELLIPSIZE_NONE, the text is simply truncated
1175         if it doesn't fit.
1176
1177         @see EnableEllipsize()
1178      */
1179     wxEllipsizeMode GetEllipsizeMode() const;
1180
1181     /**
1182         Returns the cell mode.
1183     */
1184     virtual wxDataViewCellMode GetMode() const;
1185
1186     /**
1187         Returns pointer to the owning wxDataViewColumn.
1188     */
1189     wxDataViewColumn* GetOwner() const;
1190
1191     /**
1192         This methods retrieves the value from the renderer in order to
1193         transfer the value back to the data model.
1194
1195         Returns @false on failure.
1196     */
1197     virtual bool GetValue(wxVariant& value) const = 0;
1198
1199     /**
1200         Returns a string with the type of the wxVariant supported by this renderer.
1201     */
1202     wxString GetVariantType() const;
1203
1204     /**
1205         Sets the alignment of the renderer's content.
1206         The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1207         should have the same alignment as the column header.
1208
1209         The method is not implemented under OS X and the renderer always aligns
1210         its contents as the column header on that platform. The other platforms
1211         support both vertical and horizontal alignment.
1212     */
1213     virtual void SetAlignment( int align );
1214     /**
1215         Sets the owning wxDataViewColumn.
1216         This is usually called from within wxDataViewColumn.
1217     */
1218     void SetOwner(wxDataViewColumn* owner);
1219
1220     /**
1221         Set the value of the renderer (and thus its cell) to @a value.
1222         The internal code will then render this cell with this data.
1223     */
1224     virtual bool SetValue(const wxVariant& value) = 0;
1225
1226     /**
1227         Before data is committed to the data model, it is passed to this
1228         method where it can be checked for validity. This can also be
1229         used for checking a valid range or limiting the user input in
1230         a certain aspect (e.g. max number of characters or only alphanumeric
1231         input, ASCII only etc.). Return @false if the value is not valid.
1232
1233         Please note that due to implementation limitations, this validation
1234         is done after the editing control already is destroyed and the
1235         editing process finished.
1236     */
1237     virtual bool Validate(wxVariant& value);
1238 };
1239
1240
1241
1242 /**
1243     @class wxDataViewTextRenderer
1244
1245     wxDataViewTextRenderer is used for rendering text.
1246     It supports in-place editing if desired.
1247
1248     @library{wxadv}
1249     @category{dvc}
1250 */
1251 class wxDataViewTextRenderer : public wxDataViewRenderer
1252 {
1253 public:
1254     /**
1255         The ctor.
1256     */
1257     wxDataViewTextRenderer(const wxString& varianttype = "string",
1258                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1259                            int align = wxDVR_DEFAULT_ALIGNMENT );
1260 };
1261
1262
1263
1264 /**
1265     @class wxDataViewIconTextRenderer
1266
1267     The wxDataViewIconTextRenderer class is used to display text with
1268     a small icon next to it as it is typically done in a file manager.
1269
1270     This classes uses the wxDataViewIconText helper class to store its data.
1271     wxDataViewIonText can be converted to and from a wxVariant using the left shift
1272     operator.
1273
1274     @library{wxadv}
1275     @category{dvc}
1276 */
1277 class wxDataViewIconTextRenderer : public wxDataViewRenderer
1278 {
1279 public:
1280     /**
1281         The ctor.
1282     */
1283     wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
1284                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1285                                int align = wxDVR_DEFAULT_ALIGNMENT );
1286 };
1287
1288
1289
1290 /**
1291     @class wxDataViewProgressRenderer
1292
1293     This class is used by wxDataViewCtrl to render progress bars.
1294
1295     @library{wxadv}
1296     @category{dvc}
1297 */
1298 class wxDataViewProgressRenderer : public wxDataViewRenderer
1299 {
1300 public:
1301     /**
1302         The ctor.
1303     */
1304     wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
1305                                const wxString& varianttype = "long",
1306                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1307                                int align = wxDVR_DEFAULT_ALIGNMENT );
1308 };
1309
1310
1311
1312 /**
1313     @class wxDataViewSpinRenderer
1314
1315     This is a specialized renderer for rendering integer values.
1316     It supports modifying the values in-place by using a wxSpinCtrl.
1317     The renderer only support variants of type @e long.
1318
1319     @library{wxadv}
1320     @category{dvc}
1321 */
1322 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
1323 {
1324 public:
1325     /**
1326         Constructor.
1327         @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1328     */
1329     wxDataViewSpinRenderer(int min, int max,
1330                            wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1331                            int align = wxDVR_DEFAULT_ALIGNMENT);
1332 };
1333
1334
1335
1336 /**
1337     @class wxDataViewToggleRenderer
1338
1339     This class is used by wxDataViewCtrl to render toggle controls.
1340
1341     @library{wxadv}
1342     @category{dvc}
1343 */
1344 class wxDataViewToggleRenderer : public wxDataViewRenderer
1345 {
1346 public:
1347     /**
1348         The ctor.
1349     */
1350     wxDataViewToggleRenderer(const wxString& varianttype = "bool",
1351                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1352                              int align = wxDVR_DEFAULT_ALIGNMENT);
1353 };
1354
1355
1356
1357 /**
1358     @class wxDataViewDateRenderer
1359
1360     This class is used by wxDataViewCtrl to render calendar controls.
1361
1362     @library{wxadv}
1363     @category{dvc}
1364 */
1365 class wxDataViewDateRenderer : public wxDataViewRenderer
1366 {
1367 public:
1368     /**
1369         The ctor.
1370     */
1371     wxDataViewDateRenderer(const wxString& varianttype = "datetime",
1372                            wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1373                            int align = wxDVR_DEFAULT_ALIGNMENT);
1374 };
1375
1376
1377
1378 /**
1379     @class wxDataViewCustomRenderer
1380
1381     You need to derive a new class from wxDataViewCustomRenderer in
1382     order to write a new renderer.
1383
1384     You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
1385     wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
1386
1387     If you want your renderer to support in-place editing then you also need to override
1388     wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
1389     and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1390
1391     Note that a special event handler will be pushed onto that editor control
1392     which handles @e \<ENTER\> and focus out events in order to end the editing.
1393
1394     @library{wxadv}
1395     @category{dvc}
1396 */
1397 class wxDataViewCustomRenderer : public wxDataViewRenderer
1398 {
1399 public:
1400     /**
1401         Constructor.
1402     */
1403     wxDataViewCustomRenderer(const wxString& varianttype = "string",
1404                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1405                              int align = -1, bool no_init = false);
1406
1407     /**
1408         Destructor.
1409     */
1410     virtual ~wxDataViewCustomRenderer();
1411
1412     /**
1413         Override this to react to double clicks or ENTER.
1414         This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1415     */
1416     virtual bool Activate( wxRect cell,
1417                            wxDataViewModel* model,
1418                            const wxDataViewItem & item,
1419                            unsigned int col );
1420
1421     /**
1422         Override this to create the actual editor control once editing
1423         is about to start.
1424
1425         @a parent is the parent of the editor control, @a labelRect indicates the
1426         position and size of the editor control and @a value is its initial value:
1427         @code
1428         {
1429             long l = value;
1430             return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
1431                         labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
1432         }
1433         @endcode
1434     */
1435     virtual wxControl* CreateEditorCtrl(wxWindow* parent,
1436                                         wxRect labelRect,
1437                                         const wxVariant& value);
1438
1439     /**
1440         Return the attribute to be used for rendering.
1441
1442         This function may be called from Render() implementation to use the
1443         attributes defined for the item if the renderer supports them.
1444
1445         Notice that when Render() is called, the wxDC object passed to it is
1446         already set up to use the correct attributes (e.g. its font is set to
1447         bold or italic version if wxDataViewItemAttr::GetBold() or GetItalic()
1448         returns true) so it may not be necessary to call it explicitly if you
1449         only want to render text using the items attributes.
1450
1451         @since 2.9.1
1452      */
1453     const wxDataViewItemAttr& GetAttr() const;
1454
1455     /**
1456         Return size required to show content.
1457     */
1458     virtual wxSize GetSize() const = 0;
1459
1460     /**
1461         Override this so that the renderer can get the value from the editor
1462         control (pointed to by @a editor):
1463         @code
1464         {
1465             wxSpinCtrl *sc = (wxSpinCtrl*) editor;
1466             long l = sc->GetValue();
1467             value = l;
1468             return true;
1469         }
1470         @endcode
1471     */
1472     virtual bool GetValueFromEditorCtrl(wxControl* editor,
1473                                         wxVariant& value);
1474
1475     /**
1476         Override this and make it return @true in order to
1477         indicate that this renderer supports in-place editing.
1478     */
1479     virtual bool HasEditorCtrl() const;
1480
1481     /**
1482         Override this to react to a left click.
1483         This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
1484     */
1485     virtual bool LeftClick( wxPoint cursor,
1486                             wxRect cell,
1487                             wxDataViewModel * model,
1488                             const wxDataViewItem & item,
1489                             unsigned int col );
1490
1491     /**
1492         Override this to render the cell.
1493         Before this is called, wxDataViewRenderer::SetValue was called
1494         so that this instance knows what to render.
1495     */
1496     virtual bool Render(wxRect cell, wxDC* dc, int state) = 0;
1497
1498     /**
1499         This method should be called from within Render() whenever you need to
1500         render simple text.
1501         This will ensure that the correct colour, font and vertical alignment will
1502         be chosen so the text will look the same as text drawn by native renderers.
1503     */
1504     void RenderText(const wxString& text, int xoffset, wxRect cell,
1505                     wxDC* dc, int state);
1506
1507     /**
1508         Override this to start a drag operation. Not yet supported.
1509     */
1510     virtual bool StartDrag(wxPoint cursor, wxRect cell,
1511                            wxDataViewModel* model,
1512                            const wxDataViewItem & item,
1513                            unsigned int col);
1514 };
1515
1516
1517
1518 /**
1519     @class wxDataViewBitmapRenderer
1520
1521     This class is used by wxDataViewCtrl to render bitmap controls.
1522
1523     @library{wxadv}
1524     @category{dvc}
1525 */
1526 class wxDataViewBitmapRenderer : public wxDataViewRenderer
1527 {
1528 public:
1529     /**
1530         The ctor.
1531     */
1532     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
1533                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1534                              int align = wxDVR_DEFAULT_ALIGNMENT);
1535 };
1536
1537
1538 /**
1539     The flags used by wxDataViewColumn.
1540     Can be combined together.
1541 */
1542 enum wxDataViewColumnFlags
1543 {
1544     wxDATAVIEW_COL_RESIZABLE     = 1,
1545     wxDATAVIEW_COL_SORTABLE      = 2,
1546     wxDATAVIEW_COL_REORDERABLE   = 4,
1547     wxDATAVIEW_COL_HIDDEN        = 8
1548 };
1549
1550 /**
1551     @class wxDataViewColumn
1552
1553     This class represents a column in a wxDataViewCtrl.
1554     One wxDataViewColumn is bound to one column in the data model to which the
1555     wxDataViewCtrl has been associated.
1556
1557     An instance of wxDataViewRenderer is used by this class to render its data.
1558
1559     @library{wxadv}
1560     @category{dvc}
1561 */
1562 class wxDataViewColumn : public wxSettableHeaderColumn
1563 {
1564 public:
1565     /**
1566         Constructs a text column.
1567
1568         @param title
1569             The title of the column.
1570         @param renderer
1571             The class which will render the contents of this column.
1572         @param model_column
1573             The index of the model's column which is associated with this object.
1574         @param width
1575             The width of the column.
1576             The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1577         @param align
1578             The alignment of the column title.
1579         @param flags
1580             One or more flags of the ::wxDataViewColumnFlags enumeration.
1581     */
1582     wxDataViewColumn(const wxString& title,
1583                      wxDataViewRenderer* renderer,
1584                      unsigned int model_column,
1585                      int width = wxDVC_DEFAULT_WIDTH,
1586                      wxAlignment align = wxALIGN_CENTER,
1587                      int flags = wxDATAVIEW_COL_RESIZABLE);
1588
1589     /**
1590         Constructs a bitmap column.
1591
1592         @param bitmap
1593             The bitmap of the column.
1594         @param renderer
1595             The class which will render the contents of this column.
1596         @param model_column
1597             The index of the model's column which is associated with this object.
1598         @param width
1599             The width of the column.
1600             The @c wxDVC_DEFAULT_WIDTH value is the fixed default value.
1601         @param align
1602             The alignment of the column title.
1603         @param flags
1604             One or more flags of the ::wxDataViewColumnFlags enumeration.
1605     */
1606     wxDataViewColumn(const wxBitmap& bitmap,
1607                      wxDataViewRenderer* renderer,
1608                      unsigned int model_column,
1609                      int width = wxDVC_DEFAULT_WIDTH,
1610                      wxAlignment align = wxALIGN_CENTER,
1611                      int flags = wxDATAVIEW_COL_RESIZABLE);
1612
1613     /**
1614         Returns the index of the column of the model, which this
1615         wxDataViewColumn is displaying.
1616     */
1617     unsigned int GetModelColumn() const;
1618
1619     /**
1620         Returns the owning wxDataViewCtrl.
1621     */
1622     wxDataViewCtrl* GetOwner() const;
1623
1624     /**
1625         Returns the renderer of this wxDataViewColumn.
1626
1627         @see wxDataViewRenderer.
1628     */
1629     wxDataViewRenderer* GetRenderer() const;
1630 };
1631
1632
1633
1634 /**
1635     @class wxDataViewListCtrl
1636
1637     This class is a wxDataViewCtrl which internally uses a wxDataViewListStore
1638     and forwards most of its API to that class.
1639
1640     The purpose of this class is to offer a simple way to display and
1641     edit a small table of data without having to write your own wxDataViewModel.
1642
1643     @code
1644        wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY );
1645
1646        listctrl->AppendToggleColumn( "Toggle" );
1647        listctrl->AppendTextColumn( "Text" );
1648
1649        wxVector<wxVariant> data;
1650        data.push_back( wxVariant(true) );
1651        data.push_back( wxVariant("row 1") );
1652        listctrl->AppendItem( data );
1653
1654        data.clear();
1655        data.push_back( wxVariant(false) );
1656        data.push_back( wxVariant("row 3") );
1657        listctrl->AppendItem( data );
1658     @endcode
1659
1660     @beginStyleTable
1661     See wxDataViewCtrl for the list of supported styles.
1662     @endStyleTable
1663
1664     @beginEventEmissionTable
1665     See wxDataViewCtrl for the list of events emitted by this class.
1666     @endEventTable
1667
1668     @library{wxadv}
1669     @category{ctrl,dvc}
1670 */
1671 class wxDataViewListCtrl: public wxDataViewCtrl
1672 {
1673 public:
1674     /**
1675         Default ctor.
1676     */
1677     wxDataViewListCtrl();
1678
1679     /**
1680         Constructor. Calls Create().
1681     */
1682     wxDataViewListCtrl( wxWindow *parent, wxWindowID id,
1683            const wxPoint& pos = wxDefaultPosition,
1684            const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES,
1685            const wxValidator& validator = wxDefaultValidator );
1686
1687     /**
1688         Destructor. Deletes the image list if any.
1689     */
1690     ~wxDataViewListCtrl();
1691
1692     /**
1693         Creates the control and a wxDataViewListStore as its internal model.
1694     */
1695     bool Create( wxWindow *parent, wxWindowID id,
1696            const wxPoint& pos = wxDefaultPosition,
1697            const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES,
1698            const wxValidator& validator = wxDefaultValidator );
1699
1700     //@{
1701     /**
1702         Returns the store.
1703     */
1704     wxDataViewListStore *GetStore();
1705     const wxDataViewListStore *GetStore() const;
1706     //@}
1707
1708     /**
1709         @name Column management functions
1710     */
1711     //@{
1712
1713     /**
1714         Appends a column to the control and additionally appends a
1715         column to the store with the type string.
1716     */
1717     virtual void AppendColumn( wxDataViewColumn *column );
1718
1719     /**
1720         Appends a column to the control and additionally appends a
1721         column to the list store with the type @a varianttype.
1722     */
1723     void AppendColumn( wxDataViewColumn *column, const wxString &varianttype );
1724
1725     /**
1726         Appends a text column to the control and the store.
1727
1728         See wxDataViewColumn::wxDataViewColumn for more info about
1729         the parameters.
1730     */
1731     wxDataViewColumn *AppendTextColumn( const wxString &label,
1732           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1733           int width = -1, wxAlignment align = wxALIGN_LEFT,
1734           int flags = wxDATAVIEW_COL_RESIZABLE );
1735
1736     /**
1737         Appends a toggle column to the control and the store.
1738
1739         See wxDataViewColumn::wxDataViewColumn for more info about
1740         the parameters.
1741     */
1742     wxDataViewColumn *AppendToggleColumn( const wxString &label,
1743           wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1744           int width = -1, wxAlignment align = wxALIGN_LEFT,
1745           int flags = wxDATAVIEW_COL_RESIZABLE );
1746
1747     /**
1748         Appends a progress column to the control and the store.
1749
1750         See wxDataViewColumn::wxDataViewColumn for more info about
1751         the parameters.
1752     */
1753     wxDataViewColumn *AppendProgressColumn( const wxString &label,
1754           wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1755           int width = -1, wxAlignment align = wxALIGN_LEFT,
1756           int flags = wxDATAVIEW_COL_RESIZABLE );
1757
1758     /**
1759         Appends an icon-and-text column to the control and the store.
1760
1761         See wxDataViewColumn::wxDataViewColumn for more info about
1762         the parameters.
1763     */
1764     wxDataViewColumn *AppendIconTextColumn( 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         Inserts a column to the control and additionally inserts a
1771         column to the store with the type string.
1772     */
1773     virtual void InsertColumn( unsigned int pos, wxDataViewColumn *column );
1774
1775     /**
1776         Inserts a column to the control and additionally inserts a
1777         column to the list store with the type @a varianttype.
1778     */
1779     void InsertColumn( unsigned int pos, wxDataViewColumn *column,
1780                        const wxString &varianttype );
1781
1782     /**
1783         Prepends a column to the control and additionally prepends a
1784         column to the store with the type string.
1785     */
1786     virtual void PrependColumn( wxDataViewColumn *column );
1787
1788     /**
1789         Prepends a column to the control and additionally prepends a
1790         column to the list store with the type @a varianttype.
1791     */
1792     void PrependColumn( wxDataViewColumn *column, const wxString &varianttype );
1793
1794     //@}
1795
1796
1797     /**
1798         @name Item management functions
1799     */
1800     //@{
1801
1802     /**
1803         Appends an item (=row) to the control and store.
1804     */
1805     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
1806
1807     /**
1808         Prepends an item (=row) to the control and store.
1809     */
1810     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
1811
1812     /**
1813         Inserts an item (=row) to the control and store.
1814     */
1815     void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
1816
1817     /**
1818         Delete the row at position @a row.
1819     */
1820     void DeleteItem( unsigned row );
1821
1822     /**
1823         Delete all items (= all rows).
1824     */
1825     void DeleteAllItems();
1826
1827     /**
1828          Sets the value in the store and update the control.
1829     */
1830     void SetValue( const wxVariant &value, unsigned int row, unsigned int col );
1831
1832     /**
1833          Returns the value from the store.
1834     */
1835     void GetValue( wxVariant &value, unsigned int row, unsigned int col );
1836
1837     /**
1838          Sets the value in the store and update the control.
1839
1840          This method assumes that the a string is stored in respective
1841          column.
1842     */
1843     void SetTextValue( const wxString &value, unsigned int row, unsigned int col );
1844
1845     /**
1846          Returns the value from the store.
1847
1848          This method assumes that the a string is stored in respective
1849          column.
1850     */
1851     wxString GetTextValue( unsigned int row, unsigned int col ) const;
1852
1853     /**
1854          Sets the value in the store and update the control.
1855
1856          This method assumes that the a boolean value is stored in
1857          respective column.
1858     */
1859     void SetToggleValue( bool value, unsigned int row, unsigned int col );
1860
1861     /**
1862          Returns the value from the store.
1863
1864          This method assumes that the a boolean value is stored in
1865          respective column.
1866     */
1867     bool GetToggleValue( unsigned int row, unsigned int col ) const;
1868
1869     //@}
1870 };
1871
1872
1873 /**
1874     @class wxDataViewTreeCtrl
1875
1876     This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
1877     and forwards most of its API to that class.
1878     Additionally, it uses a wxImageList to store a list of icons.
1879
1880     The main purpose of this class is to provide a simple upgrade path for code
1881     using wxTreeCtrl.
1882
1883     @beginStyleTable
1884     See wxDataViewCtrl for the list of supported styles.
1885     @endStyleTable
1886
1887     @beginEventEmissionTable
1888     See wxDataViewCtrl for the list of events emitted by this class.
1889     @endEventTable
1890
1891     @library{wxadv}
1892     @category{ctrl,dvc}
1893     @appearance{dataviewtreectrl.png}
1894 */
1895 class wxDataViewTreeCtrl : public wxDataViewCtrl
1896 {
1897 public:
1898     /**
1899         Default ctor.
1900     */
1901     wxDataViewTreeCtrl();
1902
1903     /**
1904         Constructor.
1905
1906         Calls Create().
1907     */
1908     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
1909                        const wxPoint& pos = wxDefaultPosition,
1910                        const wxSize& size = wxDefaultSize,
1911                        long style = wxDV_NO_HEADER | wxDV_ROW_LINES,
1912                        const wxValidator& validator = wxDefaultValidator);
1913
1914     /**
1915         Destructor. Deletes the image list if any.
1916     */
1917     virtual ~wxDataViewTreeCtrl();
1918
1919     /**
1920         Appends a container to the given @a parent.
1921     */
1922     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1923                                    const wxString& text,
1924                                    int icon = -1,
1925                                    int expanded = -1,
1926                                    wxClientData* data = NULL);
1927
1928     /**
1929         Appends an item to the given @a parent.
1930     */
1931     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1932                               const wxString& text,
1933                               int icon = -1,
1934                               wxClientData* data = NULL);
1935
1936     /**
1937         Creates the control and a wxDataViewTreeStore as its internal model.
1938
1939         The default tree column created by this method is an editable column
1940         using wxDataViewIconTextRenderer as its renderer.
1941     */
1942     bool Create(wxWindow* parent, wxWindowID id,
1943                 const wxPoint& pos = wxDefaultPosition,
1944                 const wxSize& size = wxDefaultSize,
1945                 long style = wxDV_NO_HEADER | wxDV_ROW_LINES,
1946                 const wxValidator& validator = wxDefaultValidator);
1947
1948     /**
1949         Calls the identical method from wxDataViewTreeStore.
1950     */
1951     void DeleteAllItems();
1952
1953     /**
1954         Calls the identical method from wxDataViewTreeStore.
1955     */
1956     void DeleteChildren(const wxDataViewItem& item);
1957
1958     /**
1959         Calls the identical method from wxDataViewTreeStore.
1960     */
1961     void DeleteItem(const wxDataViewItem& item);
1962
1963     /**
1964         Calls the identical method from wxDataViewTreeStore.
1965     */
1966     int GetChildCount(const wxDataViewItem& parent) const;
1967
1968     /**
1969         Returns the image list.
1970     */
1971     wxImageList* GetImageList();
1972
1973     /**
1974         Calls the identical method from wxDataViewTreeStore.
1975     */
1976     wxClientData* GetItemData(const wxDataViewItem& item) const;
1977
1978     /**
1979         Calls the identical method from wxDataViewTreeStore.
1980     */
1981     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
1982
1983     /**
1984         Calls the identical method from wxDataViewTreeStore.
1985     */
1986     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
1987
1988     /**
1989         Calls the identical method from wxDataViewTreeStore.
1990     */
1991     wxString GetItemText(const wxDataViewItem& item) const;
1992
1993     /**
1994         Calls the identical method from wxDataViewTreeStore.
1995     */
1996     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1997                                unsigned int pos) const;
1998
1999     //@{
2000     /**
2001         Returns the store.
2002     */
2003     wxDataViewTreeStore* GetStore();
2004     const wxDataViewTreeStore* GetStore() const;
2005     //@}
2006
2007     /**
2008         Calls the same method from wxDataViewTreeStore but uses
2009         an index position in the image list instead of a wxIcon.
2010     */
2011     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
2012                                    const wxDataViewItem& previous,
2013                                    const wxString& text,
2014                                    int icon = -1,
2015                                    int expanded = -1,
2016                                    wxClientData* data = NULL);
2017
2018     /**
2019         Calls the same method from wxDataViewTreeStore but uses
2020         an index position in the image list instead of a wxIcon.
2021     */
2022     wxDataViewItem InsertItem(const wxDataViewItem& parent,
2023                               const wxDataViewItem& previous,
2024                               const wxString& text,
2025                               int icon = -1,
2026                               wxClientData* data = NULL);
2027
2028     /**
2029         Returns true if item is a container.
2030     */
2031     bool IsContainer( const wxDataViewItem& item );
2032
2033     /**
2034         Calls the same method from wxDataViewTreeStore but uses
2035         an index position in the image list instead of a wxIcon.
2036     */
2037     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
2038                                     const wxString& text,
2039                                     int icon = -1,
2040                                     int expanded = -1,
2041                                     wxClientData* data = NULL);
2042
2043     /**
2044         Calls the same method from wxDataViewTreeStore but uses
2045         an index position in the image list instead of a wxIcon.
2046     */
2047     wxDataViewItem PrependItem(const wxDataViewItem& parent,
2048                                const wxString& text,
2049                                int icon = -1,
2050                                wxClientData* data = NULL);
2051
2052     /**
2053         Sets the image list.
2054     */
2055     void SetImageList(wxImageList* imagelist);
2056
2057     /**
2058         Calls the identical method from wxDataViewTreeStore.
2059     */
2060     void SetItemData(const wxDataViewItem& item, wxClientData* data);
2061
2062     /**
2063         Calls the identical method from wxDataViewTreeStore.
2064     */
2065     void SetItemExpandedIcon(const wxDataViewItem& item,
2066                              const wxIcon& icon);
2067
2068     /**
2069         Calls the identical method from wxDataViewTreeStore.
2070     */
2071     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
2072
2073     /**
2074         Calls the identical method from wxDataViewTreeStore.
2075     */
2076     void SetItemText(const wxDataViewItem& item,
2077                      const wxString& text);
2078 };
2079
2080
2081 /**
2082     @class wxDataViewListStore
2083
2084     wxDataViewListStore is a specialised wxDataViewModel for storing
2085     a simple table of data. Since it derives from wxDataViewIndexListModel
2086     its data is be accessed by row (i.e. by index) instead of only
2087     by wxDataViewItem.
2088
2089     This class actually stores the values (therefore its name)
2090     and implements all virtual methods from the base classes so it can be
2091     used directly without having to derive any class from it, but it is
2092     mostly used from within wxDataViewListCtrl.
2093
2094     @library{wxadv}
2095     @category{dvc}
2096 */
2097
2098 class wxDataViewListStore: public wxDataViewIndexListModel
2099 {
2100 public:
2101     /**
2102         Constructor
2103     */
2104     wxDataViewListStore();
2105
2106     /**
2107         Destructor
2108     */
2109     ~wxDataViewListStore();
2110
2111     /**
2112         Prepends a data column.
2113
2114         @a variantype indicates the type of values store in the column.
2115
2116         This does not automatically fill in any (default) values in
2117         rows which exist in the store already.
2118     */
2119     void PrependColumn( const wxString &varianttype );
2120
2121     /**
2122         Inserts a data column before @a pos.
2123
2124         @a variantype indicates the type of values store in the column.
2125
2126         This does not automatically fill in any (default) values in
2127         rows which exist in the store already.
2128     */
2129     void InsertColumn( unsigned int pos, const wxString &varianttype );
2130
2131     /**
2132         Appends a data column.
2133
2134         @a variantype indicates the type of values store in the column.
2135
2136         This does not automatically fill in any (default) values in
2137         rows which exist in the store already.
2138     */
2139     void AppendColumn( const wxString &varianttype );
2140
2141     /**
2142         Appends an item (=row) and fills it with @a values.
2143
2144         The values must match the values specifies in the column
2145         in number and type. No (default) values are filled in
2146         automatically.
2147     */
2148     void AppendItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2149
2150     /**
2151         Prepends an item (=row) and fills it with @a values.
2152
2153         The values must match the values specifies in the column
2154         in number and type. No (default) values are filled in
2155         automatically.
2156     */
2157     void PrependItem( const wxVector<wxVariant> &values, wxClientData *data = NULL );
2158
2159     /**
2160         Inserts an item (=row) and fills it with @a values.
2161
2162         The values must match the values specifies in the column
2163         in number and type. No (default) values are filled in
2164         automatically.
2165     */
2166     void InsertItem(  unsigned int row, const wxVector<wxVariant> &values, wxClientData *data = NULL );
2167
2168     /**
2169         Delete the item (=row) at position @a pos.
2170     */
2171     void DeleteItem( unsigned pos );
2172
2173     /**
2174         Delete all item (=all rows) in the store.
2175     */
2176     void DeleteAllItems();
2177
2178     /**
2179         Overriden from wxDataViewModel
2180     */
2181     virtual unsigned int GetColumnCount() const;
2182
2183     /**
2184         Overriden from wxDataViewModel
2185     */
2186     virtual wxString GetColumnType( unsigned int col ) const;
2187
2188     /**
2189         Overriden from wxDataViewIndexListModel
2190     */
2191     virtual void GetValueByRow( wxVariant &value,
2192                            unsigned int row, unsigned int col ) const;
2193
2194     /**
2195         Overriden from wxDataViewIndexListModel
2196     */
2197     virtual bool SetValueByRow( const wxVariant &value,
2198                            unsigned int row, unsigned int col );
2199 };
2200
2201
2202 /**
2203     @class wxDataViewTreeStore
2204
2205     wxDataViewTreeStore is a specialised wxDataViewModel for stroing simple
2206     trees very much like wxTreeCtrl does and it offers a similar API.
2207
2208     This class actually stores the entire tree and the values (therefore its name)
2209     and implements all virtual methods from the base class so it can be used directly
2210     without having to derive any class from it, but it is mostly used from within
2211     wxDataViewTreeCtrl.
2212
2213     @library{wxadv}
2214     @category{dvc}
2215 */
2216 class wxDataViewTreeStore : public wxDataViewModel
2217 {
2218 public:
2219     /**
2220         Constructor. Creates the invisible root node internally.
2221     */
2222     wxDataViewTreeStore();
2223
2224     /**
2225         Destructor.
2226     */
2227     virtual ~wxDataViewTreeStore();
2228
2229     /**
2230         Append a container.
2231     */
2232     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
2233                                    const wxString& text,
2234                                    const wxIcon& icon = wxNullIcon,
2235                                    const wxIcon& expanded = wxNullIcon,
2236                                    wxClientData* data = NULL);
2237
2238     /**
2239         Append an item.
2240     */
2241     wxDataViewItem AppendItem(const wxDataViewItem& parent,
2242                               const wxString& text,
2243                               const wxIcon& icon = wxNullIcon,
2244                               wxClientData* data = NULL);
2245
2246     /**
2247         Delete all item in the model.
2248     */
2249     void DeleteAllItems();
2250
2251     /**
2252         Delete all children of the item, but not the item itself.
2253     */
2254     void DeleteChildren(const wxDataViewItem& item);
2255
2256     /**
2257         Delete this item.
2258     */
2259     void DeleteItem(const wxDataViewItem& item);
2260
2261     /**
2262         Return the number of children of item.
2263     */
2264     int GetChildCount(const wxDataViewItem& parent) const;
2265
2266     /**
2267         Returns the client data asoociated with the item.
2268     */
2269     wxClientData* GetItemData(const wxDataViewItem& item) const;
2270
2271     /**
2272         Returns the icon to display in expanded containers.
2273     */
2274     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
2275
2276     /**
2277         Returns the icon of the item.
2278     */
2279     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
2280
2281     /**
2282         Returns the text of the item.
2283     */
2284     wxString GetItemText(const wxDataViewItem& item) const;
2285
2286     /**
2287         Returns the nth child item of item.
2288     */
2289     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
2290                                unsigned int pos) const;
2291
2292     /**
2293         Inserts a container after @a previous.
2294     */
2295     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
2296                                    const wxDataViewItem& previous,
2297                                    const wxString& text,
2298                                    const wxIcon& icon = wxNullIcon,
2299                                    const wxIcon& expanded = wxNullIcon,
2300                                    wxClientData* data = NULL);
2301
2302     /**
2303         Inserts an item after @a previous.
2304     */
2305     wxDataViewItem InsertItem(const wxDataViewItem& parent,
2306                               const wxDataViewItem& previous,
2307                               const wxString& text,
2308                               const wxIcon& icon = wxNullIcon,
2309                               wxClientData* data = NULL);
2310
2311     /**
2312         Inserts a container before the first child item or @a parent.
2313     */
2314     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
2315                                     const wxString& text,
2316                                     const wxIcon& icon = wxNullIcon,
2317                                     const wxIcon& expanded = wxNullIcon,
2318                                     wxClientData* data = NULL);
2319
2320     /**
2321         Inserts an item before the first child item or @a parent.
2322     */
2323     wxDataViewItem PrependItem(const wxDataViewItem& parent,
2324                                const wxString& text,
2325                                const wxIcon& icon = wxNullIcon,
2326                                wxClientData* data = NULL);
2327
2328     /**
2329         Sets the client data associated with the item.
2330     */
2331     void SetItemData(const wxDataViewItem& item, wxClientData* data);
2332
2333     /**
2334         Sets the expanded icon for the item.
2335     */
2336     void SetItemExpandedIcon(const wxDataViewItem& item,
2337                              const wxIcon& icon);
2338
2339     /**
2340         Sets the icon for the item.
2341     */
2342     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
2343 };
2344
2345
2346 /**
2347     @class wxDataViewIconText
2348
2349     wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer.
2350     This class can be converted to and from a wxVariant.
2351
2352     @library{wxadv}
2353     @category{dvc}
2354 */
2355 class wxDataViewIconText : public wxObject
2356 {
2357 public:
2358     //@{
2359     /**
2360         Constructor.
2361     */
2362     wxDataViewIconText(const wxString& text = wxEmptyString,
2363                        const wxIcon& icon = wxNullIcon);
2364     wxDataViewIconText(const wxDataViewIconText& other);
2365     //@}
2366
2367     /**
2368         Gets the icon.
2369     */
2370     const wxIcon& GetIcon() const;
2371
2372     /**
2373         Gets the text.
2374     */
2375     wxString GetText() const;
2376
2377     /**
2378         Set the icon.
2379     */
2380     void SetIcon(const wxIcon& icon);
2381
2382     /**
2383         Set the text.
2384     */
2385     void SetText(const wxString& text);
2386 };
2387
2388
2389
2390 /**
2391     @class wxDataViewEvent
2392
2393     This is the event class for the wxDataViewCtrl notifications.
2394
2395     @beginEventTable{wxDataViewEvent}
2396     @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)}
2397            Process a @c wxEVT_COMMAND_DATAVIEW_SELECTION_CHANGED event.
2398     @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)}
2399            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_ACTIVATED event.
2400     @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)}
2401            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_STARTED event.
2402     @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)}
2403            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EDITING_DONE event.
2404     @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)}
2405            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSING event.
2406     @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)}
2407            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_COLLAPSED event.
2408     @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)}
2409            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDING event.
2410     @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)}
2411            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_EXPANDED event.
2412     @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)}
2413            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_VALUE_CHANGED event.
2414     @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)}
2415            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_CONTEXT_MENU event.
2416     @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)}
2417            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_CLICKED event.
2418     @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)}
2419            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_HEADER_RIGHT_CLICKED event.
2420     @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)}
2421            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_SORTED event.
2422     @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)}
2423            Process a @c wxEVT_COMMAND_DATAVIEW_COLUMN_REORDERED event.
2424     @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)}
2425            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_BEGIN_DRAG event.
2426     @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)}
2427            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP_POSSIBLE event.
2428     @event{EVT_DATAVIEW_ITEM_DROP(id, func)}
2429            Process a @c wxEVT_COMMAND_DATAVIEW_ITEM_DROP event.
2430     @event{EVT_DATAVIEW_CACHE_HINT(id, func)}
2431            Process a @c wxEVT_COMMAND_DATAVIEW_CACHE_HINT event.
2432     @endEventTable
2433
2434     @library{wxadv}
2435     @category{events,dvc}
2436 */
2437 class wxDataViewEvent : public wxNotifyEvent
2438 {
2439 public:
2440     /**
2441         Constructor. Typically used by wxWidgets internals only.
2442     */
2443     wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
2444                     int winid = 0);
2445
2446     /**
2447         Returns the position of the column in the control or -1
2448         if no column field was set by the event emitter.
2449     */
2450     int GetColumn() const;
2451
2452     /**
2453         Returns a pointer to the wxDataViewColumn from which
2454         the event was emitted or @NULL.
2455     */
2456     wxDataViewColumn* GetDataViewColumn() const;
2457
2458     /**
2459         Returns the wxDataViewModel associated with the event.
2460     */
2461     wxDataViewModel* GetModel() const;
2462
2463     /**
2464         Returns a the position of a context menu event in screen coordinates.
2465     */
2466     wxPoint GetPosition() const;
2467
2468     /**
2469         Returns a reference to a value.
2470     */
2471     const wxVariant& GetValue() const;
2472
2473     /**
2474         Sets the column index associated with this event.
2475     */
2476     void SetColumn(int col);
2477
2478     /**
2479         For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
2480     */
2481     void SetDataViewColumn(wxDataViewColumn* col);
2482
2483     /**
2484         Sets the dataview model associated with this event.
2485     */
2486     void SetModel(wxDataViewModel* model);
2487
2488     /**
2489         Sets the value associated with this event.
2490     */
2491     void SetValue(const wxVariant& value);
2492
2493     /**
2494         Set wxDataObject for data transfer within a drag operation.
2495     */
2496     void SetDataObject( wxDataObject *obj );
2497
2498     /**
2499         Used internally. Gets associated wxDataObject for data transfer
2500         within a drag operation.
2501     */
2502     wxDataObject *GetDataObject() const;
2503
2504     /**
2505         Used internally. Sets the wxDataFormat during a drop operation.
2506     */
2507     void SetDataFormat( const wxDataFormat &format );
2508
2509     /**
2510         Gets the wxDataFormat during a drop operation.
2511     */
2512     wxDataFormat GetDataFormat() const;
2513
2514     /**
2515         Used internally. Sets the data size for a drop data transfer.
2516     */
2517     void SetDataSize( size_t size );
2518
2519     /**
2520         Gets the data size for a drop data transfer.
2521     */
2522     size_t GetDataSize() const;
2523
2524     /**
2525         Used internally. Sets the data buffer for a drop data transfer.
2526     */
2527     void SetDataBuffer( void* buf );
2528
2529     /**
2530         Gets the data buffer for a drop data transfer.
2531     */
2532     void *GetDataBuffer() const;
2533
2534     /**
2535         Return the first row that will be displayed.
2536     */
2537     int GetCacheFrom() const;
2538
2539     /**
2540         Return the last row that will be displayed.
2541     */
2542     int GetCacheTo() const;
2543 };
2544