1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: dataview.h 3 // Purpose: interface of wxDataView* classes 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 9 /** 10 @class wxDataViewModel 11 12 wxDataViewModel is the base class for all data model to be displayed by a 13 wxDataViewCtrl. 14 15 All other models derive from it and must implement its pure virtual functions 16 in order to define a complete data model. In detail, you need to override 17 wxDataViewModel::IsContainer, wxDataViewModel::GetParent, wxDataViewModel::GetChildren, 18 wxDataViewModel::GetColumnCount, wxDataViewModel::GetColumnType and 19 wxDataViewModel::GetValue in order to define the data model which acts as an 20 interface between your actual data and the wxDataViewCtrl. 21 22 Note that wxDataViewModel does not define the position or index of any item 23 in the control because different controls might display the same data differently. 24 wxDataViewModel does provide a wxDataViewModel::Compare method which the 25 wxDataViewCtrl may use to sort the data either in conjunction with a column 26 header or without (see wxDataViewModel::HasDefaultCompare). 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. To a certain extent, 31 you can use (the somewhat more elegant) wxAny instead of wxVariant as there 32 is code to convert between the two, but it is unclear what impact this will 33 have on performance. 34 35 Since you will usually allow the wxDataViewCtrl to change your data 36 through its graphical interface, you will also have to override 37 wxDataViewModel::SetValue which the wxDataViewCtrl will call when a change 38 to some data has been committed. 39 40 If the data represented by the model is changed by something else than its 41 associated wxDataViewCtrl, the control has to be notified about the change. 42 Depending on what happened you need to call one of the following methods: 43 - wxDataViewModel::ValueChanged, 44 - wxDataViewModel::ItemAdded, 45 - wxDataViewModel::ItemDeleted, 46 - wxDataViewModel::ItemChanged, 47 - wxDataViewModel::Cleared. 48 49 There are plural forms for notification of addition, change or removal of 50 several item at once. See: 51 - wxDataViewModel::ItemsAdded, 52 - wxDataViewModel::ItemsDeleted, 53 - wxDataViewModel::ItemsChanged. 54 55 This class maintains a list of wxDataViewModelNotifier which link this class 56 to the specific implementations on the supported platforms so that e.g. calling 57 wxDataViewModel::ValueChanged on this model will just call 58 wxDataViewModelNotifier::ValueChanged for each notifier that has been added. 59 You can also add your own notifier in order to get informed about any changes 60 to the data in the list model. 61 62 Currently wxWidgets provides the following models apart from the base model: 63 wxDataViewIndexListModel, wxDataViewVirtualListModel, wxDataViewTreeStore, 64 wxDataViewListStore. 65 66 Note that wxDataViewModel is reference counted, derives from wxRefCounter 67 and cannot be deleted directly as it can be shared by several wxDataViewCtrls. 68 This implies that you need to decrease the reference count after 69 associating the model with a control like this: 70 71 @code 72 wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY ); 73 wxDataViewModel *musicModel = new MyMusicModel; 74 m_musicCtrl->AssociateModel( musicModel ); 75 musicModel->DecRef(); // avoid memory leak !! 76 77 // add columns now 78 @endcode 79 80 A potentially better way to avoid memory leaks is to use wxObjectDataPtr 81 82 @code 83 wxObjectDataPtr<MyMusicModel> musicModel; 84 85 wxDataViewCtrl *musicCtrl = new wxDataViewCtrl( this, wxID_ANY ); 86 musicModel = new MyMusicModel; 87 m_musicCtrl->AssociateModel( musicModel.get() ); 88 89 // add columns now 90 @endcode 91 92 93 @library{wxadv} 94 @category{dvc} 95 */ 96 class wxDataViewModel : public wxRefCounter 97 { 98 public: 99 /** 100 Constructor. 101 */ 102 wxDataViewModel(); 103 104 /** 105 Adds a wxDataViewModelNotifier to the model. 106 */ 107 void AddNotifier(wxDataViewModelNotifier* notifier); 108 109 /** 110 Change the value of the given item and update the control to reflect 111 it. 112 113 This function simply calls SetValue() and, if it succeeded, 114 ValueChanged(). 115 116 @since 2.9.1 117 118 @param variant 119 The new value. 120 @param item 121 The item (row) to update. 122 @param col 123 The column to update. 124 @return 125 @true if both SetValue() and ValueChanged() returned @true. 126 */ 127 bool ChangeValue(const wxVariant& variant, 128 const wxDataViewItem& item, 129 unsigned int col); 130 131 /** 132 Called to inform the model that all data has been cleared. 133 The control will reread the data from the model again. 134 */ 135 bool Cleared(); 136 137 /** 138 The compare function to be used by control. The default compare function 139 sorts by container and other items separately and in ascending order. 140 Override this for a different sorting behaviour. 141 142 @see HasDefaultCompare(). 143 */ 144 virtual int Compare(const wxDataViewItem& item1, 145 const wxDataViewItem& item2, 146 unsigned int column, 147 bool ascending) const; 148 149 /** 150 Override this to indicate that the item has special font attributes. 151 This only affects the wxDataViewTextRendererText renderer. 152 153 The base class version always simply returns @false. 154 155 @see wxDataViewItemAttr. 156 157 @param item 158 The item for which the attribute is requested. 159 @param col 160 The column of the item for which the attribute is requested. 161 @param attr 162 The attribute to be filled in if the function returns @true. 163 @return 164 @true if this item has an attribute or @false otherwise. 165 */ 166 virtual bool GetAttr(const wxDataViewItem& item, unsigned int col, 167 wxDataViewItemAttr& attr) const; 168 169 /** 170 Override this to indicate that the item should be disabled. 171 172 Disabled items are displayed differently (e.g. grayed out) and cannot 173 be interacted with. 174 175 The base class version always returns @true, thus making all items 176 enabled by default. 177 178 @param item 179 The item whose enabled status is requested. 180 @param col 181 The column of the item whose enabled status is requested. 182 @return 183 @true if this item should be enabled, @false otherwise. 184 185 @note Currently disabling items is not supported by the wxOSX/Carbon 186 implementation. 187 188 @since 2.9.2 189 */ 190 virtual bool IsEnabled(const wxDataViewItem &item, 191 unsigned int col) const; 192 193 /** 194 Override this so the control can query the child items of an item. 195 Returns the number of items. 196 */ 197 virtual unsigned int GetChildren(const wxDataViewItem& item, 198 wxDataViewItemArray& children) const = 0; 199 200 /** 201 Override this to indicate the number of columns in the model. 202 */ 203 virtual unsigned int GetColumnCount() const = 0; 204 205 /** 206 Override this to indicate what type of data is stored in the 207 column specified by @a col. 208 209 This should return a string indicating the type of data as reported by wxVariant. 210 */ 211 virtual wxString GetColumnType(unsigned int col) const = 0; 212 213 /** 214 Override this to indicate which wxDataViewItem representing the parent 215 of @a item or an invalid wxDataViewItem if the root item is 216 the parent item. 217 */ 218 virtual wxDataViewItem GetParent(const wxDataViewItem& item) const = 0; 219 220 /** 221 Override this to indicate the value of @a item. 222 A wxVariant is used to store the data. 223 */ 224 virtual void GetValue(wxVariant& variant, const wxDataViewItem& item, 225 unsigned int col) const = 0; 226 227 /** 228 Override this method to indicate if a container item merely acts as a 229 headline (or for categorisation) or if it also acts a normal item with 230 entries for further columns. By default returns @false. 231 */ 232 virtual bool HasContainerColumns(const wxDataViewItem& item) const; 233 234 /** 235 Override this to indicate that the model provides a default compare 236 function that the control should use if no wxDataViewColumn has been 237 chosen for sorting. Usually, the user clicks on a column header for 238 sorting, the data will be sorted alphanumerically. 239 240 If any other order (e.g. by index or order of appearance) is required, 241 then this should be used. 242 See wxDataViewIndexListModel for a model which makes use of this. 243 */ 244 virtual bool HasDefaultCompare() const; 245 246 /** 247 Return true if there is a value in the given column of this item. 248 249 All normal items have values in all columns but the container items 250 only show their label in the first column (@a col == 0) by default (but 251 see HasContainerColumns()). So this function always returns true for 252 the first column while for the other ones it returns true only if the 253 item is not a container or HasContainerColumns() was overridden to 254 return true for it. 255 256 @since 2.9.1 257 */ 258 bool HasValue(const wxDataViewItem& item, unsigned col) const; 259 260 /** 261 Override this to indicate of @a item is a container, i.e.\ if 262 it can have child items. 263 */ 264 virtual bool IsContainer(const wxDataViewItem& item) const = 0; 265 266 /** 267 Call this to inform the model that an item has been added to the data. 268 */ 269 bool ItemAdded(const wxDataViewItem& parent, 270 const wxDataViewItem& item); 271 272 /** 273 Call this to inform the model that an item has changed. 274 275 This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED 276 event (in which the column fields will not be set) to the user. 277 */ 278 bool ItemChanged(const wxDataViewItem& item); 279 280 /** 281 Call this to inform the model that an item has been deleted from the data. 282 */ 283 bool ItemDeleted(const wxDataViewItem& parent, 284 const wxDataViewItem& item); 285 286 /** 287 Call this to inform the model that several items have been added to the data. 288 */ 289 bool ItemsAdded(const wxDataViewItem& parent, 290 const wxDataViewItemArray& items); 291 292 /** 293 Call this to inform the model that several items have changed. 294 295 This will eventually emit @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED 296 events (in which the column fields will not be set) to the user. 297 */ 298 bool ItemsChanged(const wxDataViewItemArray& items); 299 300 /** 301 Call this to inform the model that several items have been deleted. 302 */ 303 bool ItemsDeleted(const wxDataViewItem& parent, 304 const wxDataViewItemArray& items); 305 306 /** 307 Remove the @a notifier from the list of notifiers. 308 */ 309 void RemoveNotifier(wxDataViewModelNotifier* notifier); 310 311 /** 312 Call this to initiate a resort after the sort function has been changed. 313 */ 314 virtual void Resort(); 315 316 /** 317 This gets called in order to set a value in the data model. 318 319 The most common scenario is that the wxDataViewCtrl calls this method 320 after the user changed some data in the view. 321 322 This is the function you need to override in your derived class but if 323 you want to call it, ChangeValue() is usually more convenient as 324 otherwise you need to manually call ValueChanged() to update the 325 control itself. 326 */ 327 virtual bool SetValue(const wxVariant& variant, 328 const wxDataViewItem& item, 329 unsigned int col) = 0; 330 331 /** 332 Call this to inform this model that a value in the model has been changed. 333 This is also called from wxDataViewCtrl's internal editing code, e.g. when 334 editing a text field in the control. 335 336 This will eventually emit a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED 337 event to the user. 338 */ 339 bool ValueChanged(const wxDataViewItem& item, 340 unsigned int col); 341 342 343 virtual bool IsListModel() const; 344 virtual bool IsVirtualListModel() const; 345 346 protected: 347 348 /** 349 Destructor. This should not be called directly. Use DecRef() instead. 350 */ 351 virtual ~wxDataViewModel(); 352 }; 353 354 355 356 /** 357 @class wxDataViewListModel 358 359 Base class with abstract API for wxDataViewIndexListModel and 360 wxDataViewVirtualListModel. 361 362 @library{wxadv} 363 @category{dvc} 364 */ 365 class wxDataViewListModel : public wxDataViewModel 366 { 367 public: 368 369 /** 370 Destructor. 371 */ 372 virtual ~wxDataViewListModel(); 373 374 /** 375 Compare method that sorts the items by their index. 376 */ 377 int Compare(const wxDataViewItem& item1, 378 const wxDataViewItem& item2, 379 unsigned int column, bool ascending) const; 380 381 /** 382 Override this to indicate that the row has special font attributes. 383 This only affects the wxDataViewTextRendererText() renderer. 384 385 The base class version always simply returns @false. 386 387 @see wxDataViewItemAttr. 388 389 @param row 390 The row for which the attribute is requested. 391 @param col 392 The column for which the attribute is requested. 393 @param attr 394 The attribute to be filled in if the function returns @true. 395 @return 396 @true if this item has an attribute or @false otherwise. 397 */ 398 virtual bool GetAttrByRow(unsigned int row, unsigned int col, 399 wxDataViewItemAttr& attr) const; 400 401 /** 402 Override this if you want to disable specific items. 403 404 The base class version always returns @true, thus making all items 405 enabled by default. 406 407 @param row 408 The row of the item whose enabled status is requested. 409 @param col 410 The column of the item whose enabled status is requested. 411 @return 412 @true if the item at this row and column should be enabled, 413 @false otherwise. 414 415 @note See wxDataViewModel::IsEnabled() for the current status of 416 support for disabling the items under different platforms. 417 418 @since 2.9.2 419 */ 420 virtual bool IsEnabledByRow(unsigned int row, 421 unsigned int col) const; 422 423 /** 424 Returns the number of items (or rows) in the list. 425 */ 426 unsigned int GetCount() const = 0; 427 428 /** 429 Returns the position of given @e item. 430 */ 431 unsigned int GetRow(const wxDataViewItem& item) const = 0; 432 433 /** 434 Override this to allow getting values from the model. 435 */ 436 virtual void GetValueByRow(wxVariant& variant, unsigned int row, 437 unsigned int col) const = 0; 438 439 /** 440 Called in order to set a value in the model. 441 */ 442 virtual bool SetValueByRow(const wxVariant& variant, unsigned int row, 443 unsigned int col) = 0; 444 }; 445 446 447 /** 448 @class wxDataViewIndexListModel 449 450 wxDataViewIndexListModel is a specialized data model which lets you address 451 an item by its position (row) rather than its wxDataViewItem (which you can 452 obtain from this class). 453 This model also provides its own wxDataViewIndexListModel::Compare 454 method which sorts the model's data by the index. 455 456 This model is not a virtual model since the control stores each wxDataViewItem. 457 Use wxDataViewVirtualListModel if you need to display millions of items or 458 have other reason to use a virtual control. 459 460 @see wxDataViewListModel for the API. 461 462 @library{wxadv} 463 @category{dvc} 464 */ 465 466 class wxDataViewIndexListModel : public wxDataViewListModel 467 { 468 public: 469 /** 470 Constructor. 471 */ 472 wxDataViewIndexListModel(unsigned int initial_size = 0); 473 474 /** 475 Returns the wxDataViewItem at the given @e row. 476 */ 477 wxDataViewItem GetItem(unsigned int row) const; 478 479 /** 480 Call this after if the data has to be read again from the model. 481 This is useful after major changes when calling the methods below 482 (possibly thousands of times) doesn't make sense. 483 */ 484 void Reset(unsigned int new_size); 485 486 /** 487 Call this after a row has been appended to the model. 488 */ 489 void RowAppended(); 490 491 /** 492 Call this after a row has been changed. 493 */ 494 void RowChanged(unsigned int row); 495 496 /** 497 Call this after a row has been deleted. 498 */ 499 void RowDeleted(unsigned int row); 500 501 /** 502 Call this after a row has been inserted at the given position. 503 */ 504 void RowInserted(unsigned int before); 505 506 /** 507 Call this after a row has been prepended to the model. 508 */ 509 void RowPrepended(); 510 511 /** 512 Call this after a value has been changed. 513 */ 514 void RowValueChanged(unsigned int row, unsigned int col); 515 516 /** 517 Call this after rows have been deleted. 518 The array will internally get copied and sorted in descending order so 519 that the rows with the highest position will be deleted first. 520 */ 521 void RowsDeleted(const wxArrayInt& rows); 522 523 }; 524 525 /** 526 @class wxDataViewVirtualListModel 527 528 wxDataViewVirtualListModel is a specialized data model which lets you address 529 an item by its position (row) rather than its wxDataViewItem and as such offers 530 the exact same interface as wxDataViewIndexListModel. 531 The important difference is that under platforms other than OS X, using this 532 model will result in a truly virtual control able to handle millions of items 533 as the control doesn't store any item (a feature not supported by OS X). 534 535 @see wxDataViewListModel for the API. 536 537 @library{wxadv} 538 @category{dvc} 539 */ 540 541 class wxDataViewVirtualListModel : public wxDataViewListModel 542 { 543 public: 544 /** 545 Constructor. 546 */ 547 wxDataViewVirtualListModel(unsigned int initial_size = 0); 548 549 /** 550 Returns the wxDataViewItem at the given @e row. 551 */ 552 wxDataViewItem GetItem(unsigned int row) const; 553 554 /** 555 Call this after if the data has to be read again from the model. 556 This is useful after major changes when calling the methods below 557 (possibly thousands of times) doesn't make sense. 558 */ 559 void Reset(unsigned int new_size); 560 561 /** 562 Call this after a row has been appended to the model. 563 */ 564 void RowAppended(); 565 566 /** 567 Call this after a row has been changed. 568 */ 569 void RowChanged(unsigned int row); 570 571 /** 572 Call this after a row has been deleted. 573 */ 574 void RowDeleted(unsigned int row); 575 576 /** 577 Call this after a row has been inserted at the given position. 578 */ 579 void RowInserted(unsigned int before); 580 581 /** 582 Call this after a row has been prepended to the model. 583 */ 584 void RowPrepended(); 585 586 /** 587 Call this after a value has been changed. 588 */ 589 void RowValueChanged(unsigned int row, unsigned int col); 590 591 /** 592 Call this after rows have been deleted. 593 The array will internally get copied and sorted in descending order so 594 that the rows with the highest position will be deleted first. 595 */ 596 void RowsDeleted(const wxArrayInt& rows); 597 598 }; 599 600 601 602 /** 603 @class wxDataViewItemAttr 604 605 This class is used to indicate to a wxDataViewCtrl that a certain item 606 (see wxDataViewItem) has extra font attributes for its renderer. 607 For this, it is required to override wxDataViewModel::GetAttr. 608 609 Attributes are currently only supported by wxDataViewTextRendererText. 610 611 @library{wxadv} 612 @category{dvc} 613 */ 614 class wxDataViewItemAttr 615 { 616 public: 617 /** 618 Constructor. 619 */ 620 wxDataViewItemAttr(); 621 622 /** 623 Call this to indicate that the item shall be displayed in bold text. 624 */ 625 void SetBold(bool set); 626 627 /** 628 Call this to indicate that the item shall be displayed with that colour. 629 */ 630 void SetColour(const wxColour& colour); 631 632 /** 633 Call this to set the background colour to use. 634 635 Currently this attribute is only supported in the generic version of 636 wxDataViewCtrl and ignored by the native GTK+ and OS X implementations. 637 638 @since 2.9.4 639 */ 640 void SetBackgroundColour(const wxColour& colour); 641 642 /** 643 Call this to indicate that the item shall be displayed in italic text. 644 */ 645 void SetItalic(bool set); 646 647 648 /** 649 Returns true if the colour property has been set. 650 */ 651 bool HasColour() const; 652 653 /** 654 Returns this attribute's colour. 655 */ 656 const wxColour& GetColour() const; 657 658 /** 659 Returns true if any property affecting the font has been set. 660 */ 661 bool HasFont() const; 662 663 /** 664 Returns value of the bold property. 665 */ 666 bool GetBold() const; 667 668 /** 669 Returns value of the italics property. 670 */ 671 bool GetItalic() const; 672 673 /** 674 Returns true if the background colour property has been set. 675 */ 676 bool HasBackgroundColour() const; 677 678 /** 679 Returns the colour to be used for the background. 680 */ 681 const wxColour& GetBackgroundColour() const; 682 683 /** 684 Returns true if none of the properties have been set. 685 */ 686 bool IsDefault() const; 687 688 /** 689 Return the font based on the given one with this attribute applied to it. 690 */ 691 wxFont GetEffectiveFont(const wxFont& font) const; 692 }; 693 694 695 696 /** 697 @class wxDataViewItem 698 699 wxDataViewItem is a small opaque class that represents an item in a wxDataViewCtrl 700 in a persistent way, i.e. independent of the position of the item in the control 701 or changes to its contents. 702 703 It must hold a unique ID of type @e void* in its only field and can be converted 704 to and from it. 705 706 If the ID is @NULL the wxDataViewItem is invalid and wxDataViewItem::IsOk will 707 return @false which used in many places in the API of wxDataViewCtrl to 708 indicate that e.g. no item was found. An ID of @NULL is also used to indicate 709 the invisible root. Examples for this are wxDataViewModel::GetParent and 710 wxDataViewModel::GetChildren. 711 712 @library{wxadv} 713 @category{dvc} 714 */ 715 class wxDataViewItem 716 { 717 public: 718 //@{ 719 /** 720 Constructor. 721 */ 722 wxDataViewItem(); 723 wxDataViewItem(const wxDataViewItem& item); 724 explicit wxDataViewItem(void* id); 725 //@} 726 727 /** 728 Returns the ID. 729 */ 730 void* GetID() const; 731 732 /** 733 Returns @true if the ID is not @NULL. 734 */ 735 bool IsOk() const; 736 }; 737 738 739 // ---------------------------------------------------------------------------- 740 // wxDataViewCtrl flags 741 // ---------------------------------------------------------------------------- 742 743 // size of a wxDataViewRenderer without contents: 744 #define wxDVC_DEFAULT_RENDERER_SIZE 20 745 746 // the default width of new (text) columns: 747 #define wxDVC_DEFAULT_WIDTH 80 748 749 // the default width of new toggle columns: 750 #define wxDVC_TOGGLE_DEFAULT_WIDTH 30 751 752 // the default minimal width of the columns: 753 #define wxDVC_DEFAULT_MINWIDTH 30 754 755 // The default alignment of wxDataViewRenderers is to take 756 // the alignment from the column it owns. 757 #define wxDVR_DEFAULT_ALIGNMENT -1 758 759 #define wxDV_SINGLE 0x0000 // for convenience 760 #define wxDV_MULTIPLE 0x0001 // can select multiple items 761 762 #define wxDV_NO_HEADER 0x0002 // column titles not visible 763 #define wxDV_HORIZ_RULES 0x0004 // light horizontal rules between rows 764 #define wxDV_VERT_RULES 0x0008 // light vertical rules between columns 765 766 #define wxDV_ROW_LINES 0x0010 // alternating colour in rows 767 #define wxDV_VARIABLE_LINE_HEIGHT 0x0020 // variable line height 768 769 // events 770 771 wxEventType wxEVT_DATAVIEW_SELECTION_CHANGED; 772 773 wxEventType wxEVT_DATAVIEW_ITEM_ACTIVATED; 774 wxEventType wxEVT_DATAVIEW_ITEM_COLLAPSING; 775 wxEventType wxEVT_DATAVIEW_ITEM_COLLAPSED; 776 wxEventType wxEVT_DATAVIEW_ITEM_EXPANDING; 777 wxEventType wxEVT_DATAVIEW_ITEM_EXPANDED; 778 wxEventType wxEVT_DATAVIEW_ITEM_START_EDITING; 779 wxEventType wxEVT_DATAVIEW_ITEM_EDITING_STARTED; 780 wxEventType wxEVT_DATAVIEW_ITEM_EDITING_DONE; 781 wxEventType wxEVT_DATAVIEW_ITEM_VALUE_CHANGED; 782 783 wxEventType wxEVT_DATAVIEW_ITEM_CONTEXT_MENU; 784 785 wxEventType wxEVT_DATAVIEW_COLUMN_HEADER_CLICK; 786 wxEventType wxEVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK; 787 wxEventType wxEVT_DATAVIEW_COLUMN_SORTED; 788 wxEventType wxEVT_DATAVIEW_COLUMN_REORDERED; 789 wxEventType wxEVT_DATAVIEW_CACHE_HINT; 790 791 wxEventType wxEVT_DATAVIEW_ITEM_BEGIN_DRAG; 792 wxEventType wxEVT_DATAVIEW_ITEM_DROP_POSSIBLE; 793 wxEventType wxEVT_DATAVIEW_ITEM_DROP; 794 795 /** 796 @class wxDataViewCtrl 797 798 wxDataViewCtrl is a control to display data either in a tree like fashion or 799 in a tabular form or both. 800 801 If you only need to display a simple tree structure with an API more like the 802 older wxTreeCtrl class, then the specialized wxDataViewTreeCtrl can be used. 803 Likewise, if you only want to display simple table structure you can use 804 the specialized wxDataViewListCtrl class. Both wxDataViewTreeCtrl and 805 wxDataViewListCtrl can be used without defining your own wxDataViewModel. 806 807 A wxDataViewItem is used to represent a (visible) item in the control. 808 809 Unlike wxListCtrl, wxDataViewCtrl doesn't get its data from the user through 810 virtual functions or by setting it directly. Instead you need to write your own 811 wxDataViewModel and associate it with this control. 812 Then you need to add a number of wxDataViewColumn to this control to define 813 what each column shall display. Each wxDataViewColumn in turn owns 1 instance 814 of a wxDataViewRenderer to render its cells. 815 816 A number of standard renderers for rendering text, dates, images, toggle, 817 a progress bar etc. are provided. Additionally, the user can write custom 818 renderers deriving from wxDataViewCustomRenderer for displaying anything. 819 820 All data transfer from the control to the model and the user code is done 821 through wxVariant which can be extended to support more data formats as necessary. 822 Accordingly, all type information uses the strings returned from wxVariant::GetType. 823 824 @beginStyleTable 825 @style{wxDV_SINGLE} 826 Single selection mode. This is the default. 827 @style{wxDV_MULTIPLE} 828 Multiple selection mode. 829 @style{wxDV_ROW_LINES} 830 Use alternating colours for rows if supported by platform and theme. 831 Currently only supported by the native GTK and OS X implementations 832 but not by the generic one. 833 @style{wxDV_HORIZ_RULES} 834 Display the separator lines between rows. 835 @style{wxDV_VERT_RULES} 836 Display the separator lines between columns. 837 @style{wxDV_VARIABLE_LINE_HEIGHT} 838 Allow variable line heights. 839 This can be inefficient when displaying large number of items. 840 @style{wxDV_NO_HEADER} 841 Do not show column headers (which are shown by default). 842 @endStyleTable 843 844 @beginEventEmissionTable{wxDataViewEvent} 845 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)} 846 Process a @c wxEVT_DATAVIEW_SELECTION_CHANGED event. 847 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)} 848 Process a @c wxEVT_DATAVIEW_ITEM_ACTIVATED event. This event 849 is triggered by double clicking an item or pressing some special key 850 (usually "Enter") when it is focused. 851 @event{EVT_DATAVIEW_ITEM_START_EDITING(id, func)} 852 Process a @c wxEVT_DATAVIEW_ITEM_START_EDITING event. This 853 event can be vetoed in order to prevent editing on an item by item 854 basis. 855 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)} 856 Process a @c wxEVT_DATAVIEW_ITEM_EDITING_STARTED event. 857 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)} 858 Process a @c wxEVT_DATAVIEW_ITEM_EDITING_DONE event. 859 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)} 860 Process a @c wxEVT_DATAVIEW_ITEM_COLLAPSING event. 861 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)} 862 Process a @c wxEVT_DATAVIEW_ITEM_COLLAPSED event. 863 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)} 864 Process a @c wxEVT_DATAVIEW_ITEM_EXPANDING event. 865 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)} 866 Process a @c wxEVT_DATAVIEW_ITEM_EXPANDED event. 867 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)} 868 Process a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event. 869 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)} 870 Process a @c wxEVT_DATAVIEW_ITEM_CONTEXT_MENU event 871 generated when the user right clicks inside the control. Notice that 872 this menu is generated even if the click didn't occur on any valid 873 item, in this case wxDataViewEvent::GetItem() simply returns an 874 invalid item. 875 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)} 876 Process a @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICK event. 877 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)} 878 Process a @c wxEVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK event. 879 Notice that currently this event is not generated in the native OS X 880 versions of the control. 881 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)} 882 Process a @c wxEVT_DATAVIEW_COLUMN_SORTED event. 883 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)} 884 Process a @c wxEVT_DATAVIEW_COLUMN_REORDERED event. 885 @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)} 886 Process a @c wxEVT_DATAVIEW_ITEM_BEGIN_DRAG event. 887 @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)} 888 Process a @c wxEVT_DATAVIEW_ITEM_DROP_POSSIBLE event. 889 @event{EVT_DATAVIEW_ITEM_DROP(id, func)} 890 Process a @c wxEVT_DATAVIEW_ITEM_DROP event. 891 @endEventTable 892 893 Notice that this control doesn't allow to process generic mouse events such 894 as @c wxEVT_LEFT_DOWN in all ports (notably it doesn't work in wxGTK). If 895 you need to handle any mouse events not covered by the ones above, consider 896 using a custom renderer for the cells that must handle them. 897 898 @library{wxadv} 899 @category{ctrl,dvc} 900 @appearance{dataviewctrl} 901 */ 902 class wxDataViewCtrl : public wxControl 903 { 904 public: 905 /** 906 Default Constructor. 907 */ 908 wxDataViewCtrl(); 909 910 /** 911 Constructor. Calls Create(). 912 */ 913 wxDataViewCtrl(wxWindow* parent, wxWindowID id, 914 const wxPoint& pos = wxDefaultPosition, 915 const wxSize& size = wxDefaultSize, 916 long style = 0, 917 const wxValidator& validator = wxDefaultValidator, 918 const wxString& name = wxDataViewCtrlNameStr); 919 920 /** 921 Destructor. 922 */ 923 virtual ~wxDataViewCtrl(); 924 925 /** 926 Create the control. Useful for two step creation. 927 */ 928 bool Create(wxWindow* parent, wxWindowID id, 929 const wxPoint& pos = wxDefaultPosition, 930 const wxSize& size = wxDefaultSize, 931 long style = 0, 932 const wxValidator& validator = wxDefaultValidator, 933 const wxString& name = wxDataViewCtrlNameStr); 934 935 /** 936 Appends a wxDataViewColumn to the control. Returns @true on success. 937 938 Note that there is a number of short cut methods which implicitly create 939 a wxDataViewColumn and a wxDataViewRenderer for it (see below). 940 */ 941 virtual bool AppendColumn(wxDataViewColumn* col); 942 943 /** 944 Prepends a wxDataViewColumn to the control. Returns @true on success. 945 946 Note that there is a number of short cut methods which implicitly create 947 a wxDataViewColumn and a wxDataViewRenderer for it. 948 */ 949 virtual bool PrependColumn(wxDataViewColumn* col); 950 951 /** 952 Inserts a wxDataViewColumn to the control. Returns @true on success. 953 */ 954 virtual bool InsertColumn(unsigned int pos, wxDataViewColumn* col); 955 956 //@{ 957 /** 958 Appends a column for rendering a bitmap. Returns the wxDataViewColumn 959 created in the function or @NULL on failure. 960 */ 961 wxDataViewColumn* AppendBitmapColumn(const wxString& label, 962 unsigned int model_column, 963 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 964 int width = -1, 965 wxAlignment align = wxALIGN_CENTER, 966 int flags = wxDATAVIEW_COL_RESIZABLE); 967 wxDataViewColumn* AppendBitmapColumn(const wxBitmap& label, 968 unsigned int model_column, 969 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 970 int width = -1, 971 wxAlignment align = wxALIGN_CENTER, 972 int flags = wxDATAVIEW_COL_RESIZABLE); 973 //@} 974 975 //@{ 976 /** 977 Prepends a column for rendering a bitmap. Returns the wxDataViewColumn 978 created in the function or @NULL on failure. 979 */ 980 wxDataViewColumn* PrependBitmapColumn(const wxString& label, 981 unsigned int model_column, 982 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 983 int width = -1, 984 wxAlignment align = wxALIGN_CENTER, 985 int flags = wxDATAVIEW_COL_RESIZABLE); 986 wxDataViewColumn* PrependBitmapColumn(const wxBitmap& label, 987 unsigned int model_column, 988 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 989 int width = -1, 990 wxAlignment align = wxALIGN_CENTER, 991 int flags = wxDATAVIEW_COL_RESIZABLE); 992 //@} 993 994 //@{ 995 /** 996 Appends a column for rendering a date. Returns the wxDataViewColumn 997 created in the function or @NULL on failure. 998 999 @note The @a align parameter is applied to both the column header and 1000 the column renderer. 1001 */ 1002 wxDataViewColumn* AppendDateColumn(const wxString& label, 1003 unsigned int model_column, 1004 wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, 1005 int width = -1, 1006 wxAlignment align = wxALIGN_NOT, 1007 int flags = wxDATAVIEW_COL_RESIZABLE); 1008 wxDataViewColumn* AppendDateColumn(const wxBitmap& label, 1009 unsigned int model_column, 1010 wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, 1011 int width = -1, 1012 wxAlignment align = wxALIGN_NOT, 1013 int flags = wxDATAVIEW_COL_RESIZABLE); 1014 //@} 1015 1016 //@{ 1017 /** 1018 Prepends a column for rendering a date. Returns the wxDataViewColumn 1019 created in the function or @NULL on failure. 1020 1021 @note The @a align parameter is applied to both the column header and 1022 the column renderer. 1023 */ 1024 wxDataViewColumn* PrependDateColumn(const wxString& label, 1025 unsigned int model_column, 1026 wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, 1027 int width = -1, 1028 wxAlignment align = wxALIGN_NOT, 1029 int flags = wxDATAVIEW_COL_RESIZABLE); 1030 wxDataViewColumn* PrependDateColumn(const wxBitmap& label, 1031 unsigned int model_column, 1032 wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, 1033 int width = -1, 1034 wxAlignment align = wxALIGN_NOT, 1035 int flags = wxDATAVIEW_COL_RESIZABLE); 1036 //@} 1037 1038 //@{ 1039 /** 1040 Appends a column for rendering text with an icon. Returns the wxDataViewColumn 1041 created in the function or @NULL on failure. 1042 This method uses the wxDataViewIconTextRenderer class. 1043 1044 @note The @a align parameter is applied to both the column header and 1045 the column renderer. 1046 */ 1047 wxDataViewColumn* AppendIconTextColumn(const wxString& label, 1048 unsigned int model_column, 1049 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1050 int width = -1, 1051 wxAlignment align = wxALIGN_NOT, 1052 int flags = wxDATAVIEW_COL_RESIZABLE); 1053 wxDataViewColumn* AppendIconTextColumn(const wxBitmap& label, 1054 unsigned int model_column, 1055 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1056 int width = -1, 1057 wxAlignment align = wxALIGN_NOT, 1058 int flags = wxDATAVIEW_COL_RESIZABLE); 1059 //@} 1060 1061 //@{ 1062 /** 1063 Prepends a column for rendering text with an icon. Returns the wxDataViewColumn 1064 created in the function or @NULL on failure. 1065 This method uses the wxDataViewIconTextRenderer class. 1066 1067 @note The @a align parameter is applied to both the column header and 1068 the column renderer. 1069 */ 1070 wxDataViewColumn* PrependIconTextColumn(const wxString& label, 1071 unsigned int model_column, 1072 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1073 int width = -1, 1074 wxAlignment align = wxALIGN_NOT, 1075 int flags = wxDATAVIEW_COL_RESIZABLE); 1076 wxDataViewColumn* PrependIconTextColumn(const wxBitmap& label, 1077 unsigned int model_column, 1078 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1079 int width = -1, 1080 wxAlignment align = wxALIGN_NOT, 1081 int flags = wxDATAVIEW_COL_RESIZABLE); 1082 //@} 1083 1084 //@{ 1085 /** 1086 Appends a column for rendering a progress indicator. Returns the 1087 wxDataViewColumn created in the function or @NULL on failure. 1088 1089 @note The @a align parameter is applied to both the column header and 1090 the column renderer. 1091 */ 1092 wxDataViewColumn* AppendProgressColumn(const wxString& label, 1093 unsigned int model_column, 1094 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1095 int width = 80, 1096 wxAlignment align = wxALIGN_CENTER, 1097 int flags = wxDATAVIEW_COL_RESIZABLE); 1098 wxDataViewColumn* AppendProgressColumn(const wxBitmap& label, 1099 unsigned int model_column, 1100 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1101 int width = 80, 1102 wxAlignment align = wxALIGN_CENTER, 1103 int flags = wxDATAVIEW_COL_RESIZABLE); 1104 //@} 1105 1106 //@{ 1107 /** 1108 Prepends a column for rendering a progress indicator. Returns the 1109 wxDataViewColumn created in the function or @NULL on failure. 1110 1111 @note The @a align parameter is applied to both the column header and 1112 the column renderer. 1113 */ 1114 wxDataViewColumn* PrependProgressColumn(const wxString& label, 1115 unsigned int model_column, 1116 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1117 int width = 80, 1118 wxAlignment align = wxALIGN_CENTER, 1119 int flags = wxDATAVIEW_COL_RESIZABLE); 1120 wxDataViewColumn* PrependProgressColumn(const wxBitmap& label, 1121 unsigned int model_column, 1122 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1123 int width = 80, 1124 wxAlignment align = wxALIGN_CENTER, 1125 int flags = wxDATAVIEW_COL_RESIZABLE); 1126 //@} 1127 1128 //@{ 1129 /** 1130 Appends a column for rendering text. Returns the wxDataViewColumn 1131 created in the function or @NULL on failure. 1132 1133 @note The @a align parameter is applied to both the column header and 1134 the column renderer. 1135 */ 1136 wxDataViewColumn* AppendTextColumn(const wxString& label, 1137 unsigned int model_column, 1138 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1139 int width = -1, 1140 wxAlignment align = wxALIGN_NOT, 1141 int flags = wxDATAVIEW_COL_RESIZABLE); 1142 wxDataViewColumn* AppendTextColumn(const wxBitmap& label, 1143 unsigned int model_column, 1144 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1145 int width = -1, 1146 wxAlignment align = wxALIGN_NOT, 1147 int flags = wxDATAVIEW_COL_RESIZABLE); 1148 //@} 1149 1150 //@{ 1151 /** 1152 Prepends a column for rendering text. Returns the wxDataViewColumn 1153 created in the function or @NULL on failure. 1154 1155 @note The @a align parameter is applied to both the column header and 1156 the column renderer. 1157 */ 1158 wxDataViewColumn* PrependTextColumn(const wxString& label, 1159 unsigned int model_column, 1160 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1161 int width = -1, 1162 wxAlignment align = wxALIGN_NOT, 1163 int flags = wxDATAVIEW_COL_RESIZABLE); 1164 wxDataViewColumn* PrependTextColumn(const wxBitmap& label, 1165 unsigned int model_column, 1166 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1167 int width = -1, 1168 wxAlignment align = wxALIGN_NOT, 1169 int flags = wxDATAVIEW_COL_RESIZABLE); 1170 //@} 1171 1172 //@{ 1173 /** 1174 Appends a column for rendering a toggle. Returns the wxDataViewColumn 1175 created in the function or @NULL on failure. 1176 1177 @note The @a align parameter is applied to both the column header and 1178 the column renderer. 1179 */ 1180 wxDataViewColumn* AppendToggleColumn(const wxString& label, 1181 unsigned int model_column, 1182 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1183 int width = 30, 1184 wxAlignment align = wxALIGN_CENTER, 1185 int flags = wxDATAVIEW_COL_RESIZABLE); 1186 wxDataViewColumn* AppendToggleColumn(const wxBitmap& label, 1187 unsigned int model_column, 1188 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1189 int width = 30, 1190 wxAlignment align = wxALIGN_CENTER, 1191 int flags = wxDATAVIEW_COL_RESIZABLE); 1192 //@} 1193 1194 //@{ 1195 /** 1196 Prepends a column for rendering a toggle. Returns the wxDataViewColumn 1197 created in the function or @NULL on failure. 1198 1199 @note The @a align parameter is applied to both the column header and 1200 the column renderer. 1201 */ 1202 wxDataViewColumn* PrependToggleColumn(const wxString& label, 1203 unsigned int model_column, 1204 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1205 int width = 30, 1206 wxAlignment align = wxALIGN_CENTER, 1207 int flags = wxDATAVIEW_COL_RESIZABLE); 1208 wxDataViewColumn* PrependToggleColumn(const wxBitmap& label, 1209 unsigned int model_column, 1210 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1211 int width = 30, 1212 wxAlignment align = wxALIGN_CENTER, 1213 int flags = wxDATAVIEW_COL_RESIZABLE); 1214 //@} 1215 1216 /** 1217 Associates a wxDataViewModel with the control. 1218 This increases the reference count of the model by 1. 1219 */ 1220 virtual bool AssociateModel(wxDataViewModel* model); 1221 1222 /** 1223 Removes all columns. 1224 */ 1225 virtual bool ClearColumns(); 1226 1227 /** 1228 Collapses the item. 1229 */ 1230 virtual void Collapse(const wxDataViewItem& item); 1231 1232 /** 1233 Deletes given column. 1234 */ 1235 virtual bool DeleteColumn(wxDataViewColumn* column); 1236 1237 /** 1238 Programmatically starts editing given cell of @a item. 1239 1240 Doesn't do anything if the item or this column is not editable. 1241 1242 @note Currently not implemented in wxOSX/Carbon. 1243 1244 @since 2.9.4 1245 */ 1246 virtual void EditItem(const wxDataViewItem& item, const wxDataViewColumn *column); 1247 1248 /** 1249 Enable drag operations using the given @a format. 1250 */ 1251 virtual bool EnableDragSource( const wxDataFormat &format ); 1252 1253 /** 1254 Enable drop operations using the given @a format. 1255 */ 1256 virtual bool EnableDropTarget( const wxDataFormat &format ); 1257 1258 /** 1259 Call this to ensure that the given item is visible. 1260 */ 1261 virtual void EnsureVisible(const wxDataViewItem& item, 1262 const wxDataViewColumn* column = NULL); 1263 1264 /** 1265 Expands the item. 1266 */ 1267 virtual void Expand(const wxDataViewItem& item); 1268 1269 /** 1270 Expands all ancestors of the @a item. This method also 1271 ensures that the item itself as well as all ancestor 1272 items have been read from the model by the control. 1273 */ 1274 virtual void ExpandAncestors( const wxDataViewItem & item ); 1275 1276 /** 1277 Returns pointer to the column. @a pos refers to the position in the 1278 control which may change after reordering columns by the user. 1279 */ 1280 virtual wxDataViewColumn* GetColumn(unsigned int pos) const; 1281 1282 /** 1283 Returns the number of columns. 1284 */ 1285 virtual unsigned int GetColumnCount() const; 1286 1287 /** 1288 Returns the position of the column or -1 if not found in the control. 1289 */ 1290 virtual int GetColumnPosition(const wxDataViewColumn* column) const; 1291 1292 /** 1293 Returns column containing the expanders. 1294 */ 1295 wxDataViewColumn* GetExpanderColumn() const; 1296 1297 /** 1298 Returns the currently focused item. 1299 1300 This is the item that the keyboard commands apply to. It may be invalid 1301 if there is no focus currently. 1302 1303 This method is mostly useful for the controls with @c wxDV_MULTIPLE 1304 style as in the case of single selection it returns the same thing as 1305 GetSelection(). 1306 1307 Notice that under all platforms except Mac OS X the currently focused 1308 item may be selected or not but under OS X the current item is always 1309 selected. 1310 1311 @see SetCurrentItem(), GetCurrentColumn() 1312 1313 @since 2.9.2 1314 */ 1315 wxDataViewItem GetCurrentItem() const; 1316 1317 /** 1318 Returns the column that currently has focus. 1319 1320 If the focus is set to individual cell within the currently focused 1321 item (as opposed to being on the item as a whole), then this is the 1322 column that the focus is on. 1323 1324 Returns NULL if no column currently has focus. 1325 1326 @see GetCurrentItem() 1327 1328 @since 2.9.4 1329 */ 1330 wxDataViewColumn *GetCurrentColumn() const; 1331 1332 /** 1333 Returns indentation. 1334 */ 1335 int GetIndent() const; 1336 1337 /** 1338 Returns item rectangle. 1339 1340 This method is currently not implemented at all in wxGTK and only 1341 implemented for non-@NULL @a col argument in wxOSX. It is fully 1342 implemented in the generic version of the control. 1343 1344 @param item 1345 A valid item. 1346 @param col 1347 If non-@NULL, the rectangle returned corresponds to the 1348 intersection of the item with the specified column. If @NULL, the 1349 rectangle spans all the columns. 1350 */ 1351 virtual wxRect GetItemRect(const wxDataViewItem& item, 1352 const wxDataViewColumn* col = NULL) const; 1353 1354 /** 1355 Returns pointer to the data model associated with the control (if any). 1356 */ 1357 wxDataViewModel* GetModel(); 1358 1359 /** 1360 Returns the number of currently selected items. 1361 1362 This method may be called for both the controls with single and 1363 multiple selections and returns the number of selected item, possibly 1364 0, in any case. 1365 1366 @since 2.9.3 1367 */ 1368 virtual int GetSelectedItemsCount() const; 1369 1370 /** 1371 Returns first selected item or an invalid item if none is selected. 1372 1373 This method may be called for both the controls with single and 1374 multiple selections but returns an invalid item if more than one item 1375 is selected in the latter case, use HasSelection() to determine if 1376 there are any selected items when using multiple selection. 1377 */ 1378 virtual wxDataViewItem GetSelection() const; 1379 1380 /** 1381 Fills @a sel with currently selected items and returns their number. 1382 1383 This method may be called for both the controls with single and 1384 multiple selections. In the single selection case it returns the array 1385 with at most one element in it. 1386 1387 @see GetSelectedItemsCount() 1388 */ 1389 virtual int GetSelections(wxDataViewItemArray& sel) const; 1390 1391 /** 1392 Returns the wxDataViewColumn currently responsible for sorting 1393 or @NULL if none has been selected. 1394 */ 1395 virtual wxDataViewColumn* GetSortingColumn() const; 1396 1397 /** 1398 Returns true if any items are currently selected. 1399 1400 This method may be called for both the controls with single and 1401 multiple selections. 1402 1403 Calling this method is equivalent to calling GetSelectedItemsCount() 1404 and comparing its result with 0 but is more clear and might also be 1405 implemented more efficiently in the future. 1406 1407 @since 2.9.3 1408 */ 1409 bool HasSelection() const; 1410 1411 /** 1412 Hittest. 1413 */ 1414 virtual void HitTest(const wxPoint& point, wxDataViewItem& item, 1415 wxDataViewColumn*& col) const; 1416 1417 /** 1418 Return @true if the item is expanded. 1419 */ 1420 virtual bool IsExpanded(const wxDataViewItem& item) const; 1421 1422 /** 1423 Return @true if the item is selected. 1424 */ 1425 virtual bool IsSelected(const wxDataViewItem& item) const; 1426 1427 /** 1428 Select the given item. 1429 1430 In single selection mode this changes the (unique) currently selected 1431 item. In multi selection mode, the @a item is selected and the 1432 previously selected items remain selected. 1433 */ 1434 virtual void Select(const wxDataViewItem& item); 1435 1436 /** 1437 Select all items. 1438 */ 1439 virtual void SelectAll(); 1440 1441 /** 1442 Set which column shall contain the tree-like expanders. 1443 */ 1444 void SetExpanderColumn(wxDataViewColumn* col); 1445 1446 /** 1447 Changes the currently focused item. 1448 1449 The @a item parameter must be valid, there is no way to remove the 1450 current item from the control. 1451 1452 In single selection mode, calling this method is the same as calling 1453 Select() and is thus not very useful. In multiple selection mode this 1454 method only moves the current item however without changing the 1455 selection except under OS X where the current item is always selected, 1456 so calling SetCurrentItem() selects @a item if it hadn't been selected 1457 before. 1458 1459 @see GetCurrentItem() 1460 1461 @since 2.9.2 1462 */ 1463 void SetCurrentItem(const wxDataViewItem& item); 1464 1465 /** 1466 Sets the indentation. 1467 */ 1468 void SetIndent(int indent); 1469 1470 /** 1471 Sets the selection to the array of wxDataViewItems. 1472 */ 1473 virtual void SetSelections(const wxDataViewItemArray& sel); 1474 1475 /** 1476 Unselect the given item. 1477 */ 1478 virtual void Unselect(const wxDataViewItem& item); 1479 1480 /** 1481 Unselect all item. 1482 This method only has effect if multiple selections are allowed. 1483 */ 1484 virtual void UnselectAll(); 1485 1486 /** 1487 Sets the row height. 1488 1489 This function can only be used when all rows have the same height, i.e. 1490 when wxDV_VARIABLE_LINE_HEIGHT flag is not used. 1491 1492 Currently this is implemented in the generic and native GTK versions 1493 only and nothing is done (and @false returned) when using OS X port. 1494 1495 Also notice that this method can only be used to increase the row 1496 height compared with the default one (as determined by the return value 1497 of wxDataViewRenderer::GetSize()), if it is set to a too small value 1498 then the minimum required by the renderers will be used. 1499 1500 @return @true if the line height was changed or @false otherwise. 1501 1502 @since 2.9.2 1503 */ 1504 virtual bool SetRowHeight(int rowHeight); 1505 }; 1506 1507 1508 1509 /** 1510 @class wxDataViewModelNotifier 1511 1512 A wxDataViewModelNotifier instance is owned by a wxDataViewModel and mirrors 1513 its notification interface. 1514 See the documentation of that class for further information. 1515 1516 @library{wxadv} 1517 @category{dvc} 1518 */ 1519 class wxDataViewModelNotifier 1520 { 1521 public: 1522 /** 1523 Constructor. 1524 */ 1525 wxDataViewModelNotifier(); 1526 1527 /** 1528 Destructor. 1529 */ 1530 virtual ~wxDataViewModelNotifier(); 1531 1532 /** 1533 Called by owning model. 1534 */ 1535 virtual bool Cleared() = 0; 1536 1537 /** 1538 Get owning wxDataViewModel. 1539 */ 1540 wxDataViewModel* GetOwner() const; 1541 1542 /** 1543 Called by owning model. 1544 1545 @return Always return @true from this function in derived classes. 1546 */ 1547 virtual bool ItemAdded(const wxDataViewItem& parent, 1548 const wxDataViewItem& item) = 0; 1549 1550 /** 1551 Called by owning model. 1552 1553 @return Always return @true from this function in derived classes. 1554 */ 1555 virtual bool ItemChanged(const wxDataViewItem& item) = 0; 1556 1557 /** 1558 Called by owning model. 1559 1560 @return Always return @true from this function in derived classes. 1561 */ 1562 virtual bool ItemDeleted(const wxDataViewItem& parent, 1563 const wxDataViewItem& item) = 0; 1564 1565 /** 1566 Called by owning model. 1567 1568 @return Always return @true from this function in derived classes. 1569 */ 1570 virtual bool ItemsAdded(const wxDataViewItem& parent, 1571 const wxDataViewItemArray& items); 1572 1573 /** 1574 Called by owning model. 1575 1576 @return Always return @true from this function in derived classes. 1577 */ 1578 virtual bool ItemsChanged(const wxDataViewItemArray& items); 1579 1580 /** 1581 Called by owning model. 1582 1583 @return Always return @true from this function in derived classes. 1584 */ 1585 virtual bool ItemsDeleted(const wxDataViewItem& parent, 1586 const wxDataViewItemArray& items); 1587 1588 /** 1589 Called by owning model. 1590 */ 1591 virtual void Resort() = 0; 1592 1593 /** 1594 Set owner of this notifier. Used internally. 1595 */ 1596 void SetOwner(wxDataViewModel* owner); 1597 1598 /** 1599 Called by owning model. 1600 1601 @return Always return @true from this function in derived classes. 1602 */ 1603 virtual bool ValueChanged(const wxDataViewItem& item, unsigned int col) = 0; 1604 }; 1605 1606 1607 /** 1608 The mode of a data-view cell; see wxDataViewRenderer for more info. 1609 */ 1610 enum wxDataViewCellMode 1611 { 1612 /** 1613 The cell only displays information and cannot be manipulated or 1614 otherwise interacted with in any way. 1615 1616 Note that this doesn't mean that the row being drawn can't be selected, 1617 just that a particular element of it cannot be individually modified. 1618 */ 1619 wxDATAVIEW_CELL_INERT, 1620 1621 /** 1622 Indicates that the cell can be @em activated by clicking it or using 1623 keyboard. 1624 1625 Activating a cell is an alternative to showing inline editor when the 1626 value can be edited in a simple way that doesn't warrant full editor 1627 control. The most typical use of cell activation is toggling the 1628 checkbox in wxDataViewToggleRenderer; others would be e.g. an embedded 1629 volume slider or a five-star rating column. 1630 1631 The exact means of activating a cell are platform-dependent, but they 1632 are usually similar to those used for inline editing of values. 1633 Typically, a cell would be activated by Space or Enter keys or by left 1634 mouse click. 1635 1636 @note Do not confuse this with item activation in wxDataViewCtrl 1637 and the wxEVT_DATAVIEW_ITEM_ACTIVATED event. That one is 1638 used for activating the item (or, to put it differently, the 1639 entire row) similarly to analogous messages in wxTreeCtrl and 1640 wxListCtrl, and the effect differs (play a song, open a file 1641 etc.). Cell activation, on the other hand, is all about 1642 interacting with the individual cell. 1643 1644 @see wxDataViewCustomRenderer::ActivateCell() 1645 */ 1646 wxDATAVIEW_CELL_ACTIVATABLE, 1647 1648 /** 1649 Indicates that the user can edit the data in-place in an inline editor 1650 control that will show up when the user wants to edit the cell. 1651 1652 A typical example of this behaviour is changing the filename in a file 1653 managers. 1654 1655 Editing is typically triggered by slowly double-clicking the cell or by 1656 a platform-dependent keyboard shortcut (F2 is typical on Windows, Space 1657 and/or Enter is common elsewhere and supported on Windows too). 1658 1659 @see wxDataViewCustomRenderer::CreateEditorCtrl() 1660 */ 1661 wxDATAVIEW_CELL_EDITABLE 1662 }; 1663 1664 /** 1665 The values of this enum controls how a wxDataViewRenderer should display 1666 its contents in a cell. 1667 */ 1668 enum wxDataViewCellRenderState 1669 { 1670 wxDATAVIEW_CELL_SELECTED = 1, 1671 wxDATAVIEW_CELL_PRELIT = 2, 1672 wxDATAVIEW_CELL_INSENSITIVE = 4, 1673 wxDATAVIEW_CELL_FOCUSED = 8 1674 }; 1675 1676 /** 1677 @class wxDataViewRenderer 1678 1679 This class is used by wxDataViewCtrl to render the individual cells. 1680 One instance of a renderer class is owned by a wxDataViewColumn. 1681 There is a number of ready-to-use renderers provided: 1682 - wxDataViewTextRenderer, 1683 - wxDataViewIconTextRenderer, 1684 - wxDataViewToggleRenderer, 1685 - wxDataViewProgressRenderer, 1686 - wxDataViewBitmapRenderer, 1687 - wxDataViewDateRenderer, 1688 - wxDataViewSpinRenderer. 1689 - wxDataViewChoiceRenderer. 1690 1691 Additionally, the user can write their own renderers by deriving from 1692 wxDataViewCustomRenderer. 1693 1694 The ::wxDataViewCellMode and ::wxDataViewCellRenderState flags accepted 1695 by the constructors respectively controls what actions the cell data allows 1696 and how the renderer should display its contents in a cell. 1697 1698 @library{wxadv} 1699 @category{dvc} 1700 */ 1701 class wxDataViewRenderer : public wxObject 1702 { 1703 public: 1704 /** 1705 Constructor. 1706 */ 1707 wxDataViewRenderer(const wxString& varianttype, 1708 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1709 int align = wxDVR_DEFAULT_ALIGNMENT ); 1710 1711 /** 1712 Enable or disable replacing parts of the item text with ellipsis to 1713 make it fit the column width. 1714 1715 This method only makes sense for the renderers working with text, such 1716 as wxDataViewTextRenderer or wxDataViewIconTextRenderer. 1717 1718 By default wxELLIPSIZE_MIDDLE is used. 1719 1720 @param mode 1721 Ellipsization mode, use wxELLIPSIZE_NONE to disable. 1722 1723 @since 2.9.1 1724 */ 1725 void EnableEllipsize(wxEllipsizeMode mode = wxELLIPSIZE_MIDDLE); 1726 1727 /** 1728 Disable replacing parts of the item text with ellipsis. 1729 1730 If ellipsizing is disabled, the string will be truncated if it doesn't 1731 fit. 1732 1733 This is the same as @code EnableEllipsize(wxELLIPSIZE_NONE) @endcode. 1734 1735 @since 2.9.1 1736 */ 1737 void DisableEllipsize(); 1738 1739 /** 1740 Returns the alignment. See SetAlignment() 1741 */ 1742 virtual int GetAlignment() const; 1743 1744 /** 1745 Returns the ellipsize mode used by the renderer. 1746 1747 If the return value is wxELLIPSIZE_NONE, the text is simply truncated 1748 if it doesn't fit. 1749 1750 @see EnableEllipsize() 1751 */ 1752 wxEllipsizeMode GetEllipsizeMode() const; 1753 1754 /** 1755 Returns the cell mode. 1756 */ 1757 virtual wxDataViewCellMode GetMode() const; 1758 1759 /** 1760 Returns pointer to the owning wxDataViewColumn. 1761 */ 1762 wxDataViewColumn* GetOwner() const; 1763 1764 /** 1765 This methods retrieves the value from the renderer in order to 1766 transfer the value back to the data model. 1767 1768 Returns @false on failure. 1769 */ 1770 virtual bool GetValue(wxVariant& value) const = 0; 1771 1772 /** 1773 Returns a string with the type of the wxVariant supported by this renderer. 1774 */ 1775 wxString GetVariantType() const; 1776 1777 /** 1778 Sets the alignment of the renderer's content. 1779 The default value of @c wxDVR_DEFAULT_ALIGMENT indicates that the content 1780 should have the same alignment as the column header. 1781 1782 The method is not implemented under OS X and the renderer always aligns 1783 its contents as the column header on that platform. The other platforms 1784 support both vertical and horizontal alignment. 1785 */ 1786 virtual void SetAlignment( int align ); 1787 /** 1788 Sets the owning wxDataViewColumn. 1789 This is usually called from within wxDataViewColumn. 1790 */ 1791 void SetOwner(wxDataViewColumn* owner); 1792 1793 /** 1794 Set the value of the renderer (and thus its cell) to @a value. 1795 The internal code will then render this cell with this data. 1796 */ 1797 virtual bool SetValue(const wxVariant& value) = 0; 1798 1799 /** 1800 Before data is committed to the data model, it is passed to this 1801 method where it can be checked for validity. This can also be 1802 used for checking a valid range or limiting the user input in 1803 a certain aspect (e.g. max number of characters or only alphanumeric 1804 input, ASCII only etc.). Return @false if the value is not valid. 1805 1806 Please note that due to implementation limitations, this validation 1807 is done after the editing control already is destroyed and the 1808 editing process finished. 1809 */ 1810 virtual bool Validate(wxVariant& value); 1811 1812 1813 virtual bool HasEditorCtrl() const; 1814 virtual wxWindow* CreateEditorCtrl(wxWindow * parent, 1815 wxRect labelRect, 1816 const wxVariant& value); 1817 virtual bool GetValueFromEditorCtrl(wxWindow * editor, 1818 wxVariant& value); 1819 virtual bool StartEditing( const wxDataViewItem &item, wxRect labelRect ); 1820 virtual void CancelEditing(); 1821 virtual bool FinishEditing(); 1822 wxWindow *GetEditorCtrl(); 1823 1824 protected: 1825 wxDataViewCtrl* GetView() const; 1826 }; 1827 1828 1829 1830 /** 1831 @class wxDataViewTextRenderer 1832 1833 wxDataViewTextRenderer is used for rendering text. 1834 It supports in-place editing if desired. 1835 1836 @library{wxadv} 1837 @category{dvc} 1838 */ 1839 class wxDataViewTextRenderer : public wxDataViewRenderer 1840 { 1841 public: 1842 /** 1843 The ctor. 1844 */ 1845 wxDataViewTextRenderer(const wxString& varianttype = "string", 1846 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1847 int align = wxDVR_DEFAULT_ALIGNMENT ); 1848 }; 1849 1850 1851 1852 /** 1853 @class wxDataViewIconTextRenderer 1854 1855 The wxDataViewIconTextRenderer class is used to display text with 1856 a small icon next to it as it is typically done in a file manager. 1857 1858 This classes uses the wxDataViewIconText helper class to store its data. 1859 wxDataViewIconText can be converted to and from a wxVariant using the left 1860 shift operator. 1861 1862 @library{wxadv} 1863 @category{dvc} 1864 */ 1865 class wxDataViewIconTextRenderer : public wxDataViewRenderer 1866 { 1867 public: 1868 /** 1869 The ctor. 1870 */ 1871 wxDataViewIconTextRenderer(const wxString& varianttype = "wxDataViewIconText", 1872 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1873 int align = wxDVR_DEFAULT_ALIGNMENT ); 1874 }; 1875 1876 1877 1878 /** 1879 @class wxDataViewProgressRenderer 1880 1881 This class is used by wxDataViewCtrl to render progress bars. 1882 1883 @library{wxadv} 1884 @category{dvc} 1885 */ 1886 class wxDataViewProgressRenderer : public wxDataViewRenderer 1887 { 1888 public: 1889 /** 1890 The ctor. 1891 */ 1892 wxDataViewProgressRenderer(const wxString& label = wxEmptyString, 1893 const wxString& varianttype = "long", 1894 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1895 int align = wxDVR_DEFAULT_ALIGNMENT ); 1896 }; 1897 1898 1899 1900 /** 1901 @class wxDataViewSpinRenderer 1902 1903 This is a specialized renderer for rendering integer values. 1904 It supports modifying the values in-place by using a wxSpinCtrl. 1905 The renderer only support variants of type @e long. 1906 1907 @library{wxadv} 1908 @category{dvc} 1909 */ 1910 class wxDataViewSpinRenderer : public wxDataViewCustomRenderer 1911 { 1912 public: 1913 /** 1914 Constructor. 1915 @a min and @a max indicate the minimum and maximum values for the wxSpinCtrl. 1916 */ 1917 wxDataViewSpinRenderer(int min, int max, 1918 wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE, 1919 int align = wxDVR_DEFAULT_ALIGNMENT); 1920 }; 1921 1922 1923 1924 /** 1925 @class wxDataViewToggleRenderer 1926 1927 This class is used by wxDataViewCtrl to render toggle controls. 1928 1929 @library{wxadv} 1930 @category{dvc} 1931 */ 1932 class wxDataViewToggleRenderer : public wxDataViewRenderer 1933 { 1934 public: 1935 /** 1936 The ctor. 1937 */ 1938 wxDataViewToggleRenderer(const wxString& varianttype = "bool", 1939 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 1940 int align = wxDVR_DEFAULT_ALIGNMENT); 1941 }; 1942 1943 1944 /** 1945 A wxDataViewCtrl renderer using wxChoice control and values of strings in 1946 it. 1947 1948 This class is used by wxDataViewCtrl to render choice controls. 1949 It stores a string so that SetValue() and GetValue() operate 1950 on a variant holding a string. 1951 1952 @see wxDataViewChoiceByIndexRenderer 1953 1954 @library{wxadv} 1955 @category{dvc} 1956 */ 1957 1958 class wxDataViewChoiceRenderer: public wxDataViewRenderer 1959 { 1960 public: 1961 /** 1962 The ctor. 1963 */ 1964 wxDataViewChoiceRenderer( const wxArrayString &choices, 1965 wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE, 1966 int alignment = wxDVR_DEFAULT_ALIGNMENT ); 1967 1968 /** 1969 Returns the choice referred to by index. 1970 */ 1971 wxString GetChoice(size_t index) const; 1972 1973 /** 1974 Returns all choices. 1975 */ 1976 const wxArrayString& GetChoices() const; 1977 }; 1978 1979 1980 /** 1981 A wxDataViewCtrl renderer using wxChoice control and indexes into it. 1982 1983 Unlike its base wxDataViewChoiceRenderer class, this one stores the choice 1984 index, i.e. an @c int, in the variant used by its SetValue() and 1985 GetValue(). 1986 1987 @library{wxadv} 1988 @category{dvc} 1989 */ 1990 class wxDataViewChoiceByIndexRenderer : public wxDataViewChoiceRenderer 1991 { 1992 public: 1993 /** 1994 The ctor. 1995 */ 1996 wxDataViewChoiceByIndexRenderer( const wxArrayString &choices, 1997 wxDataViewCellMode mode = wxDATAVIEW_CELL_EDITABLE, 1998 int alignment = wxDVR_DEFAULT_ALIGNMENT ); 1999 }; 2000 2001 2002 /** 2003 @class wxDataViewDateRenderer 2004 2005 This class is used by wxDataViewCtrl to render calendar controls. 2006 2007 @library{wxadv} 2008 @category{dvc} 2009 */ 2010 class wxDataViewDateRenderer : public wxDataViewRenderer 2011 { 2012 public: 2013 /** 2014 The ctor. 2015 */ 2016 wxDataViewDateRenderer(const wxString& varianttype = "datetime", 2017 wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, 2018 int align = wxDVR_DEFAULT_ALIGNMENT); 2019 }; 2020 2021 2022 2023 /** 2024 @class wxDataViewCustomRenderer 2025 2026 You need to derive a new class from wxDataViewCustomRenderer in 2027 order to write a new renderer. 2028 2029 You need to override at least wxDataViewRenderer::SetValue, wxDataViewRenderer::GetValue, 2030 wxDataViewCustomRenderer::GetSize and wxDataViewCustomRenderer::Render. 2031 2032 If you want your renderer to support in-place editing then you also need to override 2033 wxDataViewCustomRenderer::HasEditorCtrl, wxDataViewCustomRenderer::CreateEditorCtrl 2034 and wxDataViewCustomRenderer::GetValueFromEditorCtrl. 2035 2036 Note that a special event handler will be pushed onto that editor control 2037 which handles @e \<ENTER\> and focus out events in order to end the editing. 2038 2039 @library{wxadv} 2040 @category{dvc} 2041 */ 2042 class wxDataViewCustomRenderer : public wxDataViewRenderer 2043 { 2044 public: 2045 /** 2046 Constructor. 2047 */ 2048 wxDataViewCustomRenderer(const wxString& varianttype = "string", 2049 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 2050 int align = wxDVR_DEFAULT_ALIGNMENT); 2051 2052 /** 2053 Destructor. 2054 */ 2055 virtual ~wxDataViewCustomRenderer(); 2056 2057 /** 2058 Override this to react to cell @em activation. Activating a cell is an 2059 alternative to showing inline editor when the value can be edited in a 2060 simple way that doesn't warrant full editor control. The most typical 2061 use of cell activation is toggling the checkbox in 2062 wxDataViewToggleRenderer; others would be e.g. an embedded volume 2063 slider or a five-star rating column. 2064 2065 The exact means of activating a cell are platform-dependent, but they 2066 are usually similar to those used for inline editing of values. 2067 Typically, a cell would be activated by Space or Enter keys or by left 2068 mouse click. 2069 2070 This method will only be called if the cell has the 2071 wxDATAVIEW_CELL_ACTIVATABLE mode. 2072 2073 @param cell 2074 Coordinates of the activated cell's area. 2075 @param model 2076 The model to manipulate in response. 2077 @param item 2078 Activated item. 2079 @param col 2080 Activated column of @a item. 2081 @param mouseEvent 2082 If the activation was triggered by mouse click, contains the 2083 corresponding event. Is @NULL otherwise (for keyboard activation). 2084 Mouse coordinates are adjusted to be relative to the cell. 2085 2086 @since 2.9.3 2087 2088 @note Do not confuse this method with item activation in wxDataViewCtrl 2089 and the wxEVT_DATAVIEW_ITEM_ACTIVATED event. That one is 2090 used for activating the item (or, to put it differently, the 2091 entire row) similarly to analogous messages in wxTreeCtrl and 2092 wxListCtrl, and the effect differs (play a song, open a file 2093 etc.). Cell activation, on the other hand, is all about 2094 interacting with the individual cell. 2095 2096 @see CreateEditorCtrl() 2097 */ 2098 virtual bool ActivateCell(const wxRect& cell, 2099 wxDataViewModel* model, 2100 const wxDataViewItem & item, 2101 unsigned int col, 2102 const wxMouseEvent *mouseEvent); 2103 2104 /** 2105 Override this to create the actual editor control once editing 2106 is about to start. 2107 2108 This method will only be called if the cell has the 2109 wxDATAVIEW_CELL_EDITABLE mode. Editing is typically triggered by slowly 2110 double-clicking the cell or by a platform-dependent keyboard shortcut 2111 (F2 is typical on Windows, Space and/or Enter is common elsewhere and 2112 supported on Windows too). 2113 2114 @param parent 2115 The parent of the editor control. 2116 @param labelRect 2117 Indicates the position and size of the editor control. The control 2118 should be created in place of the cell and @a labelRect should be 2119 respected as much as possible. 2120 @param value 2121 Initial value of the editor. 2122 2123 An example: 2124 @code 2125 { 2126 long l = value; 2127 return new wxSpinCtrl( parent, wxID_ANY, wxEmptyString, 2128 labelRect.GetTopLeft(), labelRect.GetSize(), 0, 0, 100, l ); 2129 } 2130 @endcode 2131 2132 @see ActivateCell() 2133 */ 2134 virtual wxWindow* CreateEditorCtrl(wxWindow* parent, 2135 wxRect labelRect, 2136 const wxVariant& value); 2137 2138 /** 2139 Return the attribute to be used for rendering. 2140 2141 This function may be called from Render() implementation to use the 2142 attributes defined for the item if the renderer supports them. 2143 2144 Notice that when Render() is called, the wxDC object passed to it is 2145 already set up to use the correct attributes (e.g. its font is set to 2146 bold or italic version if wxDataViewItemAttr::GetBold() or GetItalic() 2147 returns true) so it may not be necessary to call it explicitly if you 2148 only want to render text using the items attributes. 2149 2150 @since 2.9.1 2151 */ 2152 const wxDataViewItemAttr& GetAttr() const; 2153 2154 /** 2155 Return size required to show content. 2156 */ 2157 virtual wxSize GetSize() const = 0; 2158 2159 /** 2160 Override this so that the renderer can get the value from the editor 2161 control (pointed to by @a editor): 2162 @code 2163 { 2164 wxSpinCtrl *sc = (wxSpinCtrl*) editor; 2165 long l = sc->GetValue(); 2166 value = l; 2167 return true; 2168 } 2169 @endcode 2170 */ 2171 virtual bool GetValueFromEditorCtrl(wxWindow* editor, 2172 wxVariant& value); 2173 2174 /** 2175 Override this and make it return @true in order to 2176 indicate that this renderer supports in-place editing. 2177 */ 2178 virtual bool HasEditorCtrl() const; 2179 2180 /** 2181 Override this to react to a left click. This method will only be 2182 called in @c wxDATAVIEW_CELL_ACTIVATABLE mode. This method is 2183 deprecated, please use ActivateCell instead. 2184 */ 2185 virtual bool LeftClick( wxPoint cursor, 2186 wxRect cell, 2187 wxDataViewModel * model, 2188 const wxDataViewItem & item, 2189 unsigned int col ); 2190 2191 /** 2192 Override this to react to the activation of a cell. This method is 2193 deprecated, please use ActivateCell instead. 2194 */ 2195 virtual bool Activate(wxRect cell, 2196 wxDataViewModel * model, 2197 const wxDataViewItem & item, 2198 unsigned int col); 2199 2200 2201 /** 2202 Override this to render the cell. 2203 Before this is called, wxDataViewRenderer::SetValue was called 2204 so that this instance knows what to render. 2205 */ 2206 virtual bool Render(wxRect cell, wxDC* dc, int state) = 0; 2207 2208 /** 2209 This method should be called from within Render() whenever you need to 2210 render simple text. 2211 This will ensure that the correct colour, font and vertical alignment will 2212 be chosen so the text will look the same as text drawn by native renderers. 2213 */ 2214 void RenderText(const wxString& text, int xoffset, wxRect cell, 2215 wxDC* dc, int state); 2216 2217 /** 2218 Override this to start a drag operation. Not yet supported. 2219 */ 2220 virtual bool StartDrag(const wxPoint& cursor, 2221 const wxRect& cell, 2222 wxDataViewModel* model, 2223 const wxDataViewItem & item, 2224 unsigned int col); 2225 2226 protected: 2227 /** 2228 Helper for GetSize() implementations, respects attributes. 2229 */ 2230 wxSize GetTextExtent(const wxString& str) const; 2231 }; 2232 2233 2234 2235 /** 2236 @class wxDataViewBitmapRenderer 2237 2238 This class is used by wxDataViewCtrl to render bitmap controls. 2239 2240 @library{wxadv} 2241 @category{dvc} 2242 */ 2243 class wxDataViewBitmapRenderer : public wxDataViewRenderer 2244 { 2245 public: 2246 /** 2247 The ctor. 2248 */ 2249 wxDataViewBitmapRenderer(const wxString& varianttype = "wxBitmap", 2250 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 2251 int align = wxDVR_DEFAULT_ALIGNMENT); 2252 }; 2253 2254 2255 /** 2256 The flags used by wxDataViewColumn. 2257 Can be combined together. 2258 */ 2259 enum wxDataViewColumnFlags 2260 { 2261 wxDATAVIEW_COL_RESIZABLE = 1, 2262 wxDATAVIEW_COL_SORTABLE = 2, 2263 wxDATAVIEW_COL_REORDERABLE = 4, 2264 wxDATAVIEW_COL_HIDDEN = 8 2265 }; 2266 2267 /** 2268 @class wxDataViewColumn 2269 2270 This class represents a column in a wxDataViewCtrl. 2271 One wxDataViewColumn is bound to one column in the data model to which the 2272 wxDataViewCtrl has been associated. 2273 2274 An instance of wxDataViewRenderer is used by this class to render its data. 2275 2276 @library{wxadv} 2277 @category{dvc} 2278 */ 2279 class wxDataViewColumn : public wxSettableHeaderColumn 2280 { 2281 public: 2282 /** 2283 Constructs a text column. 2284 2285 @param title 2286 The title of the column. 2287 @param renderer 2288 The class which will render the contents of this column. 2289 @param model_column 2290 The index of the model's column which is associated with this object. 2291 @param width 2292 The width of the column. 2293 The @c wxDVC_DEFAULT_WIDTH value is the fixed default value. 2294 @param align 2295 The alignment of the column title. 2296 @param flags 2297 One or more flags of the ::wxDataViewColumnFlags enumeration. 2298 */ 2299 wxDataViewColumn(const wxString& title, 2300 wxDataViewRenderer* renderer, 2301 unsigned int model_column, 2302 int width = wxDVC_DEFAULT_WIDTH, 2303 wxAlignment align = wxALIGN_CENTER, 2304 int flags = wxDATAVIEW_COL_RESIZABLE); 2305 2306 /** 2307 Constructs a bitmap column. 2308 2309 @param bitmap 2310 The bitmap of the column. 2311 @param renderer 2312 The class which will render the contents of this column. 2313 @param model_column 2314 The index of the model's column which is associated with this object. 2315 @param width 2316 The width of the column. 2317 The @c wxDVC_DEFAULT_WIDTH value is the fixed default value. 2318 @param align 2319 The alignment of the column title. 2320 @param flags 2321 One or more flags of the ::wxDataViewColumnFlags enumeration. 2322 */ 2323 wxDataViewColumn(const wxBitmap& bitmap, 2324 wxDataViewRenderer* renderer, 2325 unsigned int model_column, 2326 int width = wxDVC_DEFAULT_WIDTH, 2327 wxAlignment align = wxALIGN_CENTER, 2328 int flags = wxDATAVIEW_COL_RESIZABLE); 2329 2330 /** 2331 Returns the index of the column of the model, which this 2332 wxDataViewColumn is displaying. 2333 */ 2334 unsigned int GetModelColumn() const; 2335 2336 /** 2337 Returns the owning wxDataViewCtrl. 2338 */ 2339 wxDataViewCtrl* GetOwner() const; 2340 2341 /** 2342 Returns the renderer of this wxDataViewColumn. 2343 2344 @see wxDataViewRenderer. 2345 */ 2346 wxDataViewRenderer* GetRenderer() const; 2347 }; 2348 2349 2350 2351 /** 2352 @class wxDataViewListCtrl 2353 2354 This class is a wxDataViewCtrl which internally uses a wxDataViewListStore 2355 and forwards most of its API to that class. 2356 2357 The purpose of this class is to offer a simple way to display and 2358 edit a small table of data without having to write your own wxDataViewModel. 2359 2360 @code 2361 wxDataViewListCtrl *listctrl = new wxDataViewListCtrl( parent, wxID_ANY ); 2362 2363 listctrl->AppendToggleColumn( "Toggle" ); 2364 listctrl->AppendTextColumn( "Text" ); 2365 2366 wxVector<wxVariant> data; 2367 data.push_back( wxVariant(true) ); 2368 data.push_back( wxVariant("row 1") ); 2369 listctrl->AppendItem( data ); 2370 2371 data.clear(); 2372 data.push_back( wxVariant(false) ); 2373 data.push_back( wxVariant("row 3") ); 2374 listctrl->AppendItem( data ); 2375 @endcode 2376 2377 @beginStyleTable 2378 See wxDataViewCtrl for the list of supported styles. 2379 @endStyleTable 2380 2381 @beginEventEmissionTable 2382 See wxDataViewCtrl for the list of events emitted by this class. 2383 @endEventTable 2384 2385 @library{wxadv} 2386 @category{ctrl,dvc} 2387 2388 @since 2.9.0 2389 */ 2390 class wxDataViewListCtrl: public wxDataViewCtrl 2391 { 2392 public: 2393 /** 2394 Default ctor. 2395 */ 2396 wxDataViewListCtrl(); 2397 2398 /** 2399 Constructor. Calls Create(). 2400 */ 2401 wxDataViewListCtrl( wxWindow *parent, wxWindowID id, 2402 const wxPoint& pos = wxDefaultPosition, 2403 const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES, 2404 const wxValidator& validator = wxDefaultValidator ); 2405 2406 /** 2407 Destructor. Deletes the image list if any. 2408 */ 2409 ~wxDataViewListCtrl(); 2410 2411 /** 2412 Creates the control and a wxDataViewListStore as its internal model. 2413 */ 2414 bool Create( wxWindow *parent, wxWindowID id, 2415 const wxPoint& pos = wxDefaultPosition, 2416 const wxSize& size = wxDefaultSize, long style = wxDV_ROW_LINES, 2417 const wxValidator& validator = wxDefaultValidator ); 2418 2419 //@{ 2420 /** 2421 Returns the store. 2422 */ 2423 wxDataViewListStore *GetStore(); 2424 const wxDataViewListStore *GetStore() const; 2425 //@} 2426 2427 /** 2428 Returns the position of given @e item or wxNOT_FOUND if it's 2429 not a valid item. 2430 2431 @since 2.9.2 2432 */ 2433 int ItemToRow(const wxDataViewItem &item) const; 2434 2435 /** 2436 Returns the wxDataViewItem at the given @e row. 2437 2438 @since 2.9.2 2439 */ 2440 wxDataViewItem RowToItem(int row) const; 2441 2442 //@{ 2443 /** 2444 @name Selection handling functions 2445 */ 2446 2447 /** 2448 Returns index of the selected row or wxNOT_FOUND. 2449 2450 @see wxDataViewCtrl::GetSelection() 2451 2452 @since 2.9.2 2453 */ 2454 int GetSelectedRow() const; 2455 2456 /** 2457 Selects given row. 2458 2459 @see wxDataViewCtrl::Select() 2460 2461 @since 2.9.2 2462 */ 2463 void SelectRow(unsigned row); 2464 2465 /** 2466 Unselects given row. 2467 2468 @see wxDataViewCtrl::Unselect() 2469 2470 @since 2.9.2 2471 */ 2472 void UnselectRow(unsigned row); 2473 2474 /** 2475 Returns true if @a row is selected. 2476 2477 @see wxDataViewCtrl::IsSelected() 2478 2479 @since 2.9.2 2480 */ 2481 bool IsRowSelected(unsigned row) const; 2482 2483 //@} 2484 2485 /** 2486 @name Column management functions 2487 */ 2488 //@{ 2489 2490 /** 2491 Appends a column to the control and additionally appends a 2492 column to the store with the type string. 2493 */ 2494 virtual bool AppendColumn( wxDataViewColumn *column ); 2495 2496 /** 2497 Appends a column to the control and additionally appends a 2498 column to the list store with the type @a varianttype. 2499 */ 2500 void AppendColumn( wxDataViewColumn *column, const wxString &varianttype ); 2501 2502 /** 2503 Appends a text column to the control and the store. 2504 2505 See wxDataViewColumn::wxDataViewColumn for more info about 2506 the parameters. 2507 */ 2508 wxDataViewColumn *AppendTextColumn( const wxString &label, 2509 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 2510 int width = -1, wxAlignment align = wxALIGN_LEFT, 2511 int flags = wxDATAVIEW_COL_RESIZABLE ); 2512 2513 /** 2514 Appends a toggle column to the control and the store. 2515 2516 See wxDataViewColumn::wxDataViewColumn for more info about 2517 the parameters. 2518 */ 2519 wxDataViewColumn *AppendToggleColumn( const wxString &label, 2520 wxDataViewCellMode mode = wxDATAVIEW_CELL_ACTIVATABLE, 2521 int width = -1, wxAlignment align = wxALIGN_LEFT, 2522 int flags = wxDATAVIEW_COL_RESIZABLE ); 2523 2524 /** 2525 Appends a progress column to the control and the store. 2526 2527 See wxDataViewColumn::wxDataViewColumn for more info about 2528 the parameters. 2529 */ 2530 wxDataViewColumn *AppendProgressColumn( const wxString &label, 2531 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 2532 int width = -1, wxAlignment align = wxALIGN_LEFT, 2533 int flags = wxDATAVIEW_COL_RESIZABLE ); 2534 2535 /** 2536 Appends an icon-and-text column to the control and the store. 2537 2538 See wxDataViewColumn::wxDataViewColumn for more info about 2539 the parameters. 2540 */ 2541 wxDataViewColumn *AppendIconTextColumn( const wxString &label, 2542 wxDataViewCellMode mode = wxDATAVIEW_CELL_INERT, 2543 int width = -1, wxAlignment align = wxALIGN_LEFT, 2544 int flags = wxDATAVIEW_COL_RESIZABLE ); 2545 2546 /** 2547 Inserts a column to the control and additionally inserts a 2548 column to the store with the type string. 2549 */ 2550 virtual bool InsertColumn( unsigned int pos, wxDataViewColumn *column ); 2551 2552 /** 2553 Inserts a column to the control and additionally inserts a 2554 column to the list store with the type @a varianttype. 2555 */ 2556 void InsertColumn( unsigned int pos, wxDataViewColumn *column, 2557 const wxString &varianttype ); 2558 2559 /** 2560 Prepends a column to the control and additionally prepends a 2561 column to the store with the type string. 2562 */ 2563 virtual bool PrependColumn( wxDataViewColumn *column ); 2564 2565 /** 2566 Prepends a column to the control and additionally prepends a 2567 column to the list store with the type @a varianttype. 2568 */ 2569 void PrependColumn( wxDataViewColumn *column, const wxString &varianttype ); 2570 2571 //@} 2572 2573 2574 /** 2575 @name Item management functions 2576 */ 2577 //@{ 2578 2579 /** 2580 Appends an item (=row) to the control and store. 2581 */ 2582 void AppendItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL ); 2583 2584 /** 2585 Prepends an item (=row) to the control and store. 2586 */ 2587 void PrependItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL ); 2588 2589 /** 2590 Inserts an item (=row) to the control and store. 2591 */ 2592 void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxUIntPtr data = NULL ); 2593 2594 /** 2595 Delete the row at position @a row. 2596 */ 2597 void DeleteItem( unsigned row ); 2598 2599 /** 2600 Delete all items (= all rows). 2601 */ 2602 void DeleteAllItems(); 2603 2604 /** 2605 Returns the number of items (=rows) in the control 2606 2607 @since 2.9.4 2608 */ 2609 unsigned int GetItemCount() const; 2610 2611 /** 2612 Returns the client data associated with the item. 2613 2614 @see SetItemData() 2615 2616 @since 2.9.4 2617 */ 2618 wxUIntPtr GetItemData(const wxDataViewItem& item) const; 2619 2620 /** 2621 Sets the value in the store and update the control. 2622 */ 2623 void SetValue( const wxVariant &value, unsigned int row, unsigned int col ); 2624 2625 /** 2626 Returns the value from the store. 2627 */ 2628 void GetValue( wxVariant &value, unsigned int row, unsigned int col ); 2629 2630 /** 2631 Sets the value in the store and update the control. 2632 2633 This method assumes that the string is stored in respective 2634 column. 2635 */ 2636 void SetTextValue( const wxString &value, unsigned int row, unsigned int col ); 2637 2638 /** 2639 Returns the value from the store. 2640 2641 This method assumes that the string is stored in respective 2642 column. 2643 */ 2644 wxString GetTextValue( unsigned int row, unsigned int col ) const; 2645 2646 /** 2647 Sets the value in the store and update the control. 2648 2649 This method assumes that the boolean value is stored in 2650 respective column. 2651 */ 2652 void SetToggleValue( bool value, unsigned int row, unsigned int col ); 2653 2654 /** 2655 Returns the value from the store. 2656 2657 This method assumes that the boolean value is stored in 2658 respective column. 2659 */ 2660 bool GetToggleValue( unsigned int row, unsigned int col ) const; 2661 2662 /** 2663 Associates a client data pointer with the given item. 2664 2665 Notice that the control does @e not take ownership of the pointer for 2666 compatibility with wxListCtrl. I.e. it will @e not delete the pointer 2667 (if it is a pointer and not a number) itself, it is up to you to do it. 2668 2669 @see GetItemData() 2670 2671 @since 2.9.4 2672 */ 2673 void SetItemData(const wxDataViewItem& item, wxUIntPtr data); 2674 2675 //@} 2676 }; 2677 2678 2679 /** 2680 @class wxDataViewTreeCtrl 2681 2682 This class is a wxDataViewCtrl which internally uses a wxDataViewTreeStore 2683 and forwards most of its API to that class. 2684 Additionally, it uses a wxImageList to store a list of icons. 2685 2686 The main purpose of this class is to provide a simple upgrade path for code 2687 using wxTreeCtrl. 2688 2689 @beginStyleTable 2690 See wxDataViewCtrl for the list of supported styles. 2691 @endStyleTable 2692 2693 @beginEventEmissionTable 2694 See wxDataViewCtrl for the list of events emitted by this class. 2695 @endEventTable 2696 2697 @library{wxadv} 2698 @category{ctrl,dvc} 2699 2700 @since 2.9.0 2701 2702 @appearance{dataviewtreectrl} 2703 */ 2704 class wxDataViewTreeCtrl : public wxDataViewCtrl 2705 { 2706 public: 2707 /** 2708 Default ctor. 2709 */ 2710 wxDataViewTreeCtrl(); 2711 2712 /** 2713 Constructor. 2714 2715 Calls Create(). 2716 */ 2717 wxDataViewTreeCtrl(wxWindow* parent, wxWindowID id, 2718 const wxPoint& pos = wxDefaultPosition, 2719 const wxSize& size = wxDefaultSize, 2720 long style = wxDV_NO_HEADER | wxDV_ROW_LINES, 2721 const wxValidator& validator = wxDefaultValidator); 2722 2723 /** 2724 Destructor. Deletes the image list if any. 2725 */ 2726 virtual ~wxDataViewTreeCtrl(); 2727 2728 /** 2729 Appends a container to the given @a parent. 2730 */ 2731 wxDataViewItem AppendContainer(const wxDataViewItem& parent, 2732 const wxString& text, 2733 int icon = -1, 2734 int expanded = -1, 2735 wxClientData* data = NULL); 2736 2737 /** 2738 Appends an item to the given @a parent. 2739 */ 2740 wxDataViewItem AppendItem(const wxDataViewItem& parent, 2741 const wxString& text, 2742 int icon = -1, 2743 wxClientData* data = NULL); 2744 2745 /** 2746 Creates the control and a wxDataViewTreeStore as its internal model. 2747 2748 The default tree column created by this method is an editable column 2749 using wxDataViewIconTextRenderer as its renderer. 2750 */ 2751 bool Create(wxWindow* parent, wxWindowID id, 2752 const wxPoint& pos = wxDefaultPosition, 2753 const wxSize& size = wxDefaultSize, 2754 long style = wxDV_NO_HEADER | wxDV_ROW_LINES, 2755 const wxValidator& validator = wxDefaultValidator); 2756 2757 /** 2758 Calls the identical method from wxDataViewTreeStore. 2759 */ 2760 void DeleteAllItems(); 2761 2762 /** 2763 Calls the identical method from wxDataViewTreeStore. 2764 */ 2765 void DeleteChildren(const wxDataViewItem& item); 2766 2767 /** 2768 Calls the identical method from wxDataViewTreeStore. 2769 */ 2770 void DeleteItem(const wxDataViewItem& item); 2771 2772 /** 2773 Calls the identical method from wxDataViewTreeStore. 2774 */ 2775 int GetChildCount(const wxDataViewItem& parent) const; 2776 2777 /** 2778 Returns the image list. 2779 */ 2780 wxImageList* GetImageList(); 2781 2782 /** 2783 Calls the identical method from wxDataViewTreeStore. 2784 */ 2785 wxClientData* GetItemData(const wxDataViewItem& item) const; 2786 2787 /** 2788 Calls the identical method from wxDataViewTreeStore. 2789 */ 2790 const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const; 2791 2792 /** 2793 Calls the identical method from wxDataViewTreeStore. 2794 */ 2795 const wxIcon& GetItemIcon(const wxDataViewItem& item) const; 2796 2797 /** 2798 Calls the identical method from wxDataViewTreeStore. 2799 */ 2800 wxString GetItemText(const wxDataViewItem& item) const; 2801 2802 /** 2803 Calls the identical method from wxDataViewTreeStore. 2804 */ 2805 wxDataViewItem GetNthChild(const wxDataViewItem& parent, 2806 unsigned int pos) const; 2807 2808 //@{ 2809 /** 2810 Returns the store. 2811 */ 2812 wxDataViewTreeStore* GetStore(); 2813 const wxDataViewTreeStore* GetStore() const; 2814 //@} 2815 2816 /** 2817 Calls the same method from wxDataViewTreeStore but uses 2818 an index position in the image list instead of a wxIcon. 2819 */ 2820 wxDataViewItem InsertContainer(const wxDataViewItem& parent, 2821 const wxDataViewItem& previous, 2822 const wxString& text, 2823 int icon = -1, 2824 int expanded = -1, 2825 wxClientData* data = NULL); 2826 2827 /** 2828 Calls the same method from wxDataViewTreeStore but uses 2829 an index position in the image list instead of a wxIcon. 2830 */ 2831 wxDataViewItem InsertItem(const wxDataViewItem& parent, 2832 const wxDataViewItem& previous, 2833 const wxString& text, 2834 int icon = -1, 2835 wxClientData* data = NULL); 2836 2837 /** 2838 Returns true if item is a container. 2839 */ 2840 bool IsContainer( const wxDataViewItem& item ); 2841 2842 /** 2843 Calls the same method from wxDataViewTreeStore but uses 2844 an index position in the image list instead of a wxIcon. 2845 */ 2846 wxDataViewItem PrependContainer(const wxDataViewItem& parent, 2847 const wxString& text, 2848 int icon = -1, 2849 int expanded = -1, 2850 wxClientData* data = NULL); 2851 2852 /** 2853 Calls the same method from wxDataViewTreeStore but uses 2854 an index position in the image list instead of a wxIcon. 2855 */ 2856 wxDataViewItem PrependItem(const wxDataViewItem& parent, 2857 const wxString& text, 2858 int icon = -1, 2859 wxClientData* data = NULL); 2860 2861 /** 2862 Sets the image list. 2863 */ 2864 void SetImageList(wxImageList* imagelist); 2865 2866 /** 2867 Calls the identical method from wxDataViewTreeStore. 2868 */ 2869 void SetItemData(const wxDataViewItem& item, wxClientData* data); 2870 2871 /** 2872 Calls the identical method from wxDataViewTreeStore. 2873 */ 2874 void SetItemExpandedIcon(const wxDataViewItem& item, 2875 const wxIcon& icon); 2876 2877 /** 2878 Calls the identical method from wxDataViewTreeStore. 2879 */ 2880 void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon); 2881 2882 /** 2883 Calls the identical method from wxDataViewTreeStore. 2884 */ 2885 void SetItemText(const wxDataViewItem& item, 2886 const wxString& text); 2887 }; 2888 2889 2890 /** 2891 @class wxDataViewListStore 2892 2893 wxDataViewListStore is a specialised wxDataViewModel for storing 2894 a simple table of data. Since it derives from wxDataViewIndexListModel 2895 its data is be accessed by row (i.e. by index) instead of only 2896 by wxDataViewItem. 2897 2898 This class actually stores the values (therefore its name) 2899 and implements all virtual methods from the base classes so it can be 2900 used directly without having to derive any class from it, but it is 2901 mostly used from within wxDataViewListCtrl. 2902 2903 @library{wxadv} 2904 @category{dvc} 2905 */ 2906 2907 class wxDataViewListStore: public wxDataViewIndexListModel 2908 { 2909 public: 2910 /** 2911 Constructor 2912 */ 2913 wxDataViewListStore(); 2914 2915 /** 2916 Destructor 2917 */ 2918 ~wxDataViewListStore(); 2919 2920 /** 2921 Prepends a data column. 2922 2923 @a variantype indicates the type of values store in the column. 2924 2925 This does not automatically fill in any (default) values in 2926 rows which exist in the store already. 2927 */ 2928 void PrependColumn( const wxString &varianttype ); 2929 2930 /** 2931 Inserts a data column before @a pos. 2932 2933 @a variantype indicates the type of values store in the column. 2934 2935 This does not automatically fill in any (default) values in 2936 rows which exist in the store already. 2937 */ 2938 void InsertColumn( unsigned int pos, const wxString &varianttype ); 2939 2940 /** 2941 Appends a data column. 2942 2943 @a variantype indicates the type of values store in the column. 2944 2945 This does not automatically fill in any (default) values in 2946 rows which exist in the store already. 2947 */ 2948 void AppendColumn( const wxString &varianttype ); 2949 2950 /** 2951 Appends an item (=row) and fills it with @a values. 2952 2953 The values must match the values specifies in the column 2954 in number and type. No (default) values are filled in 2955 automatically. 2956 */ 2957 void AppendItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL ); 2958 2959 /** 2960 Prepends an item (=row) and fills it with @a values. 2961 2962 The values must match the values specifies in the column 2963 in number and type. No (default) values are filled in 2964 automatically. 2965 */ 2966 void PrependItem( const wxVector<wxVariant> &values, wxUIntPtr data = NULL ); 2967 2968 /** 2969 Inserts an item (=row) and fills it with @a values. 2970 2971 The values must match the values specifies in the column 2972 in number and type. No (default) values are filled in 2973 automatically. 2974 */ 2975 void InsertItem( unsigned int row, const wxVector<wxVariant> &values, wxUIntPtr data = NULL ); 2976 2977 /** 2978 Delete the item (=row) at position @a pos. 2979 */ 2980 void DeleteItem( unsigned pos ); 2981 2982 /** 2983 Delete all item (=all rows) in the store. 2984 */ 2985 void DeleteAllItems(); 2986 2987 /** 2988 Returns the number of items (=rows) in the control 2989 2990 @since 2.9.4 2991 */ 2992 unsigned int GetItemCount() const; 2993 2994 /** 2995 Returns the client data associated with the item. 2996 2997 @see SetItemData() 2998 2999 @since 2.9.4 3000 */ 3001 wxUIntPtr GetItemData(const wxDataViewItem& item) const; 3002 3003 /** 3004 Overridden from wxDataViewModel 3005 */ 3006 virtual unsigned int GetColumnCount() const; 3007 3008 /** 3009 Overridden from wxDataViewModel 3010 */ 3011 virtual wxString GetColumnType( unsigned int col ) const; 3012 3013 /** 3014 Sets the client data associated with the item. 3015 3016 Notice that this class does @e not take ownership of the passed in 3017 pointer and will not delete it. 3018 3019 @see GetItemData() 3020 3021 @since 2.9.4 3022 */ 3023 void SetItemData(const wxDataViewItem& item, wxUIntPtr data); 3024 3025 /** 3026 Overridden from wxDataViewIndexListModel 3027 */ 3028 virtual void GetValueByRow( wxVariant &value, 3029 unsigned int row, unsigned int col ) const; 3030 3031 /** 3032 Overridden from wxDataViewIndexListModel 3033 */ 3034 virtual bool SetValueByRow( const wxVariant &value, 3035 unsigned int row, unsigned int col ); 3036 }; 3037 3038 3039 /** 3040 @class wxDataViewTreeStore 3041 3042 wxDataViewTreeStore is a specialised wxDataViewModel for storing simple 3043 trees very much like wxTreeCtrl does and it offers a similar API. 3044 3045 This class actually stores the entire tree and the values (therefore its name) 3046 and implements all virtual methods from the base class so it can be used directly 3047 without having to derive any class from it, but it is mostly used from within 3048 wxDataViewTreeCtrl. 3049 3050 @library{wxadv} 3051 @category{dvc} 3052 */ 3053 class wxDataViewTreeStore : public wxDataViewModel 3054 { 3055 public: 3056 /** 3057 Constructor. Creates the invisible root node internally. 3058 */ 3059 wxDataViewTreeStore(); 3060 3061 /** 3062 Destructor. 3063 */ 3064 virtual ~wxDataViewTreeStore(); 3065 3066 /** 3067 Append a container. 3068 */ 3069 wxDataViewItem AppendContainer(const wxDataViewItem& parent, 3070 const wxString& text, 3071 const wxIcon& icon = wxNullIcon, 3072 const wxIcon& expanded = wxNullIcon, 3073 wxClientData* data = NULL); 3074 3075 /** 3076 Append an item. 3077 */ 3078 wxDataViewItem AppendItem(const wxDataViewItem& parent, 3079 const wxString& text, 3080 const wxIcon& icon = wxNullIcon, 3081 wxClientData* data = NULL); 3082 3083 /** 3084 Delete all item in the model. 3085 */ 3086 void DeleteAllItems(); 3087 3088 /** 3089 Delete all children of the item, but not the item itself. 3090 */ 3091 void DeleteChildren(const wxDataViewItem& item); 3092 3093 /** 3094 Delete this item. 3095 */ 3096 void DeleteItem(const wxDataViewItem& item); 3097 3098 /** 3099 Return the number of children of item. 3100 */ 3101 int GetChildCount(const wxDataViewItem& parent) const; 3102 3103 /** 3104 Returns the client data associated with the item. 3105 */ 3106 wxClientData* GetItemData(const wxDataViewItem& item) const; 3107 3108 /** 3109 Returns the icon to display in expanded containers. 3110 */ 3111 const wxIcon& GetItemExpandedIcon(const wxDataViewItem& item) const; 3112 3113 /** 3114 Returns the icon of the item. 3115 */ 3116 const wxIcon& GetItemIcon(const wxDataViewItem& item) const; 3117 3118 /** 3119 Returns the text of the item. 3120 */ 3121 wxString GetItemText(const wxDataViewItem& item) const; 3122 3123 /** 3124 Returns the nth child item of item. 3125 */ 3126 wxDataViewItem GetNthChild(const wxDataViewItem& parent, 3127 unsigned int pos) const; 3128 3129 /** 3130 Inserts a container after @a previous. 3131 */ 3132 wxDataViewItem InsertContainer(const wxDataViewItem& parent, 3133 const wxDataViewItem& previous, 3134 const wxString& text, 3135 const wxIcon& icon = wxNullIcon, 3136 const wxIcon& expanded = wxNullIcon, 3137 wxClientData* data = NULL); 3138 3139 /** 3140 Inserts an item after @a previous. 3141 */ 3142 wxDataViewItem InsertItem(const wxDataViewItem& parent, 3143 const wxDataViewItem& previous, 3144 const wxString& text, 3145 const wxIcon& icon = wxNullIcon, 3146 wxClientData* data = NULL); 3147 3148 /** 3149 Inserts a container before the first child item or @a parent. 3150 */ 3151 wxDataViewItem PrependContainer(const wxDataViewItem& parent, 3152 const wxString& text, 3153 const wxIcon& icon = wxNullIcon, 3154 const wxIcon& expanded = wxNullIcon, 3155 wxClientData* data = NULL); 3156 3157 /** 3158 Inserts an item before the first child item or @a parent. 3159 */ 3160 wxDataViewItem PrependItem(const wxDataViewItem& parent, 3161 const wxString& text, 3162 const wxIcon& icon = wxNullIcon, 3163 wxClientData* data = NULL); 3164 3165 /** 3166 Sets the client data associated with the item. 3167 */ 3168 void SetItemData(const wxDataViewItem& item, wxClientData* data); 3169 3170 /** 3171 Sets the expanded icon for the item. 3172 */ 3173 void SetItemExpandedIcon(const wxDataViewItem& item, 3174 const wxIcon& icon); 3175 3176 /** 3177 Sets the icon for the item. 3178 */ 3179 void SetItemIcon(const wxDataViewItem& item, const wxIcon& icon); 3180 }; 3181 3182 3183 /** 3184 @class wxDataViewIconText 3185 3186 wxDataViewIconText is used by wxDataViewIconTextRenderer for data transfer. 3187 This class can be converted to and from a wxVariant. 3188 3189 @library{wxadv} 3190 @category{dvc} 3191 */ 3192 class wxDataViewIconText : public wxObject 3193 { 3194 public: 3195 //@{ 3196 /** 3197 Constructor. 3198 */ 3199 wxDataViewIconText(const wxString& text = wxEmptyString, 3200 const wxIcon& icon = wxNullIcon); 3201 wxDataViewIconText(const wxDataViewIconText& other); 3202 //@} 3203 3204 /** 3205 Gets the icon. 3206 */ 3207 const wxIcon& GetIcon() const; 3208 3209 /** 3210 Gets the text. 3211 */ 3212 wxString GetText() const; 3213 3214 /** 3215 Set the icon. 3216 */ 3217 void SetIcon(const wxIcon& icon); 3218 3219 /** 3220 Set the text. 3221 */ 3222 void SetText(const wxString& text); 3223 }; 3224 3225 3226 3227 /** 3228 @class wxDataViewEvent 3229 3230 This is the event class for the wxDataViewCtrl notifications. 3231 3232 @beginEventTable{wxDataViewEvent} 3233 @event{EVT_DATAVIEW_SELECTION_CHANGED(id, func)} 3234 Process a @c wxEVT_DATAVIEW_SELECTION_CHANGED event. 3235 @event{EVT_DATAVIEW_ITEM_ACTIVATED(id, func)} 3236 Process a @c wxEVT_DATAVIEW_ITEM_ACTIVATED event. 3237 @event{EVT_DATAVIEW_ITEM_EDITING_STARTED(id, func)} 3238 Process a @c wxEVT_DATAVIEW_ITEM_EDITING_STARTED event. 3239 @event{EVT_DATAVIEW_ITEM_EDITING_DONE(id, func)} 3240 Process a @c wxEVT_DATAVIEW_ITEM_EDITING_DONE event. 3241 @event{EVT_DATAVIEW_ITEM_COLLAPSING(id, func)} 3242 Process a @c wxEVT_DATAVIEW_ITEM_COLLAPSING event. 3243 @event{EVT_DATAVIEW_ITEM_COLLAPSED(id, func)} 3244 Process a @c wxEVT_DATAVIEW_ITEM_COLLAPSED event. 3245 @event{EVT_DATAVIEW_ITEM_EXPANDING(id, func)} 3246 Process a @c wxEVT_DATAVIEW_ITEM_EXPANDING event. 3247 @event{EVT_DATAVIEW_ITEM_EXPANDED(id, func)} 3248 Process a @c wxEVT_DATAVIEW_ITEM_EXPANDED event. 3249 @event{EVT_DATAVIEW_ITEM_VALUE_CHANGED(id, func)} 3250 Process a @c wxEVT_DATAVIEW_ITEM_VALUE_CHANGED event. 3251 @event{EVT_DATAVIEW_ITEM_CONTEXT_MENU(id, func)} 3252 Process a @c wxEVT_DATAVIEW_ITEM_CONTEXT_MENU event. 3253 @event{EVT_DATAVIEW_COLUMN_HEADER_CLICK(id, func)} 3254 Process a @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICK event. 3255 @event{EVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK(id, func)} 3256 Process a @c wxEVT_DATAVIEW_COLUMN_HEADER_RIGHT_CLICK event. 3257 @event{EVT_DATAVIEW_COLUMN_SORTED(id, func)} 3258 Process a @c wxEVT_DATAVIEW_COLUMN_SORTED event. 3259 @event{EVT_DATAVIEW_COLUMN_REORDERED(id, func)} 3260 Process a @c wxEVT_DATAVIEW_COLUMN_REORDERED event. 3261 Currently this even is only generated when using the native OSX 3262 version. 3263 @event{EVT_DATAVIEW_ITEM_BEGIN_DRAG(id, func)} 3264 Process a @c wxEVT_DATAVIEW_ITEM_BEGIN_DRAG event. 3265 @event{EVT_DATAVIEW_ITEM_DROP_POSSIBLE(id, func)} 3266 Process a @c wxEVT_DATAVIEW_ITEM_DROP_POSSIBLE event. 3267 @event{EVT_DATAVIEW_ITEM_DROP(id, func)} 3268 Process a @c wxEVT_DATAVIEW_ITEM_DROP event. 3269 @event{EVT_DATAVIEW_CACHE_HINT(id, func)} 3270 Process a @c wxEVT_DATAVIEW_CACHE_HINT event. 3271 @endEventTable 3272 3273 @library{wxadv} 3274 @category{events,dvc} 3275 */ 3276 class wxDataViewEvent : public wxNotifyEvent 3277 { 3278 public: 3279 /** 3280 Constructor. Typically used by wxWidgets internals only. 3281 */ 3282 wxDataViewEvent(wxEventType commandType = wxEVT_NULL, 3283 int winid = 0); 3284 3285 /** 3286 Returns the position of the column in the control or -1 3287 if no column field was set by the event emitter. 3288 */ 3289 int GetColumn() const; 3290 3291 /** 3292 Returns a pointer to the wxDataViewColumn from which 3293 the event was emitted or @NULL. 3294 */ 3295 wxDataViewColumn* GetDataViewColumn() const; 3296 3297 /** 3298 Returns the wxDataViewModel associated with the event. 3299 */ 3300 wxDataViewModel* GetModel() const; 3301 3302 /** 3303 Returns the position of a context menu event in screen coordinates. 3304 */ 3305 wxPoint GetPosition() const; 3306 3307 /** 3308 Returns a reference to a value. 3309 */ 3310 const wxVariant& GetValue() const; 3311 3312 /** 3313 Can be used to determine whether the new value is going to be accepted 3314 in wxEVT_DATAVIEW_ITEM_EDITING_DONE handler. 3315 3316 Returns @true if editing the item was cancelled or if the user tried to 3317 enter an invalid value (refused by wxDataViewRenderer::Validate()). If 3318 this method returns @false, it means that the value in the model is 3319 about to be changed to the new one. 3320 3321 Notice that wxEVT_DATAVIEW_ITEM_EDITING_DONE event handler can 3322 call wxNotifyEvent::Veto() to prevent this from happening. 3323 3324 Currently support for setting this field and for vetoing the change is 3325 only available in the generic version of wxDataViewCtrl, i.e. under MSW 3326 but not GTK nor OS X. 3327 3328 @since 2.9.3 3329 */ 3330 bool IsEditCancelled() const; 3331 3332 /** 3333 Sets the column index associated with this event. 3334 */ 3335 void SetColumn(int col); 3336 3337 /** 3338 For @c wxEVT_DATAVIEW_COLUMN_HEADER_CLICK only. 3339 */ 3340 void SetDataViewColumn(wxDataViewColumn* col); 3341 3342 /** 3343 Sets the dataview model associated with this event. 3344 */ 3345 void SetModel(wxDataViewModel* model); 3346 3347 /** 3348 Sets the value associated with this event. 3349 */ 3350 void SetValue(const wxVariant& value); 3351 3352 /** 3353 Set wxDataObject for data transfer within a drag operation. 3354 */ 3355 void SetDataObject( wxDataObject *obj ); 3356 3357 /** 3358 Gets the wxDataFormat during a drop operation. 3359 */ 3360 wxDataFormat GetDataFormat() const; 3361 3362 /** 3363 Gets the data size for a drop data transfer. 3364 */ 3365 size_t GetDataSize() const; 3366 3367 /** 3368 Gets the data buffer for a drop data transfer. 3369 */ 3370 void *GetDataBuffer() const; 3371 3372 /** 3373 Specify the kind of the drag operation to perform. 3374 3375 This method can be used inside a wxEVT_DATAVIEW_ITEM_BEGIN_DRAG 3376 handler in order to configure the drag operation. Valid values are 3377 ::wxDrag_CopyOnly (default), ::wxDrag_AllowMove (allow the data to be 3378 moved) and ::wxDrag_DefaultMove. 3379 3380 Currently it is only honoured by the generic version of wxDataViewCtrl 3381 (used e.g. under MSW) and not supported by the native GTK and OS X 3382 versions. 3383 3384 @see GetDropEffect() 3385 3386 @since 2.9.4 3387 */ 3388 void SetDragFlags(int flags); 3389 3390 /** 3391 Returns the effect the user requested to happen to the dropped data. 3392 3393 This function can be used inside 3394 wxEVT_DATAVIEW_ITEM_DROP_POSSIBLE and 3395 wxEVT_DATAVIEW_ITEM_DROP handlers and returns whether the user 3396 is trying to copy (the return value is ::wxDragCopy) or move (if the 3397 return value is ::wxDragMove) the data. 3398 3399 Currently this is only available when using the generic version of 3400 wxDataViewCtrl (used e.g. under MSW) and always returns ::wxDragNone in 3401 the GTK and OS X native versions. 3402 3403 @since 2.9.4 3404 */ 3405 wxDragResult GetDropEffect() const; 3406 3407 /** 3408 Return the first row that will be displayed. 3409 */ 3410 int GetCacheFrom() const; 3411 3412 /** 3413 Return the last row that will be displayed. 3414 */ 3415 int GetCacheTo() const; 3416 3417 3418 3419 3420 wxDataViewItem GetItem() const; 3421 void SetItem( const wxDataViewItem &item ); 3422 void SetEditCanceled(bool editCancelled); 3423 void SetPosition( int x, int y ); 3424 void SetCache(int from, int to); 3425 wxDataObject *GetDataObject() const; 3426 void SetDataFormat( const wxDataFormat &format ); 3427 void SetDataSize( size_t size ); 3428 void SetDataBuffer( void* buf ); 3429 int GetDragFlags() const; 3430 void SetDropEffect( wxDragResult effect ); 3431 3432 }; 3433 3434