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