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