interface/wx/dataview.h

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