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