1
/////////////////////////////////////////////////////////////////////////////
3
// Purpose: interface of wxGrid and related classes
4
// Author: wxWidgets team
5
// RCS-ID: $Id: grid.h 71577 2012-05-27 13:00:19Z VZ $
6
// Licence: wxWindows licence
7
/////////////////////////////////////////////////////////////////////////////
10
@class wxGridCellRenderer
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.
21
@see wxGridCellAutoWrapStringRenderer, wxGridCellBoolRenderer,
22
wxGridCellDateTimeRenderer, wxGridCellEnumRenderer,
23
wxGridCellFloatRenderer, wxGridCellNumberRenderer,
24
wxGridCellStringRenderer
26
class wxGridCellRenderer
30
This function must be implemented in derived classes to return a copy
33
virtual wxGridCellRenderer* Clone() const = 0;
36
Draw the given cell on the provided DC inside the given rectangle using
37
the style specified by the attribute and the default or selected state
38
corresponding to the isSelected value.
40
This pure virtual function has a default implementation which will
41
prepare the DC using the given attribute: it will draw the rectangle
42
with the background colour from attr and set the text colour and font.
44
virtual void Draw(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc,
45
const wxRect& rect, int row, int col,
49
Get the preferred size of the cell for its contents.
51
virtual wxSize GetBestSize(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc,
52
int row, int col) = 0;
56
@class wxGridCellAutoWrapStringRenderer
58
This class may be used to format string data in a cell. The too
59
long lines are wrapped to be shown entirely at word boundaries.
64
@see wxGridCellRenderer, wxGridCellBoolRenderer,
65
wxGridCellDateTimeRenderer, wxGridCellEnumRenderer,
66
wxGridCellFloatRenderer, wxGridCellNumberRenderer,
67
wxGridCellStringRenderer
70
class wxGridCellAutoWrapStringRenderer : public wxGridCellStringRenderer
76
wxGridCellAutoWrapStringRenderer();
81
@class wxGridCellBoolRenderer
83
This class may be used to format boolean data in a cell.
88
@see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
89
wxGridCellDateTimeRenderer, wxGridCellEnumRenderer,
90
wxGridCellFloatRenderer, wxGridCellNumberRenderer,
91
wxGridCellStringRenderer
93
class wxGridCellBoolRenderer : public wxGridCellRenderer
99
wxGridCellBoolRenderer();
103
@class wxGridCellDateTimeRenderer
105
This class may be used to format a date/time data in a cell.
106
The class wxDateTime is used internally to display the local date/time
107
or to parse the string date entered in the cell thanks to the defined format.
112
@see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
113
wxGridCellBoolRenderer, wxGridCellEnumRenderer,
114
wxGridCellFloatRenderer, wxGridCellNumberRenderer,
115
wxGridCellStringRenderer
117
class wxGridCellDateTimeRenderer : public wxGridCellStringRenderer
121
Date/time renderer constructor.
124
strptime()-like format string used the parse the output date/time.
126
strptime()-like format string used to parse the string entered in the cell.
128
wxGridCellDateTimeRenderer(const wxString& outformat = wxDefaultDateTimeFormat,
129
const wxString& informat = wxDefaultDateTimeFormat);
133
Sets the strptime()-like format string which will be used to parse
137
strptime()-like format string used to parse the date/time.
139
virtual void SetParameters(const wxString& params);
143
@class wxGridCellEnumRenderer
145
This class may be used to render in a cell a number as a textual
148
The corresponding text strings are specified as comma-separated items in
149
the string passed to this renderer ctor or SetParameters() method. For
150
example, if this string is @c "John,Fred,Bob" the cell will be rendered as
151
"John", "Fred" or "Bob" if its contents is 0, 1 or 2 respectively.
156
@see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
157
wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
158
wxGridCellFloatRenderer, wxGridCellNumberRenderer,
159
wxGridCellStringRenderer
161
class wxGridCellEnumRenderer : public wxGridCellStringRenderer
168
Comma separated string parameters "item1[,item2[...,itemN]]".
170
wxGridCellEnumRenderer( const wxString& choices = wxEmptyString );
173
Sets the comma separated string content of the enum.
176
Comma separated string parameters "item1[,item2[...,itemN]]".
178
virtual void SetParameters(const wxString& params);
182
Specifier used to format the data to string for the numbers handled by
183
wxGridCellFloatRenderer and wxGridCellFloatEditor.
187
enum wxGridCellFloatFormat
189
/// Decimal floating point (%f).
190
wxGRID_FLOAT_FORMAT_FIXED = 0x0010,
192
/// Scientific notation (mantise/exponent) using e character (%e).
193
wxGRID_FLOAT_FORMAT_SCIENTIFIC = 0x0020,
195
/// Use the shorter of %e or %f (%g).
196
wxGRID_FLOAT_FORMAT_COMPACT = 0x0040,
198
/// To use in combination with one of the above formats for the upper
199
/// case version (%F/%E/%G)
200
wxGRID_FLOAT_FORMAT_UPPER = 0x0080,
202
/// The format used by default (wxGRID_FLOAT_FORMAT_FIXED).
203
wxGRID_FLOAT_FORMAT_DEFAULT = wxGRID_FLOAT_FORMAT_FIXED
207
@class wxGridCellFloatRenderer
209
This class may be used to format floating point data in a cell.
214
@see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
215
wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
216
wxGridCellEnumRenderer, wxGridCellNumberRenderer,
217
wxGridCellStringRenderer
219
class wxGridCellFloatRenderer : public wxGridCellStringRenderer
223
Float cell renderer ctor.
226
Minimum number of characters to be shown.
228
Number of digits after the decimal dot.
230
The format used to display the string, must be a combination of
231
::wxGridCellFloatFormat enum elements. This parameter is only
232
available since wxWidgets 2.9.3.
234
wxGridCellFloatRenderer(int width = -1, int precision = -1,
235
int format = wxGRID_FLOAT_FORMAT_DEFAULT);
238
Returns the specifier used to format the data to string.
240
The returned value is a combination of ::wxGridCellFloatFormat elements.
244
int GetFormat() const;
247
Returns the precision.
249
int GetPrecision() const;
254
int GetWidth() const;
257
Set the format to use for display the number.
260
Must be a combination of ::wxGridCellFloatFormat enum elements.
264
void SetFormat(int format);
267
The parameters string format is "width[,precision[,format]]" where
268
@c format should be chosen between f|e|g|E|G (f is used by default)
270
virtual void SetParameters(const wxString& params);
275
void SetPrecision(int precision);
280
void SetWidth(int width);
284
@class wxGridCellNumberRenderer
286
This class may be used to format integer data in a cell.
291
@see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
292
wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
293
wxGridCellEnumRenderer, wxGridCellFloatRenderer,
294
wxGridCellStringRenderer
296
class wxGridCellNumberRenderer : public wxGridCellStringRenderer
302
wxGridCellNumberRenderer();
306
@class wxGridCellStringRenderer
308
This class may be used to format string data in a cell; it is the default
314
@see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
315
wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
316
wxGridCellEnumRenderer, wxGridCellFloatRenderer,
317
wxGridCellNumberRenderer
319
class wxGridCellStringRenderer : public wxGridCellRenderer
325
wxGridCellStringRenderer();
330
@class wxGridCellEditor
332
This class is responsible for providing and manipulating the in-place edit
333
controls for the grid. Instances of wxGridCellEditor (actually, instances
334
of derived classes since it is an abstract class) can be associated with
335
the cell attributes for individual cells, rows, columns, or even for the
341
@see wxGridCellAutoWrapStringEditor, wxGridCellBoolEditor,
342
wxGridCellChoiceEditor, wxGridCellEnumEditor,
343
wxGridCellFloatEditor, wxGridCellNumberEditor,
346
class wxGridCellEditor
355
Fetch the value from the table and prepare the edit control to begin
358
This function should save the original value of the grid cell at the
359
given @a row and @a col and show the control allowing the user to
364
virtual void BeginEdit(int row, int col, wxGrid* grid) = 0;
367
Create a new object which is the copy of this one.
369
virtual wxGridCellEditor* Clone() const = 0;
372
Creates the actual edit control.
374
virtual void Create(wxWindow* parent, wxWindowID id,
375
wxEvtHandler* evtHandler) = 0;
380
virtual void Destroy();
383
End editing the cell.
385
This function must check if the current value of the editing control is
386
valid and different from the original value (available as @a oldval in
387
its string form and possibly saved internally using its real type by
388
BeginEdit()). If it isn't, it just returns @false, otherwise it must do
390
# Save the new value internally so that ApplyEdit() could apply it.
391
# Fill @a newval (which is never @NULL) with the string
392
representation of the new value.
395
Notice that it must @em not modify the grid as the change could still
398
If the user-defined wxEVT_GRID_CELL_CHANGING event handler doesn't veto
399
this change, ApplyEdit() will be called next.
401
virtual bool EndEdit(int row, int col, const wxGrid* grid,
402
const wxString& oldval, wxString* newval) = 0;
405
Effectively save the changes in the grid.
407
This function should save the value of the control in the grid. It is
408
called only after EndEdit() returns @true.
410
virtual void ApplyEdit(int row, int col, wxGrid* grid) = 0;
413
Some types of controls on some platforms may need some help with the
416
virtual void HandleReturn(wxKeyEvent& event);
419
Returns @true if the edit control has been created.
424
Draws the part of the cell not occupied by the control: the base class
425
version just fills it with background colour from the attribute.
427
virtual void PaintBackground(const wxRect& rectCell, wxGridCellAttr* attr);
430
Reset the value in the control back to its starting value.
432
virtual void Reset() = 0;
435
Size and position the edit control.
437
virtual void SetSize(const wxRect& rect);
440
Show or hide the edit control, use the specified attributes to set
441
colours/fonts for it.
443
virtual void Show(bool show, wxGridCellAttr* attr = NULL);
446
If the editor is enabled by clicking on the cell, this method will be
449
virtual void StartingClick();
452
If the editor is enabled by pressing keys on the grid, this will be
453
called to let the editor do something about that first key if desired.
455
virtual void StartingKey(wxKeyEvent& event);
460
The destructor is private because only DecRef() can delete us.
462
virtual ~wxGridCellEditor();
466
@class wxGridCellAutoWrapStringEditor
468
Grid cell editor for wrappable string/text data.
473
@see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor,
474
wxGridCellEnumEditor, wxGridCellFloatEditor,
475
wxGridCellNumberEditor, wxGridCellTextEditor
477
class wxGridCellAutoWrapStringEditor : public wxGridCellTextEditor
480
wxGridCellAutoWrapStringEditor();
484
@class wxGridCellBoolEditor
486
Grid cell editor for boolean data.
491
@see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
492
wxGridCellChoiceEditor, wxGridCellEnumEditor,
493
wxGridCellFloatEditor, wxGridCellNumberEditor,
496
class wxGridCellBoolEditor : public wxGridCellEditor
502
wxGridCellBoolEditor();
505
Returns @true if the given @a value is equal to the string
506
representation of the truth value we currently use (see
509
static bool IsTrueValue(const wxString& value);
512
This method allows you to customize the values returned by GetValue()
513
for the cell using this editor. By default, the default values of the
514
arguments are used, i.e. @c "1" is returned if the cell is checked and
515
an empty string otherwise.
517
static void UseStringValues(const wxString& valueTrue = "1",
518
const wxString& valueFalse = wxEmptyString);
522
@class wxGridCellChoiceEditor
524
Grid cell editor for string data providing the user a choice from a list of
530
@see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
531
wxGridCellBoolEditor, wxGridCellEnumEditor,
532
wxGridCellFloatEditor, wxGridCellNumberEditor,
535
class wxGridCellChoiceEditor : public wxGridCellEditor
539
Choice cell renderer ctor.
542
Number of strings from which the user can choose.
544
An array of strings from which the user can choose.
546
If allowOthers is @true, the user can type a string not in choices
549
wxGridCellChoiceEditor(size_t count = 0,
550
const wxString choices[] = NULL,
551
bool allowOthers = false);
554
Choice cell renderer ctor.
557
An array of strings from which the user can choose.
559
If allowOthers is @true, the user can type a string not in choices
562
wxGridCellChoiceEditor(const wxArrayString& choices,
563
bool allowOthers = false);
566
Parameters string format is "item1[,item2[...,itemN]]"
568
virtual void SetParameters(const wxString& params);
572
@class wxGridCellEnumEditor
574
Grid cell editor which displays an enum number as a textual equivalent
575
(eg. data in cell is 0,1,2 ... n the cell could be displayed as
576
"John","Fred"..."Bob" in the combo choice box).
581
@see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
582
wxGridCellBoolEditor, wxGridCellChoiceEditor,
583
wxGridCellTextEditor, wxGridCellFloatEditor,
584
wxGridCellNumberEditor
586
class wxGridCellEnumEditor : public wxGridCellChoiceEditor
590
Enum cell editor ctor.
593
Comma separated choice parameters "item1[,item2[...,itemN]]".
595
wxGridCellEnumEditor( const wxString& choices = wxEmptyString );
599
@class wxGridCellTextEditor
601
Grid cell editor for string/text data.
606
@see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
607
wxGridCellBoolEditor, wxGridCellChoiceEditor,
608
wxGridCellEnumEditor, wxGridCellFloatEditor,
609
wxGridCellNumberEditor
611
class wxGridCellTextEditor : public wxGridCellEditor
617
wxGridCellTextEditor();
620
The parameters string format is "n" where n is a number representing
623
virtual void SetParameters(const wxString& params);
627
@class wxGridCellFloatEditor
629
The editor for floating point numbers data.
634
@see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
635
wxGridCellBoolEditor, wxGridCellChoiceEditor,
636
wxGridCellEnumEditor, wxGridCellNumberEditor,
639
class wxGridCellFloatEditor : public wxGridCellTextEditor
643
Float cell editor ctor.
646
Minimum number of characters to be shown.
648
Number of digits after the decimal dot.
650
The format to use for displaying the number, a combination of
651
::wxGridCellFloatFormat enum elements. This parameter is only
652
available since wxWidgets 2.9.3.
654
wxGridCellFloatEditor(int width = -1, int precision = -1,
655
int format = wxGRID_FLOAT_FORMAT_DEFAULT);
658
The parameters string format is "width[,precision[,format]]" where
659
@c format should be chosen between f|e|g|E|G (f is used by default)
661
virtual void SetParameters(const wxString& params);
665
@class wxGridCellNumberEditor
667
Grid cell editor for numeric integer data.
672
@see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
673
wxGridCellBoolEditor, wxGridCellChoiceEditor,
674
wxGridCellEnumEditor, wxGridCellFloatEditor,
677
class wxGridCellNumberEditor : public wxGridCellTextEditor
681
Allows you to specify the range for acceptable data. Values equal to
682
-1 for both @a min and @a max indicate that no range checking should be
685
wxGridCellNumberEditor(int min = -1, int max = -1);
689
Parameters string format is "min,max".
691
virtual void SetParameters(const wxString& params);
696
If the return value is @true, the editor uses a wxSpinCtrl to get user
697
input, otherwise it uses a wxTextCtrl.
699
bool HasRange() const;
702
String representation of the value.
704
wxString GetString() const;
710
@class wxGridCellAttr
712
This class can be used to alter the cells' appearance in the grid by
713
changing their attributes from the defaults. An object of this class may be
714
returned by wxGridTableBase::GetAttr().
723
Kind of the attribute to retrieve.
725
@see wxGridCellAttrProvider::GetAttr(), wxGridTableBase::GetAttr()
729
/// Return the combined effective attribute for the cell.
732
/// Return the attribute explicitly set for this cell.
735
/// Return the attribute set for this cells row.
738
/// Return the attribute set for this cells column.
745
wxGridCellAttr(wxGridCellAttr* attrDefault = NULL);
747
Constructor specifying some of the often used attributes.
749
wxGridCellAttr(const wxColour& colText, const wxColour& colBack,
750
const wxFont& font, int hAlign, int vAlign);
753
Creates a new copy of this object.
755
wxGridCellAttr* Clone() const;
758
This class is reference counted: it is created with ref count of 1, so
759
calling DecRef() once will delete it. Calling IncRef() allows to lock
760
it until the matching DecRef() is called.
765
Get the alignment to use for the cell with the given attribute.
767
If this attribute doesn't specify any alignment, the default attribute
768
alignment is used (which can be changed using
769
wxGrid::SetDefaultCellAlignment() but is left and top by default).
771
Notice that @a hAlign and @a vAlign values are always overwritten by
772
this function, use GetNonDefaultAlignment() if this is not desirable.
775
Horizontal alignment is returned here if this argument is non-@NULL.
776
It is one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT.
778
Vertical alignment is returned here if this argument is non-@NULL.
779
It is one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM.
781
void GetAlignment(int* hAlign, int* vAlign) const;
784
Returns the background colour.
786
const wxColour& GetBackgroundColour() const;
789
Returns the cell editor.
791
wxGridCellEditor* GetEditor(const wxGrid* grid, int row, int col) const;
796
const wxFont& GetFont() const;
799
Get the alignment defined by this attribute.
801
Unlike GetAlignment() this function only modifies @a hAlign and @a
802
vAlign if this attribute does define a non-default alignment. This
803
means that they must be initialized before calling this function and
804
that their values will be preserved unchanged if they are different
805
from wxALIGN_INVALID.
807
For example, the following fragment can be used to use the cell
808
alignment if one is defined but right-align its contents by default
809
(instead of left-aligning it by default) while still using the default
812
int hAlign = wxALIGN_RIGHT,
813
vAlign = wxALIGN_INVALID;
814
attr.GetNonDefaultAlignment(&hAlign, &vAlign);
819
void GetNonDefaultAlignment(int *hAlign, int *vAlign) const;
822
Returns the cell renderer.
824
wxGridCellRenderer* GetRenderer(const wxGrid* grid, int row, int col) const;
827
Returns the text colour.
829
const wxColour& GetTextColour() const;
832
Returns @true if this attribute has a valid alignment set.
834
bool HasAlignment() const;
837
Returns @true if this attribute has a valid background colour set.
839
bool HasBackgroundColour() const;
842
Returns @true if this attribute has a valid cell editor set.
844
bool HasEditor() const;
847
Returns @true if this attribute has a valid font set.
849
bool HasFont() const;
852
Returns @true if this attribute has a valid cell renderer set.
854
bool HasRenderer() const;
857
Returns @true if this attribute has a valid text colour set.
859
bool HasTextColour() const;
862
This class is reference counted: it is created with ref count of 1, so
863
calling DecRef() once will delete it. Calling IncRef() allows to lock
864
it until the matching DecRef() is called.
869
Returns @true if this cell is set as read-only.
871
bool IsReadOnly() const;
874
Sets the alignment. @a hAlign can be one of @c wxALIGN_LEFT,
875
@c wxALIGN_CENTRE or @c wxALIGN_RIGHT and @a vAlign can be one of
876
@c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
878
void SetAlignment(int hAlign, int vAlign);
881
Sets the background colour.
883
void SetBackgroundColour(const wxColour& colBack);
886
@todo Needs documentation.
888
void SetDefAttr(wxGridCellAttr* defAttr);
891
Sets the editor to be used with the cells with this attribute.
893
void SetEditor(wxGridCellEditor* editor);
898
void SetFont(const wxFont& font);
901
Sets the cell as read-only.
903
void SetReadOnly(bool isReadOnly = true);
906
Sets the renderer to be used for cells with this attribute. Takes
907
ownership of the pointer.
909
void SetRenderer(wxGridCellRenderer* renderer);
912
Sets the text colour.
914
void SetTextColour(const wxColour& colText);
918
Base class for corner window renderer.
920
This is the simplest of all header renderers and only has a single
923
@see wxGridCellAttrProvider::GetCornerRenderer()
927
class wxGridCornerHeaderRenderer
931
Called by the grid to draw the corner window border.
933
This method is responsible for drawing the border inside the given @a
934
rect and adjusting the rectangle size to correspond to the area inside
935
the border, i.e. usually call wxRect::Deflate() to account for the
939
The grid whose corner window is being drawn.
941
The device context to use for drawing.
943
Input/output parameter which contains the border rectangle on input
944
and should be updated to contain the area inside the border on
947
virtual void DrawBorder(const wxGrid& grid,
949
wxRect& rect) const = 0;
952
Common base class for row and column headers renderers.
954
@see wxGridColumnHeaderRenderer, wxGridRowHeaderRenderer
958
class wxGridHeaderLabelsRenderer : public wxGridCornerHeaderRenderer
962
Called by the grid to draw the specified label.
964
Notice that the base class DrawBorder() method is called before this
967
The default implementation uses wxGrid::GetLabelTextColour() and
968
wxGrid::GetLabelFont() to draw the label.
970
virtual void DrawLabel(const wxGrid& grid,
972
const wxString& value,
976
int textOrientation) const;
980
Base class for row headers renderer.
982
This is the same as wxGridHeaderLabelsRenderer currently but we still use a
983
separate class for it to distinguish it from wxGridColumnHeaderRenderer.
985
@see wxGridRowHeaderRendererDefault
987
@see wxGridCellAttrProvider::GetRowHeaderRenderer()
991
class wxGridRowHeaderRenderer : public wxGridHeaderLabelsRenderer
996
Base class for column headers renderer.
998
This is the same as wxGridHeaderLabelsRenderer currently but we still use a
999
separate class for it to distinguish it from wxGridRowHeaderRenderer.
1001
@see wxGridColumnHeaderRendererDefault
1003
@see wxGridCellAttrProvider::GetColumnHeaderRenderer()
1007
class wxGridColumnHeaderRenderer : public wxGridHeaderLabelsRenderer
1012
Default row header renderer.
1014
You may derive from this class if you need to only override one of its
1015
methods (i.e. either DrawLabel() or DrawBorder()) but continue to use the
1016
default implementation for the other one.
1018
@see wxGridColumnHeaderRendererDefault
1022
class wxGridRowHeaderRendererDefault : public wxGridRowHeaderRenderer
1025
/// Implement border drawing for the row labels.
1026
virtual void DrawBorder(const wxGrid& grid,
1028
wxRect& rect) const;
1032
Default column header renderer.
1034
@see wxGridRowHeaderRendererDefault
1038
class wxGridColumnHeaderRendererDefault : public wxGridColumnHeaderRenderer
1041
/// Implement border drawing for the column labels.
1042
virtual void DrawBorder(const wxGrid& grid,
1044
wxRect& rect) const;
1048
Default corner window renderer.
1050
@see wxGridColumnHeaderRendererDefault, wxGridRowHeaderRendererDefault
1054
class wxGridCornerHeaderRendererDefault : public wxGridCornerHeaderRenderer
1057
/// Implement border drawing for the corner window.
1058
virtual void DrawBorder(const wxGrid& grid,
1060
wxRect& rect) const;
1064
Class providing attributes to be used for the grid cells.
1066
This class both defines an interface which grid cell attributes providers
1067
should implement -- and which can be implemented differently in derived
1068
classes -- and a default implementation of this interface which is often
1069
good enough to be used without modification, especially with not very large
1070
grids for which the efficiency of attributes storage hardly matters (see
1071
the discussion below).
1073
An object of this class can be associated with a wxGrid using
1074
wxGridTableBase::SetAttrProvider() but it's not necessary to call it if you
1075
intend to use the default provider as it is used by wxGridTableBase by
1078
Notice that while attributes provided by this class can be set for
1079
individual cells using SetAttr() or the entire rows or columns using
1080
SetRowAttr() and SetColAttr() they are always retrieved using GetAttr()
1084
The default implementation of this class stores the attributes passed to
1085
its SetAttr(), SetRowAttr() and SetColAttr() in a straightforward way. A
1086
derived class may use its knowledge about how the attributes are used in
1087
your program to implement it much more efficiently: for example, using a
1088
special background colour for all even-numbered rows can be implemented by
1089
simply returning the same attribute from GetAttr() if the row number is
1090
even instead of having to store N/2 row attributes where N is the total
1091
number of rows in the grid.
1093
Notice that objects of this class can't be copied.
1095
class wxGridCellAttrProvider : public wxClientDataContainer
1098
/// Trivial default constructor.
1099
wxGridCellAttrProvider();
1101
/// Destructor releases any attributes held by this class.
1102
virtual ~wxGridCellAttrProvider();
1105
Get the attribute to use for the specified cell.
1107
If wxGridCellAttr::Any is used as @a kind value, this function combines
1108
the attributes set for this cell using SetAttr() and those for its row
1109
or column (set with SetRowAttr() or SetColAttr() respectively), with
1110
the cell attribute having the highest precedence.
1112
Notice that the caller must call DecRef() on the returned pointer if it
1116
The row of the cell.
1118
The column of the cell.
1120
The kind of the attribute to return.
1122
The attribute to use which should be DecRef()'d by caller or @NULL
1123
if no attributes are defined for this cell.
1125
virtual wxGridCellAttr *GetAttr(int row, int col,
1126
wxGridCellAttr::wxAttrKind kind) const;
1131
All these functions take ownership of the attribute passed to them,
1132
i.e. will call DecRef() on it themselves later and so it should not be
1133
destroyed by the caller. And the attribute can be @NULL to reset a
1134
previously set value.
1138
/// Set attribute for the specified cell.
1139
virtual void SetAttr(wxGridCellAttr *attr, int row, int col);
1141
/// Set attribute for the specified row.
1142
virtual void SetRowAttr(wxGridCellAttr *attr, int row);
1144
/// Set attribute for the specified column.
1145
virtual void SetColAttr(wxGridCellAttr *attr, int col);
1150
Getting header renderers.
1152
These functions return the renderers for the given row or column header
1153
label and the corner window. Unlike cell attributes, these objects are
1154
not reference counted and are never @NULL so they are returned by
1155
reference and not pointer and DecRef() shouldn't (and can't) be called
1158
All these functions were added in wxWidgets 2.9.1.
1163
Return the renderer used for drawing column headers.
1165
By default wxGridColumnHeaderRendererDefault is returned.
1167
@see wxGrid::SetUseNativeColLabels(), wxGrid::UseNativeColHeader()
1171
virtual const wxGridColumnHeaderRenderer& GetColumnHeaderRenderer(int col);
1174
Return the renderer used for drawing row headers.
1176
By default wxGridRowHeaderRendererDefault is returned.
1180
virtual const wxGridRowHeaderRenderer& GetRowHeaderRenderer(int row);
1183
Return the renderer used for drawing the corner window.
1185
By default wxGridCornerHeaderRendererDefault is returned.
1189
virtual const wxGridCornerHeaderRenderer& GetCornerRenderer();
1195
Represents coordinates of a grid cell.
1197
An object of this class is simply a (row, column) pair.
1199
class wxGridCellCoords
1203
Default constructor initializes the object to invalid state.
1205
Initially the row and column are both invalid (-1) and so operator!()
1206
for an uninitialized wxGridCellCoords returns false.
1211
Constructor taking a row and a column.
1213
wxGridCellCoords(int row, int col);
1216
Return the row of the coordinate.
1221
Set the row of the coordinate.
1226
Return the column of the coordinate.
1231
Set the column of the coordinate.
1236
Set the row and column of the coordinate.
1238
void Set(int row, int col);
1241
Assignment operator for coordinate types.
1243
wxGridCellCoords& operator=(const wxGridCellCoords& other);
1248
bool operator==(const wxGridCellCoords& other) const;
1251
Inequality operator.
1253
bool operator!=(const wxGridCellCoords& other) const;
1256
Checks whether the coordinates are invalid.
1258
Returns false only if both row and column are -1. Notice that if either
1259
row or column (but not both) are -1, this method returns true even if
1260
the object is invalid. This is done because objects in such state
1261
should actually never exist, i.e. either both coordinates should be -1
1262
or none of them should be -1.
1264
bool operator!() const;
1268
@class wxGridTableBase
1270
The almost abstract base class for grid tables.
1272
A grid table is responsible for storing the grid data and, indirectly, grid
1273
cell attributes. The data can be stored in the way most convenient for the
1274
application but has to be provided in string form to wxGrid. It is also
1275
possible to provide cells values in other formats if appropriate, e.g. as
1278
This base class is not quite abstract as it implements a trivial strategy
1279
for storing the attributes by forwarding it to wxGridCellAttrProvider and
1280
also provides stubs for some other functions. However it does have a number
1281
of pure virtual methods which must be implemented in the derived classes.
1283
@see wxGridStringTable
1288
class wxGridTableBase : public wxObject
1292
Default constructor.
1297
Destructor frees the attribute provider if it was created.
1299
virtual ~wxGridTableBase();
1302
Must be overridden to return the number of rows in the table.
1304
For backwards compatibility reasons, this method is not const.
1305
Use GetRowsCount() instead of it in const methods of derived table
1308
virtual int GetNumberRows() = 0;
1311
Must be overridden to return the number of columns in the table.
1313
For backwards compatibility reasons, this method is not const.
1314
Use GetColsCount() instead of it in const methods of derived table
1317
virtual int GetNumberCols() = 0;
1320
Return the number of rows in the table.
1322
This method is not virtual and is only provided as a convenience for
1323
the derived classes which can't call GetNumberRows() without a
1324
@c const_cast from their const methods.
1326
int GetRowsCount() const;
1329
Return the number of columns in the table.
1331
This method is not virtual and is only provided as a convenience for
1332
the derived classes which can't call GetNumberCols() without a
1333
@c const_cast from their const methods.
1335
int GetColsCount() const;
1339
@name Table Cell Accessors
1344
May be overridden to implement testing for empty cells.
1346
This method is used by the grid to test if the given cell is not used
1347
and so whether a neighbouring cell may overflow into it. By default it
1348
only returns true if the value of the given cell, as returned by
1349
GetValue(), is empty.
1351
virtual bool IsEmptyCell(int row, int col);
1354
Same as IsEmptyCell() but taking wxGridCellCoords.
1356
Notice that this method is not virtual, only IsEmptyCell() should be
1359
bool IsEmpty(const wxGridCellCoords& coords);
1362
Must be overridden to implement accessing the table values as text.
1364
virtual wxString GetValue(int row, int col) = 0;
1367
Must be overridden to implement setting the table values as text.
1369
virtual void SetValue(int row, int col, const wxString& value) = 0;
1372
Returns the type of the value in the given cell.
1374
By default all cells are strings and this method returns
1375
@c wxGRID_VALUE_STRING.
1377
virtual wxString GetTypeName(int row, int col);
1380
Returns true if the value of the given cell can be accessed as if it
1381
were of the specified type.
1383
By default the cells can only be accessed as strings. Note that a cell
1384
could be accessible in different ways, e.g. a numeric cell may return
1385
@true for @c wxGRID_VALUE_NUMBER but also for @c wxGRID_VALUE_STRING
1386
indicating that the value can be coerced to a string form.
1388
virtual bool CanGetValueAs(int row, int col, const wxString& typeName);
1391
Returns true if the value of the given cell can be set as if it were of
1394
@see CanGetValueAs()
1396
virtual bool CanSetValueAs(int row, int col, const wxString& typeName);
1399
Returns the value of the given cell as a long.
1401
This should only be called if CanGetValueAs() returns @true when called
1402
with @c wxGRID_VALUE_NUMBER argument. Default implementation always
1405
virtual long GetValueAsLong(int row, int col);
1408
Returns the value of the given cell as a double.
1410
This should only be called if CanGetValueAs() returns @true when called
1411
with @c wxGRID_VALUE_FLOAT argument. Default implementation always
1414
virtual double GetValueAsDouble(int row, int col);
1417
Returns the value of the given cell as a boolean.
1419
This should only be called if CanGetValueAs() returns @true when called
1420
with @c wxGRID_VALUE_BOOL argument. Default implementation always
1423
virtual bool GetValueAsBool(int row, int col);
1426
Returns the value of the given cell as a user-defined type.
1428
This should only be called if CanGetValueAs() returns @true when called
1429
with @a typeName. Default implementation always return @NULL.
1431
virtual void *GetValueAsCustom(int row, int col, const wxString& typeName);
1434
Sets the value of the given cell as a long.
1436
This should only be called if CanSetValueAs() returns @true when called
1437
with @c wxGRID_VALUE_NUMBER argument. Default implementation doesn't do
1440
virtual void SetValueAsLong(int row, int col, long value);
1443
Sets the value of the given cell as a double.
1445
This should only be called if CanSetValueAs() returns @true when called
1446
with @c wxGRID_VALUE_FLOAT argument. Default implementation doesn't do
1449
virtual void SetValueAsDouble(int row, int col, double value);
1452
Sets the value of the given cell as a boolean.
1454
This should only be called if CanSetValueAs() returns @true when called
1455
with @c wxGRID_VALUE_BOOL argument. Default implementation doesn't do
1458
virtual void SetValueAsBool( int row, int col, bool value );
1461
Sets the value of the given cell as a user-defined type.
1463
This should only be called if CanSetValueAs() returns @true when called
1464
with @a typeName. Default implementation doesn't do anything.
1466
virtual void SetValueAsCustom(int row, int col, const wxString& typeName,
1473
Called by the grid when the table is associated with it.
1475
The default implementation stores the pointer and returns it from its
1476
GetView() and so only makes sense if the table cannot be associated
1477
with more than one grid at a time.
1479
virtual void SetView(wxGrid *grid);
1482
Returns the last grid passed to SetView().
1484
virtual wxGrid *GetView() const;
1488
@name Table Structure Modifiers
1490
Notice that none of these functions are pure virtual as they don't have
1491
to be implemented if the table structure is never modified after
1492
creation, i.e. neither rows nor columns are never added or deleted but
1493
that you do need to implement them if they are called, i.e. if your
1494
code either calls them directly or uses the matching wxGrid methods, as
1495
by default they simply do nothing which is definitely inappropriate.
1500
Clear the table contents.
1502
This method is used by wxGrid::ClearGrid().
1504
virtual void Clear();
1507
Insert additional rows into the table.
1510
The position of the first new row.
1512
The number of rows to insert.
1514
virtual bool InsertRows(size_t pos = 0, size_t numRows = 1);
1517
Append additional rows at the end of the table.
1519
This method is provided in addition to InsertRows() as some data models
1520
may only support appending rows to them but not inserting them at
1521
arbitrary locations. In such case you may implement this method only
1522
and leave InsertRows() unimplemented.
1525
The number of rows to add.
1527
virtual bool AppendRows(size_t numRows = 1);
1530
Delete rows from the table.
1532
Notice that currently deleting a row intersecting a multi-cell (see
1533
SetCellSize()) is not supported and will result in a crash.
1536
The first row to delete.
1538
The number of rows to delete.
1540
virtual bool DeleteRows(size_t pos = 0, size_t numRows = 1);
1543
Exactly the same as InsertRows() but for columns.
1545
virtual bool InsertCols(size_t pos = 0, size_t numCols = 1);
1548
Exactly the same as AppendRows() but for columns.
1550
virtual bool AppendCols(size_t numCols = 1);
1553
Exactly the same as DeleteRows() but for columns.
1555
virtual bool DeleteCols(size_t pos = 0, size_t numCols = 1);
1560
@name Table Row and Column Labels
1562
By default the numbers are used for labeling rows and Latin letters for
1563
labeling columns. If the table has more than 26 columns, the pairs of
1564
letters are used starting from the 27-th one and so on, i.e. the
1565
sequence of labels is A, B, ..., Z, AA, AB, ..., AZ, BA, ..., ..., ZZ,
1571
Return the label of the specified row.
1573
virtual wxString GetRowLabelValue(int row);
1576
Return the label of the specified column.
1578
virtual wxString GetColLabelValue(int col);
1581
Set the given label for the specified row.
1583
The default version does nothing, i.e. the label is not stored. You
1584
must override this method in your derived class if you wish
1585
wxGrid::SetRowLabelValue() to work.
1587
virtual void SetRowLabelValue(int row, const wxString& label);
1590
Exactly the same as SetRowLabelValue() but for columns.
1592
virtual void SetColLabelValue(int col, const wxString& label);
1598
@name Attributes Management
1600
By default the attributes management is delegated to
1601
wxGridCellAttrProvider class. You may override the methods in this
1602
section to handle the attributes directly if, for example, they can be
1603
computed from the cell values.
1608
Associate this attributes provider with the table.
1610
The table takes ownership of @a attrProvider pointer and will delete it
1611
when it doesn't need it any more. The pointer can be @NULL, however
1612
this won't disable attributes management in the table but will just
1613
result in a default attributes being recreated the next time any of the
1614
other functions in this section is called. To completely disable the
1615
attributes support, should this be needed, you need to override
1616
CanHaveAttributes() to return @false.
1618
void SetAttrProvider(wxGridCellAttrProvider *attrProvider);
1621
Returns the attribute provider currently being used.
1623
This function may return @NULL if the attribute provider hasn't been
1624
neither associated with this table by SetAttrProvider() nor created on
1625
demand by any other methods.
1627
wxGridCellAttrProvider *GetAttrProvider() const;
1630
Return the attribute for the given cell.
1632
By default this function is simply forwarded to
1633
wxGridCellAttrProvider::GetAttr() but it may be overridden to handle
1634
attributes directly in the table.
1636
virtual wxGridCellAttr *GetAttr(int row, int col,
1637
wxGridCellAttr::wxAttrKind kind);
1640
Set attribute of the specified cell.
1642
By default this function is simply forwarded to
1643
wxGridCellAttrProvider::SetAttr().
1645
The table takes ownership of @a attr, i.e. will call DecRef() on it.
1647
virtual void SetAttr(wxGridCellAttr* attr, int row, int col);
1650
Set attribute of the specified row.
1652
By default this function is simply forwarded to
1653
wxGridCellAttrProvider::SetRowAttr().
1655
The table takes ownership of @a attr, i.e. will call DecRef() on it.
1657
virtual void SetRowAttr(wxGridCellAttr *attr, int row);
1660
Set attribute of the specified column.
1662
By default this function is simply forwarded to
1663
wxGridCellAttrProvider::SetColAttr().
1665
The table takes ownership of @a attr, i.e. will call DecRef() on it.
1667
virtual void SetColAttr(wxGridCellAttr *attr, int col);
1672
Returns true if this table supports attributes or false otherwise.
1674
By default, the table automatically creates a wxGridCellAttrProvider
1675
when this function is called if it had no attribute provider before and
1678
virtual bool CanHaveAttributes();
1682
@class wxGridSizesInfo
1684
wxGridSizesInfo stores information about sizes of all wxGrid rows or
1687
It assumes that most of the rows or columns (which are both called elements
1688
here as the difference between them doesn't matter at this class level)
1689
have the default size and so stores it separately. And it uses a wxHashMap
1690
to store the sizes of all elements which have the non-default size.
1692
This structure is particularly useful for serializing the sizes of all
1693
wxGrid elements at once.
1698
struct wxGridSizesInfo
1701
Default constructor.
1703
m_sizeDefault and m_customSizes must be initialized later.
1710
This constructor is used by wxGrid::GetRowSizes() and GetColSizes()
1711
methods. User code will usually use the default constructor instead.
1714
The default element size.
1716
Array containing the sizes of @em all elements, including those
1717
which have the default size.
1719
wxGridSizesInfo(int defSize, const wxArrayInt& allSizes);
1722
Get the element size.
1725
The index of the element.
1727
The size for this element, using m_customSizes if @a pos is in it
1728
or m_sizeDefault otherwise.
1730
int GetSize(unsigned pos) const;
1737
Map with element indices as keys and their sizes as values.
1739
This map only contains the elements with non-default size.
1741
wxUnsignedToIntHashMap m_customSizes;
1748
wxGrid and its related classes are used for displaying and editing tabular
1749
data. They provide a rich set of features for display, editing, and
1750
interacting with a variety of data sources. For simple applications, and to
1751
help you get started, wxGrid is the only class you need to refer to
1752
directly. It will set up default instances of the other classes and manage
1753
them for you. For more complex applications you can derive your own classes
1754
for custom grid views, grid data tables, cell editors and renderers. The
1755
@ref overview_grid has examples of simple and more complex applications,
1756
explains the relationship between the various grid classes and has a
1757
summary of the keyboard shortcuts and mouse functions provided by wxGrid.
1759
A wxGridTableBase class holds the actual data to be displayed by a wxGrid
1760
class. One or more wxGrid classes may act as a view for one table class.
1761
The default table class is called wxGridStringTable and holds an array of
1762
strings. An instance of such a class is created by CreateGrid().
1764
wxGridCellRenderer is the abstract base class for rendering contents in a
1765
cell. The following renderers are predefined:
1767
- wxGridCellBoolRenderer
1768
- wxGridCellFloatRenderer
1769
- wxGridCellNumberRenderer
1770
- wxGridCellStringRenderer
1772
The look of a cell can be further defined using wxGridCellAttr. An object
1773
of this type may be returned by wxGridTableBase::GetAttr().
1775
wxGridCellEditor is the abstract base class for editing the value of a
1776
cell. The following editors are predefined:
1778
- wxGridCellBoolEditor
1779
- wxGridCellChoiceEditor
1780
- wxGridCellFloatEditor
1781
- wxGridCellNumberEditor
1782
- wxGridCellTextEditor
1784
Please see wxGridEvent, wxGridSizeEvent, wxGridRangeSelectEvent, and
1785
wxGridEditorCreatedEvent for the documentation of all event types you can
1791
@see @ref overview_grid, wxGridUpdateLocker
1793
class wxGrid : public wxScrolledWindow
1798
Different selection modes supported by the grid.
1800
enum wxGridSelectionModes
1803
The default selection mode allowing selection of the individual
1804
cells as well as of the entire rows and columns.
1809
The selection mode allowing the selection of the entire rows only.
1811
The user won't be able to select any cells or columns in this mode.
1816
The selection mode allowing the selection of the entire columns only.
1818
The user won't be able to select any cells or rows in this mode.
1820
wxGridSelectColumns,
1823
The selection mode allowing the user to select either the entire
1824
columns or the entire rows but not individual cells nor blocks.
1826
Notice that while this constant is defined as @code
1827
wxGridSelectColumns | wxGridSelectRows @endcode this doesn't mean
1828
that all the other combinations are valid -- at least currently
1833
wxGridSelectRowsOrColumns
1837
Return values for GetCellSize().
1843
/// This cell is inside a span covered by another cell.
1844
CellSpan_Inside = -1,
1846
/// This is a normal, non-spanning cell.
1849
/// This cell spans several physical wxGrid cells.
1854
Rendering styles supported by wxGrid::Render() method.
1858
enum wxGridRenderStyle
1860
/// Draw grid row header labels.
1861
wxGRID_DRAW_ROWS_HEADER = 0x001,
1863
/// Draw grid column header labels.
1864
wxGRID_DRAW_COLS_HEADER = 0x002,
1866
/// Draw grid cell border lines.
1867
wxGRID_DRAW_CELL_LINES = 0x004,
1870
Draw a bounding rectangle around the rendered cell area.
1872
Useful where row or column headers are not drawn or where there is
1873
multi row or column cell clipping and therefore no cell border at
1874
the rendered outer boundary.
1876
wxGRID_DRAW_BOX_RECT = 0x008,
1879
Draw the grid cell selection highlight if a selection is present.
1881
At present the highlight colour drawn depends on whether the grid
1882
window loses focus before drawing begins.
1884
wxGRID_DRAW_SELECTION = 0x010,
1887
The default render style.
1889
Includes all except wxGRID_DRAW_SELECTION.
1891
wxGRID_DRAW_DEFAULT = wxGRID_DRAW_ROWS_HEADER |
1892
wxGRID_DRAW_COLS_HEADER |
1893
wxGRID_DRAW_CELL_LINES |
1894
wxGRID_DRAW_BOX_RECT
1898
@name Constructors and Initialization
1903
Default constructor.
1905
You must call Create() to really create the grid window and also call
1906
CreateGrid() or SetTable() to initialize the grid contents.
1910
Constructor creating the grid window.
1912
You must call either CreateGrid() or SetTable() to initialize the grid
1913
contents before using it.
1915
wxGrid(wxWindow* parent, wxWindowID id,
1916
const wxPoint& pos = wxDefaultPosition,
1917
const wxSize& size = wxDefaultSize,
1918
long style = wxWANTS_CHARS,
1919
const wxString& name = wxGridNameStr);
1924
This will also destroy the associated grid table unless you passed a
1925
table object to the grid and specified that the grid should not take
1926
ownership of the table (see SetTable()).
1931
Creates the grid window for an object initialized using the default
1934
You must call either CreateGrid() or SetTable() to initialize the grid
1935
contents before using it.
1937
bool Create(wxWindow* parent, wxWindowID id,
1938
const wxPoint& pos = wxDefaultPosition,
1939
const wxSize& size = wxDefaultSize,
1940
long style = wxWANTS_CHARS,
1941
const wxString& name = wxGridNameStr);
1944
Creates a grid with the specified initial number of rows and columns.
1946
Call this directly after the grid constructor. When you use this
1947
function wxGrid will create and manage a simple table of string values
1948
for you. All of the grid data will be stored in memory.
1950
For applications with more complex data types or relationships, or for
1951
dealing with very large datasets, you should derive your own grid table
1952
class and pass a table object to the grid with SetTable().
1954
bool CreateGrid(int numRows, int numCols,
1955
wxGridSelectionModes selmode = wxGridSelectCells);
1958
Passes a pointer to a custom grid table to be used by the grid.
1960
This should be called after the grid constructor and before using the
1961
grid object. If @a takeOwnership is set to @true then the table will be
1962
deleted by the wxGrid destructor.
1964
Use this function instead of CreateGrid() when your application
1965
involves complex or non-string data or data sets that are too large to
1966
fit wholly in memory.
1968
bool SetTable(wxGridTableBase* table, bool takeOwnership = false,
1969
wxGridSelectionModes selmode = wxGridSelectCells);
1975
@name Grid Line Formatting
1980
Turns the drawing of grid lines on or off.
1982
void EnableGridLines(bool enable = true);
1985
Returns the pen used for vertical grid lines.
1987
This virtual function may be overridden in derived classes in order to
1988
change the appearance of individual grid lines for the given column
1991
See GetRowGridLinePen() for an example.
1993
virtual wxPen GetColGridLinePen(int col);
1996
Returns the pen used for grid lines.
1998
This virtual function may be overridden in derived classes in order to
1999
change the appearance of grid lines. Note that currently the pen width
2002
@see GetColGridLinePen(), GetRowGridLinePen()
2004
virtual wxPen GetDefaultGridLinePen();
2007
Returns the colour used for grid lines.
2009
@see GetDefaultGridLinePen()
2011
wxColour GetGridLineColour() const;
2014
Returns the pen used for horizontal grid lines.
2016
This virtual function may be overridden in derived classes in order to
2017
change the appearance of individual grid line for the given @a row.
2021
// in a grid displaying music notation, use a solid black pen between
2022
// octaves (C0=row 127, C1=row 115 etc.)
2023
wxPen MidiGrid::GetRowGridLinePen(int row)
2025
if ( row % 12 == 7 )
2026
return wxPen(*wxBLACK, 1, wxSOLID);
2028
return GetDefaultGridLinePen();
2032
virtual wxPen GetRowGridLinePen(int row);
2035
Returns @true if drawing of grid lines is turned on, @false otherwise.
2037
bool GridLinesEnabled() const;
2040
Sets the colour used to draw grid lines.
2042
void SetGridLineColour(const wxColour& colour);
2048
@name Label Values and Formatting
2053
Sets the arguments to the current column label alignment values.
2055
Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2056
or @c wxALIGN_RIGHT.
2058
Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2061
void GetColLabelAlignment(int* horiz, int* vert) const;
2064
Returns the orientation of the column labels (either @c wxHORIZONTAL or
2067
int GetColLabelTextOrientation() const;
2070
Returns the specified column label.
2072
The default grid table class provides column labels of the form
2073
A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can
2074
override wxGridTableBase::GetColLabelValue() to provide your own
2077
wxString GetColLabelValue(int col) const;
2080
Returns the colour used for the background of row and column labels.
2082
wxColour GetLabelBackgroundColour() const;
2085
Returns the font used for row and column labels.
2087
wxFont GetLabelFont() const;
2090
Returns the colour used for row and column label text.
2092
wxColour GetLabelTextColour() const;
2095
Returns the alignment used for row labels.
2097
Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2098
or @c wxALIGN_RIGHT.
2100
Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2103
void GetRowLabelAlignment(int* horiz, int* vert) const;
2106
Returns the specified row label.
2108
The default grid table class provides numeric row labels. If you are
2109
using a custom grid table you can override
2110
wxGridTableBase::GetRowLabelValue() to provide your own labels.
2112
wxString GetRowLabelValue(int row) const;
2115
Hides the column labels by calling SetColLabelSize() with a size of 0.
2116
Show labels again by calling that method with a width greater than 0.
2118
void HideColLabels();
2121
Hides the row labels by calling SetRowLabelSize() with a size of 0.
2123
The labels can be shown again by calling SetRowLabelSize() with a width
2126
void HideRowLabels();
2129
Sets the horizontal and vertical alignment of column label text.
2131
Horizontal alignment should be one of @c wxALIGN_LEFT,
2132
@c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
2133
of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
2135
void SetColLabelAlignment(int horiz, int vert);
2138
Sets the orientation of the column labels (either @c wxHORIZONTAL or
2141
void SetColLabelTextOrientation(int textOrientation);
2144
Set the value for the given column label.
2146
If you are using a custom grid table you must override
2147
wxGridTableBase::SetColLabelValue() for this to have any effect.
2149
void SetColLabelValue(int col, const wxString& value);
2152
Sets the background colour for row and column labels.
2154
void SetLabelBackgroundColour(const wxColour& colour);
2157
Sets the font for row and column labels.
2159
void SetLabelFont(const wxFont& font);
2162
Sets the colour for row and column label text.
2164
void SetLabelTextColour(const wxColour& colour);
2167
Sets the horizontal and vertical alignment of row label text.
2169
Horizontal alignment should be one of @c wxALIGN_LEFT,
2170
@c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
2171
of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
2173
void SetRowLabelAlignment(int horiz, int vert);
2176
Sets the value for the given row label.
2178
If you are using a derived grid table you must override
2179
wxGridTableBase::SetRowLabelValue() for this to have any effect.
2181
void SetRowLabelValue(int row, const wxString& value);
2184
Call this in order to make the column labels use a native look by using
2185
wxRendererNative::DrawHeaderButton() internally.
2187
There is no equivalent method for drawing row columns as there is not
2188
native look for that. This option is useful when using wxGrid for
2189
displaying tables and not as a spread-sheet.
2191
@see UseNativeColHeader()
2193
void SetUseNativeColLabels(bool native = true);
2196
Enable the use of native header window for column labels.
2198
If this function is called with @true argument, a wxHeaderCtrl is used
2199
instead to display the column labels instead of drawing them in wxGrid
2200
code itself. This has the advantage of making the grid look and feel
2201
perfectly the same as native applications (using SetUseNativeColLabels()
2202
the grid can be made to look more natively but it still doesn't feel
2203
natively, notably the column resizing and dragging still works slightly
2204
differently as it is implemented in wxWidgets itself) but results in
2205
different behaviour for column and row headers, for which there is no
2206
equivalent function, and, most importantly, is unsuitable for grids
2207
with huge numbers of columns as wxHeaderCtrl doesn't support virtual
2208
mode. Because of this, by default the grid does not use the native
2209
header control but you should call this function to enable it if you
2210
are using the grid to display tabular data and don't have thousands of
2213
Another difference between the default behaviour and the native header
2214
behaviour is that the latter provides the user with a context menu
2215
(which appears on right clicking the header) allowing to rearrange the
2216
grid columns if CanDragColMove() returns @true. If you want to prevent
2217
this from happening for some reason, you need to define a handler for
2218
@c wxEVT_GRID_LABEL_RIGHT_CLICK event which simply does nothing (in
2219
particular doesn't skip the event) as this will prevent the default
2220
right click handling from working.
2222
Also note that currently @c wxEVT_GRID_LABEL_RIGHT_DCLICK event is not
2223
generated for the column labels if the native columns header is used
2224
(but this limitation could possibly be lifted in the future).
2226
void UseNativeColHeader(bool native = true);
2232
@name Cell Formatting
2234
Note that wxGridCellAttr can be used alternatively to most of these
2235
methods. See the "Attributes Management" of wxGridTableBase.
2240
Sets the arguments to the horizontal and vertical text alignment values
2241
for the grid cell at the specified location.
2243
Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2244
or @c wxALIGN_RIGHT.
2246
Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2249
void GetCellAlignment(int row, int col, int* horiz, int* vert) const;
2252
Returns the background colour of the cell at the specified location.
2254
wxColour GetCellBackgroundColour(int row, int col) const;
2257
Returns the font for text in the grid cell at the specified location.
2259
wxFont GetCellFont(int row, int col) const;
2262
Returns the text colour for the grid cell at the specified location.
2264
wxColour GetCellTextColour(int row, int col) const;
2267
Returns the default cell alignment.
2269
Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2270
or @c wxALIGN_RIGHT.
2272
Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2275
@see SetDefaultCellAlignment()
2277
void GetDefaultCellAlignment(int* horiz, int* vert) const;
2280
Returns the current default background colour for grid cells.
2282
wxColour GetDefaultCellBackgroundColour() const;
2285
Returns the current default font for grid cell text.
2287
wxFont GetDefaultCellFont() const;
2290
Returns the current default colour for grid cell text.
2292
wxColour GetDefaultCellTextColour() const;
2295
Sets the horizontal and vertical alignment for grid cell text at the
2298
Horizontal alignment should be one of @c wxALIGN_LEFT,
2299
@c wxALIGN_CENTRE or @c wxALIGN_RIGHT.
2301
Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
2302
or @c wxALIGN_BOTTOM.
2304
void SetCellAlignment(int row, int col, int horiz, int vert);
2306
Sets the horizontal and vertical alignment for grid cell text at the
2309
Horizontal alignment should be one of @c wxALIGN_LEFT,
2310
@c wxALIGN_CENTRE or @c wxALIGN_RIGHT.
2312
Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
2313
or @c wxALIGN_BOTTOM.
2315
void SetCellAlignment(int align, int row, int col);
2318
Set the background colour for the given cell or all cells by default.
2320
void SetCellBackgroundColour(int row, int col, const wxColour& colour);
2323
Sets the font for text in the grid cell at the specified location.
2325
void SetCellFont(int row, int col, const wxFont& font);
2328
Sets the text colour for the given cell.
2330
void SetCellTextColour(int row, int col, const wxColour& colour);
2332
Sets the text colour for the given cell.
2334
void SetCellTextColour(const wxColour& val, int row, int col);
2336
Sets the text colour for all cells by default.
2338
void SetCellTextColour(const wxColour& colour);
2341
Sets the default horizontal and vertical alignment for grid cell text.
2343
Horizontal alignment should be one of @c wxALIGN_LEFT,
2344
@c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
2345
of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
2347
void SetDefaultCellAlignment(int horiz, int vert);
2350
Sets the default background colour for grid cells.
2352
void SetDefaultCellBackgroundColour(const wxColour& colour);
2355
Sets the default font to be used for grid cell text.
2357
void SetDefaultCellFont(const wxFont& font);
2360
Sets the current default colour for grid cell text.
2362
void SetDefaultCellTextColour(const wxColour& colour);
2368
@name Cell Values, Editors, and Renderers
2370
Note that wxGridCellAttr can be used alternatively to most of these
2371
methods. See the "Attributes Management" of wxGridTableBase.
2376
Returns @true if the in-place edit control for the current grid cell
2377
can be used and @false otherwise.
2379
This function always returns @false for the read-only cells.
2381
bool CanEnableCellControl() const;
2384
Disables in-place editing of grid cells.
2386
Equivalent to calling EnableCellEditControl(@false).
2388
void DisableCellEditControl();
2391
Enables or disables in-place editing of grid cell data.
2393
The grid will issue either a @c wxEVT_GRID_EDITOR_SHOWN or
2394
@c wxEVT_GRID_EDITOR_HIDDEN event.
2396
void EnableCellEditControl(bool enable = true);
2399
Makes the grid globally editable or read-only.
2401
If the edit argument is @false this function sets the whole grid as
2402
read-only. If the argument is @true the grid is set to the default
2403
state where cells may be editable. In the default state you can set
2404
single grid cells and whole rows and columns to be editable or
2405
read-only via wxGridCellAttr::SetReadOnly(). For single cells you
2406
can also use the shortcut function SetReadOnly().
2408
For more information about controlling grid cell attributes see the
2409
wxGridCellAttr class and the @ref overview_grid.
2411
void EnableEditing(bool edit);
2414
Returns a pointer to the editor for the cell at the specified location.
2416
See wxGridCellEditor and the @ref overview_grid for more information
2417
about cell editors and renderers.
2419
The caller must call DecRef() on the returned pointer.
2421
wxGridCellEditor* GetCellEditor(int row, int col) const;
2424
Returns a pointer to the renderer for the grid cell at the specified
2427
See wxGridCellRenderer and the @ref overview_grid for more information
2428
about cell editors and renderers.
2430
The caller must call DecRef() on the returned pointer.
2432
wxGridCellRenderer* GetCellRenderer(int row, int col) const;
2435
Returns the string contained in the cell at the specified location.
2437
For simple applications where a grid object automatically uses a
2438
default grid table of string values you use this function together with
2439
SetCellValue() to access cell values. For more complex applications
2440
where you have derived your own grid table class that contains various
2441
data types (e.g. numeric, boolean or user-defined custom types) then
2442
you only use this function for those cells that contain string values.
2444
See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
2447
wxString GetCellValue(int row, int col) const;
2449
Returns the string contained in the cell at the specified location.
2451
For simple applications where a grid object automatically uses a
2452
default grid table of string values you use this function together with
2453
SetCellValue() to access cell values. For more complex applications
2454
where you have derived your own grid table class that contains various
2455
data types (e.g. numeric, boolean or user-defined custom types) then
2456
you only use this function for those cells that contain string values.
2458
See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
2461
wxString GetCellValue(const wxGridCellCoords& coords) const;
2464
Returns a pointer to the current default grid cell editor.
2466
See wxGridCellEditor and the @ref overview_grid for more information
2467
about cell editors and renderers.
2469
wxGridCellEditor* GetDefaultEditor() const;
2472
Returns the default editor for the specified cell.
2474
The base class version returns the editor appropriate for the current
2475
cell type but this method may be overridden in the derived classes to
2476
use custom editors for some cells by default.
2478
Notice that the same may be achieved in a usually simpler way by
2479
associating a custom editor with the given cell or cells.
2481
The caller must call DecRef() on the returned pointer.
2483
virtual wxGridCellEditor* GetDefaultEditorForCell(int row, int col) const;
2485
Returns the default editor for the specified cell.
2487
The base class version returns the editor appropriate for the current
2488
cell type but this method may be overridden in the derived classes to
2489
use custom editors for some cells by default.
2491
Notice that the same may be achieved in a usually simpler way by
2492
associating a custom editor with the given cell or cells.
2494
The caller must call DecRef() on the returned pointer.
2496
wxGridCellEditor* GetDefaultEditorForCell(const wxGridCellCoords& c) const;
2499
Returns the default editor for the cells containing values of the given
2502
The base class version returns the editor which was associated with the
2503
specified @a typeName when it was registered RegisterDataType() but
2504
this function may be overridden to return something different. This
2505
allows to override an editor used for one of the standard types.
2507
The caller must call DecRef() on the returned pointer.
2509
virtual wxGridCellEditor* GetDefaultEditorForType(const wxString& typeName) const;
2512
Returns a pointer to the current default grid cell renderer.
2514
See wxGridCellRenderer and the @ref overview_grid for more information
2515
about cell editors and renderers.
2517
The caller must call DecRef() on the returned pointer.
2519
wxGridCellRenderer* GetDefaultRenderer() const;
2522
Returns the default renderer for the given cell.
2524
The base class version returns the renderer appropriate for the current
2525
cell type but this method may be overridden in the derived classes to
2526
use custom renderers for some cells by default.
2528
The caller must call DecRef() on the returned pointer.
2530
virtual wxGridCellRenderer* GetDefaultRendererForCell(int row, int col) const;
2533
Returns the default renderer for the cell containing values of the
2536
@see GetDefaultEditorForType()
2538
virtual wxGridCellRenderer* GetDefaultRendererForType(const wxString& typeName) const;
2541
Hides the in-place cell edit control.
2543
void HideCellEditControl();
2546
Returns @true if the in-place edit control is currently enabled.
2548
bool IsCellEditControlEnabled() const;
2551
Returns @true if the current cell is read-only.
2553
@see SetReadOnly(), IsReadOnly()
2555
bool IsCurrentCellReadOnly() const;
2558
Returns @false if the whole grid has been set as read-only or @true
2561
See EnableEditing() for more information about controlling the editing
2562
status of grid cells.
2564
bool IsEditable() const;
2567
Returns @true if the cell at the specified location can't be edited.
2569
@see SetReadOnly(), IsCurrentCellReadOnly()
2571
bool IsReadOnly(int row, int col) const;
2574
Register a new data type.
2576
The data types allow to naturally associate specific renderers and
2577
editors to the cells containing values of the given type. For example,
2578
the grid automatically registers a data type with the name
2579
@c wxGRID_VALUE_STRING which uses wxGridCellStringRenderer and
2580
wxGridCellTextEditor as its renderer and editor respectively -- this is
2581
the data type used by all the cells of the default wxGridStringTable,
2582
so this renderer and editor are used by default for all grid cells.
2584
However if a custom table returns @c wxGRID_VALUE_BOOL from its
2585
wxGridTableBase::GetTypeName() method, then wxGridCellBoolRenderer and
2586
wxGridCellBoolEditor are used for it because the grid also registers a
2587
boolean data type with this name.
2589
And as this mechanism is completely generic, you may register your own
2590
data types using your own custom renderers and editors. Just remember
2591
that the table must identify a cell as being of the given type for them
2592
to be used for this cell.
2595
Name of the new type. May be any string, but if the type name is
2596
the same as the name of an already registered type, including one
2597
of the standard ones (which are @c wxGRID_VALUE_STRING, @c
2598
wxGRID_VALUE_BOOL, @c wxGRID_VALUE_NUMBER, @c wxGRID_VALUE_FLOAT
2599
and @c wxGRID_VALUE_CHOICE), then the new registration information
2600
replaces the previously used renderer and editor.
2602
The renderer to use for the cells of this type. Its ownership is
2603
taken by the grid, i.e. it will call DecRef() on this pointer when
2604
it doesn't need it any longer.
2606
The editor to use for the cells of this type. Its ownership is also
2609
void RegisterDataType(const wxString& typeName,
2610
wxGridCellRenderer* renderer,
2611
wxGridCellEditor* editor);
2614
Sets the value of the current grid cell to the current in-place edit
2617
This is called automatically when the grid cursor moves from the
2618
current cell to a new cell. It is also a good idea to call this
2619
function when closing a grid since any edits to the final cell location
2620
will not be saved otherwise.
2622
void SaveEditControlValue();
2625
Sets the editor for the grid cell at the specified location.
2627
The grid will take ownership of the pointer.
2629
See wxGridCellEditor and the @ref overview_grid for more information
2630
about cell editors and renderers.
2632
void SetCellEditor(int row, int col, wxGridCellEditor* editor);
2635
Sets the renderer for the grid cell at the specified location.
2637
The grid will take ownership of the pointer.
2639
See wxGridCellRenderer and the @ref overview_grid for more information
2640
about cell editors and renderers.
2642
void SetCellRenderer(int row, int col, wxGridCellRenderer* renderer);
2645
Sets the string value for the cell at the specified location.
2647
For simple applications where a grid object automatically uses a
2648
default grid table of string values you use this function together with
2649
GetCellValue() to access cell values. For more complex applications
2650
where you have derived your own grid table class that contains various
2651
data types (e.g. numeric, boolean or user-defined custom types) then
2652
you only use this function for those cells that contain string values.
2654
See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2657
void SetCellValue(int row, int col, const wxString& s);
2659
Sets the string value for the cell at the specified location.
2661
For simple applications where a grid object automatically uses a
2662
default grid table of string values you use this function together with
2663
GetCellValue() to access cell values. For more complex applications
2664
where you have derived your own grid table class that contains various
2665
data types (e.g. numeric, boolean or user-defined custom types) then
2666
you only use this function for those cells that contain string values.
2668
See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2671
void SetCellValue(const wxGridCellCoords& coords, const wxString& s);
2673
@deprecated Please use SetCellValue(int,int,const wxString&) or
2674
SetCellValue(const wxGridCellCoords&,const wxString&)
2677
Sets the string value for the cell at the specified location.
2679
For simple applications where a grid object automatically uses a
2680
default grid table of string values you use this function together with
2681
GetCellValue() to access cell values. For more complex applications
2682
where you have derived your own grid table class that contains various
2683
data types (e.g. numeric, boolean or user-defined custom types) then
2684
you only use this function for those cells that contain string values.
2686
See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2689
void SetCellValue(const wxString& val, int row, int col);
2692
Sets the specified column to display boolean values.
2694
@see SetColFormatCustom()
2696
void SetColFormatBool(int col);
2699
Sets the specified column to display data in a custom format.
2701
This method provides an alternative to defining a custom grid table
2702
which would return @a typeName from its GetTypeName() method for the
2703
cells in this column: while it doesn't really change the type of the
2704
cells in this column, it does associate the renderer and editor used
2705
for the cells of the specified type with them.
2707
See the @ref overview_grid for more information on working with custom
2710
void SetColFormatCustom(int col, const wxString& typeName);
2713
Sets the specified column to display floating point values with the
2714
given width and precision.
2716
@see SetColFormatCustom()
2718
void SetColFormatFloat(int col, int width = -1, int precision = -1);
2721
Sets the specified column to display integer values.
2723
@see SetColFormatCustom()
2725
void SetColFormatNumber(int col);
2728
Sets the default editor for grid cells.
2730
The grid will take ownership of the pointer.
2732
See wxGridCellEditor and the @ref overview_grid for more information
2733
about cell editors and renderers.
2735
void SetDefaultEditor(wxGridCellEditor* editor);
2738
Sets the default renderer for grid cells.
2740
The grid will take ownership of the pointer.
2742
See wxGridCellRenderer and the @ref overview_grid for more information
2743
about cell editors and renderers.
2745
void SetDefaultRenderer(wxGridCellRenderer* renderer);
2748
Makes the cell at the specified location read-only or editable.
2752
void SetReadOnly(int row, int col, bool isReadOnly = true);
2755
Displays the in-place cell edit control for the current cell.
2757
void ShowCellEditControl();
2763
@name Column and Row Sizes
2765
@see @ref overview_grid_resizing
2770
Automatically sets the height and width of all rows and columns to fit
2776
Automatically adjusts width of the column to fit its label.
2778
void AutoSizeColLabelSize(int col);
2781
Automatically sizes the column to fit its contents. If @a setAsMin is
2782
@true the calculated width will also be set as the minimal width for
2785
void AutoSizeColumn(int col, bool setAsMin = true);
2788
Automatically sizes all columns to fit their contents. If @a setAsMin
2789
is @true the calculated widths will also be set as the minimal widths
2792
void AutoSizeColumns(bool setAsMin = true);
2795
Automatically sizes the row to fit its contents. If @a setAsMin is
2796
@true the calculated height will also be set as the minimal height for
2799
void AutoSizeRow(int row, bool setAsMin = true);
2802
Automatically adjusts height of the row to fit its label.
2804
void AutoSizeRowLabelSize(int col);
2807
Automatically sizes all rows to fit their contents. If @a setAsMin is
2808
@true the calculated heights will also be set as the minimal heights
2811
void AutoSizeRows(bool setAsMin = true);
2814
Returns the current height of the column labels.
2816
int GetColLabelSize() const;
2819
Returns the minimal width to which a column may be resized.
2821
Use SetColMinimalAcceptableWidth() to change this value globally or
2822
SetColMinimalWidth() to do it for individual columns.
2824
@see GetRowMinimalAcceptableHeight()
2826
int GetColMinimalAcceptableWidth() const;
2829
Returns the width of the specified column.
2831
int GetColSize(int col) const;
2834
Returns @true if the specified column is not currently hidden.
2836
bool IsColShown(int col) const;
2839
Returns the default height for column labels.
2841
int GetDefaultColLabelSize() const;
2844
Returns the current default width for grid columns.
2846
int GetDefaultColSize() const;
2849
Returns the default width for the row labels.
2851
int GetDefaultRowLabelSize() const;
2854
Returns the current default height for grid rows.
2856
int GetDefaultRowSize() const;
2859
Returns the minimal size to which rows can be resized.
2861
Use SetRowMinimalAcceptableHeight() to change this value globally or
2862
SetRowMinimalHeight() to do it for individual cells.
2864
@see GetColMinimalAcceptableWidth()
2866
int GetRowMinimalAcceptableHeight() const;
2869
Returns the current width of the row labels.
2871
int GetRowLabelSize() const;
2874
Returns the height of the specified row.
2876
int GetRowSize(int row) const;
2879
Returns @true if the specified row is not currently hidden.
2881
bool IsRowShown(int row) const;
2884
Sets the height of the column labels.
2886
If @a height equals to @c wxGRID_AUTOSIZE then height is calculated
2887
automatically so that no label is truncated. Note that this could be
2888
slow for a large table.
2890
void SetColLabelSize(int height);
2893
Sets the minimal @a width to which the user can resize columns.
2895
@see GetColMinimalAcceptableWidth()
2897
void SetColMinimalAcceptableWidth(int width);
2900
Sets the minimal @a width for the specified column @a col.
2902
It is usually best to call this method during grid creation as calling
2903
it later will not resize the column to the given minimal width even if
2904
it is currently narrower than it.
2906
@a width must be greater than the minimal acceptable column width as
2907
returned by GetColMinimalAcceptableWidth().
2909
void SetColMinimalWidth(int col, int width);
2912
Sets the width of the specified column.
2917
The new column width in pixels, 0 to hide the column or -1 to fit
2918
the column width to its label width.
2920
void SetColSize(int col, int width);
2923
Hides the specified column.
2925
To show the column later you need to call SetColSize() with non-0
2931
void HideCol(int col);
2934
Shows the previously hidden column by resizing it to non-0 size.
2936
@see HideCol(), SetColSize()
2938
void ShowCol(int col);
2942
Sets the default width for columns in the grid.
2944
This will only affect columns subsequently added to the grid unless
2945
@a resizeExistingCols is @true.
2947
If @a width is less than GetColMinimalAcceptableWidth(), then the
2948
minimal acceptable width is used instead of it.
2950
void SetDefaultColSize(int width, bool resizeExistingCols = false);
2953
Sets the default height for rows in the grid.
2955
This will only affect rows subsequently added to the grid unless
2956
@a resizeExistingRows is @true.
2958
If @a height is less than GetRowMinimalAcceptableHeight(), then the
2959
minimal acceptable height is used instead of it.
2961
void SetDefaultRowSize(int height, bool resizeExistingRows = false);
2964
Sets the width of the row labels.
2966
If @a width equals @c wxGRID_AUTOSIZE then width is calculated
2967
automatically so that no label is truncated. Note that this could be
2968
slow for a large table.
2970
void SetRowLabelSize(int width);
2973
Sets the minimal row @a height used by default.
2975
See SetColMinimalAcceptableWidth() for more information.
2977
void SetRowMinimalAcceptableHeight(int height);
2980
Sets the minimal @a height for the specified @a row.
2982
See SetColMinimalWidth() for more information.
2984
void SetRowMinimalHeight(int row, int height);
2987
Sets the height of the specified row.
2989
See SetColSize() for more information.
2991
void SetRowSize(int row, int height);
2994
Hides the specified row.
2996
To show the row later you need to call SetRowSize() with non-0
3002
void HideRow(int col);
3005
Shows the previously hidden row by resizing it to non-0 size.
3007
@see HideRow(), SetRowSize()
3009
void ShowRow(int col);
3012
Get size information for all columns at once.
3014
This method is useful when the information about all column widths
3015
needs to be saved. The widths can be later restored using
3018
@sa wxGridSizesInfo, GetRowSizes()
3020
wxGridSizesInfo GetColSizes() const;
3023
Get size information for all row at once.
3025
@sa wxGridSizesInfo, GetColSizes()
3027
wxGridSizesInfo GetRowSizes() const;
3030
Restore all columns sizes.
3032
This is usually called with wxGridSizesInfo object previously returned
3037
void SetColSizes(const wxGridSizesInfo& sizeInfo);
3040
Restore all rows sizes.
3044
void SetRowSizes(const wxGridSizesInfo& sizeInfo);
3047
Set the size of the cell.
3049
Specifying a value of more than 1 in @a num_rows or @a num_cols will
3050
make the cell at (@a row, @a col) span the block of the specified size,
3051
covering the other cells which would be normally shown in it. Passing 1
3052
for both arguments resets the cell to normal appearance.
3057
The row of the cell.
3059
The column of the cell.
3061
Number of rows to be occupied by this cell, must be >= 1.
3063
Number of columns to be occupied by this cell, must be >= 1.
3065
void SetCellSize(int row, int col, int num_rows, int num_cols);
3068
Get the size of the cell in number of cells covered by it.
3070
For normal cells, the function fills both @a num_rows and @a num_cols
3071
with 1 and returns CellSpan_None. For cells which span multiple cells, i.e.
3072
for which SetCellSize() had been called, the returned values are the
3073
same ones as were passed to SetCellSize() call and the function return
3074
value is CellSpan_Main.
3076
More unexpectedly, perhaps, the returned values may be @em negative for
3077
the cells which are inside a span covered by a cell occupying multiple
3078
rows or columns. They correspond to the offset of the main cell of the
3079
span from the cell passed to this functions and the function returns
3080
CellSpan_Inside value to indicate this.
3082
As an example, consider a 3*3 grid with the cell (1, 1) (the one in the
3083
middle) having a span of 2 rows and 2 columns, i.e. the grid looks like
3093
Then the function returns 2 and 2 in @a num_rows and @a num_cols for
3094
the cell (1, 1) itself and -1 and -1 for the cell (2, 2) as well as -1
3095
and 0 for the cell (2, 1).
3098
The row of the cell.
3100
The column of the cell.
3102
Pointer to variable receiving the number of rows, must not be @NULL.
3104
Pointer to variable receiving the number of columns, must not be
3107
The kind of this cell span (the return value is new in wxWidgets
3108
2.9.1, this function was void in previous wxWidgets versions).
3110
CellSpan GetCellSize( int row, int col, int *num_rows, int *num_cols ) const;
3113
Get the number of rows and columns allocated for this cell.
3115
This overload doesn't return a CellSpan value but the values returned
3116
may still be negative, see GetCellSize(int, int, int *, int *) for
3119
wxSize GetCellSize(const wxGridCellCoords& coords);
3125
@name User-Resizing and Dragging
3127
Functions controlling various interactive mouse operations.
3129
By default, columns and rows can be resized by dragging the edges of
3130
their labels (this can be disabled using DisableDragColSize() and
3131
DisableDragRowSize() methods). And if grid line dragging is enabled with
3132
EnableDragGridSize() they can also be resized by dragging the right or
3133
bottom edge of the grid cells.
3135
Columns can also be moved to interactively change their order but this
3136
needs to be explicitly enabled with EnableDragColMove().
3141
Return @true if the dragging of cells is enabled or @false otherwise.
3143
bool CanDragCell() const;
3146
Returns @true if columns can be moved by dragging with the mouse.
3148
Columns can be moved by dragging on their labels.
3150
bool CanDragColMove() const;
3153
Returns @true if the given column can be resized by dragging with the
3156
This function returns @true if resizing the columns interactively is
3157
globally enabled, i.e. if DisableDragColSize() hadn't been called, and
3158
if this column wasn't explicitly marked as non-resizable with
3161
bool CanDragColSize(int col) const;
3164
Return @true if the dragging of grid lines to resize rows and columns
3165
is enabled or @false otherwise.
3167
bool CanDragGridSize() const;
3170
Returns @true if the given row can be resized by dragging with the
3173
This is the same as CanDragColSize() but for rows.
3175
bool CanDragRowSize(int row) const;
3178
Disable interactive resizing of the specified column.
3180
This method allows to disable resizing of an individual column in a
3181
grid where the columns are otherwise resizable (which is the case by
3184
Notice that currently there is no way to make some columns resizable in
3185
a grid where columns can't be resized by default as there doesn't seem
3186
to be any need for this in practice. There is also no way to make the
3187
column marked as fixed using this method resizable again because it is
3188
supposed that fixed columns are used for static parts of the grid and
3189
so should remain fixed during the entire grid lifetime.
3191
Also notice that disabling interactive column resizing will not prevent
3192
the program from changing the column size.
3194
@see EnableDragColSize()
3196
void DisableColResize(int col);
3199
Disable interactive resizing of the specified row.
3201
This is the same as DisableColResize() but for rows.
3203
@see EnableDragRowSize()
3205
void DisableRowResize(int row);
3208
Disables column moving by dragging with the mouse.
3210
Equivalent to passing @false to EnableDragColMove().
3212
void DisableDragColMove();
3215
Disables column sizing by dragging with the mouse.
3217
Equivalent to passing @false to EnableDragColSize().
3219
void DisableDragColSize();
3222
Disable mouse dragging of grid lines to resize rows and columns.
3224
Equivalent to passing @false to EnableDragGridSize()
3226
void DisableDragGridSize();
3229
Disables row sizing by dragging with the mouse.
3231
Equivalent to passing @false to EnableDragRowSize().
3233
void DisableDragRowSize();
3236
Enables or disables cell dragging with the mouse.
3238
void EnableDragCell(bool enable = true);
3241
Enables or disables column moving by dragging with the mouse.
3243
void EnableDragColMove(bool enable = true);
3246
Enables or disables column sizing by dragging with the mouse.
3248
@see DisableColResize()
3250
void EnableDragColSize(bool enable = true);
3253
Enables or disables row and column resizing by dragging gridlines with
3256
void EnableDragGridSize(bool enable = true);
3259
Enables or disables row sizing by dragging with the mouse.
3261
@see DisableRowResize()
3263
void EnableDragRowSize(bool enable = true);
3266
Returns the column ID of the specified column position.
3268
int GetColAt(int colPos) const;
3271
Returns the position of the specified column.
3273
int GetColPos(int colID) const;
3276
Sets the position of the specified column.
3278
void SetColPos(int colID, int newPos);
3281
Sets the positions of all columns at once.
3283
This method takes an array containing the indices of the columns in
3284
their display order, i.e. uses the same convention as
3285
wxHeaderCtrl::SetColumnsOrder().
3287
void SetColumnsOrder(const wxArrayInt& order);
3290
Resets the position of the columns to the default.
3298
@name Cursor Movement
3303
Returns the current grid cell column position.
3305
int GetGridCursorCol() const;
3308
Returns the current grid cell row position.
3310
int GetGridCursorRow() const;
3313
Make the given cell current and ensure it is visible.
3315
This method is equivalent to calling MakeCellVisible() and
3316
SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL
3317
event is generated by it and the selected cell doesn't change if the
3320
void GoToCell(int row, int col);
3322
Make the given cell current and ensure it is visible.
3324
This method is equivalent to calling MakeCellVisible() and
3325
SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL
3326
event is generated by it and the selected cell doesn't change if the
3329
void GoToCell(const wxGridCellCoords& coords);
3332
Moves the grid cursor down by one row.
3334
If a block of cells was previously selected it will expand if the
3335
argument is @true or be cleared if the argument is @false.
3337
bool MoveCursorDown(bool expandSelection);
3340
Moves the grid cursor down in the current column such that it skips to
3341
the beginning or end of a block of non-empty cells.
3343
If a block of cells was previously selected it will expand if the
3344
argument is @true or be cleared if the argument is @false.
3346
bool MoveCursorDownBlock(bool expandSelection);
3349
Moves the grid cursor left by one column.
3351
If a block of cells was previously selected it will expand if the
3352
argument is @true or be cleared if the argument is @false.
3354
bool MoveCursorLeft(bool expandSelection);
3357
Moves the grid cursor left in the current row such that it skips to the
3358
beginning or end of a block of non-empty cells.
3360
If a block of cells was previously selected it will expand if the
3361
argument is @true or be cleared if the argument is @false.
3363
bool MoveCursorLeftBlock(bool expandSelection);
3366
Moves the grid cursor right by one column.
3368
If a block of cells was previously selected it will expand if the
3369
argument is @true or be cleared if the argument is @false.
3371
bool MoveCursorRight(bool expandSelection);
3374
Moves the grid cursor right in the current row such that it skips to
3375
the beginning or end of a block of non-empty cells.
3377
If a block of cells was previously selected it will expand if the
3378
argument is @true or be cleared if the argument is @false.
3380
bool MoveCursorRightBlock(bool expandSelection);
3383
Moves the grid cursor up by one row.
3385
If a block of cells was previously selected it will expand if the
3386
argument is @true or be cleared if the argument is @false.
3388
bool MoveCursorUp(bool expandSelection);
3391
Moves the grid cursor up in the current column such that it skips to
3392
the beginning or end of a block of non-empty cells.
3394
If a block of cells was previously selected it will expand if the
3395
argument is @true or be cleared if the argument is @false.
3397
bool MoveCursorUpBlock(bool expandSelection);
3400
Moves the grid cursor down by some number of rows so that the previous
3401
bottom visible row becomes the top visible row.
3403
bool MovePageDown();
3406
Moves the grid cursor up by some number of rows so that the previous
3407
top visible row becomes the bottom visible row.
3412
Set the grid cursor to the specified cell.
3414
The grid cursor indicates the current cell and can be moved by the user
3415
using the arrow keys or the mouse.
3417
Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
3418
if the event handler vetoes this event, the cursor is not moved.
3420
This function doesn't make the target call visible, use GoToCell() to
3423
void SetGridCursor(int row, int col);
3425
Set the grid cursor to the specified cell.
3427
The grid cursor indicates the current cell and can be moved by the user
3428
using the arrow keys or the mouse.
3430
Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
3431
if the event handler vetoes this event, the cursor is not moved.
3433
This function doesn't make the target call visible, use GoToCell() to
3436
void SetGridCursor(const wxGridCellCoords& coords);
3442
@name User Selection
3447
Deselects all cells that are currently selected.
3449
void ClearSelection();
3452
Returns an array of individually selected cells.
3454
Notice that this array does @em not contain all the selected cells in
3455
general as it doesn't include the cells selected as part of column, row
3456
or block selection. You must use this method, GetSelectedCols(),
3457
GetSelectedRows() and GetSelectionBlockTopLeft() and
3458
GetSelectionBlockBottomRight() methods to obtain the entire selection
3461
Please notice this behaviour is by design and is needed in order to
3462
support grids of arbitrary size (when an entire column is selected in
3463
a grid with a million of columns, we don't want to create an array with
3464
a million of entries in this function, instead it returns an empty
3465
array and GetSelectedCols() returns an array containing one element).
3467
wxGridCellCoordsArray GetSelectedCells() const;
3470
Returns an array of selected columns.
3472
Please notice that this method alone is not sufficient to find all the
3473
selected columns as it contains only the columns which were
3474
individually selected but not those being part of the block selection
3475
or being selected in virtue of all of their cells being selected
3476
individually, please see GetSelectedCells() for more details.
3478
wxArrayInt GetSelectedCols() const;
3481
Returns an array of selected rows.
3483
Please notice that this method alone is not sufficient to find all the
3484
selected rows as it contains only the rows which were individually
3485
selected but not those being part of the block selection or being
3486
selected in virtue of all of their cells being selected individually,
3487
please see GetSelectedCells() for more details.
3489
wxArrayInt GetSelectedRows() const;
3492
Returns the colour used for drawing the selection background.
3494
wxColour GetSelectionBackground() const;
3497
Returns an array of the bottom right corners of blocks of selected
3500
Please see GetSelectedCells() for more information about the selection
3501
representation in wxGrid.
3503
@see GetSelectionBlockTopLeft()
3505
wxGridCellCoordsArray GetSelectionBlockBottomRight() const;
3508
Returns an array of the top left corners of blocks of selected cells.
3510
Please see GetSelectedCells() for more information about the selection
3511
representation in wxGrid.
3513
@see GetSelectionBlockBottomRight()
3515
wxGridCellCoordsArray GetSelectionBlockTopLeft() const;
3518
Returns the colour used for drawing the selection foreground.
3520
wxColour GetSelectionForeground() const;
3523
Returns the current selection mode.
3525
@see SetSelectionMode().
3527
wxGridSelectionModes GetSelectionMode() const;
3530
Returns @true if the given cell is selected.
3532
bool IsInSelection(int row, int col) const;
3534
Returns @true if the given cell is selected.
3536
bool IsInSelection(const wxGridCellCoords& coords) const;
3539
Returns @true if there are currently any selected cells, rows, columns
3542
bool IsSelection() const;
3545
Selects all cells in the grid.
3550
Selects a rectangular block of cells.
3552
If @a addToSelected is @false then any existing selection will be
3553
deselected; if @true the column will be added to the existing
3556
void SelectBlock(int topRow, int leftCol, int bottomRow, int rightCol,
3557
bool addToSelected = false);
3559
Selects a rectangular block of cells.
3561
If @a addToSelected is @false then any existing selection will be
3562
deselected; if @true the column will be added to the existing
3565
void SelectBlock(const wxGridCellCoords& topLeft,
3566
const wxGridCellCoords& bottomRight,
3567
bool addToSelected = false);
3570
Selects the specified column.
3572
If @a addToSelected is @false then any existing selection will be
3573
deselected; if @true the column will be added to the existing
3576
This method won't select anything if the current selection mode is
3579
void SelectCol(int col, bool addToSelected = false);
3582
Selects the specified row.
3584
If @a addToSelected is @false then any existing selection will be
3585
deselected; if @true the row will be added to the existing selection.
3587
This method won't select anything if the current selection mode is
3588
wxGridSelectColumns.
3590
void SelectRow(int row, bool addToSelected = false);
3593
Set the colour to be used for drawing the selection background.
3595
void SetSelectionBackground(const wxColour& c);
3598
Set the colour to be used for drawing the selection foreground.
3600
void SetSelectionForeground(const wxColour& c);
3603
Set the selection behaviour of the grid.
3605
The existing selection is converted to conform to the new mode if
3606
possible and discarded otherwise (e.g. any individual selected cells
3607
are deselected if the new mode allows only the selection of the entire
3610
void SetSelectionMode(wxGridSelectionModes selmode);
3621
Returns the number of pixels per horizontal scroll increment.
3625
@see GetScrollLineY(), SetScrollLineX(), SetScrollLineY()
3627
int GetScrollLineX() const;
3630
Returns the number of pixels per vertical scroll increment.
3634
@see GetScrollLineX(), SetScrollLineX(), SetScrollLineY()
3636
int GetScrollLineY() const;
3639
Returns @true if a cell is either entirely or at least partially
3640
visible in the grid window.
3642
By default, the cell must be entirely visible for this function to
3643
return @true but if @a wholeCellVisible is @false, the function returns
3644
@true even if the cell is only partially visible.
3646
bool IsVisible(int row, int col, bool wholeCellVisible = true) const;
3648
Returns @true if a cell is either entirely or at least partially
3649
visible in the grid window.
3651
By default, the cell must be entirely visible for this function to
3652
return @true but if @a wholeCellVisible is @false, the function returns
3653
@true even if the cell is only partially visible.
3655
bool IsVisible(const wxGridCellCoords& coords,
3656
bool wholeCellVisible = true) const;
3659
Brings the specified cell into the visible grid cell area with minimal
3662
Does nothing if the cell is already visible.
3664
void MakeCellVisible(int row, int col);
3666
Brings the specified cell into the visible grid cell area with minimal
3669
Does nothing if the cell is already visible.
3671
void MakeCellVisible(const wxGridCellCoords& coords);
3674
Sets the number of pixels per horizontal scroll increment.
3678
@see GetScrollLineX(), GetScrollLineY(), SetScrollLineY()
3680
void SetScrollLineX(int x);
3683
Sets the number of pixels per vertical scroll increment.
3687
@see GetScrollLineX(), GetScrollLineY(), SetScrollLineX()
3689
void SetScrollLineY(int y);
3695
@name Cell and Device Coordinate Translation
3700
Convert grid cell coordinates to grid window pixel coordinates.
3702
This function returns the rectangle that encloses the block of cells
3703
limited by @a topLeft and @a bottomRight cell in device coords and
3704
clipped to the client size of the grid window.
3708
wxRect BlockToDeviceRect(const wxGridCellCoords& topLeft,
3709
const wxGridCellCoords& bottomRight) const;
3712
Return the rectangle corresponding to the grid cell's size and position
3713
in logical coordinates.
3715
@see BlockToDeviceRect()
3717
wxRect CellToRect(int row, int col) const;
3719
Return the rectangle corresponding to the grid cell's size and position
3720
in logical coordinates.
3722
@see BlockToDeviceRect()
3724
wxRect CellToRect(const wxGridCellCoords& coords) const;
3727
Returns the column at the given pixel position.
3730
The x position to evaluate.
3732
If @true, rather than returning @c wxNOT_FOUND, it returns either
3733
the first or last column depending on whether @a x is too far to
3734
the left or right respectively.
3736
The column index or @c wxNOT_FOUND.
3738
int XToCol(int x, bool clipToMinMax = false) const;
3741
Returns the column whose right hand edge is close to the given logical
3744
If no column edge is near to this position @c wxNOT_FOUND is returned.
3746
int XToEdgeOfCol(int x) const;
3749
Translates logical pixel coordinates to the grid cell coordinates.
3751
Notice that this function expects logical coordinates on input so if
3752
you use this function in a mouse event handler you need to translate
3753
the mouse position, which is expressed in device coordinates, to
3756
@see XToCol(), YToRow()
3758
wxGridCellCoords XYToCell(int x, int y) const;
3760
Translates logical pixel coordinates to the grid cell coordinates.
3762
Notice that this function expects logical coordinates on input so if
3763
you use this function in a mouse event handler you need to translate
3764
the mouse position, which is expressed in device coordinates, to
3767
@see XToCol(), YToRow()
3769
wxGridCellCoords XYToCell(const wxPoint& pos) const;
3770
// XYToCell(int, int, wxGridCellCoords&) overload is intentionally
3771
// undocumented, using it is ugly and non-const reference parameters are
3772
// not used in wxWidgets API
3775
Returns the row whose bottom edge is close to the given logical @a y
3778
If no row edge is near to this position @c wxNOT_FOUND is returned.
3780
int YToEdgeOfRow(int y) const;
3783
Returns the grid row that corresponds to the logical @a y coordinate.
3785
Returns @c wxNOT_FOUND if there is no row at the @a y position.
3787
int YToRow(int y, bool clipToMinMax = false) const;
3793
@name Miscellaneous Functions
3798
Appends one or more new columns to the right of the grid.
3800
The @a updateLabels argument is not used at present. If you are using a
3801
derived grid table class you will need to override
3802
wxGridTableBase::AppendCols(). See InsertCols() for further
3805
@return @true on success or @false if appending columns failed.
3807
bool AppendCols(int numCols = 1, bool updateLabels = true);
3810
Appends one or more new rows to the bottom of the grid.
3812
The @a updateLabels argument is not used at present. If you are using a
3813
derived grid table class you will need to override
3814
wxGridTableBase::AppendRows(). See InsertRows() for further
3817
@return @true on success or @false if appending rows failed.
3819
bool AppendRows(int numRows = 1, bool updateLabels = true);
3822
Return @true if the horizontal grid lines stop at the last column
3823
boundary or @false if they continue to the end of the window.
3825
The default is to clip grid lines.
3827
@see ClipHorzGridLines(), AreVertGridLinesClipped()
3829
bool AreHorzGridLinesClipped() const;
3832
Return @true if the vertical grid lines stop at the last row
3833
boundary or @false if they continue to the end of the window.
3835
The default is to clip grid lines.
3837
@see ClipVertGridLines(), AreHorzGridLinesClipped()
3839
bool AreVertGridLinesClipped() const;
3842
Increments the grid's batch count.
3844
When the count is greater than zero repainting of the grid is
3845
suppressed. Each call to BeginBatch must be matched by a later call to
3846
EndBatch(). Code that does a lot of grid modification can be enclosed
3847
between BeginBatch() and EndBatch() calls to avoid screen flicker. The
3848
final EndBatch() call will cause the grid to be repainted.
3850
Notice that you should use wxGridUpdateLocker which ensures that there
3851
is always a matching EndBatch() call for this BeginBatch() if possible
3852
instead of calling this method directly.
3857
Clears all data in the underlying grid table and repaints the grid.
3859
The table is not deleted by this function. If you are using a derived
3860
table class then you need to override wxGridTableBase::Clear() for this
3861
function to have any effect.
3866
Change whether the horizontal grid lines are clipped by the end of the
3869
By default the grid lines are not drawn beyond the end of the last
3870
column but after calling this function with @a clip set to @false they
3871
will be drawn across the entire grid window.
3873
@see AreHorzGridLinesClipped(), ClipVertGridLines()
3875
void ClipHorzGridLines(bool clip);
3878
Change whether the vertical grid lines are clipped by the end of the
3881
By default the grid lines are not drawn beyond the end of the last
3882
row but after calling this function with @a clip set to @false they
3883
will be drawn across the entire grid window.
3885
@see AreVertGridLinesClipped(), ClipHorzGridLines()
3887
void ClipVertGridLines(bool clip);
3890
Deletes one or more columns from a grid starting at the specified
3893
The @a updateLabels argument is not used at present. If you are using a
3894
derived grid table class you will need to override
3895
wxGridTableBase::DeleteCols(). See InsertCols() for further
3898
@return @true on success or @false if deleting columns failed.
3900
bool DeleteCols(int pos = 0, int numCols = 1, bool updateLabels = true);
3903
Deletes one or more rows from a grid starting at the specified
3906
The @a updateLabels argument is not used at present. If you are using a
3907
derived grid table class you will need to override
3908
wxGridTableBase::DeleteRows(). See InsertRows() for further
3911
@return @true on success or @false if appending rows failed.
3913
bool DeleteRows(int pos = 0, int numRows = 1, bool updateLabels = true);
3916
Decrements the grid's batch count.
3918
When the count is greater than zero repainting of the grid is
3919
suppressed. Each previous call to BeginBatch() must be matched by a
3920
later call to EndBatch(). Code that does a lot of grid modification can
3921
be enclosed between BeginBatch() and EndBatch() calls to avoid screen
3922
flicker. The final EndBatch() will cause the grid to be repainted.
3924
@see wxGridUpdateLocker
3929
Overridden wxWindow method.
3934
Causes immediate repainting of the grid.
3936
Use this instead of the usual wxWindow::Refresh().
3938
void ForceRefresh();
3941
Returns the number of times that BeginBatch() has been called without
3942
(yet) matching calls to EndBatch(). While the grid's batch count is
3943
greater than zero the display will not be updated.
3945
int GetBatchCount();
3948
Returns the total number of grid columns.
3950
This is the same as the number of columns in the underlying grid table.
3952
int GetNumberCols() const;
3955
Returns the total number of grid rows.
3957
This is the same as the number of rows in the underlying grid table.
3959
int GetNumberRows() const;
3962
Returns the attribute for the given cell creating one if necessary.
3964
If the cell already has an attribute, it is returned. Otherwise a new
3965
attribute is created, associated with the cell and returned. In any
3966
case the caller must call DecRef() on the returned pointer.
3968
This function may only be called if CanHaveAttributes() returns @true.
3970
wxGridCellAttr *GetOrCreateCellAttr(int row, int col) const;
3973
Returns a base pointer to the current table object.
3975
The returned pointer is still owned by the grid.
3977
wxGridTableBase *GetTable() const;
3980
Inserts one or more new columns into a grid with the first new column
3981
at the specified position.
3983
Notice that inserting the columns in the grid requires grid table
3984
cooperation: when this method is called, grid object begins by
3985
requesting the underlying grid table to insert new columns. If this is
3986
successful the table notifies the grid and the grid updates the
3987
display. For a default grid (one where you have called CreateGrid())
3988
this process is automatic. If you are using a custom grid table
3989
(specified with SetTable()) then you must override
3990
wxGridTableBase::InsertCols() in your derived table class.
3993
The position which the first newly inserted column will have.
3995
The number of columns to insert.
3999
@true if the columns were successfully inserted, @false if an error
4000
occurred (most likely the table couldn't be updated).
4002
bool InsertCols(int pos = 0, int numCols = 1, bool updateLabels = true);
4005
Inserts one or more new rows into a grid with the first new row at the
4008
Notice that you must implement wxGridTableBase::InsertRows() if you use
4009
a grid with a custom table, please see InsertCols() for more
4013
The position which the first newly inserted row will have.
4015
The number of rows to insert.
4019
@true if the rows were successfully inserted, @false if an error
4020
occurred (most likely the table couldn't be updated).
4022
bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true);
4025
Invalidates the cached attribute for the given cell.
4027
For efficiency reasons, wxGrid may cache the recently used attributes
4028
(currently it caches only the single most recently used one, in fact)
4029
which can result in the cell appearance not being refreshed even when
4030
the attribute returned by your custom wxGridCellAttrProvider-derived
4031
class has changed. To force the grid to refresh the cell attribute,
4032
this function may be used. Notice that calling it will not result in
4033
actually redrawing the cell, you still need to call
4034
wxWindow::RefreshRect() to invalidate the area occupied by the cell in
4035
the window to do this. Also note that you don't need to call this
4036
function if you store the attributes in wxGrid itself, i.e. use its
4037
SetAttr() and similar methods, it is only useful when using a separate
4038
custom attributes provider.
4041
The row of the cell whose attribute needs to be queried again.
4043
The column of the cell whose attribute needs to be queried again.
4047
void RefreshAttr(int row, int col);
4050
Draws part or all of a wxGrid on a wxDC for printing or display.
4052
Pagination can be accomplished by using sequential Render() calls
4053
with appropriate values in wxGridCellCoords topLeft and bottomRight.
4056
The wxDC to be drawn on.
4058
The position on the wxDC where rendering should begin. If not
4059
specified drawing will begin at the wxDC MaxX() and MaxY().
4061
The size of the area on the wxDC that the rendered wxGrid should
4062
occupy. If not specified the drawing will be scaled to fit the
4063
available dc width or height. The wxGrid's aspect ratio is
4064
maintained whether or not size is specified.
4066
The top left cell of the block to be drawn. Defaults to ( 0, 0 ).
4068
The bottom right cell of the block to be drawn. Defaults to row and
4071
A combination of values from wxGridRenderStyle.
4075
void Render( wxDC& dc,
4076
const wxPoint& pos = wxDefaultPosition,
4077
const wxSize& size = wxDefaultSize,
4078
const wxGridCellCoords& topLeft = wxGridCellCoords( -1, -1 ),
4079
const wxGridCellCoords& bottomRight = wxGridCellCoords( -1, -1 ),
4080
int style = wxGRID_DRAW_DEFAULT );
4083
Sets the cell attributes for all cells in the specified column.
4085
For more information about controlling grid cell attributes see the
4086
wxGridCellAttr cell attribute class and the @ref overview_grid.
4088
void SetColAttr(int col, wxGridCellAttr* attr);
4091
Sets the extra margins used around the grid area.
4093
A grid may occupy more space than needed for its data display and
4094
this function allows to set how big this extra space is
4096
void SetMargins(int extraWidth, int extraHeight);
4099
Sets the cell attributes for all cells in the specified row.
4101
The grid takes ownership of the attribute pointer.
4103
See the wxGridCellAttr class for more information about controlling
4106
void SetRowAttr(int row, wxGridCellAttr* attr);
4112
@name Sorting support.
4114
wxGrid doesn't provide any support for sorting the data but it does
4115
generate events allowing the user code to sort it and supports
4116
displaying the sort indicator in the column used for sorting.
4118
To use wxGrid sorting support you need to handle wxEVT_GRID_COL_SORT
4119
event (and not veto it) and resort the data displayed in the grid. The
4120
grid will automatically update the sorting indicator on the column
4123
You can also call the functions in this section directly to update the
4124
sorting indicator. Once again, they don't do anything with the grid
4125
data, it remains your responsibility to actually sort it appropriately.
4130
Return the column in which the sorting indicator is currently
4133
Returns @c wxNOT_FOUND if sorting indicator is not currently displayed
4136
@see SetSortingColumn()
4138
int GetSortingColumn() const;
4141
Return @true if this column is currently used for sorting.
4143
@see GetSortingColumn()
4145
bool IsSortingBy(int col) const;
4148
Return @true if the current sorting order is ascending or @false if it
4151
It only makes sense to call this function if GetSortingColumn() returns
4152
a valid column index and not @c wxNOT_FOUND.
4154
@see SetSortingColumn()
4156
bool IsSortOrderAscending() const;
4159
Set the column to display the sorting indicator in and its direction.
4162
The column to display the sorting indicator in or @c wxNOT_FOUND to
4163
remove any currently displayed sorting indicator.
4165
If @true, display the ascending sort indicator, otherwise display
4166
the descending sort indicator.
4168
@see GetSortingColumn(), IsSortOrderAscending()
4170
void SetSortingColumn(int col, bool ascending = true);
4173
Remove any currently shown sorting indicator.
4175
This is equivalent to calling SetSortingColumn() with @c wxNOT_FOUND
4178
void UnsetSortingColumn();
4183
@name Accessors for component windows.
4185
Return the various child windows of wxGrid.
4187
wxGrid is an empty parent window for 4 children representing the column
4188
labels window (top), the row labels window (left), the corner window
4189
(top left) and the main grid window. It may be necessary to use these
4190
individual windows and not the wxGrid window itself if you need to
4191
handle events for them (this can be done using wxEvtHandler::Connect()
4192
or wxWindow::PushEventHandler()) or do something else requiring the use
4193
of the correct window pointer. Notice that you should not, however,
4194
change these windows (e.g. reposition them or draw over them) because
4195
they are managed by wxGrid itself.
4200
Return the main grid window containing the grid cells.
4202
This window is always shown.
4204
wxWindow *GetGridWindow() const;
4207
Return the row labels window.
4209
This window is not shown if the row labels were hidden using
4212
wxWindow *GetGridRowLabelWindow() const;
4215
Return the column labels window.
4217
This window is not shown if the columns labels were hidden using
4220
Depending on whether UseNativeColHeader() was called or not this can be
4221
either a wxHeaderCtrl or a plain wxWindow. This function returns a valid
4222
window pointer in either case but in the former case you can also use
4223
GetGridColHeader() to access it if you need wxHeaderCtrl-specific
4226
wxWindow *GetGridColLabelWindow() const;
4229
Return the window in the top left grid corner.
4231
This window is shown only of both columns and row labels are shown and
4232
normally doesn't contain anything. Clicking on it is handled by wxGrid
4233
however and can be used to select the entire grid.
4235
wxWindow *GetGridCornerLabelWindow() const;
4238
Return the header control used for column labels display.
4240
This function can only be called if UseNativeColHeader() had been
4243
wxHeaderCtrl *GetGridColHeader() const;
4249
Returns @true if this grid has support for cell attributes.
4251
The grid supports attributes if it has the associated table which, in
4252
turn, has attributes support, i.e. wxGridTableBase::CanHaveAttributes()
4255
bool CanHaveAttributes() const;
4258
Get the minimal width of the given column/row.
4260
The value returned by this function may be different than that returned
4261
by GetColMinimalAcceptableWidth() if SetColMinimalWidth() had been
4262
called for this column.
4264
int GetColMinimalWidth(int col) const;
4267
Returns the coordinate of the right border specified column.
4269
int GetColRight(int col) const;
4272
Returns the coordinate of the left border specified column.
4274
int GetColLeft(int col) const;
4277
Returns the minimal size for the given column.
4279
The value returned by this function may be different than that returned
4280
by GetRowMinimalAcceptableHeight() if SetRowMinimalHeight() had been
4281
called for this row.
4283
int GetRowMinimalHeight(int col) const;
4289
@class wxGridUpdateLocker
4291
This small class can be used to prevent wxGrid from redrawing during its
4292
lifetime by calling wxGrid::BeginBatch() in its constructor and
4293
wxGrid::EndBatch() in its destructor. It is typically used in a function
4294
performing several operations with a grid which would otherwise result in
4295
flicker. For example:
4300
m_grid = new wxGrid(this, ...);
4302
wxGridUpdateLocker noUpdates(m_grid);
4303
m_grid-AppendColumn();
4304
// ... many other operations with m_grid ...
4307
// destructor called, grid refreshed
4311
Using this class is easier and safer than calling wxGrid::BeginBatch() and
4312
wxGrid::EndBatch() because you don't risk missing the call the latter (due
4313
to an exception for example).
4318
class wxGridUpdateLocker
4322
Creates an object preventing the updates of the specified @a grid. The
4323
parameter could be @NULL in which case nothing is done. If @a grid is
4324
non-@NULL then the grid must exist for longer than this
4325
wxGridUpdateLocker object itself.
4327
The default constructor could be followed by a call to Create() to set
4328
the grid object later.
4330
wxGridUpdateLocker(wxGrid* grid = NULL);
4333
Destructor reenables updates for the grid this object is associated
4336
~wxGridUpdateLocker();
4339
This method can be called if the object had been constructed using the
4340
default constructor. It must not be called more than once.
4342
void Create(wxGrid* grid);
4350
This event class contains information about various grid events.
4352
Notice that all grid event table macros are available in two versions:
4353
@c EVT_GRID_XXX and @c EVT_GRID_CMD_XXX. The only difference between the
4354
two is that the former doesn't allow to specify the grid window identifier
4355
and so takes a single parameter, the event handler, but is not suitable if
4356
there is more than one grid control in the window where the event table is
4357
used (as it would catch the events from all the grids). The version with @c
4358
CMD takes the id as first argument and the event handler as the second one
4359
and so can be used with multiple grids as well. Otherwise there are no
4360
difference between the two and only the versions without the id are
4361
documented below for brevity.
4363
@beginEventTable{wxGridEvent}
4364
@event{EVT_GRID_CELL_CHANGING(func)}
4365
The user is about to change the data in a cell. The new cell value as
4366
string is available from GetString() event object method. This event
4367
can be vetoed if the change is not allowed.
4368
Processes a @c wxEVT_GRID_CELL_CHANGING event type.
4369
@event{EVT_GRID_CELL_CHANGED(func)}
4370
The user changed the data in a cell. The old cell value as string is
4371
available from GetString() event object method. Notice that vetoing
4372
this event still works for backwards compatibility reasons but any new
4373
code should only veto EVT_GRID_CELL_CHANGING event and not this one.
4374
Processes a @c wxEVT_GRID_CELL_CHANGED event type.
4375
@event{EVT_GRID_CELL_LEFT_CLICK(func)}
4376
The user clicked a cell with the left mouse button. Processes a
4377
@c wxEVT_GRID_CELL_LEFT_CLICK event type.
4378
@event{EVT_GRID_CELL_LEFT_DCLICK(func)}
4379
The user double-clicked a cell with the left mouse button. Processes a
4380
@c wxEVT_GRID_CELL_LEFT_DCLICK event type.
4381
@event{EVT_GRID_CELL_RIGHT_CLICK(func)}
4382
The user clicked a cell with the right mouse button. Processes a
4383
@c wxEVT_GRID_CELL_RIGHT_CLICK event type.
4384
@event{EVT_GRID_CELL_RIGHT_DCLICK(func)}
4385
The user double-clicked a cell with the right mouse button. Processes a
4386
@c wxEVT_GRID_CELL_RIGHT_DCLICK event type.
4387
@event{EVT_GRID_EDITOR_HIDDEN(func)}
4388
The editor for a cell was hidden. Processes a
4389
@c wxEVT_GRID_EDITOR_HIDDEN event type.
4390
@event{EVT_GRID_EDITOR_SHOWN(func)}
4391
The editor for a cell was shown. Processes a
4392
@c wxEVT_GRID_EDITOR_SHOWN event type.
4393
@event{EVT_GRID_LABEL_LEFT_CLICK(func)}
4394
The user clicked a label with the left mouse button. Processes a
4395
@c wxEVT_GRID_LABEL_LEFT_CLICK event type.
4396
@event{EVT_GRID_LABEL_LEFT_DCLICK(func)}
4397
The user double-clicked a label with the left mouse button. Processes a
4398
@c wxEVT_GRID_LABEL_LEFT_DCLICK event type.
4399
@event{EVT_GRID_LABEL_RIGHT_CLICK(func)}
4400
The user clicked a label with the right mouse button. Processes a
4401
@c wxEVT_GRID_LABEL_RIGHT_CLICK event type.
4402
@event{EVT_GRID_LABEL_RIGHT_DCLICK(func)}
4403
The user double-clicked a label with the right mouse button. Processes
4404
a @c wxEVT_GRID_LABEL_RIGHT_DCLICK event type.
4405
@event{EVT_GRID_SELECT_CELL(func)}
4406
The given cell was made current, either by user or by the program via a
4407
call to SetGridCursor() or GoToCell(). Processes a
4408
@c wxEVT_GRID_SELECT_CELL event type.
4409
@event{EVT_GRID_COL_MOVE(func)}
4410
The user tries to change the order of the columns in the grid by
4411
dragging the column specified by GetCol(). This event can be vetoed to
4412
either prevent the user from reordering the column change completely
4413
(but notice that if you don't want to allow it at all, you simply
4414
shouldn't call wxGrid::EnableDragColMove() in the first place), vetoed
4415
but handled in some way in the handler, e.g. by really moving the
4416
column to the new position at the associated table level, or allowed to
4417
proceed in which case wxGrid::SetColPos() is used to reorder the
4418
columns display order without affecting the use of the column indices
4420
This event macro corresponds to @c wxEVT_GRID_COL_MOVE event type.
4421
@event{EVT_GRID_COL_SORT(func)}
4422
This event is generated when a column is clicked by the user and its
4423
name is explained by the fact that the custom reaction to a click on a
4424
column is to sort the grid contents by this column. However the grid
4425
itself has no special support for sorting and it's up to the handler of
4426
this event to update the associated table. But if the event is handled
4427
(and not vetoed) the grid supposes that the table was indeed resorted
4428
and updates the column to indicate the new sort order and refreshes
4430
This event macro corresponds to @c wxEVT_GRID_COL_SORT event type.
4434
@category{grid,events}
4436
class wxGridEvent : public wxNotifyEvent
4440
Default constructor.
4444
Constructor for initializing all event attributes.
4446
wxGridEvent(int id, wxEventType type, wxObject* obj,
4447
int row = -1, int col = -1, int x = -1, int y = -1,
4448
bool sel = true, const wxKeyboardState& kbd = wxKeyboardState());
4451
Returns @true if the Alt key was down at the time of the event.
4453
bool AltDown() const;
4456
Returns @true if the Control key was down at the time of the event.
4458
bool ControlDown() const;
4461
Column at which the event occurred.
4463
Notice that for a @c wxEVT_GRID_SELECT_CELL event this column is the
4464
column of the newly selected cell while the previously selected cell
4465
can be retrieved using wxGrid::GetGridCursorCol().
4467
virtual int GetCol();
4470
Position in pixels at which the event occurred.
4472
wxPoint GetPosition();
4475
Row at which the event occurred.
4477
Notice that for a @c wxEVT_GRID_SELECT_CELL event this row is the row
4478
of the newly selected cell while the previously selected cell can be
4479
retrieved using wxGrid::GetGridCursorRow().
4481
virtual int GetRow();
4484
Returns @true if the Meta key was down at the time of the event.
4486
bool MetaDown() const;
4489
Returns @true if the user is selecting grid cells, or @false if
4495
Returns @true if the Shift key was down at the time of the event.
4497
bool ShiftDown() const;
4503
@class wxGridSizeEvent
4505
This event class contains information about a row/column resize event.
4507
@beginEventTable{wxGridSizeEvent}
4508
@event{EVT_GRID_CMD_COL_SIZE(id, func)}
4509
The user resized a column, corresponds to @c wxEVT_GRID_COL_SIZE event
4511
@event{EVT_GRID_CMD_ROW_SIZE(id, func)}
4512
The user resized a row, corresponds to @c wxEVT_GRID_ROW_SIZE event
4514
@event{EVT_GRID_COL_SIZE(func)}
4515
Same as EVT_GRID_CMD_COL_SIZE() but uses `wxID_ANY` id.
4516
@event{EVT_GRID_ROW_SIZE(func)}
4517
Same as EVT_GRID_CMD_ROW_SIZE() but uses `wxID_ANY` id.
4521
@category{grid,events}
4523
class wxGridSizeEvent : public wxNotifyEvent
4527
Default constructor.
4531
Constructor for initializing all event attributes.
4533
wxGridSizeEvent(int id, wxEventType type, wxObject* obj,
4534
int rowOrCol = -1, int x = -1, int y = -1,
4535
const wxKeyboardState& kbd = wxKeyboardState());
4538
Returns @true if the Alt key was down at the time of the event.
4540
bool AltDown() const;
4543
Returns @true if the Control key was down at the time of the event.
4545
bool ControlDown() const;
4548
Position in pixels at which the event occurred.
4550
wxPoint GetPosition();
4553
Row or column at that was resized.
4558
Returns @true if the Meta key was down at the time of the event.
4560
bool MetaDown() const;
4563
Returns @true if the Shift key was down at the time of the event.
4565
bool ShiftDown() const;
4571
@class wxGridRangeSelectEvent
4573
@beginEventTable{wxGridRangeSelectEvent}
4574
@event{EVT_GRID_RANGE_SELECT(func)}
4575
The user selected a group of contiguous cells. Processes a
4576
@c wxEVT_GRID_RANGE_SELECT event type.
4577
@event{EVT_GRID_CMD_RANGE_SELECT(id, func)}
4578
The user selected a group of contiguous cells; variant taking a window
4579
identifier. Processes a @c wxEVT_GRID_RANGE_SELECT event type.
4583
@category{grid,events}
4585
class wxGridRangeSelectEvent : public wxNotifyEvent
4589
Default constructor.
4591
wxGridRangeSelectEvent();
4593
Constructor for initializing all event attributes.
4595
wxGridRangeSelectEvent(int id, wxEventType type,
4597
const wxGridCellCoords& topLeft,
4598
const wxGridCellCoords& bottomRight,
4599
bool sel = true, const wxKeyboardState& kbd = wxKeyboardState());
4602
Returns @true if the Alt key was down at the time of the event.
4604
bool AltDown() const;
4607
Returns @true if the Control key was down at the time of the event.
4609
bool ControlDown() const;
4612
Top left corner of the rectangular area that was (de)selected.
4614
wxGridCellCoords GetBottomRightCoords();
4617
Bottom row of the rectangular area that was (de)selected.
4622
Left column of the rectangular area that was (de)selected.
4627
Right column of the rectangular area that was (de)selected.
4632
Top left corner of the rectangular area that was (de)selected.
4634
wxGridCellCoords GetTopLeftCoords();
4637
Top row of the rectangular area that was (de)selected.
4642
Returns @true if the Meta key was down at the time of the event.
4644
bool MetaDown() const;
4647
Returns @true if the area was selected, @false otherwise.
4652
Returns @true if the Shift key was down at the time of the event.
4654
bool ShiftDown() const;
4660
@class wxGridEditorCreatedEvent
4662
@beginEventTable{wxGridEditorCreatedEvent}
4663
@event{EVT_GRID_EDITOR_CREATED(func)}
4664
The editor for a cell was created. Processes a
4665
@c wxEVT_GRID_EDITOR_CREATED event type.
4666
@event{EVT_GRID_CMD_EDITOR_CREATED(id, func)}
4667
The editor for a cell was created; variant taking a window identifier.
4668
Processes a @c wxEVT_GRID_EDITOR_CREATED event type.
4672
@category{grid,events}
4674
class wxGridEditorCreatedEvent : public wxCommandEvent
4678
Default constructor.
4680
wxGridEditorCreatedEvent();
4682
Constructor for initializing all event attributes.
4684
wxGridEditorCreatedEvent(int id, wxEventType type, wxObject* obj,
4685
int row, int col, wxControl* ctrl);
4688
Returns the column at which the event occurred.
4693
Returns the edit control.
4695
wxControl* GetControl();
4698
Returns the row at which the event occurred.
4703
Sets the column at which the event occurred.
4705
void SetCol(int col);
4708
Sets the edit control.
4710
void SetControl(wxControl* ctrl);
4713
Sets the row at which the event occurred.
4715
void SetRow(int row);