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