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