interface/dataview.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dataview.h
   3 // Purpose:     interface of wxDataViewIconText
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxDataViewIconText
  11     @wxheader{dataview.h}
  12
  13     wxDataViewIconText is used by
  14     wxDataViewIconTextRenderer
  15     for data transfer. This class can be converted to a from
  16     a wxVariant.
  17
  18     @library{wxbase}
  19     @category{FIXME}
  20 */
  21 class wxDataViewIconText : public wxObject
  22 {
  23 public:
  24     //@{
  25     /**
  26         Constructor.
  27     */
  28     wxDataViewIconText(const wxString& text = wxEmptyString,
  29                        const wxIcon& icon = wxNullIcon);
  30     wxDataViewIconText(const wxDataViewIconText& other);
  31     //@}
  32
  33     /**
  34         Gets the icon.
  35     */
  36     const wxIcon GetIcon() const;
  37
  38     /**
  39         Gets the text.
  40     */
  41     wxString GetText() const;
  42
  43     /**
  44         Set the icon.
  45     */
  46     void SetIcon(const wxIcon& icon);
  47
  48     /**
  49         Set the text.
  50     */
  51     void SetText(const wxString& text);
  52 };
  53
  54
  55
  56 /**
  57     @class wxDataViewEvent
  58     @wxheader{dataview.h}
  59
  60     wxDataViewEvent - the event class for the wxDataViewCtrl notifications
  61
  62     @library{wxadv}
  63     @category{FIXME}
  64 */
  65 class wxDataViewEvent : public wxNotifyEvent
  66 {
  67 public:
  68     //@{
  69     /**
  70
  71     */
  72     wxDataViewEvent(wxEventType commandType = wxEVT_NULL,
  73                     int winid = 0);
  74     wxDataViewEvent(const wxDataViewEvent& event);
  75     //@}
  76
  77     /**
  78         Used to clone the event.
  79     */
  80     wxEvent* Clone() const;
  81
  82     /**
  83         Returns the position of the column in the control or -1
  84         if no column field was set by the event emitter.
  85     */
  86     int GetColumn() const;
  87
  88     /**
  89         Returns a pointer to the wxDataViewColumn from which
  90         the event was emitted or @NULL.
  91     */
  92     wxDataViewColumn* GetDataViewColumn();
  93
  94     /**
  95         Returns the wxDataViewModel associated with the event.
  96     */
  97     wxDataViewModel* GetModel() const;
  98
  99     /**
 100         Returns a the position of a context menu event in screen coordinates.
 101     */
 102     wxPoint GetPosition() const;
 103
 104     /**
 105         Returns a reference to a value.
 106     */
 107     const wxVariant GetValue() const;
 108
 109     /**
 110
 111     */
 112     void SetColumn(int col);
 113
 114     /**
 115         For wxEVT_DATAVIEW_COLUMN_HEADER_CLICKED only.
 116     */
 117     void SetDataViewColumn(wxDataViewColumn* col);
 118
 119     /**
 120
 121     */
 122     void SetModel(wxDataViewModel* model);
 123
 124     /**
 125
 126     */
 127     void SetValue(const wxVariant& value);
 128 };
 129
 130
 131
 132 /**
 133     @class wxDataViewIconTextRenderer
 134     @wxheader{dataview.h}
 135
 136     The wxDataViewIconTextRenderer class is used to display text with
 137     a small icon next to it as it is typically done in a file manager.
 138     This classes uses the wxDataViewIconText
 139     helper class to store its data. wxDataViewIonText can be converted
 140     to a from a wxVariant using the left shift
 141     operator.
 142
 143     @library{wxadv}
 144     @category{FIXME}
 145 */
 146 class wxDataViewIconTextRenderer : public wxDataViewRenderer
 147 {
 148 public:
 149     /**
 150
 151     */
 152     wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
 153                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
 154 };
 155
 156
 157
 158 /**
 159     @class wxDataViewIndexListModel
 160     @wxheader{dataview.h}
 161
 162     wxDataViewIndexListModel is a specialized data model which lets
 163     you address an item by its position (row) rather than its
 164     wxDataViewItem (which you can obtain from this class).
 165     This model also provides its own
 166     wxDataViewIndexListModel::Compare method
 167     which sorts the model's data by the index.
 168
 169     This model is special in the it is implemented differently under OS X
 170     and other platforms. Under OS X a wxDataViewItem is always persistent
 171     and this is also the case for this class. Under other platforms, the
 172     meaning of a wxDataViewItem is changed to reflect a row number for
 173     wxDataViewIndexListModel. The consequence of this is that
 174     wxDataViewIndexListModel can be used as a virtual model with an
 175     almost infinate number of items on platforms other than OS X.
 176
 177     @library{wxbase}
 178     @category{FIXME}
 179 */
 180 class wxDataViewIndexListModel : public wxDataViewModel
 181 {
 182 public:
 183     /**
 184         Constructor.
 185     */
 186     wxDataViewIndexListModel(unsigned int initial_size = 0);
 187
 188     /**
 189         Destructor.
 190     */
 191     ~wxDataViewIndexListModel();
 192
 193     /**
 194         Compare method that sorts the items by their index.
 195     */
 196     int Compare(const wxDataViewItem& item1,
 197                 const wxDataViewItem& item2,
 198                 unsigned int column, bool ascending);
 199
 200     /**
 201         Oberride this to indicate that the row has special font attributes.
 202         This only affects the
 203         wxDataViewTextRendererText() renderer.
 204         See also wxDataViewItemAttr.
 205     */
 206     bool GetAttr(unsigned int row, unsigned int col,
 207                  wxDataViewItemAttr& attr);
 208
 209     /**
 210         Returns the wxDataViewItem at the given @e row.
 211     */
 212     wxDataViewItem GetItem(unsigned int row) const;
 213
 214     /**
 215         Returns the position of given @e item.
 216     */
 217     unsigned int GetRow(const wxDataViewItem& item) const;
 218
 219     /**
 220         Override this to allow getting values from the model.
 221     */
 222     void GetValue(wxVariant& variant, unsigned int row,
 223                   unsigned int col) const;
 224
 225     /**
 226         Call this after if the data has to be read again from
 227         the model. This is useful after major changes when
 228         calling the methods below (possibly thousands of times)
 229         doesn't make sense.
 230     */
 231     void Reset(unsigned int new_size);
 232
 233     /**
 234         Call this after a row has been appended to the model.
 235     */
 236     void RowAppended();
 237
 238     /**
 239         Call this after a row has been changed.
 240     */
 241     void RowChanged(unsigned int row);
 242
 243     /**
 244         Call this after a row has been deleted.
 245     */
 246     void RowDeleted(unsigned int row);
 247
 248     /**
 249         Call this after a row has been inserted at the given position.
 250     */
 251     void RowInserted(unsigned int before);
 252
 253     /**
 254         Call this after a row has been prepended to the model.
 255     */
 256     void RowPrepended();
 257
 258     /**
 259         Call this after a value has been changed.
 260     */
 261     void RowValueChanged(unsigned int row, unsigned int col);
 262
 263     /**
 264         Call this after rows have been deleted. The array will internally
 265         get copied and sorted in descending order so that the rows with
 266         the highest position will be deleted first.
 267     */
 268     void RowsDeleted(const wxArrayInt& rows);
 269
 270     /**
 271         Called in order to set a value in the model.
 272     */
 273     bool SetValue(const wxVariant& variant, unsigned int row,
 274                   unsigned int col);
 275 };
 276
 277
 278
 279 /**
 280     @class wxDataViewModel
 281     @wxheader{dataview.h}
 282
 283     wxDataViewModel is the base class for all data model to be
 284     displayed by a wxDataViewCtrl.
 285     All other models derive from it and must implement its
 286     pure virtual functions in order to define a complete
 287     data model. In detail, you need to override
 288     wxDataViewModel::IsContainer,
 289     wxDataViewModel::GetParent,
 290     wxDataViewModel::GetChildren,
 291     wxDataViewModel::GetColumnCount,
 292     wxDataViewModel::GetColumnType and
 293     wxDataViewModel::GetValue in order to
 294     define the data model which acts as an interface between
 295     your actual data and the wxDataViewCtrl. Since you will
 296     usually also allow the wxDataViewCtrl to change your data
 297     through its graphical interface, you will also have to override
 298     wxDataViewModel::SetValue which the
 299     wxDataViewCtrl will call when a change to some data has been
 300     commited.
 301
 302     wxDataViewModel (as indeed the entire wxDataViewCtrl
 303     code) is using wxVariant to store data and
 304     its type in a generic way. wxVariant can be extended to contain
 305     almost any data without changes to the original class.
 306
 307     The data that is presented through this data model is expected
 308     to change at run-time. You need to inform the data model when
 309     a change happened. Depending on what happened you need to call
 310     one of the following methods:
 311     wxDataViewModel::ValueChanged,
 312     wxDataViewModel::ItemAdded,
 313     wxDataViewModel::ItemDeleted,
 314     wxDataViewModel::ItemChanged,
 315     wxDataViewModel::Cleared. There are
 316     plural forms for notification of addition, change
 317     or removal of several item at once. See
 318     wxDataViewModel::ItemsAdded,
 319     wxDataViewModel::ItemsDeleted,
 320     wxDataViewModel::ItemsChanged.
 321
 322     Note that wxDataViewModel does not define the position or
 323     index of any item in the control because different controls
 324     might display the same data differently. wxDataViewModel does
 325     provide a wxDataViewModel::Compare method
 326     which the wxDataViewCtrl may use to sort the data either
 327     in conjunction with a column header or without (see
 328     wxDataViewModel::HasDefaultCompare).
 329
 330     This class maintains a list of
 331     wxDataViewModelNotifier
 332     which link this class to the specific implementations on the
 333     supported platforms so that e.g. calling
 334     wxDataViewModel::ValueChanged
 335     on this model will just call
 336     wxDataViewModelNotifier::ValueChanged
 337     for each notifier that has been added. You can also add
 338     your own notifier in order to get informed about any changes
 339     to the data in the list model.
 340
 341     Currently wxWidgets provides the following models apart
 342     from the base model:
 343     wxDataViewIndexListModel,
 344     wxDataViewTreeStore.
 345
 346     Note that wxDataViewModel is reference counted, derives from
 347     wxObjectRefData and cannot be deleted
 348     directly as it can be shared by several wxDataViewCtrls. This
 349     implies that you need to decrease the reference count after
 350     associating the model with a control like this:
 351
 352     @code
 353     wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, ID_MUSIC_CTRL );
 354         wxDataViewModel *musicModel = new MyMusicModel;
 355         m_musicCtrl-AssociateModel( musicModel );
 356         musicModel-DecRef();  // avoid memory leak !!
 357         // add columns now
 358     @endcode
 359
 360
 361     @library{wxadv}
 362     @category{FIXME}
 363 */
 364 class wxDataViewModel : public wxObjectRefData
 365 {
 366 public:
 367     /**
 368         Constructor.
 369     */
 370     wxDataViewModel();
 371
 372     /**
 373         Destructor. This should not be called directly. Use DecRef() instead.
 374     */
 375     ~wxDataViewModel();
 376
 377     /**
 378         Adds a wxDataViewModelNotifier
 379         to the model.
 380     */
 381     void AddNotifier(wxDataViewModelNotifier* notifier);
 382
 383     /**
 384         Called to inform the model that all data has been cleared. The
 385         control will reread the data from the model again.
 386     */
 387     virtual bool Cleared();
 388
 389     /**
 390         The compare function to be used by control. The default compare function
 391         sorts by container and other items separately and in ascending order.
 392         Override this for a different sorting behaviour.
 393         See also HasDefaultCompare().
 394     */
 395     virtual int Compare(const wxDataViewItem& item1,
 396                         const wxDataViewItem& item2,
 397                         unsigned int column,
 398                         bool ascending);
 399
 400     /**
 401         Oberride this to indicate that the item has special font attributes.
 402         This only affects the
 403         wxDataViewTextRendererText() renderer.
 404         See also wxDataViewItemAttr.
 405     */
 406     bool GetAttr(const wxDataViewItem& item, unsigned int col,
 407                  wxDataViewItemAttr& attr);
 408
 409     /**
 410         Override this so the control can query the child items of
 411         an item. Returns the number of items.
 412     */
 413     virtual unsigned int GetChildren(const wxDataViewItem& item,
 414                                      wxDataViewItemArray& children) const;
 415
 416     /**
 417         Override this to indicate the number of columns in the model.
 418     */
 419     virtual unsigned int GetColumnCount() const;
 420
 421     /**
 422         Override this to indicate what type of data is stored in the
 423         column specified by @e col. This should return a string
 424         indicating the type of data as reported by wxVariant.
 425     */
 426     virtual wxString GetColumnType(unsigned int col) const;
 427
 428     /**
 429         Override this to indicate which wxDataViewItem representing the parent
 430         of @a item or an invalid wxDataViewItem if the the root item is
 431         the parent item.
 432     */
 433     virtual wxDataViewItem GetParent(const wxDataViewItem& item) const;
 434
 435     /**
 436         Override this to indicate the value of @e item
 437         A wxVariant is used to store the data.
 438     */
 439     virtual void GetValue(wxVariant& variant,
 440                           const wxDataViewItem& item,
 441                           unsigned int col) const;
 442
 443     /**
 444         Override this method to indicate if a container item merely
 445         acts as a headline (or for categorisation) or if it also
 446         acts a normal item with entries for futher columns. By
 447         default returns @e @false.
 448     */
 449     virtual bool HasContainerColumns(const wxDataViewItem& item) const;
 450
 451     /**
 452         Override this to indicate that the model provides a default compare
 453         function that the control should use if no wxDataViewColumn has been
 454         chosen for sorting. Usually, the user clicks on a column header for
 455         sorting, the data will be sorted alphanumerically. If any other
 456         order (e.g. by index or order of appearance) is required, then this
 457         should be used. See also wxDataViewIndexListModel
 458         for a model which makes use of this.
 459     */
 460     virtual bool HasDefaultCompare() const;
 461
 462     /**
 463         Override this to indicate of @a item is a container, i.e. if
 464         it can have child items.
 465     */
 466     virtual bool IsContainer(const wxDataViewItem& item) const;
 467
 468     /**
 469         Call this to inform the model that an item has been added
 470         to the data.
 471     */
 472     virtual bool ItemAdded(const wxDataViewItem& parent,
 473                            const wxDataViewItem& item);
 474
 475     /**
 476         Call this to inform the model that an item has changed.
 477         This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
 478         event (in which the column fields will not be set) to the user.
 479     */
 480     virtual bool ItemChanged(const wxDataViewItem& item);
 481
 482     /**
 483         Call this to inform the model that an item has been deleted from the data.
 484     */
 485     virtual bool ItemDeleted(const wxDataViewItem& parent,
 486                              const wxDataViewItem& item);
 487
 488     /**
 489         Call this to inform the model that several items have been added
 490         to the data.
 491     */
 492     virtual bool ItemsAdded(const wxDataViewItem& parent,
 493                             const wxDataViewItemArray& items);
 494
 495     /**
 496         Call this to inform the model that several items have changed.
 497         This will eventually emit wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
 498         events (in which the column fields will not be set) to the user.
 499     */
 500     virtual bool ItemsChanged(const wxDataViewItemArray& items);
 501
 502     /**
 503         Call this to inform the model that several items have been deleted.
 504     */
 505     virtual bool ItemsDeleted(const wxDataViewItem& parent,
 506                               const wxDataViewItemArray& items);
 507
 508     /**
 509         Remove the @a notifier from the list of notifiers.
 510     */
 511     void RemoveNotifier(wxDataViewModelNotifier* notifier);
 512
 513     /**
 514         Call this to initiate a resort after the sort function has
 515         been changed.
 516     */
 517     virtual void Resort();
 518
 519     /**
 520         This gets called in order to set a value in the data model.
 521         The most common scenario is that the wxDataViewCtrl calls
 522         this method after the user changed some data in the view.
 523         Afterwards ValueChanged()
 524         has to be called!
 525     */
 526     virtual bool SetValue(const wxVariant& variant,
 527                           const wxDataViewItem& item,
 528                           unsigned int col);
 529
 530     /**
 531         Call this to inform this model that a value in the model has
 532         been changed. This is also called from wxDataViewCtrl's
 533         internal editing code, e.g. when editing a text field
 534         in the control.
 535         This will eventually emit a wxEVT_DATAVIEW_ITEM_VALUE_CHANGED
 536         event to the user.
 537     */
 538     virtual bool ValueChanged(const wxDataViewItem& item,
 539                               unsigned int col);
 540 };
 541
 542
 543
 544 /**
 545     @class wxDataViewCustomRenderer
 546     @wxheader{dataview.h}
 547
 548     You need to derive a new class from wxDataViewCustomRenderer in
 549     order to write a new renderer. You need to override at least
 550     wxDataViewRenderer::SetValue,
 551     wxDataViewRenderer::GetValue,
 552     wxDataViewCustomRenderer::GetSize
 553     and wxDataViewCustomRenderer::Render.
 554
 555     If you want your renderer to support in-place editing then you
 556     also need to override
 557     wxDataViewCustomRenderer::HasEditorCtrl,
 558     wxDataViewCustomRenderer::CreateEditorCtrl
 559     and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
 560     Note that a special event handler will be pushed onto that
 561     editor control which handles ENTER and focus out events
 562     in order to end the editing.
 563
 564     @library{wxadv}
 565     @category{FIXME}
 566 */
 567 class wxDataViewCustomRenderer : public wxDataViewRenderer
 568 {
 569 public:
 570     /**
 571         Constructor.
 572     */
 573     wxDataViewCustomRenderer(const wxString& varianttype = "string",
 574                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 575                              bool no_init = false);
 576
 577     /**
 578         Destructor.
 579     */
 580     ~wxDataViewCustomRenderer();
 581
 582     /**
 583         Override this to react to double clicks or ENTER.
 584     */
 585     virtual bool Activate( wxRect cell,
 586                            wxDataViewModel* model,
 587                            const wxDataViewItem & item,
 588                            unsigned int col );
 589
 590     /**
 591         Override this to create the actual editor control once editing
 592         is about to start. @a parent is the parent of the editor
 593         control, @a labelRect indicates the position and
 594         size of the editor control and @a value is its initial value:
 595     */
 596     virtual wxControl* CreateEditorCtrl(wxWindow* parent,
 597                                         wxRect labelRect,
 598                                         const wxVariant& value);
 599
 600     /**
 601         Create DC on request. Internal.
 602     */
 603     virtual wxDC* GetDC();
 604
 605     /**
 606         Return size required to show content.
 607     */
 608     virtual wxSize GetSize();
 609
 610     /**
 611         Overrride this so that the renderer can get the value
 612         from the editor control (pointed to by @e editor):
 613     */
 614     virtual bool GetValueFromEditorCtrl(wxControl* editor,
 615                                         wxVariant& value);
 616
 617     /**
 618         Override this and make it return @e @true in order to
 619         indicate that this renderer supports in-place editing.
 620     */
 621     virtual bool HasEditorCtrl();
 622
 623     /**
 624         Overrride this to react to a left click.
 625     */
 626     virtual bool LeftClick( wxPoint cursor,
 627                             wxRect cell,
 628                             wxDataViewModel * model,
 629                             const wxDataViewItem & item,
 630                             unsigned int col );
 631
 632     /**
 633         Override this to render the cell. Before this is called,
 634         wxDataViewRenderer::SetValue was called
 635         so that this instance knows what to render.
 636     */
 637     virtual bool Render(wxRect cell, wxDC* dc, int state);
 638
 639     /**
 640         This method should be called from within Render()
 641         whenever you need to render simple text. This will ensure that the
 642         correct colour, font and vertical alignment will be chosen so the
 643         text will look the same as text drawn by native renderers.
 644     */
 645     bool RenderText(const wxString& text, int xoffset, wxRect cell,
 646                     wxDC* dc, int state);
 647
 648     /**
 649         Overrride this to react to a right click.
 650     */
 651     virtual bool RightClick(wxPoint cursor,
 652                             wxRect cell,
 653                             wxDataViewModel* model,
 654                             const wxDataViewItem & item,
 655                             unsigned int col);
 656
 657     /**
 658         Overrride this to start a drag operation.
 659     */
 660     virtual bool StartDrag(wxPoint cursor, wxRect cell,
 661                            wxDataViewModel* model,
 662                            const wxDataViewItem & item,
 663                            unsigned int col);
 664 };
 665
 666
 667
 668 /**
 669     @class wxDataViewBitmapRenderer
 670     @wxheader{dataview.h}
 671
 672     wxDataViewBitmapRenderer
 673
 674     @library{wxadv}
 675     @category{FIXME}
 676 */
 677 class wxDataViewBitmapRenderer : public wxDataViewRenderer
 678 {
 679 public:
 680     /**
 681
 682     */
 683     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
 684                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
 685 };
 686
 687
 688
 689 /**
 690     @class wxDataViewItemAttr
 691     @wxheader{dataview.h}
 692
 693     This class is used to indicate to a wxDataViewCtrl
 694     that a certain Item() has extra font attributes
 695     for its renderer. For this, it is required to override
 696     wxDataViewModel::GetAttr.
 697
 698     Attributes are currently only supported by
 699     wxDataViewTextRendererText().
 700
 701     @library{wxadv}
 702     @category{FIXME}
 703 */
 704 class wxDataViewItemAttr
 705 {
 706 public:
 707     /**
 708         Constructor.
 709     */
 710     wxDataViewItemAttr();
 711
 712     /**
 713         Call this to indicate that the item shall be displayed in bold text.
 714     */
 715     void SetBold(bool set);
 716
 717     /**
 718         Call this to indicate that the item shall be displayed with
 719         that colour.
 720     */
 721     void SetColour(const wxColour& colour);
 722
 723     /**
 724         Call this to indicate that the item shall be displayed in italic text.
 725     */
 726     void SetItalic(bool set);
 727 };
 728
 729
 730
 731 /**
 732     @class wxDataViewItem
 733     @wxheader{dataview.h}
 734
 735     wxDataViewItem is a small opaque class that represents an
 736     item in a wxDataViewCtrl in a
 737     persistent way, i.e. indepent of the position of the
 738     item in the control or changes to its contents. It must
 739     hold a unique ID of type @e void* in its only field
 740     and can be converted to a from it.
 741
 742     If the ID is @e @NULL the wxDataViewItem is invalid and
 743     wxDataViewItem::IsOk will return @e @false
 744     which used in many places in the API of wxDataViewCtrl
 745     to indicate that e.g. no item was found. An ID of @NULL
 746     is also used to indicate the invisible root. Examples
 747     for this are
 748     wxDataViewModel::GetParent and
 749     wxDataViewModel::GetChildren.
 750
 751     @library{wxadv}
 752     @category{FIXME}
 753 */
 754 class wxDataViewItem
 755 {
 756 public:
 757     //@{
 758     /**
 759
 760     */
 761     wxDataViewItem(void* id = NULL);
 762     wxDataViewItem(const wxDataViewItem& item);
 763     //@}
 764
 765     /**
 766         Returns the ID.
 767     */
 768     void* GetID() const;
 769
 770     /**
 771         Returns @true if the ID is not @e @NULL.
 772     */
 773     bool IsOk() const;
 774 };
 775
 776
 777
 778 /**
 779     @class wxDataViewCtrl
 780     @wxheader{dataview.h}
 781
 782     wxDataViewCtrl is a control to display data either
 783     in a tree like fashion or in a tabular form or both.
 784     If you only need to display a simple tree structure
 785     with an API more like the older wxTreeCtrl class,
 786     then the specialized wxDataViewTreeCtrl
 787     can be used.
 788
 789     A wxDataViewItem is used
 790     to represent a (visible) item in the control.
 791
 792     Unlike wxListCtrl wxDataViewCtrl doesn't
 793     get its data from the user through virtual functions or by
 794     setting it directly. Instead you need to write your own
 795     wxDataViewModel and associate
 796     it with this control. Then you need to add a number of
 797     wxDataViewColumn to this control to
 798     define what each column shall display. Each wxDataViewColumn
 799     in turn owns 1 instance of a
 800     wxDataViewRenderer to render its
 801     cells. A number of standard renderers for rendering text, dates,
 802     images, toggle, a progress bar etc. are provided. Additionally,
 803     the user can write custom renderes deriving from
 804     wxDataViewCustomRenderer
 805     for displaying anything.
 806
 807     All data transfer from the control to the model and the user
 808     code is done through wxVariant which can
 809     be extended to support more data formats as necessary.
 810     Accordingly, all type information uses the strings returned
 811     from wxVariant::GetType.
 812
 813     @beginStyleTable
 814     @style{wxDV_SINGLE}:
 815            Single selection mode. This is the default.
 816     @style{wxDV_MULTIPLE}:
 817            Multiple selection mode.
 818     @style{wxDV_ROW_LINES}:
 819            Use alternating colours for rows if supported by platform and theme.
 820     @style{wxDV_HORIZ_RULES}:
 821            Display fine rules between row if supported.
 822     @style{wxDV_VERT_RULES}:
 823            Display fine rules between columns is supported.
 824     @endStyleTable
 825
 826     @library{wxadv}
 827     @category{ctrl}
 828     @appearance{dataviewctrl.png}
 829 */
 830 class wxDataViewCtrl : public wxControl
 831 {
 832 public:
 833     //@{
 834     /**
 835         Constructor. Calls Create().
 836     */
 837     wxDataViewCtrl();
 838     wxDataViewCtrl(wxWindow* parent, wxWindowID id,
 839                    const wxPoint& pos = wxDefaultPosition,
 840                    const wxSize& size = wxDefaultSize,
 841                    long style = 0,
 842                    const wxValidator& validator = wxDefaultValidator);
 843     //@}
 844
 845     /**
 846         Destructor.
 847     */
 848     ~wxDataViewCtrl();
 849
 850     //@{
 851     /**
 852         Appends a column for rendering a bitmap. Returns the wxDataViewColumn
 853         created in the function or @NULL on failure.
 854     */
 855     wxDataViewColumn* AppendBitmapColumn(const wxString& label,
 856                                          unsigned int model_column,
 857                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 858                                          int width = -1,
 859                                          wxAlignment align = wxALIGN_CENTER,
 860                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 861     wxDataViewColumn* AppendBitmapColumn(const wxBitmap& label,
 862                                          unsigned int model_column,
 863                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 864                                          int width = -1,
 865                                          wxAlignment align = wxALIGN_CENTER,
 866                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 867     //@}
 868
 869     /**
 870         Add a wxDataViewColumn to the control. Returns
 871         @e @true on success.
 872         Note that there is a number of short cut methods which implicitly create
 873         a wxDataViewColumn and a
 874         wxDataViewRenderer for it (see below).
 875     */
 876     virtual bool AppendColumn(wxDataViewColumn* col);
 877
 878     //@{
 879     /**
 880         Appends a column for rendering a date. Returns the wxDataViewColumn
 881         created in the function or @NULL on failure.
 882     */
 883     wxDataViewColumn* AppendDateColumn(const wxString& label,
 884                                        unsigned int model_column,
 885                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
 886                                        int width = -1,
 887                                        wxAlignment align = wxALIGN_CENTER,
 888                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 889     wxDataViewColumn* AppendDateColumn(const wxBitmap& label,
 890                                        unsigned int model_column,
 891                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
 892                                        int width = -1,
 893                                        wxAlignment align = wxALIGN_CENTER,
 894                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 895     //@}
 896
 897     //@{
 898     /**
 899         Appends a column for rendering text with an icon. Returns the wxDataViewColumn
 900         created in the function or @NULL on failure. This uses the
 901         wxDataViewIconTextRenderer.
 902     */
 903     wxDataViewColumn* AppendIconTextColumn(const wxString& label,
 904                                            unsigned int model_column,
 905                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 906                                            int width = -1,
 907                                            wxAlignment align = wxALIGN_LEFT,
 908                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 909     wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label,
 910                                            unsigned int model_column,
 911                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 912                                            int width = -1,
 913                                            wxAlignment align = wxALIGN_LEFT,
 914                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 915     //@}
 916
 917     //@{
 918     /**
 919         Appends a column for rendering a progress indicator. Returns the
 920         wxDataViewColumn
 921         created in the function or @NULL on failure.
 922     */
 923     wxDataViewColumn* AppendProgressColumn(const wxString& label,
 924                                            unsigned int model_column,
 925                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 926                                            int width = 80,
 927                                            wxAlignment align = wxALIGN_CENTER,
 928                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 929     wxDataViewColumn* AppendProgressColumn(const wxBitmap& label,
 930                                            unsigned int model_column,
 931                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 932                                            int width = 80,
 933                                            wxAlignment align = wxALIGN_CENTER,
 934                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 935     //@}
 936
 937     //@{
 938     /**
 939         Appends a column for rendering text. Returns the wxDataViewColumn
 940         created in the function or @NULL on failure.
 941     */
 942     wxDataViewColumn* AppendTextColumn(const wxString& label,
 943                                        unsigned int model_column,
 944                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 945                                        int width = -1,
 946                                        wxAlignment align = wxALIGN_LEFT,
 947                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 948     wxDataViewColumn* AppendTextColumn(const wxBitmap& label,
 949                                        unsigned int model_column,
 950                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 951                                        int width = -1,
 952                                        wxAlignment align = wxALIGN_LEFT,
 953                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 954     //@}
 955
 956     //@{
 957     /**
 958         Appends a column for rendering a toggle. Returns the wxDataViewColumn
 959         created in the function or @NULL on failure.
 960     */
 961     wxDataViewColumn* AppendToggleColumn(const wxString& label,
 962                                          unsigned int model_column,
 963                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 964                                          int width = 30,
 965                                          wxAlignment align = wxALIGN_CENTER,
 966                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 967     wxDataViewColumn* AppendToggleColumn(const wxBitmap& label,
 968                                          unsigned int model_column,
 969                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 970                                          int width = 30,
 971                                          wxAlignment align = wxALIGN_CENTER,
 972                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 973     //@}
 974
 975     /**
 976         Associates a wxDataViewModel with the
 977         control. This increases the reference count of the model by 1.
 978     */
 979     virtual bool AssociateModel(wxDataViewModel* model);
 980
 981     /**
 982         Removes all columns.
 983     */
 984     virtual bool ClearColumns();
 985
 986     /**
 987         Unselects all rows.
 988     */
 989     void ClearSelection();
 990
 991     /**
 992         Collapses the item.
 993     */
 994     void Collapse(const wxDataViewItem& item);
 995
 996     /**
 997         Create the control. Useful for two step creation.
 998     */
 999     bool Create(wxWindow* parent, wxWindowID id,
1000                 const wxPoint& pos = wxDefaultPosition,
1001                 const wxSize& size = wxDefaultSize,
1002                 long style = 0,
1003                 const wxValidator& validator = wxDefaultValidator);
1004
1005     /**
1006         Deletes given column.
1007     */
1008     virtual bool DeleteColumn(const wxDataViewColumn* column);
1009
1010     /**
1011         Call this to ensure that the given item is visible.
1012     */
1013     void EnsureVisible(const wxDataViewItem& item,
1014                        const wxDataViewColumn* column = NULL);
1015
1016     /**
1017         Expands the item.
1018     */
1019     void Expand(const wxDataViewItem& item);
1020
1021     /**
1022         Returns pointer to the column. @a pos refers to the
1023         position in the control which may change after reordering
1024         columns by the user.
1025     */
1026     virtual wxDataViewColumn* GetColumn(unsigned int pos) const;
1027
1028     /**
1029         Returns the number of columns.
1030     */
1031     virtual unsigned int GetColumnCount() const;
1032
1033     /**
1034         Returns the position of the column or -1 if not found in the control.
1035     */
1036     virtual int GetColumnPosition(const wxDataViewColumn* column) const;
1037
1038     /**
1039         Returns column containing the expanders.
1040     */
1041     wxDataViewColumn* GetExpanderColumn() const;
1042
1043     /**
1044         Returns indentation.
1045     */
1046     int GetIndent() const;
1047
1048     /**
1049         Returns item rect.
1050     */
1051     wxRect GetItemRect(const wxDataViewItem& item,
1052                        const wxDataViewColumn* col = NULL) const;
1053
1054     /**
1055         Returns pointer to the data model associated with the
1056         control (if any).
1057     */
1058     virtual wxDataViewModel* GetModel() const;
1059
1060     /**
1061         Returns first selected item or an invalid item if none is selected.
1062     */
1063     wxDataViewItem GetSelection() const;
1064
1065     /**
1066         Fills @a sel with currently selected items and returns
1067         their number.
1068     */
1069     int GetSelections(wxDataViewItemArray& sel) const;
1070
1071     /**
1072         Returns the wxDataViewColumn currently responsible for sorting
1073         or @NULL if none has been selected.
1074     */
1075     virtual wxDataViewColumn* GetSortingColumn() const;
1076
1077     /**
1078         Hittest.
1079     */
1080     void HitTest(const wxPoint& point, wxDataViewItem& item,
1081                  wxDataViewColumn*& col) const;
1082
1083     /**
1084         Return @true if the item is selected.
1085     */
1086     bool IsSelected(const wxDataViewItem& item) const;
1087
1088     /**
1089         Select the given item.
1090     */
1091     void Select(const wxDataViewItem& item);
1092
1093     /**
1094         Select all items.
1095     */
1096     void SelectAll();
1097
1098     /**
1099         Set which column shall contain the tree-like expanders.
1100     */
1101     void SetExpanderColumn(wxDataViewColumn* col);
1102
1103     /**
1104         Sets the indendation.
1105     */
1106     void SetIndent(int indent);
1107
1108     /**
1109         Sets the selection to the array of wxDataViewItems.
1110     */
1111     void SetSelections(const wxDataViewItemArray& sel);
1112
1113     /**
1114         Unselect the given item.
1115     */
1116     void Unselect(const wxDataViewItem& item);
1117
1118     /**
1119         Unselect all item. This method only has effect if multiple
1120         selections are allowed.
1121     */
1122     void UnselectAll();
1123 };
1124
1125
1126
1127 /**
1128     @class wxDataViewModelNotifier
1129     @wxheader{dataview.h}
1130
1131     A wxDataViewModelNotifier instance is owned by a
1132     wxDataViewModel
1133     and mirrors its notification interface. See
1134     the documentation of that class for further
1135     information.
1136
1137     @library{wxbase}
1138     @category{FIXME}
1139 */
1140 class wxDataViewModelNotifier
1141 {
1142 public:
1143     /**
1144         Constructor.
1145     */
1146     wxDataViewModelNotifier();
1147
1148     /**
1149         Destructor.
1150     */
1151     ~wxDataViewModelNotifier();
1152
1153     /**
1154         Called by owning model.
1155     */
1156     bool Cleared();
1157
1158     /**
1159         Get owning wxDataViewModel.
1160     */
1161     wxDataViewModel* GetOwner();
1162
1163     /**
1164         Called by owning model.
1165     */
1166     bool ItemAdded(const wxDataViewItem& parent,
1167                    const wxDataViewItem& item);
1168
1169     /**
1170         Called by owning model.
1171     */
1172     bool ItemChanged(const wxDataViewItem& item);
1173
1174     /**
1175         Called by owning model.
1176     */
1177     bool ItemDeleted(const wxDataViewItem& parent,
1178                      const wxDataViewItem& item);
1179
1180     /**
1181         Called by owning model.
1182     */
1183     bool ItemsAdded(const wxDataViewItem& parent,
1184                     const wxDataViewItemArray& items);
1185
1186     /**
1187         Called by owning model.
1188     */
1189     bool ItemsChanged(const wxDataViewItemArray& items);
1190
1191     /**
1192         Called by owning model.
1193     */
1194     bool ItemsDeleted(const wxDataViewItem& parent,
1195                       const wxDataViewItemArray& items);
1196
1197     /**
1198         Called by owning model.
1199     */
1200     void Resort();
1201
1202     /**
1203         Set owner of this notifier. Used internally.
1204     */
1205     void SetOwner(wxDataViewModel* owner);
1206
1207     /**
1208         Called by owning model.
1209     */
1210     bool ValueChanged(const wxDataViewItem& item, unsigned int col);
1211 };
1212
1213
1214
1215 /**
1216     @class wxDataViewRenderer
1217     @wxheader{dataview.h}
1218
1219     This class is used by wxDataViewCtrl to
1220     render the individual cells. One instance of a renderer class is
1221     owned by wxDataViewColumn. There is
1222     a number of ready-to-use renderers provided:
1223     wxDataViewTextRenderer,
1224     wxDataViewTextRendererAttr,
1225     wxDataViewIconTextRenderer,
1226     wxDataViewToggleRenderer,
1227     wxDataViewProgressRenderer,
1228     wxDataViewBitmapRenderer,
1229     wxDataViewDateRenderer.
1230     wxDataViewSpinRenderer.
1231
1232     Additionally, the user can write own renderers by deriving from
1233     wxDataViewCustomRenderer.
1234
1235     The @e wxDataViewCellMode flag controls, what actions
1236     the cell data allows. @e wxDATAVIEW_CELL_ACTIVATABLE
1237     indicates that the user can double click the cell and
1238     something will happen (e.g. a window for editing a date
1239     will pop up). @e wxDATAVIEW_CELL_EDITABLE indicates
1240     that the user can edit the data in-place, i.e. an control
1241     will show up after a slow click on the cell. This behaviour
1242     is best known from changing the filename in most file
1243     managers etc.
1244
1245
1246     @code
1247     enum wxDataViewCellMode
1248     {
1249         wxDATAVIEW_CELL_INERT,
1250         wxDATAVIEW_CELL_ACTIVATABLE,
1251         wxDATAVIEW_CELL_EDITABLE
1252     };
1253     @endcode
1254
1255     The @e wxDataViewCellRenderState flag controls how the
1256     the renderer should display its contents in a cell:
1257
1258     @code
1259     enum wxDataViewCellRenderState
1260     {
1261         wxDATAVIEW_CELL_SELECTED    = 1,
1262         wxDATAVIEW_CELL_PRELIT      = 2,
1263         wxDATAVIEW_CELL_INSENSITIVE = 4,
1264         wxDATAVIEW_CELL_FOCUSED     = 8
1265     };
1266     @endcode
1267
1268
1269     @library{wxadv}
1270     @category{FIXME}
1271 */
1272 class wxDataViewRenderer : public wxObject
1273 {
1274 public:
1275     /**
1276         Constructor.
1277     */
1278     wxDataViewRenderer(const wxString& varianttype,
1279                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1280                        int alignment = wxALIGN_LEFT|wxALIGN_CENTRE_VERTICAL);
1281
1282     /**
1283         Returns the cell mode.
1284     */
1285     virtual wxDataViewCellMode GetMode();
1286
1287     /**
1288         Returns pointer to the owning wxDataViewColumn.
1289     */
1290     virtual wxDataViewColumn* GetOwner();
1291
1292     /**
1293         This methods retrieves the value from the renderer in order to
1294         transfer the value back to the data model. Returns @e @false
1295         on failure.
1296     */
1297     virtual bool GetValue(wxVariant& value);
1298
1299     /**
1300         Returns a string with the type of the wxVariant
1301         supported by this renderer.
1302     */
1303     virtual wxString GetVariantType();
1304
1305     /**
1306         Sets the owning wxDataViewColumn. This
1307         is usually called from within wxDataViewColumn.
1308     */
1309     virtual void SetOwner(wxDataViewColumn* owner);
1310
1311     /**
1312         Set the value of the renderer (and thus its cell) to @e value.
1313         The internal code will then render this cell with this data.
1314     */
1315     virtual bool SetValue(const wxVariant& value);
1316
1317     /**
1318         Before data is committed to the data model, it is passed to this
1319         method where it can be checked for validity. This can also be
1320         used for checking a valid range or limiting the user input in
1321         a certain aspect (e.g. max number of characters or only alphanumeric
1322         input, ASCII only etc.). Return @e @false if the value is
1323         not valid.
1324         Please note that due to implementation limitations, this validation
1325         is done after the editing control already is destroyed and the
1326         editing process finished.
1327     */
1328     virtual bool Validate(wxVariant& value);
1329 };
1330
1331
1332
1333 /**
1334     @class wxDataViewTextRenderer
1335     @wxheader{dataview.h}
1336
1337     wxDataViewTextRenderer is used for rendering text. It supports
1338     in-place editing if desired.
1339
1340     @library{wxadv}
1341     @category{FIXME}
1342 */
1343 class wxDataViewTextRenderer : public wxDataViewRenderer
1344 {
1345 public:
1346     /**
1347
1348     */
1349     wxDataViewTextRenderer(const wxString& varianttype = "string",
1350                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
1351 };
1352
1353
1354
1355 /**
1356     @class wxDataViewProgressRenderer
1357     @wxheader{dataview.h}
1358
1359     wxDataViewProgressRenderer
1360
1361     @library{wxadv}
1362     @category{FIXME}
1363 */
1364 class wxDataViewProgressRenderer : public wxDataViewRenderer
1365 {
1366 public:
1367     /**
1368
1369     */
1370     wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
1371                                const wxString& varianttype = "long",
1372                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
1373 };
1374
1375
1376
1377 /**
1378     @class wxDataViewSpinRenderer
1379     @wxheader{dataview.h}
1380
1381     This is a specialized renderer for rendering integer values. It
1382     supports modifying the values in-place by using a wxSpinCtrl.
1383     The renderer only support variants of type @e long.
1384
1385     @library{wxbase}
1386     @category{FIXME}
1387 */
1388 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
1389 {
1390 public:
1391     /**
1392         Constructor. @a min and @a max indicate the minimum und
1393         maximum values of for the wxSpinCtrl.
1394     */
1395     wxDataViewSpinRenderer(int min, int max,
1396                            wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1397                            int alignment = wxDVR_DEFAULT_ALIGNMENT);
1398 };
1399
1400
1401
1402 /**
1403     @class wxDataViewToggleRenderer
1404     @wxheader{dataview.h}
1405
1406     wxDataViewToggleRenderer
1407
1408     @library{wxadv}
1409     @category{FIXME}
1410 */
1411 class wxDataViewToggleRenderer : public wxDataViewRenderer
1412 {
1413 public:
1414     /**
1415
1416     */
1417     wxDataViewToggleRenderer(const wxString& varianttype = "bool",
1418                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
1419 };
1420
1421
1422
1423 /**
1424     @class wxDataViewTreeCtrl
1425     @wxheader{dataview.h}
1426
1427     This class is a wxDataViewCtrl which internally
1428     uses a wxDataViewTreeStore and forwards
1429     most of its API to that class. Additionally, it uses a wxImageList
1430     to store a list of icons. The main purpose of this class is to look
1431     like a wxTreeCtrl to make a transition from it
1432     to the wxDataViewCtrl class simpler.
1433
1434     @library{wxbase}
1435     @category{ctrl}
1436     @appearance{dataviewtreectrl.png}
1437 */
1438 class wxDataViewTreeCtrl : public wxDataViewCtrl
1439 {
1440 public:
1441     //@{
1442     /**
1443         Constructor. Calls Create().
1444     */
1445     wxDataViewTreeCtrl();
1446     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
1447                        const wxPoint& pos = wxDefaultPosition,
1448                        const wxSize& size = wxDefaultSize,
1449                        long style = wxDV_NO_HEADER,
1450                        const wxValidator& validator = wxDefaultValidator);
1451     //@}
1452
1453     /**
1454         Destructor. Deletes the image list if any.
1455     */
1456     ~wxDataViewTreeCtrl();
1457
1458     /**
1459
1460     */
1461     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1462                                    const wxString& text,
1463                                    int icon = -1,
1464                                    int expanded = -1,
1465                                    wxClientData* data = NULL);
1466
1467     /**
1468
1469     */
1470     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1471                               const wxString& text,
1472                               int icon = -1,
1473                               wxClientData* data = NULL);
1474
1475     /**
1476         Creates the control and a wxDataViewTreeStore as
1477         its internal model.
1478     */
1479     bool Create(wxWindow* parent, wxWindowID id,
1480                 const wxPoint& pos = wxDefaultPosition,
1481                 const wxSize& size = wxDefaultSize,
1482                 long style = wxDV_NO_HEADER,
1483                 const wxValidator& validator = wxDefaultValidator);
1484
1485     /**
1486         Calls the identical method from wxDataViewTreeStore.
1487     */
1488     void DeleteAllItems();
1489
1490     /**
1491         Calls the identical method from wxDataViewTreeStore.
1492     */
1493     void DeleteChildren(const wxDataViewItem& item);
1494
1495     /**
1496         Calls the identical method from wxDataViewTreeStore.
1497     */
1498     void DeleteItem(const wxDataViewItem& item);
1499
1500     /**
1501         Calls the identical method from wxDataViewTreeStore.
1502     */
1503     int GetChildCount(const wxDataViewItem& parent) const;
1504
1505     /**
1506         Returns the image list.
1507     */
1508     wxImageList* GetImageList();
1509
1510     /**
1511         Calls the identical method from wxDataViewTreeStore.
1512     */
1513     wxClientData* GetItemData(const wxDataViewItem& item) const;
1514
1515     /**
1516         Calls the identical method from wxDataViewTreeStore.
1517     */
1518     const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const;
1519
1520     /**
1521         Calls the identical method from wxDataViewTreeStore.
1522     */
1523     const wxIcon GetItemIcon(const wxDataViewItem& item) const;
1524
1525     /**
1526         Calls the identical method from wxDataViewTreeStore.
1527     */
1528     wxString GetItemText(const wxDataViewItem& item) const;
1529
1530     /**
1531         Calls the identical method from wxDataViewTreeStore.
1532     */
1533     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1534                                unsigned int pos) const;
1535
1536     //@{
1537     /**
1538         Returns the store.
1539     */
1540     wxDataViewTreeStore* GetStore() const;
1541     const wxDataViewTreeStore* GetStore() const;
1542     //@}
1543
1544     /**
1545         Calls the same method from wxDataViewTreeStore but uess
1546         and index position in the image list instead of a wxIcon.
1547     */
1548     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1549                                    const wxDataViewItem& previous,
1550                                    const wxString& text,
1551                                    int icon = -1,
1552                                    int expanded = -1,
1553                                    wxClientData* data = NULL);
1554
1555     /**
1556         Calls the same method from wxDataViewTreeStore but uess
1557         and index position in the image list instead of a wxIcon.
1558     */
1559     wxDataViewItem InsertItem(const wxDataViewItem& parent,
1560                               const wxDataViewItem& previous,
1561                               const wxString& text,
1562                               int icon = -1,
1563                               wxClientData* data = NULL);
1564
1565     /**
1566         Calls the same method from wxDataViewTreeStore but uess
1567         and index position in the image list instead of a wxIcon.
1568     */
1569     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1570                                     const wxString& text,
1571                                     int icon = -1,
1572                                     int expanded = -1,
1573                                     wxClientData* data = NULL);
1574
1575     /**
1576         Calls the same method from wxDataViewTreeStore but uess
1577         and index position in the image list instead of a wxIcon.
1578     */
1579     wxDataViewItem PrependItem(const wxDataViewItem& parent,
1580                                const wxString& text,
1581                                int icon = -1,
1582                                wxClientData* data = NULL);
1583
1584     /**
1585         Sets the image list.
1586     */
1587     void SetImageList(wxImageList* imagelist);
1588
1589     /**
1590         Calls the identical method from wxDataViewTreeStore.
1591     */
1592     void SetItemData(const wxDataViewItem& item, wxClientData* data);
1593
1594     /**
1595         Calls the identical method from wxDataViewTreeStore.
1596     */
1597     void SetItemExpandedIcon(const wxDataViewItem& item,
1598                              const wxIcon& icon);
1599
1600     /**
1601         Calls the identical method from wxDataViewTreeStore.
1602     */
1603     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1604
1605     /**
1606         Calls the identical method from wxDataViewTreeStore.
1607     */
1608     void SetItemText(const wxDataViewItem& item,
1609                      const wxString& text);
1610 };
1611
1612
1613
1614 /**
1615     @class wxDataViewTreeStore
1616     @wxheader{dataview.h}
1617
1618     wxDataViewTreeStore is a specialised wxDataViewModel
1619     for displaying simple trees very much like wxTreeCtrl
1620     does and it offers a similar API. This class actually stores the entire
1621     tree (therefore its name) and implements all virtual methods from the base
1622     class so it can be used directly without having to derive any class from it.
1623     This comes at the price of much reduced flexibility.
1624
1625     @library{wxadv}
1626     @category{FIXME}
1627 */
1628 class wxDataViewTreeStore : public wxDataViewModel
1629 {
1630 public:
1631     /**
1632         Constructor. Creates the invisible root node internally.
1633     */
1634     wxDataViewTreeStore();
1635
1636     /**
1637         Destructor.
1638     */
1639     ~wxDataViewTreeStore();
1640
1641     /**
1642         Append a container.
1643     */
1644     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1645                                    const wxString& text,
1646                                    const wxIcon& icon = wxNullIcon,
1647                                    const wxIcon& expanded = wxNullIcon,
1648                                    wxClientData* data = NULL);
1649
1650     /**
1651         Append an item.
1652     */
1653     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1654                               const wxString& text,
1655                               const wxIcon& icon = wxNullIcon,
1656                               wxClientData* data = NULL);
1657
1658     /**
1659         Delete all item in the model.
1660     */
1661     void DeleteAllItems();
1662
1663     /**
1664         Delete all children of the item, but not the item itself.
1665     */
1666     void DeleteChildren(const wxDataViewItem& item);
1667
1668     /**
1669         Delete this item.
1670     */
1671     void DeleteItem(const wxDataViewItem& item);
1672
1673     /**
1674         Return the number of children of item.
1675     */
1676     int GetChildCount(const wxDataViewItem& parent) const;
1677
1678     /**
1679         Returns the client data asoociated with the item.
1680     */
1681     wxClientData* GetItemData(const wxDataViewItem& item) const;
1682
1683     /**
1684         Returns the icon to display in expanded containers.
1685     */
1686     const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const;
1687
1688     /**
1689         Returns the icon of the item.
1690     */
1691     const wxIcon GetItemIcon(const wxDataViewItem& item) const;
1692
1693     /**
1694         Returns the text of the item.
1695     */
1696     wxString GetItemText(const wxDataViewItem& item) const;
1697
1698     /**
1699         Returns the nth child item of item.
1700     */
1701     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1702                                unsigned int pos) const;
1703
1704     /**
1705         Inserts a container after @e previous.
1706     */
1707     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1708                                    const wxDataViewItem& previous,
1709                                    const wxString& text,
1710                                    const wxIcon& icon = wxNullIcon,
1711                                    const wxIcon& expanded = wxNullIcon,
1712                                    wxClientData* data = NULL);
1713
1714     /**
1715         Inserts an item after @e previous.
1716     */
1717     wxDataViewItem InsertItem(const wxDataViewItem& parent,
1718                               const wxDataViewItem& previous,
1719                               const wxString& text,
1720                               const wxIcon& icon = wxNullIcon,
1721                               wxClientData* data = NULL);
1722
1723     /**
1724         Inserts a container before the first child item or @e parent.
1725     */
1726     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1727                                     const wxString& text,
1728                                     const wxIcon& icon = wxNullIcon,
1729                                     const wxIcon& expanded = wxNullIcon,
1730                                     wxClientData* data = NULL);
1731
1732     /**
1733         Inserts an item before the first child item or @e parent.
1734     */
1735     wxDataViewItem PrependItem(const wxDataViewItem& parent,
1736                                const wxString& text,
1737                                const wxIcon& icon = wxNullIcon,
1738                                wxClientData* data = NULL);
1739
1740     /**
1741         Sets the client data associated with the item.
1742     */
1743     void SetItemData(const wxDataViewItem& item, wxClientData* data);
1744
1745     /**
1746         Sets the expanded icon for the item.
1747     */
1748     void SetItemExpandedIcon(const wxDataViewItem& item,
1749                              const wxIcon& icon);
1750
1751     /**
1752         Sets the icon for the item.
1753     */
1754     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1755 };
1756
1757
1758
1759 /**
1760     @class wxDataViewDateRenderer
1761     @wxheader{dataview.h}
1762
1763     wxDataViewDateRenderer
1764
1765     @library{wxadv}
1766     @category{FIXME}
1767 */
1768 class wxDataViewDateRenderer : public wxDataViewRenderer
1769 {
1770 public:
1771     /**
1772
1773     */
1774     wxDataViewDateRenderer(const wxString& varianttype = "datetime",
1775                            wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE);
1776 };
1777
1778
1779
1780 /**
1781     @class wxDataViewTextRendererAttr
1782     @wxheader{dataview.h}
1783
1784     The same as wxDataViewTextRenderer but with
1785     support for font attributes. Font attributes are currently only supported
1786     under GTK+ and MSW.
1787
1788     See also wxDataViewModel::GetAttr and
1789     wxDataViewItemAttr.
1790
1791     @library{wxadv}
1792     @category{FIXME}
1793 */
1794 class wxDataViewTextRendererAttr : public wxDataViewTextRenderer
1795 {
1796 public:
1797     /**
1798
1799     */
1800     wxDataViewTextRendererAttr(const wxString& varianttype = "string",
1801                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1802                                int align = wxDVR_DEFAULT_ALIGNMENT);
1803 };
1804
1805
1806
1807 /**
1808     @class wxDataViewColumn
1809     @wxheader{dataview.h}
1810
1811     This class represents a column in a wxDataViewCtrl.
1812     One wxDataViewColumn is bound to one column in the data model,
1813     to which the wxDataViewCtrl has been associated.
1814
1815     An instance of wxDataViewRenderer is used by
1816     this class to render its data.
1817
1818     @library{wxadv}
1819     @category{FIXME}
1820 */
1821 class wxDataViewColumn : public wxObject
1822 {
1823 public:
1824     //@{
1825     /**
1826         Constructors.
1827     */
1828     wxDataViewColumn(const wxString& title,
1829                      wxDataViewRenderer* renderer,
1830                      unsigned int model_column,
1831                      int width = wxDVC_DEFAULT_WIDTH,
1832                      wxAlignment align = wxALIGN_CENTRE,
1833                      int flags = wxDATAVIEW_COL_RESIZABLE);
1834     wxDataViewColumn(const wxBitmap& bitmap,
1835                      wxDataViewRenderer* renderer,
1836                      unsigned int model_column,
1837                      int width = wxDVC_DEFAULT_WIDTH,
1838                      wxAlignment align = wxALIGN_CENTRE,
1839                      int flags = wxDATAVIEW_COL_RESIZABLE);
1840     //@}
1841
1842     /**
1843         Destructor.
1844     */
1845     ~wxDataViewColumn();
1846
1847     /**
1848         Returns the bitmap in the header of the column, if any.
1849     */
1850     const wxBitmap GetBitmap();
1851
1852     /**
1853         Returns the index of the column of the model, which this
1854         wxDataViewColumn is displaying.
1855     */
1856     unsigned int GetModelColumn();
1857
1858     /**
1859         Returns the owning wxDataViewCtrl.
1860     */
1861     wxDataViewCtrl* GetOwner();
1862
1863     /**
1864         Returns the renderer of this wxDataViewColumn.
1865         See also wxDataViewRenderer.
1866     */
1867     wxDataViewRenderer* GetRenderer();
1868
1869     /**
1870         Returns @true if the column is reorderable.
1871     */
1872     bool GetReorderable();
1873
1874     /**
1875         Returns @true if the column is sortable.
1876         See SetSortable()
1877     */
1878     bool GetSortable();
1879
1880     /**
1881         Returns the width of the column.
1882     */
1883     int GetWidth();
1884
1885     /**
1886         Returns @true, if the sort order is ascending.
1887         See also SetSortOrder()
1888     */
1889     bool IsSortOrderAscending();
1890
1891     /**
1892         Set the alignment of the column header.
1893     */
1894     void SetAlignment(wxAlignment align);
1895
1896     /**
1897         Set the bitmap of the column header.
1898     */
1899     void SetBitmap(const wxBitmap& bitmap);
1900
1901     /**
1902         Indicate wether the column can be reordered by the
1903         user using the mouse. This is typically implemented
1904         visually by dragging the header button around.
1905     */
1906     void SetReorderable(bool reorderable);
1907
1908     /**
1909         Indicate the sort order if the implementation of the
1910         wxDataViewCtrl supports it, most commonly by showing
1911         a little arrow.
1912     */
1913     void SetSortOrder(bool ascending);
1914
1915     /**
1916         Indicate that the column is sortable. This does
1917         not show any sorting indicate yet, but it does
1918         make the column header clickable. Call
1919         SetSortOrder()
1920         afterwards to actually make the sort indicator appear.
1921         If @a sortable is @false, the column header is
1922         no longer clickable and the sort indicator (little
1923         arrow) will disappear.
1924     */
1925     void SetSortable(bool sortable);
1926
1927     /**
1928         Set the title of the column header to @e title.
1929     */
1930     void SetTitle(const wxString& title);
1931 };
1932