interface/wx/dataview.h

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