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, wxDataViewModel* model,
 586                           unsigned int col,
 587                           unsigned int row);
 588
 589     /**
 590         Override this to create the actual editor control once editing
 591         is about to start. @a parent is the parent of the editor
 592         control, @a labelRect indicates the position and
 593         size of the editor control and @a value is its initial value:
 594     */
 595     virtual wxControl* CreateEditorCtrl(wxWindow* parent,
 596                                         wxRect labelRect,
 597                                         const wxVariant& value);
 598
 599     /**
 600         Create DC on request. Internal.
 601     */
 602     virtual wxDC* GetDC();
 603
 604     /**
 605         Return size required to show content.
 606     */
 607     virtual wxSize GetSize();
 608
 609     /**
 610         Overrride this so that the renderer can get the value
 611         from the editor control (pointed to by @e editor):
 612     */
 613     virtual bool GetValueFromEditorCtrl(wxControl* editor,
 614                                         wxVariant& value);
 615
 616     /**
 617         Override this and make it return @e @true in order to
 618         indicate that this renderer supports in-place editing.
 619     */
 620     virtual bool HasEditorCtrl();
 621
 622     /**
 623         Overrride this to react to a left click.
 624     */
 625     virtual bool LeftClick(wxPoint cursor, wxRect cell,
 626                            wxDataViewModel* model,
 627                            unsigned int col,
 628                            unsigned int row);
 629
 630     /**
 631         Override this to render the cell. Before this is called,
 632         wxDataViewRenderer::SetValue was called
 633         so that this instance knows what to render.
 634     */
 635     virtual bool Render(wxRect cell, wxDC* dc, int state);
 636
 637     /**
 638         This method should be called from within Render()
 639         whenever you need to render simple text. This will ensure that the
 640         correct colour, font and vertical alignment will be chosen so the
 641         text will look the same as text drawn by native renderers.
 642     */
 643     bool RenderText(const wxString& text, int xoffset, wxRect cell,
 644                     wxDC* dc, int state);
 645
 646     /**
 647         Overrride this to react to a right click.
 648     */
 649     virtual bool RightClick(wxPoint cursor, wxRect cell,
 650                             wxDataViewModel* model,
 651                             unsigned int col,
 652                             unsigned int row);
 653
 654     /**
 655         Overrride this to start a drag operation.
 656     */
 657     virtual bool StartDrag(wxPoint cursor, wxRect cell,
 658                            wxDataViewModel* model,
 659                            unsigned int col,
 660                            unsigned int row);
 661 };
 662
 663
 664
 665 /**
 666     @class wxDataViewBitmapRenderer
 667     @wxheader{dataview.h}
 668
 669     wxDataViewBitmapRenderer
 670
 671     @library{wxadv}
 672     @category{FIXME}
 673 */
 674 class wxDataViewBitmapRenderer : public wxDataViewRenderer
 675 {
 676 public:
 677     /**
 678
 679     */
 680     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
 681                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
 682 };
 683
 684
 685
 686 /**
 687     @class wxDataViewItemAttr
 688     @wxheader{dataview.h}
 689
 690     This class is used to indicate to a wxDataViewCtrl
 691     that a certain Item() has extra font attributes
 692     for its renderer. For this, it is required to override
 693     wxDataViewModel::GetAttr.
 694
 695     Attributes are currently only supported by
 696     wxDataViewTextRendererText().
 697
 698     @library{wxadv}
 699     @category{FIXME}
 700 */
 701 class wxDataViewItemAttr
 702 {
 703 public:
 704     /**
 705         Constructor.
 706     */
 707     wxDataViewItemAttr();
 708
 709     /**
 710         Call this to indicate that the item shall be displayed in bold text.
 711     */
 712     void SetBold(bool set);
 713
 714     /**
 715         Call this to indicate that the item shall be displayed with
 716         that colour.
 717     */
 718     void SetColour(const wxColour& colour);
 719
 720     /**
 721         Call this to indicate that the item shall be displayed in italic text.
 722     */
 723     void SetItalic(bool set);
 724 };
 725
 726
 727
 728 /**
 729     @class wxDataViewItem
 730     @wxheader{dataview.h}
 731
 732     wxDataViewItem is a small opaque class that represents an
 733     item in a wxDataViewCtrl in a
 734     persistent way, i.e. indepent of the position of the
 735     item in the control or changes to its contents. It must
 736     hold a unique ID of type @e void* in its only field
 737     and can be converted to a from it.
 738
 739     If the ID is @e @NULL the wxDataViewItem is invalid and
 740     wxDataViewItem::IsOk will return @e @false
 741     which used in many places in the API of wxDataViewCtrl
 742     to indicate that e.g. no item was found. An ID of @NULL
 743     is also used to indicate the invisible root. Examples
 744     for this are
 745     wxDataViewModel::GetParent and
 746     wxDataViewModel::GetChildren.
 747
 748     @library{wxadv}
 749     @category{FIXME}
 750 */
 751 class wxDataViewItem
 752 {
 753 public:
 754     //@{
 755     /**
 756
 757     */
 758     wxDataViewItem(void* id = NULL);
 759     wxDataViewItem(const wxDataViewItem& item);
 760     //@}
 761
 762     /**
 763         Returns the ID.
 764     */
 765     void* GetID() const;
 766
 767     /**
 768         Returns @true if the ID is not @e @NULL.
 769     */
 770     bool IsOk() const;
 771 };
 772
 773
 774
 775 /**
 776     @class wxDataViewCtrl
 777     @wxheader{dataview.h}
 778
 779     wxDataViewCtrl is a control to display data either
 780     in a tree like fashion or in a tabular form or both.
 781     If you only need to display a simple tree structure
 782     with an API more like the older wxTreeCtrl class,
 783     then the specialized wxDataViewTreeCtrl
 784     can be used.
 785
 786     A wxDataViewItem is used
 787     to represent a (visible) item in the control.
 788
 789     Unlike wxListCtrl wxDataViewCtrl doesn't
 790     get its data from the user through virtual functions or by
 791     setting it directly. Instead you need to write your own
 792     wxDataViewModel and associate
 793     it with this control. Then you need to add a number of
 794     wxDataViewColumn to this control to
 795     define what each column shall display. Each wxDataViewColumn
 796     in turn owns 1 instance of a
 797     wxDataViewRenderer to render its
 798     cells. A number of standard renderers for rendering text, dates,
 799     images, toggle, a progress bar etc. are provided. Additionally,
 800     the user can write custom renderes deriving from
 801     wxDataViewCustomRenderer
 802     for displaying anything.
 803
 804     All data transfer from the control to the model and the user
 805     code is done through wxVariant which can
 806     be extended to support more data formats as necessary.
 807     Accordingly, all type information uses the strings returned
 808     from wxVariant::GetType.
 809
 810     @beginStyleTable
 811     @style{wxDV_SINGLE}:
 812            Single selection mode. This is the default.
 813     @style{wxDV_MULTIPLE}:
 814            Multiple selection mode.
 815     @style{wxDV_ROW_LINES}:
 816            Use alternating colours for rows if supported by platform and theme.
 817     @style{wxDV_HORIZ_RULES}:
 818            Display fine rules between row if supported.
 819     @style{wxDV_VERT_RULES}:
 820            Display fine rules between columns is supported.
 821     @endStyleTable
 822
 823     @library{wxadv}
 824     @category{ctrl}
 825     @appearance{dataviewctrl.png}
 826 */
 827 class wxDataViewCtrl : public wxControl
 828 {
 829 public:
 830     //@{
 831     /**
 832         Constructor. Calls Create().
 833     */
 834     wxDataViewCtrl();
 835     wxDataViewCtrl(wxWindow* parent, wxWindowID id,
 836                    const wxPoint& pos = wxDefaultPosition,
 837                    const wxSize& size = wxDefaultSize,
 838                    long style = 0,
 839                    const wxValidator& validator = wxDefaultValidator);
 840     //@}
 841
 842     /**
 843         Destructor.
 844     */
 845     ~wxDataViewCtrl();
 846
 847     //@{
 848     /**
 849         Appends a column for rendering a bitmap. Returns the wxDataViewColumn
 850         created in the function or @NULL on failure.
 851     */
 852     wxDataViewColumn* AppendBitmapColumn(const wxString& label,
 853                                          unsigned int model_column,
 854                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 855                                          int width = -1,
 856                                          wxAlignment align = wxALIGN_CENTER,
 857                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 858     wxDataViewColumn* AppendBitmapColumn(const wxBitmap& label,
 859                                          unsigned int model_column,
 860                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 861                                          int width = -1,
 862                                          wxAlignment align = wxALIGN_CENTER,
 863                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 864     //@}
 865
 866     /**
 867         Add a wxDataViewColumn to the control. Returns
 868         @e @true on success.
 869         Note that there is a number of short cut methods which implicitly create
 870         a wxDataViewColumn and a
 871         wxDataViewRenderer for it (see below).
 872     */
 873     virtual bool AppendColumn(wxDataViewColumn* col);
 874
 875     //@{
 876     /**
 877         Appends a column for rendering a date. Returns the wxDataViewColumn
 878         created in the function or @NULL on failure.
 879     */
 880     wxDataViewColumn* AppendDateColumn(const wxString& label,
 881                                        unsigned int model_column,
 882                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
 883                                        int width = -1,
 884                                        wxAlignment align = wxALIGN_CENTER,
 885                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 886     wxDataViewColumn* AppendDateColumn(const wxBitmap& label,
 887                                        unsigned int model_column,
 888                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
 889                                        int width = -1,
 890                                        wxAlignment align = wxALIGN_CENTER,
 891                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 892     //@}
 893
 894     //@{
 895     /**
 896         Appends a column for rendering text with an icon. Returns the wxDataViewColumn
 897         created in the function or @NULL on failure. This uses the
 898         wxDataViewIconTextRenderer.
 899     */
 900     wxDataViewColumn* AppendIconTextColumn(const wxString& label,
 901                                            unsigned int model_column,
 902                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 903                                            int width = -1,
 904                                            wxAlignment align = wxALIGN_LEFT,
 905                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 906     wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label,
 907                                            unsigned int model_column,
 908                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 909                                            int width = -1,
 910                                            wxAlignment align = wxALIGN_LEFT,
 911                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 912     //@}
 913
 914     //@{
 915     /**
 916         Appends a column for rendering a progress indicator. Returns the
 917         wxDataViewColumn
 918         created in the function or @NULL on failure.
 919     */
 920     wxDataViewColumn* AppendProgressColumn(const wxString& label,
 921                                            unsigned int model_column,
 922                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 923                                            int width = 80,
 924                                            wxAlignment align = wxALIGN_CENTER,
 925                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 926     wxDataViewColumn* AppendProgressColumn(const wxBitmap& label,
 927                                            unsigned int model_column,
 928                                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 929                                            int width = 80,
 930                                            wxAlignment align = wxALIGN_CENTER,
 931                                            int flags = wxDATAVIEW_COL_RESIZABLE);
 932     //@}
 933
 934     //@{
 935     /**
 936         Appends a column for rendering text. Returns the wxDataViewColumn
 937         created in the function or @NULL on failure.
 938     */
 939     wxDataViewColumn* AppendTextColumn(const wxString& label,
 940                                        unsigned int model_column,
 941                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 942                                        int width = -1,
 943                                        wxAlignment align = wxALIGN_LEFT,
 944                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 945     wxDataViewColumn* AppendTextColumn(const wxBitmap& label,
 946                                        unsigned int model_column,
 947                                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 948                                        int width = -1,
 949                                        wxAlignment align = wxALIGN_LEFT,
 950                                        int flags = wxDATAVIEW_COL_RESIZABLE);
 951     //@}
 952
 953     //@{
 954     /**
 955         Appends a column for rendering a toggle. Returns the wxDataViewColumn
 956         created in the function or @NULL on failure.
 957     */
 958     wxDataViewColumn* AppendToggleColumn(const wxString& label,
 959                                          unsigned int model_column,
 960                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 961                                          int width = 30,
 962                                          wxAlignment align = wxALIGN_CENTER,
 963                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 964     wxDataViewColumn* AppendToggleColumn(const wxBitmap& label,
 965                                          unsigned int model_column,
 966                                          wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
 967                                          int width = 30,
 968                                          wxAlignment align = wxALIGN_CENTER,
 969                                          int flags = wxDATAVIEW_COL_RESIZABLE);
 970     //@}
 971
 972     /**
 973         Associates a wxDataViewModel with the
 974         control. This increases the reference count of the model by 1.
 975     */
 976     virtual bool AssociateModel(wxDataViewModel* model);
 977
 978     /**
 979         Removes all columns.
 980     */
 981     virtual bool ClearColumns();
 982
 983     /**
 984         Unselects all rows.
 985     */
 986     void ClearSelection();
 987
 988     /**
 989         Collapses the item.
 990     */
 991     void Collapse(const wxDataViewItem& item);
 992
 993     /**
 994         Create the control. Useful for two step creation.
 995     */
 996     bool Create(wxWindow* parent, wxWindowID id,
 997                 const wxPoint& pos = wxDefaultPosition,
 998                 const wxSize& size = wxDefaultSize,
 999                 long style = 0,
1000                 const wxValidator& validator = wxDefaultValidator);
1001
1002     /**
1003         Deletes given column.
1004     */
1005     virtual bool DeleteColumn(const wxDataViewColumn* column);
1006
1007     /**
1008         Call this to ensure that the given item is visible.
1009     */
1010     void EnsureVisible(const wxDataViewItem& item,
1011                        const wxDataViewColumn* column = NULL);
1012
1013     /**
1014         Expands the item.
1015     */
1016     void Expand(const wxDataViewItem& item);
1017
1018     /**
1019         Returns pointer to the column. @a pos refers to the
1020         position in the control which may change after reordering
1021         columns by the user.
1022     */
1023     virtual wxDataViewColumn* GetColumn(unsigned int pos) const;
1024
1025     /**
1026         Returns the number of columns.
1027     */
1028     virtual unsigned int GetColumnCount() const;
1029
1030     /**
1031         Returns the position of the column or -1 if not found in the control.
1032     */
1033     virtual int GetColumnPosition(const wxDataViewColumn* column) const;
1034
1035     /**
1036         Returns column containing the expanders.
1037     */
1038     wxDataViewColumn* GetExpanderColumn() const;
1039
1040     /**
1041         Returns indentation.
1042     */
1043     int GetIndent() const;
1044
1045     /**
1046         Returns item rect.
1047     */
1048     wxRect GetItemRect(const wxDataViewItem& item,
1049                        const wxDataViewColumn* col = NULL) const;
1050
1051     /**
1052         Returns pointer to the data model associated with the
1053         control (if any).
1054     */
1055     virtual wxDataViewModel* GetModel() const;
1056
1057     /**
1058         Returns first selected item or an invalid item if none is selected.
1059     */
1060     wxDataViewItem GetSelection() const;
1061
1062     /**
1063         Fills @a sel with currently selected items and returns
1064         their number.
1065     */
1066     int GetSelections(wxDataViewItemArray& sel) const;
1067
1068     /**
1069         Returns the wxDataViewColumn currently responsible for sorting
1070         or @NULL if none has been selected.
1071     */
1072     virtual wxDataViewColumn* GetSortingColumn() const;
1073
1074     /**
1075         Hittest.
1076     */
1077     void HitTest(const wxPoint& point, wxDataViewItem& item,
1078                  wxDataViewColumn*& col) const;
1079
1080     /**
1081         Return @true if the item is selected.
1082     */
1083     bool IsSelected(const wxDataViewItem& item) const;
1084
1085     /**
1086         Select the given item.
1087     */
1088     void Select(const wxDataViewItem& item);
1089
1090     /**
1091         Select all items.
1092     */
1093     void SelectAll();
1094
1095     /**
1096         Set which column shall contain the tree-like expanders.
1097     */
1098     void SetExpanderColumn(wxDataViewColumn* col);
1099
1100     /**
1101         Sets the indendation.
1102     */
1103     void SetIndent(int indent);
1104
1105     /**
1106         Sets the selection to the array of wxDataViewItems.
1107     */
1108     void SetSelections(const wxDataViewItemArray& sel);
1109
1110     /**
1111         Unselect the given item.
1112     */
1113     void Unselect(const wxDataViewItem& item);
1114
1115     /**
1116         Unselect all item. This method only has effect if multiple
1117         selections are allowed.
1118     */
1119     void UnselectAll();
1120 };
1121
1122
1123
1124 /**
1125     @class wxDataViewModelNotifier
1126     @wxheader{dataview.h}
1127
1128     A wxDataViewModelNotifier instance is owned by a
1129     wxDataViewModel
1130     and mirrors its notification interface. See
1131     the documentation of that class for further
1132     information.
1133
1134     @library{wxbase}
1135     @category{FIXME}
1136 */
1137 class wxDataViewModelNotifier
1138 {
1139 public:
1140     /**
1141         Constructor.
1142     */
1143     wxDataViewModelNotifier();
1144
1145     /**
1146         Destructor.
1147     */
1148     ~wxDataViewModelNotifier();
1149
1150     /**
1151         Called by owning model.
1152     */
1153     bool Cleared();
1154
1155     /**
1156         Get owning wxDataViewModel.
1157     */
1158     wxDataViewModel* GetOwner();
1159
1160     /**
1161         Called by owning model.
1162     */
1163     bool ItemAdded(const wxDataViewItem& parent,
1164                    const wxDataViewItem& item);
1165
1166     /**
1167         Called by owning model.
1168     */
1169     bool ItemChanged(const wxDataViewItem& item);
1170
1171     /**
1172         Called by owning model.
1173     */
1174     bool ItemDeleted(const wxDataViewItem& parent,
1175                      const wxDataViewItem& item);
1176
1177     /**
1178         Called by owning model.
1179     */
1180     bool ItemsAdded(const wxDataViewItem& parent,
1181                     const wxDataViewItemArray& items);
1182
1183     /**
1184         Called by owning model.
1185     */
1186     bool ItemsChanged(const wxDataViewItemArray& items);
1187
1188     /**
1189         Called by owning model.
1190     */
1191     bool ItemsDeleted(const wxDataViewItem& parent,
1192                       const wxDataViewItemArray& items);
1193
1194     /**
1195         Called by owning model.
1196     */
1197     void Resort();
1198
1199     /**
1200         Set owner of this notifier. Used internally.
1201     */
1202     void SetOwner(wxDataViewModel* owner);
1203
1204     /**
1205         Called by owning model.
1206     */
1207     bool ValueChanged(const wxDataViewItem& item, unsigned int col);
1208 };
1209
1210
1211
1212 /**
1213     @class wxDataViewRenderer
1214     @wxheader{dataview.h}
1215
1216     This class is used by wxDataViewCtrl to
1217     render the individual cells. One instance of a renderer class is
1218     owned by wxDataViewColumn. There is
1219     a number of ready-to-use renderers provided:
1220     wxDataViewTextRenderer,
1221     wxDataViewTextRendererAttr,
1222     wxDataViewIconTextRenderer,
1223     wxDataViewToggleRenderer,
1224     wxDataViewProgressRenderer,
1225     wxDataViewBitmapRenderer,
1226     wxDataViewDateRenderer.
1227     wxDataViewSpinRenderer.
1228
1229     Additionally, the user can write own renderers by deriving from
1230     wxDataViewCustomRenderer.
1231
1232     The @e wxDataViewCellMode flag controls, what actions
1233     the cell data allows. @e wxDATAVIEW_CELL_ACTIVATABLE
1234     indicates that the user can double click the cell and
1235     something will happen (e.g. a window for editing a date
1236     will pop up). @e wxDATAVIEW_CELL_EDITABLE indicates
1237     that the user can edit the data in-place, i.e. an control
1238     will show up after a slow click on the cell. This behaviour
1239     is best known from changing the filename in most file
1240     managers etc.
1241
1242
1243     @code
1244     enum wxDataViewCellMode
1245     {
1246         wxDATAVIEW_CELL_INERT,
1247         wxDATAVIEW_CELL_ACTIVATABLE,
1248         wxDATAVIEW_CELL_EDITABLE
1249     };
1250     @endcode
1251
1252     The @e wxDataViewCellRenderState flag controls how the
1253     the renderer should display its contents in a cell:
1254
1255     @code
1256     enum wxDataViewCellRenderState
1257     {
1258         wxDATAVIEW_CELL_SELECTED    = 1,
1259         wxDATAVIEW_CELL_PRELIT      = 2,
1260         wxDATAVIEW_CELL_INSENSITIVE = 4,
1261         wxDATAVIEW_CELL_FOCUSED     = 8
1262     };
1263     @endcode
1264
1265
1266     @library{wxadv}
1267     @category{FIXME}
1268 */
1269 class wxDataViewRenderer : public wxObject
1270 {
1271 public:
1272     /**
1273         Constructor.
1274     */
1275     wxDataViewRenderer(const wxString& varianttype,
1276                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1277                        int alignment = wxALIGN_LEFT|wxALIGN_CENTRE_VERTICAL);
1278
1279     /**
1280         Returns the cell mode.
1281     */
1282     virtual wxDataViewCellMode GetMode();
1283
1284     /**
1285         Returns pointer to the owning wxDataViewColumn.
1286     */
1287     virtual wxDataViewColumn* GetOwner();
1288
1289     /**
1290         This methods retrieves the value from the renderer in order to
1291         transfer the value back to the data model. Returns @e @false
1292         on failure.
1293     */
1294     virtual bool GetValue(wxVariant& value);
1295
1296     /**
1297         Returns a string with the type of the wxVariant
1298         supported by this renderer.
1299     */
1300     virtual wxString GetVariantType();
1301
1302     /**
1303         Sets the owning wxDataViewColumn. This
1304         is usually called from within wxDataViewColumn.
1305     */
1306     virtual void SetOwner(wxDataViewColumn* owner);
1307
1308     /**
1309         Set the value of the renderer (and thus its cell) to @e value.
1310         The internal code will then render this cell with this data.
1311     */
1312     virtual bool SetValue(const wxVariant& value);
1313
1314     /**
1315         Before data is committed to the data model, it is passed to this
1316         method where it can be checked for validity. This can also be
1317         used for checking a valid range or limiting the user input in
1318         a certain aspect (e.g. max number of characters or only alphanumeric
1319         input, ASCII only etc.). Return @e @false if the value is
1320         not valid.
1321         Please note that due to implementation limitations, this validation
1322         is done after the editing control already is destroyed and the
1323         editing process finished.
1324     */
1325     virtual bool Validate(wxVariant& value);
1326 };
1327
1328
1329
1330 /**
1331     @class wxDataViewTextRenderer
1332     @wxheader{dataview.h}
1333
1334     wxDataViewTextRenderer is used for rendering text. It supports
1335     in-place editing if desired.
1336
1337     @library{wxadv}
1338     @category{FIXME}
1339 */
1340 class wxDataViewTextRenderer : public wxDataViewRenderer
1341 {
1342 public:
1343     /**
1344
1345     */
1346     wxDataViewTextRenderer(const wxString& varianttype = "string",
1347                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
1348 };
1349
1350
1351
1352 /**
1353     @class wxDataViewProgressRenderer
1354     @wxheader{dataview.h}
1355
1356     wxDataViewProgressRenderer
1357
1358     @library{wxadv}
1359     @category{FIXME}
1360 */
1361 class wxDataViewProgressRenderer : public wxDataViewRenderer
1362 {
1363 public:
1364     /**
1365
1366     */
1367     wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
1368                                const wxString& varianttype = "long",
1369                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
1370 };
1371
1372
1373
1374 /**
1375     @class wxDataViewSpinRenderer
1376     @wxheader{dataview.h}
1377
1378     This is a specialized renderer for rendering integer values. It
1379     supports modifying the values in-place by using a wxSpinCtrl.
1380     The renderer only support variants of type @e long.
1381
1382     @library{wxbase}
1383     @category{FIXME}
1384 */
1385 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
1386 {
1387 public:
1388     /**
1389         Constructor. @a min and @a max indicate the minimum und
1390         maximum values of for the wxSpinCtrl.
1391     */
1392     wxDataViewSpinRenderer(int min, int max,
1393                            wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1394                            int alignment = wxDVR_DEFAULT_ALIGNMENT);
1395 };
1396
1397
1398
1399 /**
1400     @class wxDataViewToggleRenderer
1401     @wxheader{dataview.h}
1402
1403     wxDataViewToggleRenderer
1404
1405     @library{wxadv}
1406     @category{FIXME}
1407 */
1408 class wxDataViewToggleRenderer : public wxDataViewRenderer
1409 {
1410 public:
1411     /**
1412
1413     */
1414     wxDataViewToggleRenderer(const wxString& varianttype = "bool",
1415                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
1416 };
1417
1418
1419
1420 /**
1421     @class wxDataViewTreeCtrl
1422     @wxheader{dataview.h}
1423
1424     This class is a wxDataViewCtrl which internally
1425     uses a wxDataViewTreeStore and forwards
1426     most of its API to that class. Additionally, it uses a wxImageList
1427     to store a list of icons. The main purpose of this class is to look
1428     like a wxTreeCtrl to make a transition from it
1429     to the wxDataViewCtrl class simpler.
1430
1431     @library{wxbase}
1432     @category{ctrl}
1433     @appearance{dataviewtreectrl.png}
1434 */
1435 class wxDataViewTreeCtrl : public wxDataViewCtrl
1436 {
1437 public:
1438     //@{
1439     /**
1440         Constructor. Calls Create().
1441     */
1442     wxDataViewTreeCtrl();
1443     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
1444                        const wxPoint& pos = wxDefaultPosition,
1445                        const wxSize& size = wxDefaultSize,
1446                        long style = wxDV_NO_HEADER,
1447                        const wxValidator& validator = wxDefaultValidator);
1448     //@}
1449
1450     /**
1451         Destructor. Deletes the image list if any.
1452     */
1453     ~wxDataViewTreeCtrl();
1454
1455     /**
1456
1457     */
1458     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1459                                    const wxString& text,
1460                                    int icon = -1,
1461                                    int expanded = -1,
1462                                    wxClientData* data = NULL);
1463
1464     /**
1465
1466     */
1467     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1468                               const wxString& text,
1469                               int icon = -1,
1470                               wxClientData* data = NULL);
1471
1472     /**
1473         Creates the control and a wxDataViewTreeStore as
1474         its internal model.
1475     */
1476     bool Create(wxWindow* parent, wxWindowID id,
1477                 const wxPoint& pos = wxDefaultPosition,
1478                 const wxSize& size = wxDefaultSize,
1479                 long style = wxDV_NO_HEADER,
1480                 const wxValidator& validator = wxDefaultValidator);
1481
1482     /**
1483         Calls the identical method from wxDataViewTreeStore.
1484     */
1485     void DeleteAllItems();
1486
1487     /**
1488         Calls the identical method from wxDataViewTreeStore.
1489     */
1490     void DeleteChildren(const wxDataViewItem& item);
1491
1492     /**
1493         Calls the identical method from wxDataViewTreeStore.
1494     */
1495     void DeleteItem(const wxDataViewItem& item);
1496
1497     /**
1498         Calls the identical method from wxDataViewTreeStore.
1499     */
1500     int GetChildCount(const wxDataViewItem& parent) const;
1501
1502     /**
1503         Returns the image list.
1504     */
1505     wxImageList* GetImageList();
1506
1507     /**
1508         Calls the identical method from wxDataViewTreeStore.
1509     */
1510     wxClientData* GetItemData(const wxDataViewItem& item) const;
1511
1512     /**
1513         Calls the identical method from wxDataViewTreeStore.
1514     */
1515     const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const;
1516
1517     /**
1518         Calls the identical method from wxDataViewTreeStore.
1519     */
1520     const wxIcon GetItemIcon(const wxDataViewItem& item) const;
1521
1522     /**
1523         Calls the identical method from wxDataViewTreeStore.
1524     */
1525     wxString GetItemText(const wxDataViewItem& item) const;
1526
1527     /**
1528         Calls the identical method from wxDataViewTreeStore.
1529     */
1530     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1531                                unsigned int pos) const;
1532
1533     //@{
1534     /**
1535         Returns the store.
1536     */
1537     wxDataViewTreeStore* GetStore() const;
1538     const wxDataViewTreeStore* GetStore() const;
1539     //@}
1540
1541     /**
1542         Calls the same method from wxDataViewTreeStore but uess
1543         and index position in the image list instead of a wxIcon.
1544     */
1545     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1546                                    const wxDataViewItem& previous,
1547                                    const wxString& text,
1548                                    int icon = -1,
1549                                    int expanded = -1,
1550                                    wxClientData* data = NULL);
1551
1552     /**
1553         Calls the same method from wxDataViewTreeStore but uess
1554         and index position in the image list instead of a wxIcon.
1555     */
1556     wxDataViewItem InsertItem(const wxDataViewItem& parent,
1557                               const wxDataViewItem& previous,
1558                               const wxString& text,
1559                               int icon = -1,
1560                               wxClientData* data = NULL);
1561
1562     /**
1563         Calls the same method from wxDataViewTreeStore but uess
1564         and index position in the image list instead of a wxIcon.
1565     */
1566     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1567                                     const wxString& text,
1568                                     int icon = -1,
1569                                     int expanded = -1,
1570                                     wxClientData* data = NULL);
1571
1572     /**
1573         Calls the same method from wxDataViewTreeStore but uess
1574         and index position in the image list instead of a wxIcon.
1575     */
1576     wxDataViewItem PrependItem(const wxDataViewItem& parent,
1577                                const wxString& text,
1578                                int icon = -1,
1579                                wxClientData* data = NULL);
1580
1581     /**
1582         Sets the image list.
1583     */
1584     void SetImageList(wxImageList* imagelist);
1585
1586     /**
1587         Calls the identical method from wxDataViewTreeStore.
1588     */
1589     void SetItemData(const wxDataViewItem& item, wxClientData* data);
1590
1591     /**
1592         Calls the identical method from wxDataViewTreeStore.
1593     */
1594     void SetItemExpandedIcon(const wxDataViewItem& item,
1595                              const wxIcon& icon);
1596
1597     /**
1598         Calls the identical method from wxDataViewTreeStore.
1599     */
1600     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1601
1602     /**
1603         Calls the identical method from wxDataViewTreeStore.
1604     */
1605     void SetItemText(const wxDataViewItem& item,
1606                      const wxString& text);
1607 };
1608
1609
1610
1611 /**
1612     @class wxDataViewTreeStore
1613     @wxheader{dataview.h}
1614
1615     wxDataViewTreeStore is a specialised wxDataViewModel
1616     for displaying simple trees very much like wxTreeCtrl
1617     does and it offers a similar API. This class actually stores the entire
1618     tree (therefore its name) and implements all virtual methods from the base
1619     class so it can be used directly without having to derive any class from it.
1620     This comes at the price of much reduced flexibility.
1621
1622     @library{wxadv}
1623     @category{FIXME}
1624 */
1625 class wxDataViewTreeStore : public wxDataViewModel
1626 {
1627 public:
1628     /**
1629         Constructor. Creates the invisible root node internally.
1630     */
1631     wxDataViewTreeStore();
1632
1633     /**
1634         Destructor.
1635     */
1636     ~wxDataViewTreeStore();
1637
1638     /**
1639         Append a container.
1640     */
1641     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1642                                    const wxString& text,
1643                                    const wxIcon& icon = wxNullIcon,
1644                                    const wxIcon& expanded = wxNullIcon,
1645                                    wxClientData* data = NULL);
1646
1647     /**
1648         Append an item.
1649     */
1650     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1651                               const wxString& text,
1652                               const wxIcon& icon = wxNullIcon,
1653                               wxClientData* data = NULL);
1654
1655     /**
1656         Delete all item in the model.
1657     */
1658     void DeleteAllItems();
1659
1660     /**
1661         Delete all children of the item, but not the item itself.
1662     */
1663     void DeleteChildren(const wxDataViewItem& item);
1664
1665     /**
1666         Delete this item.
1667     */
1668     void DeleteItem(const wxDataViewItem& item);
1669
1670     /**
1671         Return the number of children of item.
1672     */
1673     int GetChildCount(const wxDataViewItem& parent) const;
1674
1675     /**
1676         Returns the client data asoociated with the item.
1677     */
1678     wxClientData* GetItemData(const wxDataViewItem& item) const;
1679
1680     /**
1681         Returns the icon to display in expanded containers.
1682     */
1683     const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const;
1684
1685     /**
1686         Returns the icon of the item.
1687     */
1688     const wxIcon GetItemIcon(const wxDataViewItem& item) const;
1689
1690     /**
1691         Returns the text of the item.
1692     */
1693     wxString GetItemText(const wxDataViewItem& item) const;
1694
1695     /**
1696         Returns the nth child item of item.
1697     */
1698     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1699                                unsigned int pos) const;
1700
1701     /**
1702         Inserts a container after @e previous.
1703     */
1704     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1705                                    const wxDataViewItem& previous,
1706                                    const wxString& text,
1707                                    const wxIcon& icon = wxNullIcon,
1708                                    const wxIcon& expanded = wxNullIcon,
1709                                    wxClientData* data = NULL);
1710
1711     /**
1712         Inserts an item after @e previous.
1713     */
1714     wxDataViewItem InsertItem(const wxDataViewItem& parent,
1715                               const wxDataViewItem& previous,
1716                               const wxString& text,
1717                               const wxIcon& icon = wxNullIcon,
1718                               wxClientData* data = NULL);
1719
1720     /**
1721         Inserts a container before the first child item or @e parent.
1722     */
1723     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1724                                     const wxString& text,
1725                                     const wxIcon& icon = wxNullIcon,
1726                                     const wxIcon& expanded = wxNullIcon,
1727                                     wxClientData* data = NULL);
1728
1729     /**
1730         Inserts an item before the first child item or @e parent.
1731     */
1732     wxDataViewItem PrependItem(const wxDataViewItem& parent,
1733                                const wxString& text,
1734                                const wxIcon& icon = wxNullIcon,
1735                                wxClientData* data = NULL);
1736
1737     /**
1738         Sets the client data associated with the item.
1739     */
1740     void SetItemData(const wxDataViewItem& item, wxClientData* data);
1741
1742     /**
1743         Sets the expanded icon for the item.
1744     */
1745     void SetItemExpandedIcon(const wxDataViewItem& item,
1746                              const wxIcon& icon);
1747
1748     /**
1749         Sets the icon for the item.
1750     */
1751     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1752 };
1753
1754
1755
1756 /**
1757     @class wxDataViewDateRenderer
1758     @wxheader{dataview.h}
1759
1760     wxDataViewDateRenderer
1761
1762     @library{wxadv}
1763     @category{FIXME}
1764 */
1765 class wxDataViewDateRenderer : public wxDataViewRenderer
1766 {
1767 public:
1768     /**
1769
1770     */
1771     wxDataViewDateRenderer(const wxString& varianttype = "datetime",
1772                            wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE);
1773 };
1774
1775
1776
1777 /**
1778     @class wxDataViewTextRendererAttr
1779     @wxheader{dataview.h}
1780
1781     The same as wxDataViewTextRenderer but with
1782     support for font attributes. Font attributes are currently only supported
1783     under GTK+ and MSW.
1784
1785     See also wxDataViewModel::GetAttr and
1786     wxDataViewItemAttr.
1787
1788     @library{wxadv}
1789     @category{FIXME}
1790 */
1791 class wxDataViewTextRendererAttr : public wxDataViewTextRenderer
1792 {
1793 public:
1794     /**
1795
1796     */
1797     wxDataViewTextRendererAttr(const wxString& varianttype = "string",
1798                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1799                                int align = wxDVR_DEFAULT_ALIGNMENT);
1800 };
1801
1802
1803
1804 /**
1805     @class wxDataViewColumn
1806     @wxheader{dataview.h}
1807
1808     This class represents a column in a wxDataViewCtrl.
1809     One wxDataViewColumn is bound to one column in the data model,
1810     to which the wxDataViewCtrl has been associated.
1811
1812     An instance of wxDataViewRenderer is used by
1813     this class to render its data.
1814
1815     @library{wxadv}
1816     @category{FIXME}
1817 */
1818 class wxDataViewColumn : public wxObject
1819 {
1820 public:
1821     //@{
1822     /**
1823         Constructors.
1824     */
1825     wxDataViewColumn(const wxString& title,
1826                      wxDataViewRenderer* renderer,
1827                      unsigned int model_column,
1828                      int width = wxDVC_DEFAULT_WIDTH,
1829                      wxAlignment align = wxALIGN_CENTRE,
1830                      int flags = wxDATAVIEW_COL_RESIZABLE);
1831     wxDataViewColumn(const wxBitmap& bitmap,
1832                      wxDataViewRenderer* renderer,
1833                      unsigned int model_column,
1834                      int width = wxDVC_DEFAULT_WIDTH,
1835                      wxAlignment align = wxALIGN_CENTRE,
1836                      int flags = wxDATAVIEW_COL_RESIZABLE);
1837     //@}
1838
1839     /**
1840         Destructor.
1841     */
1842     ~wxDataViewColumn();
1843
1844     /**
1845         Returns the bitmap in the header of the column, if any.
1846     */
1847     const wxBitmap GetBitmap();
1848
1849     /**
1850         Returns the index of the column of the model, which this
1851         wxDataViewColumn is displaying.
1852     */
1853     unsigned int GetModelColumn();
1854
1855     /**
1856         Returns the owning wxDataViewCtrl.
1857     */
1858     wxDataViewCtrl* GetOwner();
1859
1860     /**
1861         Returns the renderer of this wxDataViewColumn.
1862         See also wxDataViewRenderer.
1863     */
1864     wxDataViewRenderer* GetRenderer();
1865
1866     /**
1867         Returns @true if the column is reorderable.
1868     */
1869     bool GetReorderable();
1870
1871     /**
1872         Returns @true if the column is sortable.
1873         See SetSortable()
1874     */
1875     bool GetSortable();
1876
1877     /**
1878         Returns the width of the column.
1879     */
1880     int GetWidth();
1881
1882     /**
1883         Returns @true, if the sort order is ascending.
1884         See also SetSortOrder()
1885     */
1886     bool IsSortOrderAscending();
1887
1888     /**
1889         Set the alignment of the column header.
1890     */
1891     void SetAlignment(wxAlignment align);
1892
1893     /**
1894         Set the bitmap of the column header.
1895     */
1896     void SetBitmap(const wxBitmap& bitmap);
1897
1898     /**
1899         Indicate wether the column can be reordered by the
1900         user using the mouse. This is typically implemented
1901         visually by dragging the header button around.
1902     */
1903     void SetReorderable(bool reorderable);
1904
1905     /**
1906         Indicate the sort order if the implementation of the
1907         wxDataViewCtrl supports it, most commonly by showing
1908         a little arrow.
1909     */
1910     void SetSortOrder(bool ascending);
1911
1912     /**
1913         Indicate that the column is sortable. This does
1914         not show any sorting indicate yet, but it does
1915         make the column header clickable. Call
1916         SetSortOrder()
1917         afterwards to actually make the sort indicator appear.
1918         If @a sortable is @false, the column header is
1919         no longer clickable and the sort indicator (little
1920         arrow) will disappear.
1921     */
1922     void SetSortable(bool sortable);
1923
1924     /**
1925         Set the title of the column header to @e title.
1926     */
1927     void SetTitle(const wxString& title);
1928 };
1929