interface/wx/dataview.h

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