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