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