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 alignment.
1278     */
1279     virtual int GetAlignment() const;
1280
1281     /**
1282         Returns the cell mode.
1283     */
1284     virtual wxDataViewCellMode GetMode();
1285
1286     /**
1287         Returns pointer to the owning wxDataViewColumn.
1288     */
1289     virtual wxDataViewColumn* GetOwner();
1290
1291     /**
1292         This methods retrieves the value from the renderer in order to
1293         transfer the value back to the data model. Returns @e @false
1294         on failure.
1295     */
1296     virtual bool GetValue(wxVariant& value);
1297
1298     /**
1299         Returns a string with the type of the wxVariant
1300         supported by this renderer.
1301     */
1302     virtual wxString GetVariantType();
1303
1304     /**
1305         Sets the alignment.
1306     */
1307     virtual void SetAlignment( int align );
1308     /**
1309         Sets the owning wxDataViewColumn. This
1310         is usually called from within wxDataViewColumn.
1311     */
1312     virtual void SetOwner(wxDataViewColumn* owner);
1313
1314     /**
1315         Set the value of the renderer (and thus its cell) to @e value.
1316         The internal code will then render this cell with this data.
1317     */
1318     virtual bool SetValue(const wxVariant& value);
1319
1320     /**
1321         Before data is committed to the data model, it is passed to this
1322         method where it can be checked for validity. This can also be
1323         used for checking a valid range or limiting the user input in
1324         a certain aspect (e.g. max number of characters or only alphanumeric
1325         input, ASCII only etc.). Return @e @false if the value is
1326         not valid.
1327         Please note that due to implementation limitations, this validation
1328         is done after the editing control already is destroyed and the
1329         editing process finished.
1330     */
1331     virtual bool Validate(wxVariant& value);
1332 };
1333
1334
1335
1336 /**
1337     @class wxDataViewTextRenderer
1338     @wxheader{dataview.h}
1339
1340     wxDataViewTextRenderer is used for rendering text. It supports
1341     in-place editing if desired.
1342
1343     @library{wxadv}
1344     @category{FIXME}
1345 */
1346 class wxDataViewTextRenderer : public wxDataViewRenderer
1347 {
1348 public:
1349     /**
1350
1351     */
1352     wxDataViewTextRenderer(const wxString& varianttype = "string",
1353                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
1354 };
1355
1356
1357
1358 /**
1359     @class wxDataViewProgressRenderer
1360     @wxheader{dataview.h}
1361
1362     wxDataViewProgressRenderer
1363
1364     @library{wxadv}
1365     @category{FIXME}
1366 */
1367 class wxDataViewProgressRenderer : public wxDataViewRenderer
1368 {
1369 public:
1370     /**
1371
1372     */
1373     wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
1374                                const wxString& varianttype = "long",
1375                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
1376 };
1377
1378
1379
1380 /**
1381     @class wxDataViewSpinRenderer
1382     @wxheader{dataview.h}
1383
1384     This is a specialized renderer for rendering integer values. It
1385     supports modifying the values in-place by using a wxSpinCtrl.
1386     The renderer only support variants of type @e long.
1387
1388     @library{wxbase}
1389     @category{FIXME}
1390 */
1391 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
1392 {
1393 public:
1394     /**
1395         Constructor. @a min and @a max indicate the minimum und
1396         maximum values of for the wxSpinCtrl.
1397     */
1398     wxDataViewSpinRenderer(int min, int max,
1399                            wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1400                            int alignment = wxDVR_DEFAULT_ALIGNMENT);
1401 };
1402
1403
1404
1405 /**
1406     @class wxDataViewToggleRenderer
1407     @wxheader{dataview.h}
1408
1409     wxDataViewToggleRenderer
1410
1411     @library{wxadv}
1412     @category{FIXME}
1413 */
1414 class wxDataViewToggleRenderer : public wxDataViewRenderer
1415 {
1416 public:
1417     /**
1418
1419     */
1420     wxDataViewToggleRenderer(const wxString& varianttype = "bool",
1421                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT);
1422 };
1423
1424
1425
1426 /**
1427     @class wxDataViewTreeCtrl
1428     @wxheader{dataview.h}
1429
1430     This class is a wxDataViewCtrl which internally
1431     uses a wxDataViewTreeStore and forwards
1432     most of its API to that class. Additionally, it uses a wxImageList
1433     to store a list of icons. The main purpose of this class is to look
1434     like a wxTreeCtrl to make a transition from it
1435     to the wxDataViewCtrl class simpler.
1436
1437     @library{wxbase}
1438     @category{ctrl}
1439     @appearance{dataviewtreectrl.png}
1440 */
1441 class wxDataViewTreeCtrl : public wxDataViewCtrl
1442 {
1443 public:
1444     //@{
1445     /**
1446         Constructor. Calls Create().
1447     */
1448     wxDataViewTreeCtrl();
1449     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
1450                        const wxPoint& pos = wxDefaultPosition,
1451                        const wxSize& size = wxDefaultSize,
1452                        long style = wxDV_NO_HEADER,
1453                        const wxValidator& validator = wxDefaultValidator);
1454     //@}
1455
1456     /**
1457         Destructor. Deletes the image list if any.
1458     */
1459     ~wxDataViewTreeCtrl();
1460
1461     /**
1462
1463     */
1464     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1465                                    const wxString& text,
1466                                    int icon = -1,
1467                                    int expanded = -1,
1468                                    wxClientData* data = NULL);
1469
1470     /**
1471
1472     */
1473     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1474                               const wxString& text,
1475                               int icon = -1,
1476                               wxClientData* data = NULL);
1477
1478     /**
1479         Creates the control and a wxDataViewTreeStore as
1480         its internal model.
1481     */
1482     bool Create(wxWindow* parent, wxWindowID id,
1483                 const wxPoint& pos = wxDefaultPosition,
1484                 const wxSize& size = wxDefaultSize,
1485                 long style = wxDV_NO_HEADER,
1486                 const wxValidator& validator = wxDefaultValidator);
1487
1488     /**
1489         Calls the identical method from wxDataViewTreeStore.
1490     */
1491     void DeleteAllItems();
1492
1493     /**
1494         Calls the identical method from wxDataViewTreeStore.
1495     */
1496     void DeleteChildren(const wxDataViewItem& item);
1497
1498     /**
1499         Calls the identical method from wxDataViewTreeStore.
1500     */
1501     void DeleteItem(const wxDataViewItem& item);
1502
1503     /**
1504         Calls the identical method from wxDataViewTreeStore.
1505     */
1506     int GetChildCount(const wxDataViewItem& parent) const;
1507
1508     /**
1509         Returns the image list.
1510     */
1511     wxImageList* GetImageList();
1512
1513     /**
1514         Calls the identical method from wxDataViewTreeStore.
1515     */
1516     wxClientData* GetItemData(const wxDataViewItem& item) const;
1517
1518     /**
1519         Calls the identical method from wxDataViewTreeStore.
1520     */
1521     const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const;
1522
1523     /**
1524         Calls the identical method from wxDataViewTreeStore.
1525     */
1526     const wxIcon GetItemIcon(const wxDataViewItem& item) const;
1527
1528     /**
1529         Calls the identical method from wxDataViewTreeStore.
1530     */
1531     wxString GetItemText(const wxDataViewItem& item) const;
1532
1533     /**
1534         Calls the identical method from wxDataViewTreeStore.
1535     */
1536     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1537                                unsigned int pos) const;
1538
1539     //@{
1540     /**
1541         Returns the store.
1542     */
1543     wxDataViewTreeStore* GetStore() const;
1544     const wxDataViewTreeStore* GetStore() const;
1545     //@}
1546
1547     /**
1548         Calls the same method from wxDataViewTreeStore but uess
1549         and index position in the image list instead of a wxIcon.
1550     */
1551     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1552                                    const wxDataViewItem& previous,
1553                                    const wxString& text,
1554                                    int icon = -1,
1555                                    int expanded = -1,
1556                                    wxClientData* data = NULL);
1557
1558     /**
1559         Calls the same method from wxDataViewTreeStore but uess
1560         and index position in the image list instead of a wxIcon.
1561     */
1562     wxDataViewItem InsertItem(const wxDataViewItem& parent,
1563                               const wxDataViewItem& previous,
1564                               const wxString& text,
1565                               int icon = -1,
1566                               wxClientData* data = NULL);
1567
1568     /**
1569         Calls the same method from wxDataViewTreeStore but uess
1570         and index position in the image list instead of a wxIcon.
1571     */
1572     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1573                                     const wxString& text,
1574                                     int icon = -1,
1575                                     int expanded = -1,
1576                                     wxClientData* data = NULL);
1577
1578     /**
1579         Calls the same method from wxDataViewTreeStore but uess
1580         and index position in the image list instead of a wxIcon.
1581     */
1582     wxDataViewItem PrependItem(const wxDataViewItem& parent,
1583                                const wxString& text,
1584                                int icon = -1,
1585                                wxClientData* data = NULL);
1586
1587     /**
1588         Sets the image list.
1589     */
1590     void SetImageList(wxImageList* imagelist);
1591
1592     /**
1593         Calls the identical method from wxDataViewTreeStore.
1594     */
1595     void SetItemData(const wxDataViewItem& item, wxClientData* data);
1596
1597     /**
1598         Calls the identical method from wxDataViewTreeStore.
1599     */
1600     void SetItemExpandedIcon(const wxDataViewItem& item,
1601                              const wxIcon& icon);
1602
1603     /**
1604         Calls the identical method from wxDataViewTreeStore.
1605     */
1606     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1607
1608     /**
1609         Calls the identical method from wxDataViewTreeStore.
1610     */
1611     void SetItemText(const wxDataViewItem& item,
1612                      const wxString& text);
1613 };
1614
1615
1616
1617 /**
1618     @class wxDataViewTreeStore
1619     @wxheader{dataview.h}
1620
1621     wxDataViewTreeStore is a specialised wxDataViewModel
1622     for displaying simple trees very much like wxTreeCtrl
1623     does and it offers a similar API. This class actually stores the entire
1624     tree (therefore its name) and implements all virtual methods from the base
1625     class so it can be used directly without having to derive any class from it.
1626     This comes at the price of much reduced flexibility.
1627
1628     @library{wxadv}
1629     @category{FIXME}
1630 */
1631 class wxDataViewTreeStore : public wxDataViewModel
1632 {
1633 public:
1634     /**
1635         Constructor. Creates the invisible root node internally.
1636     */
1637     wxDataViewTreeStore();
1638
1639     /**
1640         Destructor.
1641     */
1642     ~wxDataViewTreeStore();
1643
1644     /**
1645         Append a container.
1646     */
1647     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1648                                    const wxString& text,
1649                                    const wxIcon& icon = wxNullIcon,
1650                                    const wxIcon& expanded = wxNullIcon,
1651                                    wxClientData* data = NULL);
1652
1653     /**
1654         Append an item.
1655     */
1656     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1657                               const wxString& text,
1658                               const wxIcon& icon = wxNullIcon,
1659                               wxClientData* data = NULL);
1660
1661     /**
1662         Delete all item in the model.
1663     */
1664     void DeleteAllItems();
1665
1666     /**
1667         Delete all children of the item, but not the item itself.
1668     */
1669     void DeleteChildren(const wxDataViewItem& item);
1670
1671     /**
1672         Delete this item.
1673     */
1674     void DeleteItem(const wxDataViewItem& item);
1675
1676     /**
1677         Return the number of children of item.
1678     */
1679     int GetChildCount(const wxDataViewItem& parent) const;
1680
1681     /**
1682         Returns the client data asoociated with the item.
1683     */
1684     wxClientData* GetItemData(const wxDataViewItem& item) const;
1685
1686     /**
1687         Returns the icon to display in expanded containers.
1688     */
1689     const wxIcon GetItemExpandedIcon(const wxDataViewItem& item) const;
1690
1691     /**
1692         Returns the icon of the item.
1693     */
1694     const wxIcon GetItemIcon(const wxDataViewItem& item) const;
1695
1696     /**
1697         Returns the text of the item.
1698     */
1699     wxString GetItemText(const wxDataViewItem& item) const;
1700
1701     /**
1702         Returns the nth child item of item.
1703     */
1704     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1705                                unsigned int pos) const;
1706
1707     /**
1708         Inserts a container after @e previous.
1709     */
1710     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1711                                    const wxDataViewItem& previous,
1712                                    const wxString& text,
1713                                    const wxIcon& icon = wxNullIcon,
1714                                    const wxIcon& expanded = wxNullIcon,
1715                                    wxClientData* data = NULL);
1716
1717     /**
1718         Inserts an item after @e previous.
1719     */
1720     wxDataViewItem InsertItem(const wxDataViewItem& parent,
1721                               const wxDataViewItem& previous,
1722                               const wxString& text,
1723                               const wxIcon& icon = wxNullIcon,
1724                               wxClientData* data = NULL);
1725
1726     /**
1727         Inserts a container before the first child item or @e parent.
1728     */
1729     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1730                                     const wxString& text,
1731                                     const wxIcon& icon = wxNullIcon,
1732                                     const wxIcon& expanded = wxNullIcon,
1733                                     wxClientData* data = NULL);
1734
1735     /**
1736         Inserts an item before the first child item or @e parent.
1737     */
1738     wxDataViewItem PrependItem(const wxDataViewItem& parent,
1739                                const wxString& text,
1740                                const wxIcon& icon = wxNullIcon,
1741                                wxClientData* data = NULL);
1742
1743     /**
1744         Sets the client data associated with the item.
1745     */
1746     void SetItemData(const wxDataViewItem& item, wxClientData* data);
1747
1748     /**
1749         Sets the expanded icon for the item.
1750     */
1751     void SetItemExpandedIcon(const wxDataViewItem& item,
1752                              const wxIcon& icon);
1753
1754     /**
1755         Sets the icon for the item.
1756     */
1757     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1758 };
1759
1760
1761
1762 /**
1763     @class wxDataViewDateRenderer
1764     @wxheader{dataview.h}
1765
1766     wxDataViewDateRenderer
1767
1768     @library{wxadv}
1769     @category{FIXME}
1770 */
1771 class wxDataViewDateRenderer : public wxDataViewRenderer
1772 {
1773 public:
1774     /**
1775
1776     */
1777     wxDataViewDateRenderer(const wxString& varianttype = "datetime",
1778                            wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE);
1779 };
1780
1781
1782
1783 /**
1784     @class wxDataViewTextRendererAttr
1785     @wxheader{dataview.h}
1786
1787     The same as wxDataViewTextRenderer but with
1788     support for font attributes. Font attributes are currently only supported
1789     under GTK+ and MSW.
1790
1791     See also wxDataViewModel::GetAttr and
1792     wxDataViewItemAttr.
1793
1794     @library{wxadv}
1795     @category{FIXME}
1796 */
1797 class wxDataViewTextRendererAttr : public wxDataViewTextRenderer
1798 {
1799 public:
1800     /**
1801
1802     */
1803     wxDataViewTextRendererAttr(const wxString& varianttype = "string",
1804                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1805                                int align = wxDVR_DEFAULT_ALIGNMENT);
1806 };
1807
1808
1809
1810 /**
1811     @class wxDataViewColumn
1812     @wxheader{dataview.h}
1813
1814     This class represents a column in a wxDataViewCtrl.
1815     One wxDataViewColumn is bound to one column in the data model,
1816     to which the wxDataViewCtrl has been associated.
1817
1818     An instance of wxDataViewRenderer is used by
1819     this class to render its data.
1820
1821     @library{wxadv}
1822     @category{FIXME}
1823 */
1824 class wxDataViewColumn : public wxObject
1825 {
1826 public:
1827     //@{
1828     /**
1829         Constructors.
1830     */
1831     wxDataViewColumn(const wxString& title,
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     wxDataViewColumn(const wxBitmap& bitmap,
1838                      wxDataViewRenderer* renderer,
1839                      unsigned int model_column,
1840                      int width = wxDVC_DEFAULT_WIDTH,
1841                      wxAlignment align = wxALIGN_CENTRE,
1842                      int flags = wxDATAVIEW_COL_RESIZABLE);
1843     //@}
1844
1845     /**
1846         Destructor.
1847     */
1848     ~wxDataViewColumn();
1849
1850     /**
1851         Returns the bitmap in the header of the column, if any.
1852     */
1853     const wxBitmap GetBitmap();
1854
1855     /**
1856         Returns the index of the column of the model, which this
1857         wxDataViewColumn is displaying.
1858     */
1859     unsigned int GetModelColumn();
1860
1861     /**
1862         Returns the owning wxDataViewCtrl.
1863     */
1864     wxDataViewCtrl* GetOwner();
1865
1866     /**
1867         Returns the renderer of this wxDataViewColumn.
1868         See also wxDataViewRenderer.
1869     */
1870     wxDataViewRenderer* GetRenderer();
1871
1872     /**
1873         Returns @true if the column is reorderable.
1874     */
1875     bool GetReorderable();
1876
1877     /**
1878         Returns @true if the column is sortable.
1879         See SetSortable()
1880     */
1881     bool GetSortable();
1882
1883     /**
1884         Returns the width of the column.
1885     */
1886     int GetWidth();
1887
1888     /**
1889         Returns @true, if the sort order is ascending.
1890         See also SetSortOrder()
1891     */
1892     bool IsSortOrderAscending();
1893
1894     /**
1895         Set the alignment of the column header.
1896     */
1897     void SetAlignment(wxAlignment align);
1898
1899     /**
1900         Set the bitmap of the column header.
1901     */
1902     void SetBitmap(const wxBitmap& bitmap);
1903
1904     /**
1905         Indicate wether the column can be reordered by the
1906         user using the mouse. This is typically implemented
1907         visually by dragging the header button around.
1908     */
1909     void SetReorderable(bool reorderable);
1910
1911     /**
1912         Indicate the sort order if the implementation of the
1913         wxDataViewCtrl supports it, most commonly by showing
1914         a little arrow.
1915     */
1916     void SetSortOrder(bool ascending);
1917
1918     /**
1919         Indicate that the column is sortable. This does
1920         not show any sorting indicate yet, but it does
1921         make the column header clickable. Call
1922         SetSortOrder()
1923         afterwards to actually make the sort indicator appear.
1924         If @a sortable is @false, the column header is
1925         no longer clickable and the sort indicator (little
1926         arrow) will disappear.
1927     */
1928     void SetSortable(bool sortable);
1929
1930     /**
1931         Set the title of the column header to @e title.
1932     */
1933     void SetTitle(const wxString& title);
1934 };
1935