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