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         Unselects all rows.
 862     */
 863     void ClearSelection();
 864
 865     /**
 866         Collapses the item.
 867     */
 868     virtual void Collapse(const wxDataViewItem& item);
 869
 870     /**
 871         Create the control. Useful for two step creation.
 872     */
 873     bool Create(wxWindow* parent, wxWindowID id,
 874                 const wxPoint& pos = wxDefaultPosition,
 875                 const wxSize& size = wxDefaultSize,
 876                 long style = 0,
 877                 const wxValidator& validator = wxDefaultValidator);
 878
 879     /**
 880         Deletes given column.
 881     */
 882     virtual bool DeleteColumn(wxDataViewColumn* column);
 883
 884     /**
 885         Call this to ensure that the given item is visible.
 886     */
 887     virtual void EnsureVisible(const wxDataViewItem& item,
 888                                const wxDataViewColumn* column = NULL);
 889
 890     /**
 891         Expands the item.
 892     */
 893     virtual void Expand(const wxDataViewItem& item);
 894
 895     /**
 896         Returns pointer to the column. @a pos refers to the position in the
 897         control which may change after reordering columns by the user.
 898     */
 899     virtual wxDataViewColumn* GetColumn(unsigned int pos) const;
 900
 901     /**
 902         Returns the number of columns.
 903     */
 904     virtual unsigned int GetColumnCount() const;
 905
 906     /**
 907         Returns the position of the column or -1 if not found in the control.
 908     */
 909     virtual int GetColumnPosition(const wxDataViewColumn* column) const;
 910
 911     /**
 912         Returns column containing the expanders.
 913     */
 914     wxDataViewColumn* GetExpanderColumn() const;
 915
 916     /**
 917         Returns indentation.
 918     */
 919     int GetIndent() const;
 920
 921     /**
 922         Returns item rect.
 923     */
 924     virtual wxRect GetItemRect(const wxDataViewItem& item,
 925                                const wxDataViewColumn* col = NULL) const;
 926
 927     /**
 928         Returns pointer to the data model associated with the control (if any).
 929     */
 930     wxDataViewModel* GetModel();
 931
 932     /**
 933         Returns first selected item or an invalid item if none is selected.
 934     */
 935     virtual wxDataViewItem GetSelection() const;
 936
 937     /**
 938         Fills @a sel with currently selected items and returns their number.
 939     */
 940     virtual int GetSelections(wxDataViewItemArray& sel) const;
 941
 942     /**
 943         Returns the wxDataViewColumn currently responsible for sorting
 944         or @NULL if none has been selected.
 945     */
 946     virtual wxDataViewColumn* GetSortingColumn() const;
 947
 948     /**
 949         Hittest.
 950     */
 951     virtual void HitTest(const wxPoint& point, wxDataViewItem& item,
 952                          wxDataViewColumn*& col) const;
 953
 954     /**
 955         Return @true if the item is selected.
 956     */
 957     virtual bool IsSelected(const wxDataViewItem& item) const;
 958
 959     /**
 960         Select the given item.
 961     */
 962     virtual void Select(const wxDataViewItem& item);
 963
 964     /**
 965         Select all items.
 966     */
 967     virtual void SelectAll();
 968
 969     /**
 970         Set which column shall contain the tree-like expanders.
 971     */
 972     void SetExpanderColumn(wxDataViewColumn* col);
 973
 974     /**
 975         Sets the indendation.
 976     */
 977     void SetIndent(int indent);
 978
 979     /**
 980         Sets the selection to the array of wxDataViewItems.
 981     */
 982     virtual void SetSelections(const wxDataViewItemArray& sel);
 983
 984     /**
 985         Unselect the given item.
 986     */
 987     virtual void Unselect(const wxDataViewItem& item);
 988
 989     /**
 990         Unselect all item.
 991         This method only has effect if multiple selections are allowed.
 992     */
 993     virtual void UnselectAll();
 994 };
 995
 996
 997
 998 /**
 999     @class wxDataViewModelNotifier
1000
1001     A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors
1002     its notification interface.
1003     See the documentation of that class for further information.
1004
1005     @library{wxadv}
1006     @category{dvc}
1007 */
1008 class wxDataViewModelNotifier
1009 {
1010 public:
1011     /**
1012         Constructor.
1013     */
1014     wxDataViewModelNotifier();
1015
1016     /**
1017         Destructor.
1018     */
1019     virtual ~wxDataViewModelNotifier();
1020
1021     /**
1022         Called by owning model.
1023     */
1024     virtual bool Cleared() = 0;
1025
1026     /**
1027         Get owning wxDataViewModel.
1028     */
1029     wxDataViewModel* GetOwner() const;
1030
1031     /**
1032         Called by owning model.
1033     */
1034     virtual bool ItemAdded(const wxDataViewItem& parent,
1035                            const wxDataViewItem& item) = 0;
1036
1037     /**
1038         Called by owning model.
1039     */
1040     virtual bool ItemChanged(const wxDataViewItem& item) = 0;
1041
1042     /**
1043         Called by owning model.
1044     */
1045     virtual bool ItemDeleted(const wxDataViewItem& parent,
1046                              const wxDataViewItem& item) = 0;
1047
1048     /**
1049         Called by owning model.
1050     */
1051     virtual bool ItemsAdded(const wxDataViewItem& parent,
1052                             const wxDataViewItemArray& items);
1053
1054     /**
1055         Called by owning model.
1056     */
1057     virtual bool ItemsChanged(const wxDataViewItemArray& items);
1058
1059     /**
1060         Called by owning model.
1061     */
1062     virtual bool ItemsDeleted(const wxDataViewItem& parent,
1063                               const wxDataViewItemArray& items);
1064
1065     /**
1066         Called by owning model.
1067     */
1068     virtual void Resort() = 0;
1069
1070     /**
1071         Set owner of this notifier. Used internally.
1072     */
1073     void SetOwner(wxDataViewModel* owner);
1074
1075     /**
1076         Called by owning model.
1077     */
1078     virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0;
1079 };
1080
1081
1082 /**
1083     The mode of a data-view cell; see wxDataViewRenderer for more info.
1084 */
1085 enum wxDataViewCellMode
1086 {
1087     wxDATAVIEW_CELL_INERT,
1088
1089     /**
1090         Indicates that the user can double click the cell and something will
1091         happen (e.g. a window for editing a date will pop up).
1092     */
1093     wxDATAVIEW_CELL_ACTIVATABLE,
1094
1095     /**
1096         Indicates that the user can edit the data in-place, i.e. an control
1097         will show up after a slow click on the cell. This behaviour is best
1098         known from changing the filename in most file managers etc.
1099     */
1100     wxDATAVIEW_CELL_EDITABLE
1101 };
1102
1103 /**
1104     The values of this enum controls how a wxDataViewRenderer should display
1105     its contents in a cell.
1106 */
1107 enum wxDataViewCellRenderState
1108 {
1109     wxDATAVIEW_CELL_SELECTED    = 1,
1110     wxDATAVIEW_CELL_PRELIT      = 2,
1111     wxDATAVIEW_CELL_INSENSITIVE = 4,
1112     wxDATAVIEW_CELL_FOCUSED     = 8
1113 };
1114
1115 /**
1116     @class wxDataViewRenderer
1117
1118     This class is used by wxDataViewCtrl to render the individual cells.
1119     One instance of a renderer class is owned by a wxDataViewColumn.
1120     There is a number of ready-to-use renderers provided:
1121     - wxDataViewTextRenderer,
1122     - wxDataViewTextRendererAttr,
1123     - wxDataViewIconTextRenderer,
1124     - wxDataViewToggleRenderer,
1125     - wxDataViewProgressRenderer,
1126     - wxDataViewBitmapRenderer,
1127     - wxDataViewDateRenderer,
1128     - wxDataViewSpinRenderer.
1129
1130     Additionally, the user can write own renderers by deriving from
1131     wxDataViewCustomRenderer.
1132
1133     The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted
1134     by the constructors respectively controls what actions the cell data allows
1135     and how the renderer should display its contents in a cell.
1136
1137     @library{wxadv}
1138     @category{dvc}
1139 */
1140 class wxDataViewRenderer : public wxObject
1141 {
1142 public:
1143     /**
1144         Constructor.
1145     */
1146     wxDataViewRenderer(const wxString& varianttype,
1147                        wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1148                        int align = wxDVR_DEFAULT_ALIGNMENT );
1149
1150     /**
1151         Returns the alignment. See SetAlignment()
1152     */
1153     virtual int GetAlignment() const;
1154
1155     /**
1156         Returns the cell mode.
1157     */
1158     virtual wxDataViewCellMode GetMode() const;
1159
1160     /**
1161         Returns pointer to the owning wxDataViewColumn.
1162     */
1163     wxDataViewColumn* GetOwner() const;
1164
1165     /**
1166         This methods retrieves the value from the renderer in order to
1167         transfer the value back to the data model.
1168
1169         Returns @false on failure.
1170     */
1171     virtual bool GetValue(wxVariant& value) const = 0;
1172
1173     /**
1174         Returns a string with the type of the wxVariant supported by this renderer.
1175     */
1176     wxString GetVariantType() const;
1177
1178     /**
1179         Sets the alignment of the renderer's content.
1180         The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content
1181         should have the same alignment as the column header.
1182
1183         The method is not implemented under OS X and the renderer always aligns
1184         its contents as the column header on that platform. The other platforms
1185         support both vertical and horizontal alignment.
1186     */
1187     virtual void SetAlignment( int align );
1188     /**
1189         Sets the owning wxDataViewColumn.
1190         This is usually called from within wxDataViewColumn.
1191     */
1192     void SetOwner(wxDataViewColumn* owner);
1193
1194     /**
1195         Set the value of the renderer (and thus its cell) to @a value.
1196         The internal code will then render this cell with this data.
1197     */
1198     virtual bool SetValue(const wxVariant& value) = 0;
1199
1200     /**
1201         Before data is committed to the data model, it is passed to this
1202         method where it can be checked for validity. This can also be
1203         used for checking a valid range or limiting the user input in
1204         a certain aspect (e.g. max number of characters or only alphanumeric
1205         input, ASCII only etc.). Return @false if the value is not valid.
1206
1207         Please note that due to implementation limitations, this validation
1208         is done after the editing control already is destroyed and the
1209         editing process finished.
1210     */
1211     virtual bool Validate(wxVariant& value);
1212 };
1213
1214
1215
1216 /**
1217     @class wxDataViewTextRenderer
1218
1219     wxDataViewTextRenderer is used for rendering text.
1220     It supports in-place editing if desired.
1221
1222     @library{wxadv}
1223     @category{dvc}
1224 */
1225 class wxDataViewTextRenderer : public wxDataViewRenderer
1226 {
1227 public:
1228     /**
1229         The ctor.
1230     */
1231     wxDataViewTextRenderer(const wxString& varianttype = "string",
1232                            wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1233                            int align = wxDVR_DEFAULT_ALIGNMENT );
1234 };
1235
1236
1237
1238 /**
1239     @class wxDataViewIconTextRenderer
1240
1241     The wxDataViewIconTextRenderer class is used to display text with
1242     a small icon next to it as it is typically done in a file manager.
1243
1244     This classes uses the wxDataViewIconText helper class to store its data.
1245     wxDataViewIonText can be converted to and from a wxVariant using the left shift
1246     operator.
1247
1248     @library{wxadv}
1249     @category{dvc}
1250 */
1251 class wxDataViewIconTextRenderer : public wxDataViewRenderer
1252 {
1253 public:
1254     /**
1255         The ctor.
1256     */
1257     wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText",
1258                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1259                                int align = wxDVR_DEFAULT_ALIGNMENT );
1260 };
1261
1262
1263
1264 /**
1265     @class wxDataViewProgressRenderer
1266
1267     This class is used by wxDataViewCtrl to render progress bars.
1268
1269     @library{wxadv}
1270     @category{dvc}
1271 */
1272 class wxDataViewProgressRenderer : public wxDataViewRenderer
1273 {
1274 public:
1275     /**
1276         The ctor.
1277     */
1278     wxDataViewProgressRenderer(const wxString& label = wxEmptyString,
1279                                const wxString& varianttype = "long",
1280                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1281                                int align = wxDVR_DEFAULT_ALIGNMENT );
1282 };
1283
1284
1285
1286 /**
1287     @class wxDataViewSpinRenderer
1288
1289     This is a specialized renderer for rendering integer values.
1290     It supports modifying the values in-place by using a wxSpinCtrl.
1291     The renderer only support variants of type @e long.
1292
1293     @library{wxadv}
1294     @category{dvc}
1295 */
1296 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer
1297 {
1298 public:
1299     /**
1300         Constructor.
1301         @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl.
1302     */
1303     wxDataViewSpinRenderer(int min, int max,
1304                            wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE,
1305                            int align = wxDVR_DEFAULT_ALIGNMENT);
1306 };
1307
1308
1309
1310 /**
1311     @class wxDataViewToggleRenderer
1312
1313     This class is used by wxDataViewCtrl to render toggle controls.
1314
1315     @library{wxadv}
1316     @category{dvc}
1317 */
1318 class wxDataViewToggleRenderer : public wxDataViewRenderer
1319 {
1320 public:
1321     /**
1322         The ctor.
1323     */
1324     wxDataViewToggleRenderer(const wxString& varianttype = "bool",
1325                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1326                              int align = wxDVR_DEFAULT_ALIGNMENT);
1327 };
1328
1329
1330
1331 /**
1332     @class wxDataViewDateRenderer
1333
1334     This class is used by wxDataViewCtrl to render calendar controls.
1335
1336     @library{wxadv}
1337     @category{dvc}
1338 */
1339 class wxDataViewDateRenderer : public wxDataViewRenderer
1340 {
1341 public:
1342     /**
1343         The ctor.
1344     */
1345     wxDataViewDateRenderer(const wxString& varianttype = "datetime",
1346                            wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE,
1347                            int align = wxDVR_DEFAULT_ALIGNMENT);
1348 };
1349
1350
1351
1352 /**
1353     @class wxDataViewTextRendererAttr
1354
1355     The same as wxDataViewTextRenderer but with support for font attributes.
1356     Font attributes are currently only supported under GTK+ and MSW.
1357
1358     @see wxDataViewModel::GetAttr and wxDataViewItemAttr.
1359
1360     @library{wxadv}
1361     @category{dvc}
1362 */
1363 class wxDataViewTextRendererAttr : public wxDataViewTextRenderer
1364 {
1365 public:
1366     /**
1367         The ctor.
1368     */
1369     wxDataViewTextRendererAttr(const wxString& varianttype = "string",
1370                                wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1371                                int align = wxDVR_DEFAULT_ALIGNMENT);
1372 };
1373
1374
1375
1376 /**
1377     @class wxDataViewCustomRenderer
1378
1379     You need to derive a new class from wxDataViewCustomRenderer in
1380     order to write a new renderer.
1381
1382     You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue,
1383     wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render.
1384
1385     If you want your renderer to support in-place editing then you also need to override
1386     wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl
1387     and wxDataViewCustomRenderer::GetValueFromEditorCtrl.
1388
1389     Note that a special event handler will be pushed onto that editor control
1390     which handles @e \<ENTER\> and focus out events in order to end the editing.
1391
1392     @library{wxadv}
1393     @category{dvc}
1394 */
1395 class wxDataViewCustomRenderer : public wxDataViewRenderer
1396 {
1397 public:
1398     /**
1399         Constructor.
1400     */
1401     wxDataViewCustomRenderer(const wxString& varianttype = "string",
1402                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1403                              int align = -1, bool no_init = false);
1404
1405     /**
1406         Destructor.
1407     */
1408     virtual ~wxDataViewCustomRenderer();
1409
1410     /**
1411         Override this to react to double clicks or ENTER.
1412         This method will only be called in wxDATAVIEW_CELL_ACTIVATABLE mode.
1413     */
1414     virtual bool Activate( wxRect cell,
1415                            wxDataViewModel* model,
1416                            const wxDataViewItem & item,
1417                            unsigned int col );
1418
1419     /**
1420         Override this to create the actual editor control once editing
1421         is about to start.
1422
1423         @a parent is the parent of the editor control, @a labelRect indicates the
1424         position and size of the editor control and @a value is its initial value:
1425         @code
1426         {
1427             long l = value;
1428             return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString,
1429                         labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l );
1430         }
1431         @endcode
1432     */
1433     virtual wxControl* CreateEditorCtrl(wxWindow* parent,
1434                                         wxRect labelRect,
1435                                         const wxVariant& value);
1436
1437     /**
1438         Create DC on request. Internal.
1439     */
1440     virtual wxDC* GetDC();
1441
1442     /**
1443         Return size required to show content.
1444     */
1445     virtual wxSize GetSize() const = 0;
1446
1447     /**
1448         Overrride this so that the renderer can get the value from the editor
1449         control (pointed to by @a editor):
1450         @code
1451         {
1452             wxSpinCtrl *sc = (wxSpinCtrl*) editor;
1453             long l = sc->GetValue();
1454             value = l;
1455             return true;
1456         }
1457         @endcode
1458     */
1459     virtual bool GetValueFromEditorCtrl(wxControl* editor,
1460                                         wxVariant& value);
1461
1462     /**
1463         Override this and make it return @true in order to
1464         indicate that this renderer supports in-place editing.
1465     */
1466     virtual bool HasEditorCtrl();
1467
1468     /**
1469         Overrride this to react to a left click.
1470         This method will only be called in @c wxDATAVIEW_CELL_ACTIVATABLE mode.
1471     */
1472     virtual bool LeftClick( wxPoint cursor,
1473                             wxRect cell,
1474                             wxDataViewModel * model,
1475                             const wxDataViewItem & item,
1476                             unsigned int col );
1477
1478     /**
1479         Override this to render the cell.
1480         Before this is called, wxDataViewRenderer::SetValue was called
1481         so that this instance knows what to render.
1482     */
1483     virtual bool Render(wxRect cell, wxDC* dc, int state) = 0;
1484
1485     /**
1486         This method should be called from within Render() whenever you need to
1487         render simple text.
1488         This will ensure that the correct colour, font and vertical alignment will
1489         be chosen so the text will look the same as text drawn by native renderers.
1490     */
1491     void RenderText(const wxString& text, int xoffset, wxRect cell,
1492                     wxDC* dc, int state);
1493
1494     /**
1495         Overrride this to start a drag operation. Not yet supported.
1496     */
1497     virtual bool StartDrag(wxPoint cursor, wxRect cell,
1498                            wxDataViewModel* model,
1499                            const wxDataViewItem & item,
1500                            unsigned int col);
1501 };
1502
1503
1504
1505 /**
1506     @class wxDataViewBitmapRenderer
1507
1508     This class is used by wxDataViewCtrl to render bitmap controls.
1509
1510     @library{wxadv}
1511     @category{dvc}
1512 */
1513 class wxDataViewBitmapRenderer : public wxDataViewRenderer
1514 {
1515 public:
1516     /**
1517         The ctor.
1518     */
1519     wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap",
1520                              wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT,
1521                              int align = wxDVR_DEFAULT_ALIGNMENT,
1522 };
1523
1524
1525 /**
1526     The flags used by wxDataViewColumn.
1527 */
1528 enum wxDataViewColumnFlags
1529 {
1530     wxDATAVIEW_COL_RESIZABLE     = 1,
1531     wxDATAVIEW_COL_SORTABLE      = 2,
1532     wxDATAVIEW_COL_REORDERABLE   = 4,
1533     wxDATAVIEW_COL_HIDDEN        = 8
1534 };
1535
1536 /**
1537     @class wxDataViewColumn
1538
1539     This class represents a column in a wxDataViewCtrl.
1540     One wxDataViewColumn is bound to one column in the data model, to which the
1541     wxDataViewCtrl has been associated.
1542
1543     An instance of wxDataViewRenderer is used by this class to render its data.
1544
1545     @library{wxadv}
1546     @category{dvc}
1547 */
1548 class wxDataViewColumn : public wxObject
1549 {
1550 public:
1551     //@{
1552     /**
1553         Constructors.
1554     */
1555     wxDataViewColumn(const wxString& title,
1556                      wxDataViewRenderer* renderer,
1557                      unsigned int model_column,
1558                      int width = wxDVC_DEFAULT_WIDTH,
1559                      wxAlignment align = wxALIGN_CENTRE,
1560                      int flags = wxDATAVIEW_COL_RESIZABLE);
1561     wxDataViewColumn(const wxBitmap& bitmap,
1562                      wxDataViewRenderer* renderer,
1563                      unsigned int model_column,
1564                      int width = wxDVC_DEFAULT_WIDTH,
1565                      wxAlignment align = wxALIGN_CENTRE,
1566                      int flags = wxDATAVIEW_COL_RESIZABLE);
1567     //@}
1568
1569     /**
1570         Destructor.
1571     */
1572     virtual ~wxDataViewColumn();
1573
1574     /**
1575         Returns the bitmap in the header of the column, if any.
1576     */
1577     const wxBitmap& GetBitmap() const;
1578
1579     /**
1580         Returns the index of the column of the model, which this
1581         wxDataViewColumn is displaying.
1582     */
1583     unsigned int GetModelColumn() const;
1584
1585     /**
1586         Returns the owning wxDataViewCtrl.
1587     */
1588     wxDataViewCtrl* GetOwner() const;
1589
1590     /**
1591         Returns the renderer of this wxDataViewColumn.
1592
1593         @see wxDataViewRenderer.
1594     */
1595     wxDataViewRenderer* GetRenderer() const;
1596
1597     /**
1598         Returns @true if the column is reorderable.
1599     */
1600     bool GetReorderable();
1601
1602     /**
1603         Returns @true if the column is sortable.
1604
1605         @see SetSortable()
1606     */
1607     bool GetSortable();
1608
1609     /**
1610         Returns the width of the column.
1611     */
1612     virtual int GetWidth() const;
1613
1614     /**
1615         Returns @true, if the sort order is ascending.
1616
1617         @see SetSortOrder()
1618     */
1619     virtual bool IsSortOrderAscending() const;
1620
1621     /**
1622         Set the alignment of the column header.
1623     */
1624     virtual void SetAlignment(wxAlignment align);
1625
1626     /**
1627         Set the bitmap of the column header.
1628     */
1629     virtual void SetBitmap(const wxBitmap& bitmap);
1630
1631     /**
1632         Indicate wether the column can be reordered by the user using the mouse.
1633         This is typically implemented visually by dragging the header button around.
1634     */
1635     virtual void SetReorderable(bool reorderable);
1636
1637     /**
1638         Indicate the sort order if the implementation of the wxDataViewCtrl supports
1639         it, most commonly by showing a little arrow.
1640     */
1641     virtual void SetSortOrder(bool ascending);
1642
1643     /**
1644         Indicate that the column is sortable.
1645         This does not show any sorting indicate yet, but it does make the column
1646         header clickable. Call SetSortOrder() afterwards to actually make the sort
1647         indicator appear.
1648
1649         If @a sortable is @false, the column header is no longer clickable and
1650         the sort indicator (little arrow) will disappear.
1651     */
1652     virtual void SetSortable(bool sortable);
1653
1654     /**
1655         Set the title of the column header to @a title.
1656     */
1657     virtual void SetTitle(const wxString& title);
1658 };
1659
1660
1661
1662 /**
1663     @class wxDataViewTreeCtrl
1664
1665     This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore
1666     and forwards most of its API to that class.
1667     Additionally, it uses a wxImageList to store a list of icons.
1668
1669     The main purpose of this class is to look like a wxTreeCtrl to make a transition
1670     from it to the wxDataViewCtrl class simpler.
1671
1672     @library{wxadv}
1673     @category{ctrl,dvc}
1674     @appearance{dataviewtreectrl.png}
1675 */
1676 class wxDataViewTreeCtrl : public wxDataViewCtrl
1677 {
1678 public:
1679     /**
1680         Default ctor.
1681     */
1682     wxDataViewTreeCtrl();
1683
1684     /**
1685         Constructor. Calls Create().
1686     */
1687     wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id,
1688                        const wxPoint& pos = wxDefaultPosition,
1689                        const wxSize& size = wxDefaultSize,
1690                        long style = wxDV_NO_HEADER,
1691                        const wxValidator& validator = wxDefaultValidator);
1692
1693     /**
1694         Destructor. Deletes the image list if any.
1695     */
1696     virtual ~wxDataViewTreeCtrl();
1697
1698     /**
1699         @todo docme
1700     */
1701     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1702                                    const wxString& text,
1703                                    int icon = -1,
1704                                    int expanded = -1,
1705                                    wxClientData* data = NULL);
1706
1707     /**
1708         @todo docme
1709     */
1710     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1711                               const wxString& text,
1712                               int icon = -1,
1713                               wxClientData* data = NULL);
1714
1715     /**
1716         Creates the control and a wxDataViewTreeStore as its internal model.
1717     */
1718     bool Create(wxWindow* parent, wxWindowID id,
1719                 const wxPoint& pos = wxDefaultPosition,
1720                 const wxSize& size = wxDefaultSize,
1721                 long style = wxDV_NO_HEADER,
1722                 const wxValidator& validator = wxDefaultValidator);
1723
1724     /**
1725         Calls the identical method from wxDataViewTreeStore.
1726     */
1727     void DeleteAllItems();
1728
1729     /**
1730         Calls the identical method from wxDataViewTreeStore.
1731     */
1732     void DeleteChildren(const wxDataViewItem& item);
1733
1734     /**
1735         Calls the identical method from wxDataViewTreeStore.
1736     */
1737     void DeleteItem(const wxDataViewItem& item);
1738
1739     /**
1740         Calls the identical method from wxDataViewTreeStore.
1741     */
1742     int GetChildCount(const wxDataViewItem& parent) const;
1743
1744     /**
1745         Returns the image list.
1746     */
1747     wxImageList* GetImageList();
1748
1749     /**
1750         Calls the identical method from wxDataViewTreeStore.
1751     */
1752     wxClientData* GetItemData(const wxDataViewItem& item) const;
1753
1754     /**
1755         Calls the identical method from wxDataViewTreeStore.
1756     */
1757     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
1758
1759     /**
1760         Calls the identical method from wxDataViewTreeStore.
1761     */
1762     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
1763
1764     /**
1765         Calls the identical method from wxDataViewTreeStore.
1766     */
1767     wxString GetItemText(const wxDataViewItem& item) const;
1768
1769     /**
1770         Calls the identical method from wxDataViewTreeStore.
1771     */
1772     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1773                                unsigned int pos) const;
1774
1775     //@{
1776     /**
1777         Returns the store.
1778     */
1779     wxDataViewTreeStore* GetStore() const;
1780     const wxDataViewTreeStore* GetStore() const;
1781     //@}
1782
1783     /**
1784         Calls the same method from wxDataViewTreeStore but uses
1785         an index position in the image list instead of a wxIcon.
1786     */
1787     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1788                                    const wxDataViewItem& previous,
1789                                    const wxString& text,
1790                                    int icon = -1,
1791                                    int expanded = -1,
1792                                    wxClientData* data = NULL);
1793
1794     /**
1795         Calls the same method from wxDataViewTreeStore but uses
1796         an index position in the image list instead of a wxIcon.
1797     */
1798     wxDataViewItem InsertItem(const wxDataViewItem& parent,
1799                               const wxDataViewItem& previous,
1800                               const wxString& text,
1801                               int icon = -1,
1802                               wxClientData* data = NULL);
1803
1804     /**
1805         Calls the same method from wxDataViewTreeStore but uses
1806         an index position in the image list instead of a wxIcon.
1807     */
1808     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1809                                     const wxString& text,
1810                                     int icon = -1,
1811                                     int expanded = -1,
1812                                     wxClientData* data = NULL);
1813
1814     /**
1815         Calls the same method from wxDataViewTreeStore but uses
1816         an index position in the image list instead of a wxIcon.
1817     */
1818     wxDataViewItem PrependItem(const wxDataViewItem& parent,
1819                                const wxString& text,
1820                                int icon = -1,
1821                                wxClientData* data = NULL);
1822
1823     /**
1824         Sets the image list.
1825     */
1826     void SetImageList(wxImageList* imagelist);
1827
1828     /**
1829         Calls the identical method from wxDataViewTreeStore.
1830     */
1831     void SetItemData(const wxDataViewItem& item, wxClientData* data);
1832
1833     /**
1834         Calls the identical method from wxDataViewTreeStore.
1835     */
1836     void SetItemExpandedIcon(const wxDataViewItem& item,
1837                              const wxIcon& icon);
1838
1839     /**
1840         Calls the identical method from wxDataViewTreeStore.
1841     */
1842     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1843
1844     /**
1845         Calls the identical method from wxDataViewTreeStore.
1846     */
1847     void SetItemText(const wxDataViewItem& item,
1848                      const wxString& text);
1849 };
1850
1851
1852
1853 /**
1854     @class wxDataViewTreeStore
1855
1856     wxDataViewTreeStore is a specialised wxDataViewModel for displaying simple
1857     trees very much like wxTreeCtrl does and it offers a similar API.
1858
1859     This class actually stores the entire tree (therefore its name) and implements
1860     all virtual methods from the base class so it can be used directly without
1861     having to derive any class from it.
1862     This comes at the price of much reduced flexibility.
1863
1864     @library{wxadv}
1865     @category{dvc}
1866 */
1867 class wxDataViewTreeStore : public wxDataViewModel
1868 {
1869 public:
1870     /**
1871         Constructor. Creates the invisible root node internally.
1872     */
1873     wxDataViewTreeStore();
1874
1875     /**
1876         Destructor.
1877     */
1878     virtual ~wxDataViewTreeStore();
1879
1880     /**
1881         Append a container.
1882     */
1883     wxDataViewItem AppendContainer(const wxDataViewItem& parent,
1884                                    const wxString& text,
1885                                    const wxIcon& icon = wxNullIcon,
1886                                    const wxIcon& expanded = wxNullIcon,
1887                                    wxClientData* data = NULL);
1888
1889     /**
1890         Append an item.
1891     */
1892     wxDataViewItem AppendItem(const wxDataViewItem& parent,
1893                               const wxString& text,
1894                               const wxIcon& icon = wxNullIcon,
1895                               wxClientData* data = NULL);
1896
1897     /**
1898         Delete all item in the model.
1899     */
1900     void DeleteAllItems();
1901
1902     /**
1903         Delete all children of the item, but not the item itself.
1904     */
1905     void DeleteChildren(const wxDataViewItem& item);
1906
1907     /**
1908         Delete this item.
1909     */
1910     void DeleteItem(const wxDataViewItem& item);
1911
1912     /**
1913         Return the number of children of item.
1914     */
1915     int GetChildCount(const wxDataViewItem& parent) const;
1916
1917     /**
1918         Returns the client data asoociated with the item.
1919     */
1920     wxClientData* GetItemData(const wxDataViewItem& item) const;
1921
1922     /**
1923         Returns the icon to display in expanded containers.
1924     */
1925     const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const;
1926
1927     /**
1928         Returns the icon of the item.
1929     */
1930     const wxIcon& GetItemIcon(const wxDataViewItem& item) const;
1931
1932     /**
1933         Returns the text of the item.
1934     */
1935     wxString GetItemText(const wxDataViewItem& item) const;
1936
1937     /**
1938         Returns the nth child item of item.
1939     */
1940     wxDataViewItem GetNthChild(const wxDataViewItem& parent,
1941                                unsigned int pos) const;
1942
1943     /**
1944         Inserts a container after @a previous.
1945     */
1946     wxDataViewItem InsertContainer(const wxDataViewItem& parent,
1947                                    const wxDataViewItem& previous,
1948                                    const wxString& text,
1949                                    const wxIcon& icon = wxNullIcon,
1950                                    const wxIcon& expanded = wxNullIcon,
1951                                    wxClientData* data = NULL);
1952
1953     /**
1954         Inserts an item after @a previous.
1955     */
1956     wxDataViewItem InsertItem(const wxDataViewItem& parent,
1957                               const wxDataViewItem& previous,
1958                               const wxString& text,
1959                               const wxIcon& icon = wxNullIcon,
1960                               wxClientData* data = NULL);
1961
1962     /**
1963         Inserts a container before the first child item or @a parent.
1964     */
1965     wxDataViewItem PrependContainer(const wxDataViewItem& parent,
1966                                     const wxString& text,
1967                                     const wxIcon& icon = wxNullIcon,
1968                                     const wxIcon& expanded = wxNullIcon,
1969                                     wxClientData* data = NULL);
1970
1971     /**
1972         Inserts an item before the first child item or @a parent.
1973     */
1974     wxDataViewItem PrependItem(const wxDataViewItem& parent,
1975                                const wxString& text,
1976                                const wxIcon& icon = wxNullIcon,
1977                                wxClientData* data = NULL);
1978
1979     /**
1980         Sets the client data associated with the item.
1981     */
1982     void SetItemData(const wxDataViewItem& item, wxClientData* data);
1983
1984     /**
1985         Sets the expanded icon for the item.
1986     */
1987     void SetItemExpandedIcon(const wxDataViewItem& item,
1988                              const wxIcon& icon);
1989
1990     /**
1991         Sets the icon for the item.
1992     */
1993     void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon);
1994 };
1995