1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxGrid and related classes
4 // Author: wxWidgets team
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 choosen beween 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 choosen beween 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();
1196 @class wxGridTableBase
1198 The almost abstract base class for grid tables.
1200 A grid table is responsible for storing the grid data and, indirectly, grid
1201 cell attributes. The data can be stored in the way most convenient for the
1202 application but has to be provided in string form to wxGrid. It is also
1203 possible to provide cells values in other formats if appropriate, e.g. as
1206 This base class is not quite abstract as it implements a trivial strategy
1207 for storing the attributes by forwarding it to wxGridCellAttrProvider and
1208 also provides stubs for some other functions. However it does have a number
1209 of pure virtual methods which must be implemented in the derived classes.
1211 @see wxGridStringTable
1216 class wxGridTableBase
: public wxObject
1220 Default constructor.
1225 Destructor frees the attribute provider if it was created.
1227 virtual ~wxGridTableBase();
1230 Must be overridden to return the number of rows in the table.
1232 For backwards compatibility reasons, this method is not const.
1233 Use GetRowsCount() instead of it in const methods of derived table
1236 virtual int GetNumberRows() = 0;
1239 Must be overridden to return the number of columns in the table.
1241 For backwards compatibility reasons, this method is not const.
1242 Use GetColsCount() instead of it in const methods of derived table
1245 virtual int GetNumberCols() = 0;
1248 Return the number of rows in the table.
1250 This method is not virtual and is only provided as a convenience for
1251 the derived classes which can't call GetNumberRows() without a
1252 @c const_cast from their const methods.
1254 int GetRowsCount() const;
1257 Return the number of columns in the table.
1259 This method is not virtual and is only provided as a convenience for
1260 the derived classes which can't call GetNumberCols() without a
1261 @c const_cast from their const methods.
1263 int GetColsCount() const;
1267 @name Table Cell Accessors
1272 May be overridden to implement testing for empty cells.
1274 This method is used by the grid to test if the given cell is not used
1275 and so whether a neighbouring cell may overflow into it. By default it
1276 only returns true if the value of the given cell, as returned by
1277 GetValue(), is empty.
1279 virtual bool IsEmptyCell(int row
, int col
);
1282 Same as IsEmptyCell() but taking wxGridCellCoords.
1284 Notice that this method is not virtual, only IsEmptyCell() should be
1287 bool IsEmpty(const wxGridCellCoords
& coords
);
1290 Must be overridden to implement accessing the table values as text.
1292 virtual wxString
GetValue(int row
, int col
) = 0;
1295 Must be overridden to implement setting the table values as text.
1297 virtual void SetValue(int row
, int col
, const wxString
& value
) = 0;
1300 Returns the type of the value in the given cell.
1302 By default all cells are strings and this method returns
1303 @c wxGRID_VALUE_STRING.
1305 virtual wxString
GetTypeName(int row
, int col
);
1308 Returns true if the value of the given cell can be accessed as if it
1309 were of the specified type.
1311 By default the cells can only be accessed as strings. Note that a cell
1312 could be accessible in different ways, e.g. a numeric cell may return
1313 @true for @c wxGRID_VALUE_NUMBER but also for @c wxGRID_VALUE_STRING
1314 indicating that the value can be coerced to a string form.
1316 virtual bool CanGetValueAs(int row
, int col
, const wxString
& typeName
);
1319 Returns true if the value of the given cell can be set as if it were of
1322 @see CanGetValueAs()
1324 virtual bool CanSetValueAs(int row
, int col
, const wxString
& typeName
);
1327 Returns the value of the given cell as a long.
1329 This should only be called if CanGetValueAs() returns @true when called
1330 with @c wxGRID_VALUE_NUMBER argument. Default implementation always
1333 virtual long GetValueAsLong(int row
, int col
);
1336 Returns the value of the given cell as a double.
1338 This should only be called if CanGetValueAs() returns @true when called
1339 with @c wxGRID_VALUE_FLOAT argument. Default implementation always
1342 virtual double GetValueAsDouble(int row
, int col
);
1345 Returns the value of the given cell as a boolean.
1347 This should only be called if CanGetValueAs() returns @true when called
1348 with @c wxGRID_VALUE_BOOL argument. Default implementation always
1351 virtual bool GetValueAsBool(int row
, int col
);
1354 Returns the value of the given cell as a user-defined type.
1356 This should only be called if CanGetValueAs() returns @true when called
1357 with @a typeName. Default implementation always return @NULL.
1359 virtual void *GetValueAsCustom(int row
, int col
, const wxString
& typeName
);
1362 Sets the value of the given cell as a long.
1364 This should only be called if CanSetValueAs() returns @true when called
1365 with @c wxGRID_VALUE_NUMBER argument. Default implementation doesn't do
1368 virtual void SetValueAsLong(int row
, int col
, long value
);
1371 Sets the value of the given cell as a double.
1373 This should only be called if CanSetValueAs() returns @true when called
1374 with @c wxGRID_VALUE_FLOAT argument. Default implementation doesn't do
1377 virtual void SetValueAsDouble(int row
, int col
, double value
);
1380 Sets the value of the given cell as a boolean.
1382 This should only be called if CanSetValueAs() returns @true when called
1383 with @c wxGRID_VALUE_BOOL argument. Default implementation doesn't do
1386 virtual void SetValueAsBool( int row
, int col
, bool value
);
1389 Sets the value of the given cell as a user-defined type.
1391 This should only be called if CanSetValueAs() returns @true when called
1392 with @a typeName. Default implementation doesn't do anything.
1394 virtual void SetValueAsCustom(int row
, int col
, const wxString
& typeName
,
1401 Called by the grid when the table is associated with it.
1403 The default implementation stores the pointer and returns it from its
1404 GetView() and so only makes sense if the table cannot be associated
1405 with more than one grid at a time.
1407 virtual void SetView(wxGrid
*grid
);
1410 Returns the last grid passed to SetView().
1412 virtual wxGrid
*GetView() const;
1416 @name Table Structure Modifiers
1418 Notice that none of these functions are pure virtual as they don't have
1419 to be implemented if the table structure is never modified after
1420 creation, i.e. neither rows nor columns are never added or deleted but
1421 that you do need to implement them if they are called, i.e. if your
1422 code either calls them directly or uses the matching wxGrid methods, as
1423 by default they simply do nothing which is definitely inappropriate.
1428 Clear the table contents.
1430 This method is used by wxGrid::ClearGrid().
1432 virtual void Clear();
1435 Insert additional rows into the table.
1438 The position of the first new row.
1440 The number of rows to insert.
1442 virtual bool InsertRows(size_t pos
= 0, size_t numRows
= 1);
1445 Append additional rows at the end of the table.
1447 This method is provided in addition to InsertRows() as some data models
1448 may only support appending rows to them but not inserting them at
1449 arbitrary locations. In such case you may implement this method only
1450 and leave InsertRows() unimplemented.
1453 The number of rows to add.
1455 virtual bool AppendRows(size_t numRows
= 1);
1458 Delete rows from the table.
1461 The first row to delete.
1463 The number of rows to delete.
1465 virtual bool DeleteRows(size_t pos
= 0, size_t numRows
= 1);
1468 Exactly the same as InsertRows() but for columns.
1470 virtual bool InsertCols(size_t pos
= 0, size_t numCols
= 1);
1473 Exactly the same as AppendRows() but for columns.
1475 virtual bool AppendCols(size_t numCols
= 1);
1478 Exactly the same as DeleteRows() but for columns.
1480 virtual bool DeleteCols(size_t pos
= 0, size_t numCols
= 1);
1485 @name Table Row and Column Labels
1487 By default the numbers are used for labeling rows and Latin letters for
1488 labeling columns. If the table has more than 26 columns, the pairs of
1489 letters are used starting from the 27-th one and so on, i.e. the
1490 sequence of labels is A, B, ..., Z, AA, AB, ..., AZ, BA, ..., ..., ZZ,
1496 Return the label of the specified row.
1498 virtual wxString
GetRowLabelValue(int row
);
1501 Return the label of the specified column.
1503 virtual wxString
GetColLabelValue(int col
);
1506 Set the given label for the specified row.
1508 The default version does nothing, i.e. the label is not stored. You
1509 must override this method in your derived class if you wish
1510 wxGrid::SetRowLabelValue() to work.
1512 virtual void SetRowLabelValue(int row
, const wxString
& label
);
1515 Exactly the same as SetRowLabelValue() but for columns.
1517 virtual void SetColLabelValue(int col
, const wxString
& label
);
1523 @name Attributes Management
1525 By default the attributes management is delegated to
1526 wxGridCellAttrProvider class. You may override the methods in this
1527 section to handle the attributes directly if, for example, they can be
1528 computed from the cell values.
1533 Associate this attributes provider with the table.
1535 The table takes ownership of @a attrProvider pointer and will delete it
1536 when it doesn't need it any more. The pointer can be @NULL, however
1537 this won't disable attributes management in the table but will just
1538 result in a default attributes being recreated the next time any of the
1539 other functions in this section is called. To completely disable the
1540 attributes support, should this be needed, you need to override
1541 CanHaveAttributes() to return @false.
1543 void SetAttrProvider(wxGridCellAttrProvider
*attrProvider
);
1546 Returns the attribute provider currently being used.
1548 This function may return @NULL if the attribute provider hasn't been
1549 neither associated with this table by SetAttrProvider() nor created on
1550 demand by any other methods.
1552 wxGridCellAttrProvider
*GetAttrProvider() const;
1555 Return the attribute for the given cell.
1557 By default this function is simply forwarded to
1558 wxGridCellAttrProvider::GetAttr() but it may be overridden to handle
1559 attributes directly in the table.
1561 virtual wxGridCellAttr
*GetAttr(int row
, int col
,
1562 wxGridCellAttr::wxAttrKind kind
);
1565 Set attribute of the specified cell.
1567 By default this function is simply forwarded to
1568 wxGridCellAttrProvider::SetAttr().
1570 The table takes ownership of @a attr, i.e. will call DecRef() on it.
1572 virtual void SetAttr(wxGridCellAttr
* attr
, int row
, int col
);
1575 Set attribute of the specified row.
1577 By default this function is simply forwarded to
1578 wxGridCellAttrProvider::SetRowAttr().
1580 The table takes ownership of @a attr, i.e. will call DecRef() on it.
1582 virtual void SetRowAttr(wxGridCellAttr
*attr
, int row
);
1585 Set attribute of the specified column.
1587 By default this function is simply forwarded to
1588 wxGridCellAttrProvider::SetColAttr().
1590 The table takes ownership of @a attr, i.e. will call DecRef() on it.
1592 virtual void SetColAttr(wxGridCellAttr
*attr
, int col
);
1597 Returns true if this table supports attributes or false otherwise.
1599 By default, the table automatically creates a wxGridCellAttrProvider
1600 when this function is called if it had no attribute provider before and
1603 virtual bool CanHaveAttributes();
1607 @class wxGridSizesInfo
1609 wxGridSizesInfo stores information about sizes of all wxGrid rows or
1612 It assumes that most of the rows or columns (which are both called elements
1613 here as the difference between them doesn't matter at this class level)
1614 have the default size and so stores it separately. And it uses a wxHashMap
1615 to store the sizes of all elements which have the non-default size.
1617 This structure is particularly useful for serializing the sizes of all
1618 wxGrid elements at once.
1623 struct wxGridSizesInfo
1626 Default constructor.
1628 m_sizeDefault and m_customSizes must be initialized later.
1635 This constructor is used by wxGrid::GetRowSizes() and GetColSizes()
1636 methods. User code will usually use the default constructor instead.
1639 The default element size.
1641 Array containing the sizes of @em all elements, including those
1642 which have the default size.
1644 wxGridSizesInfo(int defSize
, const wxArrayInt
& allSizes
);
1647 Get the element size.
1650 The index of the element.
1652 The size for this element, using m_customSizes if @a pos is in it
1653 or m_sizeDefault otherwise.
1655 int GetSize(unsigned pos
) const;
1662 Map with element indices as keys and their sizes as values.
1664 This map only contains the elements with non-default size.
1666 wxUnsignedToIntHashMap m_customSizes
;
1673 wxGrid and its related classes are used for displaying and editing tabular
1674 data. They provide a rich set of features for display, editing, and
1675 interacting with a variety of data sources. For simple applications, and to
1676 help you get started, wxGrid is the only class you need to refer to
1677 directly. It will set up default instances of the other classes and manage
1678 them for you. For more complex applications you can derive your own classes
1679 for custom grid views, grid data tables, cell editors and renderers. The
1680 @ref overview_grid has examples of simple and more complex applications,
1681 explains the relationship between the various grid classes and has a
1682 summary of the keyboard shortcuts and mouse functions provided by wxGrid.
1684 A wxGridTableBase class holds the actual data to be displayed by a wxGrid
1685 class. One or more wxGrid classes may act as a view for one table class.
1686 The default table class is called wxGridStringTable and holds an array of
1687 strings. An instance of such a class is created by CreateGrid().
1689 wxGridCellRenderer is the abstract base class for rendering contents in a
1690 cell. The following renderers are predefined:
1692 - wxGridCellBoolRenderer
1693 - wxGridCellFloatRenderer
1694 - wxGridCellNumberRenderer
1695 - wxGridCellStringRenderer
1697 The look of a cell can be further defined using wxGridCellAttr. An object
1698 of this type may be returned by wxGridTableBase::GetAttr().
1700 wxGridCellEditor is the abstract base class for editing the value of a
1701 cell. The following editors are predefined:
1703 - wxGridCellBoolEditor
1704 - wxGridCellChoiceEditor
1705 - wxGridCellFloatEditor
1706 - wxGridCellNumberEditor
1707 - wxGridCellTextEditor
1709 Please see wxGridEvent, wxGridSizeEvent, wxGridRangeSelectEvent, and
1710 wxGridEditorCreatedEvent for the documentation of all event types you can
1716 @see @ref overview_grid, wxGridUpdateLocker
1718 class wxGrid
: public wxScrolledWindow
1723 Different selection modes supported by the grid.
1725 enum wxGridSelectionModes
1728 The default selection mode allowing selection of the individual
1729 cells as well as of the entire rows and columns.
1734 The selection mode allowing the selection of the entire rows only.
1736 The user won't be able to select any cells or columns in this mode.
1741 The selection mode allowing the selection of the entire columns only.
1743 The user won't be able to select any cells or rows in this mode.
1745 wxGridSelectColumns
,
1748 The selection mode allowing the user to select either the entire
1749 columns or the entire rows but not individual cells nor blocks.
1751 Notice that while this constant is defined as @code
1752 wxGridSelectColumns | wxGridSelectRows @endcode this doesn't mean
1753 that all the other combinations are valid -- at least currently
1758 wxGridSelectRowsOrColumns
1762 Return values for GetCellSize().
1768 /// This cell is inside a span covered by another cell.
1769 CellSpan_Inside
= -1,
1771 /// This is a normal, non-spanning cell.
1774 /// This cell spans several physical wxGrid cells.
1779 @name Constructors and Initialization
1784 Default constructor.
1786 You must call Create() to really create the grid window and also call
1787 CreateGrid() or SetTable() to initialize the grid contents.
1791 Constructor creating the grid window.
1793 You must call either CreateGrid() or SetTable() to initialize the grid
1794 contents before using it.
1796 wxGrid(wxWindow
* parent
, wxWindowID id
,
1797 const wxPoint
& pos
= wxDefaultPosition
,
1798 const wxSize
& size
= wxDefaultSize
,
1799 long style
= wxWANTS_CHARS
,
1800 const wxString
& name
= wxGridNameStr
);
1805 This will also destroy the associated grid table unless you passed a
1806 table object to the grid and specified that the grid should not take
1807 ownership of the table (see SetTable()).
1812 Creates the grid window for an object initialized using the default
1815 You must call either CreateGrid() or SetTable() to initialize the grid
1816 contents before using it.
1818 bool Create(wxWindow
* parent
, wxWindowID id
,
1819 const wxPoint
& pos
= wxDefaultPosition
,
1820 const wxSize
& size
= wxDefaultSize
,
1821 long style
= wxWANTS_CHARS
,
1822 const wxString
& name
= wxGridNameStr
);
1825 Creates a grid with the specified initial number of rows and columns.
1827 Call this directly after the grid constructor. When you use this
1828 function wxGrid will create and manage a simple table of string values
1829 for you. All of the grid data will be stored in memory.
1831 For applications with more complex data types or relationships, or for
1832 dealing with very large datasets, you should derive your own grid table
1833 class and pass a table object to the grid with SetTable().
1835 bool CreateGrid(int numRows
, int numCols
,
1836 wxGridSelectionModes selmode
= wxGridSelectCells
);
1839 Passes a pointer to a custom grid table to be used by the grid.
1841 This should be called after the grid constructor and before using the
1842 grid object. If @a takeOwnership is set to @true then the table will be
1843 deleted by the wxGrid destructor.
1845 Use this function instead of CreateGrid() when your application
1846 involves complex or non-string data or data sets that are too large to
1847 fit wholly in memory.
1849 bool SetTable(wxGridTableBase
* table
, bool takeOwnership
= false,
1850 wxGridSelectionModes selmode
= wxGridSelectCells
);
1856 @name Grid Line Formatting
1861 Turns the drawing of grid lines on or off.
1863 void EnableGridLines(bool enable
= true);
1866 Returns the pen used for vertical grid lines.
1868 This virtual function may be overridden in derived classes in order to
1869 change the appearance of individual grid lines for the given column
1872 See GetRowGridLinePen() for an example.
1874 virtual wxPen
GetColGridLinePen(int col
);
1877 Returns the pen used for grid lines.
1879 This virtual function may be overridden in derived classes in order to
1880 change the appearance of grid lines. Note that currently the pen width
1883 @see GetColGridLinePen(), GetRowGridLinePen()
1885 virtual wxPen
GetDefaultGridLinePen();
1888 Returns the colour used for grid lines.
1890 @see GetDefaultGridLinePen()
1892 wxColour
GetGridLineColour() const;
1895 Returns the pen used for horizontal grid lines.
1897 This virtual function may be overridden in derived classes in order to
1898 change the appearance of individual grid line for the given @a row.
1902 // in a grid displaying music notation, use a solid black pen between
1903 // octaves (C0=row 127, C1=row 115 etc.)
1904 wxPen MidiGrid::GetRowGridLinePen(int row)
1906 if ( row % 12 == 7 )
1907 return wxPen(*wxBLACK, 1, wxSOLID);
1909 return GetDefaultGridLinePen();
1913 virtual wxPen
GetRowGridLinePen(int row
);
1916 Returns @true if drawing of grid lines is turned on, @false otherwise.
1918 bool GridLinesEnabled() const;
1921 Sets the colour used to draw grid lines.
1923 void SetGridLineColour(const wxColour
& colour
);
1929 @name Label Values and Formatting
1934 Sets the arguments to the current column label alignment values.
1936 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
1937 or @c wxALIGN_RIGHT.
1939 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
1942 void GetColLabelAlignment(int* horiz
, int* vert
) const;
1945 Returns the orientation of the column labels (either @c wxHORIZONTAL or
1948 int GetColLabelTextOrientation() const;
1951 Returns the specified column label.
1953 The default grid table class provides column labels of the form
1954 A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can
1955 override wxGridTableBase::GetColLabelValue() to provide your own
1958 wxString
GetColLabelValue(int col
) const;
1961 Returns the colour used for the background of row and column labels.
1963 wxColour
GetLabelBackgroundColour() const;
1966 Returns the font used for row and column labels.
1968 wxFont
GetLabelFont() const;
1971 Returns the colour used for row and column label text.
1973 wxColour
GetLabelTextColour() const;
1976 Returns the alignment used for row labels.
1978 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
1979 or @c wxALIGN_RIGHT.
1981 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
1984 void GetRowLabelAlignment(int* horiz
, int* vert
) const;
1987 Returns the specified row label.
1989 The default grid table class provides numeric row labels. If you are
1990 using a custom grid table you can override
1991 wxGridTableBase::GetRowLabelValue() to provide your own labels.
1993 wxString
GetRowLabelValue(int row
) const;
1996 Hides the column labels by calling SetColLabelSize() with a size of 0.
1997 Show labels again by calling that method with a width greater than 0.
1999 void HideColLabels();
2002 Hides the row labels by calling SetRowLabelSize() with a size of 0.
2004 The labels can be shown again by calling SetRowLabelSize() with a width
2007 void HideRowLabels();
2010 Sets the horizontal and vertical alignment of column label text.
2012 Horizontal alignment should be one of @c wxALIGN_LEFT,
2013 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
2014 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
2016 void SetColLabelAlignment(int horiz
, int vert
);
2019 Sets the orientation of the column labels (either @c wxHORIZONTAL or
2022 void SetColLabelTextOrientation(int textOrientation
);
2025 Set the value for the given column label.
2027 If you are using a custom grid table you must override
2028 wxGridTableBase::SetColLabelValue() for this to have any effect.
2030 void SetColLabelValue(int col
, const wxString
& value
);
2033 Sets the background colour for row and column labels.
2035 void SetLabelBackgroundColour(const wxColour
& colour
);
2038 Sets the font for row and column labels.
2040 void SetLabelFont(const wxFont
& font
);
2043 Sets the colour for row and column label text.
2045 void SetLabelTextColour(const wxColour
& colour
);
2048 Sets the horizontal and vertical alignment of row label text.
2050 Horizontal alignment should be one of @c wxALIGN_LEFT,
2051 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
2052 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
2054 void SetRowLabelAlignment(int horiz
, int vert
);
2057 Sets the value for the given row label.
2059 If you are using a derived grid table you must override
2060 wxGridTableBase::SetRowLabelValue() for this to have any effect.
2062 void SetRowLabelValue(int row
, const wxString
& value
);
2065 Call this in order to make the column labels use a native look by using
2066 wxRendererNative::DrawHeaderButton() internally.
2068 There is no equivalent method for drawing row columns as there is not
2069 native look for that. This option is useful when using wxGrid for
2070 displaying tables and not as a spread-sheet.
2072 @see UseNativeColHeader()
2074 void SetUseNativeColLabels(bool native
= true);
2077 Enable the use of native header window for column labels.
2079 If this function is called with @true argument, a wxHeaderCtrl is used
2080 instead to display the column labels instead of drawing them in wxGrid
2081 code itself. This has the advantage of making the grid look and feel
2082 perfectly the same as native applications (using SetUseNativeColLabels()
2083 the grid can be made to look more natively but it still doesn't feel
2084 natively, notably the column resizing and dragging still works slightly
2085 differently as it is implemented in wxWidgets itself) but results in
2086 different behaviour for column and row headers, for which there is no
2087 equivalent function, and, most importantly, is unsuitable for grids
2088 with huge numbers of columns as wxHeaderCtrl doesn't support virtual
2089 mode. Because of this, by default the grid does not use the native
2090 header control but you should call this function to enable it if you
2091 are using the grid to display tabular data and don't have thousands of
2094 Another difference between the default behaviour and the native header
2095 behaviour is that the latter provides the user with a context menu
2096 (which appears on right clicking the header) allowing to rearrange the
2097 grid columns if CanDragColMove() returns @true. If you want to prevent
2098 this from happening for some reason, you need to define a handler for
2099 @c wxEVT_GRID_LABEL_RIGHT_CLICK event which simply does nothing (in
2100 particular doesn't skip the event) as this will prevent the default
2101 right click handling from working.
2103 Also note that currently @c wxEVT_GRID_LABEL_RIGHT_DCLICK event is not
2104 generated for the column labels if the native columns header is used
2105 (but this limitation could possibly be lifted in the future).
2107 void UseNativeColHeader(bool native
= true);
2113 @name Cell Formatting
2115 Note that wxGridCellAttr can be used alternatively to most of these
2116 methods. See the "Attributes Management" of wxGridTableBase.
2121 Sets the arguments to the horizontal and vertical text alignment values
2122 for the grid cell at the specified location.
2124 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2125 or @c wxALIGN_RIGHT.
2127 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2130 void GetCellAlignment(int row
, int col
, int* horiz
, int* vert
) const;
2133 Returns the background colour of the cell at the specified location.
2135 wxColour
GetCellBackgroundColour(int row
, int col
) const;
2138 Returns the font for text in the grid cell at the specified location.
2140 wxFont
GetCellFont(int row
, int col
) const;
2143 Returns the text colour for the grid cell at the specified location.
2145 wxColour
GetCellTextColour(int row
, int col
) const;
2148 Returns the default cell alignment.
2150 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2151 or @c wxALIGN_RIGHT.
2153 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2156 @see SetDefaultCellAlignment()
2158 void GetDefaultCellAlignment(int* horiz
, int* vert
) const;
2161 Returns the current default background colour for grid cells.
2163 wxColour
GetDefaultCellBackgroundColour() const;
2166 Returns the current default font for grid cell text.
2168 wxFont
GetDefaultCellFont() const;
2171 Returns the current default colour for grid cell text.
2173 wxColour
GetDefaultCellTextColour() const;
2176 Sets the horizontal and vertical alignment for grid cell text at the
2179 Horizontal alignment should be one of @c wxALIGN_LEFT,
2180 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT.
2182 Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
2183 or @c wxALIGN_BOTTOM.
2185 void SetCellAlignment(int row
, int col
, int horiz
, int vert
);
2187 Sets the horizontal and vertical alignment for grid cell text at the
2190 Horizontal alignment should be one of @c wxALIGN_LEFT,
2191 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT.
2193 Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
2194 or @c wxALIGN_BOTTOM.
2196 void SetCellAlignment(int align
, int row
, int col
);
2199 Set the background colour for the given cell or all cells by default.
2201 void SetCellBackgroundColour(int row
, int col
, const wxColour
& colour
);
2204 Sets the font for text in the grid cell at the specified location.
2206 void SetCellFont(int row
, int col
, const wxFont
& font
);
2209 Sets the text colour for the given cell.
2211 void SetCellTextColour(int row
, int col
, const wxColour
& colour
);
2213 Sets the text colour for the given cell.
2215 void SetCellTextColour(const wxColour
& val
, int row
, int col
);
2217 Sets the text colour for all cells by default.
2219 void SetCellTextColour(const wxColour
& colour
);
2222 Sets the default horizontal and vertical alignment for grid cell text.
2224 Horizontal alignment should be one of @c wxALIGN_LEFT,
2225 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
2226 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
2228 void SetDefaultCellAlignment(int horiz
, int vert
);
2231 Sets the default background colour for grid cells.
2233 void SetDefaultCellBackgroundColour(const wxColour
& colour
);
2236 Sets the default font to be used for grid cell text.
2238 void SetDefaultCellFont(const wxFont
& font
);
2241 Sets the current default colour for grid cell text.
2243 void SetDefaultCellTextColour(const wxColour
& colour
);
2249 @name Cell Values, Editors, and Renderers
2251 Note that wxGridCellAttr can be used alternatively to most of these
2252 methods. See the "Attributes Management" of wxGridTableBase.
2257 Returns @true if the in-place edit control for the current grid cell
2258 can be used and @false otherwise.
2260 This function always returns @false for the read-only cells.
2262 bool CanEnableCellControl() const;
2265 Disables in-place editing of grid cells.
2267 Equivalent to calling EnableCellEditControl(@false).
2269 void DisableCellEditControl();
2272 Enables or disables in-place editing of grid cell data.
2274 The grid will issue either a @c wxEVT_GRID_EDITOR_SHOWN or
2275 @c wxEVT_GRID_EDITOR_HIDDEN event.
2277 void EnableCellEditControl(bool enable
= true);
2280 Makes the grid globally editable or read-only.
2282 If the edit argument is @false this function sets the whole grid as
2283 read-only. If the argument is @true the grid is set to the default
2284 state where cells may be editable. In the default state you can set
2285 single grid cells and whole rows and columns to be editable or
2286 read-only via wxGridCellAttr::SetReadOnly(). For single cells you
2287 can also use the shortcut function SetReadOnly().
2289 For more information about controlling grid cell attributes see the
2290 wxGridCellAttr class and the @ref overview_grid.
2292 void EnableEditing(bool edit
);
2295 Returns a pointer to the editor for the cell at the specified location.
2297 See wxGridCellEditor and the @ref overview_grid for more information
2298 about cell editors and renderers.
2300 The caller must call DecRef() on the returned pointer.
2302 wxGridCellEditor
* GetCellEditor(int row
, int col
) const;
2305 Returns a pointer to the renderer for the grid cell at the specified
2308 See wxGridCellRenderer and the @ref overview_grid for more information
2309 about cell editors and renderers.
2311 The caller must call DecRef() on the returned pointer.
2313 wxGridCellRenderer
* GetCellRenderer(int row
, int col
) const;
2316 Returns the string contained in the cell at the specified location.
2318 For simple applications where a grid object automatically uses a
2319 default grid table of string values you use this function together with
2320 SetCellValue() to access cell values. For more complex applications
2321 where you have derived your own grid table class that contains various
2322 data types (e.g. numeric, boolean or user-defined custom types) then
2323 you only use this function for those cells that contain string values.
2325 See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
2328 wxString
GetCellValue(int row
, int col
) const;
2330 Returns the string contained in the cell at the specified location.
2332 For simple applications where a grid object automatically uses a
2333 default grid table of string values you use this function together with
2334 SetCellValue() to access cell values. For more complex applications
2335 where you have derived your own grid table class that contains various
2336 data types (e.g. numeric, boolean or user-defined custom types) then
2337 you only use this function for those cells that contain string values.
2339 See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
2342 wxString
GetCellValue(const wxGridCellCoords
& coords
) const;
2345 Returns a pointer to the current default grid cell editor.
2347 See wxGridCellEditor and the @ref overview_grid for more information
2348 about cell editors and renderers.
2350 wxGridCellEditor
* GetDefaultEditor() const;
2353 Returns the default editor for the specified cell.
2355 The base class version returns the editor appropriate for the current
2356 cell type but this method may be overridden in the derived classes to
2357 use custom editors for some cells by default.
2359 Notice that the same may be achieved in a usually simpler way by
2360 associating a custom editor with the given cell or cells.
2362 The caller must call DecRef() on the returned pointer.
2364 virtual wxGridCellEditor
* GetDefaultEditorForCell(int row
, int col
) const;
2366 Returns the default editor for the specified cell.
2368 The base class version returns the editor appropriate for the current
2369 cell type but this method may be overridden in the derived classes to
2370 use custom editors for some cells by default.
2372 Notice that the same may be achieved in a usually simpler way by
2373 associating a custom editor with the given cell or cells.
2375 The caller must call DecRef() on the returned pointer.
2377 wxGridCellEditor
* GetDefaultEditorForCell(const wxGridCellCoords
& c
) const;
2380 Returns the default editor for the cells containing values of the given
2383 The base class version returns the editor which was associated with the
2384 specified @a typeName when it was registered RegisterDataType() but
2385 this function may be overridden to return something different. This
2386 allows to override an editor used for one of the standard types.
2388 The caller must call DecRef() on the returned pointer.
2390 virtual wxGridCellEditor
* GetDefaultEditorForType(const wxString
& typeName
) const;
2393 Returns a pointer to the current default grid cell renderer.
2395 See wxGridCellRenderer and the @ref overview_grid for more information
2396 about cell editors and renderers.
2398 The caller must call DecRef() on the returned pointer.
2400 wxGridCellRenderer
* GetDefaultRenderer() const;
2403 Returns the default renderer for the given cell.
2405 The base class version returns the renderer appropriate for the current
2406 cell type but this method may be overridden in the derived classes to
2407 use custom renderers for some cells by default.
2409 The caller must call DecRef() on the returned pointer.
2411 virtual wxGridCellRenderer
* GetDefaultRendererForCell(int row
, int col
) const;
2414 Returns the default renderer for the cell containing values of the
2417 @see GetDefaultEditorForType()
2419 virtual wxGridCellRenderer
* GetDefaultRendererForType(const wxString
& typeName
) const;
2422 Hides the in-place cell edit control.
2424 void HideCellEditControl();
2427 Returns @true if the in-place edit control is currently enabled.
2429 bool IsCellEditControlEnabled() const;
2432 Returns @true if the current cell is read-only.
2434 @see SetReadOnly(), IsReadOnly()
2436 bool IsCurrentCellReadOnly() const;
2439 Returns @false if the whole grid has been set as read-only or @true
2442 See EnableEditing() for more information about controlling the editing
2443 status of grid cells.
2445 bool IsEditable() const;
2448 Returns @true if the cell at the specified location can't be edited.
2450 @see SetReadOnly(), IsCurrentCellReadOnly()
2452 bool IsReadOnly(int row
, int col
) const;
2455 Register a new data type.
2457 The data types allow to naturally associate specific renderers and
2458 editors to the cells containing values of the given type. For example,
2459 the grid automatically registers a data type with the name
2460 @c wxGRID_VALUE_STRING which uses wxGridCellStringRenderer and
2461 wxGridCellTextEditor as its renderer and editor respectively -- this is
2462 the data type used by all the cells of the default wxGridStringTable,
2463 so this renderer and editor are used by default for all grid cells.
2465 However if a custom table returns @c wxGRID_VALUE_BOOL from its
2466 wxGridTableBase::GetTypeName() method, then wxGridCellBoolRenderer and
2467 wxGridCellBoolEditor are used for it because the grid also registers a
2468 boolean data type with this name.
2470 And as this mechanism is completely generic, you may register your own
2471 data types using your own custom renderers and editors. Just remember
2472 that the table must identify a cell as being of the given type for them
2473 to be used for this cell.
2476 Name of the new type. May be any string, but if the type name is
2477 the same as the name of an already registered type, including one
2478 of the standard ones (which are @c wxGRID_VALUE_STRING, @c
2479 wxGRID_VALUE_BOOL, @c wxGRID_VALUE_NUMBER, @c wxGRID_VALUE_FLOAT
2480 and @c wxGRID_VALUE_CHOICE), then the new registration information
2481 replaces the previously used renderer and editor.
2483 The renderer to use for the cells of this type. Its ownership is
2484 taken by the grid, i.e. it will call DecRef() on this pointer when
2485 it doesn't need it any longer.
2487 The editor to use for the cells of this type. Its ownership is also
2490 void RegisterDataType(const wxString
& typeName
,
2491 wxGridCellRenderer
* renderer
,
2492 wxGridCellEditor
* editor
);
2495 Sets the value of the current grid cell to the current in-place edit
2498 This is called automatically when the grid cursor moves from the
2499 current cell to a new cell. It is also a good idea to call this
2500 function when closing a grid since any edits to the final cell location
2501 will not be saved otherwise.
2503 void SaveEditControlValue();
2506 Sets the editor for the grid cell at the specified location.
2508 The grid will take ownership of the pointer.
2510 See wxGridCellEditor and the @ref overview_grid for more information
2511 about cell editors and renderers.
2513 void SetCellEditor(int row
, int col
, wxGridCellEditor
* editor
);
2516 Sets the renderer for the grid cell at the specified location.
2518 The grid will take ownership of the pointer.
2520 See wxGridCellRenderer and the @ref overview_grid for more information
2521 about cell editors and renderers.
2523 void SetCellRenderer(int row
, int col
, wxGridCellRenderer
* renderer
);
2526 Sets the string value for the cell at the specified location.
2528 For simple applications where a grid object automatically uses a
2529 default grid table of string values you use this function together with
2530 GetCellValue() to access cell values. For more complex applications
2531 where you have derived your own grid table class that contains various
2532 data types (e.g. numeric, boolean or user-defined custom types) then
2533 you only use this function for those cells that contain string values.
2535 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2538 void SetCellValue(int row
, int col
, const wxString
& s
);
2540 Sets the string value for the cell at the specified location.
2542 For simple applications where a grid object automatically uses a
2543 default grid table of string values you use this function together with
2544 GetCellValue() to access cell values. For more complex applications
2545 where you have derived your own grid table class that contains various
2546 data types (e.g. numeric, boolean or user-defined custom types) then
2547 you only use this function for those cells that contain string values.
2549 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2552 void SetCellValue(const wxGridCellCoords
& coords
, const wxString
& s
);
2554 @deprecated Please use SetCellValue(int,int,const wxString&) or
2555 SetCellValue(const wxGridCellCoords&,const wxString&)
2558 Sets the string value for the cell at the specified location.
2560 For simple applications where a grid object automatically uses a
2561 default grid table of string values you use this function together with
2562 GetCellValue() to access cell values. For more complex applications
2563 where you have derived your own grid table class that contains various
2564 data types (e.g. numeric, boolean or user-defined custom types) then
2565 you only use this function for those cells that contain string values.
2567 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2570 void SetCellValue(const wxString
& val
, int row
, int col
);
2573 Sets the specified column to display boolean values.
2575 @see SetColFormatCustom()
2577 void SetColFormatBool(int col
);
2580 Sets the specified column to display data in a custom format.
2582 This method provides an alternative to defining a custom grid table
2583 which would return @a typeName from its GetTypeName() method for the
2584 cells in this column: while it doesn't really change the type of the
2585 cells in this column, it does associate the renderer and editor used
2586 for the cells of the specified type with them.
2588 See the @ref overview_grid for more information on working with custom
2591 void SetColFormatCustom(int col
, const wxString
& typeName
);
2594 Sets the specified column to display floating point values with the
2595 given width and precision.
2597 @see SetColFormatCustom()
2599 void SetColFormatFloat(int col
, int width
= -1, int precision
= -1);
2602 Sets the specified column to display integer values.
2604 @see SetColFormatCustom()
2606 void SetColFormatNumber(int col
);
2609 Sets the default editor for grid cells.
2611 The grid will take ownership of the pointer.
2613 See wxGridCellEditor and the @ref overview_grid for more information
2614 about cell editors and renderers.
2616 void SetDefaultEditor(wxGridCellEditor
* editor
);
2619 Sets the default renderer for grid cells.
2621 The grid will take ownership of the pointer.
2623 See wxGridCellRenderer and the @ref overview_grid for more information
2624 about cell editors and renderers.
2626 void SetDefaultRenderer(wxGridCellRenderer
* renderer
);
2629 Makes the cell at the specified location read-only or editable.
2633 void SetReadOnly(int row
, int col
, bool isReadOnly
= true);
2636 Displays the in-place cell edit control for the current cell.
2638 void ShowCellEditControl();
2644 @name Column and Row Sizes
2646 @see @ref overview_grid_resizing
2651 Automatically sets the height and width of all rows and columns to fit
2657 Automatically adjusts width of the column to fit its label.
2659 void AutoSizeColLabelSize(int col
);
2662 Automatically sizes the column to fit its contents. If @a setAsMin is
2663 @true the calculated width will also be set as the minimal width for
2666 void AutoSizeColumn(int col
, bool setAsMin
= true);
2669 Automatically sizes all columns to fit their contents. If @a setAsMin
2670 is @true the calculated widths will also be set as the minimal widths
2673 void AutoSizeColumns(bool setAsMin
= true);
2676 Automatically sizes the row to fit its contents. If @a setAsMin is
2677 @true the calculated height will also be set as the minimal height for
2680 void AutoSizeRow(int row
, bool setAsMin
= true);
2683 Automatically adjusts height of the row to fit its label.
2685 void AutoSizeRowLabelSize(int col
);
2688 Automatically sizes all rows to fit their contents. If @a setAsMin is
2689 @true the calculated heights will also be set as the minimal heights
2692 void AutoSizeRows(bool setAsMin
= true);
2695 Returns the current height of the column labels.
2697 int GetColLabelSize() const;
2700 Returns the minimal width to which a column may be resized.
2702 Use SetColMinimalAcceptableWidth() to change this value globally or
2703 SetColMinimalWidth() to do it for individual columns.
2705 @see GetRowMinimalAcceptableHeight()
2707 int GetColMinimalAcceptableWidth() const;
2710 Returns the width of the specified column.
2712 int GetColSize(int col
) const;
2715 Returns @true if the specified column is not currently hidden.
2717 bool IsColShown(int col
) const;
2720 Returns the default height for column labels.
2722 int GetDefaultColLabelSize() const;
2725 Returns the current default width for grid columns.
2727 int GetDefaultColSize() const;
2730 Returns the default width for the row labels.
2732 int GetDefaultRowLabelSize() const;
2735 Returns the current default height for grid rows.
2737 int GetDefaultRowSize() const;
2740 Returns the minimal size to which rows can be resized.
2742 Use SetRowMinimalAcceptableHeight() to change this value globally or
2743 SetRowMinimalHeight() to do it for individual cells.
2745 @see GetColMinimalAcceptableWidth()
2747 int GetRowMinimalAcceptableHeight() const;
2750 Returns the current width of the row labels.
2752 int GetRowLabelSize() const;
2755 Returns the height of the specified row.
2757 int GetRowSize(int row
) const;
2760 Returns @true if the specified row is not currently hidden.
2762 bool IsRowShown(int row
) const;
2765 Sets the height of the column labels.
2767 If @a height equals to @c wxGRID_AUTOSIZE then height is calculated
2768 automatically so that no label is truncated. Note that this could be
2769 slow for a large table.
2771 void SetColLabelSize(int height
);
2774 Sets the minimal @a width to which the user can resize columns.
2776 @see GetColMinimalAcceptableWidth()
2778 void SetColMinimalAcceptableWidth(int width
);
2781 Sets the minimal @a width for the specified column @a col.
2783 It is usually best to call this method during grid creation as calling
2784 it later will not resize the column to the given minimal width even if
2785 it is currently narrower than it.
2787 @a width must be greater than the minimal acceptable column width as
2788 returned by GetColMinimalAcceptableWidth().
2790 void SetColMinimalWidth(int col
, int width
);
2793 Sets the width of the specified column.
2798 The new column width in pixels, 0 to hide the column or -1 to fit
2799 the column width to its label width.
2801 void SetColSize(int col
, int width
);
2804 Hides the specified column.
2806 To show the column later you need to call SetColSize() with non-0
2812 void HideCol(int col
);
2815 Shows the previously hidden column by resizing it to non-0 size.
2817 @see HideCol(), SetColSize()
2819 void ShowCol(int col
);
2823 Sets the default width for columns in the grid.
2825 This will only affect columns subsequently added to the grid unless
2826 @a resizeExistingCols is @true.
2828 If @a width is less than GetColMinimalAcceptableWidth(), then the
2829 minimal acceptable width is used instead of it.
2831 void SetDefaultColSize(int width
, bool resizeExistingCols
= false);
2834 Sets the default height for rows in the grid.
2836 This will only affect rows subsequently added to the grid unless
2837 @a resizeExistingRows is @true.
2839 If @a height is less than GetRowMinimalAcceptableHeight(), then the
2840 minimal acceptable height is used instead of it.
2842 void SetDefaultRowSize(int height
, bool resizeExistingRows
= false);
2845 Sets the width of the row labels.
2847 If @a width equals @c wxGRID_AUTOSIZE then width is calculated
2848 automatically so that no label is truncated. Note that this could be
2849 slow for a large table.
2851 void SetRowLabelSize(int width
);
2854 Sets the minimal row @a height used by default.
2856 See SetColMinimalAcceptableWidth() for more information.
2858 void SetRowMinimalAcceptableHeight(int height
);
2861 Sets the minimal @a height for the specified @a row.
2863 See SetColMinimalWidth() for more information.
2865 void SetRowMinimalHeight(int row
, int height
);
2868 Sets the height of the specified row.
2870 See SetColSize() for more information.
2872 void SetRowSize(int row
, int height
);
2875 Hides the specified row.
2877 To show the row later you need to call SetRowSize() with non-0
2883 void HideRow(int col
);
2886 Shows the previously hidden row by resizing it to non-0 size.
2888 @see HideRow(), SetRowSize()
2890 void ShowRow(int col
);
2893 Get size information for all columns at once.
2895 This method is useful when the information about all column widths
2896 needs to be saved. The widths can be later restored using
2899 @sa wxGridSizesInfo, GetRowSizes()
2901 wxGridSizesInfo
GetColSizes() const;
2904 Get size information for all row at once.
2906 @sa wxGridSizesInfo, GetColSizes()
2908 wxGridSizesInfo
GetRowSizes() const;
2911 Restore all columns sizes.
2913 This is usually called with wxGridSizesInfo object previously returned
2918 void SetColSizes(const wxGridSizesInfo
& sizeInfo
);
2921 Restore all rows sizes.
2925 void SetRowSizes(const wxGridSizesInfo
& sizeInfo
);
2928 Set the size of the cell.
2930 Specifying a value of more than 1 in @a num_rows or @a num_cols will
2931 make the cell at (@a row, @a col) span the block of the specified size,
2932 covering the other cells which would be normally shown in it. Passing 1
2933 for both arguments resets the cell to normal appearance.
2938 The row of the cell.
2940 The column of the cell.
2942 Number of rows to be occupied by this cell, must be >= 1.
2944 Number of columns to be occupied by this cell, must be >= 1.
2946 void SetCellSize(int row
, int col
, int num_rows
, int num_cols
);
2949 Get the size of the cell in number of cells covered by it.
2951 For normal cells, the function fills both @a num_rows and @a num_cols
2952 with 1 and returns CellSpan_None. For cells which span multiple cells, i.e.
2953 for which SetCellSize() had been called, the returned values are the
2954 same ones as were passed to SetCellSize() call and the function return
2955 value is CellSpan_Main.
2957 More unexpectedly, perhaps, the returned values may be @em negative for
2958 the cells which are inside a span covered by a cell occupying multiple
2959 rows or columns. They correspond to the offset of the main cell of the
2960 span from the cell passed to this functions and the function returns
2961 CellSpan_Inside value to indicate this.
2963 As an example, consider a 3*3 grid with the cell (1, 1) (the one in the
2964 middle) having a span of 2 rows and 2 columns, i.e. the grid looks like
2974 Then the function returns 2 and 2 in @a num_rows and @a num_cols for
2975 the cell (1, 1) itself and -1 and -1 for the cell (2, 2) as well as -1
2976 and 0 for the cell (2, 1).
2979 The row of the cell.
2981 The column of the cell.
2983 Pointer to variable receiving the number of rows, must not be @NULL.
2985 Pointer to variable receiving the number of columns, must not be
2988 The kind of this cell span (the return value is new in wxWidgets
2989 2.9.1, this function was void in previous wxWidgets versions).
2991 CellSpan
GetCellSize( int row
, int col
, int *num_rows
, int *num_cols
) const;
2994 Get the number of rows and columns allocated for this cell.
2996 This overload doesn't return a CellSpan value but the values returned
2997 may still be negative, see GetCellSize(int, int, int *, int *) for
3000 wxSize
GetCellSize(const wxGridCellCoords
& coords
);
3006 @name User-Resizing and Dragging
3008 Functions controlling various interactive mouse operations.
3010 By default, columns and rows can be resized by dragging the edges of
3011 their labels (this can be disabled using DisableDragColSize() and
3012 DisableDragRowSize() methods). And if grid line dragging is enabled with
3013 EnableDragGridSize() they can also be resized by dragging the right or
3014 bottom edge of the grid cells.
3016 Columns can also be moved to interactively change their order but this
3017 needs to be explicitly enabled with EnableDragColMove().
3022 Return @true if the dragging of cells is enabled or @false otherwise.
3024 bool CanDragCell() const;
3027 Returns @true if columns can be moved by dragging with the mouse.
3029 Columns can be moved by dragging on their labels.
3031 bool CanDragColMove() const;
3034 Returns @true if the given column can be resized by dragging with the
3037 This function returns @true if resizing the columns interactively is
3038 globally enabled, i.e. if DisableDragColSize() hadn't been called, and
3039 if this column wasn't explicitly marked as non-resizable with
3042 bool CanDragColSize(int col
) const;
3045 Return @true if the dragging of grid lines to resize rows and columns
3046 is enabled or @false otherwise.
3048 bool CanDragGridSize() const;
3051 Returns @true if the given row can be resized by dragging with the
3054 This is the same as CanDragColSize() but for rows.
3056 bool CanDragRowSize(int row
) const;
3059 Disable interactive resizing of the specified column.
3061 This method allows to disable resizing of an individual column in a
3062 grid where the columns are otherwise resizable (which is the case by
3065 Notice that currently there is no way to make some columns resizable in
3066 a grid where columns can't be resized by default as there doesn't seem
3067 to be any need for this in practice. There is also no way to make the
3068 column marked as fixed using this method resizable again because it is
3069 supposed that fixed columns are used for static parts of the grid and
3070 so should remain fixed during the entire grid lifetime.
3072 Also notice that disabling interactive column resizing will not prevent
3073 the program from changing the column size.
3075 @see EnableDragColSize()
3077 void DisableColResize(int col
);
3080 Disable interactive resizing of the specified row.
3082 This is the same as DisableColResize() but for rows.
3084 @see EnableDragRowSize()
3086 void DisableRowResize(int row
);
3089 Disables column moving by dragging with the mouse.
3091 Equivalent to passing @false to EnableDragColMove().
3093 void DisableDragColMove();
3096 Disables column sizing by dragging with the mouse.
3098 Equivalent to passing @false to EnableDragColSize().
3100 void DisableDragColSize();
3103 Disable mouse dragging of grid lines to resize rows and columns.
3105 Equivalent to passing @false to EnableDragGridSize()
3107 void DisableDragGridSize();
3110 Disables row sizing by dragging with the mouse.
3112 Equivalent to passing @false to EnableDragRowSize().
3114 void DisableDragRowSize();
3117 Enables or disables cell dragging with the mouse.
3119 void EnableDragCell(bool enable
= true);
3122 Enables or disables column moving by dragging with the mouse.
3124 void EnableDragColMove(bool enable
= true);
3127 Enables or disables column sizing by dragging with the mouse.
3129 @see DisableColResize()
3131 void EnableDragColSize(bool enable
= true);
3134 Enables or disables row and column resizing by dragging gridlines with
3137 void EnableDragGridSize(bool enable
= true);
3140 Enables or disables row sizing by dragging with the mouse.
3142 @see DisableRowResize()
3144 void EnableDragRowSize(bool enable
= true);
3147 Returns the column ID of the specified column position.
3149 int GetColAt(int colPos
) const;
3152 Returns the position of the specified column.
3154 int GetColPos(int colID
) const;
3157 Sets the position of the specified column.
3159 void SetColPos(int colID
, int newPos
);
3162 Sets the positions of all columns at once.
3164 This method takes an array containing the indices of the columns in
3165 their display order, i.e. uses the same convention as
3166 wxHeaderCtrl::SetColumnsOrder().
3168 void SetColumnsOrder(const wxArrayInt
& order
);
3171 Resets the position of the columns to the default.
3179 @name Cursor Movement
3184 Returns the current grid cell column position.
3186 int GetGridCursorCol() const;
3189 Returns the current grid cell row position.
3191 int GetGridCursorRow() const;
3194 Make the given cell current and ensure it is visible.
3196 This method is equivalent to calling MakeCellVisible() and
3197 SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL
3198 event is generated by it and the selected cell doesn't change if the
3201 void GoToCell(int row
, int col
);
3203 Make the given cell current and ensure it is visible.
3205 This method is equivalent to calling MakeCellVisible() and
3206 SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL
3207 event is generated by it and the selected cell doesn't change if the
3210 void GoToCell(const wxGridCellCoords
& coords
);
3213 Moves the grid cursor down by one row.
3215 If a block of cells was previously selected it will expand if the
3216 argument is @true or be cleared if the argument is @false.
3218 bool MoveCursorDown(bool expandSelection
);
3221 Moves the grid cursor down in the current column such that it skips to
3222 the beginning or end of a block of non-empty cells.
3224 If a block of cells was previously selected it will expand if the
3225 argument is @true or be cleared if the argument is @false.
3227 bool MoveCursorDownBlock(bool expandSelection
);
3230 Moves the grid cursor left by one column.
3232 If a block of cells was previously selected it will expand if the
3233 argument is @true or be cleared if the argument is @false.
3235 bool MoveCursorLeft(bool expandSelection
);
3238 Moves the grid cursor left in the current row such that it skips to the
3239 beginning or end of a block of non-empty cells.
3241 If a block of cells was previously selected it will expand if the
3242 argument is @true or be cleared if the argument is @false.
3244 bool MoveCursorLeftBlock(bool expandSelection
);
3247 Moves the grid cursor right by one column.
3249 If a block of cells was previously selected it will expand if the
3250 argument is @true or be cleared if the argument is @false.
3252 bool MoveCursorRight(bool expandSelection
);
3255 Moves the grid cursor right in the current row such that it skips to
3256 the beginning or end of a block of non-empty cells.
3258 If a block of cells was previously selected it will expand if the
3259 argument is @true or be cleared if the argument is @false.
3261 bool MoveCursorRightBlock(bool expandSelection
);
3264 Moves the grid cursor up by one row.
3266 If a block of cells was previously selected it will expand if the
3267 argument is @true or be cleared if the argument is @false.
3269 bool MoveCursorUp(bool expandSelection
);
3272 Moves the grid cursor up in the current column such that it skips to
3273 the beginning or end of a block of non-empty cells.
3275 If a block of cells was previously selected it will expand if the
3276 argument is @true or be cleared if the argument is @false.
3278 bool MoveCursorUpBlock(bool expandSelection
);
3281 Moves the grid cursor down by some number of rows so that the previous
3282 bottom visible row becomes the top visible row.
3284 bool MovePageDown();
3287 Moves the grid cursor up by some number of rows so that the previous
3288 top visible row becomes the bottom visible row.
3293 Set the grid cursor to the specified cell.
3295 The grid cursor indicates the current cell and can be moved by the user
3296 using the arrow keys or the mouse.
3298 Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
3299 if the event handler vetoes this event, the cursor is not moved.
3301 This function doesn't make the target call visible, use GoToCell() to
3304 void SetGridCursor(int row
, int col
);
3306 Set the grid cursor to the specified cell.
3308 The grid cursor indicates the current cell and can be moved by the user
3309 using the arrow keys or the mouse.
3311 Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
3312 if the event handler vetoes this event, the cursor is not moved.
3314 This function doesn't make the target call visible, use GoToCell() to
3317 void SetGridCursor(const wxGridCellCoords
& coords
);
3323 @name User Selection
3328 Deselects all cells that are currently selected.
3330 void ClearSelection();
3333 Returns an array of individually selected cells.
3335 Notice that this array does @em not contain all the selected cells in
3336 general as it doesn't include the cells selected as part of column, row
3337 or block selection. You must use this method, GetSelectedCols(),
3338 GetSelectedRows() and GetSelectionBlockTopLeft() and
3339 GetSelectionBlockBottomRight() methods to obtain the entire selection
3342 Please notice this behaviour is by design and is needed in order to
3343 support grids of arbitrary size (when an entire column is selected in
3344 a grid with a million of columns, we don't want to create an array with
3345 a million of entries in this function, instead it returns an empty
3346 array and GetSelectedCols() returns an array containing one element).
3348 wxGridCellCoordsArray
GetSelectedCells() const;
3351 Returns an array of selected columns.
3353 Please notice that this method alone is not sufficient to find all the
3354 selected columns as it contains only the columns which were
3355 individually selected but not those being part of the block selection
3356 or being selected in virtue of all of their cells being selected
3357 individually, please see GetSelectedCells() for more details.
3359 wxArrayInt
GetSelectedCols() const;
3362 Returns an array of selected rows.
3364 Please notice that this method alone is not sufficient to find all the
3365 selected rows as it contains only the rows which were individually
3366 selected but not those being part of the block selection or being
3367 selected in virtue of all of their cells being selected individually,
3368 please see GetSelectedCells() for more details.
3370 wxArrayInt
GetSelectedRows() const;
3373 Returns the colour used for drawing the selection background.
3375 wxColour
GetSelectionBackground() const;
3378 Returns an array of the bottom right corners of blocks of selected
3381 Please see GetSelectedCells() for more information about the selection
3382 representation in wxGrid.
3384 @see GetSelectionBlockTopLeft()
3386 wxGridCellCoordsArray
GetSelectionBlockBottomRight() const;
3389 Returns an array of the top left corners of blocks of selected cells.
3391 Please see GetSelectedCells() for more information about the selection
3392 representation in wxGrid.
3394 @see GetSelectionBlockBottomRight()
3396 wxGridCellCoordsArray
GetSelectionBlockTopLeft() const;
3399 Returns the colour used for drawing the selection foreground.
3401 wxColour
GetSelectionForeground() const;
3404 Returns the current selection mode.
3406 @see SetSelectionMode().
3408 wxGridSelectionModes
GetSelectionMode() const;
3411 Returns @true if the given cell is selected.
3413 bool IsInSelection(int row
, int col
) const;
3415 Returns @true if the given cell is selected.
3417 bool IsInSelection(const wxGridCellCoords
& coords
) const;
3420 Returns @true if there are currently any selected cells, rows, columns
3423 bool IsSelection() const;
3426 Selects all cells in the grid.
3431 Selects a rectangular block of cells.
3433 If @a addToSelected is @false then any existing selection will be
3434 deselected; if @true the column will be added to the existing
3437 void SelectBlock(int topRow
, int leftCol
, int bottomRow
, int rightCol
,
3438 bool addToSelected
= false);
3440 Selects a rectangular block of cells.
3442 If @a addToSelected is @false then any existing selection will be
3443 deselected; if @true the column will be added to the existing
3446 void SelectBlock(const wxGridCellCoords
& topLeft
,
3447 const wxGridCellCoords
& bottomRight
,
3448 bool addToSelected
= false);
3451 Selects the specified column.
3453 If @a addToSelected is @false then any existing selection will be
3454 deselected; if @true the column will be added to the existing
3457 This method won't select anything if the current selection mode is
3460 void SelectCol(int col
, bool addToSelected
= false);
3463 Selects the specified row.
3465 If @a addToSelected is @false then any existing selection will be
3466 deselected; if @true the row will be added to the existing selection.
3468 This method won't select anything if the current selection mode is
3469 wxGridSelectColumns.
3471 void SelectRow(int row
, bool addToSelected
= false);
3474 Set the colour to be used for drawing the selection background.
3476 void SetSelectionBackground(const wxColour
& c
);
3479 Set the colour to be used for drawing the selection foreground.
3481 void SetSelectionForeground(const wxColour
& c
);
3484 Set the selection behaviour of the grid.
3486 The existing selection is converted to conform to the new mode if
3487 possible and discarded otherwise (e.g. any individual selected cells
3488 are deselected if the new mode allows only the selection of the entire
3491 void SetSelectionMode(wxGridSelectionModes selmode
);
3502 Returns the number of pixels per horizontal scroll increment.
3506 @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY()
3508 int GetScrollLineX() const;
3511 Returns the number of pixels per vertical scroll increment.
3515 @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY()
3517 int GetScrollLineY() const;
3520 Returns @true if a cell is either entirely or at least partially
3521 visible in the grid window.
3523 By default, the cell must be entirely visible for this function to
3524 return @true but if @a wholeCellVisible is @false, the function returns
3525 @true even if the cell is only partially visible.
3527 bool IsVisible(int row
, int col
, bool wholeCellVisible
= true) const;
3529 Returns @true if a cell is either entirely or at least partially
3530 visible in the grid window.
3532 By default, the cell must be entirely visible for this function to
3533 return @true but if @a wholeCellVisible is @false, the function returns
3534 @true even if the cell is only partially visible.
3536 bool IsVisible(const wxGridCellCoords
& coords
,
3537 bool wholeCellVisible
= true) const;
3540 Brings the specified cell into the visible grid cell area with minimal
3543 Does nothing if the cell is already visible.
3545 void MakeCellVisible(int row
, int col
);
3547 Brings the specified cell into the visible grid cell area with minimal
3550 Does nothing if the cell is already visible.
3552 void MakeCellVisible(const wxGridCellCoords
& coords
);
3555 Sets the number of pixels per horizontal scroll increment.
3559 @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY()
3561 void SetScrollLineX(int x
);
3564 Sets the number of pixels per vertical scroll increment.
3568 @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX()
3570 void SetScrollLineY(int y
);
3576 @name Cell and Device Coordinate Translation
3581 Convert grid cell coordinates to grid window pixel coordinates.
3583 This function returns the rectangle that encloses the block of cells
3584 limited by @a topLeft and @a bottomRight cell in device coords and
3585 clipped to the client size of the grid window.
3589 wxRect
BlockToDeviceRect(const wxGridCellCoords
& topLeft
,
3590 const wxGridCellCoords
& bottomRight
) const;
3593 Return the rectangle corresponding to the grid cell's size and position
3594 in logical coordinates.
3596 @see BlockToDeviceRect()
3598 wxRect
CellToRect(int row
, int col
) const;
3600 Return the rectangle corresponding to the grid cell's size and position
3601 in logical coordinates.
3603 @see BlockToDeviceRect()
3605 wxRect
CellToRect(const wxGridCellCoords
& coords
) const;
3608 Returns the column at the given pixel position.
3611 The x position to evaluate.
3613 If @true, rather than returning @c wxNOT_FOUND, it returns either
3614 the first or last column depending on whether @a x is too far to
3615 the left or right respectively.
3617 The column index or @c wxNOT_FOUND.
3619 int XToCol(int x
, bool clipToMinMax
= false) const;
3622 Returns the column whose right hand edge is close to the given logical
3625 If no column edge is near to this position @c wxNOT_FOUND is returned.
3627 int XToEdgeOfCol(int x
) const;
3630 Translates logical pixel coordinates to the grid cell coordinates.
3632 Notice that this function expects logical coordinates on input so if
3633 you use this function in a mouse event handler you need to translate
3634 the mouse position, which is expressed in device coordinates, to
3637 @see XToCol(), YToRow()
3639 wxGridCellCoords
XYToCell(int x
, int y
) const;
3641 Translates logical pixel coordinates to the grid cell coordinates.
3643 Notice that this function expects logical coordinates on input so if
3644 you use this function in a mouse event handler you need to translate
3645 the mouse position, which is expressed in device coordinates, to
3648 @see XToCol(), YToRow()
3650 wxGridCellCoords
XYToCell(const wxPoint
& pos
) const;
3651 // XYToCell(int, int, wxGridCellCoords&) overload is intentionally
3652 // undocumented, using it is ugly and non-const reference parameters are
3653 // not used in wxWidgets API
3656 Returns the row whose bottom edge is close to the given logical @a y
3659 If no row edge is near to this position @c wxNOT_FOUND is returned.
3661 int YToEdgeOfRow(int y
) const;
3664 Returns the grid row that corresponds to the logical @a y coordinate.
3666 Returns @c wxNOT_FOUND if there is no row at the @a y position.
3668 int YToRow(int y
, bool clipToMinMax
= false) const;
3674 @name Miscellaneous Functions
3679 Appends one or more new columns to the right of the grid.
3681 The @a updateLabels argument is not used at present. If you are using a
3682 derived grid table class you will need to override
3683 wxGridTableBase::AppendCols(). See InsertCols() for further
3686 @return @true on success or @false if appending columns failed.
3688 bool AppendCols(int numCols
= 1, bool updateLabels
= true);
3691 Appends one or more new rows to the bottom of the grid.
3693 The @a updateLabels argument is not used at present. If you are using a
3694 derived grid table class you will need to override
3695 wxGridTableBase::AppendRows(). See InsertRows() for further
3698 @return @true on success or @false if appending rows failed.
3700 bool AppendRows(int numRows
= 1, bool updateLabels
= true);
3703 Return @true if the horizontal grid lines stop at the last column
3704 boundary or @false if they continue to the end of the window.
3706 The default is to clip grid lines.
3708 @see ClipHorzGridLines(), AreVertGridLinesClipped()
3710 bool AreHorzGridLinesClipped() const;
3713 Return @true if the vertical grid lines stop at the last row
3714 boundary or @false if they continue to the end of the window.
3716 The default is to clip grid lines.
3718 @see ClipVertGridLines(), AreHorzGridLinesClipped()
3720 bool AreVertGridLinesClipped() const;
3723 Increments the grid's batch count.
3725 When the count is greater than zero repainting of the grid is
3726 suppressed. Each call to BeginBatch must be matched by a later call to
3727 EndBatch(). Code that does a lot of grid modification can be enclosed
3728 between BeginBatch() and EndBatch() calls to avoid screen flicker. The
3729 final EndBatch() call will cause the grid to be repainted.
3731 Notice that you should use wxGridUpdateLocker which ensures that there
3732 is always a matching EndBatch() call for this BeginBatch() if possible
3733 instead of calling this method directly.
3738 Clears all data in the underlying grid table and repaints the grid.
3740 The table is not deleted by this function. If you are using a derived
3741 table class then you need to override wxGridTableBase::Clear() for this
3742 function to have any effect.
3747 Change whether the horizontal grid lines are clipped by the end of the
3750 By default the grid lines are not drawn beyond the end of the last
3751 column but after calling this function with @a clip set to @false they
3752 will be drawn across the entire grid window.
3754 @see AreHorzGridLinesClipped(), ClipVertGridLines()
3756 void ClipHorzGridLines(bool clip
);
3759 Change whether the vertical grid lines are clipped by the end of the
3762 By default the grid lines are not drawn beyond the end of the last
3763 row but after calling this function with @a clip set to @false they
3764 will be drawn across the entire grid window.
3766 @see AreVertGridLinesClipped(), ClipHorzGridLines()
3768 void ClipVertGridLines(bool clip
);
3771 Deletes one or more columns from a grid starting at the specified
3774 The @a updateLabels argument is not used at present. If you are using a
3775 derived grid table class you will need to override
3776 wxGridTableBase::DeleteCols(). See InsertCols() for further
3779 @return @true on success or @false if deleting columns failed.
3781 bool DeleteCols(int pos
= 0, int numCols
= 1, bool updateLabels
= true);
3784 Deletes one or more rows from a grid starting at the specified
3787 The @a updateLabels argument is not used at present. If you are using a
3788 derived grid table class you will need to override
3789 wxGridTableBase::DeleteRows(). See InsertRows() for further
3792 @return @true on success or @false if appending rows failed.
3794 bool DeleteRows(int pos
= 0, int numRows
= 1, bool updateLabels
= true);
3797 Decrements the grid's batch count.
3799 When the count is greater than zero repainting of the grid is
3800 suppressed. Each previous call to BeginBatch() must be matched by a
3801 later call to EndBatch(). Code that does a lot of grid modification can
3802 be enclosed between BeginBatch() and EndBatch() calls to avoid screen
3803 flicker. The final EndBatch() will cause the grid to be repainted.
3805 @see wxGridUpdateLocker
3810 Overridden wxWindow method.
3815 Causes immediate repainting of the grid.
3817 Use this instead of the usual wxWindow::Refresh().
3819 void ForceRefresh();
3822 Returns the number of times that BeginBatch() has been called without
3823 (yet) matching calls to EndBatch(). While the grid's batch count is
3824 greater than zero the display will not be updated.
3826 int GetBatchCount();
3829 Returns the total number of grid columns.
3831 This is the same as the number of columns in the underlying grid table.
3833 int GetNumberCols() const;
3836 Returns the total number of grid rows.
3838 This is the same as the number of rows in the underlying grid table.
3840 int GetNumberRows() const;
3843 Returns the attribute for the given cell creating one if necessary.
3845 If the cell already has an attribute, it is returned. Otherwise a new
3846 attribute is created, associated with the cell and returned. In any
3847 case the caller must call DecRef() on the returned pointer.
3849 This function may only be called if CanHaveAttributes() returns @true.
3851 wxGridCellAttr
*GetOrCreateCellAttr(int row
, int col
) const;
3854 Returns a base pointer to the current table object.
3856 The returned pointer is still owned by the grid.
3858 wxGridTableBase
*GetTable() const;
3861 Inserts one or more new columns into a grid with the first new column
3862 at the specified position.
3864 Notice that inserting the columns in the grid requires grid table
3865 cooperation: when this method is called, grid object begins by
3866 requesting the underlying grid table to insert new columns. If this is
3867 successful the table notifies the grid and the grid updates the
3868 display. For a default grid (one where you have called CreateGrid())
3869 this process is automatic. If you are using a custom grid table
3870 (specified with SetTable()) then you must override
3871 wxGridTableBase::InsertCols() in your derived table class.
3874 The position which the first newly inserted column will have.
3876 The number of columns to insert.
3880 @true if the columns were successfully inserted, @false if an error
3881 occurred (most likely the table couldn't be updated).
3883 bool InsertCols(int pos
= 0, int numCols
= 1, bool updateLabels
= true);
3886 Inserts one or more new rows into a grid with the first new row at the
3889 Notice that you must implement wxGridTableBase::InsertRows() if you use
3890 a grid with a custom table, please see InsertCols() for more
3894 The position which the first newly inserted row will have.
3896 The number of rows to insert.
3900 @true if the rows were successfully inserted, @false if an error
3901 occurred (most likely the table couldn't be updated).
3903 bool InsertRows(int pos
= 0, int numRows
= 1, bool updateLabels
= true);
3906 Invalidates the cached attribute for the given cell.
3908 For efficiency reasons, wxGrid may cache the recently used attributes
3909 (currently it caches only the single most recently used one, in fact)
3910 which can result in the cell appearance not being refreshed even when
3911 the attribute returned by your custom wxGridCellAttrProvider-derived
3912 class has changed. To force the grid to refresh the cell attribute,
3913 this function may be used. Notice that calling it will not result in
3914 actually redrawing the cell, you still need to call
3915 wxWindow::RefreshRect() to invalidate the area occupied by the cell in
3916 the window to do this. Also note that you don't need to call this
3917 function if you store the attributes in wxGrid itself, i.e. use its
3918 SetAttr() and similar methods, it is only useful when using a separate
3919 custom attributes provider.
3922 The row of the cell whose attribute needs to be queried again.
3924 The column of the cell whose attribute needs to be queried again.
3928 void RefreshAttr(int row
, int col
);
3931 Sets the cell attributes for all cells in the specified column.
3933 For more information about controlling grid cell attributes see the
3934 wxGridCellAttr cell attribute class and the @ref overview_grid.
3936 void SetColAttr(int col
, wxGridCellAttr
* attr
);
3939 Sets the extra margins used around the grid area.
3941 A grid may occupy more space than needed for its data display and
3942 this function allows to set how big this extra space is
3944 void SetMargins(int extraWidth
, int extraHeight
);
3947 Sets the cell attributes for all cells in the specified row.
3949 The grid takes ownership of the attribute pointer.
3951 See the wxGridCellAttr class for more information about controlling
3954 void SetRowAttr(int row
, wxGridCellAttr
* attr
);
3960 @name Sorting support.
3962 wxGrid doesn't provide any support for sorting the data but it does
3963 generate events allowing the user code to sort it and supports
3964 displaying the sort indicator in the column used for sorting.
3966 To use wxGrid sorting support you need to handle wxEVT_GRID_COL_SORT
3967 event (and not veto it) and resort the data displayed in the grid. The
3968 grid will automatically update the sorting indicator on the column
3971 You can also call the functions in this section directly to update the
3972 sorting indicator. Once again, they don't do anything with the grid
3973 data, it remains your responsibility to actually sort it appropriately.
3978 Return the column in which the sorting indicator is currently
3981 Returns @c wxNOT_FOUND if sorting indicator is not currently displayed
3984 @see SetSortingColumn()
3986 int GetSortingColumn() const;
3989 Return @true if this column is currently used for sorting.
3991 @see GetSortingColumn()
3993 bool IsSortingBy(int col
) const;
3996 Return @true if the current sorting order is ascending or @false if it
3999 It only makes sense to call this function if GetSortingColumn() returns
4000 a valid column index and not @c wxNOT_FOUND.
4002 @see SetSortingColumn()
4004 bool IsSortOrderAscending() const;
4007 Set the column to display the sorting indicator in and its direction.
4010 The column to display the sorting indicator in or @c wxNOT_FOUND to
4011 remove any currently displayed sorting indicator.
4013 If @true, display the ascending sort indicator, otherwise display
4014 the descending sort indicator.
4016 @see GetSortingColumn(), IsSortOrderAscending()
4018 void SetSortingColumn(int col
, bool ascending
= true);
4021 Remove any currently shown sorting indicator.
4023 This is equivalent to calling SetSortingColumn() with @c wxNOT_FOUND
4026 void UnsetSortingColumn();
4031 @name Accessors for component windows.
4033 Return the various child windows of wxGrid.
4035 wxGrid is an empty parent window for 4 children representing the column
4036 labels window (top), the row labels window (left), the corner window
4037 (top left) and the main grid window. It may be necessary to use these
4038 individual windows and not the wxGrid window itself if you need to
4039 handle events for them (this can be done using wxEvtHandler::Connect()
4040 or wxWindow::PushEventHandler()) or do something else requiring the use
4041 of the correct window pointer. Notice that you should not, however,
4042 change these windows (e.g. reposition them or draw over them) because
4043 they are managed by wxGrid itself.
4048 Return the main grid window containing the grid cells.
4050 This window is always shown.
4052 wxWindow
*GetGridWindow() const;
4055 Return the row labels window.
4057 This window is not shown if the row labels were hidden using
4060 wxWindow
*GetGridRowLabelWindow() const;
4063 Return the column labels window.
4065 This window is not shown if the columns labels were hidden using
4068 Depending on whether UseNativeColHeader() was called or not this can be
4069 either a wxHeaderCtrl or a plain wxWindow. This function returns a valid
4070 window pointer in either case but in the former case you can also use
4071 GetGridColHeader() to access it if you need wxHeaderCtrl-specific
4074 wxWindow
*GetGridColLabelWindow() const;
4077 Return the window in the top left grid corner.
4079 This window is shown only of both columns and row labels are shown and
4080 normally doesn't contain anything. Clicking on it is handled by wxGrid
4081 however and can be used to select the entire grid.
4083 wxWindow
*GetGridCornerLabelWindow() const;
4086 Return the header control used for column labels display.
4088 This function can only be called if UseNativeColHeader() had been
4091 wxHeaderCtrl
*GetGridColHeader() const;
4097 Returns @true if this grid has support for cell attributes.
4099 The grid supports attributes if it has the associated table which, in
4100 turn, has attributes support, i.e. wxGridTableBase::CanHaveAttributes()
4103 bool CanHaveAttributes() const;
4106 Get the minimal width of the given column/row.
4108 The value returned by this function may be different than that returned
4109 by GetColMinimalAcceptableWidth() if SetColMinimalWidth() had been
4110 called for this column.
4112 int GetColMinimalWidth(int col
) const;
4115 Returns the coordinate of the right border specified column.
4117 int GetColRight(int col
) const;
4120 Returns the coordinate of the left border specified column.
4122 int GetColLeft(int col
) const;
4125 Returns the minimal size for the given column.
4127 The value returned by this function may be different than that returned
4128 by GetRowMinimalAcceptableHeight() if SetRowMinimalHeight() had been
4129 called for this row.
4131 int GetRowMinimalHeight(int col
) const;
4137 @class wxGridUpdateLocker
4139 This small class can be used to prevent wxGrid from redrawing during its
4140 lifetime by calling wxGrid::BeginBatch() in its constructor and
4141 wxGrid::EndBatch() in its destructor. It is typically used in a function
4142 performing several operations with a grid which would otherwise result in
4143 flicker. For example:
4148 m_grid = new wxGrid(this, ...);
4150 wxGridUpdateLocker noUpdates(m_grid);
4151 m_grid-AppendColumn();
4152 // ... many other operations with m_grid ...
4155 // destructor called, grid refreshed
4159 Using this class is easier and safer than calling wxGrid::BeginBatch() and
4160 wxGrid::EndBatch() because you don't risk missing the call the latter (due
4161 to an exception for example).
4166 class wxGridUpdateLocker
4170 Creates an object preventing the updates of the specified @a grid. The
4171 parameter could be @NULL in which case nothing is done. If @a grid is
4172 non-@NULL then the grid must exist for longer than this
4173 wxGridUpdateLocker object itself.
4175 The default constructor could be followed by a call to Create() to set
4176 the grid object later.
4178 wxGridUpdateLocker(wxGrid
* grid
= NULL
);
4181 Destructor reenables updates for the grid this object is associated
4184 ~wxGridUpdateLocker();
4187 This method can be called if the object had been constructed using the
4188 default constructor. It must not be called more than once.
4190 void Create(wxGrid
* grid
);
4198 This event class contains information about various grid events.
4200 Notice that all grid event table macros are available in two versions:
4201 @c EVT_GRID_XXX and @c EVT_GRID_CMD_XXX. The only difference between the
4202 two is that the former doesn't allow to specify the grid window identifier
4203 and so takes a single parameter, the event handler, but is not suitable if
4204 there is more than one grid control in the window where the event table is
4205 used (as it would catch the events from all the grids). The version with @c
4206 CMD takes the id as first argument and the event handler as the second one
4207 and so can be used with multiple grids as well. Otherwise there are no
4208 difference between the two and only the versions without the id are
4209 documented below for brevity.
4211 @beginEventTable{wxGridEvent}
4212 @event{EVT_GRID_CELL_CHANGING(func)}
4213 The user is about to change the data in a cell. The new cell value as
4214 string is available from GetString() event object method. This event
4215 can be vetoed if the change is not allowed.
4216 Processes a @c wxEVT_GRID_CELL_CHANGING event type.
4217 @event{EVT_GRID_CELL_CHANGED(func)}
4218 The user changed the data in a cell. The old cell value as string is
4219 available from GetString() event object method. Notice that vetoing
4220 this event still works for backwards compatibility reasons but any new
4221 code should only veto EVT_GRID_CELL_CHANGING event and not this one.
4222 Processes a @c wxEVT_GRID_CELL_CHANGED event type.
4223 @event{EVT_GRID_CELL_LEFT_CLICK(func)}
4224 The user clicked a cell with the left mouse button. Processes a
4225 @c wxEVT_GRID_CELL_LEFT_CLICK event type.
4226 @event{EVT_GRID_CELL_LEFT_DCLICK(func)}
4227 The user double-clicked a cell with the left mouse button. Processes a
4228 @c wxEVT_GRID_CELL_LEFT_DCLICK event type.
4229 @event{EVT_GRID_CELL_RIGHT_CLICK(func)}
4230 The user clicked a cell with the right mouse button. Processes a
4231 @c wxEVT_GRID_CELL_RIGHT_CLICK event type.
4232 @event{EVT_GRID_CELL_RIGHT_DCLICK(func)}
4233 The user double-clicked a cell with the right mouse button. Processes a
4234 @c wxEVT_GRID_CELL_RIGHT_DCLICK event type.
4235 @event{EVT_GRID_EDITOR_HIDDEN(func)}
4236 The editor for a cell was hidden. Processes a
4237 @c wxEVT_GRID_EDITOR_HIDDEN event type.
4238 @event{EVT_GRID_EDITOR_SHOWN(func)}
4239 The editor for a cell was shown. Processes a
4240 @c wxEVT_GRID_EDITOR_SHOWN event type.
4241 @event{EVT_GRID_LABEL_LEFT_CLICK(func)}
4242 The user clicked a label with the left mouse button. Processes a
4243 @c wxEVT_GRID_LABEL_LEFT_CLICK event type.
4244 @event{EVT_GRID_LABEL_LEFT_DCLICK(func)}
4245 The user double-clicked a label with the left mouse button. Processes a
4246 @c wxEVT_GRID_LABEL_LEFT_DCLICK event type.
4247 @event{EVT_GRID_LABEL_RIGHT_CLICK(func)}
4248 The user clicked a label with the right mouse button. Processes a
4249 @c wxEVT_GRID_LABEL_RIGHT_CLICK event type.
4250 @event{EVT_GRID_LABEL_RIGHT_DCLICK(func)}
4251 The user double-clicked a label with the right mouse button. Processes
4252 a @c wxEVT_GRID_LABEL_RIGHT_DCLICK event type.
4253 @event{EVT_GRID_SELECT_CELL(func)}
4254 The given cell was made current, either by user or by the program via a
4255 call to SetGridCursor() or GoToCell(). Processes a
4256 @c wxEVT_GRID_SELECT_CELL event type.
4257 @event{EVT_GRID_COL_MOVE(func)}
4258 The user tries to change the order of the columns in the grid by
4259 dragging the column specified by GetCol(). This event can be vetoed to
4260 either prevent the user from reordering the column change completely
4261 (but notice that if you don't want to allow it at all, you simply
4262 shouldn't call wxGrid::EnableDragColMove() in the first place), vetoed
4263 but handled in some way in the handler, e.g. by really moving the
4264 column to the new position at the associated table level, or allowed to
4265 proceed in which case wxGrid::SetColPos() is used to reorder the
4266 columns display order without affecting the use of the column indices
4268 This event macro corresponds to @c wxEVT_GRID_COL_MOVE event type.
4269 @event{EVT_GRID_COL_SORT(func)}
4270 This event is generated when a column is clicked by the user and its
4271 name is explained by the fact that the custom reaction to a click on a
4272 column is to sort the grid contents by this column. However the grid
4273 itself has no special support for sorting and it's up to the handler of
4274 this event to update the associated table. But if the event is handled
4275 (and not vetoed) the grid supposes that the table was indeed resorted
4276 and updates the column to indicate the new sort order and refreshes
4278 This event macro corresponds to @c wxEVT_GRID_COL_SORT event type.
4282 @category{grid,events}
4284 class wxGridEvent
: public wxNotifyEvent
4288 Default constructor.
4292 Constructor for initializing all event attributes.
4294 wxGridEvent(int id
, wxEventType type
, wxObject
* obj
,
4295 int row
= -1, int col
= -1, int x
= -1, int y
= -1,
4296 bool sel
= true, const wxKeyboardState
& kbd
= wxKeyboardState());
4299 Returns @true if the Alt key was down at the time of the event.
4301 bool AltDown() const;
4304 Returns @true if the Control key was down at the time of the event.
4306 bool ControlDown() const;
4309 Column at which the event occurred.
4311 Notice that for a @c wxEVT_GRID_SELECT_CELL event this column is the
4312 column of the newly selected cell while the previously selected cell
4313 can be retrieved using wxGrid::GetGridCursorCol().
4315 virtual int GetCol();
4318 Position in pixels at which the event occurred.
4320 wxPoint
GetPosition();
4323 Row at which the event occurred.
4325 Notice that for a @c wxEVT_GRID_SELECT_CELL event this row is the row
4326 of the newly selected cell while the previously selected cell can be
4327 retrieved using wxGrid::GetGridCursorRow().
4329 virtual int GetRow();
4332 Returns @true if the Meta key was down at the time of the event.
4334 bool MetaDown() const;
4337 Returns @true if the user is selecting grid cells, or @false if
4343 Returns @true if the Shift key was down at the time of the event.
4345 bool ShiftDown() const;
4351 @class wxGridSizeEvent
4353 This event class contains information about a row/column resize event.
4355 @beginEventTable{wxGridSizeEvent}
4356 @event{EVT_GRID_CMD_COL_SIZE(id, func)}
4357 The user resized a column, corresponds to @c wxEVT_GRID_COL_SIZE event
4359 @event{EVT_GRID_CMD_ROW_SIZE(id, func)}
4360 The user resized a row, corresponds to @c wxEVT_GRID_ROW_SIZE event
4362 @event{EVT_GRID_COL_SIZE(func)}
4363 Same as EVT_GRID_CMD_COL_SIZE() but uses `wxID_ANY` id.
4364 @event{EVT_GRID_ROW_SIZE(func)}
4365 Same as EVT_GRID_CMD_ROW_SIZE() but uses `wxID_ANY` id.
4369 @category{grid,events}
4371 class wxGridSizeEvent
: public wxNotifyEvent
4375 Default constructor.
4379 Constructor for initializing all event attributes.
4381 wxGridSizeEvent(int id
, wxEventType type
, wxObject
* obj
,
4382 int rowOrCol
= -1, int x
= -1, int y
= -1,
4383 const wxKeyboardState
& kbd
= wxKeyboardState());
4386 Returns @true if the Alt key was down at the time of the event.
4388 bool AltDown() const;
4391 Returns @true if the Control key was down at the time of the event.
4393 bool ControlDown() const;
4396 Position in pixels at which the event occurred.
4398 wxPoint
GetPosition();
4401 Row or column at that was resized.
4406 Returns @true if the Meta key was down at the time of the event.
4408 bool MetaDown() const;
4411 Returns @true if the Shift key was down at the time of the event.
4413 bool ShiftDown() const;
4419 @class wxGridRangeSelectEvent
4421 @beginEventTable{wxGridRangeSelectEvent}
4422 @event{EVT_GRID_RANGE_SELECT(func)}
4423 The user selected a group of contiguous cells. Processes a
4424 @c wxEVT_GRID_RANGE_SELECT event type.
4425 @event{EVT_GRID_CMD_RANGE_SELECT(id, func)}
4426 The user selected a group of contiguous cells; variant taking a window
4427 identifier. Processes a @c wxEVT_GRID_RANGE_SELECT event type.
4431 @category{grid,events}
4433 class wxGridRangeSelectEvent
: public wxNotifyEvent
4437 Default constructor.
4439 wxGridRangeSelectEvent();
4441 Constructor for initializing all event attributes.
4443 wxGridRangeSelectEvent(int id
, wxEventType type
,
4445 const wxGridCellCoords
& topLeft
,
4446 const wxGridCellCoords
& bottomRight
,
4447 bool sel
= true, const wxKeyboardState
& kbd
= wxKeyboardState());
4450 Returns @true if the Alt key was down at the time of the event.
4452 bool AltDown() const;
4455 Returns @true if the Control key was down at the time of the event.
4457 bool ControlDown() const;
4460 Top left corner of the rectangular area that was (de)selected.
4462 wxGridCellCoords
GetBottomRightCoords();
4465 Bottom row of the rectangular area that was (de)selected.
4470 Left column of the rectangular area that was (de)selected.
4475 Right column of the rectangular area that was (de)selected.
4480 Top left corner of the rectangular area that was (de)selected.
4482 wxGridCellCoords
GetTopLeftCoords();
4485 Top row of the rectangular area that was (de)selected.
4490 Returns @true if the Meta key was down at the time of the event.
4492 bool MetaDown() const;
4495 Returns @true if the area was selected, @false otherwise.
4500 Returns @true if the Shift key was down at the time of the event.
4502 bool ShiftDown() const;
4508 @class wxGridEditorCreatedEvent
4510 @beginEventTable{wxGridEditorCreatedEvent}
4511 @event{EVT_GRID_EDITOR_CREATED(func)}
4512 The editor for a cell was created. Processes a
4513 @c wxEVT_GRID_EDITOR_CREATED event type.
4514 @event{EVT_GRID_CMD_EDITOR_CREATED(id, func)}
4515 The editor for a cell was created; variant taking a window identifier.
4516 Processes a @c wxEVT_GRID_EDITOR_CREATED event type.
4520 @category{grid,events}
4522 class wxGridEditorCreatedEvent
: public wxCommandEvent
4526 Default constructor.
4528 wxGridEditorCreatedEvent();
4530 Constructor for initializing all event attributes.
4532 wxGridEditorCreatedEvent(int id
, wxEventType type
, wxObject
* obj
,
4533 int row
, int col
, wxControl
* ctrl
);
4536 Returns the column at which the event occurred.
4541 Returns the edit control.
4543 wxControl
* GetControl();
4546 Returns the row at which the event occurred.
4551 Sets the column at which the event occurred.
4553 void SetCol(int col
);
4556 Sets the edit control.
4558 void SetControl(wxControl
* ctrl
);
4561 Sets the row at which the event occurred.
4563 void SetRow(int row
);