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