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