1 ///////////////////////////////////////////////////////////////////////////// 2 // Name: grid.h 3 // Purpose: interface of wxGrid and related classes 4 // Author: wxWidgets team 5 // Licence: wxWindows licence 6 ///////////////////////////////////////////////////////////////////////////// 7 8 9 /// Magic constant which tells (to some functions) to automatically calculate 10 /// the appropriate size 11 #define wxGRID_AUTOSIZE (-1) 12 13 14 /** 15 @class wxGridCellRenderer 16 17 This class is responsible for actually drawing the cell in the grid. You 18 may pass it to the wxGridCellAttr (below) to change the format of one given 19 cell or to wxGrid::SetDefaultRenderer() to change the view of all cells. 20 This is an abstract class, and you will normally use one of the predefined 21 derived classes or derive your own class from it. 22 23 @library{wxcore} 24 @category{grid} 25 26 @see wxGridCellAutoWrapStringRenderer, wxGridCellBoolRenderer, 27 wxGridCellDateTimeRenderer, wxGridCellEnumRenderer, 28 wxGridCellFloatRenderer, wxGridCellNumberRenderer, 29 wxGridCellStringRenderer 30 */ 31 class wxGridCellRenderer : public wxClientDataContainer, public wxRefCounter 32 { 33 public: 34 wxGridCellRenderer(); 35 36 /** 37 This function must be implemented in derived classes to return a copy 38 of itself. 39 */ 40 virtual wxGridCellRenderer* Clone() const = 0; 41 42 /** 43 Draw the given cell on the provided DC inside the given rectangle using 44 the style specified by the attribute and the default or selected state 45 corresponding to the isSelected value. 46 47 This pure virtual function has a default implementation which will 48 prepare the DC using the given attribute: it will draw the rectangle 49 with the background colour from attr and set the text colour and font. 50 */ 51 virtual void Draw(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, 52 const wxRect& rect, int row, int col, 53 bool isSelected) = 0; 54 55 /** 56 Get the preferred size of the cell for its contents. 57 58 This method must be overridden in the derived classes to return the 59 minimal fitting size for displaying the content of the given grid cell. 60 61 @see GetBestHeight(), GetBestWidth() 62 */ 63 virtual wxSize GetBestSize(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, 64 int row, int col) = 0; 65 66 /** 67 Get the preferred height of the cell at the given width. 68 69 Some renderers may not have a well-defined best size, but only be able 70 to provide the best height at the given width, e.g. this is the case of 71 the standard wxGridCellAutoWrapStringRenderer. In this case, they 72 should override this method, in addition to GetBestSize(). 73 74 @see GetBestWidth() 75 76 @since 3.1.0 77 */ 78 virtual int GetBestHeight(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, 79 int row, int col, int width); 80 81 /** 82 Get the preferred width of the cell at the given height. 83 84 See GetBestHeight(), this method is symmetric to it. 85 86 @since 3.1.0 87 */ 88 virtual int GetBestWidth(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, 89 int row, int col, int height); 90 91 /** 92 Get the maximum possible size for a cell using this renderer, if 93 possible. 94 95 This function may be overridden in the derived class if it can return 96 the maximum size needed for displaying the cells rendered it without 97 iterating over all cells. The base class version simply returns 98 ::wxDefaultSize, indicating that this is infeasible and that 99 GetBestSize() should be called for each cell individually. 100 101 Note that this method will only be used if 102 wxGridTableBase::CanMeasureColUsingSameAttr() is overridden to return 103 @true. 104 105 @since 3.1.4 106 */ 107 virtual wxSize GetMaxBestSize(wxGrid& grid, 108 wxGridCellAttr& attr, 109 wxDC& dc); 110 111 protected: 112 /** 113 Helper function setting the correct colours and font. 114 115 This function can be useful in the derived classes Draw() 116 implementation as it takes care of setting the appropriate colours and 117 font for @a dc depending on the global @a grid attributes, cell 118 attributions specified in @a attr and whether @a isSelected is @true. 119 120 Simply call it before doing any drawing in the derived class version to 121 use consistent colours and font for all cells. 122 123 @since 3.1.5 124 */ 125 void SetTextColoursAndFont(const wxGrid& grid, 126 const wxGridCellAttr& attr, 127 wxDC& dc, 128 bool isSelected); 129 /** 130 The destructor is private because only DecRef() can delete us. 131 */ 132 virtual ~wxGridCellRenderer(); 133 }; 134 135 /** 136 Smart pointer wrapping wxGridCellRenderer. 137 138 wxGridCellRendererPtr takes ownership of wxGridCellRenderer passed to it on 139 construction and calls DecRef() on it automatically when it is destroyed. 140 It also provides transparent access to wxGridCellRenderer methods by allowing 141 to use objects of this class as if they were wxGridCellRenderer pointers. 142 143 @since 3.1.4 144 145 @category{grid} 146 */ 147 typedef wxObjectDataPtr<wxGridCellRenderer> wxGridCellRendererPtr; 148 149 /** 150 @class wxGridCellAutoWrapStringRenderer 151 152 This class may be used to format string data in a cell. The too 153 long lines are wrapped to be shown entirely at word boundaries. 154 155 @library{wxcore} 156 @category{grid} 157 158 @see wxGridCellRenderer, wxGridCellBoolRenderer, 159 wxGridCellDateTimeRenderer, wxGridCellEnumRenderer, 160 wxGridCellFloatRenderer, wxGridCellNumberRenderer, 161 wxGridCellStringRenderer 162 */ 163 164 class wxGridCellAutoWrapStringRenderer : public wxGridCellStringRenderer 165 { 166 public: 167 /** 168 Default constructor. 169 */ 170 wxGridCellAutoWrapStringRenderer(); 171 }; 172 173 174 /** 175 @class wxGridCellBoolRenderer 176 177 This class may be used to format boolean data in a cell. 178 179 @library{wxcore} 180 @category{grid} 181 182 @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, 183 wxGridCellDateTimeRenderer, wxGridCellEnumRenderer, 184 wxGridCellFloatRenderer, wxGridCellNumberRenderer, 185 wxGridCellStringRenderer 186 */ 187 class wxGridCellBoolRenderer : public wxGridCellRenderer 188 { 189 public: 190 /** 191 Default constructor. 192 */ 193 wxGridCellBoolRenderer(); 194 }; 195 196 /** 197 @class wxGridCellDateRenderer 198 199 This class may be used to show a date, without time, in a cell. 200 201 See @ref wxGridCellDateTimeRenderer for a date/time version. 202 wxDateTime::Format() is used internally to render the date 203 representation. wxDateTime::ParseDate() is used to parse the string 204 data entered in the cell. 205 206 @library{wxcore} 207 @category{grid} 208 209 @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, 210 wxGridCellBoolRenderer, wxGridCellEnumRenderer, 211 wxGridCellFloatRenderer, wxGridCellNumberRenderer, 212 wxGridCellStringRenderer, wxGridCellDateTimeRenderer 213 214 @since 3.1.3 215 */ 216 class wxGridCellDateRenderer : public wxGridCellStringRenderer 217 { 218 public: 219 /** 220 Date renderer constructor. 221 222 @param outformat 223 strftime()-like format string used to render the output date. 224 By default (or if provided format string is empty) localized 225 date representation ("%x") is used. 226 */ 227 wxGridCellDateRenderer(const wxString& outformat = wxString()); 228 229 230 /** 231 Sets the strftime()-like format string which will be used to render 232 the date. 233 234 @param params 235 strftime()-like format string used to render the date. 236 */ 237 virtual void SetParameters(const wxString& params); 238 }; 239 240 /** 241 @class wxGridCellDateTimeRenderer 242 243 This class may be used to format a date/time data in a cell. 244 The class wxDateTime is used internally to display the local date/time 245 or to parse the string date entered in the cell thanks to the defined format. 246 247 @library{wxcore} 248 @category{grid} 249 250 @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, 251 wxGridCellBoolRenderer, wxGridCellEnumRenderer, 252 wxGridCellFloatRenderer, wxGridCellNumberRenderer, 253 wxGridCellStringRenderer, wxGridCellDateRenderer 254 */ 255 class wxGridCellDateTimeRenderer : public wxGridCellDateRenderer 256 { 257 public: 258 /** 259 Date/time renderer constructor. 260 261 @param outformat 262 strptime()-like format string used the parse the output date/time. 263 @param informat 264 strptime()-like format string used to parse the string entered in the cell. 265 */ 266 wxGridCellDateTimeRenderer(const wxString& outformat = wxDefaultDateTimeFormat, 267 const wxString& informat = wxDefaultDateTimeFormat); 268 }; 269 270 /** 271 @class wxGridCellEnumRenderer 272 273 This class may be used to render in a cell a number as a textual 274 equivalent. 275 276 The corresponding text strings are specified as comma-separated items in 277 the string passed to this renderer ctor or SetParameters() method. For 278 example, if this string is @c "John,Fred,Bob" the cell will be rendered as 279 "John", "Fred" or "Bob" if its contents is 0, 1 or 2 respectively. 280 281 @library{wxcore} 282 @category{grid} 283 284 @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, 285 wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, 286 wxGridCellFloatRenderer, wxGridCellNumberRenderer, 287 wxGridCellStringRenderer 288 */ 289 class wxGridCellEnumRenderer : public wxGridCellStringRenderer 290 { 291 public: 292 /** 293 Enum renderer ctor. 294 295 @param choices 296 Comma separated string parameters "item1[,item2[...,itemN]]". 297 */ 298 wxGridCellEnumRenderer( const wxString& choices = wxEmptyString ); 299 300 /** 301 Sets the comma separated string content of the enum. 302 303 @param params 304 Comma separated string parameters "item1[,item2[...,itemN]]". 305 */ 306 virtual void SetParameters(const wxString& params); 307 }; 308 309 /** 310 Specifier used to format the data to string for the numbers handled by 311 wxGridCellFloatRenderer and wxGridCellFloatEditor. 312 313 @since 2.9.3 314 */ 315 enum wxGridCellFloatFormat 316 { 317 /// Decimal floating point (%f). 318 wxGRID_FLOAT_FORMAT_FIXED = 0x0010, 319 320 /// Scientific notation (mantissa/exponent) using e character (%e). 321 wxGRID_FLOAT_FORMAT_SCIENTIFIC = 0x0020, 322 323 /// Use the shorter of %e or %f (%g). 324 wxGRID_FLOAT_FORMAT_COMPACT = 0x0040, 325 326 /// To use in combination with one of the above formats for the upper 327 /// case version (%F/%E/%G) 328 wxGRID_FLOAT_FORMAT_UPPER = 0x0080, 329 330 /// The format used by default (wxGRID_FLOAT_FORMAT_FIXED). 331 wxGRID_FLOAT_FORMAT_DEFAULT = wxGRID_FLOAT_FORMAT_FIXED 332 }; 333 334 /** 335 @class wxGridCellFloatRenderer 336 337 This class may be used to format floating point data in a cell. 338 339 @library{wxcore} 340 @category{grid} 341 342 @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, 343 wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, 344 wxGridCellEnumRenderer, wxGridCellNumberRenderer, 345 wxGridCellStringRenderer 346 */ 347 class wxGridCellFloatRenderer : public wxGridCellStringRenderer 348 { 349 public: 350 /** 351 Float cell renderer ctor. 352 353 @param width 354 Minimum number of characters to be shown. 355 @param precision 356 Number of digits after the decimal dot. 357 @param format 358 The format used to display the string, must be a combination of 359 ::wxGridCellFloatFormat enum elements. This parameter is only 360 available since wxWidgets 2.9.3. 361 */ 362 wxGridCellFloatRenderer(int width = -1, int precision = -1, 363 int format = wxGRID_FLOAT_FORMAT_DEFAULT); 364 365 /** 366 Returns the specifier used to format the data to string. 367 368 The returned value is a combination of ::wxGridCellFloatFormat elements. 369 370 @since 2.9.3 371 */ 372 int GetFormat() const; 373 374 /** 375 Returns the precision. 376 */ 377 int GetPrecision() const; 378 379 /** 380 Returns the width. 381 */ 382 int GetWidth() const; 383 384 /** 385 Set the format to use for display the number. 386 387 @param format 388 Must be a combination of ::wxGridCellFloatFormat enum elements. 389 390 @since 2.9.3 391 */ 392 void SetFormat(int format); 393 394 /** 395 The parameters string format is "width[,precision[,format]]" where 396 @c format should be chosen between f|e|g|E|G (f is used by default) 397 */ 398 virtual void SetParameters(const wxString& params); 399 400 /** 401 Sets the precision. 402 */ 403 void SetPrecision(int precision); 404 405 /** 406 Sets the width. 407 */ 408 void SetWidth(int width); 409 }; 410 411 /** 412 @class wxGridCellNumberRenderer 413 414 This class may be used to format integer data in a cell. 415 416 @library{wxcore} 417 @category{grid} 418 419 @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, 420 wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, 421 wxGridCellEnumRenderer, wxGridCellFloatRenderer, 422 wxGridCellStringRenderer 423 */ 424 class wxGridCellNumberRenderer : public wxGridCellStringRenderer 425 { 426 public: 427 /** 428 Default constructor. 429 */ 430 wxGridCellNumberRenderer(); 431 }; 432 433 /** 434 @class wxGridCellStringRenderer 435 436 This class may be used to format string data in a cell; it is the default 437 for string cells. 438 439 @library{wxcore} 440 @category{grid} 441 442 @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, 443 wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, 444 wxGridCellEnumRenderer, wxGridCellFloatRenderer, 445 wxGridCellNumberRenderer 446 */ 447 class wxGridCellStringRenderer : public wxGridCellRenderer 448 { 449 public: 450 /** 451 Default constructor. 452 */ 453 wxGridCellStringRenderer(); 454 }; 455 456 457 /** 458 Represents a source of cell activation, which may be either a user event 459 (mouse or keyboard) or the program itself. 460 461 An object of this class is passed to wxGridCellEditor::TryActivate() by the 462 library and the code overriding this method may use its GetOrigin() method 463 to determine how exactly the cell is being activated. 464 465 @since 3.1.4 466 */ 467 class wxGridActivationSource 468 { 469 public: 470 /// Result of GetOrigin(). 471 enum Origin 472 { 473 /// Activated due to an explicit wxGrid::EnableCellEditControl() call. 474 Program, 475 476 /// Activated due to the user pressing a key, see GetKeyEvent(). 477 Key, 478 479 /// Activated due to the user clicking on a cell, see GetMouseEvent(). 480 Mouse 481 }; 482 483 /// Get the origin of the activation. 484 Origin GetOrigin() const; 485 486 /** 487 Get the key event corresponding to the key press activating the cell. 488 489 This method can be called for objects with Key origin only, use 490 GetOrigin() to check for this first. 491 */ 492 const wxKeyEvent& GetKeyEvent() const; 493 494 /** 495 Get the mouse event corresponding to the click activating the cell. 496 497 This method can be called for objects with Mouse origin only, use 498 GetOrigin() to check for this first. 499 */ 500 const wxMouseEvent& GetMouseEvent() const; 501 }; 502 503 /** 504 Represents the result of wxGridCellEditor::TryActivate(). 505 506 Editors overriding wxGridCellEditor::TryActivate() must use one of 507 DoNothing(), DoChange() or DoEdit() methods to return an object of this 508 type corresponding to the desired action. 509 510 @since 3.1.4 511 */ 512 class wxGridActivationResult 513 { 514 public: 515 /** 516 Indicate that nothing should be done and the cell shouldn't be edited 517 at all. 518 519 Note that this is different from DoEdit() and may be useful when the 520 value of the cell wouldn't change if it were activated anyhow, e.g. 521 because the key or mouse event carried by wxGridActivationSource would 522 leave the cell value unchanged. 523 */ 524 static wxGridActivationResult DoNothing(); 525 526 /** 527 Indicate that activating the cell is possible and would change its 528 value to the given one. 529 530 This is the method to call for activatable editors, using it will 531 result in changing the value of the cell to @a newval without showing 532 the editor control at all. 533 534 Note that the change may still be vetoed by wxEVT_GRID_CELL_CHANGING 535 handler. 536 */ 537 static wxGridActivationResult DoChange(const wxString& newval); 538 539 /** 540 Indicate that the editor control should be shown and the cell should be 541 edited normally. 542 543 This is the default return value of wxGridCellEditor::TryActivate(). 544 */ 545 static wxGridActivationResult DoEdit(); 546 }; 547 548 /** 549 @class wxGridCellEditor 550 551 This class is responsible for providing and manipulating the in-place edit 552 controls for the grid. Instances of wxGridCellEditor (actually, instances 553 of derived classes since it is an abstract class) can be associated with 554 the cell attributes for individual cells, rows, columns, or even for the 555 entire grid. 556 557 Normally wxGridCellEditor shows some UI control allowing the user to edit 558 the cell, but starting with wxWidgets 3.1.4 it's also possible to define 559 "activatable" cell editors, that change the value of the cell directly when 560 it's activated (typically by pressing Space key or clicking on it), see 561 TryActivate() method. Note that when implementing an editor which is always 562 activatable, i.e. never shows any in-place editor, it is more convenient to 563 derive its class from wxGridCellActivatableEditor than from wxGridCellEditor 564 itself. 565 566 @library{wxcore} 567 @category{grid} 568 569 @see wxGridCellAutoWrapStringEditor, wxGridCellBoolEditor, 570 wxGridCellChoiceEditor, wxGridCellEnumEditor, 571 wxGridCellFloatEditor, wxGridCellNumberEditor, 572 wxGridCellTextEditor, wxGridCellDateEditor 573 */ 574 class wxGridCellEditor : public wxClientDataContainer, public wxRefCounter 575 { 576 public: 577 /** 578 Default constructor. 579 */ 580 wxGridCellEditor(); 581 582 /** 583 Fetch the value from the table and prepare the edit control to begin 584 editing. 585 586 This function should save the original value of the grid cell at the 587 given @a row and @a col and show the control allowing the user to 588 change it. 589 590 @see EndEdit() 591 */ 592 virtual void BeginEdit(int row, int col, wxGrid* grid) = 0; 593 594 /** 595 Create a new object which is the copy of this one. 596 */ 597 virtual wxGridCellEditor* Clone() const = 0; 598 599 /** 600 Creates the actual edit control. 601 */ 602 virtual void Create(wxWindow* parent, wxWindowID id, 603 wxEvtHandler* evtHandler) = 0; 604 605 /** 606 Final cleanup. 607 */ 608 virtual void Destroy(); 609 610 /** 611 End editing the cell. 612 613 This function must check if the current value of the editing control is 614 valid and different from the original value (available as @a oldval in 615 its string form and possibly saved internally using its real type by 616 BeginEdit()). If it isn't, it just returns @false, otherwise it must do 617 the following: 618 - Save the new value internally so that ApplyEdit() could apply it. 619 - Fill @a newval (which is never @NULL) with the string 620 representation of the new value. 621 - Return @true 622 623 Notice that it must @em not modify the grid as the change could still 624 be vetoed. 625 626 If the user-defined wxEVT_GRID_CELL_CHANGING event handler doesn't veto 627 this change, ApplyEdit() will be called next. 628 */ 629 virtual bool EndEdit(int row, int col, const wxGrid* grid, 630 const wxString& oldval, wxString* newval) = 0; 631 632 /** 633 Effectively save the changes in the grid. 634 635 This function should save the value of the control in the grid. It is 636 called only after EndEdit() returns @true. 637 */ 638 virtual void ApplyEdit(int row, int col, wxGrid* grid) = 0; 639 640 /** 641 Some types of controls on some platforms may need some help with the 642 Return key. 643 */ 644 virtual void HandleReturn(wxKeyEvent& event); 645 646 /** 647 Returns @true if the edit control has been created. 648 */ 649 bool IsCreated(); 650 651 /** 652 Draws the part of the cell not occupied by the control: the base class 653 version just fills it with background colour from the attribute. 654 */ 655 virtual void PaintBackground(wxDC& dc, const wxRect& rectCell, const wxGridCellAttr& attr); 656 657 /** 658 Reset the value in the control back to its starting value. 659 */ 660 virtual void Reset() = 0; 661 662 /** 663 Size and position the edit control. 664 */ 665 virtual void SetSize(const wxRect& rect); 666 667 /** 668 Show or hide the edit control, use the specified attributes to set 669 colours/fonts for it. 670 */ 671 virtual void Show(bool show, wxGridCellAttr* attr = NULL); 672 673 /** 674 If the editor is enabled by clicking on the cell, this method will be 675 called. 676 */ 677 virtual void StartingClick(); 678 679 /** 680 If the editor is enabled by pressing keys on the grid, this will be 681 called to let the editor do something about that first key if desired. 682 */ 683 virtual void StartingKey(wxKeyEvent& event); 684 685 /** 686 Return @true to allow the given key to start editing: the base class 687 version only checks that the event has no modifiers. 688 689 If the key is F2 (special), editing will always start and this 690 method will not be called at all (but StartingKey() will) 691 */ 692 virtual bool IsAcceptedKey(wxKeyEvent& event); 693 694 695 /** 696 Returns the value currently in the editor control. 697 */ 698 virtual wxString GetValue() const = 0; 699 700 /** 701 Get the edit window used by this editor. 702 703 @since 3.1.3 704 */ 705 wxWindow* GetWindow() const; 706 707 /** 708 Set the wxWindow that will be used by this cell editor for editing the 709 value. 710 711 @since 3.1.3 712 */ 713 void SetWindow(wxWindow* window); 714 715 /** 716 Get the wxControl used by this editor. 717 718 This function is preserved for compatibility, but GetWindow() should be 719 preferred in the new code as the associated window doesn't need to be of 720 a wxControl-derived class. 721 722 Note that if SetWindow() had been called with an object not deriving 723 from wxControl, this method will return @NULL. 724 */ 725 wxControl* GetControl(); 726 727 /** 728 Set the wxControl that will be used by this cell editor for editing the 729 value. 730 731 This function is preserved for compatibility, but SetWindow() should be 732 preferred in the new code, see GetControl(). 733 */ 734 void SetControl(wxControl* control); 735 736 737 /** 738 Function allowing to create an "activatable" editor. 739 740 As explained in this class description, activatable editors don't show 741 any edit control but change the cell value directly, when it is 742 activated (by any way described by wxGridActivationSource). 743 744 To create such editor, this method must be overridden to return 745 wxGridActivationResult::DoChange() passing it the new value of the 746 cell. If the change is not vetoed by wxEVT_GRID_CELL_CHANGING handler, 747 DoActivate() will be called to actually change the value, so it must be 748 overridden as well if TryActivate() is overridden. 749 750 By default, wxGridActivationResult::DoEdit() is returned, meaning that 751 this is a normal editor, using an edit control for changing the cell 752 value. 753 754 @since 3.1.4 755 */ 756 virtual wxGridActivationResult 757 TryActivate(int row, int col, wxGrid* grid, 758 const wxGridActivationSource& actSource); 759 760 /** 761 Function which must be overridden for "activatable" editors. 762 763 If TryActivate() is overridden to return "change" action, this function 764 will be called to actually apply this change. Note that it is not 765 passed the value to apply, as it is assumed that the editor class 766 stores this value as a member variable anyhow. 767 768 @since 3.1.4 769 */ 770 virtual void DoActivate(int row, int col, wxGrid* grid); 771 772 protected: 773 774 /** 775 The destructor is private because only DecRef() can delete us. 776 */ 777 virtual ~wxGridCellEditor(); 778 }; 779 780 /** 781 Base class for activatable editors. 782 783 Inheriting from this class makes it simpler to implement editors that 784 support only activation, but not in-place editing, as they only need to 785 implement TryActivate(), DoActivate() and Clone() methods, but not all the 786 other pure virtual methods of wxGridCellEditor. 787 788 @since 3.1.4 789 */ 790 class wxGridCellActivatableEditor : public wxGridCellEditor 791 { 792 public: 793 /** 794 Same method as in wxGridCellEditor, but pure virtual. 795 796 Note that the implementation of this method must never return 797 wxGridActivationResult::DoEdit() for the editors inheriting from this 798 class, as it doesn't support normal editing. 799 */ 800 virtual wxGridActivationResult 801 TryActivate(int row, int col, wxGrid* grid, 802 const wxGridActivationSource& actSource) = 0; 803 804 /// Same method as in wxGridCellEditor, but pure virtual. 805 virtual void DoActivate(int row, int col, wxGrid* grid) = 0; 806 }; 807 808 /** 809 Smart pointer wrapping wxGridCellEditor. 810 811 wxGridCellEditorPtr takes ownership of wxGridCellEditor passed to it on 812 construction and calls DecRef() on it automatically when it is destroyed. 813 It also provides transparent access to wxGridCellEditor methods by allowing 814 to use objects of this class as if they were wxGridCellEditor pointers. 815 816 @since 3.1.4 817 818 @category{grid} 819 */ 820 typedef wxObjectDataPtr<wxGridCellEditor> wxGridCellEditorPtr; 821 822 /** 823 @class wxGridCellAutoWrapStringEditor 824 825 Grid cell editor for wrappable string/text data. 826 827 @library{wxcore} 828 @category{grid} 829 830 @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor, 831 wxGridCellEnumEditor, wxGridCellFloatEditor, 832 wxGridCellNumberEditor, wxGridCellTextEditor, 833 wxGridCellDateEditor 834 */ 835 class wxGridCellAutoWrapStringEditor : public wxGridCellTextEditor 836 { 837 public: 838 wxGridCellAutoWrapStringEditor(); 839 }; 840 841 /** 842 @class wxGridCellBoolEditor 843 844 Grid cell editor for boolean data. 845 846 @library{wxcore} 847 @category{grid} 848 849 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, 850 wxGridCellChoiceEditor, wxGridCellEnumEditor, 851 wxGridCellFloatEditor, wxGridCellNumberEditor, 852 wxGridCellTextEditor, wxGridCellDateEditor 853 */ 854 class wxGridCellBoolEditor : public wxGridCellEditor 855 { 856 public: 857 /** 858 Default constructor. 859 */ 860 wxGridCellBoolEditor(); 861 862 /** 863 Returns @true if the given @a value is equal to the string 864 representation of the truth value we currently use (see 865 UseStringValues()). 866 */ 867 static bool IsTrueValue(const wxString& value); 868 869 /** 870 This method allows you to customize the values returned by GetValue() 871 for the cell using this editor. By default, the default values of the 872 arguments are used, i.e. @c "1" is returned if the cell is checked and 873 an empty string otherwise. 874 */ 875 static void UseStringValues(const wxString& valueTrue = "1", 876 const wxString& valueFalse = wxEmptyString); 877 }; 878 879 /** 880 @class wxGridCellChoiceEditor 881 882 Grid cell editor for string data providing the user a choice from a list of 883 strings. 884 885 @library{wxcore} 886 @category{grid} 887 888 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, 889 wxGridCellBoolEditor, wxGridCellEnumEditor, 890 wxGridCellFloatEditor, wxGridCellNumberEditor, 891 wxGridCellTextEditor, wxGridCellDateEditor 892 */ 893 class wxGridCellChoiceEditor : public wxGridCellEditor 894 { 895 public: 896 /** 897 Choice cell renderer ctor. 898 899 @param count 900 Number of strings from which the user can choose. 901 @param choices 902 An array of strings from which the user can choose. 903 @param allowOthers 904 If allowOthers is @true, the user can type a string not in choices 905 array. 906 */ 907 wxGridCellChoiceEditor(size_t count = 0, 908 const wxString choices[] = NULL, 909 bool allowOthers = false); 910 911 /** 912 Choice cell renderer ctor. 913 914 @param choices 915 An array of strings from which the user can choose. 916 @param allowOthers 917 If allowOthers is @true, the user can type a string not in choices 918 array. 919 */ 920 wxGridCellChoiceEditor(const wxArrayString& choices, 921 bool allowOthers = false); 922 923 /** 924 Parameters string format is "item1[,item2[...,itemN]]". 925 926 This method can be called before the editor is used for the first time, 927 or later, in which case it replaces the previously specified strings 928 with the new ones. 929 */ 930 virtual void SetParameters(const wxString& params); 931 }; 932 933 /** 934 @class wxGridCellEnumEditor 935 936 Grid cell editor which displays an enum number as a textual equivalent 937 (e.g. data in cell is 0,1,2 ... n the cell could be displayed as 938 "John","Fred"..."Bob" in the combo choice box). 939 940 @library{wxcore} 941 @category{grid} 942 943 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, 944 wxGridCellBoolEditor, wxGridCellChoiceEditor, 945 wxGridCellTextEditor, wxGridCellFloatEditor, 946 wxGridCellNumberEditor, wxGridCellDateEditor 947 */ 948 class wxGridCellEnumEditor : public wxGridCellChoiceEditor 949 { 950 public: 951 /** 952 Enum cell editor ctor. 953 954 @param choices 955 Comma separated choice parameters "item1[,item2[...,itemN]]". 956 */ 957 wxGridCellEnumEditor( const wxString& choices = wxEmptyString ); 958 }; 959 960 /** 961 @class wxGridCellTextEditor 962 963 Grid cell editor for string/text data. 964 965 @library{wxcore} 966 @category{grid} 967 968 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, 969 wxGridCellBoolEditor, wxGridCellChoiceEditor, 970 wxGridCellEnumEditor, wxGridCellFloatEditor, 971 wxGridCellNumberEditor, wxGridCellDateEditor 972 */ 973 class wxGridCellTextEditor : public wxGridCellEditor 974 { 975 public: 976 /** 977 Text cell editor constructor. 978 979 @param maxChars 980 Maximum width of text (this parameter is supported starting since 981 wxWidgets 2.9.5). 982 */ 983 explicit wxGridCellTextEditor(size_t maxChars = 0); 984 985 /** 986 The parameters string format is "n" where n is a number representing 987 the maximum width. 988 */ 989 virtual void SetParameters(const wxString& params); 990 991 /** 992 Set validator to validate user input. 993 994 @since 2.9.5 995 */ 996 virtual void SetValidator(const wxValidator& validator); 997 }; 998 999 /** 1000 @class wxGridCellFloatEditor 1001 1002 The editor for floating point numbers data. 1003 1004 @library{wxcore} 1005 @category{grid} 1006 1007 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, 1008 wxGridCellBoolEditor, wxGridCellChoiceEditor, 1009 wxGridCellEnumEditor, wxGridCellNumberEditor, 1010 wxGridCellTextEditor, wxGridCellDateEditor 1011 */ 1012 class wxGridCellFloatEditor : public wxGridCellTextEditor 1013 { 1014 public: 1015 /** 1016 Float cell editor ctor. 1017 1018 @param width 1019 Minimum number of characters to be shown. 1020 @param precision 1021 Number of digits after the decimal dot. 1022 @param format 1023 The format to use for displaying the number, a combination of 1024 ::wxGridCellFloatFormat enum elements. This parameter is only 1025 available since wxWidgets 2.9.3. 1026 */ 1027 wxGridCellFloatEditor(int width = -1, int precision = -1, 1028 int format = wxGRID_FLOAT_FORMAT_DEFAULT); 1029 1030 /** 1031 The parameters string format is "width[,precision[,format]]" where 1032 @c format should be chosen between f|e|g|E|G (f is used by default) 1033 */ 1034 virtual void SetParameters(const wxString& params); 1035 }; 1036 1037 /** 1038 @class wxGridCellNumberEditor 1039 1040 Grid cell editor for numeric integer data. 1041 1042 @library{wxcore} 1043 @category{grid} 1044 1045 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, 1046 wxGridCellBoolEditor, wxGridCellChoiceEditor, 1047 wxGridCellEnumEditor, wxGridCellFloatEditor, 1048 wxGridCellTextEditor, wxGridCellDateEditor 1049 */ 1050 class wxGridCellNumberEditor : public wxGridCellTextEditor 1051 { 1052 public: 1053 /** 1054 Allows you to specify the range for acceptable data. Values equal to 1055 -1 for both @a min and @a max indicate that no range checking should be 1056 done. 1057 */ 1058 wxGridCellNumberEditor(int min = -1, int max = -1); 1059 1060 1061 /** 1062 Parameters string format is "min,max". 1063 */ 1064 virtual void SetParameters(const wxString& params); 1065 1066 protected: 1067 1068 /** 1069 If the return value is @true, the editor uses a wxSpinCtrl to get user 1070 input, otherwise it uses a wxTextCtrl. 1071 */ 1072 bool HasRange() const; 1073 1074 /** 1075 String representation of the value. 1076 */ 1077 wxString GetString() const; 1078 }; 1079 1080 /** 1081 @class wxGridCellDateEditor 1082 1083 Grid cell editor for dates. 1084 1085 Uses @ref wxDatePickerCtrl as actual edit control. 1086 1087 @library{wxcore} 1088 @category{grid} 1089 1090 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, 1091 wxGridCellBoolEditor, wxGridCellChoiceEditor, 1092 wxGridCellEnumEditor, wxGridCellFloatEditor, 1093 wxGridCellTextEditor 1094 1095 @since 3.1.3 1096 */ 1097 class wxGridCellDateEditor : public wxGridCellEditor 1098 { 1099 public: 1100 /** 1101 Date editor constructor. 1102 1103 @param format Optional format for the date displayed in the associated 1104 cell. By default, the locale-specific date format ("%x") is assumed. 1105 You would typically want to specify the same format as the one 1106 used with the cell renderer, if a non-default one is used. 1107 Note that this parameter is only available since wxWidgets 3.1.5. 1108 */ 1109 explicit wxGridCellDateEditor(const wxString& format = wxString()); 1110 }; 1111 1112 1113 1114 /** 1115 @class wxGridFitMode 1116 1117 Allows to specify the behaviour when the cell contents doesn't fit into its 1118 allotted space. 1119 1120 Objects of this class are used with wxGridCellAttr::SetFitMode() and 1121 wxGrid::SetDefaultCellFitMode() and wxGrid::SetCellFitMode() functions and 1122 allow to specify what should happen if the cell contents doesn't fit into 1123 the available space. The possibilities are: 1124 1125 - Overflow into the cell to the right if it is empty, or possibly several 1126 cells, if the cell contents still doesn't fit after overflowing into the 1127 immediately neighbouring cell. 1128 - Clip the cell contents, discarding the part which doesn't fit. 1129 - Ellipsize the cell contents, i.e. replace the non-fitting part with 1130 ellipsis (@c ...), putting the ellipsis at the end by default, but possibly 1131 at the beginning or in the middle. 1132 1133 The default behaviour is to overflow, use wxGrid::SetDefaultCellFitMode() 1134 to change this, for example: 1135 @code 1136 grid->SetDefaultCellFitMode(wxGridFitMode::Clip()); 1137 @endcode 1138 1139 Objects of this class are created using static functions instead of 1140 constructors for better readability and can't be changed after creating 1141 them except by using the assignment operator. 1142 1143 @library{wxcore} 1144 @category{grid} 1145 1146 @since 3.1.4 1147 */ 1148 class wxGridFitMode 1149 { 1150 public: 1151 /** 1152 Default constructor creates an object not specifying any behaviour. 1153 1154 This constructor is not very useful, use static methods Clip() and 1155 Overflow() below to create objects of this class instead. 1156 */ 1157 wxGridFitMode(); 1158 1159 /** 1160 Pseudo-constructor for object specifying clipping behaviour. 1161 */ 1162 static wxGridFitMode Clip(); 1163 1164 /** 1165 Pseudo-constructor for object specifying overflow behaviour. 1166 */ 1167 static wxGridFitMode Overflow(); 1168 1169 /** 1170 Pseudo-constructor for object specifying ellipsize behaviour. 1171 */ 1172 static wxGridFitMode Ellipsize(wxEllipsizeMode ellipsize = wxELLIPSIZE_END); 1173 1174 /** 1175 Return true if the object specifies some particular behaviour. 1176 1177 This method returns @false for default-constructed objects of this 1178 type only. 1179 */ 1180 bool IsSpecified() const; 1181 1182 /** 1183 Return true if the object specifies clipping behaviour. 1184 1185 This method returns @true only for the objects returned by Clip(). 1186 */ 1187 bool IsClip() const; 1188 1189 /** 1190 Return true if the object specifies overflow behaviour. 1191 1192 This method returns @true only for the objects returned by Overflow(). 1193 */ 1194 bool IsOverflow() const; 1195 1196 /** 1197 Return ellipsize mode, possibly @c wxELLIPSIZE_NONE. 1198 1199 For the objects constructed using Ellipsize(), the same ellipsization 1200 mode as was passed to it is returned. For all the other objects, 1201 ::wxELLIPSIZE_NONE is. 1202 */ 1203 wxEllipsizeMode GetEllipsizeMode() const; 1204 }; 1205 1206 /** 1207 @class wxGridCellAttr 1208 1209 This class can be used to alter the cells' appearance in the grid by 1210 changing their attributes from the defaults. An object of this class may be 1211 returned by wxGridTableBase::GetAttr(). 1212 1213 Note that objects of this class are reference-counted and it's recommended 1214 to use wxGridCellAttrPtr smart pointer class when working with them to 1215 avoid memory leaks. 1216 1217 @library{wxcore} 1218 @category{grid} 1219 */ 1220 class wxGridCellAttr : public wxClientDataContainer, public wxRefCounter 1221 { 1222 public: 1223 /** 1224 Kind of the attribute to retrieve. 1225 1226 @see wxGridCellAttrProvider::GetAttr(), wxGridTableBase::GetAttr() 1227 */ 1228 enum wxAttrKind 1229 { 1230 /// Return the combined effective attribute for the cell. 1231 Any, 1232 1233 /// Return the attribute explicitly set for this cell. 1234 Cell, 1235 1236 /// Return the attribute set for this cells row. 1237 Row, 1238 1239 /// Return the attribute set for this cells column. 1240 Col, 1241 1242 Default, 1243 Merged 1244 }; 1245 1246 /** 1247 Default constructor. 1248 */ 1249 explicit wxGridCellAttr(wxGridCellAttr* attrDefault = NULL); 1250 1251 /** 1252 Constructor specifying some of the often used attributes. 1253 */ 1254 wxGridCellAttr(const wxColour& colText, const wxColour& colBack, 1255 const wxFont& font, int hAlign, int vAlign); 1256 1257 /** 1258 Creates a new copy of this object. 1259 */ 1260 wxGridCellAttr* Clone() const; 1261 1262 /** 1263 This class is reference counted: it is created with ref count of 1, so 1264 calling DecRef() once will delete it. Calling IncRef() allows locking 1265 it until the matching DecRef() is called. 1266 */ 1267 void DecRef(); 1268 1269 /** 1270 Get the alignment to use for the cell with the given attribute. 1271 1272 If this attribute doesn't specify any alignment, the default attribute 1273 alignment is used (which can be changed using 1274 wxGrid::SetDefaultCellAlignment() but is left and top by default). 1275 1276 Notice that @a hAlign and @a vAlign values are always overwritten by 1277 this function, use GetNonDefaultAlignment() if this is not desirable. 1278 1279 @param hAlign 1280 Horizontal alignment is returned here if this argument is non-@NULL. 1281 It is one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT. 1282 @param vAlign 1283 Vertical alignment is returned here if this argument is non-@NULL. 1284 It is one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. 1285 */ 1286 void GetAlignment(int* hAlign, int* vAlign) const; 1287 1288 /** 1289 Returns the background colour. 1290 */ 1291 const wxColour& GetBackgroundColour() const; 1292 1293 /** 1294 Returns the cell editor. 1295 1296 The caller is responsible for calling DecRef() on the returned pointer, 1297 use GetEditorPtr() to do it automatically. 1298 */ 1299 wxGridCellEditor* GetEditor(const wxGrid* grid, int row, int col) const; 1300 1301 /** 1302 Returns the cell editor. 1303 1304 This method is identical to GetEditor(), but returns a smart pointer, 1305 which frees the caller from the need to call DecRef() manually. 1306 1307 @since 3.1.4 1308 */ 1309 wxGridCellEditorPtr GetEditorPtr(const wxGrid* grid, int row, int col) const; 1310 1311 /** 1312 Returns the font. 1313 */ 1314 const wxFont& GetFont() const; 1315 1316 /** 1317 Get the alignment defined by this attribute. 1318 1319 Unlike GetAlignment() this function only modifies @a hAlign and @a 1320 vAlign if this attribute does define a non-default alignment. This 1321 means that they must be initialized before calling this function and 1322 that their values will be preserved unchanged if they are different 1323 from wxALIGN_INVALID. 1324 1325 For example, the following fragment can be used to use the cell 1326 alignment if one is defined but right-align its contents by default 1327 (instead of left-aligning it by default) while still using the default 1328 vertical alignment: 1329 @code 1330 int hAlign = wxALIGN_RIGHT, 1331 vAlign = wxALIGN_INVALID; 1332 attr.GetNonDefaultAlignment(&hAlign, &vAlign); 1333 @endcode 1334 1335 @since 2.9.1 1336 */ 1337 void GetNonDefaultAlignment(int *hAlign, int *vAlign) const; 1338 1339 /** 1340 Returns the cell renderer. 1341 1342 The caller is responsible for calling DecRef() on the returned pointer, 1343 use GetRendererPtr() to do it automatically. 1344 */ 1345 wxGridCellRenderer* GetRenderer(const wxGrid* grid, int row, int col) const; 1346 1347 /** 1348 Returns the cell editor. 1349 1350 This method is identical to GetRenderer(), but returns a smart pointer, 1351 which frees the caller from the need to call DecRef() manually. 1352 1353 @since 3.1.4 1354 */ 1355 wxGridCellRendererPtr GetRendererPtr(const wxGrid* grid, int row, int col) const; 1356 1357 /** 1358 Returns the text colour. 1359 */ 1360 const wxColour& GetTextColour() const; 1361 1362 /** 1363 Returns @true if this attribute has a valid alignment set. 1364 */ 1365 bool HasAlignment() const; 1366 1367 /** 1368 Returns @true if this attribute has a valid background colour set. 1369 */ 1370 bool HasBackgroundColour() const; 1371 1372 /** 1373 Returns @true if this attribute has a valid cell editor set. 1374 */ 1375 bool HasEditor() const; 1376 1377 /** 1378 Returns @true if this attribute has a valid font set. 1379 */ 1380 bool HasFont() const; 1381 1382 /** 1383 Returns @true if this attribute has a valid cell renderer set. 1384 */ 1385 bool HasRenderer() const; 1386 1387 /** 1388 Returns @true if this attribute has a valid text colour set. 1389 */ 1390 bool HasTextColour() const; 1391 1392 /** 1393 This class is reference counted: it is created with ref count of 1, so 1394 calling DecRef() once will delete it. Calling IncRef() allows locking 1395 it until the matching DecRef() is called. 1396 */ 1397 void IncRef(); 1398 1399 /** 1400 Returns @true if this cell is set as read-only. 1401 */ 1402 bool IsReadOnly() const; 1403 1404 /** 1405 Sets the alignment. @a hAlign can be one of @c wxALIGN_LEFT, 1406 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT and @a vAlign can be one of 1407 @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM. 1408 */ 1409 void SetAlignment(int hAlign, int vAlign); 1410 1411 /** 1412 Sets the background colour. 1413 */ 1414 void SetBackgroundColour(const wxColour& colBack); 1415 1416 /** 1417 @todo Needs documentation. 1418 */ 1419 void SetDefAttr(wxGridCellAttr* defAttr); 1420 1421 /** 1422 Sets the editor to be used with the cells with this attribute. 1423 */ 1424 void SetEditor(wxGridCellEditor* editor); 1425 1426 /** 1427 Sets the font. 1428 */ 1429 void SetFont(const wxFont& font); 1430 1431 /** 1432 Sets the cell as read-only. 1433 */ 1434 void SetReadOnly(bool isReadOnly = true); 1435 1436 /** 1437 Sets the renderer to be used for cells with this attribute. Takes 1438 ownership of the pointer. 1439 */ 1440 void SetRenderer(wxGridCellRenderer* renderer); 1441 1442 /** 1443 Sets the text colour. 1444 */ 1445 void SetTextColour(const wxColour& colText); 1446 1447 1448 void MergeWith(wxGridCellAttr *mergefrom); 1449 1450 void SetSize(int num_rows, int num_cols); 1451 1452 /** 1453 Specifies the behaviour of the cell contents if it doesn't fit into the 1454 available space. 1455 1456 @see wxGridFitMode 1457 1458 @since 3.1.4 1459 */ 1460 void SetFitMode(wxGridFitMode fitMode); 1461 1462 /** 1463 Specifies if cells using this attribute should overflow or clip their 1464 contents. 1465 1466 This is the same as calling SetFitMode() with either 1467 wxGridFitMode::Overflow() or wxGridFitMode::Clip() argument depending 1468 on whether @a allow is @true or @false. 1469 1470 Prefer using SetFitMode() directly instead in the new code. 1471 */ 1472 void SetOverflow(bool allow = true); 1473 1474 void SetKind(wxAttrKind kind); 1475 1476 bool HasReadWriteMode() const; 1477 bool HasOverflowMode() const; 1478 bool HasSize() const; 1479 1480 void GetSize(int *num_rows, int *num_cols) const; 1481 1482 /** 1483 Returns the fitting mode for the cells using this attribute. 1484 1485 The returned wxGridFitMode is always specified, i.e. 1486 wxGridFitMode::IsSpecified() always returns @true. The default value, 1487 if SetFitMode() hadn't been called before, is "overflow". 1488 1489 @since 3.1.4 1490 */ 1491 wxGridFitMode GetFitMode() const; 1492 1493 /** 1494 Returns true if the cells using this attribute overflow into the 1495 neighbouring cells. 1496 1497 Prefer using GetFitMode() in the new code. 1498 */ 1499 bool GetOverflow() const; 1500 1501 /** 1502 Returns @true if the cell will draw an overflowed text into the 1503 neighbouring cells. 1504 1505 Note that only left aligned cells currently can overflow. It means that 1506 GetFitMode().IsOverflow() should returns true and GetAlignment should 1507 returns wxALIGN_LEFT for hAlign parameter. 1508 1509 @since 3.1.4 1510 */ 1511 bool CanOverflow() const; 1512 1513 wxAttrKind GetKind(); 1514 1515 1516 protected: 1517 1518 /** 1519 The destructor is private because only DecRef() can delete us. 1520 */ 1521 virtual ~wxGridCellAttr(); 1522 }; 1523 1524 /** 1525 Smart pointer wrapping wxGridCellAttr. 1526 1527 wxGridCellAttrPtr takes ownership of wxGridCellAttr passed to it on 1528 construction and calls DecRef() on it automatically when it is destroyed. 1529 It also provides transparent access to wxGridCellAttr methods by allowing 1530 to use objects of this class as if they were wxGridCellAttr pointers. 1531 1532 @since 3.1.4 1533 1534 @category{grid} 1535 */ 1536 typedef wxObjectDataPtr<wxGridCellAttr> wxGridCellAttrPtr; 1537 1538 /** 1539 Base class for header cells renderers. 1540 1541 A cell renderer can be used to draw the text of a cell's label, and/or 1542 the border around it. 1543 1544 @since 2.9.1 1545 */ 1546 class wxGridHeaderLabelsRenderer 1547 { 1548 public: 1549 /** 1550 Called by the grid to draw the border around the cell header. 1551 1552 This method is responsible for drawing the border inside the given @a 1553 rect and adjusting the rectangle size to correspond to the area inside 1554 the border, i.e. usually call wxRect::Deflate() to account for the 1555 border width. 1556 1557 @param grid 1558 The grid whose header cell window is being drawn. 1559 @param dc 1560 The device context to use for drawing. 1561 @param rect 1562 Input/output parameter which contains the border rectangle on input 1563 and should be updated to contain the area inside the border on 1564 function return. 1565 */ 1566 virtual void DrawBorder(const wxGrid& grid, 1567 wxDC& dc, 1568 wxRect& rect) const = 0; 1569 1570 /** 1571 Called by the grid to draw the specified label. 1572 1573 Notice that the DrawBorder() method is called before this one. 1574 1575 The default implementation uses wxGrid::GetLabelTextColour() and 1576 wxGrid::GetLabelFont() to draw the label. 1577 */ 1578 virtual void DrawLabel(const wxGrid& grid, 1579 wxDC& dc, 1580 const wxString& value, 1581 const wxRect& rect, 1582 int horizAlign, 1583 int vertAlign, 1584 int textOrientation) const; 1585 }; 1586 1587 /** 1588 Base class for row headers renderer. 1589 1590 This is the same as wxGridHeaderLabelsRenderer currently but we still use a 1591 separate class for it to distinguish it from wxGridColumnHeaderRenderer 1592 and wxGridCornerHeaderRenderer. 1593 1594 @see wxGridRowHeaderRendererDefault 1595 1596 @see wxGridCellAttrProvider::GetRowHeaderRenderer() 1597 1598 @since 2.9.1 1599 */ 1600 class wxGridRowHeaderRenderer : public wxGridHeaderLabelsRenderer 1601 { 1602 }; 1603 1604 /** 1605 Base class for column headers renderer. 1606 1607 This is the same as wxGridHeaderLabelsRenderer currently but we still use a 1608 separate class for it to distinguish it from wxGridRowHeaderRenderer and 1609 wxGridCornerHeaderRenderer. 1610 1611 @see wxGridColumnHeaderRendererDefault 1612 1613 @see wxGridCellAttrProvider::GetColumnHeaderRenderer() 1614 1615 @since 2.9.1 1616 */ 1617 class wxGridColumnHeaderRenderer : public wxGridHeaderLabelsRenderer 1618 { 1619 }; 1620 1621 /** 1622 Base class for corner header renderer. 1623 1624 This is the same as wxGridHeaderLabelsRenderer currently but we still use a 1625 separate class for it to distinguish it from wxGridRowHeaderRenderer and 1626 wxGridColumnHeaderRenderer. 1627 1628 @see wxGridCornerHeaderRendererDefault 1629 1630 @see wxGridCellAttrProvider::GetCornerRenderer() 1631 1632 @since 2.9.1 1633 */ 1634 class wxGridCornerHeaderRenderer : public wxGridHeaderLabelsRenderer 1635 { 1636 }; 1637 1638 /** 1639 Default row header renderer. 1640 1641 You may derive from this class if you need to only override one of its 1642 methods (i.e. either DrawLabel() or DrawBorder()) but continue to use the 1643 default implementation for the other one. 1644 1645 @see wxGridColumnHeaderRendererDefault, wxGridCornerHeaderRendererDefault 1646 1647 @since 2.9.1 1648 */ 1649 class wxGridRowHeaderRendererDefault : public wxGridRowHeaderRenderer 1650 { 1651 public: 1652 /// Implement border drawing for the row labels. 1653 virtual void DrawBorder(const wxGrid& grid, 1654 wxDC& dc, 1655 wxRect& rect) const; 1656 }; 1657 1658 /** 1659 Default column header renderer. 1660 1661 @see wxGridRowHeaderRendererDefault, wxGridCornerHeaderRendererDefault 1662 1663 @since 2.9.1 1664 */ 1665 class wxGridColumnHeaderRendererDefault : public wxGridColumnHeaderRenderer 1666 { 1667 public: 1668 /// Implement border drawing for the column labels. 1669 virtual void DrawBorder(const wxGrid& grid, 1670 wxDC& dc, 1671 wxRect& rect) const; 1672 }; 1673 1674 /** 1675 Default corner window renderer. 1676 1677 @see wxGridColumnHeaderRendererDefault, wxGridRowHeaderRendererDefault 1678 1679 @since 2.9.1 1680 */ 1681 class wxGridCornerHeaderRendererDefault : public wxGridCornerHeaderRenderer 1682 { 1683 public: 1684 /// Implement border drawing for the corner window. 1685 virtual void DrawBorder(const wxGrid& grid, 1686 wxDC& dc, 1687 wxRect& rect) const; 1688 }; 1689 1690 /** 1691 Class providing attributes to be used for the grid cells. 1692 1693 This class both defines an interface which grid cell attributes providers 1694 should implement -- and which can be implemented differently in derived 1695 classes -- and a default implementation of this interface which is often 1696 good enough to be used without modification, especially with not very large 1697 grids for which the efficiency of attributes storage hardly matters (see 1698 the discussion below). 1699 1700 An object of this class can be associated with a wxGrid using 1701 wxGridTableBase::SetAttrProvider() but it's not necessary to call it if you 1702 intend to use the default provider as it is used by wxGridTableBase by 1703 default anyhow. 1704 1705 Notice that while attributes provided by this class can be set for 1706 individual cells using SetAttr() or the entire rows or columns using 1707 SetRowAttr() and SetColAttr() they are always retrieved using GetAttr() 1708 function. 1709 1710 1711 The default implementation of this class stores the attributes passed to 1712 its SetAttr(), SetRowAttr() and SetColAttr() in a straightforward way. A 1713 derived class may use its knowledge about how the attributes are used in 1714 your program to implement it much more efficiently: for example, using a 1715 special background colour for all even-numbered rows can be implemented by 1716 simply returning the same attribute from GetAttr() if the row number is 1717 even instead of having to store N/2 row attributes where N is the total 1718 number of rows in the grid. 1719 1720 Notice that objects of this class can't be copied. 1721 */ 1722 class wxGridCellAttrProvider : public wxClientDataContainer 1723 { 1724 public: 1725 /// Trivial default constructor. 1726 wxGridCellAttrProvider(); 1727 1728 /// Destructor releases any attributes held by this class. 1729 virtual ~wxGridCellAttrProvider(); 1730 1731 /** 1732 Get the attribute to use for the specified cell. 1733 1734 If wxGridCellAttr::Any is used as @a kind value, this function combines 1735 the attributes set for this cell using SetAttr() and those for its row 1736 or column (set with SetRowAttr() or SetColAttr() respectively), with 1737 the cell attribute having the highest precedence. 1738 1739 Notice that the caller must call DecRef() on the returned pointer if it 1740 is non-@NULL. GetAttrPtr() method can be used to do this automatically. 1741 1742 @param row 1743 The row of the cell. 1744 @param col 1745 The column of the cell. 1746 @param kind 1747 The kind of the attribute to return. 1748 @return 1749 The attribute to use which should be DecRef()'d by caller or @NULL 1750 if no attributes are defined for this cell. 1751 */ 1752 virtual wxGridCellAttr *GetAttr(int row, int col, 1753 wxGridCellAttr::wxAttrKind kind) const; 1754 1755 /** 1756 Get the attribute to use for the specified cell. 1757 1758 This method is identical to GetAttr(), but returns a smart pointer, 1759 which frees the caller from the need to call DecRef() manually. 1760 1761 @since 3.1.4 1762 */ 1763 wxGridCellAttrPtr GetAttrPtr(int row, int col, 1764 wxGridCellAttr::wxAttrKind kind) const; 1765 1766 /*! 1767 @name Setting attributes. 1768 1769 All these functions take ownership of the attribute passed to them, 1770 i.e. will call DecRef() on it themselves later and so it should not be 1771 destroyed by the caller. The attribute can be @NULL to reset a 1772 previously set value. 1773 */ 1774 //@{ 1775 1776 /// Set attribute for the specified cell. 1777 virtual void SetAttr(wxGridCellAttr *attr, int row, int col); 1778 1779 /// Set attribute for the specified row. 1780 virtual void SetRowAttr(wxGridCellAttr *attr, int row); 1781 1782 /// Set attribute for the specified column. 1783 virtual void SetColAttr(wxGridCellAttr *attr, int col); 1784 1785 //@} 1786 1787 /** 1788 @name Getting header renderers. 1789 1790 These functions return the renderers for the given row or column header 1791 label and the corner window. Unlike cell attributes, these objects are 1792 not reference counted and are never @NULL so they are returned by 1793 reference and not pointer and DecRef() shouldn't (and can't) be called 1794 for them. 1795 1796 All these functions were added in wxWidgets 2.9.1. 1797 */ 1798 //@{ 1799 1800 /** 1801 Return the renderer used for drawing column headers. 1802 1803 By default wxGridColumnHeaderRendererDefault is returned. 1804 1805 @see wxGrid::SetUseNativeColLabels(), wxGrid::UseNativeColHeader() 1806 1807 @since 2.9.1 1808 */ 1809 virtual const wxGridColumnHeaderRenderer& GetColumnHeaderRenderer(int col); 1810 1811 /** 1812 Return the renderer used for drawing row headers. 1813 1814 By default wxGridRowHeaderRendererDefault is returned. 1815 1816 @since 2.9.1 1817 */ 1818 virtual const wxGridRowHeaderRenderer& GetRowHeaderRenderer(int row); 1819 1820 /** 1821 Return the renderer used for drawing the corner window. 1822 1823 By default wxGridCornerHeaderRendererDefault is returned. 1824 1825 @since 2.9.1 1826 */ 1827 virtual const wxGridCornerHeaderRenderer& GetCornerRenderer(); 1828 1829 //@} 1830 }; 1831 1832 /** 1833 Message class used by the grid table to send requests and notifications to 1834 the grid view. 1835 1836 A message object of this class must be sent to the grid using 1837 wxGrid::ProcessTableMessage() every time the table changes, e.g. rows are 1838 added/deleted. The messages are just notifications and don't result in any 1839 actual changes but just allow the view to react to changes to the model. 1840 */ 1841 class wxGridTableMessage 1842 { 1843 public: 1844 /** 1845 Default constructor initializes the object to invalid state. 1846 */ 1847 wxGridTableMessage(); 1848 1849 /** 1850 Constructor really initialize the message. 1851 1852 @param table Pointer to the grid table 1853 @param id One of wxGridTableRequest enum elements. 1854 @param comInt1 Position after which the rows are inserted/deleted 1855 @param comInt2 Number of rows to be inserted/deleted 1856 */ 1857 wxGridTableMessage(wxGridTableBase *table, int id, int comInt1 = -1, int comInt2 = -1); 1858 1859 /** 1860 Sets the table object 1861 */ 1862 void SetTableObject( wxGridTableBase *table ); 1863 1864 /** 1865 Gets the table object 1866 */ 1867 wxGridTableBase * GetTableObject() const; 1868 1869 /** 1870 Sets an id 1871 */ 1872 void SetId( int id ); 1873 1874 /** 1875 Gets an id 1876 */ 1877 int GetId() const; 1878 1879 /** 1880 Set the position after which the insertion/deletion occur 1881 */ 1882 void SetCommandInt( int comInt1 ); 1883 1884 /** 1885 Get the position after which the insertion/deletion occur 1886 */ 1887 int GetCommandInt() const; 1888 1889 /** 1890 Set the number of rows to be inserted/deleted 1891 */ 1892 void SetCommandInt2( int comInt2 ); 1893 1894 /** 1895 Get the number of rows to be inserted/deleted 1896 */ 1897 int GetCommandInt2() const; 1898 }; 1899 1900 1901 /** 1902 Simplest type of data table for a grid for small tables of strings that are 1903 stored in memory. 1904 1905 The number of rows and columns in the table can be specified initially but 1906 may also be changed later dynamically. 1907 */ 1908 class wxGridStringTable 1909 { 1910 public: 1911 /** 1912 Default constructor creates an empty table. 1913 */ 1914 wxGridStringTable(); 1915 1916 /** 1917 Constructor taking number of rows and columns. 1918 */ 1919 wxGridStringTable( int numRows, int numCols ); 1920 1921 virtual int GetNumberRows(); 1922 virtual int GetNumberCols(); 1923 virtual wxString GetValue( int row, int col ); 1924 virtual void SetValue( int row, int col, const wxString& s ); 1925 1926 void Clear(); 1927 bool InsertRows( size_t pos = 0, size_t numRows = 1 ); 1928 bool AppendRows( size_t numRows = 1 ); 1929 bool DeleteRows( size_t pos = 0, size_t numRows = 1 ); 1930 bool InsertCols( size_t pos = 0, size_t numCols = 1 ); 1931 bool AppendCols( size_t numCols = 1 ); 1932 bool DeleteCols( size_t pos = 0, size_t numCols = 1 ); 1933 1934 void SetRowLabelValue( int row, const wxString& ); 1935 void SetColLabelValue( int col, const wxString& ); 1936 void SetCornerLabelValue( const wxString& ); 1937 wxString GetRowLabelValue( int row ); 1938 wxString GetColLabelValue( int col ); 1939 wxString GetCornerLabelValue() const; 1940 }; 1941 1942 /** 1943 Represents coordinates of a grid cell. 1944 1945 An object of this class is simply a (row, column) pair. 1946 */ 1947 class wxGridCellCoords 1948 { 1949 public: 1950 /** 1951 Default constructor initializes the object to invalid state. 1952 1953 Initially the row and column are both invalid (-1) and so operator!() 1954 for an uninitialized wxGridCellCoords returns false. 1955 */ 1956 wxGridCellCoords(); 1957 1958 /** 1959 Constructor taking a row and a column. 1960 */ 1961 wxGridCellCoords(int row, int col); 1962 1963 /** 1964 Return the row of the coordinate. 1965 */ 1966 int GetRow() const; 1967 1968 /** 1969 Set the row of the coordinate. 1970 */ 1971 void SetRow(int n); 1972 1973 /** 1974 Return the column of the coordinate. 1975 */ 1976 int GetCol() const; 1977 1978 /** 1979 Set the column of the coordinate. 1980 */ 1981 void SetCol(int n); 1982 1983 /** 1984 Set the row and column of the coordinate. 1985 */ 1986 void Set(int row, int col); 1987 1988 /** 1989 Assignment operator for coordinate types. 1990 */ 1991 wxGridCellCoords& operator=(const wxGridCellCoords& other); 1992 1993 /** 1994 Equality operator. 1995 */ 1996 bool operator==(const wxGridCellCoords& other) const; 1997 1998 /** 1999 Inequality operator. 2000 */ 2001 bool operator!=(const wxGridCellCoords& other) const; 2002 2003 /** 2004 Checks whether the coordinates are invalid. 2005 2006 Returns false only if both row and column are -1. Notice that if either 2007 row or column (but not both) are -1, this method returns true even if 2008 the object is invalid. This is done because objects in such state 2009 should actually never exist, i.e. either both coordinates should be -1 2010 or none of them should be -1. 2011 */ 2012 bool operator!() const; 2013 }; 2014 2015 /** 2016 Represents coordinates of a block of cells in the grid. 2017 2018 An object of this class contains coordinates of the left top and the bottom right 2019 corners of a block. 2020 2021 @since 3.1.4 2022 */ 2023 class wxGridBlockCoords 2024 { 2025 public: 2026 /** 2027 Default constructor initializes the object to invalid state. 2028 2029 Initially the coordinates are invalid (-1) and so operator!() for an 2030 uninitialized wxGridBlockCoords returns @true. 2031 */ 2032 wxGridBlockCoords(); 2033 2034 /** 2035 Constructor taking a coordinates of the left top and the bottom right 2036 corners. 2037 */ 2038 wxGridBlockCoords(int topRow, int leftCol, int bottomRow, int rightCol); 2039 2040 /** 2041 Return the row of the left top corner. 2042 */ 2043 int GetTopRow() const; 2044 2045 /** 2046 Set the row of the left top corner. 2047 */ 2048 void SetTopRow(int row); 2049 2050 /** 2051 Return the column of the left top corner. 2052 */ 2053 int GetLeftCol() const; 2054 2055 /** 2056 Set the column of the left top corner. 2057 */ 2058 void SetLeftCol(int col); 2059 2060 /** 2061 Return the row of the bottom right corner. 2062 */ 2063 int GetBottomRow() const; 2064 2065 /** 2066 Set the row of the bottom right corner. 2067 */ 2068 void SetBottomRow(int row); 2069 2070 /** 2071 Return the column of the bottom right corner. 2072 */ 2073 int GetRightCol() const; 2074 2075 /** 2076 Set the column of the bottom right corner. 2077 */ 2078 void SetRightCol(int col); 2079 2080 /** 2081 Return the coordinates of the top left corner. 2082 */ GetTopLeft()2083 wxGridCellCoords GetTopLeft() const 2084 { 2085 return wxGridCellCoords(m_topRow, m_leftCol); 2086 } 2087 2088 /** 2089 Return the coordinates of the bottom right corner. 2090 */ GetBottomRight()2091 wxGridCellCoords GetBottomRight() const 2092 { 2093 return wxGridCellCoords(m_bottomRow, m_rightCol); 2094 } 2095 2096 /** 2097 Return the canonicalized block where top left coordinates is less 2098 then bottom right coordinates. 2099 */ 2100 wxGridBlockCoords Canonicalize() const; 2101 2102 /** 2103 Whether the blocks intersect. 2104 2105 @return 2106 @true, if the block intersects with the other, @false, otherwise. 2107 */ Intersects(const wxGridBlockCoords & other)2108 bool Intersects(const wxGridBlockCoords& other) const 2109 { 2110 return m_topRow <= other.m_bottomRow && m_bottomRow >= other.m_topRow && 2111 m_leftCol <= other.m_rightCol && m_rightCol >= other.m_leftCol; 2112 } 2113 2114 /** 2115 Check whether this block contains the given cell. 2116 2117 @return 2118 @true, if the block contains the cell, @false otherwise. 2119 */ 2120 bool Contains(const wxGridCellCoords& cell) const; 2121 2122 /** 2123 Check whether this block contains another one. 2124 2125 @return 2126 @true if @a other is entirely contained within this block. 2127 */ 2128 bool Contains(const wxGridBlockCoords& other) const; 2129 2130 /** 2131 Calculates the result blocks by subtracting the other block from this 2132 block. 2133 2134 @param other 2135 The block to subtract from this block. 2136 @param splitOrientation 2137 The block splitting orientation (either @c wxHORIZONTAL or 2138 @c wxVERTICAL). 2139 @return 2140 Up to 4 blocks. If block doesn't exist in the result, it has value 2141 of @c wxGridNoBlockCoords. 2142 */ 2143 wxGridBlockDiffResult 2144 Difference(const wxGridBlockCoords& other, int splitOrientation) const; 2145 2146 /** 2147 Calculates the symmetric difference of the blocks. 2148 2149 @param other 2150 The block to subtract from this block. 2151 @return 2152 Up to 4 blocks. If block doesn't exist in the result, it has value 2153 of @c wxGridNoBlockCoords. 2154 */ 2155 wxGridBlockDiffResult 2156 SymDifference(const wxGridBlockCoords& other) const; 2157 2158 /** 2159 Equality operator. 2160 */ 2161 bool operator==(const wxGridBlockCoords& other) const; 2162 2163 /** 2164 Inequality operator. 2165 */ 2166 bool operator!=(const wxGridBlockCoords& other) const; 2167 2168 /** 2169 Checks whether the cells block is invalid. 2170 2171 Returns @true only if all components are -1. Notice that if one 2172 of the components (but not all) is -1, this method returns @false even 2173 if the object is invalid. This is done because objects in such state 2174 should actually never exist, i.e. either all components should be -1 2175 or none of them should be -1. 2176 */ 2177 bool operator!() const; 2178 2179 private: 2180 int m_topRow; 2181 int m_leftCol; 2182 int m_bottomRow; 2183 int m_rightCol; 2184 }; 2185 2186 /** 2187 @class wxGridBlockDiffResult 2188 2189 The helper struct uses as a result type for difference functions of 2190 @c wxGridBlockCoords class. 2191 2192 Parts can be uninitialized (equals to @c wxGridNoBlockCoords), that means 2193 that the corresponding part doesn't exists in the result. 2194 2195 @since 3.1.4 2196 */ 2197 struct wxGridBlockDiffResult 2198 { 2199 wxGridBlockCoords m_parts[4]; 2200 }; 2201 2202 /** 2203 Represents a collection of grid blocks that can be iterated over. 2204 2205 This class provides read-only access to the blocks making up the grid 2206 selection in the most general case. 2207 2208 Note that objects of this class can only be returned by wxGrid, but not 2209 constructed in the application code. 2210 2211 The preferable way to iterate over it is using C++11 range-for loop: 2212 @code 2213 for ( const auto& block: grid->GetSelectedBlocks() ) { 2214 ... do something with block ... 2215 } 2216 @endcode 2217 When not using C++11, iteration has to be done manually: 2218 @code 2219 wxGridBlocks range = grid->GetSelectedBlocks(); 2220 for ( wxGridBlocks::iterator it = range.begin(); 2221 it != range.end(); 2222 ++it ) { 2223 ... do something with *it ... 2224 } 2225 @endcode 2226 2227 @since 3.1.4 2228 */ 2229 class wxGridBlocks 2230 { 2231 public: 2232 /** 2233 Read-only forward iterator type. 2234 2235 This is an opaque type, which satisfies the forward iterator 2236 requirements, i.e. provides all the expected operations, such as 2237 comparison, dereference and pre- and post-increment. 2238 */ 2239 class iterator 2240 { 2241 iterator(); 2242 2243 const wxGridBlockCoords& operator*() const; 2244 const wxGridBlockCoords* operator->() const; 2245 2246 iterator& operator++(); 2247 iterator operator++(int); 2248 2249 bool operator==(const iterator& it) const; 2250 bool operator!=(const iterator& it) const; 2251 }; 2252 2253 /// Return iterator corresponding to the beginning of the range. 2254 iterator begin() const; 2255 2256 /// Return iterator corresponding to the end of the range. 2257 iterator end() const; 2258 }; 2259 2260 /** 2261 @class wxGridTableBase 2262 2263 The almost abstract base class for grid tables. 2264 2265 A grid table is responsible for storing the grid data and, indirectly, grid 2266 cell attributes. The data can be stored in the way most convenient for the 2267 application but has to be provided in string form to wxGrid. It is also 2268 possible to provide cells values in other formats if appropriate, e.g. as 2269 numbers. 2270 2271 This base class is not quite abstract as it implements a trivial strategy 2272 for storing the attributes by forwarding it to wxGridCellAttrProvider and 2273 also provides stubs for some other functions. However it does have a number 2274 of pure virtual methods which must be implemented in the derived classes. 2275 2276 @see wxGridStringTable 2277 2278 @library{wxcore} 2279 @category{grid} 2280 */ 2281 class wxGridTableBase : public wxObject 2282 { 2283 public: 2284 /** 2285 Default constructor. 2286 */ 2287 wxGridTableBase(); 2288 2289 /** 2290 Destructor frees the attribute provider if it was created. 2291 */ 2292 virtual ~wxGridTableBase(); 2293 2294 /** 2295 Must be overridden to return the number of rows in the table. 2296 2297 For backwards compatibility reasons, this method is not const. 2298 Use GetRowsCount() instead of it in const methods of derived table 2299 classes. 2300 */ 2301 virtual int GetNumberRows() = 0; 2302 2303 /** 2304 Must be overridden to return the number of columns in the table. 2305 2306 For backwards compatibility reasons, this method is not const. 2307 Use GetColsCount() instead of it in const methods of derived table 2308 classes, 2309 */ 2310 virtual int GetNumberCols() = 0; 2311 2312 /** 2313 Return the number of rows in the table. 2314 2315 This method is not virtual and is only provided as a convenience for 2316 the derived classes which can't call GetNumberRows() without a 2317 @c const_cast from their const methods. 2318 */ 2319 int GetRowsCount() const; 2320 2321 /** 2322 Return the number of columns in the table. 2323 2324 This method is not virtual and is only provided as a convenience for 2325 the derived classes which can't call GetNumberCols() without a 2326 @c const_cast from their const methods. 2327 */ 2328 int GetColsCount() const; 2329 2330 2331 /** 2332 @name Table Cell Accessors 2333 */ 2334 //@{ 2335 2336 /** 2337 May be overridden to implement testing for empty cells. 2338 2339 This method is used by the grid to test if the given cell is not used 2340 and so whether a neighbouring cell may overflow into it. By default it 2341 only returns true if the value of the given cell, as returned by 2342 GetValue(), is empty. 2343 */ 2344 virtual bool IsEmptyCell(int row, int col); 2345 2346 /** 2347 Same as IsEmptyCell() but taking wxGridCellCoords. 2348 2349 Notice that this method is not virtual, only IsEmptyCell() should be 2350 overridden. 2351 */ 2352 bool IsEmpty(const wxGridCellCoords& coords); 2353 2354 /** 2355 Must be overridden to implement accessing the table values as text. 2356 */ 2357 virtual wxString GetValue(int row, int col) = 0; 2358 2359 /** 2360 Must be overridden to implement setting the table values as text. 2361 */ 2362 virtual void SetValue(int row, int col, const wxString& value) = 0; 2363 2364 /** 2365 Returns the type of the value in the given cell. 2366 2367 By default all cells are strings and this method returns 2368 @c wxGRID_VALUE_STRING. 2369 */ 2370 virtual wxString GetTypeName(int row, int col); 2371 2372 /** 2373 Returns true if the value of the given cell can be accessed as if it 2374 were of the specified type. 2375 2376 By default the cells can only be accessed as strings. Note that a cell 2377 could be accessible in different ways, e.g. a numeric cell may return 2378 @true for @c wxGRID_VALUE_NUMBER but also for @c wxGRID_VALUE_STRING 2379 indicating that the value can be coerced to a string form. 2380 */ 2381 virtual bool CanGetValueAs(int row, int col, const wxString& typeName); 2382 2383 /** 2384 Returns true if the value of the given cell can be set as if it were of 2385 the specified type. 2386 2387 @see CanGetValueAs() 2388 */ 2389 virtual bool CanSetValueAs(int row, int col, const wxString& typeName); 2390 2391 /** 2392 Returns the value of the given cell as a long. 2393 2394 This should only be called if CanGetValueAs() returns @true when called 2395 with @c wxGRID_VALUE_NUMBER argument. Default implementation always 2396 return 0. 2397 */ 2398 virtual long GetValueAsLong(int row, int col); 2399 2400 /** 2401 Returns the value of the given cell as a double. 2402 2403 This should only be called if CanGetValueAs() returns @true when called 2404 with @c wxGRID_VALUE_FLOAT argument. Default implementation always 2405 return 0.0. 2406 */ 2407 virtual double GetValueAsDouble(int row, int col); 2408 2409 /** 2410 Returns the value of the given cell as a boolean. 2411 2412 This should only be called if CanGetValueAs() returns @true when called 2413 with @c wxGRID_VALUE_BOOL argument. Default implementation always 2414 return false. 2415 */ 2416 virtual bool GetValueAsBool(int row, int col); 2417 2418 /** 2419 Returns the value of the given cell as a user-defined type. 2420 2421 This should only be called if CanGetValueAs() returns @true when called 2422 with @a typeName. Default implementation always return @NULL. 2423 2424 Note that if the pointer is not null, it will be deleted by the caller, 2425 so it must be allocated on the heap by any class overriding this 2426 method. In practice, it means that the value stored internally must be 2427 cloned on every call. 2428 */ 2429 virtual void *GetValueAsCustom(int row, int col, const wxString& typeName); 2430 2431 /** 2432 Sets the value of the given cell as a long. 2433 2434 This should only be called if CanSetValueAs() returns @true when called 2435 with @c wxGRID_VALUE_NUMBER argument. Default implementation doesn't do 2436 anything. 2437 */ 2438 virtual void SetValueAsLong(int row, int col, long value); 2439 2440 /** 2441 Sets the value of the given cell as a double. 2442 2443 This should only be called if CanSetValueAs() returns @true when called 2444 with @c wxGRID_VALUE_FLOAT argument. Default implementation doesn't do 2445 anything. 2446 */ 2447 virtual void SetValueAsDouble(int row, int col, double value); 2448 2449 /** 2450 Sets the value of the given cell as a boolean. 2451 2452 This should only be called if CanSetValueAs() returns @true when called 2453 with @c wxGRID_VALUE_BOOL argument. Default implementation doesn't do 2454 anything. 2455 */ 2456 virtual void SetValueAsBool( int row, int col, bool value ); 2457 2458 /** 2459 Sets the value of the given cell as a user-defined type. 2460 2461 This should only be called if CanSetValueAs() returns @true when called 2462 with @a typeName. Default implementation doesn't do anything. 2463 */ 2464 virtual void SetValueAsCustom(int row, int col, const wxString& typeName, 2465 void *value); 2466 2467 //@} 2468 2469 2470 /** 2471 Called by the grid when the table is associated with it. 2472 2473 The default implementation stores the pointer and returns it from its 2474 GetView() and so only makes sense if the table cannot be associated 2475 with more than one grid at a time. 2476 */ 2477 virtual void SetView(wxGrid *grid); 2478 2479 /** 2480 Returns the last grid passed to SetView(). 2481 */ 2482 virtual wxGrid *GetView() const; 2483 2484 2485 /*! 2486 @name Table Structure Modifiers 2487 2488 Note that none of these functions are pure virtual as they don't have 2489 to be implemented if the table structure is never modified after 2490 creation, i.e. neither rows nor columns are ever added or deleted. 2491 2492 Also note that you do need to implement them if they are called, i.e. if your 2493 code either calls them directly or uses the matching wxGrid methods, as 2494 by default they simply do nothing which is definitely inappropriate. 2495 */ 2496 //@{ 2497 2498 /** 2499 Clear the table contents. 2500 2501 This method is used by wxGrid::ClearGrid(). 2502 */ 2503 virtual void Clear(); 2504 2505 /** 2506 Insert additional rows into the table. 2507 2508 @param pos 2509 The position of the first new row. 2510 @param numRows 2511 The number of rows to insert. 2512 */ 2513 virtual bool InsertRows(size_t pos = 0, size_t numRows = 1); 2514 2515 /** 2516 Append additional rows at the end of the table. 2517 2518 This method is provided in addition to InsertRows() as some data models 2519 may only support appending rows to them but not inserting them at 2520 arbitrary locations. In such case you may implement this method only 2521 and leave InsertRows() unimplemented. 2522 2523 @param numRows 2524 The number of rows to add. 2525 */ 2526 virtual bool AppendRows(size_t numRows = 1); 2527 2528 /** 2529 Delete rows from the table. 2530 2531 @param pos 2532 The first row to delete. 2533 @param numRows 2534 The number of rows to delete. 2535 */ 2536 virtual bool DeleteRows(size_t pos = 0, size_t numRows = 1); 2537 2538 /** 2539 Exactly the same as InsertRows() but for columns. 2540 */ 2541 virtual bool InsertCols(size_t pos = 0, size_t numCols = 1); 2542 2543 /** 2544 Exactly the same as AppendRows() but for columns. 2545 */ 2546 virtual bool AppendCols(size_t numCols = 1); 2547 2548 /** 2549 Exactly the same as DeleteRows() but for columns. 2550 */ 2551 virtual bool DeleteCols(size_t pos = 0, size_t numCols = 1); 2552 2553 //@} 2554 2555 /*! 2556 @name Table Row, Column and Corner Labels 2557 2558 By default the numbers are used for labelling rows and Latin letters for 2559 labelling columns. If the table has more than 26 columns, the pairs of 2560 letters are used starting from the 27-th one and so on, i.e. the 2561 sequence of labels is A, B, ..., Z, AA, AB, ..., AZ, BA, ..., ..., ZZ, 2562 AAA, ... 2563 2564 A cell in the top-left corner of a grid can also have a label. It is 2565 empty by default. Use wxGrid::SetCornerLabelValue() to set it and 2566 wxGrid::GetCornerLabelValue() to get its' current value. 2567 2568 @see wxGridTableBase::GetCornerLabelValue, wxGridTableBase::SetCornerLabelValue 2569 */ 2570 //@{ 2571 2572 /** 2573 Return the label of the specified row. 2574 */ 2575 virtual wxString GetRowLabelValue(int row); 2576 2577 /** 2578 Return the label of the specified column. 2579 */ 2580 virtual wxString GetColLabelValue(int col); 2581 2582 /** 2583 Return the label of the grid's corner. 2584 2585 @since 3.1.2 2586 */ 2587 virtual wxString GetCornerLabelValue() const; 2588 2589 /** 2590 Set the given label for the specified row. 2591 2592 The default version does nothing, i.e. the label is not stored. You 2593 must override this method in your derived class if you wish 2594 wxGrid::SetRowLabelValue() to work. 2595 */ 2596 virtual void SetRowLabelValue(int row, const wxString& label); 2597 2598 /** 2599 Exactly the same as SetRowLabelValue() but for columns. 2600 */ 2601 virtual void SetColLabelValue(int col, const wxString& label); 2602 2603 /** 2604 Set the given label for the grid's corner. 2605 2606 The default version does nothing, i.e. the label is not stored. You 2607 must override this method in your derived class if you wish 2608 wxGrid::GetCornerLabelValue() to work. 2609 2610 @since 3.1.2 2611 */ 2612 virtual void SetCornerLabelValue( const wxString& ); 2613 2614 //@} 2615 2616 2617 /** 2618 @name Attributes Management 2619 2620 By default the attributes management is delegated to 2621 wxGridCellAttrProvider class. You may override the methods in this 2622 section to handle the attributes directly if, for example, they can be 2623 computed from the cell values. 2624 */ 2625 //@{ 2626 2627 /** 2628 Associate this attributes provider with the table. 2629 2630 The table takes ownership of @a attrProvider pointer and will delete it 2631 when it doesn't need it any more. The pointer can be @NULL, however 2632 this won't disable attributes management in the table but will just 2633 result in a default attributes being recreated the next time any of the 2634 other functions in this section is called. To completely disable the 2635 attributes support, should this be needed, you need to override 2636 CanHaveAttributes() to return @false. 2637 */ 2638 void SetAttrProvider(wxGridCellAttrProvider *attrProvider); 2639 2640 /** 2641 Returns the attribute provider currently being used. 2642 2643 This function may return @NULL if the attribute provider hasn't been 2644 neither associated with this table by SetAttrProvider() nor created on 2645 demand by any other methods. 2646 */ 2647 wxGridCellAttrProvider *GetAttrProvider() const; 2648 2649 /** 2650 Return the attribute for the given cell. 2651 2652 By default this function is simply forwarded to 2653 wxGridCellAttrProvider::GetAttr() but it may be overridden to handle 2654 attributes directly in the table. 2655 2656 Prefer to use GetAttrPtr() to avoid the need to call DecRef() on the 2657 returned pointer manually. 2658 */ 2659 virtual wxGridCellAttr *GetAttr(int row, int col, 2660 wxGridCellAttr::wxAttrKind kind); 2661 2662 /** 2663 Return the attribute for the given cell. 2664 2665 This method is identical to GetAttr(), but returns a smart pointer, 2666 which frees the caller from the need to call DecRef() manually. 2667 2668 @since 3.1.4 2669 */ 2670 wxGridCellAttrPtr GetAttrPtr(int row, int col, 2671 wxGridCellAttr::wxAttrKind kind); 2672 2673 /** 2674 Set attribute of the specified cell. 2675 2676 By default this function is simply forwarded to 2677 wxGridCellAttrProvider::SetAttr(). 2678 2679 The table takes ownership of @a attr, i.e. will call DecRef() on it. 2680 */ 2681 virtual void SetAttr(wxGridCellAttr* attr, int row, int col); 2682 2683 /** 2684 Set attribute of the specified row. 2685 2686 By default this function is simply forwarded to 2687 wxGridCellAttrProvider::SetRowAttr(). 2688 2689 The table takes ownership of @a attr, i.e. will call DecRef() on it. 2690 */ 2691 virtual void SetRowAttr(wxGridCellAttr *attr, int row); 2692 2693 /** 2694 Set attribute of the specified column. 2695 2696 By default this function is simply forwarded to 2697 wxGridCellAttrProvider::SetColAttr(). 2698 2699 The table takes ownership of @a attr, i.e. will call DecRef() on it. 2700 */ 2701 virtual void SetColAttr(wxGridCellAttr *attr, int col); 2702 2703 //@} 2704 2705 /** 2706 Returns true if this table supports attributes or false otherwise. 2707 2708 By default, the table automatically creates a wxGridCellAttrProvider 2709 when this function is called if it had no attribute provider before and 2710 returns @true. 2711 */ 2712 virtual bool CanHaveAttributes(); 2713 2714 /** 2715 Override to return true if the same attribute can be used for measuring 2716 all cells in the given column. 2717 2718 This function is provided for optimization purposes: it returns @false 2719 by default, but can be overridden to return @true when all the cells in 2720 the same grid column use sensibly the same attribute, i.e. they use the 2721 same renderer (either explicitly, or implicitly, due to their type as 2722 returned by GetTypeName()) and the font of the same size. 2723 2724 Returning @true from this function allows AutoSizeColumns() to skip 2725 looking up the attribute and the renderer for each individual cell, 2726 which results in very noticeable performance improvements for the grids 2727 with many rows. 2728 2729 @since 3.1.4 2730 */ 2731 virtual bool CanMeasureColUsingSameAttr(int col) const; 2732 }; 2733 2734 2735 /** 2736 Possible types for grid table notifications. 2737 */ 2738 enum wxGridTableRequest 2739 { 2740 /// New rows have been inserted into the table. 2741 wxGRIDTABLE_NOTIFY_ROWS_INSERTED, 2742 /// New rows have been append to the table. 2743 wxGRIDTABLE_NOTIFY_ROWS_APPENDED, 2744 /// Rows have been deleted from the table. 2745 wxGRIDTABLE_NOTIFY_ROWS_DELETED, 2746 /// New columns have been inserted into the table. 2747 wxGRIDTABLE_NOTIFY_COLS_INSERTED, 2748 /// New columns have been append to the table. 2749 wxGRIDTABLE_NOTIFY_COLS_APPENDED, 2750 /// Columns have been deleted from the table. 2751 wxGRIDTABLE_NOTIFY_COLS_DELETED 2752 }; 2753 2754 2755 2756 /** 2757 @class wxGridSizesInfo 2758 2759 wxGridSizesInfo stores information about sizes of all wxGrid rows or 2760 columns. 2761 2762 It assumes that most of the rows or columns (which are both called elements 2763 here as the difference between them doesn't matter at this class level) 2764 have the default size and so stores it separately. And it uses a wxHashMap 2765 to store the sizes of all elements which have the non-default size. 2766 2767 This structure is particularly useful for serializing the sizes of all 2768 wxGrid elements at once. 2769 2770 @library{wxcore} 2771 @category{grid} 2772 */ 2773 struct wxGridSizesInfo 2774 { 2775 /** 2776 Default constructor. 2777 2778 m_sizeDefault and m_customSizes must be initialized later. 2779 */ 2780 wxGridSizesInfo(); 2781 2782 /** 2783 Constructor. 2784 2785 This constructor is used by wxGrid::GetRowSizes() and GetColSizes() 2786 methods. User code will usually use the default constructor instead. 2787 2788 @param defSize 2789 The default element size. 2790 @param allSizes 2791 Array containing the sizes of @em all elements, including those 2792 which have the default size. 2793 */ 2794 wxGridSizesInfo(int defSize, const wxArrayInt& allSizes); 2795 2796 /** 2797 Get the element size. 2798 2799 @param pos 2800 The index of the element. 2801 @return 2802 The size for this element, using m_customSizes if @a pos is in it 2803 or m_sizeDefault otherwise. 2804 */ 2805 int GetSize(unsigned pos) const; 2806 2807 2808 /// Default size 2809 int m_sizeDefault; 2810 2811 /** 2812 Map with element indices as keys and their sizes as values. 2813 2814 This map only contains the elements with non-default size. 2815 */ 2816 wxUnsignedToIntHashMap m_customSizes; 2817 }; 2818 2819 2820 2821 /** 2822 Rendering styles supported by wxGrid::Render() method. 2823 2824 @since 2.9.4 2825 */ 2826 enum wxGridRenderStyle 2827 { 2828 /// Draw grid row header labels. 2829 wxGRID_DRAW_ROWS_HEADER = 0x001, 2830 2831 /// Draw grid column header labels. 2832 wxGRID_DRAW_COLS_HEADER = 0x002, 2833 2834 /// Draw grid cell border lines. 2835 wxGRID_DRAW_CELL_LINES = 0x004, 2836 2837 /** 2838 Draw a bounding rectangle around the rendered cell area. 2839 2840 Useful where row or column headers are not drawn or where there is 2841 multi row or column cell clipping and therefore no cell border at 2842 the rendered outer boundary. 2843 */ 2844 wxGRID_DRAW_BOX_RECT = 0x008, 2845 2846 /** 2847 Draw the grid cell selection highlight if a selection is present. 2848 2849 At present the highlight colour drawn depends on whether the grid 2850 window loses focus before drawing begins. 2851 */ 2852 wxGRID_DRAW_SELECTION = 0x010, 2853 2854 /** 2855 The default render style. 2856 2857 Includes all except wxGRID_DRAW_SELECTION. 2858 */ 2859 wxGRID_DRAW_DEFAULT = wxGRID_DRAW_ROWS_HEADER | 2860 wxGRID_DRAW_COLS_HEADER | 2861 wxGRID_DRAW_CELL_LINES | 2862 wxGRID_DRAW_BOX_RECT 2863 }; 2864 2865 2866 2867 /** 2868 @class wxGrid 2869 2870 wxGrid and its related classes are used for displaying and editing tabular 2871 data. They provide a rich set of features for display, editing, and 2872 interacting with a variety of data sources. For simple applications, and to 2873 help you get started, wxGrid is the only class you need to refer to 2874 directly. It will set up default instances of the other classes and manage 2875 them for you. For more complex applications you can derive your own classes 2876 for custom grid views, grid data tables, cell editors and renderers. The 2877 @ref overview_grid has examples of simple and more complex applications, 2878 explains the relationship between the various grid classes and has a 2879 summary of the keyboard shortcuts and mouse functions provided by wxGrid. 2880 2881 A wxGridTableBase class holds the actual data to be displayed by a wxGrid 2882 class. One or more wxGrid classes may act as a view for one table class. 2883 The default table class is called wxGridStringTable and holds an array of 2884 strings. An instance of such a class is created by CreateGrid(). 2885 2886 wxGridCellRenderer is the abstract base class for rendering contents in a 2887 cell. The following renderers are predefined: 2888 2889 - wxGridCellBoolRenderer 2890 - wxGridCellFloatRenderer 2891 - wxGridCellNumberRenderer 2892 - wxGridCellStringRenderer 2893 - wxGridCellDateRenderer 2894 - wxGridCellDateTimeRenderer 2895 2896 The look of a cell can be further defined using wxGridCellAttr. An object 2897 of this type may be returned by wxGridTableBase::GetAttr(). 2898 2899 wxGridCellEditor is the abstract base class for editing the value of a 2900 cell. The following editors are predefined: 2901 2902 - wxGridCellBoolEditor 2903 - wxGridCellChoiceEditor 2904 - wxGridCellFloatEditor 2905 - wxGridCellNumberEditor 2906 - wxGridCellTextEditor 2907 - wxGridCellDateEditor 2908 2909 Please see wxGridEvent, wxGridSizeEvent, wxGridRangeSelectEvent, and 2910 wxGridEditorCreatedEvent for the documentation of all event types you can 2911 use with wxGrid. 2912 2913 @library{wxcore} 2914 @category{grid} 2915 2916 @see @ref overview_grid, wxGridUpdateLocker 2917 */ 2918 class wxGrid : public wxScrolledCanvas 2919 { 2920 public: 2921 2922 /** 2923 Different selection modes supported by the grid. 2924 */ 2925 enum wxGridSelectionModes 2926 { 2927 /** 2928 The default selection mode allowing selection of the individual 2929 cells as well as of the entire rows and columns. 2930 */ 2931 wxGridSelectCells, 2932 2933 /** 2934 The selection mode allowing the selection of the entire rows only. 2935 2936 The user won't be able to select any cells or columns in this mode. 2937 */ 2938 wxGridSelectRows, 2939 2940 /** 2941 The selection mode allowing the selection of the entire columns only. 2942 2943 The user won't be able to select any cells or rows in this mode. 2944 */ 2945 wxGridSelectColumns, 2946 2947 /** 2948 The selection mode allowing the user to select either the entire 2949 columns or the entire rows but not individual cells nor blocks. 2950 2951 Notice that while this constant is defined as @code 2952 wxGridSelectColumns | wxGridSelectRows @endcode this doesn't mean 2953 that all the other combinations are valid -- at least currently 2954 they are not. 2955 2956 @since 2.9.1 2957 */ 2958 wxGridSelectRowsOrColumns, 2959 2960 /** 2961 The selection mode allowing no selections to be made at all. 2962 2963 The user won't be able to select any cells in this mode. 2964 2965 @since 3.1.5 2966 */ 2967 wxGridSelectNone 2968 }; 2969 2970 /** 2971 Return values for GetCellSize(). 2972 2973 @since 2.9.1 2974 */ 2975 enum CellSpan 2976 { 2977 /// This cell is inside a span covered by another cell. 2978 CellSpan_Inside = -1, 2979 2980 /// This is a normal, non-spanning cell. 2981 CellSpan_None = 0, 2982 2983 /// This cell spans several physical wxGrid cells. 2984 CellSpan_Main 2985 }; 2986 2987 /** 2988 Constants defining different support built-in TAB handling behaviours. 2989 2990 The elements of this enum determine what happens when TAB is pressed 2991 when the cursor is in the rightmost column (or Shift-TAB is pressed 2992 when the cursor is in the leftmost one). 2993 2994 @see SetTabBehaviour(), @c wxEVT_GRID_TABBING 2995 2996 @since 2.9.5 2997 */ 2998 enum TabBehaviour 2999 { 3000 /// Do nothing, this is default. 3001 Tab_Stop, 3002 3003 /// Move to the beginning of the next (or the end of the previous) row. 3004 Tab_Wrap, 3005 3006 /// Move to the next (or the previous) control after the grid. 3007 Tab_Leave 3008 }; 3009 3010 /** 3011 @name Constructors and Initialization 3012 */ 3013 //@{ 3014 3015 /** 3016 Default constructor. 3017 3018 You must call Create() to really create the grid window and also call 3019 CreateGrid() or SetTable() or AssignTable() to initialize its contents. 3020 */ 3021 wxGrid(); 3022 /** 3023 Constructor creating the grid window. 3024 3025 You must call either CreateGrid() or SetTable() or AssignTable() to 3026 initialize the grid contents before using it. 3027 */ 3028 wxGrid(wxWindow* parent, wxWindowID id, 3029 const wxPoint& pos = wxDefaultPosition, 3030 const wxSize& size = wxDefaultSize, 3031 long style = wxWANTS_CHARS, 3032 const wxString& name = wxGridNameStr); 3033 3034 /** 3035 Destructor. 3036 3037 This will also destroy the associated grid table unless you passed a 3038 table object to the grid and specified that the grid should not take 3039 ownership of the table (see SetTable()). 3040 */ 3041 virtual ~wxGrid(); 3042 3043 /** 3044 Creates the grid window for an object initialized using the default 3045 constructor. 3046 3047 You must call either CreateGrid() or SetTable() or AssignTable() to 3048 initialize the grid contents before using it. 3049 */ 3050 bool Create(wxWindow* parent, wxWindowID id, 3051 const wxPoint& pos = wxDefaultPosition, 3052 const wxSize& size = wxDefaultSize, 3053 long style = wxWANTS_CHARS, 3054 const wxString& name = wxGridNameStr); 3055 3056 /** 3057 Creates a grid with the specified initial number of rows and columns. 3058 3059 Call this directly after the grid constructor. When you use this 3060 function wxGrid will create and manage a simple table of string values 3061 for you. All of the grid data will be stored in memory. 3062 3063 For applications with more complex data types or relationships, or for 3064 dealing with very large datasets, you should derive your own grid table 3065 class and pass a table object to the grid with SetTable() or 3066 AssignTable(). 3067 */ 3068 bool CreateGrid(int numRows, int numCols, 3069 wxGridSelectionModes selmode = wxGridSelectCells); 3070 3071 /** 3072 Passes a pointer to a custom grid table to be used by the grid. 3073 3074 This should be called after the grid constructor and before using the 3075 grid object. If @a takeOwnership is set to @true then the table will be 3076 deleted by the wxGrid destructor. 3077 3078 Use this function instead of CreateGrid() when your application 3079 involves complex or non-string data or data sets that are too large to 3080 fit wholly in memory. 3081 3082 When the custom table should be owned by the grid, consider using the 3083 simpler AssignTable() function instead of this one with @true value of 3084 @a takeOwnership parameter. 3085 */ 3086 bool SetTable(wxGridTableBase* table, bool takeOwnership = false, 3087 wxGridSelectionModes selmode = wxGridSelectCells); 3088 3089 /** 3090 Assigns a pointer to a custom grid table to be used by the grid. 3091 3092 This function is identical to SetTable() with @c takeOwnership 3093 parameter set to @true, i.e. it simply always takes the ownership of 3094 the passed in pointer. This makes it simpler to use than SetTable() in 3095 the common case when the table should be owned by the grid object. 3096 3097 Note that this function should be called at most once and can't be used 3098 to change the table used by the grid later on or reset it: if such 3099 extra flexibility is needed, use SetTable() directly. 3100 3101 @since 3.1.4 3102 3103 @param table The heap-allocated pointer to the table. 3104 @param selmode Selection mode to use. 3105 */ 3106 void AssignTable( wxGridTableBase *table, 3107 wxGridSelectionModes selmode = wxGridSelectCells); 3108 3109 /** 3110 Receive and handle a message from the table. 3111 */ 3112 bool ProcessTableMessage(wxGridTableMessage& msg); 3113 3114 //@} 3115 3116 3117 /** 3118 @name Grid Line Formatting 3119 */ 3120 //@{ 3121 3122 /** 3123 Turns the drawing of grid lines on or off. 3124 */ 3125 void EnableGridLines(bool enable = true); 3126 3127 /** 3128 Returns the pen used for vertical grid lines. 3129 3130 This virtual function may be overridden in derived classes in order to 3131 change the appearance of individual grid lines for the given column 3132 @a col. 3133 3134 See GetRowGridLinePen() for an example. 3135 */ 3136 virtual wxPen GetColGridLinePen(int col); 3137 3138 /** 3139 Returns the pen used for grid lines. 3140 3141 This virtual function may be overridden in derived classes in order to 3142 change the appearance of grid lines. Note that currently the pen width 3143 must be 1. 3144 3145 @see GetColGridLinePen(), GetRowGridLinePen() 3146 */ 3147 virtual wxPen GetDefaultGridLinePen(); 3148 3149 /** 3150 Returns the colour used for grid lines. 3151 3152 @see GetDefaultGridLinePen() 3153 */ 3154 wxColour GetGridLineColour() const; 3155 3156 /** 3157 Returns the pen used for horizontal grid lines. 3158 3159 This virtual function may be overridden in derived classes in order to 3160 change the appearance of individual grid line for the given @a row. 3161 3162 Example: 3163 @code 3164 // in a grid displaying music notation, use a solid black pen between 3165 // octaves (C0=row 127, C1=row 115 etc.) 3166 wxPen MidiGrid::GetRowGridLinePen(int row) 3167 { 3168 if ( row % 12 == 7 ) 3169 return wxPen(*wxBLACK, 1, wxPENSTYLE_SOLID); 3170 else 3171 return GetDefaultGridLinePen(); 3172 } 3173 @endcode 3174 */ 3175 virtual wxPen GetRowGridLinePen(int row); 3176 3177 /** 3178 Returns @true if drawing of grid lines is turned on, @false otherwise. 3179 */ 3180 bool GridLinesEnabled() const; 3181 3182 /** 3183 Sets the colour used to draw grid lines. 3184 */ 3185 void SetGridLineColour(const wxColour& colour); 3186 3187 //@} 3188 3189 3190 /** 3191 @name Label Values and Formatting 3192 */ 3193 //@{ 3194 3195 /** 3196 Sets the arguments to the current column label alignment values. 3197 3198 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE 3199 or @c wxALIGN_RIGHT. 3200 3201 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or 3202 @c wxALIGN_BOTTOM. 3203 */ 3204 void GetColLabelAlignment(int* horiz, int* vert) const; 3205 3206 /** 3207 Returns the orientation of the column labels (either @c wxHORIZONTAL or 3208 @c wxVERTICAL). 3209 */ 3210 int GetColLabelTextOrientation() const; 3211 3212 /** 3213 Returns the specified column label. 3214 3215 The default grid table class provides column labels of the form 3216 A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can 3217 override wxGridTableBase::GetColLabelValue() to provide your own 3218 labels. 3219 */ 3220 wxString GetColLabelValue(int col) const; 3221 3222 /** 3223 Sets the arguments to the current corner label alignment values. 3224 3225 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE 3226 or @c wxALIGN_RIGHT. 3227 3228 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or 3229 @c wxALIGN_BOTTOM. 3230 3231 @since 3.1.2 3232 */ 3233 void GetCornerLabelAlignment( int *horiz, int *vert ) const; 3234 3235 /** 3236 Returns the orientation of the corner label (either @c wxHORIZONTAL or 3237 @c wxVERTICAL). 3238 3239 @since 3.1.2 3240 */ 3241 int GetCornerLabelTextOrientation() const; 3242 3243 /** 3244 Returns the (top-left) corner label. 3245 3246 @since 3.1.2 3247 */ 3248 wxString GetCornerLabelValue() const; 3249 3250 /** 3251 Returns the colour used for the background of row and column labels. 3252 */ 3253 wxColour GetLabelBackgroundColour() const; 3254 3255 /** 3256 Returns the font used for row and column labels. 3257 */ 3258 wxFont GetLabelFont() const; 3259 3260 /** 3261 Returns the colour used for row and column label text. 3262 */ 3263 wxColour GetLabelTextColour() const; 3264 3265 /** 3266 Returns the alignment used for row labels. 3267 3268 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE 3269 or @c wxALIGN_RIGHT. 3270 3271 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or 3272 @c wxALIGN_BOTTOM. 3273 */ 3274 void GetRowLabelAlignment(int* horiz, int* vert) const; 3275 3276 /** 3277 Returns the specified row label. 3278 3279 The default grid table class provides numeric row labels. If you are 3280 using a custom grid table you can override 3281 wxGridTableBase::GetRowLabelValue() to provide your own labels. 3282 */ 3283 wxString GetRowLabelValue(int row) const; 3284 3285 /** 3286 Hides the column labels by calling SetColLabelSize() with a size of 0. 3287 3288 The labels can be shown again by calling SetColLabelSize() with a 3289 height greater than 0. 3290 3291 Note that when the column labels are hidden, the grid won't have any 3292 visible border on the top side, which may result in a less than ideal 3293 appearance. Because of this, you may want to create the grid window 3294 with a border style, such as @c wxBORDER_SIMPLE, when you don't plan to 3295 show the column labels for it. 3296 3297 @see HideRowLabels() 3298 */ 3299 void HideColLabels(); 3300 3301 /** 3302 Hides the row labels by calling SetRowLabelSize() with a size of 0. 3303 3304 The labels can be shown again by calling SetRowLabelSize() with a width 3305 greater than 0. 3306 3307 See HideColLabels() for a note explaining why you may want to use a 3308 border with a grid without the row labels. 3309 */ 3310 void HideRowLabels(); 3311 3312 /** 3313 Sets the horizontal and vertical alignment of column label text. 3314 3315 Horizontal alignment should be one of @c wxALIGN_LEFT, 3316 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one 3317 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM. 3318 */ 3319 void SetColLabelAlignment(int horiz, int vert); 3320 3321 /** 3322 Sets the orientation of the column labels (either @c wxHORIZONTAL or 3323 @c wxVERTICAL). 3324 */ 3325 void SetColLabelTextOrientation(int textOrientation); 3326 3327 /** 3328 Set the value for the given column label. 3329 3330 If you are using a custom grid table you must override 3331 wxGridTableBase::SetColLabelValue() for this to have any effect. 3332 */ 3333 void SetColLabelValue(int col, const wxString& value); 3334 3335 /** 3336 Sets the horizontal and vertical alignment of the (top-left) corner label text. 3337 3338 Horizontal alignment should be one of @c wxALIGN_LEFT, 3339 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one 3340 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM. 3341 3342 @since 3.1.2 3343 */ 3344 void SetCornerLabelAlignment( int horiz, int vert ); 3345 3346 /** 3347 Sets the orientation of the (top-left) corner label (either @c wxHORIZONTAL or 3348 @c wxVERTICAL). 3349 3350 @since 3.1.2 3351 */ 3352 void SetCornerLabelTextOrientation( int textOrientation ); 3353 3354 /** 3355 Set the value for the (top-left) corner label. 3356 3357 If you are using a custom grid table you must override 3358 wxGridTableBase::SetCornerLabelValue() for this to have any effect. 3359 3360 @since 3.1.2 3361 */ 3362 void SetCornerLabelValue( const wxString& ); 3363 3364 /** 3365 Sets the background colour for row and column labels. 3366 */ 3367 void SetLabelBackgroundColour(const wxColour& colour); 3368 3369 /** 3370 Sets the font for row and column labels. 3371 */ 3372 void SetLabelFont(const wxFont& font); 3373 3374 /** 3375 Sets the colour for row and column label text. 3376 */ 3377 void SetLabelTextColour(const wxColour& colour); 3378 3379 /** 3380 Sets the horizontal and vertical alignment of row label text. 3381 3382 Horizontal alignment should be one of @c wxALIGN_LEFT, 3383 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one 3384 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM. 3385 */ 3386 void SetRowLabelAlignment(int horiz, int vert); 3387 3388 /** 3389 Sets the value for the given row label. 3390 3391 If you are using a derived grid table you must override 3392 wxGridTableBase::SetRowLabelValue() for this to have any effect. 3393 */ 3394 void SetRowLabelValue(int row, const wxString& value); 3395 3396 /** 3397 Call this in order to make the column labels use a native look by using 3398 wxRendererNative::DrawHeaderButton() internally. 3399 3400 There is no equivalent method for drawing row columns as there is not 3401 native look for that. This option is useful when using wxGrid for 3402 displaying tables and not as a spread-sheet. 3403 3404 @see UseNativeColHeader() 3405 */ 3406 void SetUseNativeColLabels(bool native = true); 3407 3408 /** 3409 Enable the use of native header window for column labels. 3410 3411 If this function is called with @true argument, a wxHeaderCtrl is used 3412 instead to display the column labels instead of drawing them in wxGrid 3413 code itself. This has the advantage of making the grid look and feel 3414 perfectly the same as native applications (using SetUseNativeColLabels() 3415 the grid can be made to look more natively but it still doesn't feel 3416 natively, notably the column resizing and dragging still works slightly 3417 differently as it is implemented in wxWidgets itself) but results in 3418 different behaviour for column and row headers, for which there is no 3419 equivalent function, and, most importantly, is unsuitable for grids 3420 with huge numbers of columns as wxHeaderCtrl doesn't support virtual 3421 mode. Because of this, by default the grid does not use the native 3422 header control but you should call this function to enable it if you 3423 are using the grid to display tabular data and don't have thousands of 3424 columns in it. 3425 3426 Another difference between the default behaviour and the native header 3427 behaviour is that the latter provides the user with a context menu 3428 (which appears on right clicking the header) allowing to rearrange the 3429 grid columns if CanDragColMove() returns @true. If you want to prevent 3430 this from happening for some reason, you need to define a handler for 3431 @c wxEVT_GRID_LABEL_RIGHT_CLICK event which simply does nothing (in 3432 particular doesn't skip the event) as this will prevent the default 3433 right click handling from working. 3434 3435 Also note that currently @c wxEVT_GRID_LABEL_RIGHT_DCLICK event is not 3436 generated for the column labels if the native columns header is used 3437 (but this limitation could possibly be lifted in the future). 3438 3439 Finally, please note that using the native control is currently 3440 incompatible with freezing columns in the grid (see FreezeTo()) and 3441 this function will return @false, without doing anything, if it's 3442 called on a grid in which any columns are frozen. 3443 */ 3444 bool UseNativeColHeader(bool native = true); 3445 3446 //@} 3447 3448 3449 /*! 3450 @name Cell Formatting 3451 3452 Note that wxGridCellAttr can be used alternatively to most of these 3453 methods. See the "Attributes Management" of wxGridTableBase. 3454 */ 3455 //@{ 3456 3457 /** 3458 Sets the arguments to the horizontal and vertical text alignment values 3459 for the grid cell at the specified location. 3460 3461 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE 3462 or @c wxALIGN_RIGHT. 3463 3464 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or 3465 @c wxALIGN_BOTTOM. 3466 */ 3467 void GetCellAlignment(int row, int col, int* horiz, int* vert) const; 3468 3469 /** 3470 Returns the background colour of the cell at the specified location. 3471 */ 3472 wxColour GetCellBackgroundColour(int row, int col) const; 3473 3474 /** 3475 Returns the font for text in the grid cell at the specified location. 3476 */ 3477 wxFont GetCellFont(int row, int col) const; 3478 3479 /** 3480 Returns the text colour for the grid cell at the specified location. 3481 */ 3482 wxColour GetCellTextColour(int row, int col) const; 3483 3484 /** 3485 Returns the default cell alignment. 3486 3487 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE 3488 or @c wxALIGN_RIGHT. 3489 3490 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or 3491 @c wxALIGN_BOTTOM. 3492 3493 @see SetDefaultCellAlignment() 3494 */ 3495 void GetDefaultCellAlignment(int* horiz, int* vert) const; 3496 3497 /** 3498 Returns the current default background colour for grid cells. 3499 */ 3500 wxColour GetDefaultCellBackgroundColour() const; 3501 3502 /** 3503 Returns the current default font for grid cell text. 3504 */ 3505 wxFont GetDefaultCellFont() const; 3506 3507 /** 3508 Returns the current default colour for grid cell text. 3509 */ 3510 wxColour GetDefaultCellTextColour() const; 3511 3512 /** 3513 Sets the horizontal and vertical alignment for grid cell text at the 3514 specified location. 3515 3516 Horizontal alignment should be one of @c wxALIGN_LEFT, 3517 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. 3518 3519 Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE 3520 or @c wxALIGN_BOTTOM. 3521 */ 3522 void SetCellAlignment(int row, int col, int horiz, int vert); 3523 /** 3524 Sets the horizontal and vertical alignment for grid cell text at the 3525 specified location. 3526 3527 Horizontal alignment should be one of @c wxALIGN_LEFT, 3528 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. 3529 3530 Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE 3531 or @c wxALIGN_BOTTOM. 3532 3533 @deprecated Please use SetCellAlignment(row, col, horiz, vert) instead. 3534 */ 3535 void SetCellAlignment(int align, int row, int col); 3536 3537 /** 3538 Set the background colour for the given cell or all cells by default. 3539 */ 3540 void SetCellBackgroundColour(int row, int col, const wxColour& colour); 3541 3542 /** 3543 Sets the font for text in the grid cell at the specified location. 3544 */ 3545 void SetCellFont(int row, int col, const wxFont& font); 3546 3547 /** 3548 Sets the text colour for the given cell. 3549 */ 3550 void SetCellTextColour(int row, int col, const wxColour& colour); 3551 /** 3552 Sets the text colour for the given cell. 3553 3554 @deprecated Please use SetCellTextColour(row, col, colour) 3555 */ 3556 void SetCellTextColour(const wxColour& val, int row, int col); 3557 /** 3558 Sets the text colour for all cells by default. 3559 3560 @deprecated Please use SetDefaultCellTextColour(colour) instead. 3561 */ 3562 void SetCellTextColour(const wxColour& colour); 3563 3564 /** 3565 Sets the default horizontal and vertical alignment for grid cell text. 3566 3567 Horizontal alignment should be one of @c wxALIGN_LEFT, 3568 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one 3569 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM. 3570 */ 3571 void SetDefaultCellAlignment(int horiz, int vert); 3572 3573 /** 3574 Sets the default background colour for grid cells. 3575 */ 3576 void SetDefaultCellBackgroundColour(const wxColour& colour); 3577 3578 /** 3579 Sets the default font to be used for grid cell text. 3580 */ 3581 void SetDefaultCellFont(const wxFont& font); 3582 3583 /** 3584 Sets the current default colour for grid cell text. 3585 */ 3586 void SetDefaultCellTextColour(const wxColour& colour); 3587 3588 //@} 3589 3590 3591 /*! 3592 @name Cell Values, Editors, and Renderers 3593 3594 Note that wxGridCellAttr can be used alternatively to most of these 3595 methods. See the "Attributes Management" of wxGridTableBase. 3596 */ 3597 //@{ 3598 3599 /** 3600 Returns @true if the in-place edit control for the current grid cell 3601 can be used and @false otherwise. 3602 3603 This function always returns @false for the read-only cells. 3604 */ 3605 bool CanEnableCellControl() const; 3606 3607 /** 3608 Disables in-place editing of grid cells. 3609 3610 Equivalent to calling EnableCellEditControl(@false). 3611 */ 3612 void DisableCellEditControl(); 3613 3614 /** 3615 Enables or disables in-place editing of grid cell data. 3616 3617 Enabling in-place editing generates @c wxEVT_GRID_EDITOR_SHOWN and, if 3618 it isn't vetoed by the application, shows the in-place editor which 3619 allows the user to change the cell value. 3620 3621 Disabling in-place editing does nothing if the in-place editor isn't 3622 currently shown, otherwise the @c wxEVT_GRID_EDITOR_HIDDEN event is 3623 generated but, unlike the "shown" event, it can't be vetoed and the 3624 in-place editor is dismissed unconditionally. 3625 3626 Note that it is an error to call this function if the current cell is 3627 read-only, use CanEnableCellControl() to check for this precondition. 3628 */ 3629 void EnableCellEditControl(bool enable = true); 3630 3631 /** 3632 Makes the grid globally editable or read-only. 3633 3634 If the edit argument is @false this function sets the whole grid as 3635 read-only. If the argument is @true the grid is set to the default 3636 state where cells may be editable. In the default state you can set 3637 single grid cells and whole rows and columns to be editable or 3638 read-only via wxGridCellAttr::SetReadOnly(). For single cells you 3639 can also use the shortcut function SetReadOnly(). 3640 3641 For more information about controlling grid cell attributes see the 3642 wxGridCellAttr class and the @ref overview_grid. 3643 */ 3644 void EnableEditing(bool edit); 3645 3646 /** 3647 Returns a pointer to the editor for the cell at the specified location. 3648 3649 See wxGridCellEditor and the @ref overview_grid for more information 3650 about cell editors and renderers. 3651 3652 The caller must call DecRef() on the returned pointer. 3653 */ 3654 wxGridCellEditor* GetCellEditor(int row, int col) const; 3655 3656 /** 3657 Returns a pointer to the renderer for the grid cell at the specified 3658 location. 3659 3660 See wxGridCellRenderer and the @ref overview_grid for more information 3661 about cell editors and renderers. 3662 3663 The caller must call DecRef() on the returned pointer. 3664 */ 3665 wxGridCellRenderer* GetCellRenderer(int row, int col) const; 3666 3667 /** 3668 Returns the string contained in the cell at the specified location. 3669 3670 For simple applications where a grid object automatically uses a 3671 default grid table of string values you use this function together with 3672 SetCellValue() to access cell values. For more complex applications 3673 where you have derived your own grid table class that contains various 3674 data types (e.g. numeric, boolean or user-defined custom types) then 3675 you only use this function for those cells that contain string values. 3676 3677 See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for 3678 more information. 3679 */ 3680 wxString GetCellValue(int row, int col) const; 3681 /** 3682 Returns the string contained in the cell at the specified location. 3683 3684 For simple applications where a grid object automatically uses a 3685 default grid table of string values you use this function together with 3686 SetCellValue() to access cell values. For more complex applications 3687 where you have derived your own grid table class that contains various 3688 data types (e.g. numeric, boolean or user-defined custom types) then 3689 you only use this function for those cells that contain string values. 3690 3691 See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for 3692 more information. 3693 */ 3694 wxString GetCellValue(const wxGridCellCoords& coords) const; 3695 3696 /** 3697 Returns a pointer to the current default grid cell editor. 3698 3699 See wxGridCellEditor and the @ref overview_grid for more information 3700 about cell editors and renderers. 3701 */ 3702 wxGridCellEditor* GetDefaultEditor() const; 3703 3704 /** 3705 Returns the default editor for the specified cell. 3706 3707 The base class version returns the editor appropriate for the current 3708 cell type but this method may be overridden in the derived classes to 3709 use custom editors for some cells by default. 3710 3711 Notice that the same may be achieved in a usually simpler way by 3712 associating a custom editor with the given cell or cells. 3713 3714 The caller must call DecRef() on the returned pointer. 3715 */ 3716 virtual wxGridCellEditor* GetDefaultEditorForCell(int row, int col) const; 3717 /** 3718 Returns the default editor for the specified cell. 3719 3720 The base class version returns the editor appropriate for the current 3721 cell type but this method may be overridden in the derived classes to 3722 use custom editors for some cells by default. 3723 3724 Notice that the same may be achieved in a usually simpler way by 3725 associating a custom editor with the given cell or cells. 3726 3727 The caller must call DecRef() on the returned pointer. 3728 */ 3729 wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c) const; 3730 3731 /** 3732 Returns the default editor for the cells containing values of the given 3733 type. 3734 3735 The base class version returns the editor which was associated with the 3736 specified @a typeName when it was registered RegisterDataType() but 3737 this function may be overridden to return something different. This 3738 allows overriding an editor used for one of the standard types. 3739 3740 The caller must call DecRef() on the returned pointer. 3741 */ 3742 virtual wxGridCellEditor* GetDefaultEditorForType(const wxString& typeName) const; 3743 3744 /** 3745 Returns a pointer to the current default grid cell renderer. 3746 3747 See wxGridCellRenderer and the @ref overview_grid for more information 3748 about cell editors and renderers. 3749 3750 The caller must call DecRef() on the returned pointer. 3751 */ 3752 wxGridCellRenderer* GetDefaultRenderer() const; 3753 3754 /** 3755 Returns the default renderer for the given cell. 3756 3757 The base class version returns the renderer appropriate for the current 3758 cell type but this method may be overridden in the derived classes to 3759 use custom renderers for some cells by default. 3760 3761 The caller must call DecRef() on the returned pointer. 3762 */ 3763 virtual wxGridCellRenderer* GetDefaultRendererForCell(int row, int col) const; 3764 3765 /** 3766 Returns the default renderer for the cell containing values of the 3767 given type. 3768 3769 @see GetDefaultEditorForType() 3770 */ 3771 virtual wxGridCellRenderer* GetDefaultRendererForType(const wxString& typeName) const; 3772 3773 /** 3774 Hides the in-place cell edit control. 3775 */ 3776 void HideCellEditControl(); 3777 3778 /** 3779 Returns @true if the in-place edit control is currently enabled. 3780 */ 3781 bool IsCellEditControlEnabled() const; 3782 3783 /** 3784 Returns @true if the in-place edit control is currently shown. 3785 3786 @see HideCellEditControl() 3787 */ 3788 bool IsCellEditControlShown() const; 3789 3790 /** 3791 Returns @true if the current cell is read-only. 3792 3793 @see SetReadOnly(), IsReadOnly() 3794 */ 3795 bool IsCurrentCellReadOnly() const; 3796 3797 /** 3798 Returns @false if the whole grid has been set as read-only or @true 3799 otherwise. 3800 3801 See EnableEditing() for more information about controlling the editing 3802 status of grid cells. 3803 */ 3804 bool IsEditable() const; 3805 3806 /** 3807 Returns @true if the cell at the specified location can't be edited. 3808 3809 @see SetReadOnly(), IsCurrentCellReadOnly() 3810 */ 3811 bool IsReadOnly(int row, int col) const; 3812 3813 /** 3814 Register a new data type. 3815 3816 The data types allow to naturally associate specific renderers and 3817 editors to the cells containing values of the given type. For example, 3818 the grid automatically registers a data type with the name 3819 @c wxGRID_VALUE_STRING which uses wxGridCellStringRenderer and 3820 wxGridCellTextEditor as its renderer and editor respectively -- this is 3821 the data type used by all the cells of the default wxGridStringTable, 3822 so this renderer and editor are used by default for all grid cells. 3823 3824 However if a custom table returns @c wxGRID_VALUE_BOOL from its 3825 wxGridTableBase::GetTypeName() method, then wxGridCellBoolRenderer and 3826 wxGridCellBoolEditor are used for it because the grid also registers a 3827 boolean data type with this name. 3828 3829 And as this mechanism is completely generic, you may register your own 3830 data types using your own custom renderers and editors. Just remember 3831 that the table must identify a cell as being of the given type for them 3832 to be used for this cell. 3833 3834 @param typeName 3835 Name of the new type. May be any string, but if the type name is 3836 the same as the name of an already registered type, including one 3837 of the standard ones (which are @c wxGRID_VALUE_STRING, @c 3838 wxGRID_VALUE_BOOL, @c wxGRID_VALUE_NUMBER, @c wxGRID_VALUE_FLOAT, 3839 @c wxGRID_VALUE_CHOICE and @c wxGRID_VALUE_DATE), then the new 3840 registration information replaces the previously used renderer and 3841 editor. 3842 @param renderer 3843 The renderer to use for the cells of this type. Its ownership is 3844 taken by the grid, i.e. it will call DecRef() on this pointer when 3845 it doesn't need it any longer. 3846 @param editor 3847 The editor to use for the cells of this type. Its ownership is also 3848 taken by the grid. 3849 */ 3850 void RegisterDataType(const wxString& typeName, 3851 wxGridCellRenderer* renderer, 3852 wxGridCellEditor* editor); 3853 3854 /** 3855 Sets the value of the current grid cell to the current in-place edit 3856 control value. 3857 3858 This is called automatically when the grid cursor moves from the 3859 current cell to a new cell. It is also a good idea to call this 3860 function when closing a grid since any edits to the final cell location 3861 will not be saved otherwise. 3862 */ 3863 void SaveEditControlValue(); 3864 3865 /** 3866 Sets the editor for the grid cell at the specified location. 3867 3868 The grid will take ownership of the pointer. 3869 3870 See wxGridCellEditor and the @ref overview_grid for more information 3871 about cell editors and renderers. 3872 */ 3873 void SetCellEditor(int row, int col, wxGridCellEditor* editor); 3874 3875 /** 3876 Sets the renderer for the grid cell at the specified location. 3877 3878 The grid will take ownership of the pointer. 3879 3880 See wxGridCellRenderer and the @ref overview_grid for more information 3881 about cell editors and renderers. 3882 */ 3883 void SetCellRenderer(int row, int col, wxGridCellRenderer* renderer); 3884 3885 /** 3886 Sets the string value for the cell at the specified location. 3887 3888 For simple applications where a grid object automatically uses a 3889 default grid table of string values you use this function together with 3890 GetCellValue() to access cell values. For more complex applications 3891 where you have derived your own grid table class that contains various 3892 data types (e.g. numeric, boolean or user-defined custom types) then 3893 you only use this function for those cells that contain string values. 3894 3895 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for 3896 more information. 3897 */ 3898 void SetCellValue(int row, int col, const wxString& s); 3899 /** 3900 Sets the string value for the cell at the specified location. 3901 3902 For simple applications where a grid object automatically uses a 3903 default grid table of string values you use this function together with 3904 GetCellValue() to access cell values. For more complex applications 3905 where you have derived your own grid table class that contains various 3906 data types (e.g. numeric, boolean or user-defined custom types) then 3907 you only use this function for those cells that contain string values. 3908 3909 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for 3910 more information. 3911 */ 3912 void SetCellValue(const wxGridCellCoords& coords, const wxString& s); 3913 /** 3914 @deprecated Please use SetCellValue(int,int,const wxString&) or 3915 SetCellValue(const wxGridCellCoords&,const wxString&) 3916 instead. 3917 3918 Sets the string value for the cell at the specified location. 3919 3920 For simple applications where a grid object automatically uses a 3921 default grid table of string values you use this function together with 3922 GetCellValue() to access cell values. For more complex applications 3923 where you have derived your own grid table class that contains various 3924 data types (e.g. numeric, boolean or user-defined custom types) then 3925 you only use this function for those cells that contain string values. 3926 3927 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for 3928 more information. 3929 */ 3930 void SetCellValue(const wxString& val, int row, int col); 3931 3932 /** 3933 Sets the specified column to display boolean values. 3934 3935 @see SetColFormatCustom() 3936 */ 3937 void SetColFormatBool(int col); 3938 3939 /** 3940 Sets the specified column to display data in a custom format. 3941 3942 This method provides an alternative to defining a custom grid table 3943 which would return @a typeName from its GetTypeName() method for the 3944 cells in this column: while it doesn't really change the type of the 3945 cells in this column, it does associate the renderer and editor used 3946 for the cells of the specified type with them. 3947 3948 See the @ref overview_grid for more information on working with custom 3949 data types. 3950 */ 3951 void SetColFormatCustom(int col, const wxString& typeName); 3952 3953 /** 3954 Sets the specified column to display floating point values with the 3955 given width and precision. 3956 3957 @see SetColFormatCustom() 3958 */ 3959 void SetColFormatFloat(int col, int width = -1, int precision = -1); 3960 3961 /** 3962 Sets the specified column to display integer values. 3963 3964 @see SetColFormatCustom() 3965 */ 3966 void SetColFormatNumber(int col); 3967 3968 /** 3969 Sets the specified column to display date values. 3970 3971 The @a format argument is used with wxGridCellDateRenderer and allows 3972 to specify the strftime-like format string to use for displaying the 3973 dates in this column. 3974 3975 @see SetColFormatCustom() 3976 3977 @since 3.1.3 3978 */ 3979 void SetColFormatDate(int col, const wxString& format = wxString()); 3980 3981 /** 3982 Sets the default editor for grid cells. 3983 3984 The grid will take ownership of the pointer. 3985 3986 See wxGridCellEditor and the @ref overview_grid for more information 3987 about cell editors and renderers. 3988 */ 3989 void SetDefaultEditor(wxGridCellEditor* editor); 3990 3991 /** 3992 Sets the default renderer for grid cells. 3993 3994 The grid will take ownership of the pointer. 3995 3996 See wxGridCellRenderer and the @ref overview_grid for more information 3997 about cell editors and renderers. 3998 */ 3999 void SetDefaultRenderer(wxGridCellRenderer* renderer); 4000 4001 /** 4002 Makes the cell at the specified location read-only or editable. 4003 4004 @see IsReadOnly() 4005 */ 4006 void SetReadOnly(int row, int col, bool isReadOnly = true); 4007 4008 /** 4009 Displays the active in-place cell edit control for the current cell 4010 after it was hidden. 4011 4012 This method should only be called after calling HideCellEditControl(), 4013 to start editing the current grid cell use EnableCellEditControl() 4014 instead. 4015 */ 4016 void ShowCellEditControl(); 4017 4018 //@} 4019 4020 4021 /** 4022 @name Column and Row Sizes 4023 4024 @see @ref overview_grid_resizing 4025 */ 4026 //@{ 4027 4028 /** 4029 Automatically sets the height and width of all rows and columns to fit 4030 their contents. 4031 */ 4032 void AutoSize(); 4033 4034 /** 4035 Automatically adjusts width of the column to fit its label. 4036 */ 4037 void AutoSizeColLabelSize(int col); 4038 4039 /** 4040 Automatically sizes the column to fit its contents. If @a setAsMin is 4041 @true the calculated width will also be set as the minimal width for 4042 the column. 4043 */ 4044 void AutoSizeColumn(int col, bool setAsMin = true); 4045 4046 /** 4047 Automatically sizes all columns to fit their contents. If @a setAsMin 4048 is @true the calculated widths will also be set as the minimal widths 4049 for the columns. 4050 */ 4051 void AutoSizeColumns(bool setAsMin = true); 4052 4053 /** 4054 Automatically sizes the row to fit its contents. If @a setAsMin is 4055 @true the calculated height will also be set as the minimal height for 4056 the row. 4057 */ 4058 void AutoSizeRow(int row, bool setAsMin = true); 4059 4060 /** 4061 Automatically adjusts height of the row to fit its label. 4062 */ 4063 void AutoSizeRowLabelSize(int col); 4064 4065 /** 4066 Automatically sizes all rows to fit their contents. If @a setAsMin is 4067 @true the calculated heights will also be set as the minimal heights 4068 for the rows. 4069 */ 4070 void AutoSizeRows(bool setAsMin = true); 4071 4072 /** 4073 Returns the cell fitting mode. 4074 4075 @see wxGridFitMode 4076 4077 @since 3.1.4 4078 */ 4079 wxGridFitMode GetCellFitMode(int row, int col) const; 4080 4081 /** 4082 Returns @true if the cell value can overflow. 4083 4084 This is identical to calling GetCellFitMode() and using 4085 wxGridFitMode::IsOverflow() on the returned value. 4086 4087 Prefer using GetCellFitMode() directly in the new code. 4088 */ 4089 bool GetCellOverflow(int row, int col) const; 4090 4091 /** 4092 Returns the current height of the column labels. 4093 */ 4094 int GetColLabelSize() const; 4095 4096 /** 4097 Returns the minimal width to which a column may be resized. 4098 4099 Use SetColMinimalAcceptableWidth() to change this value globally or 4100 SetColMinimalWidth() to do it for individual columns. 4101 4102 @see GetRowMinimalAcceptableHeight() 4103 */ 4104 int GetColMinimalAcceptableWidth() const; 4105 4106 /** 4107 Returns the width of the specified column. 4108 */ 4109 int GetColSize(int col) const; 4110 4111 /** 4112 Returns @true if the specified column is not currently hidden. 4113 */ 4114 bool IsColShown(int col) const; 4115 4116 /** 4117 Returns the default cell fitting mode. 4118 4119 The default mode is "overflow", but can be modified using 4120 SetDefaultCellFitMode(). 4121 4122 @see wxGridFitMode 4123 4124 @since 3.1.4 4125 */ 4126 wxGridFitMode GetDefaultCellFitMode() const; 4127 4128 /** 4129 Returns @true if the cells can overflow by default. 4130 4131 This is identical to calling GetDefaultCellFitMode() and using 4132 wxGridFitMode::IsOverflow() on the returned value. 4133 4134 Prefer using GetDefaultCellFitMode() directly in the new code. 4135 */ 4136 bool GetDefaultCellOverflow() const; 4137 4138 /** 4139 Returns the default height for column labels. 4140 */ 4141 int GetDefaultColLabelSize() const; 4142 4143 /** 4144 Returns the current default width for grid columns. 4145 */ 4146 int GetDefaultColSize() const; 4147 4148 /** 4149 Returns the default width for the row labels. 4150 */ 4151 int GetDefaultRowLabelSize() const; 4152 4153 /** 4154 Returns the current default height for grid rows. 4155 */ 4156 int GetDefaultRowSize() const; 4157 4158 /** 4159 Returns the minimal size to which rows can be resized. 4160 4161 Use SetRowMinimalAcceptableHeight() to change this value globally or 4162 SetRowMinimalHeight() to do it for individual cells. 4163 4164 @see GetColMinimalAcceptableWidth() 4165 */ 4166 int GetRowMinimalAcceptableHeight() const; 4167 4168 /** 4169 Returns the current width of the row labels. 4170 */ 4171 int GetRowLabelSize() const; 4172 4173 /** 4174 Returns the height of the specified row. 4175 */ 4176 int GetRowSize(int row) const; 4177 4178 /** 4179 Returns @true if the specified row is not currently hidden. 4180 */ 4181 bool IsRowShown(int row) const; 4182 4183 /** 4184 Specifies the behaviour of the cell contents if it doesn't fit into the 4185 available space. 4186 4187 @see wxGridFitMode 4188 4189 @since 3.1.4 4190 */ 4191 void SetCellFitMode(int row, int col, wxGridFitMode fitMode); 4192 4193 /** 4194 Sets the overflow permission of the cell. 4195 4196 Prefer using SetCellFitMode() in the new code. 4197 */ 4198 void SetCellOverflow(int row, int col, bool allow); 4199 4200 /** 4201 Sets the height of the column labels. 4202 4203 If @a height equals to @c wxGRID_AUTOSIZE then height is calculated 4204 automatically so that no label is truncated. Note that this could be 4205 slow for a large table. 4206 */ 4207 void SetColLabelSize(int height); 4208 4209 /** 4210 Sets the minimal @a width to which the user can resize columns. 4211 4212 @see GetColMinimalAcceptableWidth() 4213 */ 4214 void SetColMinimalAcceptableWidth(int width); 4215 4216 /** 4217 Sets the minimal @a width for the specified column @a col. 4218 4219 It is usually best to call this method during grid creation as calling 4220 it later will not resize the column to the given minimal width even if 4221 it is currently narrower than it. 4222 4223 @a width must be greater than the minimal acceptable column width as 4224 returned by GetColMinimalAcceptableWidth(). 4225 */ 4226 void SetColMinimalWidth(int col, int width); 4227 4228 /** 4229 Sets the width of the specified column. 4230 4231 @param col 4232 The column index. 4233 @param width 4234 The new column width in pixels, 0 to hide the column or -1 to fit 4235 the column width to its label width. 4236 */ 4237 void SetColSize(int col, int width); 4238 4239 /** 4240 Hides the specified column. 4241 4242 To show the column later you need to call SetColSize() with non-0 4243 width or ShowCol() to restore the previous column width. 4244 4245 If the column is already hidden, this method doesn't do anything. 4246 4247 @param col 4248 The column index. 4249 */ 4250 void HideCol(int col); 4251 4252 /** 4253 Shows the previously hidden column by resizing it to non-0 size. 4254 4255 The column is shown again with the same width that it had before 4256 HideCol() call. 4257 4258 If the column is currently shown, this method doesn't do anything. 4259 4260 @see HideCol(), SetColSize() 4261 */ 4262 void ShowCol(int col); 4263 4264 4265 /** 4266 Specifies the default behaviour of the cell contents if it doesn't fit 4267 into the available space. 4268 4269 @see wxGridFitMode 4270 4271 @since 3.1.4 4272 */ 4273 void SetDefaultCellFitMode(wxGridFitMode fitMode); 4274 4275 /** 4276 Sets the default overflow permission of the cells. 4277 4278 Prefer using SetDefaultCellFitMode() in the new code. 4279 */ 4280 void SetDefaultCellOverflow( bool allow ); 4281 4282 /** 4283 Sets the default width for columns in the grid. 4284 4285 This will only affect columns subsequently added to the grid unless 4286 @a resizeExistingCols is @true. 4287 4288 If @a width is less than GetColMinimalAcceptableWidth(), then the 4289 minimal acceptable width is used instead of it. 4290 */ 4291 void SetDefaultColSize(int width, bool resizeExistingCols = false); 4292 4293 /** 4294 Sets the default height for rows in the grid. 4295 4296 This will only affect rows subsequently added to the grid unless 4297 @a resizeExistingRows is @true. 4298 4299 If @a height is less than GetRowMinimalAcceptableHeight(), then the 4300 minimal acceptable height is used instead of it. 4301 */ 4302 void SetDefaultRowSize(int height, bool resizeExistingRows = false); 4303 4304 /** 4305 Sets the width of the row labels. 4306 4307 If @a width equals @c wxGRID_AUTOSIZE then width is calculated 4308 automatically so that no label is truncated. Note that this could be 4309 slow for a large table. 4310 */ 4311 void SetRowLabelSize(int width); 4312 4313 /** 4314 Sets the minimal row @a height used by default. 4315 4316 See SetColMinimalAcceptableWidth() for more information. 4317 */ 4318 void SetRowMinimalAcceptableHeight(int height); 4319 4320 /** 4321 Sets the minimal @a height for the specified @a row. 4322 4323 See SetColMinimalWidth() for more information. 4324 */ 4325 void SetRowMinimalHeight(int row, int height); 4326 4327 /** 4328 Sets the height of the specified row. 4329 4330 See SetColSize() for more information. 4331 */ 4332 void SetRowSize(int row, int height); 4333 4334 /** 4335 Hides the specified row. 4336 4337 To show the row later you need to call SetRowSize() with non-0 4338 width or ShowRow() to restore its original height. 4339 4340 If the row is already hidden, this method doesn't do anything. 4341 4342 @param col 4343 The row index. 4344 */ 4345 void HideRow(int col); 4346 4347 /** 4348 Shows the previously hidden row. 4349 4350 The row is shown again with the same height that it had before 4351 HideRow() call. 4352 4353 If the row is currently shown, this method doesn't do anything. 4354 4355 @see HideRow(), SetRowSize() 4356 */ 4357 void ShowRow(int col); 4358 4359 /** 4360 Get size information for all columns at once. 4361 4362 This method is useful when the information about all column widths 4363 needs to be saved. The widths can be later restored using 4364 SetColSizes(). 4365 4366 @sa wxGridSizesInfo, GetRowSizes() 4367 */ 4368 wxGridSizesInfo GetColSizes() const; 4369 4370 /** 4371 Get size information for all row at once. 4372 4373 @sa wxGridSizesInfo, GetColSizes() 4374 */ 4375 wxGridSizesInfo GetRowSizes() const; 4376 4377 /** 4378 Restore all columns sizes. 4379 4380 This is usually called with wxGridSizesInfo object previously returned 4381 by GetColSizes(). 4382 4383 @sa SetRowSizes() 4384 */ 4385 void SetColSizes(const wxGridSizesInfo& sizeInfo); 4386 4387 /** 4388 Restore all rows sizes. 4389 4390 @sa SetColSizes() 4391 */ 4392 void SetRowSizes(const wxGridSizesInfo& sizeInfo); 4393 4394 /** 4395 Set the size of the cell. 4396 4397 Specifying a value of more than 1 in @a num_rows or @a num_cols will 4398 make the cell at (@a row, @a col) span the block of the specified size, 4399 covering the other cells which would be normally shown in it. Passing 1 4400 for both arguments resets the cell to normal appearance. 4401 4402 @see GetCellSize() 4403 4404 @param row 4405 The row of the cell. 4406 @param col 4407 The column of the cell. 4408 @param num_rows 4409 Number of rows to be occupied by this cell, must be >= 1. 4410 @param num_cols 4411 Number of columns to be occupied by this cell, must be >= 1. 4412 */ 4413 void SetCellSize(int row, int col, int num_rows, int num_cols); 4414 4415 /** 4416 Get the size of the cell in number of cells covered by it. 4417 4418 For normal cells, the function fills both @a num_rows and @a num_cols 4419 with 1 and returns CellSpan_None. For cells which span multiple cells, i.e. 4420 for which SetCellSize() had been called, the returned values are the 4421 same ones as were passed to SetCellSize() call and the function return 4422 value is CellSpan_Main. 4423 4424 More unexpectedly, perhaps, the returned values may be @em negative for 4425 the cells which are inside a span covered by a cell occupying multiple 4426 rows or columns. They correspond to the offset of the main cell of the 4427 span from the cell passed to this functions and the function returns 4428 CellSpan_Inside value to indicate this. 4429 4430 As an example, consider a 3*3 grid with the cell (1, 1) (the one in the 4431 middle) having a span of 2 rows and 2 columns, i.e. the grid looks like 4432 @code 4433 +----+----+----+ 4434 | | | | 4435 +----+----+----+ 4436 | | | 4437 +----+ | 4438 | | | 4439 +----+----+----+ 4440 @endcode 4441 Then the function returns 2 and 2 in @a num_rows and @a num_cols for 4442 the cell (1, 1) itself and -1 and -1 for the cell (2, 2) as well as -1 4443 and 0 for the cell (2, 1). 4444 4445 @param row 4446 The row of the cell. 4447 @param col 4448 The column of the cell. 4449 @param num_rows 4450 Pointer to variable receiving the number of rows, must not be @NULL. 4451 @param num_cols 4452 Pointer to variable receiving the number of columns, must not be 4453 @NULL. 4454 @return 4455 The kind of this cell span (the return value is new in wxWidgets 4456 2.9.1, this function was void in previous wxWidgets versions). 4457 */ 4458 CellSpan GetCellSize( int row, int col, int *num_rows, int *num_cols ) const; 4459 4460 /** 4461 Get the number of rows and columns allocated for this cell. 4462 4463 This overload doesn't return a CellSpan value but the values returned 4464 may still be negative, see GetCellSize(int, int, int *, int *) for 4465 details. 4466 */ 4467 wxSize GetCellSize(const wxGridCellCoords& coords) const; 4468 4469 //@} 4470 4471 4472 /** 4473 @name User-Resizing and Dragging 4474 4475 Functions controlling various interactive mouse operations. 4476 4477 By default, columns and rows can be resized by dragging the edges of 4478 their labels (this can be disabled using DisableDragColSize() and 4479 DisableDragRowSize() methods). And if grid line dragging is enabled with 4480 EnableDragGridSize() they can also be resized by dragging the right or 4481 bottom edge of the grid cells. 4482 4483 Columns can also be moved to interactively change their order but this 4484 needs to be explicitly enabled with EnableDragColMove(). 4485 */ 4486 //@{ 4487 4488 /** 4489 Return @true if the dragging of cells is enabled or @false otherwise. 4490 */ 4491 bool CanDragCell() const; 4492 4493 /** 4494 Returns @true if columns can be moved by dragging with the mouse. 4495 4496 Columns can be moved by dragging on their labels. 4497 */ 4498 bool CanDragColMove() const; 4499 4500 /** 4501 Returns @true if the given column can be resized by dragging with the 4502 mouse. 4503 4504 This function returns @true if resizing the columns interactively is 4505 globally enabled, i.e. if DisableDragColSize() hadn't been called, and 4506 if this column wasn't explicitly marked as non-resizable with 4507 DisableColResize(). 4508 */ 4509 bool CanDragColSize(int col) const; 4510 4511 /** 4512 Return @true if column edges inside the grid can be dragged to resize 4513 the rows. 4514 4515 @see CanDragGridSize(), CanDragColSize() 4516 4517 @since 3.1.4 4518 */ 4519 bool CanDragGridColEdges() const; 4520 4521 /** 4522 Return @true if row edges inside the grid can be dragged to resize the 4523 rows. 4524 4525 @see CanDragGridSize(), CanDragRowSize() 4526 4527 @since 3.1.4 4528 */ 4529 bool CanDragGridRowEdges() const; 4530 4531 /** 4532 Return @true if the dragging of grid lines to resize rows and columns 4533 is enabled or @false otherwise. 4534 */ 4535 bool CanDragGridSize() const; 4536 4537 /** 4538 Returns @true if the given row can be resized by dragging with the 4539 mouse. 4540 4541 This is the same as CanDragColSize() but for rows. 4542 */ 4543 bool CanDragRowSize(int row) const; 4544 4545 /** 4546 Returns @true if columns can be hidden from the popup menu of the native header. 4547 4548 @since 3.1.3 4549 */ 4550 bool CanHideColumns() const; 4551 4552 /** 4553 Disable interactive resizing of the specified column. 4554 4555 This method allows one to disable resizing of an individual column in a 4556 grid where the columns are otherwise resizable (which is the case by 4557 default). 4558 4559 Notice that currently there is no way to make some columns resizable in 4560 a grid where columns can't be resized by default as there doesn't seem 4561 to be any need for this in practice. There is also no way to make the 4562 column marked as fixed using this method resizable again because it is 4563 supposed that fixed columns are used for static parts of the grid and 4564 so should remain fixed during the entire grid lifetime. 4565 4566 Also notice that disabling interactive column resizing will not prevent 4567 the program from changing the column size. 4568 4569 @see EnableDragColSize() 4570 */ 4571 void DisableColResize(int col); 4572 4573 /** 4574 Disable interactive resizing of the specified row. 4575 4576 This is the same as DisableColResize() but for rows. 4577 4578 @see EnableDragRowSize() 4579 */ 4580 void DisableRowResize(int row); 4581 4582 /** 4583 Disables column moving by dragging with the mouse. 4584 4585 Equivalent to passing @false to EnableDragColMove(). 4586 */ 4587 void DisableDragColMove(); 4588 4589 /** 4590 Disables column sizing by dragging with the mouse. 4591 4592 Equivalent to passing @false to EnableDragColSize(). 4593 */ 4594 void DisableDragColSize(); 4595 4596 /** 4597 Disable mouse dragging of grid lines to resize rows and columns. 4598 4599 Equivalent to passing @false to EnableDragGridSize() 4600 */ 4601 void DisableDragGridSize(); 4602 4603 /** 4604 Disables row sizing by dragging with the mouse. 4605 4606 Equivalent to passing @false to EnableDragRowSize(). 4607 */ 4608 void DisableDragRowSize(); 4609 4610 /** 4611 Disables column hiding from the header popup menu. 4612 4613 Equivalent to passing @false to EnableHidingColumns(). 4614 4615 @since 3.1.3 4616 */ 4617 void DisableHidingColumns(); 4618 4619 /** 4620 Enables or disables cell dragging with the mouse. 4621 */ 4622 void EnableDragCell(bool enable = true); 4623 4624 /** 4625 Enables or disables column moving by dragging with the mouse. 4626 4627 Note that reordering columns by dragging them is currently not 4628 supported when the grid has any frozen columns (see FreezeTo()) and if 4629 this method is called with @a enable equal to @true in this situation, 4630 it returns @false without doing anything. Otherwise it returns @true to 4631 indicate that it was successful. 4632 */ 4633 bool EnableDragColMove(bool enable = true); 4634 4635 /** 4636 Enables or disables column sizing by dragging with the mouse. 4637 4638 @see DisableColResize() 4639 */ 4640 void EnableDragColSize(bool enable = true); 4641 4642 /** 4643 Enables or disables row and column resizing by dragging gridlines with 4644 the mouse. 4645 */ 4646 void EnableDragGridSize(bool enable = true); 4647 4648 /** 4649 Enables or disables row sizing by dragging with the mouse. 4650 4651 @see DisableRowResize() 4652 */ 4653 void EnableDragRowSize(bool enable = true); 4654 4655 /** 4656 Enables or disables column hiding from the header popup menu. 4657 4658 Note that currently the popup menu can only be shown when using 4659 wxHeaderCtrl, i.e. if UseNativeColHeader() had been called. 4660 4661 If the native header is not used, this method always simply returns 4662 @false without doing anything, as hiding columns is not supported 4663 anyhow. If @a enable value is the same as CanHideColumns(), it also 4664 returns @false to indicate that nothing was done. Otherwise, it returns 4665 @true to indicate that the value of this option was successfully 4666 changed. 4667 4668 The main use case for this method is to disallow hiding the columns 4669 interactively when using the native header. 4670 4671 @since 3.1.3 4672 4673 @see DisableHidingColumns() 4674 */ 4675 bool EnableHidingColumns(bool enable = true); 4676 4677 /** 4678 Returns the column ID of the specified column position. 4679 */ 4680 int GetColAt(int colPos) const; 4681 4682 /** 4683 Returns the position of the specified column. 4684 */ 4685 int GetColPos(int colID) const; 4686 4687 /** 4688 Sets the position of the specified column. 4689 */ 4690 void SetColPos(int colID, int newPos); 4691 4692 /** 4693 Sets the positions of all columns at once. 4694 4695 This method takes an array containing the indices of the columns in 4696 their display order, i.e. uses the same convention as 4697 wxHeaderCtrl::SetColumnsOrder(). 4698 */ 4699 void SetColumnsOrder(const wxArrayInt& order); 4700 4701 /** 4702 Resets the position of the columns to the default. 4703 */ 4704 void ResetColPos(); 4705 4706 //@} 4707 4708 4709 /** 4710 @name Cursor Movement 4711 */ 4712 //@{ 4713 4714 /** 4715 Returns the current grid cursor position. 4716 4717 If grid cursor doesn't have any valid position (e.g. if the grid is 4718 completely empty and doesn't have any rows or columns), returns 4719 @c wxGridNoCellCoords which has both row and columns set to @c -1. 4720 4721 @since 3.1.3 4722 */ 4723 const wxGridCellCoords& GetGridCursorCoords() const; 4724 4725 /** 4726 Returns the current grid cell column position. 4727 4728 @see GetGridCursorCoords() 4729 */ 4730 int GetGridCursorCol() const; 4731 4732 /** 4733 Returns the current grid cell row position. 4734 4735 @see GetGridCursorCoords() 4736 */ 4737 int GetGridCursorRow() const; 4738 4739 /** 4740 Make the given cell current and ensure it is visible. 4741 4742 This method is equivalent to calling MakeCellVisible() and 4743 SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL 4744 event is generated by it and the selected cell doesn't change if the 4745 event is vetoed. 4746 */ 4747 void GoToCell(int row, int col); 4748 /** 4749 Make the given cell current and ensure it is visible. 4750 4751 This method is equivalent to calling MakeCellVisible() and 4752 SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL 4753 event is generated by it and the selected cell doesn't change if the 4754 event is vetoed. 4755 */ 4756 void GoToCell(const wxGridCellCoords& coords); 4757 4758 /** 4759 Moves the grid cursor down by one row. 4760 4761 If a block of cells was previously selected it will expand if the 4762 argument is @true or be cleared if the argument is @false. 4763 */ 4764 bool MoveCursorDown(bool expandSelection); 4765 4766 /** 4767 Moves the grid cursor down in the current column such that it skips to 4768 the beginning or end of a block of non-empty cells. 4769 4770 If a block of cells was previously selected it will expand if the 4771 argument is @true or be cleared if the argument is @false. 4772 */ 4773 bool MoveCursorDownBlock(bool expandSelection); 4774 4775 /** 4776 Moves the grid cursor left by one column. 4777 4778 If a block of cells was previously selected it will expand if the 4779 argument is @true or be cleared if the argument is @false. 4780 */ 4781 bool MoveCursorLeft(bool expandSelection); 4782 4783 /** 4784 Moves the grid cursor left in the current row such that it skips to the 4785 beginning or end of a block of non-empty cells. 4786 4787 If a block of cells was previously selected it will expand if the 4788 argument is @true or be cleared if the argument is @false. 4789 */ 4790 bool MoveCursorLeftBlock(bool expandSelection); 4791 4792 /** 4793 Moves the grid cursor right by one column. 4794 4795 If a block of cells was previously selected it will expand if the 4796 argument is @true or be cleared if the argument is @false. 4797 */ 4798 bool MoveCursorRight(bool expandSelection); 4799 4800 /** 4801 Moves the grid cursor right in the current row such that it skips to 4802 the beginning or end of a block of non-empty cells. 4803 4804 If a block of cells was previously selected it will expand if the 4805 argument is @true or be cleared if the argument is @false. 4806 */ 4807 bool MoveCursorRightBlock(bool expandSelection); 4808 4809 /** 4810 Moves the grid cursor up by one row. 4811 4812 If a block of cells was previously selected it will expand if the 4813 argument is @true or be cleared if the argument is @false. 4814 */ 4815 bool MoveCursorUp(bool expandSelection); 4816 4817 /** 4818 Moves the grid cursor up in the current column such that it skips to 4819 the beginning or end of a block of non-empty cells. 4820 4821 If a block of cells was previously selected it will expand if the 4822 argument is @true or be cleared if the argument is @false. 4823 */ 4824 bool MoveCursorUpBlock(bool expandSelection); 4825 4826 /** 4827 Moves the grid cursor down by some number of rows so that the previous 4828 bottom visible row becomes the top visible row. 4829 */ 4830 bool MovePageDown(); 4831 4832 /** 4833 Moves the grid cursor up by some number of rows so that the previous 4834 top visible row becomes the bottom visible row. 4835 */ 4836 bool MovePageUp(); 4837 4838 /** 4839 Set the grid cursor to the specified cell. 4840 4841 The grid cursor indicates the current cell and can be moved by the user 4842 using the arrow keys or the mouse. 4843 4844 Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and 4845 if the event handler vetoes this event, the cursor is not moved. 4846 4847 This function doesn't make the target call visible, use GoToCell() to 4848 do this. 4849 */ 4850 void SetGridCursor(int row, int col); 4851 /** 4852 Set the grid cursor to the specified cell. 4853 4854 The grid cursor indicates the current cell and can be moved by the user 4855 using the arrow keys or the mouse. 4856 4857 Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and 4858 if the event handler vetoes this event, the cursor is not moved. 4859 4860 This function doesn't make the target call visible, use GoToCell() to 4861 do this. 4862 */ 4863 void SetGridCursor(const wxGridCellCoords& coords); 4864 4865 /** 4866 Set the grid's behaviour when the user presses the TAB key. 4867 4868 Pressing the TAB key moves the grid cursor right in the current row, if 4869 there is a cell at the right and, similarly, Shift-TAB moves the cursor 4870 to the left in the current row if it's not in the first column. 4871 4872 What happens if the cursor can't be moved because it it's already at 4873 the beginning or end of the row can be configured using this function, 4874 see wxGrid::TabBehaviour documentation for the detailed description. 4875 4876 IF none of the standard behaviours is appropriate, you can always 4877 handle @c wxEVT_GRID_TABBING event directly to implement a custom 4878 TAB-handling logic. 4879 4880 @since 2.9.5 4881 */ 4882 void SetTabBehaviour(TabBehaviour behaviour); 4883 4884 //@} 4885 4886 4887 /** 4888 @name User Selection 4889 */ 4890 //@{ 4891 4892 /** 4893 Deselects all cells that are currently selected. 4894 */ 4895 void ClearSelection(); 4896 4897 /** 4898 Deselects a row of cells. 4899 */ 4900 void DeselectRow( int row ); 4901 4902 /** 4903 Deselects a column of cells. 4904 */ 4905 void DeselectCol( int col ); 4906 4907 /** 4908 Deselects a cell. 4909 */ 4910 void DeselectCell( int row, int col ); 4911 4912 /** 4913 Returns a range of grid selection blocks. 4914 4915 The returned range can be iterated over, e.g. with C++11 range-for loop: 4916 @code 4917 for ( const auto block: grid->GetSelectedBlocks() ) { 4918 if ( block.Intersects(myBlock) ) 4919 break; 4920 } 4921 @endcode 4922 4923 Notice that the blocks returned by this method are not ordered in any 4924 particular way and may overlap. For grids using rows or columns-only 4925 selection modes, GetSelectedRowBlocks() or GetSelectedColBlocks() can 4926 be more convenient, as they return ordered and non-overlapping blocks. 4927 4928 @since 3.1.4 4929 */ 4930 wxGridBlocks GetSelectedBlocks() const; 4931 4932 /** 4933 Returns an ordered range of non-overlapping selected rows. 4934 4935 For the grids using wxGridSelectRows selection mode, returns the 4936 possibly empty vector containing the coordinates of non-overlapping 4937 selected row blocks in the natural order, i.e. from smallest to the 4938 biggest row indices. 4939 4940 To see the difference between this method and GetSelectedBlocks(), 4941 consider the case when the user selects rows 2..4 in the grid and then 4942 also selects (using Ctrl/Shift keys) the rows 1..3. Iterating over the 4943 result of GetSelectedBlocks() would yield two blocks directly 4944 corresponding to the users selection, while this method returns a 4945 vector with a single element corresponding to the rows 1..4. 4946 4947 This method returns empty vector for the other selection modes. 4948 4949 @see GetSelectedBlocks(), GetSelectedColBlocks() 4950 4951 @since 3.1.4 4952 */ 4953 wxGridBlockCoordsVector GetSelectedRowBlocks() const; 4954 4955 /** 4956 Returns an ordered range of non-overlapping selected columns. 4957 4958 This method is symmetric to GetSelectedRowBlocks(), but is useful only 4959 in wxGridSelectColumns selection mode. 4960 4961 @see GetSelectedBlocks() 4962 4963 @since 3.1.4 4964 */ 4965 wxGridBlockCoordsVector GetSelectedColBlocks() const; 4966 4967 /** 4968 Returns an array of individually selected cells. 4969 4970 Notice that this array does @em not contain all the selected cells in 4971 general as it doesn't include the cells selected as part of column, row 4972 or block selection. You must use this method, GetSelectedCols(), 4973 GetSelectedRows() and GetSelectionBlockTopLeft() and 4974 GetSelectionBlockBottomRight() methods to obtain the entire selection 4975 in general. 4976 4977 Please notice this behaviour is by design and is needed in order to 4978 support grids of arbitrary size (when an entire column is selected in 4979 a grid with a million of columns, we don't want to create an array with 4980 a million of entries in this function, instead it returns an empty 4981 array and GetSelectedCols() returns an array containing one element). 4982 4983 The function can be slow for the big grids, use GetSelectedBlocks() 4984 in the new code. 4985 */ 4986 wxGridCellCoordsArray GetSelectedCells() const; 4987 4988 /** 4989 Returns an array of selected columns. 4990 4991 Please notice that this method alone is not sufficient to find all the 4992 selected columns as it contains only the columns which were 4993 individually selected but not those being part of the block selection 4994 or being selected in virtue of all of their cells being selected 4995 individually, please see GetSelectedCells() for more details. 4996 4997 The function can be slow for the big grids, use GetSelectedBlocks() 4998 in the new code. 4999 */ 5000 wxArrayInt GetSelectedCols() const; 5001 5002 /** 5003 Returns an array of selected rows. 5004 5005 Please notice that this method alone is not sufficient to find all the 5006 selected rows as it contains only the rows which were individually 5007 selected but not those being part of the block selection or being 5008 selected in virtue of all of their cells being selected individually, 5009 please see GetSelectedCells() for more details. 5010 5011 The function can be slow for the big grids, use GetSelectedBlocks() 5012 in the new code. 5013 */ 5014 wxArrayInt GetSelectedRows() const; 5015 5016 /** 5017 Returns the colour used for drawing the selection background. 5018 */ 5019 wxColour GetSelectionBackground() const; 5020 5021 /** 5022 Returns an array of the bottom right corners of blocks of selected 5023 cells. 5024 5025 Please see GetSelectedCells() for more information about the selection 5026 representation in wxGrid. 5027 5028 The function can be slow for the big grids, use GetSelectedBlocks() 5029 in the new code. 5030 5031 @see GetSelectionBlockTopLeft() 5032 */ 5033 wxGridCellCoordsArray GetSelectionBlockBottomRight() const; 5034 5035 /** 5036 Returns an array of the top left corners of blocks of selected cells. 5037 5038 Please see GetSelectedCells() for more information about the selection 5039 representation in wxGrid. 5040 5041 The function can be slow for the big grids, use GetSelectedBlocks() 5042 in the new code. 5043 5044 @see GetSelectionBlockBottomRight() 5045 */ 5046 wxGridCellCoordsArray GetSelectionBlockTopLeft() const; 5047 5048 /** 5049 Returns the colour used for drawing the selection foreground. 5050 */ 5051 wxColour GetSelectionForeground() const; 5052 5053 /** 5054 Returns the current selection mode. 5055 5056 @see SetSelectionMode(). 5057 */ 5058 wxGridSelectionModes GetSelectionMode() const; 5059 5060 /** 5061 Returns @true if the given cell is selected. 5062 */ 5063 bool IsInSelection(int row, int col) const; 5064 /** 5065 Returns @true if the given cell is selected. 5066 */ 5067 bool IsInSelection(const wxGridCellCoords& coords) const; 5068 5069 /** 5070 Returns @true if there are currently any selected cells, rows, columns 5071 or blocks. 5072 */ 5073 bool IsSelection() const; 5074 5075 /** 5076 Selects all cells in the grid. 5077 */ 5078 void SelectAll(); 5079 5080 /** 5081 Selects a rectangular block of cells. 5082 5083 If @a addToSelected is @false then any existing selection will be 5084 deselected; if @true the column will be added to the existing 5085 selection. 5086 */ 5087 void SelectBlock(int topRow, int leftCol, int bottomRow, int rightCol, 5088 bool addToSelected = false); 5089 /** 5090 Selects a rectangular block of cells. 5091 5092 If @a addToSelected is @false then any existing selection will be 5093 deselected; if @true the column will be added to the existing 5094 selection. 5095 */ 5096 void SelectBlock(const wxGridCellCoords& topLeft, 5097 const wxGridCellCoords& bottomRight, 5098 bool addToSelected = false); 5099 5100 /** 5101 Selects the specified column. 5102 5103 If @a addToSelected is @false then any existing selection will be 5104 deselected; if @true the column will be added to the existing 5105 selection. 5106 5107 This method won't select anything if the current selection mode is 5108 wxGridSelectRows. 5109 */ 5110 void SelectCol(int col, bool addToSelected = false); 5111 5112 /** 5113 Selects the specified row. 5114 5115 If @a addToSelected is @false then any existing selection will be 5116 deselected; if @true the row will be added to the existing selection. 5117 5118 This method won't select anything if the current selection mode is 5119 wxGridSelectColumns. 5120 */ 5121 void SelectRow(int row, bool addToSelected = false); 5122 5123 /** 5124 Set the colour to be used for drawing the selection background. 5125 */ 5126 void SetSelectionBackground(const wxColour& c); 5127 5128 /** 5129 Set the colour to be used for drawing the selection foreground. 5130 */ 5131 void SetSelectionForeground(const wxColour& c); 5132 5133 /** 5134 Set the selection behaviour of the grid. 5135 5136 The existing selection is converted to conform to the new mode if 5137 possible and discarded otherwise (e.g. any individual selected cells 5138 are deselected if the new mode allows only the selection of the entire 5139 rows or columns). 5140 */ 5141 void SetSelectionMode(wxGridSelectionModes selmode); 5142 5143 //@} 5144 5145 5146 /** 5147 @name Scrolling 5148 */ 5149 //@{ 5150 5151 /** 5152 Returns the number of pixels per horizontal scroll increment. 5153 5154 The default is 15. 5155 5156 @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY() 5157 */ 5158 int GetScrollLineX() const; 5159 5160 /** 5161 Returns the number of pixels per vertical scroll increment. 5162 5163 The default is 15. 5164 5165 @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY() 5166 */ 5167 int GetScrollLineY() const; 5168 5169 /** 5170 Returns @true if a cell is either entirely or at least partially 5171 visible in the grid window. 5172 5173 By default, the cell must be entirely visible for this function to 5174 return @true but if @a wholeCellVisible is @false, the function returns 5175 @true even if the cell is only partially visible. 5176 */ 5177 bool IsVisible(int row, int col, bool wholeCellVisible = true) const; 5178 /** 5179 Returns @true if a cell is either entirely or at least partially 5180 visible in the grid window. 5181 5182 By default, the cell must be entirely visible for this function to 5183 return @true but if @a wholeCellVisible is @false, the function returns 5184 @true even if the cell is only partially visible. 5185 */ 5186 bool IsVisible(const wxGridCellCoords& coords, 5187 bool wholeCellVisible = true) const; 5188 5189 /** 5190 Brings the specified cell into the visible grid cell area with minimal 5191 scrolling. 5192 5193 Does nothing if the cell is already visible. 5194 */ 5195 void MakeCellVisible(int row, int col); 5196 /** 5197 Brings the specified cell into the visible grid cell area with minimal 5198 scrolling. 5199 5200 Does nothing if the cell is already visible. 5201 */ 5202 void MakeCellVisible(const wxGridCellCoords& coords); 5203 5204 /** 5205 Returns the topmost row of the current visible area. 5206 Returns -1 if the grid doesn't have any rows. 5207 */ 5208 int GetFirstFullyVisibleRow() const; 5209 /** 5210 Returns the leftmost column of the current visible area. 5211 Returns -1 if the grid doesn't have any columns. 5212 */ 5213 int GetFirstFullyVisibleColumn() const; 5214 5215 /** 5216 Sets the number of pixels per horizontal scroll increment. 5217 5218 The default is 15. 5219 5220 @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY() 5221 */ 5222 void SetScrollLineX(int x); 5223 5224 /** 5225 Sets the number of pixels per vertical scroll increment. 5226 5227 The default is 15. 5228 5229 @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX() 5230 */ 5231 void SetScrollLineY(int y); 5232 5233 //@} 5234 5235 5236 /** 5237 @name Cell and Device Coordinate Translation 5238 */ 5239 //@{ 5240 5241 /** 5242 Convert grid cell coordinates to grid window pixel coordinates. 5243 5244 This function returns the rectangle that encloses the block of cells 5245 limited by @a topLeft and @a bottomRight cell in device coords and 5246 clipped to the client size of the grid window. 5247 5248 @since 3.1.3 Parameter @a gridWindow has been added. 5249 5250 @see CellToRect() 5251 */ 5252 wxRect BlockToDeviceRect(const wxGridCellCoords& topLeft, 5253 const wxGridCellCoords& bottomRight, 5254 const wxGridWindow *gridWindow = NULL) const; 5255 5256 /** 5257 Return the rectangle corresponding to the grid cell's size and position 5258 in logical coordinates. 5259 5260 @see BlockToDeviceRect() 5261 */ 5262 wxRect CellToRect(int row, int col) const; 5263 /** 5264 Return the rectangle corresponding to the grid cell's size and position 5265 in logical coordinates. 5266 5267 @see BlockToDeviceRect() 5268 */ 5269 wxRect CellToRect(const wxGridCellCoords& coords) const; 5270 5271 /** 5272 Returns the grid window that contains the cell. 5273 5274 In a grid without frozen rows or columns (see FreezeTo()), this will 5275 always return the same window as GetGridWindow(), however if some parts 5276 of the grid are frozen, this function returns the window containing the 5277 given cell. 5278 5279 @since 3.1.3 5280 */ 5281 wxGridWindow* CellToGridWindow( int row, int col ) const; 5282 5283 /// @overload 5284 wxGridWindow* CellToGridWindow( const wxGridCellCoords& coords ) const; 5285 5286 /** 5287 Returns the grid window that includes the input coordinates. 5288 5289 @since 3.1.3 5290 */ 5291 wxGridWindow* DevicePosToGridWindow(wxPoint pos) const; 5292 5293 /// @overload 5294 wxGridWindow* DevicePosToGridWindow(int x, int y) const; 5295 5296 /** 5297 Returns the grid window's offset from the grid starting position taking 5298 into account the frozen cells. 5299 5300 If there are no frozen cells, returns (0, 0). 5301 5302 @since 3.1.3 5303 5304 @see FreezeTo() 5305 */ 5306 void GetGridWindowOffset(const wxGridWindow *gridWindow, int &x, int &y) const; 5307 5308 /// @overload 5309 wxPoint GetGridWindowOffset(const wxGridWindow *gridWindow) const; 5310 5311 /** 5312 Translates the device coordinates to the logical ones, taking into 5313 account the grid window type. 5314 5315 @since 3.1.3 5316 5317 @see wxScrolled::CalcUnscrolledPosition() 5318 */ 5319 void CalcGridWindowUnscrolledPosition(int x, int y, 5320 int *xx, int *yy, 5321 const wxGridWindow *gridWindow) const; 5322 /// @overload 5323 wxPoint CalcGridWindowUnscrolledPosition(const wxPoint& pt, 5324 const wxGridWindow *gridWindow) const; 5325 5326 /** 5327 Translates the logical coordinates to the device ones, taking into 5328 account the grid window type. 5329 5330 @since 3.1.3 5331 5332 @see wxScrolled::CalcScrolledPosition() 5333 */ 5334 void CalcGridWindowScrolledPosition(int x, int y, 5335 int *xx, int *yy, 5336 const wxGridWindow *gridWindow) const; 5337 5338 /// @overload 5339 wxPoint CalcGridWindowScrolledPosition(const wxPoint& pt, 5340 const wxGridWindow *gridWindow) const; 5341 5342 /** 5343 Returns the column at the given pixel position depending on the window. 5344 5345 @param x 5346 The x position to evaluate. 5347 @param clipToMinMax 5348 If @true, rather than returning @c wxNOT_FOUND, it returns either 5349 the first or last column depending on whether @a x is too far to 5350 the left or right respectively. 5351 @param gridWindow 5352 The associated grid window that limits the search (note that this 5353 parameter is only available since wxWidgets 3.1.3). 5354 If @a gridWindow is @NULL, it will consider all the cells, no matter 5355 which grid they belong to. 5356 @return 5357 The column index or @c wxNOT_FOUND. 5358 */ 5359 int XToCol(int x, bool clipToMinMax = false, wxGridWindow *gridWindow = NULL) const; 5360 5361 /** 5362 Returns the column whose right hand edge is close to the given logical 5363 @a x position. 5364 5365 If no column edge is near to this position @c wxNOT_FOUND is returned. 5366 */ 5367 int XToEdgeOfCol(int x) const; 5368 5369 /** 5370 Translates logical pixel coordinates to the grid cell coordinates. 5371 5372 Notice that this function expects logical coordinates on input so if 5373 you use this function in a mouse event handler you need to translate 5374 the mouse position, which is expressed in device coordinates, to 5375 logical ones. 5376 5377 The parameter @a gridWindow is new since wxWidgets 3.1.3. If it is 5378 specified, i.e. non-@NULL, the coordinates must be in this window 5379 coordinate system and only the cells of this window are considered, 5380 i.e. the function returns @c wxNOT_FOUND if the coordinates are out of 5381 bounds. 5382 5383 If @a gridWindow is @NULL, coordinates are relative to the main grid 5384 window and all cells are considered. 5385 5386 @see XToCol(), YToRow() 5387 */ 5388 wxGridCellCoords XYToCell(int x, int y, wxGridWindow *gridWindow = NULL) const; 5389 5390 /// @overload 5391 wxGridCellCoords XYToCell(const wxPoint& pos, wxGridWindow *gridWindow = NULL) const; 5392 5393 // XYToCell(int, int, wxGridCellCoords&) overload is intentionally 5394 // undocumented, using it is ugly and non-const reference parameters are 5395 // not used in wxWidgets API 5396 5397 /** 5398 Returns the row whose bottom edge is close to the given logical @a y 5399 position. 5400 5401 If no row edge is near to this position @c wxNOT_FOUND is returned. 5402 */ 5403 int YToEdgeOfRow(int y) const; 5404 5405 /** 5406 Returns the grid row that corresponds to the logical @a y coordinate. 5407 5408 5409 The parameter @a gridWindow is new since wxWidgets 3.1.3. If it is 5410 specified, i.e. non-@NULL, only the cells of this window are 5411 considered, i.e. the function returns @c wxNOT_FOUND if @a y is out of 5412 bounds. 5413 5414 If @a gridWindow is @NULL, the function returns @c wxNOT_FOUND only if 5415 there is no row at all at the @a y position. 5416 */ 5417 int YToRow(int y, bool clipToMinMax = false, wxGridWindow *gridWindow = NULL) const; 5418 5419 //@} 5420 5421 5422 /** 5423 @name Miscellaneous Functions 5424 */ 5425 //@{ 5426 5427 /** 5428 Appends one or more new columns to the right of the grid. 5429 5430 The @a updateLabels argument is not used at present. If you are using a 5431 derived grid table class you will need to override 5432 wxGridTableBase::AppendCols(). See InsertCols() for further 5433 information. 5434 5435 @return @true on success or @false if appending columns failed. 5436 */ 5437 bool AppendCols(int numCols = 1, bool updateLabels = true); 5438 5439 /** 5440 Appends one or more new rows to the bottom of the grid. 5441 5442 The @a updateLabels argument is not used at present. If you are using a 5443 derived grid table class you will need to override 5444 wxGridTableBase::AppendRows(). See InsertRows() for further 5445 information. 5446 5447 @return @true on success or @false if appending rows failed. 5448 */ 5449 bool AppendRows(int numRows = 1, bool updateLabels = true); 5450 5451 /** 5452 Return @true if the horizontal grid lines stop at the last column 5453 boundary or @false if they continue to the end of the window. 5454 5455 The default is to clip grid lines. 5456 5457 @see ClipHorzGridLines(), AreVertGridLinesClipped() 5458 */ 5459 bool AreHorzGridLinesClipped() const; 5460 5461 /** 5462 Return @true if the vertical grid lines stop at the last row 5463 boundary or @false if they continue to the end of the window. 5464 5465 The default is to clip grid lines. 5466 5467 @see ClipVertGridLines(), AreHorzGridLinesClipped() 5468 */ 5469 bool AreVertGridLinesClipped() const; 5470 5471 /** 5472 Increments the grid's batch count. 5473 5474 When the count is greater than zero repainting of the grid is 5475 suppressed. Each call to BeginBatch must be matched by a later call to 5476 EndBatch(). Code that does a lot of grid modification can be enclosed 5477 between BeginBatch() and EndBatch() calls to avoid screen flicker. The 5478 final EndBatch() call will cause the grid to be repainted. 5479 5480 Notice that you should use wxGridUpdateLocker which ensures that there 5481 is always a matching EndBatch() call for this BeginBatch() if possible 5482 instead of calling this method directly. 5483 */ 5484 void BeginBatch(); 5485 5486 /** 5487 Clears all data in the underlying grid table and repaints the grid. 5488 5489 The table is not deleted by this function. If you are using a derived 5490 table class then you need to override wxGridTableBase::Clear() for this 5491 function to have any effect. 5492 */ 5493 void ClearGrid(); 5494 5495 /** 5496 Change whether the horizontal grid lines are clipped by the end of the 5497 last column. 5498 5499 By default the grid lines are not drawn beyond the end of the last 5500 column but after calling this function with @a clip set to @false they 5501 will be drawn across the entire grid window. 5502 5503 @see AreHorzGridLinesClipped(), ClipVertGridLines() 5504 */ 5505 void ClipHorzGridLines(bool clip); 5506 5507 /** 5508 Change whether the vertical grid lines are clipped by the end of the 5509 last row. 5510 5511 By default the grid lines are not drawn beyond the end of the last 5512 row but after calling this function with @a clip set to @false they 5513 will be drawn across the entire grid window. 5514 5515 @see AreVertGridLinesClipped(), ClipHorzGridLines() 5516 */ 5517 void ClipVertGridLines(bool clip); 5518 5519 /** 5520 Deletes one or more columns from a grid starting at the specified 5521 position. 5522 5523 The @a updateLabels argument is not used at present. If you are using a 5524 derived grid table class you will need to override 5525 wxGridTableBase::DeleteCols(). See InsertCols() for further 5526 information. 5527 5528 @return @true on success or @false if deleting columns failed. 5529 */ 5530 bool DeleteCols(int pos = 0, int numCols = 1, bool updateLabels = true); 5531 5532 /** 5533 Deletes one or more rows from a grid starting at the specified 5534 position. 5535 5536 The @a updateLabels argument is not used at present. If you are using a 5537 derived grid table class you will need to override 5538 wxGridTableBase::DeleteRows(). See InsertRows() for further 5539 information. 5540 5541 @return @true on success or @false if deleting rows failed. 5542 */ 5543 bool DeleteRows(int pos = 0, int numRows = 1, bool updateLabels = true); 5544 5545 /** 5546 Sets or resets the frozen columns and rows. 5547 5548 @param row 5549 The number of rows to freeze, 0 means to unfreeze all rows. 5550 @param col 5551 The number of columns to freeze, 0 means to unfreeze all columns. 5552 @return @true on success or @false if it failed. 5553 5554 Note that this method doesn't do anything, and returns @false, if any 5555 of the following conditions are true: 5556 - Either @a row or @a col are out of range 5557 - Size of the frozen area would be bigger than the current viewing area 5558 - There are any merged cells in the area to be frozen 5559 - Grid uses a native header control (see UseNativeColHeader()) 5560 5561 (some of these limitations could be lifted in the future). 5562 5563 @since 3.1.3 5564 */ 5565 bool FreezeTo(unsigned row, unsigned col); 5566 5567 /// @overload 5568 bool FreezeTo(const wxGridCellCoords& coords); 5569 5570 /** 5571 Decrements the grid's batch count. 5572 5573 When the count is greater than zero repainting of the grid is 5574 suppressed. Each previous call to BeginBatch() must be matched by a 5575 later call to EndBatch(). Code that does a lot of grid modification can 5576 be enclosed between BeginBatch() and EndBatch() calls to avoid screen 5577 flicker. The final EndBatch() will cause the grid to be repainted. 5578 5579 @see wxGridUpdateLocker 5580 */ 5581 void EndBatch(); 5582 5583 /** 5584 Overridden wxWindow method. 5585 */ 5586 virtual void Fit(); 5587 5588 /** 5589 Causes immediate repainting of the grid. 5590 5591 Use this instead of the usual wxWindow::Refresh(). 5592 */ 5593 void ForceRefresh(); 5594 5595 /** 5596 Returns the number of times that BeginBatch() has been called without 5597 (yet) matching calls to EndBatch(). While the grid's batch count is 5598 greater than zero the display will not be updated. 5599 */ 5600 int GetBatchCount() const; 5601 5602 /** 5603 Returns the total number of grid columns. 5604 5605 This is the same as the number of columns in the underlying grid table. 5606 */ 5607 int GetNumberCols() const; 5608 5609 /** 5610 Returns the total number of grid rows. 5611 5612 This is the same as the number of rows in the underlying grid table. 5613 */ 5614 int GetNumberRows() const; 5615 5616 /** 5617 Returns the number of frozen grid columns. 5618 5619 If there are no frozen columns, returns 0. 5620 5621 @since 3.1.3 5622 5623 @see FreezeTo() 5624 */ 5625 int GetNumberFrozenCols() const; 5626 5627 /** 5628 Returns the number of frozen grid rows. 5629 5630 If there are no frozen rows, returns 0. 5631 5632 @since 3.1.3 5633 5634 @see FreezeTo() 5635 */ 5636 int GetNumberFrozenRows() const; 5637 5638 /** 5639 Returns the attribute for the given cell creating one if necessary. 5640 5641 If the cell already has an attribute, it is returned. Otherwise a new 5642 attribute is created, associated with the cell and returned. In any 5643 case the caller must call DecRef() on the returned pointer. 5644 5645 Prefer to use GetOrCreateCellAttrPtr() to avoid the need to call 5646 DecRef() on the returned pointer. 5647 5648 This function may only be called if CanHaveAttributes() returns @true. 5649 */ 5650 wxGridCellAttr *GetOrCreateCellAttr(int row, int col) const; 5651 5652 /** 5653 Returns the attribute for the given cell creating one if necessary. 5654 5655 This method is identical to GetOrCreateCellAttr(), but returns a smart 5656 pointer, which frees the caller from the need to call DecRef() 5657 manually. 5658 5659 @since 3.1.4 5660 */ 5661 wxGridCellAttrPtr GetOrCreateCellAttrPtr(int row, int col) const; 5662 5663 /** 5664 Returns a base pointer to the current table object. 5665 5666 The returned pointer is still owned by the grid. 5667 */ 5668 wxGridTableBase *GetTable() const; 5669 5670 /** 5671 Inserts one or more new columns into a grid with the first new column 5672 at the specified position. 5673 5674 Notice that inserting the columns in the grid requires grid table 5675 cooperation: when this method is called, grid object begins by 5676 requesting the underlying grid table to insert new columns. If this is 5677 successful the table notifies the grid and the grid updates the 5678 display. For a default grid (one where you have called CreateGrid()) 5679 this process is automatic. If you are using a custom grid table 5680 (specified with SetTable() or AssignTable()) then you must override 5681 wxGridTableBase::InsertCols() in your derived table class. 5682 5683 @param pos 5684 The position which the first newly inserted column will have. 5685 @param numCols 5686 The number of columns to insert. 5687 @param updateLabels 5688 Currently not used. 5689 @return 5690 @true if the columns were successfully inserted, @false if an error 5691 occurred (most likely the table couldn't be updated). 5692 */ 5693 bool InsertCols(int pos = 0, int numCols = 1, bool updateLabels = true); 5694 5695 /** 5696 Inserts one or more new rows into a grid with the first new row at the 5697 specified position. 5698 5699 Notice that you must implement wxGridTableBase::InsertRows() if you use 5700 a grid with a custom table, please see InsertCols() for more 5701 information. 5702 5703 @param pos 5704 The position which the first newly inserted row will have. 5705 @param numRows 5706 The number of rows to insert. 5707 @param updateLabels 5708 Currently not used. 5709 @return 5710 @true if the rows were successfully inserted, @false if an error 5711 occurred (most likely the table couldn't be updated). 5712 */ 5713 bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true); 5714 5715 /** 5716 Invalidates the cached attribute for the given cell. 5717 5718 For efficiency reasons, wxGrid may cache the recently used attributes 5719 (currently it caches only the single most recently used one, in fact) 5720 which can result in the cell appearance not being refreshed even when 5721 the attribute returned by your custom wxGridCellAttrProvider-derived 5722 class has changed. To force the grid to refresh the cell attribute, 5723 this function may be used. Notice that calling it will not result in 5724 actually redrawing the cell, you still need to call 5725 wxWindow::RefreshRect() to invalidate the area occupied by the cell in 5726 the window to do this. Also note that you don't need to call this 5727 function if you store the attributes in wxGrid itself, i.e. use its 5728 SetAttr() and similar methods, it is only useful when using a separate 5729 custom attributes provider. 5730 5731 @param row 5732 The row of the cell whose attribute needs to be queried again. 5733 @param col 5734 The column of the cell whose attribute needs to be queried again. 5735 5736 @since 2.9.2 5737 */ 5738 void RefreshAttr(int row, int col); 5739 5740 /** 5741 Draws part or all of a wxGrid on a wxDC for printing or display. 5742 5743 Pagination can be accomplished by using sequential Render() calls 5744 with appropriate values in wxGridCellCoords topLeft and bottomRight. 5745 5746 @param dc 5747 The wxDC to be drawn on. 5748 @param pos 5749 The position on the wxDC where rendering should begin. If not 5750 specified drawing will begin at the wxDC MaxX() and MaxY(). 5751 @param size 5752 The size of the area on the wxDC that the rendered wxGrid should 5753 occupy. If not specified the drawing will be scaled to fit the 5754 available dc width or height. The wxGrid's aspect ratio is 5755 maintained whether or not size is specified. 5756 @param topLeft 5757 The top left cell of the block to be drawn. Defaults to ( 0, 0 ). 5758 @param bottomRight 5759 The bottom right cell of the block to be drawn. Defaults to row and 5760 column counts. 5761 @param style 5762 A combination of values from wxGridRenderStyle. 5763 5764 @since 2.9.4 5765 */ 5766 void Render( wxDC& dc, 5767 const wxPoint& pos = wxDefaultPosition, 5768 const wxSize& size = wxDefaultSize, 5769 const wxGridCellCoords& topLeft = wxGridCellCoords( -1, -1 ), 5770 const wxGridCellCoords& bottomRight = wxGridCellCoords( -1, -1 ), 5771 int style = wxGRID_DRAW_DEFAULT ); 5772 5773 /** 5774 Sets the cell attributes for the specified cell. 5775 5776 The grid takes ownership of the attribute pointer. 5777 5778 See the wxGridCellAttr class for more information about controlling 5779 cell attributes. 5780 */ 5781 void SetAttr(int row, int col, wxGridCellAttr *attr); 5782 5783 /** 5784 Sets the cell attributes for all cells in the specified column. 5785 5786 For more information about controlling grid cell attributes see the 5787 wxGridCellAttr cell attribute class and the @ref overview_grid. 5788 */ 5789 void SetColAttr(int col, wxGridCellAttr* attr); 5790 5791 /** 5792 Sets the extra margins used around the grid area. 5793 5794 A grid may occupy more space than needed for its data display and 5795 this function allows setting how big this extra space is 5796 */ 5797 void SetMargins(int extraWidth, int extraHeight); 5798 5799 /** 5800 Sets the cell attributes for all cells in the specified row. 5801 5802 The grid takes ownership of the attribute pointer. 5803 5804 See the wxGridCellAttr class for more information about controlling 5805 cell attributes. 5806 */ 5807 void SetRowAttr(int row, wxGridCellAttr* attr); 5808 5809 5810 wxArrayInt CalcRowLabelsExposed( const wxRegion& reg, 5811 wxGridWindow *gridWindow = NULL) const; 5812 wxArrayInt CalcColLabelsExposed( const wxRegion& reg, 5813 wxGridWindow *gridWindow = NULL) const; 5814 wxGridCellCoordsArray CalcCellsExposed( const wxRegion& reg, 5815 wxGridWindow *gridWindow = NULL) const; 5816 5817 //@} 5818 5819 5820 /** 5821 @name Sorting support. 5822 5823 wxGrid doesn't provide any support for sorting the data but it does 5824 generate events allowing the user code to sort it and supports 5825 displaying the sort indicator in the column used for sorting. 5826 5827 To use wxGrid sorting support you need to handle wxEVT_GRID_COL_SORT 5828 event (and not veto it) and resort the data displayed in the grid. The 5829 grid will automatically update the sorting indicator on the column 5830 which was clicked. 5831 5832 You can also call the functions in this section directly to update the 5833 sorting indicator. Once again, they don't do anything with the grid 5834 data, it remains your responsibility to actually sort it appropriately. 5835 */ 5836 //@{ 5837 5838 /** 5839 Return the column in which the sorting indicator is currently 5840 displayed. 5841 5842 Returns @c wxNOT_FOUND if sorting indicator is not currently displayed 5843 at all. 5844 5845 @see SetSortingColumn() 5846 */ 5847 int GetSortingColumn() const; 5848 5849 /** 5850 Return @true if this column is currently used for sorting. 5851 5852 @see GetSortingColumn() 5853 */ 5854 bool IsSortingBy(int col) const; 5855 5856 /** 5857 Return @true if the current sorting order is ascending or @false if it 5858 is descending. 5859 5860 It only makes sense to call this function if GetSortingColumn() returns 5861 a valid column index and not @c wxNOT_FOUND. 5862 5863 @see SetSortingColumn() 5864 */ 5865 bool IsSortOrderAscending() const; 5866 5867 /** 5868 Set the column to display the sorting indicator in and its direction. 5869 5870 @param col 5871 The column to display the sorting indicator in or @c wxNOT_FOUND to 5872 remove any currently displayed sorting indicator. 5873 @param ascending 5874 If @true, display the ascending sort indicator, otherwise display 5875 the descending sort indicator. 5876 5877 @see GetSortingColumn(), IsSortOrderAscending() 5878 */ 5879 void SetSortingColumn(int col, bool ascending = true); 5880 5881 /** 5882 Remove any currently shown sorting indicator. 5883 5884 This is equivalent to calling SetSortingColumn() with @c wxNOT_FOUND 5885 first argument. 5886 */ 5887 void UnsetSortingColumn(); 5888 //@} 5889 5890 5891 /** 5892 @name Accessors for component windows. 5893 5894 Return the various child windows of wxGrid. 5895 5896 wxGrid is an empty parent window for at least 4 children representing 5897 the column labels window (top), the row labels window (left), the 5898 corner window (top left) and the main grid window. It may be necessary 5899 to use these individual windows and not the wxGrid window itself if you 5900 need to handle events for them (using wxEvtHandler::Bind()) or do 5901 something else requiring the use of the correct window pointer. Notice 5902 that you should not, however, change these windows (e.g. reposition 5903 them or draw over them) because they are managed by wxGrid itself. 5904 5905 When parts of the grid are frozen using FreezeTo() function, the main 5906 grid window contains only the unfrozen part and additional windows are 5907 used for the parts containing frozen rows and/or columns and the corner 5908 window if both some rows and some columns are frozen. 5909 */ 5910 //@{ 5911 5912 /** 5913 Return the main grid window containing the grid cells. 5914 5915 This window is always shown. 5916 */ 5917 wxWindow *GetGridWindow() const; 5918 5919 /** 5920 Return the corner grid window containing frozen cells. 5921 5922 This window is shown only when there are frozen rows and columns. 5923 5924 @since 3.1.3 5925 */ 5926 wxWindow* GetFrozenCornerGridWindow() const; 5927 5928 /** 5929 Return the rows grid window containing row frozen cells. 5930 5931 This window is shown only when there are frozen rows. 5932 5933 @since 3.1.3 5934 */ 5935 wxWindow* GetFrozenRowGridWindow() const; 5936 5937 /** 5938 Return the columns grid window containing column frozen cells. 5939 5940 This window is shown only when there are frozen columns. 5941 5942 @since 3.1.3 5943 */ 5944 wxWindow* GetFrozenColGridWindow() const; 5945 5946 /** 5947 Return the row labels window. 5948 5949 This window is not shown if the row labels were hidden using 5950 HideRowLabels(). 5951 */ 5952 wxWindow *GetGridRowLabelWindow() const; 5953 5954 /** 5955 Return the column labels window. 5956 5957 This window is not shown if the columns labels were hidden using 5958 HideColLabels(). 5959 5960 Depending on whether UseNativeColHeader() was called or not this can be 5961 either a wxHeaderCtrl or a plain wxWindow. This function returns a valid 5962 window pointer in either case but in the former case you can also use 5963 GetGridColHeader() to access it if you need wxHeaderCtrl-specific 5964 functionality. 5965 */ 5966 wxWindow *GetGridColLabelWindow() const; 5967 5968 /** 5969 Return the window in the top left grid corner. 5970 5971 This window is shown only of both columns and row labels are shown and 5972 normally doesn't contain anything. Clicking on it is handled by wxGrid 5973 however and can be used to select the entire grid. 5974 */ 5975 wxWindow *GetGridCornerLabelWindow() const; 5976 5977 /** 5978 Return the header control used for column labels display. 5979 5980 This function can only be called if UseNativeColHeader() had been 5981 called. 5982 5983 @see IsUsingNativeHeader() 5984 */ 5985 wxHeaderCtrl *GetGridColHeader() const; 5986 5987 /** 5988 Return true if native header control is currently being used. 5989 5990 @since 3.1.4 5991 */ 5992 bool IsUsingNativeHeader() const; 5993 5994 //@} 5995 5996 5997 virtual void DrawCellHighlight( wxDC& dc, const wxGridCellAttr *attr ); 5998 5999 virtual void DrawRowLabels( wxDC& dc, const wxArrayInt& rows ); 6000 virtual void DrawRowLabel( wxDC& dc, int row ); 6001 6002 virtual void DrawColLabels( wxDC& dc, const wxArrayInt& cols ); 6003 virtual void DrawColLabel( wxDC& dc, int col ); 6004 6005 virtual void DrawCornerLabel(wxDC& dc); 6006 6007 void DrawTextRectangle( wxDC& dc, const wxString& text, const wxRect& rect, 6008 int horizontalAlignment = wxALIGN_LEFT, 6009 int verticalAlignment = wxALIGN_TOP, 6010 int textOrientation = wxHORIZONTAL ) const; 6011 6012 void DrawTextRectangle( wxDC& dc, const wxArrayString& lines, const wxRect& rect, 6013 int horizontalAlignment = wxALIGN_LEFT, 6014 int verticalAlignment = wxALIGN_TOP, 6015 int textOrientation = wxHORIZONTAL ) const; 6016 6017 wxColour GetCellHighlightColour() const; 6018 int GetCellHighlightPenWidth() const; 6019 int GetCellHighlightROPenWidth() const; 6020 6021 void SetCellHighlightColour( const wxColour& ); 6022 void SetCellHighlightPenWidth(int width); 6023 void SetCellHighlightROPenWidth(int width); 6024 void SetGridFrozenBorderColour( const wxColour& ); 6025 void SetGridFrozenBorderPenWidth( int width ); 6026 6027 6028 protected: 6029 /** 6030 Returns @true if this grid has support for cell attributes. 6031 6032 The grid supports attributes if it has the associated table which, in 6033 turn, has attributes support, i.e. wxGridTableBase::CanHaveAttributes() 6034 returns @true. 6035 */ 6036 bool CanHaveAttributes() const; 6037 6038 /** 6039 Get the minimal width of the given column/row. 6040 6041 The value returned by this function may be different from that returned 6042 by GetColMinimalAcceptableWidth() if SetColMinimalWidth() had been 6043 called for this column. 6044 */ 6045 int GetColMinimalWidth(int col) const; 6046 6047 /** 6048 Returns the coordinate of the right border specified column. 6049 */ 6050 int GetColRight(int col) const; 6051 6052 /** 6053 Returns the coordinate of the left border specified column. 6054 */ 6055 int GetColLeft(int col) const; 6056 6057 /** 6058 Returns the minimal size for the given column. 6059 6060 The value returned by this function may be different from that returned 6061 by GetRowMinimalAcceptableHeight() if SetRowMinimalHeight() had been 6062 called for this row. 6063 */ 6064 int GetRowMinimalHeight(int col) const; 6065 }; 6066 6067 6068 6069 /** 6070 @class wxGridUpdateLocker 6071 6072 This small class can be used to prevent wxGrid from redrawing during its 6073 lifetime by calling wxGrid::BeginBatch() in its constructor and 6074 wxGrid::EndBatch() in its destructor. It is typically used in a function 6075 performing several operations with a grid which would otherwise result in 6076 flicker. For example: 6077 6078 @code 6079 void MyFrame::Foo() 6080 { 6081 m_grid = new wxGrid(this, ...); 6082 6083 wxGridUpdateLocker noUpdates(m_grid); 6084 m_grid-AppendColumn(); 6085 // ... many other operations with m_grid ... 6086 m_grid-AppendRow(); 6087 6088 // destructor called, grid refreshed 6089 } 6090 @endcode 6091 6092 Using this class is easier and safer than calling wxGrid::BeginBatch() and 6093 wxGrid::EndBatch() because you don't risk missing the call the latter (due 6094 to an exception for example). 6095 6096 @library{wxcore} 6097 @category{grid} 6098 */ 6099 class wxGridUpdateLocker 6100 { 6101 public: 6102 /** 6103 Creates an object preventing the updates of the specified @a grid. The 6104 parameter could be @NULL in which case nothing is done. If @a grid is 6105 non-@NULL then the grid must exist for longer than this 6106 wxGridUpdateLocker object itself. 6107 6108 The default constructor could be followed by a call to Create() to set 6109 the grid object later. 6110 */ 6111 wxGridUpdateLocker(wxGrid* grid = NULL); 6112 6113 /** 6114 Destructor reenables updates for the grid this object is associated 6115 with. 6116 */ 6117 ~wxGridUpdateLocker(); 6118 6119 /** 6120 This method can be called if the object had been constructed using the 6121 default constructor. It must not be called more than once. 6122 */ 6123 void Create(wxGrid* grid); 6124 }; 6125 6126 6127 6128 /** 6129 @class wxGridEvent 6130 6131 This event class contains information about various grid events. 6132 6133 Notice that all grid event table macros are available in two versions: 6134 @c EVT_GRID_XXX and @c EVT_GRID_CMD_XXX. The only difference between the 6135 two is that the former doesn't allow to specify the grid window identifier 6136 and so takes a single parameter, the event handler, but is not suitable if 6137 there is more than one grid control in the window where the event table is 6138 used (as it would catch the events from all the grids). The version with @c 6139 CMD takes the id as first argument and the event handler as the second one 6140 and so can be used with multiple grids as well. Otherwise there are no 6141 difference between the two and only the versions without the id are 6142 documented below for brevity. 6143 6144 @beginEventTable{wxGridEvent} 6145 @event{EVT_GRID_CELL_CHANGING(func)} 6146 The user is about to change the data in a cell. The new cell value as 6147 string is available from GetString() event object method. This event 6148 can be vetoed if the change is not allowed. 6149 Processes a @c wxEVT_GRID_CELL_CHANGING event type. 6150 @event{EVT_GRID_CELL_CHANGED(func)} 6151 The user changed the data in a cell. The old cell value as string is 6152 available from GetString() event object method. Notice that vetoing 6153 this event still works for backwards compatibility reasons but any new 6154 code should only veto EVT_GRID_CELL_CHANGING event and not this one. 6155 Processes a @c wxEVT_GRID_CELL_CHANGED event type. 6156 @event{EVT_GRID_CELL_LEFT_CLICK(func)} 6157 The user clicked a cell with the left mouse button. Processes a 6158 @c wxEVT_GRID_CELL_LEFT_CLICK event type. 6159 @event{EVT_GRID_CELL_LEFT_DCLICK(func)} 6160 The user double-clicked a cell with the left mouse button. Processes a 6161 @c wxEVT_GRID_CELL_LEFT_DCLICK event type. 6162 @event{EVT_GRID_CELL_RIGHT_CLICK(func)} 6163 The user clicked a cell with the right mouse button. Processes a 6164 @c wxEVT_GRID_CELL_RIGHT_CLICK event type. 6165 @event{EVT_GRID_CELL_RIGHT_DCLICK(func)} 6166 The user double-clicked a cell with the right mouse button. Processes a 6167 @c wxEVT_GRID_CELL_RIGHT_DCLICK event type. 6168 @event{EVT_GRID_EDITOR_HIDDEN(func)} 6169 The editor for a cell was hidden. Processes a 6170 @c wxEVT_GRID_EDITOR_HIDDEN event type. 6171 @event{EVT_GRID_EDITOR_SHOWN(func)} 6172 The editor for a cell was shown. Processes a 6173 @c wxEVT_GRID_EDITOR_SHOWN event type. 6174 @event{EVT_GRID_LABEL_LEFT_CLICK(func)} 6175 The user clicked a label with the left mouse button. Processes a 6176 @c wxEVT_GRID_LABEL_LEFT_CLICK event type. 6177 @event{EVT_GRID_LABEL_LEFT_DCLICK(func)} 6178 The user double-clicked a label with the left mouse button. Processes a 6179 @c wxEVT_GRID_LABEL_LEFT_DCLICK event type. 6180 @event{EVT_GRID_LABEL_RIGHT_CLICK(func)} 6181 The user clicked a label with the right mouse button. Processes a 6182 @c wxEVT_GRID_LABEL_RIGHT_CLICK event type. 6183 @event{EVT_GRID_LABEL_RIGHT_DCLICK(func)} 6184 The user double-clicked a label with the right mouse button. Processes 6185 a @c wxEVT_GRID_LABEL_RIGHT_DCLICK event type. 6186 @event{EVT_GRID_SELECT_CELL(func)} 6187 The given cell was made current, either by user or by the program via a 6188 call to SetGridCursor() or GoToCell(). Processes a 6189 @c wxEVT_GRID_SELECT_CELL event type. 6190 @event{EVT_GRID_COL_MOVE(func)} 6191 The user tries to change the order of the columns in the grid by 6192 dragging the column specified by GetCol(). This event can be vetoed to 6193 either prevent the user from reordering the column change completely 6194 (but notice that if you don't want to allow it at all, you simply 6195 shouldn't call wxGrid::EnableDragColMove() in the first place), vetoed 6196 but handled in some way in the handler, e.g. by really moving the 6197 column to the new position at the associated table level, or allowed to 6198 proceed in which case wxGrid::SetColPos() is used to reorder the 6199 columns display order without affecting the use of the column indices 6200 otherwise. 6201 This event macro corresponds to @c wxEVT_GRID_COL_MOVE event type. 6202 @event{EVT_GRID_COL_SORT(func)} 6203 This event is generated when a column is clicked by the user and its 6204 name is explained by the fact that the custom reaction to a click on a 6205 column is to sort the grid contents by this column. However the grid 6206 itself has no special support for sorting and it's up to the handler of 6207 this event to update the associated table. But if the event is handled 6208 (and not vetoed) the grid supposes that the table was indeed resorted 6209 and updates the column to indicate the new sort order and refreshes 6210 itself. 6211 This event macro corresponds to @c wxEVT_GRID_COL_SORT event type. 6212 @event{EVT_GRID_TABBING(func)} 6213 This event is generated when the user presses TAB or Shift-TAB in the 6214 grid. It can be used to customize the simple default TAB handling 6215 logic, e.g. to go to the next non-empty cell instead of just the next 6216 cell. See also wxGrid::SetTabBehaviour(). This event is new since 6217 wxWidgets 2.9.5. 6218 @endEventTable 6219 6220 @library{wxcore} 6221 @category{grid,events} 6222 */ 6223 class wxGridEvent : public wxNotifyEvent 6224 { 6225 public: 6226 /** 6227 Default constructor. 6228 */ 6229 wxGridEvent(); 6230 /** 6231 Constructor for initializing all event attributes. 6232 */ 6233 wxGridEvent(int id, wxEventType type, wxObject* obj, 6234 int row = -1, int col = -1, int x = -1, int y = -1, 6235 bool sel = true, const wxKeyboardState& kbd = wxKeyboardState()); 6236 6237 /** 6238 Returns @true if the Alt key was down at the time of the event. 6239 */ 6240 bool AltDown() const; 6241 6242 /** 6243 Returns @true if the Control key was down at the time of the event. 6244 */ 6245 bool ControlDown() const; 6246 6247 /** 6248 Column at which the event occurred. 6249 6250 Notice that for a @c wxEVT_GRID_SELECT_CELL event this column is the 6251 column of the newly selected cell while the previously selected cell 6252 can be retrieved using wxGrid::GetGridCursorCol(). 6253 */ 6254 int GetCol() const; 6255 6256 /** 6257 Position in pixels at which the event occurred. 6258 */ 6259 wxPoint GetPosition() const; 6260 6261 /** 6262 Row at which the event occurred. 6263 6264 Notice that for a @c wxEVT_GRID_SELECT_CELL event this row is the row 6265 of the newly selected cell while the previously selected cell can be 6266 retrieved using wxGrid::GetGridCursorRow(). 6267 */ 6268 int GetRow() const; 6269 6270 /** 6271 Returns @true if the Meta key was down at the time of the event. 6272 */ 6273 bool MetaDown() const; 6274 6275 /** 6276 Returns @true if the user is selecting grid cells, or @false if 6277 deselecting. 6278 */ 6279 bool Selecting() const; 6280 6281 /** 6282 Returns @true if the Shift key was down at the time of the event. 6283 */ 6284 bool ShiftDown() const; 6285 }; 6286 6287 6288 6289 /** 6290 @class wxGridSizeEvent 6291 6292 This event class contains information about a row/column resize event. 6293 6294 @beginEventTable{wxGridSizeEvent} 6295 @event{EVT_GRID_CMD_COL_SIZE(id, func)} 6296 The user resized a column, corresponds to @c wxEVT_GRID_COL_SIZE event 6297 type. 6298 @event{EVT_GRID_CMD_ROW_SIZE(id, func)} 6299 The user resized a row, corresponds to @c wxEVT_GRID_ROW_SIZE event 6300 type. 6301 @event{EVT_GRID_COL_SIZE(func)} 6302 Same as EVT_GRID_CMD_COL_SIZE() but uses `wxID_ANY` id. 6303 @event{EVT_GRID_COL_AUTO_SIZE(func)} 6304 This event is sent when a column must be resized to its best size, e.g. 6305 when the user double clicks the column divider. The default 6306 implementation simply resizes the column to fit the column label (but 6307 not its contents as this could be too slow for big grids). This macro 6308 corresponds to @c wxEVT_GRID_COL_AUTO_SIZE event type and is new since 6309 wxWidgets 2.9.5. 6310 @event{EVT_GRID_ROW_SIZE(func)} 6311 Same as EVT_GRID_CMD_ROW_SIZE() but uses `wxID_ANY` id. 6312 @endEventTable 6313 6314 @library{wxcore} 6315 @category{grid,events} 6316 */ 6317 class wxGridSizeEvent : public wxNotifyEvent 6318 { 6319 public: 6320 /** 6321 Default constructor. 6322 */ 6323 wxGridSizeEvent(); 6324 /** 6325 Constructor for initializing all event attributes. 6326 */ 6327 wxGridSizeEvent(int id, wxEventType type, wxObject* obj, 6328 int rowOrCol = -1, int x = -1, int y = -1, 6329 const wxKeyboardState& kbd = wxKeyboardState()); 6330 6331 /** 6332 Returns @true if the Alt key was down at the time of the event. 6333 */ 6334 bool AltDown() const; 6335 6336 /** 6337 Returns @true if the Control key was down at the time of the event. 6338 */ 6339 bool ControlDown() const; 6340 6341 /** 6342 Position in pixels at which the event occurred. 6343 */ 6344 wxPoint GetPosition() const; 6345 6346 /** 6347 Row or column at that was resized. 6348 */ 6349 int GetRowOrCol() const; 6350 6351 /** 6352 Returns @true if the Meta key was down at the time of the event. 6353 */ 6354 bool MetaDown() const; 6355 6356 /** 6357 Returns @true if the Shift key was down at the time of the event. 6358 */ 6359 bool ShiftDown() const; 6360 }; 6361 6362 6363 6364 /** 6365 @class wxGridRangeSelectEvent 6366 6367 Events of this class notify about a range of cells being selected. 6368 6369 When the user uses the mouse for selection, one or more @c SELECTING events 6370 are generated first, with @c SELECTED event generated at the end, when 6371 selection is final. This allows the application to handle either the @c 6372 SELECTING events if it needs to update its state in real-time, as the 6373 selection changes, or just the final @c SELECTED event, if updating its 6374 state on every selection change would be too time-consuming. 6375 6376 Note that if the user performs the selection from keyboard, @c SELECTING 6377 events are not generated at all, so @c SELECTED event still must be 6378 handled. 6379 6380 Finally, contrary to most of the other events with the name ending in 6381 "ing", @c SELECTING event can @e not be vetoed. 6382 6383 @beginEventTable{wxGridRangeSelectEvent} 6384 @event{EVT_GRID_RANGE_SELECTING(func)} 6385 The user is selecting a group of contiguous cells. Processes a 6386 @c wxEVT_GRID_RANGE_SELECTING event type. 6387 This event is available in wxWidgets 3.1.5 and later only. 6388 @event{EVT_GRID_CMD_RANGE_SELECTING(id, func)} 6389 The user is selecting a group of contiguous cells; variant taking a window 6390 identifier. Processes a @c wxEVT_GRID_RANGE_SELECTING event type. 6391 This event is available in wxWidgets 3.1.5 and later only. 6392 @event{EVT_GRID_RANGE_SELECTED(func)} 6393 The user selected a group of contiguous cells. Processes a 6394 @c wxEVT_GRID_RANGE_SELECTED event type. 6395 This event is available in wxWidgets 3.1.5 and later only and was 6396 called @c wxEVT_GRID_RANGE_SELECT in the previous versions. 6397 @event{EVT_GRID_CMD_RANGE_SELECTED(id, func)} 6398 The user selected a group of contiguous cells; variant taking a window 6399 identifier. Processes a @c wxEVT_GRID_RANGE_SELECTED event type. 6400 This event is available in wxWidgets 3.1.5 and later only and was 6401 called @c wxEVT_GRID_RANGE_SELECT in the previous versions. 6402 @endEventTable 6403 6404 @library{wxcore} 6405 @category{grid,events} 6406 */ 6407 class wxGridRangeSelectEvent : public wxNotifyEvent 6408 { 6409 public: 6410 /** 6411 Default constructor. 6412 */ 6413 wxGridRangeSelectEvent(); 6414 /** 6415 Constructor for initializing all event attributes. 6416 */ 6417 wxGridRangeSelectEvent(int id, wxEventType type, 6418 wxObject* obj, 6419 const wxGridCellCoords& topLeft, 6420 const wxGridCellCoords& bottomRight, 6421 bool sel = true, const wxKeyboardState& kbd = wxKeyboardState()); 6422 6423 /** 6424 Returns @true if the Alt key was down at the time of the event. 6425 */ 6426 bool AltDown() const; 6427 6428 /** 6429 Returns @true if the Control key was down at the time of the event. 6430 */ 6431 bool ControlDown() const; 6432 6433 /** 6434 Top left corner of the rectangular area that was (de)selected. 6435 */ 6436 wxGridCellCoords GetBottomRightCoords() const; 6437 6438 /** 6439 Bottom row of the rectangular area that was (de)selected. 6440 */ 6441 int GetBottomRow() const; 6442 6443 /** 6444 Left column of the rectangular area that was (de)selected. 6445 */ 6446 int GetLeftCol() const; 6447 6448 /** 6449 Right column of the rectangular area that was (de)selected. 6450 */ 6451 int GetRightCol() const; 6452 6453 /** 6454 Top left corner of the rectangular area that was (de)selected. 6455 */ 6456 wxGridCellCoords GetTopLeftCoords() const; 6457 6458 /** 6459 Top row of the rectangular area that was (de)selected. 6460 */ 6461 int GetTopRow() const; 6462 6463 /** 6464 Returns @true if the Meta key was down at the time of the event. 6465 */ 6466 bool MetaDown() const; 6467 6468 /** 6469 Returns @true if the area was selected, @false otherwise. 6470 */ 6471 bool Selecting() const; 6472 6473 /** 6474 Returns @true if the Shift key was down at the time of the event. 6475 */ 6476 bool ShiftDown() const; 6477 }; 6478 6479 6480 6481 /** 6482 @class wxGridEditorCreatedEvent 6483 6484 @beginEventTable{wxGridEditorCreatedEvent} 6485 @event{EVT_GRID_EDITOR_CREATED(func)} 6486 The editor for a cell was created. Processes a 6487 @c wxEVT_GRID_EDITOR_CREATED event type. 6488 @event{EVT_GRID_CMD_EDITOR_CREATED(id, func)} 6489 The editor for a cell was created; variant taking a window identifier. 6490 Processes a @c wxEVT_GRID_EDITOR_CREATED event type. 6491 @endEventTable 6492 6493 @library{wxcore} 6494 @category{grid,events} 6495 */ 6496 class wxGridEditorCreatedEvent : public wxCommandEvent 6497 { 6498 public: 6499 /** 6500 Default constructor. 6501 */ 6502 wxGridEditorCreatedEvent(); 6503 /** 6504 Constructor for initializing all event attributes. 6505 */ 6506 wxGridEditorCreatedEvent(int id, wxEventType type, wxObject* obj, 6507 int row, int col, wxControl* ctrl); 6508 6509 /** 6510 Returns the column at which the event occurred. 6511 */ 6512 int GetCol() const; 6513 6514 /** 6515 Returns the edit control. 6516 6517 This function is preserved for compatibility, but GetWindow() should be 6518 preferred in the new code as the associated window doesn't need to be of 6519 a wxControl-derived class. 6520 6521 Note that if SetWindow() had been called with an object not deriving 6522 from wxControl, this method will return @NULL. 6523 */ 6524 wxControl* GetControl(); 6525 6526 /** 6527 Returns the row at which the event occurred. 6528 */ 6529 int GetRow() const; 6530 6531 /** 6532 Returns the edit window. 6533 6534 @since 3.1.3 6535 */ 6536 wxWindow* GetWindow() const; 6537 6538 /** 6539 Sets the column at which the event occurred. 6540 */ 6541 void SetCol(int col); 6542 6543 /** 6544 Sets the edit control. 6545 6546 This function is preserved for compatibility, but SetWindow() should be 6547 preferred in the new code, see GetControl(). 6548 */ 6549 void SetControl(wxControl* ctrl); 6550 6551 /** 6552 Sets the row at which the event occurred. 6553 */ 6554 void SetRow(int row); 6555 6556 /** 6557 Sets the edit window. 6558 6559 @since 3.1.3 6560 */ 6561 void SetWindow(wxWindow* window); 6562 }; 6563 6564 6565 wxEventType wxEVT_GRID_CELL_LEFT_CLICK; 6566 wxEventType wxEVT_GRID_CELL_RIGHT_CLICK; 6567 wxEventType wxEVT_GRID_CELL_LEFT_DCLICK; 6568 wxEventType wxEVT_GRID_CELL_RIGHT_DCLICK; 6569 wxEventType wxEVT_GRID_LABEL_LEFT_CLICK; 6570 wxEventType wxEVT_GRID_LABEL_RIGHT_CLICK; 6571 wxEventType wxEVT_GRID_LABEL_LEFT_DCLICK; 6572 wxEventType wxEVT_GRID_LABEL_RIGHT_DCLICK; 6573 wxEventType wxEVT_GRID_ROW_SIZE; 6574 wxEventType wxEVT_GRID_COL_SIZE; 6575 wxEventType wxEVT_GRID_COL_AUTO_SIZE; 6576 wxEventType wxEVT_GRID_RANGE_SELECTING; 6577 wxEventType wxEVT_GRID_RANGE_SELECTED; 6578 wxEventType wxEVT_GRID_CELL_CHANGING; 6579 wxEventType wxEVT_GRID_CELL_CHANGED; 6580 wxEventType wxEVT_GRID_SELECT_CELL; 6581 wxEventType wxEVT_GRID_EDITOR_SHOWN; 6582 wxEventType wxEVT_GRID_EDITOR_HIDDEN; 6583 wxEventType wxEVT_GRID_EDITOR_CREATED; 6584 wxEventType wxEVT_GRID_CELL_BEGIN_DRAG; 6585 wxEventType wxEVT_GRID_COL_MOVE; 6586 wxEventType wxEVT_GRID_COL_SORT; 6587 wxEventType wxEVT_GRID_TABBING; 6588