interface/wx/dataview.h

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