interface/wx/grid.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        grid.h
   3 // Purpose:     interface of wxGrid and related classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxGridCellRenderer
  11
  12     This class is responsible for actually drawing the cell in the grid. You
  13     may pass it to the wxGridCellAttr (below) to change the format of one given
  14     cell or to wxGrid::SetDefaultRenderer() to change the view of all cells.
  15     This is an abstract class, and you will normally use one of the predefined
  16     derived classes or derive your own class from it.
  17
  18     @library{wxadv}
  19     @category{grid}
  20
  21     @see wxGridCellAutoWrapStringRenderer, wxGridCellBoolRenderer,
  22          wxGridCellDateTimeRenderer, wxGridCellEnumRenderer,
  23          wxGridCellFloatRenderer, wxGridCellNumberRenderer,
  24          wxGridCellStringRenderer
  25 */
  26 class wxGridCellRenderer
  27 {
  28 public:
  29     /**
  30         This function must be implemented in derived classes to return a copy
  31         of itself.
  32     */
  33     virtual wxGridCellRenderer* Clone() const = 0;
  34
  35     /**
  36         Draw the given cell on the provided DC inside the given rectangle using
  37         the style specified by the attribute and the default or selected state
  38         corresponding to the isSelected value.
  39
  40         This pure virtual function has a default implementation which will
  41         prepare the DC using the given attribute: it will draw the rectangle
  42         with the background colour from attr and set the text colour and font.
  43     */
  44     virtual void Draw(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc,
  45                       const wxRect& rect, int row, int col,
  46                       bool isSelected) = 0;
  47
  48     /**
  49         Get the preferred size of the cell for its contents.
  50     */
  51     virtual wxSize GetBestSize(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc,
  52                                int row, int col) = 0;
  53 };
  54
  55 /**
  56     @class wxGridCellAutoWrapStringRenderer
  57
  58     This class may be used to format string data in a cell. The too
  59     long lines are wrapped to be shown entirely at word boundaries.
  60
  61     @library{wxadv}
  62     @category{grid}
  63
  64     @see wxGridCellRenderer, wxGridCellBoolRenderer,
  65          wxGridCellDateTimeRenderer, wxGridCellEnumRenderer,
  66          wxGridCellFloatRenderer, wxGridCellNumberRenderer,
  67          wxGridCellStringRenderer
  68 */
  69
  70 class wxGridCellAutoWrapStringRenderer : public wxGridCellStringRenderer
  71 {
  72 public:
  73     /**
  74         Default constructor.
  75     */
  76     wxGridCellAutoWrapStringRenderer();
  77 };
  78
  79
  80 /**
  81     @class wxGridCellBoolRenderer
  82
  83     This class may be used to format boolean data in a cell.
  84
  85     @library{wxadv}
  86     @category{grid}
  87
  88     @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
  89          wxGridCellDateTimeRenderer, wxGridCellEnumRenderer,
  90          wxGridCellFloatRenderer, wxGridCellNumberRenderer,
  91          wxGridCellStringRenderer
  92 */
  93 class wxGridCellBoolRenderer : public wxGridCellRenderer
  94 {
  95 public:
  96     /**
  97         Default constructor.
  98     */
  99     wxGridCellBoolRenderer();
 100 };
 101
 102 /**
 103     @class wxGridCellDateTimeRenderer
 104
 105     This class may be used to format a date/time data in a cell.
 106     The class wxDateTime is used internally to display the local date/time
 107     or to parse the string date entered in the cell thanks to the defined format.
 108
 109     @library{wxadv}
 110     @category{grid}
 111
 112     @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
 113          wxGridCellBoolRenderer, wxGridCellEnumRenderer,
 114          wxGridCellFloatRenderer, wxGridCellNumberRenderer,
 115          wxGridCellStringRenderer
 116 */
 117 class wxGridCellDateTimeRenderer : public wxGridCellStringRenderer
 118 {
 119 public:
 120     /**
 121         Date/time renderer constructor.
 122
 123         @param outformat
 124             strptime()-like format string used the parse the output date/time.
 125         @param informat
 126             strptime()-like format string used to parse the string entered in the cell.
 127     */
 128     wxGridCellDateTimeRenderer(const wxString& outformat = wxDefaultDateTimeFormat,
 129                                const wxString& informat = wxDefaultDateTimeFormat);
 130
 131
 132     /**
 133         Sets the strptime()-like format string which will be used to parse
 134         the date/time.
 135
 136         @param params
 137             strptime()-like format string used to parse the date/time.
 138     */
 139     virtual void SetParameters(const wxString& params);
 140 };
 141
 142 /**
 143     @class wxGridCellEnumRenderer
 144
 145     This class may be used to render in a cell a number as a textual
 146     equivalent.
 147
 148     The corresponding text strings are specified as comma-separated items in
 149     the string passed to this renderer ctor or SetParameters() method. For
 150     example, if this string is @c "John,Fred,Bob" the cell will be rendered as
 151     "John", "Fred" or "Bob" if its contents is 0, 1 or 2 respectively.
 152
 153     @library{wxadv}
 154     @category{grid}
 155
 156     @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
 157          wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
 158          wxGridCellFloatRenderer, wxGridCellNumberRenderer,
 159          wxGridCellStringRenderer
 160 */
 161 class wxGridCellEnumRenderer : public wxGridCellStringRenderer
 162 {
 163 public:
 164     /**
 165         Enum renderer ctor.
 166
 167         @param choices
 168             Comma separated string parameters "item1[,item2[...,itemN]]".
 169     */
 170     wxGridCellEnumRenderer( const wxString& choices = wxEmptyString );
 171
 172     /**
 173         Sets the comma separated string content of the enum.
 174
 175         @param params
 176             Comma separated string parameters "item1[,item2[...,itemN]]".
 177     */
 178     virtual void SetParameters(const wxString& params);
 179 };
 180
 181 /**
 182     @class wxGridCellFloatRenderer
 183
 184     This class may be used to format floating point data in a cell.
 185
 186     @library{wxadv}
 187     @category{grid}
 188
 189     @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
 190          wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
 191          wxGridCellEnumRenderer, wxGridCellNumberRenderer,
 192          wxGridCellStringRenderer
 193 */
 194 class wxGridCellFloatRenderer : public wxGridCellStringRenderer
 195 {
 196 public:
 197     /**
 198         Float cell renderer ctor.
 199
 200         @param width
 201             Minimum number of characters to be shown.
 202         @param precision
 203             Number of digits after the decimal dot.
 204     */
 205     wxGridCellFloatRenderer(int width = -1, int precision = -1);
 206
 207     /**
 208         Returns the precision.
 209     */
 210     int GetPrecision() const;
 211
 212     /**
 213         Returns the width.
 214     */
 215     int GetWidth() const;
 216
 217     /**
 218         Parameters string format is "width[,precision]".
 219     */
 220     virtual void SetParameters(const wxString& params);
 221
 222     /**
 223         Sets the precision.
 224     */
 225     void SetPrecision(int precision);
 226
 227     /**
 228         Sets the width.
 229     */
 230     void SetWidth(int width);
 231 };
 232
 233 /**
 234     @class wxGridCellNumberRenderer
 235
 236     This class may be used to format integer data in a cell.
 237
 238     @library{wxadv}
 239     @category{grid}
 240
 241     @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
 242          wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
 243          wxGridCellEnumRenderer, wxGridCellFloatRenderer,
 244          wxGridCellStringRenderer
 245 */
 246 class wxGridCellNumberRenderer : public wxGridCellStringRenderer
 247 {
 248 public:
 249     /**
 250         Default constructor.
 251     */
 252     wxGridCellNumberRenderer();
 253 };
 254
 255 /**
 256     @class wxGridCellStringRenderer
 257
 258     This class may be used to format string data in a cell; it is the default
 259     for string cells.
 260
 261     @library{wxadv}
 262     @category{grid}
 263
 264     @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
 265          wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
 266          wxGridCellEnumRenderer, wxGridCellFloatRenderer,
 267          wxGridCellNumberRenderer
 268 */
 269 class wxGridCellStringRenderer : public wxGridCellRenderer
 270 {
 271 public:
 272     /**
 273         Default constructor.
 274     */
 275     wxGridCellStringRenderer();
 276 };
 277
 278
 279 /**
 280     @class wxGridCellEditor
 281
 282     This class is responsible for providing and manipulating the in-place edit
 283     controls for the grid.  Instances of wxGridCellEditor (actually, instances
 284     of derived classes since it is an abstract class) can be associated with
 285     the cell attributes for individual cells, rows, columns, or even for the
 286     entire grid.
 287
 288     @library{wxadv}
 289     @category{grid}
 290
 291     @see wxGridCellAutoWrapStringEditor, wxGridCellBoolEditor,
 292          wxGridCellChoiceEditor, wxGridCellEnumEditor,
 293          wxGridCellFloatEditor, wxGridCellNumberEditor,
 294          wxGridCellTextEditor
 295 */
 296 class wxGridCellEditor
 297 {
 298 public:
 299     /**
 300         Default constructor.
 301     */
 302     wxGridCellEditor();
 303
 304     /**
 305         Fetch the value from the table and prepare the edit control to begin
 306         editing.
 307
 308         This function should save the original value of the grid cell at the
 309         given @a row and @a col and show the control allowing the user to
 310         change it.
 311
 312         @see EndEdit()
 313     */
 314     virtual void BeginEdit(int row, int col, wxGrid* grid) = 0;
 315
 316     /**
 317         Create a new object which is the copy of this one.
 318     */
 319     virtual wxGridCellEditor* Clone() const = 0;
 320
 321     /**
 322         Creates the actual edit control.
 323     */
 324     virtual void Create(wxWindow* parent, wxWindowID id,
 325                         wxEvtHandler* evtHandler) = 0;
 326
 327     /**
 328         Final cleanup.
 329     */
 330     virtual void Destroy();
 331
 332     /**
 333         End editing the cell.
 334
 335         This function must check if the current value of the editing control is
 336         valid and different from the original value (available as @a oldval in
 337         its string form and possibly saved internally using its real type by
 338         BeginEdit()). If it isn't, it just returns @false, otherwise it must do
 339         the following:
 340             # Save the new value internally so that ApplyEdit() could apply it.
 341             # Fill @a newval (which is never @NULL) with the string
 342             representation of the new value.
 343             # Return @true
 344
 345         Notice that it must @em not modify the grid as the change could still
 346         be vetoed.
 347
 348         If the user-defined wxEVT_GRID_CELL_CHANGING event handler doesn't veto
 349         this change, ApplyEdit() will be called next.
 350     */
 351     virtual bool EndEdit(int row, int col, const wxGrid* grid,
 352                          const wxString& oldval, wxString* newval) = 0;
 353
 354     /**
 355         Effectively save the changes in the grid.
 356
 357         This function should save the value of the control in the grid. It is
 358         called only after EndEdit() returns @true.
 359      */
 360     virtual void ApplyEdit(int row, int col, wxGrid* grid) = 0;
 361
 362     /**
 363         Some types of controls on some platforms may need some help with the
 364         Return key.
 365     */
 366     virtual void HandleReturn(wxKeyEvent& event);
 367
 368     /**
 369         Returns @true if the edit control has been created.
 370     */
 371     bool IsCreated();
 372
 373     /**
 374         Draws the part of the cell not occupied by the control: the base class
 375         version just fills it with background colour from the attribute.
 376     */
 377     virtual void PaintBackground(const wxRect& rectCell, wxGridCellAttr* attr);
 378
 379     /**
 380         Reset the value in the control back to its starting value.
 381     */
 382     virtual void Reset() = 0;
 383
 384     /**
 385         Size and position the edit control.
 386     */
 387     virtual void SetSize(const wxRect& rect);
 388
 389     /**
 390         Show or hide the edit control, use the specified attributes to set
 391         colours/fonts for it.
 392     */
 393     virtual void Show(bool show, wxGridCellAttr* attr = NULL);
 394
 395     /**
 396         If the editor is enabled by clicking on the cell, this method will be
 397         called.
 398     */
 399     virtual void StartingClick();
 400
 401     /**
 402         If the editor is enabled by pressing keys on the grid, this will be
 403         called to let the editor do something about that first key if desired.
 404     */
 405     virtual void StartingKey(wxKeyEvent& event);
 406
 407 protected:
 408
 409     /**
 410         The destructor is private because only DecRef() can delete us.
 411     */
 412     virtual ~wxGridCellEditor();
 413 };
 414
 415 /**
 416     @class wxGridCellAutoWrapStringEditor
 417
 418     Grid cell editor for wrappable string/text data.
 419
 420     @library{wxadv}
 421     @category{grid}
 422
 423     @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor,
 424          wxGridCellEnumEditor, wxGridCellFloatEditor,
 425          wxGridCellNumberEditor, wxGridCellTextEditor
 426 */
 427 class wxGridCellAutoWrapStringEditor : public wxGridCellTextEditor
 428 {
 429 public:
 430     wxGridCellAutoWrapStringEditor();
 431 };
 432
 433 /**
 434     @class wxGridCellBoolEditor
 435
 436     Grid cell editor for boolean data.
 437
 438     @library{wxadv}
 439     @category{grid}
 440
 441     @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
 442          wxGridCellChoiceEditor, wxGridCellEnumEditor,
 443          wxGridCellFloatEditor, wxGridCellNumberEditor,
 444          wxGridCellTextEditor
 445 */
 446 class wxGridCellBoolEditor : public wxGridCellEditor
 447 {
 448 public:
 449     /**
 450         Default constructor.
 451     */
 452     wxGridCellBoolEditor();
 453
 454     /**
 455         Returns @true if the given @a value is equal to the string
 456         representation of the truth value we currently use (see
 457         UseStringValues()).
 458     */
 459     static bool IsTrueValue(const wxString& value);
 460
 461     /**
 462         This method allows you to customize the values returned by GetValue()
 463         for the cell using this editor. By default, the default values of the
 464         arguments are used, i.e. @c "1" is returned if the cell is checked and
 465         an empty string otherwise.
 466     */
 467     static void UseStringValues(const wxString& valueTrue = "1",
 468                                 const wxString& valueFalse = wxEmptyString);
 469 };
 470
 471 /**
 472     @class wxGridCellChoiceEditor
 473
 474     Grid cell editor for string data providing the user a choice from a list of
 475     strings.
 476
 477     @library{wxadv}
 478     @category{grid}
 479
 480     @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
 481          wxGridCellBoolEditor, wxGridCellEnumEditor,
 482          wxGridCellFloatEditor, wxGridCellNumberEditor,
 483          wxGridCellTextEditor
 484 */
 485 class wxGridCellChoiceEditor : public wxGridCellEditor
 486 {
 487 public:
 488     /**
 489         Choice cell renderer ctor.
 490
 491         @param count
 492             Number of strings from which the user can choose.
 493         @param choices
 494             An array of strings from which the user can choose.
 495         @param allowOthers
 496             If allowOthers is @true, the user can type a string not in choices
 497             array.
 498     */
 499     wxGridCellChoiceEditor(size_t count = 0,
 500                            const wxString choices[] = NULL,
 501                            bool allowOthers = false);
 502
 503     /**
 504         Choice cell renderer ctor.
 505
 506         @param choices
 507             An array of strings from which the user can choose.
 508         @param allowOthers
 509             If allowOthers is @true, the user can type a string not in choices
 510             array.
 511     */
 512     wxGridCellChoiceEditor(const wxArrayString& choices,
 513                            bool allowOthers = false);
 514
 515     /**
 516         Parameters string format is "item1[,item2[...,itemN]]"
 517     */
 518     virtual void SetParameters(const wxString& params);
 519 };
 520
 521 /**
 522     @class wxGridCellEnumEditor
 523
 524     Grid cell editor which displays an enum number as a textual equivalent
 525     (eg. data in cell is 0,1,2 ... n the cell could be displayed as
 526     "John","Fred"..."Bob" in the combo choice box).
 527
 528     @library{wxadv}
 529     @category{grid}
 530
 531     @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
 532          wxGridCellBoolEditor, wxGridCellChoiceEditor,
 533          wxGridCellTextEditor, wxGridCellFloatEditor,
 534          wxGridCellNumberEditor
 535 */
 536 class wxGridCellEnumEditor : public wxGridCellChoiceEditor
 537 {
 538 public:
 539     /**
 540         Enum cell editor ctor.
 541
 542         @param choices
 543             Comma separated choice parameters "item1[,item2[...,itemN]]".
 544     */
 545     wxGridCellEnumEditor( const wxString& choices = wxEmptyString );
 546 };
 547
 548 /**
 549     @class wxGridCellTextEditor
 550
 551     Grid cell editor for string/text data.
 552
 553     @library{wxadv}
 554     @category{grid}
 555
 556     @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
 557          wxGridCellBoolEditor, wxGridCellChoiceEditor,
 558          wxGridCellEnumEditor, wxGridCellFloatEditor,
 559          wxGridCellNumberEditor
 560 */
 561 class wxGridCellTextEditor : public wxGridCellEditor
 562 {
 563 public:
 564     /**
 565         Default constructor.
 566     */
 567     wxGridCellTextEditor();
 568
 569     /**
 570         The parameters string format is "n" where n is a number representing
 571         the maximum width.
 572     */
 573     virtual void SetParameters(const wxString& params);
 574 };
 575
 576 /**
 577     @class wxGridCellFloatEditor
 578
 579     The editor for floating point numbers data.
 580
 581     @library{wxadv}
 582     @category{grid}
 583
 584     @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
 585          wxGridCellBoolEditor, wxGridCellChoiceEditor,
 586          wxGridCellEnumEditor, wxGridCellNumberEditor,
 587          wxGridCellTextEditor
 588 */
 589 class wxGridCellFloatEditor : public wxGridCellTextEditor
 590 {
 591 public:
 592     /**
 593         Float cell editor ctor.
 594
 595         @param width
 596             Minimum number of characters to be shown.
 597         @param precision
 598             Number of digits after the decimal dot.
 599     */
 600     wxGridCellFloatEditor(int width = -1, int precision = -1);
 601
 602     /**
 603         Parameters string format is "width,precision"
 604     */
 605     virtual void SetParameters(const wxString& params);
 606 };
 607
 608 /**
 609     @class wxGridCellNumberEditor
 610
 611     Grid cell editor for numeric integer data.
 612
 613     @library{wxadv}
 614     @category{grid}
 615
 616     @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
 617          wxGridCellBoolEditor, wxGridCellChoiceEditor,
 618          wxGridCellEnumEditor, wxGridCellFloatEditor,
 619          wxGridCellTextEditor
 620 */
 621 class wxGridCellNumberEditor : public wxGridCellTextEditor
 622 {
 623 public:
 624     /**
 625         Allows you to specify the range for acceptable data. Values equal to
 626         -1 for both @a min and @a max indicate that no range checking should be
 627         done.
 628     */
 629     wxGridCellNumberEditor(int min = -1, int max = -1);
 630
 631
 632     /**
 633         Parameters string format is "min,max".
 634     */
 635     virtual void SetParameters(const wxString& params);
 636
 637 protected:
 638
 639     /**
 640         If the return value is @true, the editor uses a wxSpinCtrl to get user
 641         input, otherwise it uses a wxTextCtrl.
 642     */
 643     bool HasRange() const;
 644
 645     /**
 646         String representation of the value.
 647     */
 648     wxString GetString() const;
 649 };
 650
 651
 652
 653 /**
 654     @class wxGridCellAttr
 655
 656     This class can be used to alter the cells' appearance in the grid by
 657     changing their attributes from the defaults. An object of this class may be
 658     returned by wxGridTableBase::GetAttr().
 659
 660     @library{wxadv}
 661     @category{grid}
 662 */
 663 class wxGridCellAttr
 664 {
 665 public:
 666     /**
 667         Kind of the attribute to retrieve.
 668
 669         @see wxGridCellAttrProvider::GetAttr(), wxGridTableBase::GetAttr()
 670      */
 671     enum wxAttrKind
 672     {
 673         /// Return the combined effective attribute for the cell.
 674         Any,
 675
 676         /// Return the attribute explicitly set for this cell.
 677         Cell,
 678
 679         /// Return the attribute set for this cells row.
 680         Row,
 681
 682         /// Return the attribute set for this cells column.
 683         Col
 684     };
 685
 686     /**
 687         Default constructor.
 688     */
 689     wxGridCellAttr(wxGridCellAttr* attrDefault = NULL);
 690     /**
 691         Constructor specifying some of the often used attributes.
 692     */
 693     wxGridCellAttr(const wxColour& colText, const wxColour& colBack,
 694                    const wxFont& font, int hAlign, int vAlign);
 695
 696     /**
 697         Creates a new copy of this object.
 698     */
 699     wxGridCellAttr* Clone() const;
 700
 701     /**
 702         This class is reference counted: it is created with ref count of 1, so
 703         calling DecRef() once will delete it. Calling IncRef() allows to lock
 704         it until the matching DecRef() is called.
 705     */
 706     void DecRef();
 707
 708     /**
 709         Get the alignment to use for the cell with the given attribute.
 710
 711         If this attribute doesn't specify any alignment, the default attribute
 712         alignment is used (which can be changed using
 713         wxGrid::SetDefaultCellAlignment() but is left and top by default).
 714
 715         Notice that @a hAlign and @a vAlign values are always overwritten by
 716         this function, use GetNonDefaultAlignment() if this is not desirable.
 717
 718         @param hAlign
 719             Horizontal alignment is returned here if this argument is non-@NULL.
 720             It is one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT.
 721         @param vAlign
 722             Vertical alignment is returned here if this argument is non-@NULL.
 723             It is one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM.
 724     */
 725     void GetAlignment(int* hAlign, int* vAlign) const;
 726
 727     /**
 728         Returns the background colour.
 729     */
 730     const wxColour& GetBackgroundColour() const;
 731
 732     /**
 733         Returns the cell editor.
 734     */
 735     wxGridCellEditor* GetEditor(const wxGrid* grid, int row, int col) const;
 736
 737     /**
 738         Returns the font.
 739     */
 740     const wxFont& GetFont() const;
 741
 742     /**
 743         Get the alignment defined by this attribute.
 744
 745         Unlike GetAlignment() this function only modifies @a hAlign and @a
 746         vAlign if this attribute does define a non-default alignment. This
 747         means that they must be initialized before calling this function and
 748         that their values will be preserved unchanged if they are different
 749         from wxALIGN_INVALID.
 750
 751         For example, the following fragment can be used to use the cell
 752         alignment if one is defined but right-align its contents by default
 753         (instead of left-aligning it by default) while still using the default
 754         vertical alignment:
 755         @code
 756             int hAlign = wxALIGN_RIGHT,
 757                 vAlign = wxALIGN_INVALID;
 758             attr.GetNonDefaultAlignment(&hAlign, &vAlign);
 759         @endcode
 760
 761         @since 2.9.1
 762      */
 763     void GetNonDefaultAlignment(int *hAlign, int *vAlign) const;
 764
 765     /**
 766         Returns the cell renderer.
 767     */
 768     wxGridCellRenderer* GetRenderer(const wxGrid* grid, int row, int col) const;
 769
 770     /**
 771         Returns the text colour.
 772     */
 773     const wxColour& GetTextColour() const;
 774
 775     /**
 776         Returns @true if this attribute has a valid alignment set.
 777     */
 778     bool HasAlignment() const;
 779
 780     /**
 781         Returns @true if this attribute has a valid background colour set.
 782     */
 783     bool HasBackgroundColour() const;
 784
 785     /**
 786         Returns @true if this attribute has a valid cell editor set.
 787     */
 788     bool HasEditor() const;
 789
 790     /**
 791         Returns @true if this attribute has a valid font set.
 792     */
 793     bool HasFont() const;
 794
 795     /**
 796         Returns @true if this attribute has a valid cell renderer set.
 797     */
 798     bool HasRenderer() const;
 799
 800     /**
 801         Returns @true if this attribute has a valid text colour set.
 802     */
 803     bool HasTextColour() const;
 804
 805     /**
 806         This class is reference counted: it is created with ref count of 1, so
 807         calling DecRef() once will delete it. Calling IncRef() allows to lock
 808         it until the matching DecRef() is called.
 809     */
 810     void IncRef();
 811
 812     /**
 813         Returns @true if this cell is set as read-only.
 814     */
 815     bool IsReadOnly() const;
 816
 817     /**
 818         Sets the alignment. @a hAlign can be one of @c wxALIGN_LEFT,
 819         @c wxALIGN_CENTRE or @c wxALIGN_RIGHT and @a vAlign can be one of
 820         @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
 821     */
 822     void SetAlignment(int hAlign, int vAlign);
 823
 824     /**
 825         Sets the background colour.
 826     */
 827     void SetBackgroundColour(const wxColour& colBack);
 828
 829     /**
 830         @todo Needs documentation.
 831     */
 832     void SetDefAttr(wxGridCellAttr* defAttr);
 833
 834     /**
 835         Sets the editor to be used with the cells with this attribute.
 836     */
 837     void SetEditor(wxGridCellEditor* editor);
 838
 839     /**
 840         Sets the font.
 841     */
 842     void SetFont(const wxFont& font);
 843
 844     /**
 845         Sets the cell as read-only.
 846     */
 847     void SetReadOnly(bool isReadOnly = true);
 848
 849     /**
 850         Sets the renderer to be used for cells with this attribute. Takes
 851         ownership of the pointer.
 852     */
 853     void SetRenderer(wxGridCellRenderer* renderer);
 854
 855     /**
 856         Sets the text colour.
 857     */
 858     void SetTextColour(const wxColour& colText);
 859 };
 860
 861 /**
 862     Base class for corner window renderer.
 863
 864     This is the simplest of all header renderers and only has a single
 865     function.
 866
 867     @see wxGridCellAttrProvider::GetCornerRenderer()
 868
 869     @since 2.9.1
 870  */
 871 class wxGridCornerHeaderRenderer
 872 {
 873 public:
 874     /**
 875         Called by the grid to draw the corner window border.
 876
 877         This method is responsible for drawing the border inside the given @a
 878         rect and adjusting the rectangle size to correspond to the area inside
 879         the border, i.e. usually call wxRect::Deflate() to account for the
 880         border width.
 881
 882         @param grid
 883             The grid whose corner window is being drawn.
 884         @param dc
 885             The device context to use for drawing.
 886         @param rect
 887             Input/output parameter which contains the border rectangle on input
 888             and should be updated to contain the area inside the border on
 889             function return.
 890      */
 891     virtual void DrawBorder(const wxGrid& grid,
 892                             wxDC& dc,
 893                             wxRect& rect) const = 0;
 894 };
 895 /**
 896     Common base class for row and column headers renderers.
 897
 898     @see wxGridColumnHeaderRenderer, wxGridRowHeaderRenderer
 899
 900     @since 2.9.1
 901  */
 902 class wxGridHeaderLabelsRenderer : public wxGridCornerHeaderRenderer
 903 {
 904 public:
 905     /**
 906         Called by the grid to draw the specified label.
 907
 908         Notice that the base class DrawBorder() method is called before this
 909         one.
 910
 911         The default implementation uses wxGrid::GetLabelTextColour() and
 912         wxGrid::GetLabelFont() to draw the label.
 913      */
 914     virtual void DrawLabel(const wxGrid& grid,
 915                            wxDC& dc,
 916                            const wxString& value,
 917                            const wxRect& rect,
 918                            int horizAlign,
 919                            int vertAlign,
 920                            int textOrientation) const;
 921 };
 922
 923 /**
 924     Base class for row headers renderer.
 925
 926     This is the same as wxGridHeaderLabelsRenderer currently but we still use a
 927     separate class for it to distinguish it from wxGridColumnHeaderRenderer.
 928
 929     @see wxGridRowHeaderRendererDefault
 930
 931     @see wxGridCellAttrProvider::GetRowHeaderRenderer()
 932
 933     @since 2.9.1
 934  */
 935 class wxGridRowHeaderRenderer : public wxGridHeaderLabelsRenderer
 936 {
 937 };
 938
 939 /**
 940     Base class for column headers renderer.
 941
 942     This is the same as wxGridHeaderLabelsRenderer currently but we still use a
 943     separate class for it to distinguish it from wxGridRowHeaderRenderer.
 944
 945     @see wxGridColumnHeaderRendererDefault
 946
 947     @see wxGridCellAttrProvider::GetColumnHeaderRenderer()
 948
 949     @since 2.9.1
 950  */
 951 class wxGridColumnHeaderRenderer : public wxGridHeaderLabelsRenderer
 952 {
 953 };
 954
 955 /**
 956     Default row header renderer.
 957
 958     You may derive from this class if you need to only override one of its
 959     methods (i.e. either DrawLabel() or DrawBorder()) but continue to use the
 960     default implementation for the other one.
 961
 962     @see wxGridColumnHeaderRendererDefault
 963
 964     @since 2.9.1
 965  */
 966 class wxGridRowHeaderRendererDefault : public wxGridRowHeaderRenderer
 967 {
 968 public:
 969     /// Implement border drawing for the row labels.
 970     virtual void DrawBorder(const wxGrid& grid,
 971                             wxDC& dc,
 972                             wxRect& rect) const;
 973 };
 974
 975 /**
 976     Default column header renderer.
 977
 978     @see wxGridRowHeaderRendererDefault
 979
 980     @since 2.9.1
 981  */
 982 class wxGridColumnHeaderRendererDefault : public wxGridColumnHeaderRenderer
 983 {
 984 public:
 985     /// Implement border drawing for the column labels.
 986     virtual void DrawBorder(const wxGrid& grid,
 987                             wxDC& dc,
 988                             wxRect& rect) const;
 989 };
 990
 991 /**
 992     Default corner window renderer.
 993
 994     @see wxGridColumnHeaderRendererDefault, wxGridRowHeaderRendererDefault
 995
 996     @since 2.9.1
 997  */
 998 class wxGridCornerHeaderRendererDefault : public wxGridCornerHeaderRenderer
 999 {
1000 public:
1001     /// Implement border drawing for the corner window.
1002     virtual void DrawBorder(const wxGrid& grid,
1003                             wxDC& dc,
1004                             wxRect& rect) const;
1005 };
1006
1007 /**
1008     Class providing attributes to be used for the grid cells.
1009
1010     This class both defines an interface which grid cell attributes providers
1011     should implement -- and which can be implemented differently in derived
1012     classes -- and a default implementation of this interface which is often
1013     good enough to be used without modification, especially with not very large
1014     grids for which the efficiency of attributes storage hardly matters (see
1015     the discussion below).
1016
1017     An object of this class can be associated with a wxGrid using
1018     wxGridTableBase::SetAttrProvider() but it's not necessary to call it if you
1019     intend to use the default provider as it is used by wxGridTableBase by
1020     default anyhow.
1021
1022     Notice that while attributes provided by this class can be set for
1023     individual cells using SetAttr() or the entire rows or columns using
1024     SetRowAttr() and SetColAttr() they are always retrieved using GetAttr()
1025     function.
1026
1027
1028     The default implementation of this class stores the attributes passed to
1029     its SetAttr(), SetRowAttr() and SetColAttr() in a straightforward way. A
1030     derived class may use its knowledge about how the attributes are used in
1031     your program to implement it much more efficiently: for example, using a
1032     special background colour for all even-numbered rows can be implemented by
1033     simply returning the same attribute from GetAttr() if the row number is
1034     even instead of having to store N/2 row attributes where N is the total
1035     number of rows in the grid.
1036
1037     Notice that objects of this class can't be copied.
1038  */
1039 class wxGridCellAttrProvider : public wxClientDataContainer
1040 {
1041 public:
1042     /// Trivial default constructor.
1043     wxGridCellAttrProvider();
1044
1045     /// Destructor releases any attributes held by this class.
1046     virtual ~wxGridCellAttrProvider();
1047
1048     /**
1049         Get the attribute to use for the specified cell.
1050
1051         If wxGridCellAttr::Any is used as @a kind value, this function combines
1052         the attributes set for this cell using SetAttr() and those for its row
1053         or column (set with SetRowAttr() or SetColAttr() respectively), with
1054         the cell attribute having the highest precedence.
1055
1056         Notice that the caller must call DecRef() on the returned pointer if it
1057         is non-@NULL.
1058
1059         @param row
1060             The row of the cell.
1061         @param col
1062             The column of the cell.
1063         @param kind
1064             The kind of the attribute to return.
1065         @return
1066             The attribute to use which should be DecRef()'d by caller or @NULL
1067             if no attributes are defined for this cell.
1068      */
1069     virtual wxGridCellAttr *GetAttr(int row, int col,
1070                                     wxGridCellAttr::wxAttrKind kind) const;
1071
1072     /**
1073         Setting attributes.
1074
1075         All these functions take ownership of the attribute passed to them,
1076         i.e. will call DecRef() on it themselves later and so it should not be
1077         destroyed by the caller. And the attribute can be @NULL to reset a
1078         previously set value.
1079      */
1080     //@{
1081
1082     /// Set attribute for the specified cell.
1083     virtual void SetAttr(wxGridCellAttr *attr, int row, int col);
1084
1085     /// Set attribute for the specified row.
1086     virtual void SetRowAttr(wxGridCellAttr *attr, int row);
1087
1088     /// Set attribute for the specified column.
1089     virtual void SetColAttr(wxGridCellAttr *attr, int col);
1090
1091     //@}
1092
1093     /**
1094         Getting header renderers.
1095
1096         These functions return the renderers for the given row or column header
1097         label and the corner window. Unlike cell attributes, these objects are
1098         not reference counted and are never @NULL so they are returned by
1099         reference and not pointer and DecRef() shouldn't (and can't) be called
1100         for them.
1101
1102         All these functions were added in wxWidgets 2.9.1.
1103      */
1104     //@{
1105
1106     /**
1107         Return the renderer used for drawing column headers.
1108
1109         By default wxGridColumnHeaderRendererDefault is returned.
1110
1111         @see wxGrid::SetUseNativeColLabels(), wxGrid::UseNativeColHeader()
1112
1113         @since 2.9.1
1114      */
1115     virtual const wxGridColumnHeaderRenderer& GetColumnHeaderRenderer(int col);
1116
1117     /**
1118         Return the renderer used for drawing row headers.
1119
1120         By default wxGridRowHeaderRendererDefault is returned.
1121
1122         @since 2.9.1
1123      */
1124     virtual const wxGridRowHeaderRenderer& GetRowHeaderRenderer(int row);
1125
1126     /**
1127         Return the renderer used for drawing the corner window.
1128
1129         By default wxGridCornerHeaderRendererDefault is returned.
1130
1131         @since 2.9.1
1132      */
1133     virtual const wxGridCornerHeaderRenderer& GetCornerRenderer();
1134
1135     //@}
1136 };
1137
1138
1139 /**
1140     @class wxGridTableBase
1141
1142     The almost abstract base class for grid tables.
1143
1144     A grid table is responsible for storing the grid data and, indirectly, grid
1145     cell attributes. The data can be stored in the way most convenient for the
1146     application but has to be provided in string form to wxGrid. It is also
1147     possible to provide cells values in other formats if appropriate, e.g. as
1148     numbers.
1149
1150     This base class is not quite abstract as it implements a trivial strategy
1151     for storing the attributes by forwarding it to wxGridCellAttrProvider and
1152     also provides stubs for some other functions. However it does have a number
1153     of pure virtual methods which must be implemented in the derived classes.
1154
1155     @see wxGridStringTable
1156
1157     @library{wxadv}
1158     @category{grid}
1159 */
1160 class wxGridTableBase : public wxObject
1161 {
1162 public:
1163     /**
1164         Default constructor.
1165      */
1166     wxGridTableBase();
1167
1168     /**
1169         Destructor frees the attribute provider if it was created.
1170      */
1171     virtual ~wxGridTableBase();
1172
1173     /**
1174         Must be overridden to return the number of rows in the table.
1175
1176         For backwards compatibility reasons, this method is not const.
1177         Use GetRowsCount() instead of it in const methods of derived table
1178         classes.
1179      */
1180     virtual int GetNumberRows() = 0;
1181
1182     /**
1183         Must be overridden to return the number of columns in the table.
1184
1185         For backwards compatibility reasons, this method is not const.
1186         Use GetColsCount() instead of it in const methods of derived table
1187         classes,
1188      */
1189     virtual int GetNumberCols() = 0;
1190
1191     /**
1192         Return the number of rows in the table.
1193
1194         This method is not virtual and is only provided as a convenience for
1195         the derived classes which can't call GetNumberRows() without a
1196         @c const_cast from their const methods.
1197      */
1198     int GetRowsCount() const;
1199
1200     /**
1201         Return the number of columns in the table.
1202
1203         This method is not virtual and is only provided as a convenience for
1204         the derived classes which can't call GetNumberCols() without a
1205         @c const_cast from their const methods.
1206      */
1207     int GetColsCount() const;
1208
1209
1210     /**
1211         @name Table Cell Accessors
1212      */
1213     //@{
1214
1215     /**
1216         May be overridden to implement testing for empty cells.
1217
1218         This method is used by the grid to test if the given cell is not used
1219         and so whether a neighbouring cell may overflow into it. By default it
1220         only returns true if the value of the given cell, as returned by
1221         GetValue(), is empty.
1222      */
1223     virtual bool IsEmptyCell(int row, int col);
1224
1225     /**
1226         Same as IsEmptyCell() but taking wxGridCellCoords.
1227
1228         Notice that this method is not virtual, only IsEmptyCell() should be
1229         overridden.
1230      */
1231     bool IsEmpty(const wxGridCellCoords& coords);
1232
1233     /**
1234         Must be overridden to implement accessing the table values as text.
1235      */
1236     virtual wxString GetValue(int row, int col) = 0;
1237
1238     /**
1239         Must be overridden to implement setting the table values as text.
1240      */
1241     virtual void SetValue(int row, int col, const wxString& value) = 0;
1242
1243     /**
1244         Returns the type of the value in the given cell.
1245
1246         By default all cells are strings and this method returns
1247         @c wxGRID_VALUE_STRING.
1248      */
1249     virtual wxString GetTypeName(int row, int col);
1250
1251     /**
1252         Returns true if the value of the given cell can be accessed as if it
1253         were of the specified type.
1254
1255         By default the cells can only be accessed as strings. Note that a cell
1256         could be accessible in different ways, e.g. a numeric cell may return
1257         @true for @c wxGRID_VALUE_NUMBER but also for @c wxGRID_VALUE_STRING
1258         indicating that the value can be coerced to a string form.
1259      */
1260     virtual bool CanGetValueAs(int row, int col, const wxString& typeName);
1261
1262     /**
1263         Returns true if the value of the given cell can be set as if it were of
1264         the specified type.
1265
1266         @see CanGetValueAs()
1267      */
1268     virtual bool CanSetValueAs(int row, int col, const wxString& typeName);
1269
1270     /**
1271         Returns the value of the given cell as a long.
1272
1273         This should only be called if CanGetValueAs() returns @true when called
1274         with @c wxGRID_VALUE_NUMBER argument. Default implementation always
1275         return 0.
1276      */
1277     virtual long GetValueAsLong(int row, int col);
1278
1279     /**
1280         Returns the value of the given cell as a double.
1281
1282         This should only be called if CanGetValueAs() returns @true when called
1283         with @c wxGRID_VALUE_FLOAT argument. Default implementation always
1284         return 0.0.
1285      */
1286     virtual double GetValueAsDouble(int row, int col);
1287
1288     /**
1289         Returns the value of the given cell as a boolean.
1290
1291         This should only be called if CanGetValueAs() returns @true when called
1292         with @c wxGRID_VALUE_BOOL argument. Default implementation always
1293         return false.
1294      */
1295     virtual bool GetValueAsBool(int row, int col);
1296
1297     /**
1298         Returns the value of the given cell as a user-defined type.
1299
1300         This should only be called if CanGetValueAs() returns @true when called
1301         with @a typeName. Default implementation always return @NULL.
1302      */
1303     virtual void *GetValueAsCustom(int row, int col, const wxString& typeName);
1304
1305     /**
1306         Sets the value of the given cell as a long.
1307
1308         This should only be called if CanSetValueAs() returns @true when called
1309         with @c wxGRID_VALUE_NUMBER argument. Default implementation doesn't do
1310         anything.
1311      */
1312     virtual void SetValueAsLong(int row, int col, long value);
1313
1314     /**
1315         Sets the value of the given cell as a double.
1316
1317         This should only be called if CanSetValueAs() returns @true when called
1318         with @c wxGRID_VALUE_FLOAT argument. Default implementation doesn't do
1319         anything.
1320      */
1321     virtual void SetValueAsDouble(int row, int col, double value);
1322
1323     /**
1324         Sets the value of the given cell as a boolean.
1325
1326         This should only be called if CanSetValueAs() returns @true when called
1327         with @c wxGRID_VALUE_BOOL argument. Default implementation doesn't do
1328         anything.
1329      */
1330     virtual void SetValueAsBool( int row, int col, bool value );
1331
1332     /**
1333         Sets the value of the given cell as a user-defined type.
1334
1335         This should only be called if CanSetValueAs() returns @true when called
1336         with @a typeName. Default implementation doesn't do anything.
1337      */
1338     virtual void SetValueAsCustom(int row, int col, const wxString& typeName,
1339                                   void *value);
1340
1341     //@}
1342
1343
1344     /**
1345         Called by the grid when the table is associated with it.
1346
1347         The default implementation stores the pointer and returns it from its
1348         GetView() and so only makes sense if the table cannot be associated
1349         with more than one grid at a time.
1350      */
1351     virtual void SetView(wxGrid *grid);
1352
1353     /**
1354         Returns the last grid passed to SetView().
1355      */
1356     virtual wxGrid *GetView() const;
1357
1358
1359     /**
1360         @name Table Structure Modifiers
1361
1362         Notice that none of these functions are pure virtual as they don't have
1363         to be implemented if the table structure is never modified after
1364         creation, i.e. neither rows nor columns are never added or deleted but
1365         that you do need to implement them if they are called, i.e. if your
1366         code either calls them directly or uses the matching wxGrid methods, as
1367         by default they simply do nothing which is definitely inappropriate.
1368      */
1369     //@{
1370
1371     /**
1372         Clear the table contents.
1373
1374         This method is used by wxGrid::ClearGrid().
1375      */
1376     virtual void Clear();
1377
1378     /**
1379         Insert additional rows into the table.
1380
1381         @param pos
1382             The position of the first new row.
1383         @param numRows
1384             The number of rows to insert.
1385      */
1386     virtual bool InsertRows(size_t pos = 0, size_t numRows = 1);
1387
1388     /**
1389         Append additional rows at the end of the table.
1390
1391         This method is provided in addition to InsertRows() as some data models
1392         may only support appending rows to them but not inserting them at
1393         arbitrary locations. In such case you may implement this method only
1394         and leave InsertRows() unimplemented.
1395
1396         @param numRows
1397             The number of rows to add.
1398      */
1399     virtual bool AppendRows(size_t numRows = 1);
1400
1401     /**
1402         Delete rows from the table.
1403
1404         @param pos
1405             The first row to delete.
1406         @param numRows
1407             The number of rows to delete.
1408      */
1409     virtual bool DeleteRows(size_t pos = 0, size_t numRows = 1);
1410
1411     /**
1412         Exactly the same as InsertRows() but for columns.
1413      */
1414     virtual bool InsertCols(size_t pos = 0, size_t numCols = 1);
1415
1416     /**
1417         Exactly the same as AppendRows() but for columns.
1418      */
1419     virtual bool AppendCols(size_t numCols = 1);
1420
1421     /**
1422         Exactly the same as DeleteRows() but for columns.
1423      */
1424     virtual bool DeleteCols(size_t pos = 0, size_t numCols = 1);
1425
1426     //@}
1427
1428     /**
1429         @name Table Row and Column Labels
1430
1431         By default the numbers are used for labeling rows and Latin letters for
1432         labeling columns. If the table has more than 26 columns, the pairs of
1433         letters are used starting from the 27-th one and so on, i.e. the
1434         sequence of labels is A, B, ..., Z, AA, AB, ..., AZ, BA, ..., ..., ZZ,
1435         AAA, ...
1436      */
1437     //@{
1438
1439     /**
1440         Return the label of the specified row.
1441      */
1442     virtual wxString GetRowLabelValue(int row);
1443
1444     /**
1445         Return the label of the specified column.
1446      */
1447     virtual wxString GetColLabelValue(int col);
1448
1449     /**
1450         Set the given label for the specified row.
1451
1452         The default version does nothing, i.e. the label is not stored. You
1453         must override this method in your derived class if you wish
1454         wxGrid::SetRowLabelValue() to work.
1455      */
1456     virtual void SetRowLabelValue(int row, const wxString& label);
1457
1458     /**
1459         Exactly the same as SetRowLabelValue() but for columns.
1460      */
1461     virtual void SetColLabelValue(int col, const wxString& label);
1462
1463     //@}
1464
1465
1466     /**
1467         @name Attributes Management
1468
1469         By default the attributes management is delegated to
1470         wxGridCellAttrProvider class. You may override the methods in this
1471         section to handle the attributes directly if, for example, they can be
1472         computed from the cell values.
1473      */
1474     //@{
1475
1476     /**
1477         Associate this attributes provider with the table.
1478
1479         The table takes ownership of @a attrProvider pointer and will delete it
1480         when it doesn't need it any more. The pointer can be @NULL, however
1481         this won't disable attributes management in the table but will just
1482         result in a default attributes being recreated the next time any of the
1483         other functions in this section is called. To completely disable the
1484         attributes support, should this be needed, you need to override
1485         CanHaveAttributes() to return @false.
1486      */
1487     void SetAttrProvider(wxGridCellAttrProvider *attrProvider);
1488
1489     /**
1490         Returns the attribute provider currently being used.
1491
1492         This function may return @NULL if the attribute provider hasn't been
1493         neither associated with this table by SetAttrProvider() nor created on
1494         demand by any other methods.
1495      */
1496     wxGridCellAttrProvider *GetAttrProvider() const;
1497
1498     /**
1499         Return the attribute for the given cell.
1500
1501         By default this function is simply forwarded to
1502         wxGridCellAttrProvider::GetAttr() but it may be overridden to handle
1503         attributes directly in the table.
1504      */
1505     virtual wxGridCellAttr *GetAttr(int row, int col,
1506                                     wxGridCellAttr::wxAttrKind kind);
1507
1508     /**
1509         Set attribute of the specified cell.
1510
1511         By default this function is simply forwarded to
1512         wxGridCellAttrProvider::SetAttr().
1513
1514         The table takes ownership of @a attr, i.e. will call DecRef() on it.
1515      */
1516     virtual void SetAttr(wxGridCellAttr* attr, int row, int col);
1517
1518     /**
1519         Set attribute of the specified row.
1520
1521         By default this function is simply forwarded to
1522         wxGridCellAttrProvider::SetRowAttr().
1523
1524         The table takes ownership of @a attr, i.e. will call DecRef() on it.
1525      */
1526     virtual void SetRowAttr(wxGridCellAttr *attr, int row);
1527
1528     /**
1529         Set attribute of the specified column.
1530
1531         By default this function is simply forwarded to
1532         wxGridCellAttrProvider::SetColAttr().
1533
1534         The table takes ownership of @a attr, i.e. will call DecRef() on it.
1535      */
1536     virtual void SetColAttr(wxGridCellAttr *attr, int col);
1537
1538     //@}
1539
1540     /**
1541         Returns true if this table supports attributes or false otherwise.
1542
1543         By default, the table automatically creates a wxGridCellAttrProvider
1544         when this function is called if it had no attribute provider before and
1545         returns @true.
1546      */
1547     virtual bool CanHaveAttributes();
1548 };
1549
1550 /**
1551     @class wxGridSizesInfo
1552
1553     wxGridSizesInfo stores information about sizes of all wxGrid rows or
1554     columns.
1555
1556     It assumes that most of the rows or columns (which are both called elements
1557     here as the difference between them doesn't matter at this class level)
1558     have the default size and so stores it separately. And it uses a wxHashMap
1559     to store the sizes of all elements which have the non-default size.
1560
1561     This structure is particularly useful for serializing the sizes of all
1562     wxGrid elements at once.
1563
1564     @library{wxadv}
1565     @category{grid}
1566  */
1567 struct wxGridSizesInfo
1568 {
1569     /**
1570         Default constructor.
1571
1572         m_sizeDefault and m_customSizes must be initialized later.
1573      */
1574     wxGridSizesInfo();
1575
1576     /**
1577         Constructor.
1578
1579         This constructor is used by wxGrid::GetRowSizes() and GetColSizes()
1580         methods. User code will usually use the default constructor instead.
1581
1582         @param defSize
1583             The default element size.
1584         @param allSizes
1585             Array containing the sizes of @em all elements, including those
1586             which have the default size.
1587      */
1588     wxGridSizesInfo(int defSize, const wxArrayInt& allSizes);
1589
1590     /**
1591         Get the element size.
1592
1593         @param pos
1594             The index of the element.
1595         @return
1596             The size for this element, using m_customSizes if @a pos is in it
1597             or m_sizeDefault otherwise.
1598      */
1599     int GetSize(unsigned pos) const;
1600
1601
1602     /// Default size
1603     int m_sizeDefault;
1604
1605     /**
1606         Map with element indices as keys and their sizes as values.
1607
1608         This map only contains the elements with non-default size.
1609      */
1610     wxUnsignedToIntHashMap m_customSizes;
1611 };
1612
1613
1614 /**
1615     @class wxGrid
1616
1617     wxGrid and its related classes are used for displaying and editing tabular
1618     data. They provide a rich set of features for display, editing, and
1619     interacting with a variety of data sources. For simple applications, and to
1620     help you get started, wxGrid is the only class you need to refer to
1621     directly. It will set up default instances of the other classes and manage
1622     them for you. For more complex applications you can derive your own classes
1623     for custom grid views, grid data tables, cell editors and renderers. The
1624     @ref overview_grid has examples of simple and more complex applications,
1625     explains the relationship between the various grid classes and has a
1626     summary of the keyboard shortcuts and mouse functions provided by wxGrid.
1627
1628     A wxGridTableBase class holds the actual data to be displayed by a wxGrid
1629     class. One or more wxGrid classes may act as a view for one table class.
1630     The default table class is called wxGridStringTable and holds an array of
1631     strings. An instance of such a class is created by CreateGrid().
1632
1633     wxGridCellRenderer is the abstract base class for rendereing contents in a
1634     cell. The following renderers are predefined:
1635
1636     - wxGridCellBoolRenderer
1637     - wxGridCellFloatRenderer
1638     - wxGridCellNumberRenderer
1639     - wxGridCellStringRenderer
1640
1641     The look of a cell can be further defined using wxGridCellAttr. An object
1642     of this type may be returned by wxGridTableBase::GetAttr().
1643
1644     wxGridCellEditor is the abstract base class for editing the value of a
1645     cell. The following editors are predefined:
1646
1647     - wxGridCellBoolEditor
1648     - wxGridCellChoiceEditor
1649     - wxGridCellFloatEditor
1650     - wxGridCellNumberEditor
1651     - wxGridCellTextEditor
1652
1653     Please see wxGridEvent, wxGridSizeEvent, wxGridRangeSelectEvent, and
1654     wxGridEditorCreatedEvent for the documentation of all event types you can
1655     use with wxGrid.
1656
1657     @library{wxadv}
1658     @category{grid}
1659
1660     @see @ref overview_grid, wxGridUpdateLocker
1661 */
1662 class wxGrid : public wxScrolledWindow
1663 {
1664 public:
1665
1666     /**
1667         Different selection modes supported by the grid.
1668      */
1669     enum wxGridSelectionModes
1670     {
1671         /**
1672             The default selection mode allowing selection of the individual
1673             cells as well as of the entire rows and columns.
1674          */
1675         wxGridSelectCells,
1676
1677         /**
1678             The selection mode allowing the selection of the entire rows only.
1679
1680             The user won't be able to select any cells or columns in this mode.
1681          */
1682         wxGridSelectRows,
1683
1684         /**
1685             The selection mode allowing the selection of the entire columns only.
1686
1687             The user won't be able to select any cells or rows in this mode.
1688          */
1689         wxGridSelectColumns
1690     };
1691
1692     /**
1693         Return values for GetCellSize().
1694
1695         @since 2.9.1
1696      */
1697     enum CellSpan
1698     {
1699         /// This cell is inside a span covered by another cell.
1700         CellSpan_Inside = -1,
1701
1702         /// This is a normal, non-spanning cell.
1703         CellSpan_None = 0,
1704
1705         /// This cell spans several physical wxGrid cells.
1706         CellSpan_Main
1707     };
1708
1709     /**
1710         @name Constructors and Initialization
1711      */
1712     //@{
1713
1714     /**
1715         Default constructor.
1716
1717         You must call Create() to really create the grid window and also call
1718         CreateGrid() or SetTable() to initialize the grid contents.
1719      */
1720     wxGrid();
1721     /**
1722         Constructor creating the grid window.
1723
1724         You must call either CreateGrid() or SetTable() to initialize the grid
1725         contents before using it.
1726     */
1727     wxGrid(wxWindow* parent, wxWindowID id,
1728            const wxPoint& pos = wxDefaultPosition,
1729            const wxSize& size = wxDefaultSize,
1730            long style = wxWANTS_CHARS,
1731            const wxString& name = wxGridNameStr);
1732
1733     /**
1734         Destructor.
1735
1736         This will also destroy the associated grid table unless you passed a
1737         table object to the grid and specified that the grid should not take
1738         ownership of the table (see SetTable()).
1739     */
1740     virtual ~wxGrid();
1741
1742     /**
1743         Creates the grid window for an object initialized using the default
1744         constructor.
1745
1746         You must call either CreateGrid() or SetTable() to initialize the grid
1747         contents before using it.
1748      */
1749     bool Create(wxWindow* parent, wxWindowID id,
1750                 const wxPoint& pos = wxDefaultPosition,
1751                 const wxSize& size = wxDefaultSize,
1752                 long style = wxWANTS_CHARS,
1753                 const wxString& name = wxGridNameStr);
1754
1755     /**
1756         Creates a grid with the specified initial number of rows and columns.
1757
1758         Call this directly after the grid constructor. When you use this
1759         function wxGrid will create and manage a simple table of string values
1760         for you. All of the grid data will be stored in memory.
1761
1762         For applications with more complex data types or relationships, or for
1763         dealing with very large datasets, you should derive your own grid table
1764         class and pass a table object to the grid with SetTable().
1765     */
1766     bool CreateGrid(int numRows, int numCols,
1767                     wxGridSelectionModes selmode = wxGridSelectCells);
1768
1769     /**
1770         Passes a pointer to a custom grid table to be used by the grid.
1771
1772         This should be called after the grid constructor and before using the
1773         grid object. If @a takeOwnership is set to @true then the table will be
1774         deleted by the wxGrid destructor.
1775
1776         Use this function instead of CreateGrid() when your application
1777         involves complex or non-string data or data sets that are too large to
1778         fit wholly in memory.
1779     */
1780     bool SetTable(wxGridTableBase* table, bool takeOwnership = false,
1781                   wxGridSelectionModes selmode = wxGridSelectCells);
1782
1783     //@}
1784
1785
1786     /**
1787         @name Grid Line Formatting
1788      */
1789     //@{
1790
1791     /**
1792         Turns the drawing of grid lines on or off.
1793     */
1794     void EnableGridLines(bool enable = true);
1795
1796     /**
1797         Returns the pen used for vertical grid lines.
1798
1799         This virtual function may be overridden in derived classes in order to
1800         change the appearance of individual grid lines for the given column
1801         @a col.
1802
1803         See GetRowGridLinePen() for an example.
1804     */
1805     virtual wxPen GetColGridLinePen(int col);
1806
1807     /**
1808         Returns the pen used for grid lines.
1809
1810         This virtual function may be overridden in derived classes in order to
1811         change the appearance of grid lines. Note that currently the pen width
1812         must be 1.
1813
1814         @see GetColGridLinePen(), GetRowGridLinePen()
1815     */
1816     virtual wxPen GetDefaultGridLinePen();
1817
1818     /**
1819         Returns the colour used for grid lines.
1820
1821         @see GetDefaultGridLinePen()
1822     */
1823     wxColour GetGridLineColour() const;
1824
1825     /**
1826         Returns the pen used for horizontal grid lines.
1827
1828         This virtual function may be overridden in derived classes in order to
1829         change the appearance of individual grid line for the given @a row.
1830
1831         Example:
1832         @code
1833         // in a grid displaying music notation, use a solid black pen between
1834         // octaves (C0=row 127, C1=row 115 etc.)
1835         wxPen MidiGrid::GetRowGridLinePen(int row)
1836         {
1837             if ( row % 12 == 7 )
1838                 return wxPen(*wxBLACK, 1, wxSOLID);
1839             else
1840                 return GetDefaultGridLinePen();
1841         }
1842         @endcode
1843     */
1844     virtual wxPen GetRowGridLinePen(int row);
1845
1846     /**
1847         Returns @true if drawing of grid lines is turned on, @false otherwise.
1848     */
1849     bool GridLinesEnabled() const;
1850
1851     /**
1852         Sets the colour used to draw grid lines.
1853     */
1854     void SetGridLineColour(const wxColour& colour);
1855
1856     //@}
1857
1858
1859     /**
1860         @name Label Values and Formatting
1861      */
1862     //@{
1863
1864     /**
1865         Sets the arguments to the current column label alignment values.
1866
1867         Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
1868         or @c wxALIGN_RIGHT.
1869
1870         Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
1871         @c wxALIGN_BOTTOM.
1872     */
1873     void GetColLabelAlignment(int* horiz, int* vert) const;
1874
1875     /**
1876         Returns the orientation of the column labels (either @c wxHORIZONTAL or
1877         @c wxVERTICAL).
1878     */
1879     int GetColLabelTextOrientation() const;
1880
1881     /**
1882         Returns the specified column label.
1883
1884         The default grid table class provides column labels of the form
1885         A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can
1886         override wxGridTableBase::GetColLabelValue() to provide your own
1887         labels.
1888     */
1889     wxString GetColLabelValue(int col) const;
1890
1891     /**
1892         Returns the colour used for the background of row and column labels.
1893     */
1894     wxColour GetLabelBackgroundColour() const;
1895
1896     /**
1897         Returns the font used for row and column labels.
1898     */
1899     wxFont GetLabelFont() const;
1900
1901     /**
1902         Returns the colour used for row and column label text.
1903     */
1904     wxColour GetLabelTextColour() const;
1905
1906     /**
1907         Returns the alignment used for row labels.
1908
1909         Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
1910         or @c wxALIGN_RIGHT.
1911
1912         Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
1913         @c wxALIGN_BOTTOM.
1914     */
1915     void GetRowLabelAlignment(int* horiz, int* vert) const;
1916
1917     /**
1918         Returns the specified row label.
1919
1920         The default grid table class provides numeric row labels. If you are
1921         using a custom grid table you can override
1922         wxGridTableBase::GetRowLabelValue() to provide your own labels.
1923     */
1924     wxString GetRowLabelValue(int row) const;
1925
1926     /**
1927         Hides the column labels by calling SetColLabelSize() with a size of 0.
1928         Show labels again by calling that method with a width greater than 0.
1929     */
1930     void HideColLabels();
1931
1932     /**
1933         Hides the row labels by calling SetRowLabelSize() with a size of 0.
1934
1935         The labels can be shown again by calling SetRowLabelSize() with a width
1936         greater than 0.
1937     */
1938     void HideRowLabels();
1939
1940     /**
1941         Sets the horizontal and vertical alignment of column label text.
1942
1943         Horizontal alignment should be one of @c wxALIGN_LEFT,
1944         @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
1945         of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
1946     */
1947     void SetColLabelAlignment(int horiz, int vert);
1948
1949     /**
1950         Sets the orientation of the column labels (either @c wxHORIZONTAL or
1951         @c wxVERTICAL).
1952     */
1953     void SetColLabelTextOrientation(int textOrientation);
1954
1955     /**
1956         Set the value for the given column label.
1957
1958         If you are using a custom grid table you must override
1959         wxGridTableBase::SetColLabelValue() for this to have any effect.
1960     */
1961     void SetColLabelValue(int col, const wxString& value);
1962
1963     /**
1964         Sets the background colour for row and column labels.
1965     */
1966     void SetLabelBackgroundColour(const wxColour& colour);
1967
1968     /**
1969         Sets the font for row and column labels.
1970     */
1971     void SetLabelFont(const wxFont& font);
1972
1973     /**
1974         Sets the colour for row and column label text.
1975     */
1976     void SetLabelTextColour(const wxColour& colour);
1977
1978     /**
1979         Sets the horizontal and vertical alignment of row label text.
1980
1981         Horizontal alignment should be one of @c wxALIGN_LEFT,
1982         @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
1983         of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
1984     */
1985     void SetRowLabelAlignment(int horiz, int vert);
1986
1987     /**
1988         Sets the value for the given row label.
1989
1990         If you are using a derived grid table you must override
1991         wxGridTableBase::SetRowLabelValue() for this to have any effect.
1992     */
1993     void SetRowLabelValue(int row, const wxString& value);
1994
1995     /**
1996         Call this in order to make the column labels use a native look by using
1997         wxRendererNative::DrawHeaderButton() internally.
1998
1999         There is no equivalent method for drawing row columns as there is not
2000         native look for that. This option is useful when using wxGrid for
2001         displaying tables and not as a spread-sheet.
2002
2003         @see UseNativeColHeader()
2004     */
2005     void SetUseNativeColLabels(bool native = true);
2006
2007     /**
2008         Enable the use of native header window for column labels.
2009
2010         If this function is called with @true argument, a wxHeaderCtrl is used
2011         instead to display the column labels instead of drawing them in wxGrid
2012         code itself. This has the advantage of making the grid look and feel
2013         perfectly the same as native applications (using SetUseNativeColLabels()
2014         the grid can be made to look more natively but it still doesn't feel
2015         natively, notably the column resizing and dragging still works slightly
2016         differently as it is implemented in wxWidgets itself) but results in
2017         different behaviour for column and row headers, for which there is no
2018         equivalent function, and, most importantly, is unsuitable for grids
2019         with huge numbers of columns as wxHeaderCtrl doesn't support virtual
2020         mode. Because of this, by default the grid does not use the native
2021         header control but you should call this function to enable it if you
2022         are using the grid to display tabular data and don't have thousands of
2023         columns in it.
2024
2025         Another difference between the default behaviour and the native header
2026         behaviour is that the latter provides the user with a context menu
2027         (which appears on right clicking the header) allowing to rearrange the
2028         grid columns if CanDragColMove() returns @true. If you want to prevent
2029         this from happening for some reason, you need to define a handler for
2030         @c wxEVT_GRID_LABEL_RIGHT_CLICK event which simply does nothing (in
2031         particular doesn't skip the event) as this will prevent the default
2032         right click handling from working.
2033
2034         Also note that currently @c wxEVT_GRID_LABEL_RIGHT_DCLICK event is not
2035         generated for the column labels if the native columns header is used
2036         (but this limitation could possibly be lifted in the future).
2037      */
2038     void UseNativeColHeader(bool native = true);
2039
2040     //@}
2041
2042
2043     /**
2044         @name Cell Formatting
2045
2046         Note that wxGridCellAttr can be used alternatively to most of these
2047         methods. See the "Attributes Management" of wxGridTableBase.
2048      */
2049     //@{
2050
2051     /**
2052         Sets the arguments to the horizontal and vertical text alignment values
2053         for the grid cell at the specified location.
2054
2055         Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2056         or @c wxALIGN_RIGHT.
2057
2058         Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2059         @c wxALIGN_BOTTOM.
2060     */
2061     void GetCellAlignment(int row, int col, int* horiz, int* vert) const;
2062
2063     /**
2064         Returns the background colour of the cell at the specified location.
2065     */
2066     wxColour GetCellBackgroundColour(int row, int col) const;
2067
2068     /**
2069         Returns the font for text in the grid cell at the specified location.
2070     */
2071     wxFont GetCellFont(int row, int col) const;
2072
2073     /**
2074         Returns the text colour for the grid cell at the specified location.
2075     */
2076     wxColour GetCellTextColour(int row, int col) const;
2077
2078     /**
2079         Returns the default cell alignment.
2080
2081         Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2082         or @c wxALIGN_RIGHT.
2083
2084         Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2085         @c wxALIGN_BOTTOM.
2086
2087         @see SetDefaultCellAlignment()
2088     */
2089     void GetDefaultCellAlignment(int* horiz, int* vert) const;
2090
2091     /**
2092         Returns the current default background colour for grid cells.
2093     */
2094     wxColour GetDefaultCellBackgroundColour() const;
2095
2096     /**
2097         Returns the current default font for grid cell text.
2098     */
2099     wxFont GetDefaultCellFont() const;
2100
2101     /**
2102         Returns the current default colour for grid cell text.
2103     */
2104     wxColour GetDefaultCellTextColour() const;
2105
2106     /**
2107         Sets the horizontal and vertical alignment for grid cell text at the
2108         specified location.
2109
2110         Horizontal alignment should be one of @c wxALIGN_LEFT,
2111         @c wxALIGN_CENTRE or @c wxALIGN_RIGHT.
2112
2113         Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
2114         or @c wxALIGN_BOTTOM.
2115     */
2116     void SetCellAlignment(int row, int col, int horiz, int vert);
2117     /**
2118         Sets the horizontal and vertical alignment for grid cell text at the
2119         specified location.
2120
2121         Horizontal alignment should be one of @c wxALIGN_LEFT,
2122         @c wxALIGN_CENTRE or @c wxALIGN_RIGHT.
2123
2124         Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
2125         or @c wxALIGN_BOTTOM.
2126     */
2127     void SetCellAlignment(int align, int row, int col);
2128
2129     /**
2130         Set the background colour for the given cell or all cells by default.
2131     */
2132     void SetCellBackgroundColour(int row, int col, const wxColour& colour);
2133
2134     /**
2135         Sets the font for text in the grid cell at the specified location.
2136     */
2137     void SetCellFont(int row, int col, const wxFont& font);
2138
2139     /**
2140         Sets the text colour for the given cell.
2141     */
2142     void SetCellTextColour(int row, int col, const wxColour& colour);
2143     /**
2144         Sets the text colour for the given cell.
2145     */
2146     void SetCellTextColour(const wxColour& val, int row, int col);
2147     /**
2148         Sets the text colour for all cells by default.
2149     */
2150     void SetCellTextColour(const wxColour& colour);
2151
2152     /**
2153         Sets the default horizontal and vertical alignment for grid cell text.
2154
2155         Horizontal alignment should be one of @c wxALIGN_LEFT,
2156         @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
2157         of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
2158     */
2159     void SetDefaultCellAlignment(int horiz, int vert);
2160
2161     /**
2162         Sets the default background colour for grid cells.
2163     */
2164     void SetDefaultCellBackgroundColour(const wxColour& colour);
2165
2166     /**
2167         Sets the default font to be used for grid cell text.
2168     */
2169     void SetDefaultCellFont(const wxFont& font);
2170
2171     /**
2172         Sets the current default colour for grid cell text.
2173     */
2174     void SetDefaultCellTextColour(const wxColour& colour);
2175
2176     //@}
2177
2178
2179     /**
2180         @name Cell Values, Editors, and Renderers
2181
2182         Note that wxGridCellAttr can be used alternatively to most of these
2183         methods. See the "Attributes Management" of wxGridTableBase.
2184      */
2185     //@{
2186
2187     /**
2188         Returns @true if the in-place edit control for the current grid cell
2189         can be used and @false otherwise.
2190
2191         This function always returns @false for the read-only cells.
2192     */
2193     bool CanEnableCellControl() const;
2194
2195     /**
2196         Disables in-place editing of grid cells.
2197
2198         Equivalent to calling EnableCellEditControl(@false).
2199     */
2200     void DisableCellEditControl();
2201
2202     /**
2203         Enables or disables in-place editing of grid cell data.
2204
2205         The grid will issue either a @c wxEVT_GRID_EDITOR_SHOWN or
2206         @c wxEVT_GRID_EDITOR_HIDDEN event.
2207     */
2208     void EnableCellEditControl(bool enable = true);
2209
2210     /**
2211         Makes the grid globally editable or read-only.
2212
2213         If the edit argument is @false this function sets the whole grid as
2214         read-only. If the argument is @true the grid is set to the default
2215         state where cells may be editable. In the default state you can set
2216         single grid cells and whole rows and columns to be editable or
2217         read-only via wxGridCellAttr::SetReadOnly(). For single cells you
2218         can also use the shortcut function SetReadOnly().
2219
2220         For more information about controlling grid cell attributes see the
2221         wxGridCellAttr class and the @ref overview_grid.
2222     */
2223     void EnableEditing(bool edit);
2224
2225     /**
2226         Returns a pointer to the editor for the cell at the specified location.
2227
2228         See wxGridCellEditor and the @ref overview_grid for more information
2229         about cell editors and renderers.
2230
2231         The caller must call DecRef() on the returned pointer.
2232     */
2233     wxGridCellEditor* GetCellEditor(int row, int col) const;
2234
2235     /**
2236         Returns a pointer to the renderer for the grid cell at the specified
2237         location.
2238
2239         See wxGridCellRenderer and the @ref overview_grid for more information
2240         about cell editors and renderers.
2241
2242         The caller must call DecRef() on the returned pointer.
2243     */
2244     wxGridCellRenderer* GetCellRenderer(int row, int col) const;
2245
2246     /**
2247         Returns the string contained in the cell at the specified location.
2248
2249         For simple applications where a grid object automatically uses a
2250         default grid table of string values you use this function together with
2251         SetCellValue() to access cell values. For more complex applications
2252         where you have derived your own grid table class that contains various
2253         data types (e.g. numeric, boolean or user-defined custom types) then
2254         you only use this function for those cells that contain string values.
2255
2256         See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
2257         more information.
2258     */
2259     wxString GetCellValue(int row, int col) const;
2260     /**
2261         Returns the string contained in the cell at the specified location.
2262
2263         For simple applications where a grid object automatically uses a
2264         default grid table of string values you use this function together with
2265         SetCellValue() to access cell values. For more complex applications
2266         where you have derived your own grid table class that contains various
2267         data types (e.g. numeric, boolean or user-defined custom types) then
2268         you only use this function for those cells that contain string values.
2269
2270         See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
2271         more information.
2272     */
2273     wxString GetCellValue(const wxGridCellCoords& coords) const;
2274
2275     /**
2276         Returns a pointer to the current default grid cell editor.
2277
2278         See wxGridCellEditor and the @ref overview_grid for more information
2279         about cell editors and renderers.
2280     */
2281     wxGridCellEditor* GetDefaultEditor() const;
2282
2283     /**
2284         Returns the default editor for the specified cell.
2285
2286         The base class version returns the editor appropriate for the current
2287         cell type but this method may be overridden in the derived classes to
2288         use custom editors for some cells by default.
2289
2290         Notice that the same may be achieved in a usually simpler way by
2291         associating a custom editor with the given cell or cells.
2292
2293         The caller must call DecRef() on the returned pointer.
2294     */
2295     virtual wxGridCellEditor* GetDefaultEditorForCell(int row, int col) const;
2296     /**
2297         Returns the default editor for the specified cell.
2298
2299         The base class version returns the editor appropriate for the current
2300         cell type but this method may be overridden in the derived classes to
2301         use custom editors for some cells by default.
2302
2303         Notice that the same may be achieved in a usually simpler way by
2304         associating a custom editor with the given cell or cells.
2305
2306         The caller must call DecRef() on the returned pointer.
2307     */
2308     wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c) const;
2309
2310     /**
2311         Returns the default editor for the cells containing values of the given
2312         type.
2313
2314         The base class version returns the editor which was associated with the
2315         specified @a typeName when it was registered RegisterDataType() but
2316         this function may be overridden to return something different. This
2317         allows to override an editor used for one of the standard types.
2318
2319         The caller must call DecRef() on the returned pointer.
2320     */
2321     virtual wxGridCellEditor* GetDefaultEditorForType(const wxString& typeName) const;
2322
2323     /**
2324         Returns a pointer to the current default grid cell renderer.
2325
2326         See wxGridCellRenderer and the @ref overview_grid for more information
2327         about cell editors and renderers.
2328
2329         The caller must call DecRef() on the returned pointer.
2330     */
2331     wxGridCellRenderer* GetDefaultRenderer() const;
2332
2333     /**
2334         Returns the default renderer for the given cell.
2335
2336         The base class version returns the renderer appropriate for the current
2337         cell type but this method may be overridden in the derived classes to
2338         use custom renderers for some cells by default.
2339
2340         The caller must call DecRef() on the returned pointer.
2341     */
2342     virtual wxGridCellRenderer* GetDefaultRendererForCell(int row, int col) const;
2343
2344     /**
2345         Returns the default renderer for the cell containing values of the
2346         given type.
2347
2348         @see GetDefaultEditorForType()
2349     */
2350     virtual wxGridCellRenderer* GetDefaultRendererForType(const wxString& typeName) const;
2351
2352     /**
2353         Hides the in-place cell edit control.
2354     */
2355     void HideCellEditControl();
2356
2357     /**
2358         Returns @true if the in-place edit control is currently enabled.
2359     */
2360     bool IsCellEditControlEnabled() const;
2361
2362     /**
2363         Returns @true if the current cell is read-only.
2364
2365         @see SetReadOnly(), IsReadOnly()
2366     */
2367     bool IsCurrentCellReadOnly() const;
2368
2369     /**
2370         Returns @false if the whole grid has been set as read-only or @true
2371         otherwise.
2372
2373         See EnableEditing() for more information about controlling the editing
2374         status of grid cells.
2375     */
2376     bool IsEditable() const;
2377
2378     /**
2379         Returns @true if the cell at the specified location can't be edited.
2380
2381         @see SetReadOnly(), IsCurrentCellReadOnly()
2382     */
2383     bool IsReadOnly(int row, int col) const;
2384
2385     /**
2386         Register a new data type.
2387
2388         The data types allow to naturally associate specific renderers and
2389         editors to the cells containing values of the given type. For example,
2390         the grid automatically registers a data type with the name
2391         @c wxGRID_VALUE_STRING which uses wxGridCellStringRenderer and
2392         wxGridCellTextEditor as its renderer and editor respectively -- this is
2393         the data type used by all the cells of the default wxGridStringTable,
2394         so this renderer and editor are used by default for all grid cells.
2395
2396         However if a custom table returns @c wxGRID_VALUE_BOOL from its
2397         wxGridTableBase::GetTypeName() method, then wxGridCellBoolRenderer and
2398         wxGridCellBoolEditor are used for it because the grid also registers a
2399         boolean data type with this name.
2400
2401         And as this mechanism is completely generic, you may register your own
2402         data types using your own custom renderers and editors. Just remember
2403         that the table must identify a cell as being of the given type for them
2404         to be used for this cell.
2405
2406         @param typeName
2407             Name of the new type. May be any string, but if the type name is
2408             the same as the name of an already registered type, including one
2409             of the standard ones (which are @c wxGRID_VALUE_STRING, @c
2410             wxGRID_VALUE_BOOL, @c wxGRID_VALUE_NUMBER, @c wxGRID_VALUE_FLOAT
2411             and @c wxGRID_VALUE_CHOICE), then the new registration information
2412             replaces the previously used renderer and editor.
2413         @param renderer
2414             The renderer to use for the cells of this type. Its ownership is
2415             taken by the grid, i.e. it will call DecRef() on this pointer when
2416             it doesn't need it any longer.
2417         @param editor
2418             The editor to use for the cells of this type. Its ownership is also
2419             taken by the grid.
2420     */
2421     void RegisterDataType(const wxString& typeName,
2422                           wxGridCellRenderer* renderer,
2423                           wxGridCellEditor* editor);
2424
2425     /**
2426         Sets the value of the current grid cell to the current in-place edit
2427         control value.
2428
2429         This is called automatically when the grid cursor moves from the
2430         current cell to a new cell. It is also a good idea to call this
2431         function when closing a grid since any edits to the final cell location
2432         will not be saved otherwise.
2433     */
2434     void SaveEditControlValue();
2435
2436     /**
2437         Sets the editor for the grid cell at the specified location.
2438
2439         The grid will take ownership of the pointer.
2440
2441         See wxGridCellEditor and the @ref overview_grid for more information
2442         about cell editors and renderers.
2443     */
2444     void SetCellEditor(int row, int col, wxGridCellEditor* editor);
2445
2446     /**
2447         Sets the renderer for the grid cell at the specified location.
2448
2449         The grid will take ownership of the pointer.
2450
2451         See wxGridCellRenderer and the @ref overview_grid for more information
2452         about cell editors and renderers.
2453     */
2454     void SetCellRenderer(int row, int col, wxGridCellRenderer* renderer);
2455
2456     /**
2457         Sets the string value for the cell at the specified location.
2458
2459         For simple applications where a grid object automatically uses a
2460         default grid table of string values you use this function together with
2461         GetCellValue() to access cell values. For more complex applications
2462         where you have derived your own grid table class that contains various
2463         data types (e.g. numeric, boolean or user-defined custom types) then
2464         you only use this function for those cells that contain string values.
2465
2466         See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2467         more information.
2468     */
2469     void SetCellValue(int row, int col, const wxString& s);
2470     /**
2471         Sets the string value for the cell at the specified location.
2472
2473         For simple applications where a grid object automatically uses a
2474         default grid table of string values you use this function together with
2475         GetCellValue() to access cell values. For more complex applications
2476         where you have derived your own grid table class that contains various
2477         data types (e.g. numeric, boolean or user-defined custom types) then
2478         you only use this function for those cells that contain string values.
2479
2480         See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2481         more information.
2482     */
2483     void SetCellValue(const wxGridCellCoords& coords, const wxString& s);
2484     /**
2485         @deprecated Please use SetCellValue(int,int,const wxString&) or
2486                     SetCellValue(const wxGridCellCoords&,const wxString&)
2487                     instead.
2488
2489         Sets the string value for the cell at the specified location.
2490
2491         For simple applications where a grid object automatically uses a
2492         default grid table of string values you use this function together with
2493         GetCellValue() to access cell values. For more complex applications
2494         where you have derived your own grid table class that contains various
2495         data types (e.g. numeric, boolean or user-defined custom types) then
2496         you only use this function for those cells that contain string values.
2497
2498         See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2499         more information.
2500     */
2501     void SetCellValue(const wxString& val, int row, int col);
2502
2503     /**
2504         Sets the specified column to display boolean values.
2505
2506         @see SetColFormatCustom()
2507     */
2508     void SetColFormatBool(int col);
2509
2510     /**
2511         Sets the specified column to display data in a custom format.
2512
2513         This method provides an alternative to defining a custom grid table
2514         which would return @a typeName from its GetTypeName() method for the
2515         cells in this column: while it doesn't really change the type of the
2516         cells in this column, it does associate the renderer and editor used
2517         for the cells of the specified type with them.
2518
2519         See the @ref overview_grid for more information on working with custom
2520         data types.
2521     */
2522     void SetColFormatCustom(int col, const wxString& typeName);
2523
2524     /**
2525         Sets the specified column to display floating point values with the
2526         given width and precision.
2527
2528         @see SetColFormatCustom()
2529     */
2530     void SetColFormatFloat(int col, int width = -1, int precision = -1);
2531
2532     /**
2533         Sets the specified column to display integer values.
2534
2535         @see SetColFormatCustom()
2536     */
2537     void SetColFormatNumber(int col);
2538
2539     /**
2540         Sets the default editor for grid cells.
2541
2542         The grid will take ownership of the pointer.
2543
2544         See wxGridCellEditor and the @ref overview_grid for more information
2545         about cell editors and renderers.
2546     */
2547     void SetDefaultEditor(wxGridCellEditor* editor);
2548
2549     /**
2550         Sets the default renderer for grid cells.
2551
2552         The grid will take ownership of the pointer.
2553
2554         See wxGridCellRenderer and the @ref overview_grid for more information
2555         about cell editors and renderers.
2556     */
2557     void SetDefaultRenderer(wxGridCellRenderer* renderer);
2558
2559     /**
2560         Makes the cell at the specified location read-only or editable.
2561
2562         @see IsReadOnly()
2563     */
2564     void SetReadOnly(int row, int col, bool isReadOnly = true);
2565
2566     /**
2567         Displays the in-place cell edit control for the current cell.
2568     */
2569     void ShowCellEditControl();
2570
2571     //@}
2572
2573
2574     /**
2575         @name Column and Row Sizes
2576
2577         @see @ref overview_grid_resizing
2578      */
2579     //@{
2580
2581     /**
2582         Automatically sets the height and width of all rows and columns to fit
2583         their contents.
2584     */
2585     void AutoSize();
2586
2587     /**
2588         Automatically adjusts width of the column to fit its label.
2589     */
2590     void AutoSizeColLabelSize(int col);
2591
2592     /**
2593         Automatically sizes the column to fit its contents. If @a setAsMin is
2594         @true the calculated width will also be set as the minimal width for
2595         the column.
2596     */
2597     void AutoSizeColumn(int col, bool setAsMin = true);
2598
2599     /**
2600         Automatically sizes all columns to fit their contents. If @a setAsMin
2601         is @true the calculated widths will also be set as the minimal widths
2602         for the columns.
2603     */
2604     void AutoSizeColumns(bool setAsMin = true);
2605
2606     /**
2607         Automatically sizes the row to fit its contents. If @a setAsMin is
2608         @true the calculated height will also be set as the minimal height for
2609         the row.
2610     */
2611     void AutoSizeRow(int row, bool setAsMin = true);
2612
2613     /**
2614         Automatically adjusts height of the row to fit its label.
2615     */
2616     void AutoSizeRowLabelSize(int col);
2617
2618     /**
2619         Automatically sizes all rows to fit their contents. If @a setAsMin is
2620         @true the calculated heights will also be set as the minimal heights
2621         for the rows.
2622     */
2623     void AutoSizeRows(bool setAsMin = true);
2624
2625     /**
2626         Returns the current height of the column labels.
2627     */
2628     int GetColLabelSize() const;
2629
2630     /**
2631         Returns the minimal width to which a column may be resized.
2632
2633         Use SetColMinimalAcceptableWidth() to change this value globally or
2634         SetColMinimalWidth() to do it for individual columns.
2635
2636         @see GetRowMinimalAcceptableHeight()
2637     */
2638     int GetColMinimalAcceptableWidth() const;
2639
2640     /**
2641         Returns the width of the specified column.
2642     */
2643     int GetColSize(int col) const;
2644
2645     /**
2646         Returns @true if the specified column is not currently hidden.
2647      */
2648     bool IsColShown(int col) const;
2649
2650     /**
2651         Returns the default height for column labels.
2652     */
2653     int GetDefaultColLabelSize() const;
2654
2655     /**
2656         Returns the current default width for grid columns.
2657     */
2658     int GetDefaultColSize() const;
2659
2660     /**
2661         Returns the default width for the row labels.
2662     */
2663     int GetDefaultRowLabelSize() const;
2664
2665     /**
2666         Returns the current default height for grid rows.
2667     */
2668     int GetDefaultRowSize() const;
2669
2670     /**
2671         Returns the minimal size to which rows can be resized.
2672
2673         Use SetRowMinimalAcceptableHeight() to change this value globally or
2674         SetRowMinimalHeight() to do it for individual cells.
2675
2676         @see GetColMinimalAcceptableWidth()
2677     */
2678     int GetRowMinimalAcceptableHeight() const;
2679
2680     /**
2681         Returns the current width of the row labels.
2682     */
2683     int GetRowLabelSize() const;
2684
2685     /**
2686         Returns the height of the specified row.
2687     */
2688     int GetRowSize(int row) const;
2689
2690     /**
2691         Returns @true if the specified row is not currently hidden.
2692      */
2693     bool IsRowShown(int row) const;
2694
2695     /**
2696         Sets the height of the column labels.
2697
2698         If @a height equals to @c wxGRID_AUTOSIZE then height is calculated
2699         automatically so that no label is truncated. Note that this could be
2700         slow for a large table.
2701     */
2702     void SetColLabelSize(int height);
2703
2704     /**
2705         Sets the minimal @a width to which the user can resize columns.
2706
2707         @see GetColMinimalAcceptableWidth()
2708     */
2709     void SetColMinimalAcceptableWidth(int width);
2710
2711     /**
2712         Sets the minimal @a width for the specified column @a col.
2713
2714         It is usually best to call this method during grid creation as calling
2715         it later will not resize the column to the given minimal width even if
2716         it is currently narrower than it.
2717
2718         @a width must be greater than the minimal acceptable column width as
2719         returned by GetColMinimalAcceptableWidth().
2720     */
2721     void SetColMinimalWidth(int col, int width);
2722
2723     /**
2724         Sets the width of the specified column.
2725
2726         @param col
2727             The column index.
2728         @param width
2729             The new column width in pixels, 0 to hide the column or -1 to fit
2730             the column width to its label width.
2731     */
2732     void SetColSize(int col, int width);
2733
2734     /**
2735         Hides the specified column.
2736
2737         To show the column later you need to call SetColSize() with non-0
2738         width or ShowCol().
2739
2740         @param col
2741             The column index.
2742      */
2743     void HideCol(int col);
2744
2745     /**
2746         Shows the previously hidden column by resizing it to non-0 size.
2747
2748         @see HideCol(), SetColSize()
2749      */
2750     void ShowCol(int col);
2751
2752
2753     /**
2754         Sets the default width for columns in the grid.
2755
2756         This will only affect columns subsequently added to the grid unless
2757         @a resizeExistingCols is @true.
2758
2759         If @a width is less than GetColMinimalAcceptableWidth(), then the
2760         minimal acceptable width is used instead of it.
2761     */
2762     void SetDefaultColSize(int width, bool resizeExistingCols = false);
2763
2764     /**
2765         Sets the default height for rows in the grid.
2766
2767         This will only affect rows subsequently added to the grid unless
2768         @a resizeExistingRows is @true.
2769
2770         If @a height is less than GetRowMinimalAcceptableHeight(), then the
2771         minimal acceptable heihgt is used instead of it.
2772     */
2773     void SetDefaultRowSize(int height, bool resizeExistingRows = false);
2774
2775     /**
2776         Sets the width of the row labels.
2777
2778         If @a width equals @c wxGRID_AUTOSIZE then width is calculated
2779         automatically so that no label is truncated. Note that this could be
2780         slow for a large table.
2781     */
2782     void SetRowLabelSize(int width);
2783
2784     /**
2785         Sets the minimal row @a height used by default.
2786
2787         See SetColMinimalAcceptableWidth() for more information.
2788     */
2789     void SetRowMinimalAcceptableHeight(int height);
2790
2791     /**
2792         Sets the minimal @a height for the specified @a row.
2793
2794         See SetColMinimalWidth() for more information.
2795     */
2796     void SetRowMinimalHeight(int row, int height);
2797
2798     /**
2799         Sets the height of the specified row.
2800
2801         See SetColSize() for more information.
2802     */
2803     void SetRowSize(int row, int height);
2804
2805     /**
2806         Hides the specified row.
2807
2808         To show the row later you need to call SetRowSize() with non-0
2809         width or ShowRow().
2810
2811         @param col
2812             The row index.
2813      */
2814     void HideRow(int col);
2815
2816     /**
2817         Shows the previously hidden row by resizing it to non-0 size.
2818
2819         @see HideRow(), SetRowSize()
2820      */
2821     void ShowRow(int col);
2822
2823     /**
2824         Get size information for all columns at once.
2825
2826         This method is useful when the information about all column widths
2827         needs to be saved. The widths can be later restored using
2828         SetColSizes().
2829
2830         @sa wxGridSizesInfo, GetRowSizes()
2831      */
2832     wxGridSizesInfo GetColSizes() const;
2833
2834     /**
2835         Get size information for all row at once.
2836
2837         @sa wxGridSizesInfo, GetColSizes()
2838      */
2839     wxGridSizesInfo GetRowSizes() const;
2840
2841     /**
2842         Restore all columns sizes.
2843
2844         This is usually called with wxGridSizesInfo object previously returned
2845         by GetColSizes().
2846
2847         @sa SetRowSizes()
2848      */
2849     void SetColSizes(const wxGridSizesInfo& sizeInfo);
2850
2851     /**
2852         Restore all rows sizes.
2853
2854         @sa SetColSizes()
2855      */
2856     void SetRowSizes(const wxGridSizesInfo& sizeInfo);
2857
2858     /**
2859         Set the size of the cell.
2860
2861         Specifying a value of more than 1 in @a num_rows or @a num_cols will
2862         make the cell at (@a row, @a col) span the block of the specified size,
2863         covering the other cells which would be normally shown in it. Passing 1
2864         for both arguments resets the cell to normal appearance.
2865
2866         @see GetCellSize()
2867
2868         @param row
2869             The row of the cell.
2870         @param col
2871             The column of the cell.
2872         @param num_rows
2873             Number of rows to be occupied by this cell, must be >= 1.
2874         @param num_cols
2875             Number of columns to be occupied by this cell, must be >= 1.
2876      */
2877     void SetCellSize(int row, int col, int num_rows, int num_cols);
2878
2879     /**
2880         Get the size of the cell in number of cells covered by it.
2881
2882         For normal cells, the function fills both @a num_rows and @a num_cols
2883         with 1 and returns CellSpan_None. For cells which span multiple cells, i.e.
2884         for which SetCellSize() had been called, the returned values are the
2885         same ones as were passed to SetCellSize() call and the function return
2886         value is CellSpan_Main.
2887
2888         More unexpectedly, perhaps, the returned values may be @em negative for
2889         the cells which are inside a span covered by a cell occupying multiple
2890         rows or columns. They correspond to the offset of the main cell of the
2891         span from the cell passed to this functions and the function returns
2892         CellSpan_Inside value to indicate this.
2893
2894         As an example, consider a 3*3 grid with the cell (1, 1) (the one in the
2895         middle) having a span of 2 rows and 2 columns, i.e. the grid looks like
2896         @code
2897             +----+----+----+
2898             |    |    |    |
2899             +----+----+----+
2900             |    |         |
2901             +----+         |
2902             |    |         |
2903             +----+----+----+
2904         @endcode
2905         Then the function returns 2 and 2 in @a num_rows and @a num_cols for
2906         the cell (1, 1) itself and -1 and -1 for the cell (2, 2) as well as -1
2907         and 0 for the cell (2, 1).
2908
2909         @param row
2910             The row of the cell.
2911         @param col
2912             The column of the cell.
2913         @param num_rows
2914             Pointer to variable receiving the number of rows, must not be @NULL.
2915         @param num_cols
2916             Pointer to variable receiving the number of columns, must not be
2917             @NULL.
2918         @return
2919             The kind of this cell span (the return value is new in wxWidgets
2920             2.9.1, this function was void in previous wxWidgets versions).
2921      */
2922     CellSpan GetCellSize( int row, int col, int *num_rows, int *num_cols ) const;
2923
2924     /**
2925         Get the number of rows and columns allocated for this cell.
2926
2927         This overload doesn't return a CellSpan value but the values returned
2928         may still be negative, see GetCellSize(int, int, int *, int *) for
2929         details.
2930      */
2931     wxSize GetCellSize(const wxGridCellCoords& coords);
2932
2933     //@}
2934
2935
2936     /**
2937         @name User-Resizing and Dragging
2938
2939         Functions controlling various interactive mouse operations.
2940
2941         By default, columns and rows can be resized by dragging the edges of
2942         their labels (this can be disabled using DisableDragColSize() and
2943         DisableDragRowSize() methods). And if grid line dragging is enabled with
2944         EnableDragGridSize() they can also be resized by dragging the right or
2945         bottom edge of the grid cells.
2946
2947         Columns can also be moved to interactively change their order but this
2948         needs to be explicitly enabled with EnableDragColMove().
2949      */
2950     //@{
2951
2952     /**
2953         Return @true if the dragging of cells is enabled or @false otherwise.
2954     */
2955     bool CanDragCell() const;
2956
2957     /**
2958         Returns @true if columns can be moved by dragging with the mouse.
2959
2960         Columns can be moved by dragging on their labels.
2961     */
2962     bool CanDragColMove() const;
2963
2964     /**
2965         Returns @true if the given column can be resized by dragging with the
2966         mouse.
2967
2968         This function returns @true if resizing the columns interactively is
2969         globally enabled, i.e. if DisableDragColSize() hadn't been called, and
2970         if this column wasn't explicitly marked as non-resizable with
2971         DisableColResize().
2972     */
2973     bool CanDragColSize(int col) const;
2974
2975     /**
2976         Return @true if the dragging of grid lines to resize rows and columns
2977         is enabled or @false otherwise.
2978     */
2979     bool CanDragGridSize() const;
2980
2981     /**
2982         Returns @true if the given row can be resized by dragging with the
2983         mouse.
2984
2985         This is the same as CanDragColSize() but for rows.
2986     */
2987     bool CanDragRowSize(int row) const;
2988
2989     /**
2990         Disable interactive resizing of the specified column.
2991
2992         This method allows to disable resizing of an individual column in a
2993         grid where the columns are otherwise resizable (which is the case by
2994         default).
2995
2996         Notice that currently there is no way to make some columns resizable in
2997         a grid where columns can't be resized by default as there doesn't seem
2998         to be any need for this in practice. There is also no way to make the
2999         column marked as fixed using this method resizeable again because it is
3000         supposed that fixed columns are used for static parts of the grid and
3001         so should remain fixed during the entire grid lifetime.
3002
3003         Also notice that disabling interactive column resizing will not prevent
3004         the program from changing the column size.
3005
3006         @see EnableDragColSize()
3007      */
3008     void DisableColResize(int col);
3009
3010     /**
3011         Disable interactive resizing of the specified row.
3012
3013         This is the same as DisableColResize() but for rows.
3014
3015         @see EnableDragRowSize()
3016      */
3017     void DisableRowResize(int row);
3018
3019     /**
3020         Disables column moving by dragging with the mouse.
3021
3022         Equivalent to passing @false to EnableDragColMove().
3023     */
3024     void DisableDragColMove();
3025
3026     /**
3027         Disables column sizing by dragging with the mouse.
3028
3029         Equivalent to passing @false to EnableDragColSize().
3030     */
3031     void DisableDragColSize();
3032
3033     /**
3034         Disable mouse dragging of grid lines to resize rows and columns.
3035
3036         Equivalent to passing @false to EnableDragGridSize()
3037     */
3038     void DisableDragGridSize();
3039
3040     /**
3041         Disables row sizing by dragging with the mouse.
3042
3043         Equivalent to passing @false to EnableDragRowSize().
3044     */
3045     void DisableDragRowSize();
3046
3047     /**
3048         Enables or disables cell dragging with the mouse.
3049     */
3050     void EnableDragCell(bool enable = true);
3051
3052     /**
3053         Enables or disables column moving by dragging with the mouse.
3054     */
3055     void EnableDragColMove(bool enable = true);
3056
3057     /**
3058         Enables or disables column sizing by dragging with the mouse.
3059
3060         @see DisableColResize()
3061     */
3062     void EnableDragColSize(bool enable = true);
3063
3064     /**
3065         Enables or disables row and column resizing by dragging gridlines with
3066         the mouse.
3067     */
3068     void EnableDragGridSize(bool enable = true);
3069
3070     /**
3071         Enables or disables row sizing by dragging with the mouse.
3072
3073         @see DisableRowResize()
3074     */
3075     void EnableDragRowSize(bool enable = true);
3076
3077     /**
3078         Returns the column ID of the specified column position.
3079     */
3080     int GetColAt(int colPos) const;
3081
3082     /**
3083         Returns the position of the specified column.
3084     */
3085     int GetColPos(int colID) const;
3086
3087     /**
3088         Sets the position of the specified column.
3089     */
3090     void SetColPos(int colID, int newPos);
3091
3092     /**
3093         Sets the positions of all columns at once.
3094
3095         This method takes an array containing the indices of the columns in
3096         their display order, i.e. uses the same convention as
3097         wxHeaderCtrl::SetColumnsOrder().
3098     */
3099     void SetColumnsOrder(const wxArrayInt& order);
3100
3101     /**
3102         Resets the position of the columns to the default.
3103     */
3104     void ResetColPos();
3105
3106     //@}
3107
3108
3109     /**
3110         @name Cursor Movement
3111     */
3112     //@{
3113
3114     /**
3115         Returns the current grid cell column position.
3116     */
3117     int GetGridCursorCol() const;
3118
3119     /**
3120         Returns the current grid cell row position.
3121     */
3122     int GetGridCursorRow() const;
3123
3124     /**
3125         Make the given cell current and ensure it is visible.
3126
3127         This method is equivalent to calling MakeCellVisible() and
3128         SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL
3129         event is generated by it and the selected cell doesn't change if the
3130         event is vetoed.
3131      */
3132     void GoToCell(int row, int col);
3133     /**
3134         Make the given cell current and ensure it is visible.
3135
3136         This method is equivalent to calling MakeCellVisible() and
3137         SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL
3138         event is generated by it and the selected cell doesn't change if the
3139         event is vetoed.
3140      */
3141     void GoToCell(const wxGridCellCoords& coords);
3142
3143     /**
3144         Moves the grid cursor down by one row.
3145
3146         If a block of cells was previously selected it will expand if the
3147         argument is @true or be cleared if the argument is @false.
3148     */
3149     bool MoveCursorDown(bool expandSelection);
3150
3151     /**
3152         Moves the grid cursor down in the current column such that it skips to
3153         the beginning or end of a block of non-empty cells.
3154
3155         If a block of cells was previously selected it will expand if the
3156         argument is @true or be cleared if the argument is @false.
3157     */
3158     bool MoveCursorDownBlock(bool expandSelection);
3159
3160     /**
3161         Moves the grid cursor left by one column.
3162
3163         If a block of cells was previously selected it will expand if the
3164         argument is @true or be cleared if the argument is @false.
3165     */
3166     bool MoveCursorLeft(bool expandSelection);
3167
3168     /**
3169         Moves the grid cursor left in the current row such that it skips to the
3170         beginning or end of a block of non-empty cells.
3171
3172         If a block of cells was previously selected it will expand if the
3173         argument is @true or be cleared if the argument is @false.
3174     */
3175     bool MoveCursorLeftBlock(bool expandSelection);
3176
3177     /**
3178         Moves the grid cursor right by one column.
3179
3180         If a block of cells was previously selected it will expand if the
3181         argument is @true or be cleared if the argument is @false.
3182     */
3183     bool MoveCursorRight(bool expandSelection);
3184
3185     /**
3186         Moves the grid cursor right in the current row such that it skips to
3187         the beginning or end of a block of non-empty cells.
3188
3189         If a block of cells was previously selected it will expand if the
3190         argument is @true or be cleared if the argument is @false.
3191     */
3192     bool MoveCursorRightBlock(bool expandSelection);
3193
3194     /**
3195         Moves the grid cursor up by one row.
3196
3197         If a block of cells was previously selected it will expand if the
3198         argument is @true or be cleared if the argument is @false.
3199     */
3200     bool MoveCursorUp(bool expandSelection);
3201
3202     /**
3203         Moves the grid cursor up in the current column such that it skips to
3204         the beginning or end of a block of non-empty cells.
3205
3206         If a block of cells was previously selected it will expand if the
3207         argument is @true or be cleared if the argument is @false.
3208     */
3209     bool MoveCursorUpBlock(bool expandSelection);
3210
3211     /**
3212         Moves the grid cursor down by some number of rows so that the previous
3213         bottom visible row becomes the top visible row.
3214     */
3215     bool MovePageDown();
3216
3217     /**
3218         Moves the grid cursor up by some number of rows so that the previous
3219         top visible row becomes the bottom visible row.
3220     */
3221     bool MovePageUp();
3222
3223     /**
3224         Set the grid cursor to the specified cell.
3225
3226         The grid cursor indicates the current cell and can be moved by the user
3227         using the arrow keys or the mouse.
3228
3229         Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
3230         if the event handler vetoes this event, the cursor is not moved.
3231
3232         This function doesn't make the target call visible, use GoToCell() to
3233         do this.
3234     */
3235     void SetGridCursor(int row, int col);
3236     /**
3237         Set the grid cursor to the specified cell.
3238
3239         The grid cursor indicates the current cell and can be moved by the user
3240         using the arrow keys or the mouse.
3241
3242         Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
3243         if the event handler vetoes this event, the cursor is not moved.
3244
3245         This function doesn't make the target call visible, use GoToCell() to
3246         do this.
3247     */
3248     void SetGridCursor(const wxGridCellCoords& coords);
3249
3250     //@}
3251
3252
3253     /**
3254         @name User Selection
3255      */
3256     //@{
3257
3258     /**
3259         Deselects all cells that are currently selected.
3260     */
3261     void ClearSelection();
3262
3263     /**
3264         Returns an array of individually selected cells.
3265
3266         Notice that this array does @em not contain all the selected cells in
3267         general as it doesn't include the cells selected as part of column, row
3268         or block selection. You must use this method, GetSelectedCols(),
3269         GetSelectedRows() and GetSelectionBlockTopLeft() and
3270         GetSelectionBlockBottomRight() methods to obtain the entire selection
3271         in general.
3272
3273         Please notice this behaviour is by design and is needed in order to
3274         support grids of arbitrary size (when an entire column is selected in
3275         a grid with a million of columns, we don't want to create an array with
3276         a million of entries in this function, instead it returns an empty
3277         array and GetSelectedCols() returns an array containing one element).
3278     */
3279     wxGridCellCoordsArray GetSelectedCells() const;
3280
3281     /**
3282         Returns an array of selected columns.
3283
3284         Please notice that this method alone is not sufficient to find all the
3285         selected columns as it contains only the columns which were
3286         individually selected but not those being part of the block selection
3287         or being selected in virtue of all of their cells being selected
3288         individually, please see GetSelectedCells() for more details.
3289     */
3290     wxArrayInt GetSelectedCols() const;
3291
3292     /**
3293         Returns an array of selected rows.
3294
3295         Please notice that this method alone is not sufficient to find all the
3296         selected rows as it contains only the rows which were individually
3297         selected but not those being part of the block selection or being
3298         selected in virtue of all of their cells being selected individually,
3299         please see GetSelectedCells() for more details.
3300     */
3301     wxArrayInt GetSelectedRows() const;
3302
3303     /**
3304         Returns the colour used for drawing the selection background.
3305     */
3306     wxColour GetSelectionBackground() const;
3307
3308     /**
3309         Returns an array of the bottom right corners of blocks of selected
3310         cells.
3311
3312         Please see GetSelectedCells() for more information about the selection
3313         representation in wxGrid.
3314
3315         @see GetSelectionBlockTopLeft()
3316     */
3317     wxGridCellCoordsArray GetSelectionBlockBottomRight() const;
3318
3319     /**
3320         Returns an array of the top left corners of blocks of selected cells.
3321
3322         Please see GetSelectedCells() for more information about the selection
3323         representation in wxGrid.
3324
3325         @see GetSelectionBlockBottomRight()
3326     */
3327     wxGridCellCoordsArray GetSelectionBlockTopLeft() const;
3328
3329     /**
3330         Returns the colour used for drawing the selection foreground.
3331     */
3332     wxColour GetSelectionForeground() const;
3333
3334     /**
3335         Returns the current selection mode.
3336
3337         @see SetSelectionMode().
3338     */
3339     wxGridSelectionModes GetSelectionMode() const;
3340
3341     /**
3342         Returns @true if the given cell is selected.
3343     */
3344     bool IsInSelection(int row, int col) const;
3345     /**
3346         Returns @true if the given cell is selected.
3347     */
3348     bool IsInSelection(const wxGridCellCoords& coords) const;
3349
3350     /**
3351         Returns @true if there are currently any selected cells, rows, columns
3352         or blocks.
3353     */
3354     bool IsSelection() const;
3355
3356     /**
3357         Selects all cells in the grid.
3358     */
3359     void SelectAll();
3360
3361     /**
3362         Selects a rectangular block of cells.
3363
3364         If @a addToSelected is @false then any existing selection will be
3365         deselected; if @true the column will be added to the existing
3366         selection.
3367     */
3368     void SelectBlock(int topRow, int leftCol, int bottomRow, int rightCol,
3369                      bool addToSelected = false);
3370     /**
3371         Selects a rectangular block of cells.
3372
3373         If @a addToSelected is @false then any existing selection will be
3374         deselected; if @true the column will be added to the existing
3375         selection.
3376     */
3377     void SelectBlock(const wxGridCellCoords& topLeft,
3378                      const wxGridCellCoords& bottomRight,
3379                      bool addToSelected = false);
3380
3381     /**
3382         Selects the specified column.
3383
3384         If @a addToSelected is @false then any existing selection will be
3385         deselected; if @true the column will be added to the existing
3386         selection.
3387
3388         This method won't select anything if the current selection mode is
3389         wxGridSelectRows.
3390     */
3391     void SelectCol(int col, bool addToSelected = false);
3392
3393     /**
3394         Selects the specified row.
3395
3396         If @a addToSelected is @false then any existing selection will be
3397         deselected; if @true the row will be added to the existing selection.
3398
3399         This method won't select anything if the current selection mode is
3400         wxGridSelectColumns.
3401     */
3402     void SelectRow(int row, bool addToSelected = false);
3403
3404     /**
3405         Set the colour to be used for drawing the selection background.
3406     */
3407     void SetSelectionBackground(const wxColour& c);
3408
3409     /**
3410         Set the colour to be used for drawing the selection foreground.
3411     */
3412     void SetSelectionForeground(const wxColour& c);
3413
3414     /**
3415         Set the selection behaviour of the grid.
3416
3417         The existing selection is converted to conform to the new mode if
3418         possible and discarded otherwise (e.g. any individual selected cells
3419         are deselected if the new mode allows only the selection of the entire
3420         rows or columns).
3421     */
3422     void SetSelectionMode(wxGridSelectionModes selmode);
3423
3424     //@}
3425
3426
3427     /**
3428         @name Scrolling
3429      */
3430     //@{
3431
3432     /**
3433         Returns the number of pixels per horizontal scroll increment.
3434
3435         The default is 15.
3436
3437         @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY()
3438     */
3439     int GetScrollLineX() const;
3440
3441     /**
3442         Returns the number of pixels per vertical scroll increment.
3443
3444         The default is 15.
3445
3446         @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY()
3447     */
3448     int GetScrollLineY() const;
3449
3450     /**
3451         Returns @true if a cell is either entirely or at least partially
3452         visible in the grid window.
3453
3454         By default, the cell must be entirely visible for this function to
3455         return @true but if @a wholeCellVisible is @false, the function returns
3456         @true even if the cell is only partially visible.
3457     */
3458     bool IsVisible(int row, int col, bool wholeCellVisible = true) const;
3459     /**
3460         Returns @true if a cell is either entirely or at least partially
3461         visible in the grid window.
3462
3463         By default, the cell must be entirely visible for this function to
3464         return @true but if @a wholeCellVisible is @false, the function returns
3465         @true even if the cell is only partially visible.
3466     */
3467     bool IsVisible(const wxGridCellCoords& coords,
3468                    bool wholeCellVisible = true) const;
3469
3470     /**
3471         Brings the specified cell into the visible grid cell area with minimal
3472         scrolling.
3473
3474         Does nothing if the cell is already visible.
3475     */
3476     void MakeCellVisible(int row, int col);
3477     /**
3478         Brings the specified cell into the visible grid cell area with minimal
3479         scrolling.
3480
3481         Does nothing if the cell is already visible.
3482     */
3483     void MakeCellVisible(const wxGridCellCoords& coords);
3484
3485     /**
3486         Sets the number of pixels per horizontal scroll increment.
3487
3488         The default is 15.
3489
3490         @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY()
3491     */
3492     void SetScrollLineX(int x);
3493
3494     /**
3495         Sets the number of pixels per vertical scroll increment.
3496
3497         The default is 15.
3498
3499         @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX()
3500     */
3501     void SetScrollLineY(int y);
3502
3503     //@}
3504
3505
3506     /**
3507         @name Cell and Device Coordinate Translation
3508      */
3509     //@{
3510
3511     /**
3512         Convert grid cell coordinates to grid window pixel coordinates.
3513
3514         This function returns the rectangle that encloses the block of cells
3515         limited by @a topLeft and @a bottomRight cell in device coords and
3516         clipped to the client size of the grid window.
3517
3518         @see CellToRect()
3519     */
3520     wxRect BlockToDeviceRect(const wxGridCellCoords& topLeft,
3521                              const wxGridCellCoords& bottomRight) const;
3522
3523     /**
3524         Return the rectangle corresponding to the grid cell's size and position
3525         in logical coordinates.
3526
3527         @see BlockToDeviceRect()
3528     */
3529     wxRect CellToRect(int row, int col) const;
3530     /**
3531         Return the rectangle corresponding to the grid cell's size and position
3532         in logical coordinates.
3533
3534         @see BlockToDeviceRect()
3535     */
3536     wxRect CellToRect(const wxGridCellCoords& coords) const;
3537
3538     /**
3539         Returns the column at the given pixel position.
3540
3541         @param x
3542             The x position to evaluate.
3543         @param clipToMinMax
3544             If @true, rather than returning @c wxNOT_FOUND, it returns either
3545             the first or last column depending on whether @a x is too far to
3546             the left or right respectively.
3547         @return
3548             The column index or @c wxNOT_FOUND.
3549     */
3550     int XToCol(int x, bool clipToMinMax = false) const;
3551
3552     /**
3553         Returns the column whose right hand edge is close to the given logical
3554         @a x position.
3555
3556         If no column edge is near to this position @c wxNOT_FOUND is returned.
3557     */
3558     int XToEdgeOfCol(int x) const;
3559
3560     /**
3561         Translates logical pixel coordinates to the grid cell coordinates.
3562
3563         Notice that this function expects logical coordinates on input so if
3564         you use this function in a mouse event handler you need to translate
3565         the mouse position, which is expressed in device coordinates, to
3566         logical ones.
3567
3568         @see XToCol(), YToRow()
3569      */
3570     wxGridCellCoords XYToCell(int x, int y) const;
3571     /**
3572         Translates logical pixel coordinates to the grid cell coordinates.
3573
3574         Notice that this function expects logical coordinates on input so if
3575         you use this function in a mouse event handler you need to translate
3576         the mouse position, which is expressed in device coordinates, to
3577         logical ones.
3578
3579         @see XToCol(), YToRow()
3580      */
3581     wxGridCellCoords XYToCell(const wxPoint& pos) const;
3582     // XYToCell(int, int, wxGridCellCoords&) overload is intentionally
3583     // undocumented, using it is ugly and non-const reference parameters are
3584     // not used in wxWidgets API
3585
3586     /**
3587         Returns the row whose bottom edge is close to the given logical @a y
3588         position.
3589
3590         If no row edge is near to this position @c wxNOT_FOUND is returned.
3591     */
3592     int YToEdgeOfRow(int y) const;
3593
3594     /**
3595         Returns the grid row that corresponds to the logical @a y coordinate.
3596
3597         Returns @c wxNOT_FOUND if there is no row at the @a y position.
3598     */
3599     int YToRow(int y, bool clipToMinMax = false) const;
3600
3601     //@}
3602
3603
3604     /**
3605         @name Miscellaneous Functions
3606      */
3607     //@{
3608
3609     /**
3610         Appends one or more new columns to the right of the grid.
3611
3612         The @a updateLabels argument is not used at present. If you are using a
3613         derived grid table class you will need to override
3614         wxGridTableBase::AppendCols(). See InsertCols() for further
3615         information.
3616
3617         @return @true on success or @false if appending columns failed.
3618     */
3619     bool AppendCols(int numCols = 1, bool updateLabels = true);
3620
3621     /**
3622         Appends one or more new rows to the bottom of the grid.
3623
3624         The @a updateLabels argument is not used at present. If you are using a
3625         derived grid table class you will need to override
3626         wxGridTableBase::AppendRows(). See InsertRows() for further
3627         information.
3628
3629         @return @true on success or @false if appending rows failed.
3630     */
3631     bool AppendRows(int numRows = 1, bool updateLabels = true);
3632
3633     /**
3634         Return @true if the horizontal grid lines stop at the last column
3635         boundary or @false if they continue to the end of the window.
3636
3637         The default is to clip grid lines.
3638
3639         @see ClipHorzGridLines(), AreVertGridLinesClipped()
3640      */
3641     bool AreHorzGridLinesClipped() const;
3642
3643     /**
3644         Return @true if the vertical grid lines stop at the last row
3645         boundary or @false if they continue to the end of the window.
3646
3647         The default is to clip grid lines.
3648
3649         @see ClipVertGridLines(), AreHorzGridLinesClipped()
3650      */
3651     bool AreVertGridLinesClipped() const;
3652
3653     /**
3654         Increments the grid's batch count.
3655
3656         When the count is greater than zero repainting of the grid is
3657         suppressed. Each call to BeginBatch must be matched by a later call to
3658         EndBatch(). Code that does a lot of grid modification can be enclosed
3659         between BeginBatch() and EndBatch() calls to avoid screen flicker. The
3660         final EndBatch() call will cause the grid to be repainted.
3661
3662         Notice that you should use wxGridUpdateLocker which ensures that there
3663         is always a matching EndBatch() call for this BeginBatch() if possible
3664         instead of calling this method directly.
3665     */
3666     void BeginBatch();
3667
3668     /**
3669         Clears all data in the underlying grid table and repaints the grid.
3670
3671         The table is not deleted by this function. If you are using a derived
3672         table class then you need to override wxGridTableBase::Clear() for this
3673         function to have any effect.
3674     */
3675     void ClearGrid();
3676
3677     /**
3678         Change whether the horizontal grid lines are clipped by the end of the
3679         last column.
3680
3681         By default the grid lines are not drawn beyond the end of the last
3682         column but after calling this function with @a clip set to @false they
3683         will be drawn across the entire grid window.
3684
3685         @see AreHorzGridLinesClipped(), ClipVertGridLines()
3686      */
3687     void ClipHorzGridLines(bool clip);
3688
3689     /**
3690         Change whether the vertical grid lines are clipped by the end of the
3691         last row.
3692
3693         By default the grid lines are not drawn beyond the end of the last
3694         row but after calling this function with @a clip set to @false they
3695         will be drawn across the entire grid window.
3696
3697         @see AreVertGridLinesClipped(), ClipHorzGridLines()
3698      */
3699     void ClipVertGridLines(bool clip);
3700
3701     /**
3702         Deletes one or more columns from a grid starting at the specified
3703         position.
3704
3705         The @a updateLabels argument is not used at present. If you are using a
3706         derived grid table class you will need to override
3707         wxGridTableBase::DeleteCols(). See InsertCols() for further
3708         information.
3709
3710         @return @true on success or @false if deleting columns failed.
3711     */
3712     bool DeleteCols(int pos = 0, int numCols = 1, bool updateLabels = true);
3713
3714     /**
3715         Deletes one or more rows from a grid starting at the specified
3716         position.
3717
3718         The @a updateLabels argument is not used at present. If you are using a
3719         derived grid table class you will need to override
3720         wxGridTableBase::DeleteRows(). See InsertRows() for further
3721         information.
3722
3723         @return @true on success or @false if appending rows failed.
3724     */
3725     bool DeleteRows(int pos = 0, int numRows = 1, bool updateLabels = true);
3726
3727     /**
3728         Decrements the grid's batch count.
3729
3730         When the count is greater than zero repainting of the grid is
3731         suppressed. Each previous call to BeginBatch() must be matched by a
3732         later call to EndBatch(). Code that does a lot of grid modification can
3733         be enclosed between BeginBatch() and EndBatch() calls to avoid screen
3734         flicker. The final EndBatch() will cause the grid to be repainted.
3735
3736         @see wxGridUpdateLocker
3737     */
3738     void EndBatch();
3739
3740     /**
3741         Overridden wxWindow method.
3742     */
3743     virtual void Fit();
3744
3745     /**
3746         Causes immediate repainting of the grid.
3747
3748         Use this instead of the usual wxWindow::Refresh().
3749     */
3750     void ForceRefresh();
3751
3752     /**
3753         Returns the number of times that BeginBatch() has been called without
3754         (yet) matching calls to EndBatch(). While the grid's batch count is
3755         greater than zero the display will not be updated.
3756     */
3757     int GetBatchCount();
3758
3759     /**
3760         Returns the total number of grid columns.
3761
3762         This is the same as the number of columns in the underlying grid table.
3763     */
3764     int GetNumberCols() const;
3765
3766     /**
3767         Returns the total number of grid rows.
3768
3769         This is the same as the number of rows in the underlying grid table.
3770     */
3771     int GetNumberRows() const;
3772
3773     /**
3774         Returns the attribute for the given cell creating one if necessary.
3775
3776         If the cell already has an attribute, it is returned. Otherwise a new
3777         attribute is created, associated with the cell and returned. In any
3778         case the caller must call DecRef() on the returned pointer.
3779
3780         This function may only be called if CanHaveAttributes() returns @true.
3781     */
3782     wxGridCellAttr *GetOrCreateCellAttr(int row, int col) const;
3783
3784     /**
3785         Returns a base pointer to the current table object.
3786
3787         The returned pointer is still owned by the grid.
3788     */
3789     wxGridTableBase *GetTable() const;
3790
3791     /**
3792         Inserts one or more new columns into a grid with the first new column
3793         at the specified position.
3794
3795         Notice that inserting the columns in the grid requires grid table
3796         cooperation: when this method is called, grid object begins by
3797         requesting the underlying grid table to insert new columns. If this is
3798         successful the table notifies the grid and the grid updates the
3799         display. For a default grid (one where you have called CreateGrid())
3800         this process is automatic. If you are using a custom grid table
3801         (specified with SetTable()) then you must override
3802         wxGridTableBase::InsertCols() in your derived table class.
3803
3804         @param pos
3805             The position which the first newly inserted column will have.
3806         @param numCols
3807             The number of columns to insert.
3808         @param updateLabels
3809             Currently not used.
3810         @return
3811             @true if the columns were successfully inserted, @false if an error
3812             occurred (most likely the table couldn't be updated).
3813     */
3814     bool InsertCols(int pos = 0, int numCols = 1, bool updateLabels = true);
3815
3816     /**
3817         Inserts one or more new rows into a grid with the first new row at the
3818         specified position.
3819
3820         Notice that you must implement wxGridTableBase::InsertRows() if you use
3821         a grid with a custom table, please see InsertCols() for more
3822         information.
3823
3824         @param pos
3825             The position which the first newly inserted row will have.
3826         @param numRows
3827             The number of rows to insert.
3828         @param updateLabels
3829             Currently not used.
3830         @return
3831             @true if the rows were successfully inserted, @false if an error
3832             occurred (most likely the table couldn't be updated).
3833     */
3834     bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true);
3835
3836     /**
3837         Sets the cell attributes for all cells in the specified column.
3838
3839         For more information about controlling grid cell attributes see the
3840         wxGridCellAttr cell attribute class and the @ref overview_grid.
3841     */
3842     void SetColAttr(int col, wxGridCellAttr* attr);
3843
3844     /**
3845         Sets the extra margins used around the grid area.
3846
3847         A grid may occupy more space than needed for its data display and
3848         this function allows to set how big this extra space is
3849     */
3850     void SetMargins(int extraWidth, int extraHeight);
3851
3852     /**
3853         Sets the cell attributes for all cells in the specified row.
3854
3855         The grid takes ownership of the attribute pointer.
3856
3857         See the wxGridCellAttr class for more information about controlling
3858         cell attributes.
3859     */
3860     void SetRowAttr(int row, wxGridCellAttr* attr);
3861
3862     //@}
3863
3864
3865     /**
3866         @name Sorting support.
3867
3868         wxGrid doesn't provide any support for sorting the data but it does
3869         generate events allowing the user code to sort it and supports
3870         displaying the sort indicator in the column used for sorting.
3871
3872         To use wxGrid sorting support you need to handle wxEVT_GRID_COL_SORT
3873         event (and not veto it) and resort the data displayed in the grid. The
3874         grid will automatically update the sorting indicator on the column
3875         which was clicked.
3876
3877         You can also call the functions in this section directly to update the
3878         sorting indicator. Once again, they don't do anything with the grid
3879         data, it remains your responsibility to actually sort it appropriately.
3880      */
3881     //@{
3882
3883     /**
3884         Return the column in which the sorting indicator is currently
3885         displayed.
3886
3887         Returns @c wxNOT_FOUND if sorting indicator is not currently displayed
3888         at all.
3889
3890         @see SetSortingColumn()
3891      */
3892     int GetSortingColumn() const;
3893
3894     /**
3895         Return @true if this column is currently used for sorting.
3896
3897         @see GetSortingColumn()
3898      */
3899     bool IsSortingBy(int col) const;
3900
3901     /**
3902         Return @true if the current sorting order is ascending or @false if it
3903         is descending.
3904
3905         It only makes sense to call this function if GetSortingColumn() returns
3906         a valid column index and not @c wxNOT_FOUND.
3907
3908         @see SetSortingColumn()
3909      */
3910     bool IsSortOrderAscending() const;
3911
3912     /**
3913         Set the column to display the sorting indicator in and its direction.
3914
3915         @param col
3916             The column to display the sorting indicator in or @c wxNOT_FOUND to
3917             remove any currently displayed sorting indicator.
3918         @param ascending
3919             If @true, display the ascending sort indicator, otherwise display
3920             the descending sort indicator.
3921
3922         @see GetSortingColumn(), IsSortOrderAscending()
3923      */
3924     void SetSortingColumn(int col, bool ascending = true);
3925
3926     /**
3927         Remove any currently shown sorting indicator.
3928
3929         This is equivalent to calling SetSortingColumn() with @c wxNOT_FOUND
3930         first argument.
3931      */
3932     void UnsetSortingColumn();
3933     //@}
3934
3935
3936     /**
3937         @name Accessors for component windows.
3938
3939         Return the various child windows of wxGrid.
3940
3941         wxGrid is an empty parent window for 4 children representing the column
3942         labels window (top), the row labels window (left), the corner window
3943         (top left) and the main grid window. It may be necessary to use these
3944         individual windows and not the wxGrid window itself if you need to
3945         handle events for them (this can be done using wxEvtHandler::Connect()
3946         or wxWindow::PushEventHandler()) or do something else requiring the use
3947         of the correct window pointer. Notice that you should not, however,
3948         change these windows (e.g. reposition them or draw over them) because
3949         they are managed by wxGrid itself.
3950      */
3951     //@{
3952
3953     /**
3954         Return the main grid window containing the grid cells.
3955
3956         This window is always shown.
3957      */
3958     wxWindow *GetGridWindow() const;
3959
3960     /**
3961         Return the row labels window.
3962
3963         This window is not shown if the row labels were hidden using
3964         HideRowLabels().
3965      */
3966     wxWindow *GetGridRowLabelWindow() const;
3967
3968     /**
3969         Return the column labels window.
3970
3971         This window is not shown if the columns labels were hidden using
3972         HideColLabels().
3973
3974         Depending on whether UseNativeColHeader() was called or not this can be
3975         either a wxHeaderCtrl or a plain wxWindow.  This function returns a valid
3976         window pointer in either case but in the former case you can also use
3977         GetGridColHeader() to access it if you need wxHeaderCtrl-specific
3978         functionality.
3979      */
3980     wxWindow *GetGridColLabelWindow() const;
3981
3982     /**
3983         Return the window in the top left grid corner.
3984
3985         This window is shown only of both columns and row labels are shown and
3986         normally doesn't contain anything. Clicking on it is handled by wxGrid
3987         however and can be used to select the entire grid.
3988      */
3989     wxWindow *GetGridCornerLabelWindow() const;
3990
3991     /**
3992         Return the header control used for column labels display.
3993
3994         This function can only be called if UseNativeColHeader() had been
3995         called.
3996      */
3997     wxHeaderCtrl *GetGridColHeader() const;
3998
3999     //@}
4000
4001 protected:
4002     /**
4003         Returns @true if this grid has support for cell attributes.
4004
4005         The grid supports attributes if it has the associated table which, in
4006         turn, has attributes support, i.e. wxGridTableBase::CanHaveAttributes()
4007         returns @true.
4008     */
4009     bool CanHaveAttributes() const;
4010
4011     /**
4012         Get the minimal width of the given column/row.
4013
4014         The value returned by this function may be different than that returned
4015         by GetColMinimalAcceptableWidth() if SetColMinimalWidth() had been
4016         called for this column.
4017     */
4018     int GetColMinimalWidth(int col) const;
4019
4020     /**
4021         Returns the coordinate of the right border specified column.
4022     */
4023     int GetColRight(int col) const;
4024
4025     /**
4026         Returns the coordinate of the left border specified column.
4027     */
4028     int GetColLeft(int col) const;
4029
4030     /**
4031         Returns the minimal size for the given column.
4032
4033         The value returned by this function may be different than that returned
4034         by GetRowMinimalAcceptableHeight() if SetRowMinimalHeight() had been
4035         called for this row.
4036     */
4037     int GetRowMinimalHeight(int col) const;
4038 };
4039
4040
4041
4042 /**
4043     @class wxGridUpdateLocker
4044
4045     This small class can be used to prevent wxGrid from redrawing during its
4046     lifetime by calling wxGrid::BeginBatch() in its constructor and
4047     wxGrid::EndBatch() in its destructor. It is typically used in a function
4048     performing several operations with a grid which would otherwise result in
4049     flicker. For example:
4050
4051     @code
4052     void MyFrame::Foo()
4053     {
4054         m_grid = new wxGrid(this, ...);
4055
4056         wxGridUpdateLocker noUpdates(m_grid);
4057         m_grid-AppendColumn();
4058         // ... many other operations with m_grid ...
4059         m_grid-AppendRow();
4060
4061         // destructor called, grid refreshed
4062     }
4063     @endcode
4064
4065     Using this class is easier and safer than calling wxGrid::BeginBatch() and
4066     wxGrid::EndBatch() because you don't risk missing the call the latter (due
4067     to an exception for example).
4068
4069     @library{wxadv}
4070     @category{grid}
4071 */
4072 class wxGridUpdateLocker
4073 {
4074 public:
4075     /**
4076         Creates an object preventing the updates of the specified @a grid. The
4077         parameter could be @NULL in which case nothing is done. If @a grid is
4078         non-@NULL then the grid must exist for longer than this
4079         wxGridUpdateLocker object itself.
4080
4081         The default constructor could be followed by a call to Create() to set
4082         the grid object later.
4083     */
4084     wxGridUpdateLocker(wxGrid* grid = NULL);
4085
4086     /**
4087         Destructor reenables updates for the grid this object is associated
4088         with.
4089     */
4090     ~wxGridUpdateLocker();
4091
4092     /**
4093         This method can be called if the object had been constructed using the
4094         default constructor. It must not be called more than once.
4095     */
4096     void Create(wxGrid* grid);
4097 };
4098
4099
4100
4101 /**
4102     @class wxGridEvent
4103
4104     This event class contains information about various grid events.
4105
4106     Notice that all grid event table macros are available in two versions:
4107     @c EVT_GRID_XXX and @c EVT_GRID_CMD_XXX. The only difference between the
4108     two is that the former doesn't allow to specify the grid window identifier
4109     and so takes a single parameter, the event handler, but is not suitable if
4110     there is more than one grid control in the window where the event table is
4111     used (as it would catch the events from all the grids). The version with @c
4112     CMD takes the id as first argument and the event handler as the second one
4113     and so can be used with multiple grids as well. Otherwise there are no
4114     difference between the two and only the versions without the id are
4115     documented below for brevity.
4116
4117     @beginEventTable{wxGridEvent}
4118     @event{EVT_GRID_CELL_CHANGING(func)}
4119         The user is about to change the data in a cell. The new cell value as
4120         string is available from GetString() event object method. This event
4121         can be vetoed if the change is not allowed.
4122         Processes a @c wxEVT_GRID_CELL_CHANGING event type.
4123     @event{EVT_GRID_CELL_CHANGED(func)}
4124         The user changed the data in a cell. The old cell value as string is
4125         available from GetString() event object method. Notice that vetoing
4126         this event still works for backwards compatibility reasons but any new
4127         code should only veto EVT_GRID_CELL_CHANGING event and not this one.
4128         Processes a @c wxEVT_GRID_CELL_CHANGED event type.
4129     @event{EVT_GRID_CELL_LEFT_CLICK(func)}
4130         The user clicked a cell with the left mouse button. Processes a
4131         @c wxEVT_GRID_CELL_LEFT_CLICK event type.
4132     @event{EVT_GRID_CELL_LEFT_DCLICK(func)}
4133         The user double-clicked a cell with the left mouse button. Processes a
4134         @c wxEVT_GRID_CELL_LEFT_DCLICK event type.
4135     @event{EVT_GRID_CELL_RIGHT_CLICK(func)}
4136         The user clicked a cell with the right mouse button. Processes a
4137         @c wxEVT_GRID_CELL_RIGHT_CLICK event type.
4138     @event{EVT_GRID_CELL_RIGHT_DCLICK(func)}
4139         The user double-clicked a cell with the right mouse button. Processes a
4140         @c wxEVT_GRID_CELL_RIGHT_DCLICK event type.
4141     @event{EVT_GRID_EDITOR_HIDDEN(func)}
4142         The editor for a cell was hidden. Processes a
4143         @c wxEVT_GRID_EDITOR_HIDDEN event type.
4144     @event{EVT_GRID_EDITOR_SHOWN(func)}
4145         The editor for a cell was shown. Processes a
4146         @c wxEVT_GRID_EDITOR_SHOWN event type.
4147     @event{EVT_GRID_LABEL_LEFT_CLICK(func)}
4148         The user clicked a label with the left mouse button. Processes a
4149         @c wxEVT_GRID_LABEL_LEFT_CLICK event type.
4150     @event{EVT_GRID_LABEL_LEFT_DCLICK(func)}
4151         The user double-clicked a label with the left mouse button. Processes a
4152         @c wxEVT_GRID_LABEL_LEFT_DCLICK event type.
4153     @event{EVT_GRID_LABEL_RIGHT_CLICK(func)}
4154         The user clicked a label with the right mouse button. Processes a
4155         @c wxEVT_GRID_LABEL_RIGHT_CLICK event type.
4156     @event{EVT_GRID_LABEL_RIGHT_DCLICK(func)}
4157         The user double-clicked a label with the right mouse button. Processes
4158         a @c wxEVT_GRID_LABEL_RIGHT_DCLICK event type.
4159     @event{EVT_GRID_SELECT_CELL(func)}
4160         The given cell was made current, either by user or by the program via a
4161         call to SetGridCursor() or GoToCell(). Processes a
4162         @c wxEVT_GRID_SELECT_CELL event type.
4163     @event{EVT_GRID_COL_MOVE(func)}
4164         The user tries to change the order of the columns in the grid by
4165         dragging the column specified by GetCol(). This event can be vetoed to
4166         either prevent the user from reordering the column change completely
4167         (but notice that if you don't want to allow it at all, you simply
4168         shouldn't call wxGrid::EnableDragColMove() in the first place), vetoed
4169         but handled in some way in the handler, e.g. by really moving the
4170         column to the new position at the associated table level, or allowed to
4171         proceed in which case wxGrid::SetColPos() is used to reorder the
4172         columns display order without affecting the use of the column indices
4173         otherwise.
4174         This event macro corresponds to @c wxEVT_GRID_COL_MOVE event type.
4175     @event{EVT_GRID_COL_SORT(func)}
4176         This event is generated when a column is clicked by the user and its
4177         name is explained by the fact that the custom reaction to a click on a
4178         column is to sort the grid contents by this column. However the grid
4179         itself has no special support for sorting and it's up to the handler of
4180         this event to update the associated table. But if the event is handled
4181         (and not vetoed) the grid supposes that the table was indeed resorted
4182         and updates the column to indicate the new sort order and refreshes
4183         itself.
4184         This event macro corresponds to @c wxEVT_GRID_COL_SORT event type.
4185     @endEventTable
4186
4187     @library{wxadv}
4188     @category{grid,events}
4189 */
4190 class wxGridEvent : public wxNotifyEvent
4191 {
4192 public:
4193     /**
4194         Default constructor.
4195     */
4196     wxGridEvent();
4197     /**
4198         Constructor for initializing all event attributes.
4199     */
4200     wxGridEvent(int id, wxEventType type, wxObject* obj,
4201                 int row = -1, int col = -1, int x = -1, int y = -1,
4202                 bool sel = true, const wxKeyboardState& kbd = wxKeyboardState());
4203
4204     /**
4205         Returns @true if the Alt key was down at the time of the event.
4206     */
4207     bool AltDown() const;
4208
4209     /**
4210         Returns @true if the Control key was down at the time of the event.
4211     */
4212     bool ControlDown() const;
4213
4214     /**
4215         Column at which the event occurred.
4216     */
4217     virtual int GetCol();
4218
4219     /**
4220         Position in pixels at which the event occurred.
4221     */
4222     wxPoint GetPosition();
4223
4224     /**
4225         Row at which the event occurred.
4226     */
4227     virtual int GetRow();
4228
4229     /**
4230         Returns @true if the Meta key was down at the time of the event.
4231     */
4232     bool MetaDown() const;
4233
4234     /**
4235         Returns @true if the user is selecting grid cells, or @false if
4236         deselecting.
4237     */
4238     bool Selecting();
4239
4240     /**
4241         Returns @true if the Shift key was down at the time of the event.
4242     */
4243     bool ShiftDown() const;
4244 };
4245
4246
4247
4248 /**
4249     @class wxGridSizeEvent
4250
4251     This event class contains information about a row/column resize event.
4252
4253     @beginEventTable{wxGridSizeEvent}
4254     @event{EVT_GRID_CMD_COL_SIZE(id, func)}
4255         The user resized a column, corresponds to @c wxEVT_GRID_COL_SIZE event
4256         type.
4257     @event{EVT_GRID_CMD_ROW_SIZE(id, func)}
4258         The user resized a row, corresponds to @c wxEVT_GRID_ROW_SIZE event
4259         type.
4260     @event{EVT_GRID_COL_SIZE(func)}
4261         Same as EVT_GRID_CMD_COL_SIZE() but uses `wxID_ANY` id.
4262     @event{EVT_GRID_ROW_SIZE(func)}
4263         Same as EVT_GRID_CMD_ROW_SIZE() but uses `wxID_ANY` id.
4264     @endEventTable
4265
4266     @library{wxadv}
4267     @category{grid,events}
4268 */
4269 class wxGridSizeEvent : public wxNotifyEvent
4270 {
4271 public:
4272     /**
4273         Default constructor.
4274     */
4275     wxGridSizeEvent();
4276     /**
4277         Constructor for initializing all event attributes.
4278     */
4279     wxGridSizeEvent(int id, wxEventType type, wxObject* obj,
4280                     int rowOrCol = -1, int x = -1, int y = -1,
4281                     const wxKeyboardState& kbd = wxKeyboardState());
4282
4283     /**
4284         Returns @true if the Alt key was down at the time of the event.
4285     */
4286     bool AltDown() const;
4287
4288     /**
4289         Returns @true if the Control key was down at the time of the event.
4290     */
4291     bool ControlDown() const;
4292
4293     /**
4294         Position in pixels at which the event occurred.
4295     */
4296     wxPoint GetPosition();
4297
4298     /**
4299         Row or column at that was resized.
4300     */
4301     int GetRowOrCol();
4302
4303     /**
4304         Returns @true if the Meta key was down at the time of the event.
4305     */
4306     bool MetaDown() const;
4307
4308     /**
4309         Returns @true if the Shift key was down at the time of the event.
4310     */
4311     bool ShiftDown() const;
4312 };
4313
4314
4315
4316 /**
4317     @class wxGridRangeSelectEvent
4318
4319     @beginEventTable{wxGridRangeSelectEvent}
4320     @event{EVT_GRID_RANGE_SELECT(func)}
4321         The user selected a group of contiguous cells. Processes a
4322         @c wxEVT_GRID_RANGE_SELECT event type.
4323     @event{EVT_GRID_CMD_RANGE_SELECT(id, func)}
4324         The user selected a group of contiguous cells; variant taking a window
4325         identifier. Processes a @c wxEVT_GRID_RANGE_SELECT event type.
4326     @endEventTable
4327
4328     @library{wxadv}
4329     @category{grid,events}
4330 */
4331 class wxGridRangeSelectEvent : public wxNotifyEvent
4332 {
4333 public:
4334     /**
4335         Default constructor.
4336     */
4337     wxGridRangeSelectEvent();
4338     /**
4339         Constructor for initializing all event attributes.
4340     */
4341     wxGridRangeSelectEvent(int id, wxEventType type,
4342                            wxObject* obj,
4343                            const wxGridCellCoords& topLeft,
4344                            const wxGridCellCoords& bottomRight,
4345                            bool sel = true, const wxKeyboardState& kbd = wxKeyboardState());
4346
4347     /**
4348         Returns @true if the Alt key was down at the time of the event.
4349     */
4350     bool AltDown() const;
4351
4352     /**
4353         Returns @true if the Control key was down at the time of the event.
4354     */
4355     bool ControlDown() const;
4356
4357     /**
4358         Top left corner of the rectangular area that was (de)selected.
4359     */
4360     wxGridCellCoords GetBottomRightCoords();
4361
4362     /**
4363         Bottom row of the rectangular area that was (de)selected.
4364     */
4365     int GetBottomRow();
4366
4367     /**
4368         Left column of the rectangular area that was (de)selected.
4369     */
4370     int GetLeftCol();
4371
4372     /**
4373         Right column of the rectangular area that was (de)selected.
4374     */
4375     int GetRightCol();
4376
4377     /**
4378         Top left corner of the rectangular area that was (de)selected.
4379     */
4380     wxGridCellCoords GetTopLeftCoords();
4381
4382     /**
4383         Top row of the rectangular area that was (de)selected.
4384     */
4385     int GetTopRow();
4386
4387     /**
4388         Returns @true if the Meta key was down at the time of the event.
4389     */
4390     bool MetaDown() const;
4391
4392     /**
4393         Returns @true if the area was selected, @false otherwise.
4394     */
4395     bool Selecting();
4396
4397     /**
4398         Returns @true if the Shift key was down at the time of the event.
4399     */
4400     bool ShiftDown() const;
4401 };
4402
4403
4404
4405 /**
4406     @class wxGridEditorCreatedEvent
4407
4408     @beginEventTable{wxGridEditorCreatedEvent}
4409     @event{EVT_GRID_EDITOR_CREATED(func)}
4410         The editor for a cell was created. Processes a
4411         @c wxEVT_GRID_EDITOR_CREATED event type.
4412     @event{EVT_GRID_CMD_EDITOR_CREATED(id, func)}
4413         The editor for a cell was created; variant taking a window identifier.
4414         Processes a @c wxEVT_GRID_EDITOR_CREATED event type.
4415     @endEventTable
4416
4417     @library{wxadv}
4418     @category{grid,events}
4419 */
4420 class wxGridEditorCreatedEvent : public wxCommandEvent
4421 {
4422 public:
4423     /**
4424         Default constructor.
4425     */
4426     wxGridEditorCreatedEvent();
4427     /**
4428         Constructor for initializing all event attributes.
4429     */
4430     wxGridEditorCreatedEvent(int id, wxEventType type, wxObject* obj,
4431                              int row, int col, wxControl* ctrl);
4432
4433     /**
4434         Returns the column at which the event occurred.
4435     */
4436     int GetCol();
4437
4438     /**
4439         Returns the edit control.
4440     */
4441     wxControl* GetControl();
4442
4443     /**
4444         Returns the row at which the event occurred.
4445     */
4446     int GetRow();
4447
4448     /**
4449         Sets the column at which the event occurred.
4450     */
4451     void SetCol(int col);
4452
4453     /**
4454         Sets the edit control.
4455     */
4456     void SetControl(wxControl* ctrl);
4457
4458     /**
4459         Sets the row at which the event occurred.
4460     */
4461     void SetRow(int row);
4462 };
4463