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 chosen between f|e|g|E|G (f is used by default)
270 virtual void SetParameters(const wxString
& params
);
275 void SetPrecision(int precision
);
280 void SetWidth(int width
);
284 @class wxGridCellNumberRenderer
286 This class may be used to format integer data in a cell.
291 @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
292 wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
293 wxGridCellEnumRenderer, wxGridCellFloatRenderer,
294 wxGridCellStringRenderer
296 class wxGridCellNumberRenderer
: public wxGridCellStringRenderer
302 wxGridCellNumberRenderer();
306 @class wxGridCellStringRenderer
308 This class may be used to format string data in a cell; it is the default
314 @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
315 wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
316 wxGridCellEnumRenderer, wxGridCellFloatRenderer,
317 wxGridCellNumberRenderer
319 class wxGridCellStringRenderer
: public wxGridCellRenderer
325 wxGridCellStringRenderer();
330 @class wxGridCellEditor
332 This class is responsible for providing and manipulating the in-place edit
333 controls for the grid. Instances of wxGridCellEditor (actually, instances
334 of derived classes since it is an abstract class) can be associated with
335 the cell attributes for individual cells, rows, columns, or even for the
341 @see wxGridCellAutoWrapStringEditor, wxGridCellBoolEditor,
342 wxGridCellChoiceEditor, wxGridCellEnumEditor,
343 wxGridCellFloatEditor, wxGridCellNumberEditor,
346 class wxGridCellEditor
355 Fetch the value from the table and prepare the edit control to begin
358 This function should save the original value of the grid cell at the
359 given @a row and @a col and show the control allowing the user to
364 virtual void BeginEdit(int row
, int col
, wxGrid
* grid
) = 0;
367 Create a new object which is the copy of this one.
369 virtual wxGridCellEditor
* Clone() const = 0;
372 Creates the actual edit control.
374 virtual void Create(wxWindow
* parent
, wxWindowID id
,
375 wxEvtHandler
* evtHandler
) = 0;
380 virtual void Destroy();
383 End editing the cell.
385 This function must check if the current value of the editing control is
386 valid and different from the original value (available as @a oldval in
387 its string form and possibly saved internally using its real type by
388 BeginEdit()). If it isn't, it just returns @false, otherwise it must do
390 # Save the new value internally so that ApplyEdit() could apply it.
391 # Fill @a newval (which is never @NULL) with the string
392 representation of the new value.
395 Notice that it must @em not modify the grid as the change could still
398 If the user-defined wxEVT_GRID_CELL_CHANGING event handler doesn't veto
399 this change, ApplyEdit() will be called next.
401 virtual bool EndEdit(int row
, int col
, const wxGrid
* grid
,
402 const wxString
& oldval
, wxString
* newval
) = 0;
405 Effectively save the changes in the grid.
407 This function should save the value of the control in the grid. It is
408 called only after EndEdit() returns @true.
410 virtual void ApplyEdit(int row
, int col
, wxGrid
* grid
) = 0;
413 Some types of controls on some platforms may need some help with the
416 virtual void HandleReturn(wxKeyEvent
& event
);
419 Returns @true if the edit control has been created.
424 Draws the part of the cell not occupied by the control: the base class
425 version just fills it with background colour from the attribute.
427 virtual void PaintBackground(const wxRect
& rectCell
, wxGridCellAttr
* attr
);
430 Reset the value in the control back to its starting value.
432 virtual void Reset() = 0;
435 Size and position the edit control.
437 virtual void SetSize(const wxRect
& rect
);
440 Show or hide the edit control, use the specified attributes to set
441 colours/fonts for it.
443 virtual void Show(bool show
, wxGridCellAttr
* attr
= NULL
);
446 If the editor is enabled by clicking on the cell, this method will be
449 virtual void StartingClick();
452 If the editor is enabled by pressing keys on the grid, this will be
453 called to let the editor do something about that first key if desired.
455 virtual void StartingKey(wxKeyEvent
& event
);
460 The destructor is private because only DecRef() can delete us.
462 virtual ~wxGridCellEditor();
466 @class wxGridCellAutoWrapStringEditor
468 Grid cell editor for wrappable string/text data.
473 @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor,
474 wxGridCellEnumEditor, wxGridCellFloatEditor,
475 wxGridCellNumberEditor, wxGridCellTextEditor
477 class wxGridCellAutoWrapStringEditor
: public wxGridCellTextEditor
480 wxGridCellAutoWrapStringEditor();
484 @class wxGridCellBoolEditor
486 Grid cell editor for boolean data.
491 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
492 wxGridCellChoiceEditor, wxGridCellEnumEditor,
493 wxGridCellFloatEditor, wxGridCellNumberEditor,
496 class wxGridCellBoolEditor
: public wxGridCellEditor
502 wxGridCellBoolEditor();
505 Returns @true if the given @a value is equal to the string
506 representation of the truth value we currently use (see
509 static bool IsTrueValue(const wxString
& value
);
512 This method allows you to customize the values returned by GetValue()
513 for the cell using this editor. By default, the default values of the
514 arguments are used, i.e. @c "1" is returned if the cell is checked and
515 an empty string otherwise.
517 static void UseStringValues(const wxString
& valueTrue
= "1",
518 const wxString
& valueFalse
= wxEmptyString
);
522 @class wxGridCellChoiceEditor
524 Grid cell editor for string data providing the user a choice from a list of
530 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
531 wxGridCellBoolEditor, wxGridCellEnumEditor,
532 wxGridCellFloatEditor, wxGridCellNumberEditor,
535 class wxGridCellChoiceEditor
: public wxGridCellEditor
539 Choice cell renderer ctor.
542 Number of strings from which the user can choose.
544 An array of strings from which the user can choose.
546 If allowOthers is @true, the user can type a string not in choices
549 wxGridCellChoiceEditor(size_t count
= 0,
550 const wxString choices
[] = NULL
,
551 bool allowOthers
= false);
554 Choice cell renderer ctor.
557 An array of strings from which the user can choose.
559 If allowOthers is @true, the user can type a string not in choices
562 wxGridCellChoiceEditor(const wxArrayString
& choices
,
563 bool allowOthers
= false);
566 Parameters string format is "item1[,item2[...,itemN]]"
568 virtual void SetParameters(const wxString
& params
);
572 @class wxGridCellEnumEditor
574 Grid cell editor which displays an enum number as a textual equivalent
575 (eg. data in cell is 0,1,2 ... n the cell could be displayed as
576 "John","Fred"..."Bob" in the combo choice box).
581 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
582 wxGridCellBoolEditor, wxGridCellChoiceEditor,
583 wxGridCellTextEditor, wxGridCellFloatEditor,
584 wxGridCellNumberEditor
586 class wxGridCellEnumEditor
: public wxGridCellChoiceEditor
590 Enum cell editor ctor.
593 Comma separated choice parameters "item1[,item2[...,itemN]]".
595 wxGridCellEnumEditor( const wxString
& choices
= wxEmptyString
);
599 @class wxGridCellTextEditor
601 Grid cell editor for string/text data.
606 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
607 wxGridCellBoolEditor, wxGridCellChoiceEditor,
608 wxGridCellEnumEditor, wxGridCellFloatEditor,
609 wxGridCellNumberEditor
611 class wxGridCellTextEditor
: public wxGridCellEditor
617 wxGridCellTextEditor();
620 The parameters string format is "n" where n is a number representing
623 virtual void SetParameters(const wxString
& params
);
627 @class wxGridCellFloatEditor
629 The editor for floating point numbers data.
634 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
635 wxGridCellBoolEditor, wxGridCellChoiceEditor,
636 wxGridCellEnumEditor, wxGridCellNumberEditor,
639 class wxGridCellFloatEditor
: public wxGridCellTextEditor
643 Float cell editor ctor.
646 Minimum number of characters to be shown.
648 Number of digits after the decimal dot.
650 The format to use for displaying the number, a combination of
651 ::wxGridCellFloatFormat enum elements. This parameter is only
652 available since wxWidgets 2.9.3.
654 wxGridCellFloatEditor(int width
= -1, int precision
= -1,
655 int format
= wxGRID_FLOAT_FORMAT_DEFAULT
);
658 The parameters string format is "width[,precision[,format]]" where
659 @c format should be chosen between f|e|g|E|G (f is used by default)
661 virtual void SetParameters(const wxString
& params
);
665 @class wxGridCellNumberEditor
667 Grid cell editor for numeric integer data.
672 @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
673 wxGridCellBoolEditor, wxGridCellChoiceEditor,
674 wxGridCellEnumEditor, wxGridCellFloatEditor,
677 class wxGridCellNumberEditor
: public wxGridCellTextEditor
681 Allows you to specify the range for acceptable data. Values equal to
682 -1 for both @a min and @a max indicate that no range checking should be
685 wxGridCellNumberEditor(int min
= -1, int max
= -1);
689 Parameters string format is "min,max".
691 virtual void SetParameters(const wxString
& params
);
696 If the return value is @true, the editor uses a wxSpinCtrl to get user
697 input, otherwise it uses a wxTextCtrl.
699 bool HasRange() const;
702 String representation of the value.
704 wxString
GetString() const;
710 @class wxGridCellAttr
712 This class can be used to alter the cells' appearance in the grid by
713 changing their attributes from the defaults. An object of this class may be
714 returned by wxGridTableBase::GetAttr().
723 Kind of the attribute to retrieve.
725 @see wxGridCellAttrProvider::GetAttr(), wxGridTableBase::GetAttr()
729 /// Return the combined effective attribute for the cell.
732 /// Return the attribute explicitly set for this cell.
735 /// Return the attribute set for this cells row.
738 /// Return the attribute set for this cells column.
745 wxGridCellAttr(wxGridCellAttr
* attrDefault
= NULL
);
747 Constructor specifying some of the often used attributes.
749 wxGridCellAttr(const wxColour
& colText
, const wxColour
& colBack
,
750 const wxFont
& font
, int hAlign
, int vAlign
);
753 Creates a new copy of this object.
755 wxGridCellAttr
* Clone() const;
758 This class is reference counted: it is created with ref count of 1, so
759 calling DecRef() once will delete it. Calling IncRef() allows to lock
760 it until the matching DecRef() is called.
765 Get the alignment to use for the cell with the given attribute.
767 If this attribute doesn't specify any alignment, the default attribute
768 alignment is used (which can be changed using
769 wxGrid::SetDefaultCellAlignment() but is left and top by default).
771 Notice that @a hAlign and @a vAlign values are always overwritten by
772 this function, use GetNonDefaultAlignment() if this is not desirable.
775 Horizontal alignment is returned here if this argument is non-@NULL.
776 It is one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT.
778 Vertical alignment is returned here if this argument is non-@NULL.
779 It is one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM.
781 void GetAlignment(int* hAlign
, int* vAlign
) const;
784 Returns the background colour.
786 const wxColour
& GetBackgroundColour() const;
789 Returns the cell editor.
791 wxGridCellEditor
* GetEditor(const wxGrid
* grid
, int row
, int col
) const;
796 const wxFont
& GetFont() const;
799 Get the alignment defined by this attribute.
801 Unlike GetAlignment() this function only modifies @a hAlign and @a
802 vAlign if this attribute does define a non-default alignment. This
803 means that they must be initialized before calling this function and
804 that their values will be preserved unchanged if they are different
805 from wxALIGN_INVALID.
807 For example, the following fragment can be used to use the cell
808 alignment if one is defined but right-align its contents by default
809 (instead of left-aligning it by default) while still using the default
812 int hAlign = wxALIGN_RIGHT,
813 vAlign = wxALIGN_INVALID;
814 attr.GetNonDefaultAlignment(&hAlign, &vAlign);
819 void GetNonDefaultAlignment(int *hAlign
, int *vAlign
) const;
822 Returns the cell renderer.
824 wxGridCellRenderer
* GetRenderer(const wxGrid
* grid
, int row
, int col
) const;
827 Returns the text colour.
829 const wxColour
& GetTextColour() const;
832 Returns @true if this attribute has a valid alignment set.
834 bool HasAlignment() const;
837 Returns @true if this attribute has a valid background colour set.
839 bool HasBackgroundColour() const;
842 Returns @true if this attribute has a valid cell editor set.
844 bool HasEditor() const;
847 Returns @true if this attribute has a valid font set.
849 bool HasFont() const;
852 Returns @true if this attribute has a valid cell renderer set.
854 bool HasRenderer() const;
857 Returns @true if this attribute has a valid text colour set.
859 bool HasTextColour() const;
862 This class is reference counted: it is created with ref count of 1, so
863 calling DecRef() once will delete it. Calling IncRef() allows to lock
864 it until the matching DecRef() is called.
869 Returns @true if this cell is set as read-only.
871 bool IsReadOnly() const;
874 Sets the alignment. @a hAlign can be one of @c wxALIGN_LEFT,
875 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT and @a vAlign can be one of
876 @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
878 void SetAlignment(int hAlign
, int vAlign
);
881 Sets the background colour.
883 void SetBackgroundColour(const wxColour
& colBack
);
886 @todo Needs documentation.
888 void SetDefAttr(wxGridCellAttr
* defAttr
);
891 Sets the editor to be used with the cells with this attribute.
893 void SetEditor(wxGridCellEditor
* editor
);
898 void SetFont(const wxFont
& font
);
901 Sets the cell as read-only.
903 void SetReadOnly(bool isReadOnly
= true);
906 Sets the renderer to be used for cells with this attribute. Takes
907 ownership of the pointer.
909 void SetRenderer(wxGridCellRenderer
* renderer
);
912 Sets the text colour.
914 void SetTextColour(const wxColour
& colText
);
918 Base class for corner window renderer.
920 This is the simplest of all header renderers and only has a single
923 @see wxGridCellAttrProvider::GetCornerRenderer()
927 class wxGridCornerHeaderRenderer
931 Called by the grid to draw the corner window border.
933 This method is responsible for drawing the border inside the given @a
934 rect and adjusting the rectangle size to correspond to the area inside
935 the border, i.e. usually call wxRect::Deflate() to account for the
939 The grid whose corner window is being drawn.
941 The device context to use for drawing.
943 Input/output parameter which contains the border rectangle on input
944 and should be updated to contain the area inside the border on
947 virtual void DrawBorder(const wxGrid
& grid
,
949 wxRect
& rect
) const = 0;
952 Common base class for row and column headers renderers.
954 @see wxGridColumnHeaderRenderer, wxGridRowHeaderRenderer
958 class wxGridHeaderLabelsRenderer
: public wxGridCornerHeaderRenderer
962 Called by the grid to draw the specified label.
964 Notice that the base class DrawBorder() method is called before this
967 The default implementation uses wxGrid::GetLabelTextColour() and
968 wxGrid::GetLabelFont() to draw the label.
970 virtual void DrawLabel(const wxGrid
& grid
,
972 const wxString
& value
,
976 int textOrientation
) const;
980 Base class for row headers renderer.
982 This is the same as wxGridHeaderLabelsRenderer currently but we still use a
983 separate class for it to distinguish it from wxGridColumnHeaderRenderer.
985 @see wxGridRowHeaderRendererDefault
987 @see wxGridCellAttrProvider::GetRowHeaderRenderer()
991 class wxGridRowHeaderRenderer
: public wxGridHeaderLabelsRenderer
996 Base class for column headers renderer.
998 This is the same as wxGridHeaderLabelsRenderer currently but we still use a
999 separate class for it to distinguish it from wxGridRowHeaderRenderer.
1001 @see wxGridColumnHeaderRendererDefault
1003 @see wxGridCellAttrProvider::GetColumnHeaderRenderer()
1007 class wxGridColumnHeaderRenderer
: public wxGridHeaderLabelsRenderer
1012 Default row header renderer.
1014 You may derive from this class if you need to only override one of its
1015 methods (i.e. either DrawLabel() or DrawBorder()) but continue to use the
1016 default implementation for the other one.
1018 @see wxGridColumnHeaderRendererDefault
1022 class wxGridRowHeaderRendererDefault
: public wxGridRowHeaderRenderer
1025 /// Implement border drawing for the row labels.
1026 virtual void DrawBorder(const wxGrid
& grid
,
1028 wxRect
& rect
) const;
1032 Default column header renderer.
1034 @see wxGridRowHeaderRendererDefault
1038 class wxGridColumnHeaderRendererDefault
: public wxGridColumnHeaderRenderer
1041 /// Implement border drawing for the column labels.
1042 virtual void DrawBorder(const wxGrid
& grid
,
1044 wxRect
& rect
) const;
1048 Default corner window renderer.
1050 @see wxGridColumnHeaderRendererDefault, wxGridRowHeaderRendererDefault
1054 class wxGridCornerHeaderRendererDefault
: public wxGridCornerHeaderRenderer
1057 /// Implement border drawing for the corner window.
1058 virtual void DrawBorder(const wxGrid
& grid
,
1060 wxRect
& rect
) const;
1064 Class providing attributes to be used for the grid cells.
1066 This class both defines an interface which grid cell attributes providers
1067 should implement -- and which can be implemented differently in derived
1068 classes -- and a default implementation of this interface which is often
1069 good enough to be used without modification, especially with not very large
1070 grids for which the efficiency of attributes storage hardly matters (see
1071 the discussion below).
1073 An object of this class can be associated with a wxGrid using
1074 wxGridTableBase::SetAttrProvider() but it's not necessary to call it if you
1075 intend to use the default provider as it is used by wxGridTableBase by
1078 Notice that while attributes provided by this class can be set for
1079 individual cells using SetAttr() or the entire rows or columns using
1080 SetRowAttr() and SetColAttr() they are always retrieved using GetAttr()
1084 The default implementation of this class stores the attributes passed to
1085 its SetAttr(), SetRowAttr() and SetColAttr() in a straightforward way. A
1086 derived class may use its knowledge about how the attributes are used in
1087 your program to implement it much more efficiently: for example, using a
1088 special background colour for all even-numbered rows can be implemented by
1089 simply returning the same attribute from GetAttr() if the row number is
1090 even instead of having to store N/2 row attributes where N is the total
1091 number of rows in the grid.
1093 Notice that objects of this class can't be copied.
1095 class wxGridCellAttrProvider
: public wxClientDataContainer
1098 /// Trivial default constructor.
1099 wxGridCellAttrProvider();
1101 /// Destructor releases any attributes held by this class.
1102 virtual ~wxGridCellAttrProvider();
1105 Get the attribute to use for the specified cell.
1107 If wxGridCellAttr::Any is used as @a kind value, this function combines
1108 the attributes set for this cell using SetAttr() and those for its row
1109 or column (set with SetRowAttr() or SetColAttr() respectively), with
1110 the cell attribute having the highest precedence.
1112 Notice that the caller must call DecRef() on the returned pointer if it
1116 The row of the cell.
1118 The column of the cell.
1120 The kind of the attribute to return.
1122 The attribute to use which should be DecRef()'d by caller or @NULL
1123 if no attributes are defined for this cell.
1125 virtual wxGridCellAttr
*GetAttr(int row
, int col
,
1126 wxGridCellAttr::wxAttrKind kind
) const;
1131 All these functions take ownership of the attribute passed to them,
1132 i.e. will call DecRef() on it themselves later and so it should not be
1133 destroyed by the caller. And the attribute can be @NULL to reset a
1134 previously set value.
1138 /// Set attribute for the specified cell.
1139 virtual void SetAttr(wxGridCellAttr
*attr
, int row
, int col
);
1141 /// Set attribute for the specified row.
1142 virtual void SetRowAttr(wxGridCellAttr
*attr
, int row
);
1144 /// Set attribute for the specified column.
1145 virtual void SetColAttr(wxGridCellAttr
*attr
, int col
);
1150 Getting header renderers.
1152 These functions return the renderers for the given row or column header
1153 label and the corner window. Unlike cell attributes, these objects are
1154 not reference counted and are never @NULL so they are returned by
1155 reference and not pointer and DecRef() shouldn't (and can't) be called
1158 All these functions were added in wxWidgets 2.9.1.
1163 Return the renderer used for drawing column headers.
1165 By default wxGridColumnHeaderRendererDefault is returned.
1167 @see wxGrid::SetUseNativeColLabels(), wxGrid::UseNativeColHeader()
1171 virtual const wxGridColumnHeaderRenderer
& GetColumnHeaderRenderer(int col
);
1174 Return the renderer used for drawing row headers.
1176 By default wxGridRowHeaderRendererDefault is returned.
1180 virtual const wxGridRowHeaderRenderer
& GetRowHeaderRenderer(int row
);
1183 Return the renderer used for drawing the corner window.
1185 By default wxGridCornerHeaderRendererDefault is returned.
1189 virtual const wxGridCornerHeaderRenderer
& GetCornerRenderer();
1195 Represents coordinates of a grid cell.
1197 An object of this class is simply a (row, column) pair.
1199 class wxGridCellCoords
1203 Default constructor initializes the object to invalid state.
1205 Initially the row and column are both invalid (-1) and so operator!()
1206 for an uninitialized wxGridCellCoords returns false.
1211 Constructor taking a row and a column.
1213 wxGridCellCoords(int row
, int col
);
1216 Return the row of the coordinate.
1221 Set the row of the coordinate.
1226 Return the column of the coordinate.
1231 Set the column of the coordinate.
1236 Set the row and column of the coordinate.
1238 void Set(int row
, int col
);
1241 Assignment operator for coordinate types.
1243 wxGridCellCoords
& operator=(const wxGridCellCoords
& other
);
1248 bool operator==(const wxGridCellCoords
& other
) const;
1251 Inequality operator.
1253 bool operator!=(const wxGridCellCoords
& other
) const;
1256 Checks whether the coordinates are invalid.
1258 Returns false only if both row and column are -1. Notice that if either
1259 row or column (but not both) are -1, this method returns true even if
1260 the object is invalid. This is done because objects in such state
1261 should actually never exist, i.e. either both coordinates should be -1
1262 or none of them should be -1.
1264 bool operator!() const;
1268 @class wxGridTableBase
1270 The almost abstract base class for grid tables.
1272 A grid table is responsible for storing the grid data and, indirectly, grid
1273 cell attributes. The data can be stored in the way most convenient for the
1274 application but has to be provided in string form to wxGrid. It is also
1275 possible to provide cells values in other formats if appropriate, e.g. as
1278 This base class is not quite abstract as it implements a trivial strategy
1279 for storing the attributes by forwarding it to wxGridCellAttrProvider and
1280 also provides stubs for some other functions. However it does have a number
1281 of pure virtual methods which must be implemented in the derived classes.
1283 @see wxGridStringTable
1288 class wxGridTableBase
: public wxObject
1292 Default constructor.
1297 Destructor frees the attribute provider if it was created.
1299 virtual ~wxGridTableBase();
1302 Must be overridden to return the number of rows in the table.
1304 For backwards compatibility reasons, this method is not const.
1305 Use GetRowsCount() instead of it in const methods of derived table
1308 virtual int GetNumberRows() = 0;
1311 Must be overridden to return the number of columns in the table.
1313 For backwards compatibility reasons, this method is not const.
1314 Use GetColsCount() instead of it in const methods of derived table
1317 virtual int GetNumberCols() = 0;
1320 Return the number of rows in the table.
1322 This method is not virtual and is only provided as a convenience for
1323 the derived classes which can't call GetNumberRows() without a
1324 @c const_cast from their const methods.
1326 int GetRowsCount() const;
1329 Return the number of columns in the table.
1331 This method is not virtual and is only provided as a convenience for
1332 the derived classes which can't call GetNumberCols() without a
1333 @c const_cast from their const methods.
1335 int GetColsCount() const;
1339 @name Table Cell Accessors
1344 May be overridden to implement testing for empty cells.
1346 This method is used by the grid to test if the given cell is not used
1347 and so whether a neighbouring cell may overflow into it. By default it
1348 only returns true if the value of the given cell, as returned by
1349 GetValue(), is empty.
1351 virtual bool IsEmptyCell(int row
, int col
);
1354 Same as IsEmptyCell() but taking wxGridCellCoords.
1356 Notice that this method is not virtual, only IsEmptyCell() should be
1359 bool IsEmpty(const wxGridCellCoords
& coords
);
1362 Must be overridden to implement accessing the table values as text.
1364 virtual wxString
GetValue(int row
, int col
) = 0;
1367 Must be overridden to implement setting the table values as text.
1369 virtual void SetValue(int row
, int col
, const wxString
& value
) = 0;
1372 Returns the type of the value in the given cell.
1374 By default all cells are strings and this method returns
1375 @c wxGRID_VALUE_STRING.
1377 virtual wxString
GetTypeName(int row
, int col
);
1380 Returns true if the value of the given cell can be accessed as if it
1381 were of the specified type.
1383 By default the cells can only be accessed as strings. Note that a cell
1384 could be accessible in different ways, e.g. a numeric cell may return
1385 @true for @c wxGRID_VALUE_NUMBER but also for @c wxGRID_VALUE_STRING
1386 indicating that the value can be coerced to a string form.
1388 virtual bool CanGetValueAs(int row
, int col
, const wxString
& typeName
);
1391 Returns true if the value of the given cell can be set as if it were of
1394 @see CanGetValueAs()
1396 virtual bool CanSetValueAs(int row
, int col
, const wxString
& typeName
);
1399 Returns the value of the given cell as a long.
1401 This should only be called if CanGetValueAs() returns @true when called
1402 with @c wxGRID_VALUE_NUMBER argument. Default implementation always
1405 virtual long GetValueAsLong(int row
, int col
);
1408 Returns the value of the given cell as a double.
1410 This should only be called if CanGetValueAs() returns @true when called
1411 with @c wxGRID_VALUE_FLOAT argument. Default implementation always
1414 virtual double GetValueAsDouble(int row
, int col
);
1417 Returns the value of the given cell as a boolean.
1419 This should only be called if CanGetValueAs() returns @true when called
1420 with @c wxGRID_VALUE_BOOL argument. Default implementation always
1423 virtual bool GetValueAsBool(int row
, int col
);
1426 Returns the value of the given cell as a user-defined type.
1428 This should only be called if CanGetValueAs() returns @true when called
1429 with @a typeName. Default implementation always return @NULL.
1431 virtual void *GetValueAsCustom(int row
, int col
, const wxString
& typeName
);
1434 Sets the value of the given cell as a long.
1436 This should only be called if CanSetValueAs() returns @true when called
1437 with @c wxGRID_VALUE_NUMBER argument. Default implementation doesn't do
1440 virtual void SetValueAsLong(int row
, int col
, long value
);
1443 Sets the value of the given cell as a double.
1445 This should only be called if CanSetValueAs() returns @true when called
1446 with @c wxGRID_VALUE_FLOAT argument. Default implementation doesn't do
1449 virtual void SetValueAsDouble(int row
, int col
, double value
);
1452 Sets the value of the given cell as a boolean.
1454 This should only be called if CanSetValueAs() returns @true when called
1455 with @c wxGRID_VALUE_BOOL argument. Default implementation doesn't do
1458 virtual void SetValueAsBool( int row
, int col
, bool value
);
1461 Sets the value of the given cell as a user-defined type.
1463 This should only be called if CanSetValueAs() returns @true when called
1464 with @a typeName. Default implementation doesn't do anything.
1466 virtual void SetValueAsCustom(int row
, int col
, const wxString
& typeName
,
1473 Called by the grid when the table is associated with it.
1475 The default implementation stores the pointer and returns it from its
1476 GetView() and so only makes sense if the table cannot be associated
1477 with more than one grid at a time.
1479 virtual void SetView(wxGrid
*grid
);
1482 Returns the last grid passed to SetView().
1484 virtual wxGrid
*GetView() const;
1488 @name Table Structure Modifiers
1490 Notice that none of these functions are pure virtual as they don't have
1491 to be implemented if the table structure is never modified after
1492 creation, i.e. neither rows nor columns are never added or deleted but
1493 that you do need to implement them if they are called, i.e. if your
1494 code either calls them directly or uses the matching wxGrid methods, as
1495 by default they simply do nothing which is definitely inappropriate.
1500 Clear the table contents.
1502 This method is used by wxGrid::ClearGrid().
1504 virtual void Clear();
1507 Insert additional rows into the table.
1510 The position of the first new row.
1512 The number of rows to insert.
1514 virtual bool InsertRows(size_t pos
= 0, size_t numRows
= 1);
1517 Append additional rows at the end of the table.
1519 This method is provided in addition to InsertRows() as some data models
1520 may only support appending rows to them but not inserting them at
1521 arbitrary locations. In such case you may implement this method only
1522 and leave InsertRows() unimplemented.
1525 The number of rows to add.
1527 virtual bool AppendRows(size_t numRows
= 1);
1530 Delete rows from the table.
1532 Notice that currently deleting a row intersecting a multi-cell (see
1533 SetCellSize()) is not supported and will result in a crash.
1536 The first row to delete.
1538 The number of rows to delete.
1540 virtual bool DeleteRows(size_t pos
= 0, size_t numRows
= 1);
1543 Exactly the same as InsertRows() but for columns.
1545 virtual bool InsertCols(size_t pos
= 0, size_t numCols
= 1);
1548 Exactly the same as AppendRows() but for columns.
1550 virtual bool AppendCols(size_t numCols
= 1);
1553 Exactly the same as DeleteRows() but for columns.
1555 virtual bool DeleteCols(size_t pos
= 0, size_t numCols
= 1);
1560 @name Table Row and Column Labels
1562 By default the numbers are used for labeling rows and Latin letters for
1563 labeling columns. If the table has more than 26 columns, the pairs of
1564 letters are used starting from the 27-th one and so on, i.e. the
1565 sequence of labels is A, B, ..., Z, AA, AB, ..., AZ, BA, ..., ..., ZZ,
1571 Return the label of the specified row.
1573 virtual wxString
GetRowLabelValue(int row
);
1576 Return the label of the specified column.
1578 virtual wxString
GetColLabelValue(int col
);
1581 Set the given label for the specified row.
1583 The default version does nothing, i.e. the label is not stored. You
1584 must override this method in your derived class if you wish
1585 wxGrid::SetRowLabelValue() to work.
1587 virtual void SetRowLabelValue(int row
, const wxString
& label
);
1590 Exactly the same as SetRowLabelValue() but for columns.
1592 virtual void SetColLabelValue(int col
, const wxString
& label
);
1598 @name Attributes Management
1600 By default the attributes management is delegated to
1601 wxGridCellAttrProvider class. You may override the methods in this
1602 section to handle the attributes directly if, for example, they can be
1603 computed from the cell values.
1608 Associate this attributes provider with the table.
1610 The table takes ownership of @a attrProvider pointer and will delete it
1611 when it doesn't need it any more. The pointer can be @NULL, however
1612 this won't disable attributes management in the table but will just
1613 result in a default attributes being recreated the next time any of the
1614 other functions in this section is called. To completely disable the
1615 attributes support, should this be needed, you need to override
1616 CanHaveAttributes() to return @false.
1618 void SetAttrProvider(wxGridCellAttrProvider
*attrProvider
);
1621 Returns the attribute provider currently being used.
1623 This function may return @NULL if the attribute provider hasn't been
1624 neither associated with this table by SetAttrProvider() nor created on
1625 demand by any other methods.
1627 wxGridCellAttrProvider
*GetAttrProvider() const;
1630 Return the attribute for the given cell.
1632 By default this function is simply forwarded to
1633 wxGridCellAttrProvider::GetAttr() but it may be overridden to handle
1634 attributes directly in the table.
1636 virtual wxGridCellAttr
*GetAttr(int row
, int col
,
1637 wxGridCellAttr::wxAttrKind kind
);
1640 Set attribute of the specified cell.
1642 By default this function is simply forwarded to
1643 wxGridCellAttrProvider::SetAttr().
1645 The table takes ownership of @a attr, i.e. will call DecRef() on it.
1647 virtual void SetAttr(wxGridCellAttr
* attr
, int row
, int col
);
1650 Set attribute of the specified row.
1652 By default this function is simply forwarded to
1653 wxGridCellAttrProvider::SetRowAttr().
1655 The table takes ownership of @a attr, i.e. will call DecRef() on it.
1657 virtual void SetRowAttr(wxGridCellAttr
*attr
, int row
);
1660 Set attribute of the specified column.
1662 By default this function is simply forwarded to
1663 wxGridCellAttrProvider::SetColAttr().
1665 The table takes ownership of @a attr, i.e. will call DecRef() on it.
1667 virtual void SetColAttr(wxGridCellAttr
*attr
, int col
);
1672 Returns true if this table supports attributes or false otherwise.
1674 By default, the table automatically creates a wxGridCellAttrProvider
1675 when this function is called if it had no attribute provider before and
1678 virtual bool CanHaveAttributes();
1682 @class wxGridSizesInfo
1684 wxGridSizesInfo stores information about sizes of all wxGrid rows or
1687 It assumes that most of the rows or columns (which are both called elements
1688 here as the difference between them doesn't matter at this class level)
1689 have the default size and so stores it separately. And it uses a wxHashMap
1690 to store the sizes of all elements which have the non-default size.
1692 This structure is particularly useful for serializing the sizes of all
1693 wxGrid elements at once.
1698 struct wxGridSizesInfo
1701 Default constructor.
1703 m_sizeDefault and m_customSizes must be initialized later.
1710 This constructor is used by wxGrid::GetRowSizes() and GetColSizes()
1711 methods. User code will usually use the default constructor instead.
1714 The default element size.
1716 Array containing the sizes of @em all elements, including those
1717 which have the default size.
1719 wxGridSizesInfo(int defSize
, const wxArrayInt
& allSizes
);
1722 Get the element size.
1725 The index of the element.
1727 The size for this element, using m_customSizes if @a pos is in it
1728 or m_sizeDefault otherwise.
1730 int GetSize(unsigned pos
) const;
1737 Map with element indices as keys and their sizes as values.
1739 This map only contains the elements with non-default size.
1741 wxUnsignedToIntHashMap m_customSizes
;
1748 wxGrid and its related classes are used for displaying and editing tabular
1749 data. They provide a rich set of features for display, editing, and
1750 interacting with a variety of data sources. For simple applications, and to
1751 help you get started, wxGrid is the only class you need to refer to
1752 directly. It will set up default instances of the other classes and manage
1753 them for you. For more complex applications you can derive your own classes
1754 for custom grid views, grid data tables, cell editors and renderers. The
1755 @ref overview_grid has examples of simple and more complex applications,
1756 explains the relationship between the various grid classes and has a
1757 summary of the keyboard shortcuts and mouse functions provided by wxGrid.
1759 A wxGridTableBase class holds the actual data to be displayed by a wxGrid
1760 class. One or more wxGrid classes may act as a view for one table class.
1761 The default table class is called wxGridStringTable and holds an array of
1762 strings. An instance of such a class is created by CreateGrid().
1764 wxGridCellRenderer is the abstract base class for rendering contents in a
1765 cell. The following renderers are predefined:
1767 - wxGridCellBoolRenderer
1768 - wxGridCellFloatRenderer
1769 - wxGridCellNumberRenderer
1770 - wxGridCellStringRenderer
1772 The look of a cell can be further defined using wxGridCellAttr. An object
1773 of this type may be returned by wxGridTableBase::GetAttr().
1775 wxGridCellEditor is the abstract base class for editing the value of a
1776 cell. The following editors are predefined:
1778 - wxGridCellBoolEditor
1779 - wxGridCellChoiceEditor
1780 - wxGridCellFloatEditor
1781 - wxGridCellNumberEditor
1782 - wxGridCellTextEditor
1784 Please see wxGridEvent, wxGridSizeEvent, wxGridRangeSelectEvent, and
1785 wxGridEditorCreatedEvent for the documentation of all event types you can
1791 @see @ref overview_grid, wxGridUpdateLocker
1793 class wxGrid
: public wxScrolledWindow
1798 Different selection modes supported by the grid.
1800 enum wxGridSelectionModes
1803 The default selection mode allowing selection of the individual
1804 cells as well as of the entire rows and columns.
1809 The selection mode allowing the selection of the entire rows only.
1811 The user won't be able to select any cells or columns in this mode.
1816 The selection mode allowing the selection of the entire columns only.
1818 The user won't be able to select any cells or rows in this mode.
1820 wxGridSelectColumns
,
1823 The selection mode allowing the user to select either the entire
1824 columns or the entire rows but not individual cells nor blocks.
1826 Notice that while this constant is defined as @code
1827 wxGridSelectColumns | wxGridSelectRows @endcode this doesn't mean
1828 that all the other combinations are valid -- at least currently
1833 wxGridSelectRowsOrColumns
1837 Return values for GetCellSize().
1843 /// This cell is inside a span covered by another cell.
1844 CellSpan_Inside
= -1,
1846 /// This is a normal, non-spanning cell.
1849 /// This cell spans several physical wxGrid cells.
1854 @name Constructors and Initialization
1859 Default constructor.
1861 You must call Create() to really create the grid window and also call
1862 CreateGrid() or SetTable() to initialize the grid contents.
1866 Constructor creating the grid window.
1868 You must call either CreateGrid() or SetTable() to initialize the grid
1869 contents before using it.
1871 wxGrid(wxWindow
* parent
, wxWindowID id
,
1872 const wxPoint
& pos
= wxDefaultPosition
,
1873 const wxSize
& size
= wxDefaultSize
,
1874 long style
= wxWANTS_CHARS
,
1875 const wxString
& name
= wxGridNameStr
);
1880 This will also destroy the associated grid table unless you passed a
1881 table object to the grid and specified that the grid should not take
1882 ownership of the table (see SetTable()).
1887 Creates the grid window for an object initialized using the default
1890 You must call either CreateGrid() or SetTable() to initialize the grid
1891 contents before using it.
1893 bool Create(wxWindow
* parent
, wxWindowID id
,
1894 const wxPoint
& pos
= wxDefaultPosition
,
1895 const wxSize
& size
= wxDefaultSize
,
1896 long style
= wxWANTS_CHARS
,
1897 const wxString
& name
= wxGridNameStr
);
1900 Creates a grid with the specified initial number of rows and columns.
1902 Call this directly after the grid constructor. When you use this
1903 function wxGrid will create and manage a simple table of string values
1904 for you. All of the grid data will be stored in memory.
1906 For applications with more complex data types or relationships, or for
1907 dealing with very large datasets, you should derive your own grid table
1908 class and pass a table object to the grid with SetTable().
1910 bool CreateGrid(int numRows
, int numCols
,
1911 wxGridSelectionModes selmode
= wxGridSelectCells
);
1914 Passes a pointer to a custom grid table to be used by the grid.
1916 This should be called after the grid constructor and before using the
1917 grid object. If @a takeOwnership is set to @true then the table will be
1918 deleted by the wxGrid destructor.
1920 Use this function instead of CreateGrid() when your application
1921 involves complex or non-string data or data sets that are too large to
1922 fit wholly in memory.
1924 bool SetTable(wxGridTableBase
* table
, bool takeOwnership
= false,
1925 wxGridSelectionModes selmode
= wxGridSelectCells
);
1931 @name Grid Line Formatting
1936 Turns the drawing of grid lines on or off.
1938 void EnableGridLines(bool enable
= true);
1941 Returns the pen used for vertical grid lines.
1943 This virtual function may be overridden in derived classes in order to
1944 change the appearance of individual grid lines for the given column
1947 See GetRowGridLinePen() for an example.
1949 virtual wxPen
GetColGridLinePen(int col
);
1952 Returns the pen used for grid lines.
1954 This virtual function may be overridden in derived classes in order to
1955 change the appearance of grid lines. Note that currently the pen width
1958 @see GetColGridLinePen(), GetRowGridLinePen()
1960 virtual wxPen
GetDefaultGridLinePen();
1963 Returns the colour used for grid lines.
1965 @see GetDefaultGridLinePen()
1967 wxColour
GetGridLineColour() const;
1970 Returns the pen used for horizontal grid lines.
1972 This virtual function may be overridden in derived classes in order to
1973 change the appearance of individual grid line for the given @a row.
1977 // in a grid displaying music notation, use a solid black pen between
1978 // octaves (C0=row 127, C1=row 115 etc.)
1979 wxPen MidiGrid::GetRowGridLinePen(int row)
1981 if ( row % 12 == 7 )
1982 return wxPen(*wxBLACK, 1, wxSOLID);
1984 return GetDefaultGridLinePen();
1988 virtual wxPen
GetRowGridLinePen(int row
);
1991 Returns @true if drawing of grid lines is turned on, @false otherwise.
1993 bool GridLinesEnabled() const;
1996 Sets the colour used to draw grid lines.
1998 void SetGridLineColour(const wxColour
& colour
);
2004 @name Label Values and Formatting
2009 Sets the arguments to the current column label alignment values.
2011 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2012 or @c wxALIGN_RIGHT.
2014 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2017 void GetColLabelAlignment(int* horiz
, int* vert
) const;
2020 Returns the orientation of the column labels (either @c wxHORIZONTAL or
2023 int GetColLabelTextOrientation() const;
2026 Returns the specified column label.
2028 The default grid table class provides column labels of the form
2029 A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can
2030 override wxGridTableBase::GetColLabelValue() to provide your own
2033 wxString
GetColLabelValue(int col
) const;
2036 Returns the colour used for the background of row and column labels.
2038 wxColour
GetLabelBackgroundColour() const;
2041 Returns the font used for row and column labels.
2043 wxFont
GetLabelFont() const;
2046 Returns the colour used for row and column label text.
2048 wxColour
GetLabelTextColour() const;
2051 Returns the alignment used for row labels.
2053 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2054 or @c wxALIGN_RIGHT.
2056 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2059 void GetRowLabelAlignment(int* horiz
, int* vert
) const;
2062 Returns the specified row label.
2064 The default grid table class provides numeric row labels. If you are
2065 using a custom grid table you can override
2066 wxGridTableBase::GetRowLabelValue() to provide your own labels.
2068 wxString
GetRowLabelValue(int row
) const;
2071 Hides the column labels by calling SetColLabelSize() with a size of 0.
2072 Show labels again by calling that method with a width greater than 0.
2074 void HideColLabels();
2077 Hides the row labels by calling SetRowLabelSize() with a size of 0.
2079 The labels can be shown again by calling SetRowLabelSize() with a width
2082 void HideRowLabels();
2085 Sets the horizontal and vertical alignment of column label text.
2087 Horizontal alignment should be one of @c wxALIGN_LEFT,
2088 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
2089 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
2091 void SetColLabelAlignment(int horiz
, int vert
);
2094 Sets the orientation of the column labels (either @c wxHORIZONTAL or
2097 void SetColLabelTextOrientation(int textOrientation
);
2100 Set the value for the given column label.
2102 If you are using a custom grid table you must override
2103 wxGridTableBase::SetColLabelValue() for this to have any effect.
2105 void SetColLabelValue(int col
, const wxString
& value
);
2108 Sets the background colour for row and column labels.
2110 void SetLabelBackgroundColour(const wxColour
& colour
);
2113 Sets the font for row and column labels.
2115 void SetLabelFont(const wxFont
& font
);
2118 Sets the colour for row and column label text.
2120 void SetLabelTextColour(const wxColour
& colour
);
2123 Sets the horizontal and vertical alignment of row label text.
2125 Horizontal alignment should be one of @c wxALIGN_LEFT,
2126 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
2127 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
2129 void SetRowLabelAlignment(int horiz
, int vert
);
2132 Sets the value for the given row label.
2134 If you are using a derived grid table you must override
2135 wxGridTableBase::SetRowLabelValue() for this to have any effect.
2137 void SetRowLabelValue(int row
, const wxString
& value
);
2140 Call this in order to make the column labels use a native look by using
2141 wxRendererNative::DrawHeaderButton() internally.
2143 There is no equivalent method for drawing row columns as there is not
2144 native look for that. This option is useful when using wxGrid for
2145 displaying tables and not as a spread-sheet.
2147 @see UseNativeColHeader()
2149 void SetUseNativeColLabels(bool native
= true);
2152 Enable the use of native header window for column labels.
2154 If this function is called with @true argument, a wxHeaderCtrl is used
2155 instead to display the column labels instead of drawing them in wxGrid
2156 code itself. This has the advantage of making the grid look and feel
2157 perfectly the same as native applications (using SetUseNativeColLabels()
2158 the grid can be made to look more natively but it still doesn't feel
2159 natively, notably the column resizing and dragging still works slightly
2160 differently as it is implemented in wxWidgets itself) but results in
2161 different behaviour for column and row headers, for which there is no
2162 equivalent function, and, most importantly, is unsuitable for grids
2163 with huge numbers of columns as wxHeaderCtrl doesn't support virtual
2164 mode. Because of this, by default the grid does not use the native
2165 header control but you should call this function to enable it if you
2166 are using the grid to display tabular data and don't have thousands of
2169 Another difference between the default behaviour and the native header
2170 behaviour is that the latter provides the user with a context menu
2171 (which appears on right clicking the header) allowing to rearrange the
2172 grid columns if CanDragColMove() returns @true. If you want to prevent
2173 this from happening for some reason, you need to define a handler for
2174 @c wxEVT_GRID_LABEL_RIGHT_CLICK event which simply does nothing (in
2175 particular doesn't skip the event) as this will prevent the default
2176 right click handling from working.
2178 Also note that currently @c wxEVT_GRID_LABEL_RIGHT_DCLICK event is not
2179 generated for the column labels if the native columns header is used
2180 (but this limitation could possibly be lifted in the future).
2182 void UseNativeColHeader(bool native
= true);
2188 @name Cell Formatting
2190 Note that wxGridCellAttr can be used alternatively to most of these
2191 methods. See the "Attributes Management" of wxGridTableBase.
2196 Sets the arguments to the horizontal and vertical text alignment values
2197 for the grid cell at the specified location.
2199 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2200 or @c wxALIGN_RIGHT.
2202 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2205 void GetCellAlignment(int row
, int col
, int* horiz
, int* vert
) const;
2208 Returns the background colour of the cell at the specified location.
2210 wxColour
GetCellBackgroundColour(int row
, int col
) const;
2213 Returns the font for text in the grid cell at the specified location.
2215 wxFont
GetCellFont(int row
, int col
) const;
2218 Returns the text colour for the grid cell at the specified location.
2220 wxColour
GetCellTextColour(int row
, int col
) const;
2223 Returns the default cell alignment.
2225 Horizontal alignment will be one of @c wxALIGN_LEFT, @c wxALIGN_CENTRE
2226 or @c wxALIGN_RIGHT.
2228 Vertical alignment will be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE or
2231 @see SetDefaultCellAlignment()
2233 void GetDefaultCellAlignment(int* horiz
, int* vert
) const;
2236 Returns the current default background colour for grid cells.
2238 wxColour
GetDefaultCellBackgroundColour() const;
2241 Returns the current default font for grid cell text.
2243 wxFont
GetDefaultCellFont() const;
2246 Returns the current default colour for grid cell text.
2248 wxColour
GetDefaultCellTextColour() const;
2251 Sets the horizontal and vertical alignment for grid cell text at the
2254 Horizontal alignment should be one of @c wxALIGN_LEFT,
2255 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT.
2257 Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
2258 or @c wxALIGN_BOTTOM.
2260 void SetCellAlignment(int row
, int col
, int horiz
, int vert
);
2262 Sets the horizontal and vertical alignment for grid cell text at the
2265 Horizontal alignment should be one of @c wxALIGN_LEFT,
2266 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT.
2268 Vertical alignment should be one of @c wxALIGN_TOP, @c wxALIGN_CENTRE
2269 or @c wxALIGN_BOTTOM.
2271 void SetCellAlignment(int align
, int row
, int col
);
2274 Set the background colour for the given cell or all cells by default.
2276 void SetCellBackgroundColour(int row
, int col
, const wxColour
& colour
);
2279 Sets the font for text in the grid cell at the specified location.
2281 void SetCellFont(int row
, int col
, const wxFont
& font
);
2284 Sets the text colour for the given cell.
2286 void SetCellTextColour(int row
, int col
, const wxColour
& colour
);
2288 Sets the text colour for the given cell.
2290 void SetCellTextColour(const wxColour
& val
, int row
, int col
);
2292 Sets the text colour for all cells by default.
2294 void SetCellTextColour(const wxColour
& colour
);
2297 Sets the default horizontal and vertical alignment for grid cell text.
2299 Horizontal alignment should be one of @c wxALIGN_LEFT,
2300 @c wxALIGN_CENTRE or @c wxALIGN_RIGHT. Vertical alignment should be one
2301 of @c wxALIGN_TOP, @c wxALIGN_CENTRE or @c wxALIGN_BOTTOM.
2303 void SetDefaultCellAlignment(int horiz
, int vert
);
2306 Sets the default background colour for grid cells.
2308 void SetDefaultCellBackgroundColour(const wxColour
& colour
);
2311 Sets the default font to be used for grid cell text.
2313 void SetDefaultCellFont(const wxFont
& font
);
2316 Sets the current default colour for grid cell text.
2318 void SetDefaultCellTextColour(const wxColour
& colour
);
2324 @name Cell Values, Editors, and Renderers
2326 Note that wxGridCellAttr can be used alternatively to most of these
2327 methods. See the "Attributes Management" of wxGridTableBase.
2332 Returns @true if the in-place edit control for the current grid cell
2333 can be used and @false otherwise.
2335 This function always returns @false for the read-only cells.
2337 bool CanEnableCellControl() const;
2340 Disables in-place editing of grid cells.
2342 Equivalent to calling EnableCellEditControl(@false).
2344 void DisableCellEditControl();
2347 Enables or disables in-place editing of grid cell data.
2349 The grid will issue either a @c wxEVT_GRID_EDITOR_SHOWN or
2350 @c wxEVT_GRID_EDITOR_HIDDEN event.
2352 void EnableCellEditControl(bool enable
= true);
2355 Makes the grid globally editable or read-only.
2357 If the edit argument is @false this function sets the whole grid as
2358 read-only. If the argument is @true the grid is set to the default
2359 state where cells may be editable. In the default state you can set
2360 single grid cells and whole rows and columns to be editable or
2361 read-only via wxGridCellAttr::SetReadOnly(). For single cells you
2362 can also use the shortcut function SetReadOnly().
2364 For more information about controlling grid cell attributes see the
2365 wxGridCellAttr class and the @ref overview_grid.
2367 void EnableEditing(bool edit
);
2370 Returns a pointer to the editor for the cell at the specified location.
2372 See wxGridCellEditor and the @ref overview_grid for more information
2373 about cell editors and renderers.
2375 The caller must call DecRef() on the returned pointer.
2377 wxGridCellEditor
* GetCellEditor(int row
, int col
) const;
2380 Returns a pointer to the renderer for the grid cell at the specified
2383 See wxGridCellRenderer and the @ref overview_grid for more information
2384 about cell editors and renderers.
2386 The caller must call DecRef() on the returned pointer.
2388 wxGridCellRenderer
* GetCellRenderer(int row
, int col
) const;
2391 Returns the string contained in the cell at the specified location.
2393 For simple applications where a grid object automatically uses a
2394 default grid table of string values you use this function together with
2395 SetCellValue() to access cell values. For more complex applications
2396 where you have derived your own grid table class that contains various
2397 data types (e.g. numeric, boolean or user-defined custom types) then
2398 you only use this function for those cells that contain string values.
2400 See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
2403 wxString
GetCellValue(int row
, int col
) const;
2405 Returns the string contained in the cell at the specified location.
2407 For simple applications where a grid object automatically uses a
2408 default grid table of string values you use this function together with
2409 SetCellValue() to access cell values. For more complex applications
2410 where you have derived your own grid table class that contains various
2411 data types (e.g. numeric, boolean or user-defined custom types) then
2412 you only use this function for those cells that contain string values.
2414 See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for
2417 wxString
GetCellValue(const wxGridCellCoords
& coords
) const;
2420 Returns a pointer to the current default grid cell editor.
2422 See wxGridCellEditor and the @ref overview_grid for more information
2423 about cell editors and renderers.
2425 wxGridCellEditor
* GetDefaultEditor() const;
2428 Returns the default editor for the specified cell.
2430 The base class version returns the editor appropriate for the current
2431 cell type but this method may be overridden in the derived classes to
2432 use custom editors for some cells by default.
2434 Notice that the same may be achieved in a usually simpler way by
2435 associating a custom editor with the given cell or cells.
2437 The caller must call DecRef() on the returned pointer.
2439 virtual wxGridCellEditor
* GetDefaultEditorForCell(int row
, int col
) const;
2441 Returns the default editor for the specified cell.
2443 The base class version returns the editor appropriate for the current
2444 cell type but this method may be overridden in the derived classes to
2445 use custom editors for some cells by default.
2447 Notice that the same may be achieved in a usually simpler way by
2448 associating a custom editor with the given cell or cells.
2450 The caller must call DecRef() on the returned pointer.
2452 wxGridCellEditor
* GetDefaultEditorForCell(const wxGridCellCoords
& c
) const;
2455 Returns the default editor for the cells containing values of the given
2458 The base class version returns the editor which was associated with the
2459 specified @a typeName when it was registered RegisterDataType() but
2460 this function may be overridden to return something different. This
2461 allows to override an editor used for one of the standard types.
2463 The caller must call DecRef() on the returned pointer.
2465 virtual wxGridCellEditor
* GetDefaultEditorForType(const wxString
& typeName
) const;
2468 Returns a pointer to the current default grid cell renderer.
2470 See wxGridCellRenderer and the @ref overview_grid for more information
2471 about cell editors and renderers.
2473 The caller must call DecRef() on the returned pointer.
2475 wxGridCellRenderer
* GetDefaultRenderer() const;
2478 Returns the default renderer for the given cell.
2480 The base class version returns the renderer appropriate for the current
2481 cell type but this method may be overridden in the derived classes to
2482 use custom renderers for some cells by default.
2484 The caller must call DecRef() on the returned pointer.
2486 virtual wxGridCellRenderer
* GetDefaultRendererForCell(int row
, int col
) const;
2489 Returns the default renderer for the cell containing values of the
2492 @see GetDefaultEditorForType()
2494 virtual wxGridCellRenderer
* GetDefaultRendererForType(const wxString
& typeName
) const;
2497 Hides the in-place cell edit control.
2499 void HideCellEditControl();
2502 Returns @true if the in-place edit control is currently enabled.
2504 bool IsCellEditControlEnabled() const;
2507 Returns @true if the current cell is read-only.
2509 @see SetReadOnly(), IsReadOnly()
2511 bool IsCurrentCellReadOnly() const;
2514 Returns @false if the whole grid has been set as read-only or @true
2517 See EnableEditing() for more information about controlling the editing
2518 status of grid cells.
2520 bool IsEditable() const;
2523 Returns @true if the cell at the specified location can't be edited.
2525 @see SetReadOnly(), IsCurrentCellReadOnly()
2527 bool IsReadOnly(int row
, int col
) const;
2530 Register a new data type.
2532 The data types allow to naturally associate specific renderers and
2533 editors to the cells containing values of the given type. For example,
2534 the grid automatically registers a data type with the name
2535 @c wxGRID_VALUE_STRING which uses wxGridCellStringRenderer and
2536 wxGridCellTextEditor as its renderer and editor respectively -- this is
2537 the data type used by all the cells of the default wxGridStringTable,
2538 so this renderer and editor are used by default for all grid cells.
2540 However if a custom table returns @c wxGRID_VALUE_BOOL from its
2541 wxGridTableBase::GetTypeName() method, then wxGridCellBoolRenderer and
2542 wxGridCellBoolEditor are used for it because the grid also registers a
2543 boolean data type with this name.
2545 And as this mechanism is completely generic, you may register your own
2546 data types using your own custom renderers and editors. Just remember
2547 that the table must identify a cell as being of the given type for them
2548 to be used for this cell.
2551 Name of the new type. May be any string, but if the type name is
2552 the same as the name of an already registered type, including one
2553 of the standard ones (which are @c wxGRID_VALUE_STRING, @c
2554 wxGRID_VALUE_BOOL, @c wxGRID_VALUE_NUMBER, @c wxGRID_VALUE_FLOAT
2555 and @c wxGRID_VALUE_CHOICE), then the new registration information
2556 replaces the previously used renderer and editor.
2558 The renderer to use for the cells of this type. Its ownership is
2559 taken by the grid, i.e. it will call DecRef() on this pointer when
2560 it doesn't need it any longer.
2562 The editor to use for the cells of this type. Its ownership is also
2565 void RegisterDataType(const wxString
& typeName
,
2566 wxGridCellRenderer
* renderer
,
2567 wxGridCellEditor
* editor
);
2570 Sets the value of the current grid cell to the current in-place edit
2573 This is called automatically when the grid cursor moves from the
2574 current cell to a new cell. It is also a good idea to call this
2575 function when closing a grid since any edits to the final cell location
2576 will not be saved otherwise.
2578 void SaveEditControlValue();
2581 Sets the editor for the grid cell at the specified location.
2583 The grid will take ownership of the pointer.
2585 See wxGridCellEditor and the @ref overview_grid for more information
2586 about cell editors and renderers.
2588 void SetCellEditor(int row
, int col
, wxGridCellEditor
* editor
);
2591 Sets the renderer for the grid cell at the specified location.
2593 The grid will take ownership of the pointer.
2595 See wxGridCellRenderer and the @ref overview_grid for more information
2596 about cell editors and renderers.
2598 void SetCellRenderer(int row
, int col
, wxGridCellRenderer
* renderer
);
2601 Sets the string value for the cell at the specified location.
2603 For simple applications where a grid object automatically uses a
2604 default grid table of string values you use this function together with
2605 GetCellValue() to access cell values. For more complex applications
2606 where you have derived your own grid table class that contains various
2607 data types (e.g. numeric, boolean or user-defined custom types) then
2608 you only use this function for those cells that contain string values.
2610 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2613 void SetCellValue(int row
, int col
, const wxString
& s
);
2615 Sets the string value for the cell at the specified location.
2617 For simple applications where a grid object automatically uses a
2618 default grid table of string values you use this function together with
2619 GetCellValue() to access cell values. For more complex applications
2620 where you have derived your own grid table class that contains various
2621 data types (e.g. numeric, boolean or user-defined custom types) then
2622 you only use this function for those cells that contain string values.
2624 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2627 void SetCellValue(const wxGridCellCoords
& coords
, const wxString
& s
);
2629 @deprecated Please use SetCellValue(int,int,const wxString&) or
2630 SetCellValue(const wxGridCellCoords&,const wxString&)
2633 Sets the string value for the cell at the specified location.
2635 For simple applications where a grid object automatically uses a
2636 default grid table of string values you use this function together with
2637 GetCellValue() to access cell values. For more complex applications
2638 where you have derived your own grid table class that contains various
2639 data types (e.g. numeric, boolean or user-defined custom types) then
2640 you only use this function for those cells that contain string values.
2642 See wxGridTableBase::CanSetValueAs() and the @ref overview_grid for
2645 void SetCellValue(const wxString
& val
, int row
, int col
);
2648 Sets the specified column to display boolean values.
2650 @see SetColFormatCustom()
2652 void SetColFormatBool(int col
);
2655 Sets the specified column to display data in a custom format.
2657 This method provides an alternative to defining a custom grid table
2658 which would return @a typeName from its GetTypeName() method for the
2659 cells in this column: while it doesn't really change the type of the
2660 cells in this column, it does associate the renderer and editor used
2661 for the cells of the specified type with them.
2663 See the @ref overview_grid for more information on working with custom
2666 void SetColFormatCustom(int col
, const wxString
& typeName
);
2669 Sets the specified column to display floating point values with the
2670 given width and precision.
2672 @see SetColFormatCustom()
2674 void SetColFormatFloat(int col
, int width
= -1, int precision
= -1);
2677 Sets the specified column to display integer values.
2679 @see SetColFormatCustom()
2681 void SetColFormatNumber(int col
);
2684 Sets the default editor for grid cells.
2686 The grid will take ownership of the pointer.
2688 See wxGridCellEditor and the @ref overview_grid for more information
2689 about cell editors and renderers.
2691 void SetDefaultEditor(wxGridCellEditor
* editor
);
2694 Sets the default renderer for grid cells.
2696 The grid will take ownership of the pointer.
2698 See wxGridCellRenderer and the @ref overview_grid for more information
2699 about cell editors and renderers.
2701 void SetDefaultRenderer(wxGridCellRenderer
* renderer
);
2704 Makes the cell at the specified location read-only or editable.
2708 void SetReadOnly(int row
, int col
, bool isReadOnly
= true);
2711 Displays the in-place cell edit control for the current cell.
2713 void ShowCellEditControl();
2719 @name Column and Row Sizes
2721 @see @ref overview_grid_resizing
2726 Automatically sets the height and width of all rows and columns to fit
2732 Automatically adjusts width of the column to fit its label.
2734 void AutoSizeColLabelSize(int col
);
2737 Automatically sizes the column to fit its contents. If @a setAsMin is
2738 @true the calculated width will also be set as the minimal width for
2741 void AutoSizeColumn(int col
, bool setAsMin
= true);
2744 Automatically sizes all columns to fit their contents. If @a setAsMin
2745 is @true the calculated widths will also be set as the minimal widths
2748 void AutoSizeColumns(bool setAsMin
= true);
2751 Automatically sizes the row to fit its contents. If @a setAsMin is
2752 @true the calculated height will also be set as the minimal height for
2755 void AutoSizeRow(int row
, bool setAsMin
= true);
2758 Automatically adjusts height of the row to fit its label.
2760 void AutoSizeRowLabelSize(int col
);
2763 Automatically sizes all rows to fit their contents. If @a setAsMin is
2764 @true the calculated heights will also be set as the minimal heights
2767 void AutoSizeRows(bool setAsMin
= true);
2770 Returns the current height of the column labels.
2772 int GetColLabelSize() const;
2775 Returns the minimal width to which a column may be resized.
2777 Use SetColMinimalAcceptableWidth() to change this value globally or
2778 SetColMinimalWidth() to do it for individual columns.
2780 @see GetRowMinimalAcceptableHeight()
2782 int GetColMinimalAcceptableWidth() const;
2785 Returns the width of the specified column.
2787 int GetColSize(int col
) const;
2790 Returns @true if the specified column is not currently hidden.
2792 bool IsColShown(int col
) const;
2795 Returns the default height for column labels.
2797 int GetDefaultColLabelSize() const;
2800 Returns the current default width for grid columns.
2802 int GetDefaultColSize() const;
2805 Returns the default width for the row labels.
2807 int GetDefaultRowLabelSize() const;
2810 Returns the current default height for grid rows.
2812 int GetDefaultRowSize() const;
2815 Returns the minimal size to which rows can be resized.
2817 Use SetRowMinimalAcceptableHeight() to change this value globally or
2818 SetRowMinimalHeight() to do it for individual cells.
2820 @see GetColMinimalAcceptableWidth()
2822 int GetRowMinimalAcceptableHeight() const;
2825 Returns the current width of the row labels.
2827 int GetRowLabelSize() const;
2830 Returns the height of the specified row.
2832 int GetRowSize(int row
) const;
2835 Returns @true if the specified row is not currently hidden.
2837 bool IsRowShown(int row
) const;
2840 Sets the height of the column labels.
2842 If @a height equals to @c wxGRID_AUTOSIZE then height is calculated
2843 automatically so that no label is truncated. Note that this could be
2844 slow for a large table.
2846 void SetColLabelSize(int height
);
2849 Sets the minimal @a width to which the user can resize columns.
2851 @see GetColMinimalAcceptableWidth()
2853 void SetColMinimalAcceptableWidth(int width
);
2856 Sets the minimal @a width for the specified column @a col.
2858 It is usually best to call this method during grid creation as calling
2859 it later will not resize the column to the given minimal width even if
2860 it is currently narrower than it.
2862 @a width must be greater than the minimal acceptable column width as
2863 returned by GetColMinimalAcceptableWidth().
2865 void SetColMinimalWidth(int col
, int width
);
2868 Sets the width of the specified column.
2873 The new column width in pixels, 0 to hide the column or -1 to fit
2874 the column width to its label width.
2876 void SetColSize(int col
, int width
);
2879 Hides the specified column.
2881 To show the column later you need to call SetColSize() with non-0
2887 void HideCol(int col
);
2890 Shows the previously hidden column by resizing it to non-0 size.
2892 @see HideCol(), SetColSize()
2894 void ShowCol(int col
);
2898 Sets the default width for columns in the grid.
2900 This will only affect columns subsequently added to the grid unless
2901 @a resizeExistingCols is @true.
2903 If @a width is less than GetColMinimalAcceptableWidth(), then the
2904 minimal acceptable width is used instead of it.
2906 void SetDefaultColSize(int width
, bool resizeExistingCols
= false);
2909 Sets the default height for rows in the grid.
2911 This will only affect rows subsequently added to the grid unless
2912 @a resizeExistingRows is @true.
2914 If @a height is less than GetRowMinimalAcceptableHeight(), then the
2915 minimal acceptable height is used instead of it.
2917 void SetDefaultRowSize(int height
, bool resizeExistingRows
= false);
2920 Sets the width of the row labels.
2922 If @a width equals @c wxGRID_AUTOSIZE then width is calculated
2923 automatically so that no label is truncated. Note that this could be
2924 slow for a large table.
2926 void SetRowLabelSize(int width
);
2929 Sets the minimal row @a height used by default.
2931 See SetColMinimalAcceptableWidth() for more information.
2933 void SetRowMinimalAcceptableHeight(int height
);
2936 Sets the minimal @a height for the specified @a row.
2938 See SetColMinimalWidth() for more information.
2940 void SetRowMinimalHeight(int row
, int height
);
2943 Sets the height of the specified row.
2945 See SetColSize() for more information.
2947 void SetRowSize(int row
, int height
);
2950 Hides the specified row.
2952 To show the row later you need to call SetRowSize() with non-0
2958 void HideRow(int col
);
2961 Shows the previously hidden row by resizing it to non-0 size.
2963 @see HideRow(), SetRowSize()
2965 void ShowRow(int col
);
2968 Get size information for all columns at once.
2970 This method is useful when the information about all column widths
2971 needs to be saved. The widths can be later restored using
2974 @sa wxGridSizesInfo, GetRowSizes()
2976 wxGridSizesInfo
GetColSizes() const;
2979 Get size information for all row at once.
2981 @sa wxGridSizesInfo, GetColSizes()
2983 wxGridSizesInfo
GetRowSizes() const;
2986 Restore all columns sizes.
2988 This is usually called with wxGridSizesInfo object previously returned
2993 void SetColSizes(const wxGridSizesInfo
& sizeInfo
);
2996 Restore all rows sizes.
3000 void SetRowSizes(const wxGridSizesInfo
& sizeInfo
);
3003 Set the size of the cell.
3005 Specifying a value of more than 1 in @a num_rows or @a num_cols will
3006 make the cell at (@a row, @a col) span the block of the specified size,
3007 covering the other cells which would be normally shown in it. Passing 1
3008 for both arguments resets the cell to normal appearance.
3013 The row of the cell.
3015 The column of the cell.
3017 Number of rows to be occupied by this cell, must be >= 1.
3019 Number of columns to be occupied by this cell, must be >= 1.
3021 void SetCellSize(int row
, int col
, int num_rows
, int num_cols
);
3024 Get the size of the cell in number of cells covered by it.
3026 For normal cells, the function fills both @a num_rows and @a num_cols
3027 with 1 and returns CellSpan_None. For cells which span multiple cells, i.e.
3028 for which SetCellSize() had been called, the returned values are the
3029 same ones as were passed to SetCellSize() call and the function return
3030 value is CellSpan_Main.
3032 More unexpectedly, perhaps, the returned values may be @em negative for
3033 the cells which are inside a span covered by a cell occupying multiple
3034 rows or columns. They correspond to the offset of the main cell of the
3035 span from the cell passed to this functions and the function returns
3036 CellSpan_Inside value to indicate this.
3038 As an example, consider a 3*3 grid with the cell (1, 1) (the one in the
3039 middle) having a span of 2 rows and 2 columns, i.e. the grid looks like
3049 Then the function returns 2 and 2 in @a num_rows and @a num_cols for
3050 the cell (1, 1) itself and -1 and -1 for the cell (2, 2) as well as -1
3051 and 0 for the cell (2, 1).
3054 The row of the cell.
3056 The column of the cell.
3058 Pointer to variable receiving the number of rows, must not be @NULL.
3060 Pointer to variable receiving the number of columns, must not be
3063 The kind of this cell span (the return value is new in wxWidgets
3064 2.9.1, this function was void in previous wxWidgets versions).
3066 CellSpan
GetCellSize( int row
, int col
, int *num_rows
, int *num_cols
) const;
3069 Get the number of rows and columns allocated for this cell.
3071 This overload doesn't return a CellSpan value but the values returned
3072 may still be negative, see GetCellSize(int, int, int *, int *) for
3075 wxSize
GetCellSize(const wxGridCellCoords
& coords
);
3081 @name User-Resizing and Dragging
3083 Functions controlling various interactive mouse operations.
3085 By default, columns and rows can be resized by dragging the edges of
3086 their labels (this can be disabled using DisableDragColSize() and
3087 DisableDragRowSize() methods). And if grid line dragging is enabled with
3088 EnableDragGridSize() they can also be resized by dragging the right or
3089 bottom edge of the grid cells.
3091 Columns can also be moved to interactively change their order but this
3092 needs to be explicitly enabled with EnableDragColMove().
3097 Return @true if the dragging of cells is enabled or @false otherwise.
3099 bool CanDragCell() const;
3102 Returns @true if columns can be moved by dragging with the mouse.
3104 Columns can be moved by dragging on their labels.
3106 bool CanDragColMove() const;
3109 Returns @true if the given column can be resized by dragging with the
3112 This function returns @true if resizing the columns interactively is
3113 globally enabled, i.e. if DisableDragColSize() hadn't been called, and
3114 if this column wasn't explicitly marked as non-resizable with
3117 bool CanDragColSize(int col
) const;
3120 Return @true if the dragging of grid lines to resize rows and columns
3121 is enabled or @false otherwise.
3123 bool CanDragGridSize() const;
3126 Returns @true if the given row can be resized by dragging with the
3129 This is the same as CanDragColSize() but for rows.
3131 bool CanDragRowSize(int row
) const;
3134 Disable interactive resizing of the specified column.
3136 This method allows to disable resizing of an individual column in a
3137 grid where the columns are otherwise resizable (which is the case by
3140 Notice that currently there is no way to make some columns resizable in
3141 a grid where columns can't be resized by default as there doesn't seem
3142 to be any need for this in practice. There is also no way to make the
3143 column marked as fixed using this method resizable again because it is
3144 supposed that fixed columns are used for static parts of the grid and
3145 so should remain fixed during the entire grid lifetime.
3147 Also notice that disabling interactive column resizing will not prevent
3148 the program from changing the column size.
3150 @see EnableDragColSize()
3152 void DisableColResize(int col
);
3155 Disable interactive resizing of the specified row.
3157 This is the same as DisableColResize() but for rows.
3159 @see EnableDragRowSize()
3161 void DisableRowResize(int row
);
3164 Disables column moving by dragging with the mouse.
3166 Equivalent to passing @false to EnableDragColMove().
3168 void DisableDragColMove();
3171 Disables column sizing by dragging with the mouse.
3173 Equivalent to passing @false to EnableDragColSize().
3175 void DisableDragColSize();
3178 Disable mouse dragging of grid lines to resize rows and columns.
3180 Equivalent to passing @false to EnableDragGridSize()
3182 void DisableDragGridSize();
3185 Disables row sizing by dragging with the mouse.
3187 Equivalent to passing @false to EnableDragRowSize().
3189 void DisableDragRowSize();
3192 Enables or disables cell dragging with the mouse.
3194 void EnableDragCell(bool enable
= true);
3197 Enables or disables column moving by dragging with the mouse.
3199 void EnableDragColMove(bool enable
= true);
3202 Enables or disables column sizing by dragging with the mouse.
3204 @see DisableColResize()
3206 void EnableDragColSize(bool enable
= true);
3209 Enables or disables row and column resizing by dragging gridlines with
3212 void EnableDragGridSize(bool enable
= true);
3215 Enables or disables row sizing by dragging with the mouse.
3217 @see DisableRowResize()
3219 void EnableDragRowSize(bool enable
= true);
3222 Returns the column ID of the specified column position.
3224 int GetColAt(int colPos
) const;
3227 Returns the position of the specified column.
3229 int GetColPos(int colID
) const;
3232 Sets the position of the specified column.
3234 void SetColPos(int colID
, int newPos
);
3237 Sets the positions of all columns at once.
3239 This method takes an array containing the indices of the columns in
3240 their display order, i.e. uses the same convention as
3241 wxHeaderCtrl::SetColumnsOrder().
3243 void SetColumnsOrder(const wxArrayInt
& order
);
3246 Resets the position of the columns to the default.
3254 @name Cursor Movement
3259 Returns the current grid cell column position.
3261 int GetGridCursorCol() const;
3264 Returns the current grid cell row position.
3266 int GetGridCursorRow() const;
3269 Make the given cell current and ensure it is visible.
3271 This method is equivalent to calling MakeCellVisible() and
3272 SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL
3273 event is generated by it and the selected cell doesn't change if the
3276 void GoToCell(int row
, int col
);
3278 Make the given cell current and ensure it is visible.
3280 This method is equivalent to calling MakeCellVisible() and
3281 SetGridCursor() and so, as with the latter, a @c wxEVT_GRID_SELECT_CELL
3282 event is generated by it and the selected cell doesn't change if the
3285 void GoToCell(const wxGridCellCoords
& coords
);
3288 Moves the grid cursor down by one row.
3290 If a block of cells was previously selected it will expand if the
3291 argument is @true or be cleared if the argument is @false.
3293 bool MoveCursorDown(bool expandSelection
);
3296 Moves the grid cursor down in the current column such that it skips to
3297 the beginning or end of a block of non-empty cells.
3299 If a block of cells was previously selected it will expand if the
3300 argument is @true or be cleared if the argument is @false.
3302 bool MoveCursorDownBlock(bool expandSelection
);
3305 Moves the grid cursor left by one column.
3307 If a block of cells was previously selected it will expand if the
3308 argument is @true or be cleared if the argument is @false.
3310 bool MoveCursorLeft(bool expandSelection
);
3313 Moves the grid cursor left in the current row such that it skips to the
3314 beginning or end of a block of non-empty cells.
3316 If a block of cells was previously selected it will expand if the
3317 argument is @true or be cleared if the argument is @false.
3319 bool MoveCursorLeftBlock(bool expandSelection
);
3322 Moves the grid cursor right by one column.
3324 If a block of cells was previously selected it will expand if the
3325 argument is @true or be cleared if the argument is @false.
3327 bool MoveCursorRight(bool expandSelection
);
3330 Moves the grid cursor right in the current row such that it skips to
3331 the beginning or end of a block of non-empty cells.
3333 If a block of cells was previously selected it will expand if the
3334 argument is @true or be cleared if the argument is @false.
3336 bool MoveCursorRightBlock(bool expandSelection
);
3339 Moves the grid cursor up by one row.
3341 If a block of cells was previously selected it will expand if the
3342 argument is @true or be cleared if the argument is @false.
3344 bool MoveCursorUp(bool expandSelection
);
3347 Moves the grid cursor up in the current column such that it skips to
3348 the beginning or end of a block of non-empty cells.
3350 If a block of cells was previously selected it will expand if the
3351 argument is @true or be cleared if the argument is @false.
3353 bool MoveCursorUpBlock(bool expandSelection
);
3356 Moves the grid cursor down by some number of rows so that the previous
3357 bottom visible row becomes the top visible row.
3359 bool MovePageDown();
3362 Moves the grid cursor up by some number of rows so that the previous
3363 top visible row becomes the bottom visible row.
3368 Set the grid cursor to the specified cell.
3370 The grid cursor indicates the current cell and can be moved by the user
3371 using the arrow keys or the mouse.
3373 Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
3374 if the event handler vetoes this event, the cursor is not moved.
3376 This function doesn't make the target call visible, use GoToCell() to
3379 void SetGridCursor(int row
, int col
);
3381 Set the grid cursor to the specified cell.
3383 The grid cursor indicates the current cell and can be moved by the user
3384 using the arrow keys or the mouse.
3386 Calling this function generates a @c wxEVT_GRID_SELECT_CELL event and
3387 if the event handler vetoes this event, the cursor is not moved.
3389 This function doesn't make the target call visible, use GoToCell() to
3392 void SetGridCursor(const wxGridCellCoords
& coords
);
3398 @name User Selection
3403 Deselects all cells that are currently selected.
3405 void ClearSelection();
3408 Returns an array of individually selected cells.
3410 Notice that this array does @em not contain all the selected cells in
3411 general as it doesn't include the cells selected as part of column, row
3412 or block selection. You must use this method, GetSelectedCols(),
3413 GetSelectedRows() and GetSelectionBlockTopLeft() and
3414 GetSelectionBlockBottomRight() methods to obtain the entire selection
3417 Please notice this behaviour is by design and is needed in order to
3418 support grids of arbitrary size (when an entire column is selected in
3419 a grid with a million of columns, we don't want to create an array with
3420 a million of entries in this function, instead it returns an empty
3421 array and GetSelectedCols() returns an array containing one element).
3423 wxGridCellCoordsArray
GetSelectedCells() const;
3426 Returns an array of selected columns.
3428 Please notice that this method alone is not sufficient to find all the
3429 selected columns as it contains only the columns which were
3430 individually selected but not those being part of the block selection
3431 or being selected in virtue of all of their cells being selected
3432 individually, please see GetSelectedCells() for more details.
3434 wxArrayInt
GetSelectedCols() const;
3437 Returns an array of selected rows.
3439 Please notice that this method alone is not sufficient to find all the
3440 selected rows as it contains only the rows which were individually
3441 selected but not those being part of the block selection or being
3442 selected in virtue of all of their cells being selected individually,
3443 please see GetSelectedCells() for more details.
3445 wxArrayInt
GetSelectedRows() const;
3448 Returns the colour used for drawing the selection background.
3450 wxColour
GetSelectionBackground() const;
3453 Returns an array of the bottom right corners of blocks of selected
3456 Please see GetSelectedCells() for more information about the selection
3457 representation in wxGrid.
3459 @see GetSelectionBlockTopLeft()
3461 wxGridCellCoordsArray
GetSelectionBlockBottomRight() const;
3464 Returns an array of the top left corners of blocks of selected cells.
3466 Please see GetSelectedCells() for more information about the selection
3467 representation in wxGrid.
3469 @see GetSelectionBlockBottomRight()
3471 wxGridCellCoordsArray
GetSelectionBlockTopLeft() const;
3474 Returns the colour used for drawing the selection foreground.
3476 wxColour
GetSelectionForeground() const;
3479 Returns the current selection mode.
3481 @see SetSelectionMode().
3483 wxGridSelectionModes
GetSelectionMode() const;
3486 Returns @true if the given cell is selected.
3488 bool IsInSelection(int row
, int col
) const;
3490 Returns @true if the given cell is selected.
3492 bool IsInSelection(const wxGridCellCoords
& coords
) const;
3495 Returns @true if there are currently any selected cells, rows, columns
3498 bool IsSelection() const;
3501 Selects all cells in the grid.
3506 Selects a rectangular block of cells.
3508 If @a addToSelected is @false then any existing selection will be
3509 deselected; if @true the column will be added to the existing
3512 void SelectBlock(int topRow
, int leftCol
, int bottomRow
, int rightCol
,
3513 bool addToSelected
= false);
3515 Selects a rectangular block of cells.
3517 If @a addToSelected is @false then any existing selection will be
3518 deselected; if @true the column will be added to the existing
3521 void SelectBlock(const wxGridCellCoords
& topLeft
,
3522 const wxGridCellCoords
& bottomRight
,
3523 bool addToSelected
= false);
3526 Selects the specified column.
3528 If @a addToSelected is @false then any existing selection will be
3529 deselected; if @true the column will be added to the existing
3532 This method won't select anything if the current selection mode is
3535 void SelectCol(int col
, bool addToSelected
= false);
3538 Selects the specified row.
3540 If @a addToSelected is @false then any existing selection will be
3541 deselected; if @true the row will be added to the existing selection.
3543 This method won't select anything if the current selection mode is
3544 wxGridSelectColumns.
3546 void SelectRow(int row
, bool addToSelected
= false);
3549 Set the colour to be used for drawing the selection background.
3551 void SetSelectionBackground(const wxColour
& c
);
3554 Set the colour to be used for drawing the selection foreground.
3556 void SetSelectionForeground(const wxColour
& c
);
3559 Set the selection behaviour of the grid.
3561 The existing selection is converted to conform to the new mode if
3562 possible and discarded otherwise (e.g. any individual selected cells
3563 are deselected if the new mode allows only the selection of the entire
3566 void SetSelectionMode(wxGridSelectionModes selmode
);
3577 Returns the number of pixels per horizontal scroll increment.
3581 @see GetScrollLineY(), SetScrollLineX(), SetScrollLineY()
3583 int GetScrollLineX() const;
3586 Returns the number of pixels per vertical scroll increment.
3590 @see GetScrollLineX(), SetScrollLineX(), SetScrollLineY()
3592 int GetScrollLineY() const;
3595 Returns @true if a cell is either entirely or at least partially
3596 visible in the grid window.
3598 By default, the cell must be entirely visible for this function to
3599 return @true but if @a wholeCellVisible is @false, the function returns
3600 @true even if the cell is only partially visible.
3602 bool IsVisible(int row
, int col
, bool wholeCellVisible
= true) const;
3604 Returns @true if a cell is either entirely or at least partially
3605 visible in the grid window.
3607 By default, the cell must be entirely visible for this function to
3608 return @true but if @a wholeCellVisible is @false, the function returns
3609 @true even if the cell is only partially visible.
3611 bool IsVisible(const wxGridCellCoords
& coords
,
3612 bool wholeCellVisible
= true) const;
3615 Brings the specified cell into the visible grid cell area with minimal
3618 Does nothing if the cell is already visible.
3620 void MakeCellVisible(int row
, int col
);
3622 Brings the specified cell into the visible grid cell area with minimal
3625 Does nothing if the cell is already visible.
3627 void MakeCellVisible(const wxGridCellCoords
& coords
);
3630 Sets the number of pixels per horizontal scroll increment.
3634 @see GetScrollLineX(), GetScrollLineY(), SetScrollLineY()
3636 void SetScrollLineX(int x
);
3639 Sets the number of pixels per vertical scroll increment.
3643 @see GetScrollLineX(), GetScrollLineY(), SetScrollLineX()
3645 void SetScrollLineY(int y
);
3651 @name Cell and Device Coordinate Translation
3656 Convert grid cell coordinates to grid window pixel coordinates.
3658 This function returns the rectangle that encloses the block of cells
3659 limited by @a topLeft and @a bottomRight cell in device coords and
3660 clipped to the client size of the grid window.
3664 wxRect
BlockToDeviceRect(const wxGridCellCoords
& topLeft
,
3665 const wxGridCellCoords
& bottomRight
) const;
3668 Return the rectangle corresponding to the grid cell's size and position
3669 in logical coordinates.
3671 @see BlockToDeviceRect()
3673 wxRect
CellToRect(int row
, int col
) const;
3675 Return the rectangle corresponding to the grid cell's size and position
3676 in logical coordinates.
3678 @see BlockToDeviceRect()
3680 wxRect
CellToRect(const wxGridCellCoords
& coords
) const;
3683 Returns the column at the given pixel position.
3686 The x position to evaluate.
3688 If @true, rather than returning @c wxNOT_FOUND, it returns either
3689 the first or last column depending on whether @a x is too far to
3690 the left or right respectively.
3692 The column index or @c wxNOT_FOUND.
3694 int XToCol(int x
, bool clipToMinMax
= false) const;
3697 Returns the column whose right hand edge is close to the given logical
3700 If no column edge is near to this position @c wxNOT_FOUND is returned.
3702 int XToEdgeOfCol(int x
) const;
3705 Translates logical pixel coordinates to the grid cell coordinates.
3707 Notice that this function expects logical coordinates on input so if
3708 you use this function in a mouse event handler you need to translate
3709 the mouse position, which is expressed in device coordinates, to
3712 @see XToCol(), YToRow()
3714 wxGridCellCoords
XYToCell(int x
, int y
) const;
3716 Translates logical pixel coordinates to the grid cell coordinates.
3718 Notice that this function expects logical coordinates on input so if
3719 you use this function in a mouse event handler you need to translate
3720 the mouse position, which is expressed in device coordinates, to
3723 @see XToCol(), YToRow()
3725 wxGridCellCoords
XYToCell(const wxPoint
& pos
) const;
3726 // XYToCell(int, int, wxGridCellCoords&) overload is intentionally
3727 // undocumented, using it is ugly and non-const reference parameters are
3728 // not used in wxWidgets API
3731 Returns the row whose bottom edge is close to the given logical @a y
3734 If no row edge is near to this position @c wxNOT_FOUND is returned.
3736 int YToEdgeOfRow(int y
) const;
3739 Returns the grid row that corresponds to the logical @a y coordinate.
3741 Returns @c wxNOT_FOUND if there is no row at the @a y position.
3743 int YToRow(int y
, bool clipToMinMax
= false) const;
3749 @name Miscellaneous Functions
3754 Appends one or more new columns to the right of the grid.
3756 The @a updateLabels argument is not used at present. If you are using a
3757 derived grid table class you will need to override
3758 wxGridTableBase::AppendCols(). See InsertCols() for further
3761 @return @true on success or @false if appending columns failed.
3763 bool AppendCols(int numCols
= 1, bool updateLabels
= true);
3766 Appends one or more new rows to the bottom of the grid.
3768 The @a updateLabels argument is not used at present. If you are using a
3769 derived grid table class you will need to override
3770 wxGridTableBase::AppendRows(). See InsertRows() for further
3773 @return @true on success or @false if appending rows failed.
3775 bool AppendRows(int numRows
= 1, bool updateLabels
= true);
3778 Return @true if the horizontal grid lines stop at the last column
3779 boundary or @false if they continue to the end of the window.
3781 The default is to clip grid lines.
3783 @see ClipHorzGridLines(), AreVertGridLinesClipped()
3785 bool AreHorzGridLinesClipped() const;
3788 Return @true if the vertical grid lines stop at the last row
3789 boundary or @false if they continue to the end of the window.
3791 The default is to clip grid lines.
3793 @see ClipVertGridLines(), AreHorzGridLinesClipped()
3795 bool AreVertGridLinesClipped() const;
3798 Increments the grid's batch count.
3800 When the count is greater than zero repainting of the grid is
3801 suppressed. Each call to BeginBatch must be matched by a later call to
3802 EndBatch(). Code that does a lot of grid modification can be enclosed
3803 between BeginBatch() and EndBatch() calls to avoid screen flicker. The
3804 final EndBatch() call will cause the grid to be repainted.
3806 Notice that you should use wxGridUpdateLocker which ensures that there
3807 is always a matching EndBatch() call for this BeginBatch() if possible
3808 instead of calling this method directly.
3813 Clears all data in the underlying grid table and repaints the grid.
3815 The table is not deleted by this function. If you are using a derived
3816 table class then you need to override wxGridTableBase::Clear() for this
3817 function to have any effect.
3822 Change whether the horizontal grid lines are clipped by the end of the
3825 By default the grid lines are not drawn beyond the end of the last
3826 column but after calling this function with @a clip set to @false they
3827 will be drawn across the entire grid window.
3829 @see AreHorzGridLinesClipped(), ClipVertGridLines()
3831 void ClipHorzGridLines(bool clip
);
3834 Change whether the vertical grid lines are clipped by the end of the
3837 By default the grid lines are not drawn beyond the end of the last
3838 row but after calling this function with @a clip set to @false they
3839 will be drawn across the entire grid window.
3841 @see AreVertGridLinesClipped(), ClipHorzGridLines()
3843 void ClipVertGridLines(bool clip
);
3846 Deletes one or more columns from a grid starting at the specified
3849 The @a updateLabels argument is not used at present. If you are using a
3850 derived grid table class you will need to override
3851 wxGridTableBase::DeleteCols(). See InsertCols() for further
3854 @return @true on success or @false if deleting columns failed.
3856 bool DeleteCols(int pos
= 0, int numCols
= 1, bool updateLabels
= true);
3859 Deletes one or more rows from a grid starting at the specified
3862 The @a updateLabels argument is not used at present. If you are using a
3863 derived grid table class you will need to override
3864 wxGridTableBase::DeleteRows(). See InsertRows() for further
3867 @return @true on success or @false if appending rows failed.
3869 bool DeleteRows(int pos
= 0, int numRows
= 1, bool updateLabels
= true);
3872 Decrements the grid's batch count.
3874 When the count is greater than zero repainting of the grid is
3875 suppressed. Each previous call to BeginBatch() must be matched by a
3876 later call to EndBatch(). Code that does a lot of grid modification can
3877 be enclosed between BeginBatch() and EndBatch() calls to avoid screen
3878 flicker. The final EndBatch() will cause the grid to be repainted.
3880 @see wxGridUpdateLocker
3885 Overridden wxWindow method.
3890 Causes immediate repainting of the grid.
3892 Use this instead of the usual wxWindow::Refresh().
3894 void ForceRefresh();
3897 Returns the number of times that BeginBatch() has been called without
3898 (yet) matching calls to EndBatch(). While the grid's batch count is
3899 greater than zero the display will not be updated.
3901 int GetBatchCount();
3904 Returns the total number of grid columns.
3906 This is the same as the number of columns in the underlying grid table.
3908 int GetNumberCols() const;
3911 Returns the total number of grid rows.
3913 This is the same as the number of rows in the underlying grid table.
3915 int GetNumberRows() const;
3918 Returns the attribute for the given cell creating one if necessary.
3920 If the cell already has an attribute, it is returned. Otherwise a new
3921 attribute is created, associated with the cell and returned. In any
3922 case the caller must call DecRef() on the returned pointer.
3924 This function may only be called if CanHaveAttributes() returns @true.
3926 wxGridCellAttr
*GetOrCreateCellAttr(int row
, int col
) const;
3929 Returns a base pointer to the current table object.
3931 The returned pointer is still owned by the grid.
3933 wxGridTableBase
*GetTable() const;
3936 Inserts one or more new columns into a grid with the first new column
3937 at the specified position.
3939 Notice that inserting the columns in the grid requires grid table
3940 cooperation: when this method is called, grid object begins by
3941 requesting the underlying grid table to insert new columns. If this is
3942 successful the table notifies the grid and the grid updates the
3943 display. For a default grid (one where you have called CreateGrid())
3944 this process is automatic. If you are using a custom grid table
3945 (specified with SetTable()) then you must override
3946 wxGridTableBase::InsertCols() in your derived table class.
3949 The position which the first newly inserted column will have.
3951 The number of columns to insert.
3955 @true if the columns were successfully inserted, @false if an error
3956 occurred (most likely the table couldn't be updated).
3958 bool InsertCols(int pos
= 0, int numCols
= 1, bool updateLabels
= true);
3961 Inserts one or more new rows into a grid with the first new row at the
3964 Notice that you must implement wxGridTableBase::InsertRows() if you use
3965 a grid with a custom table, please see InsertCols() for more
3969 The position which the first newly inserted row will have.
3971 The number of rows to insert.
3975 @true if the rows were successfully inserted, @false if an error
3976 occurred (most likely the table couldn't be updated).
3978 bool InsertRows(int pos
= 0, int numRows
= 1, bool updateLabels
= true);
3981 Invalidates the cached attribute for the given cell.
3983 For efficiency reasons, wxGrid may cache the recently used attributes
3984 (currently it caches only the single most recently used one, in fact)
3985 which can result in the cell appearance not being refreshed even when
3986 the attribute returned by your custom wxGridCellAttrProvider-derived
3987 class has changed. To force the grid to refresh the cell attribute,
3988 this function may be used. Notice that calling it will not result in
3989 actually redrawing the cell, you still need to call
3990 wxWindow::RefreshRect() to invalidate the area occupied by the cell in
3991 the window to do this. Also note that you don't need to call this
3992 function if you store the attributes in wxGrid itself, i.e. use its
3993 SetAttr() and similar methods, it is only useful when using a separate
3994 custom attributes provider.
3997 The row of the cell whose attribute needs to be queried again.
3999 The column of the cell whose attribute needs to be queried again.
4003 void RefreshAttr(int row
, int col
);
4006 Sets the cell attributes for all cells in the specified column.
4008 For more information about controlling grid cell attributes see the
4009 wxGridCellAttr cell attribute class and the @ref overview_grid.
4011 void SetColAttr(int col
, wxGridCellAttr
* attr
);
4014 Sets the extra margins used around the grid area.
4016 A grid may occupy more space than needed for its data display and
4017 this function allows to set how big this extra space is
4019 void SetMargins(int extraWidth
, int extraHeight
);
4022 Sets the cell attributes for all cells in the specified row.
4024 The grid takes ownership of the attribute pointer.
4026 See the wxGridCellAttr class for more information about controlling
4029 void SetRowAttr(int row
, wxGridCellAttr
* attr
);
4035 @name Sorting support.
4037 wxGrid doesn't provide any support for sorting the data but it does
4038 generate events allowing the user code to sort it and supports
4039 displaying the sort indicator in the column used for sorting.
4041 To use wxGrid sorting support you need to handle wxEVT_GRID_COL_SORT
4042 event (and not veto it) and resort the data displayed in the grid. The
4043 grid will automatically update the sorting indicator on the column
4046 You can also call the functions in this section directly to update the
4047 sorting indicator. Once again, they don't do anything with the grid
4048 data, it remains your responsibility to actually sort it appropriately.
4053 Return the column in which the sorting indicator is currently
4056 Returns @c wxNOT_FOUND if sorting indicator is not currently displayed
4059 @see SetSortingColumn()
4061 int GetSortingColumn() const;
4064 Return @true if this column is currently used for sorting.
4066 @see GetSortingColumn()
4068 bool IsSortingBy(int col
) const;
4071 Return @true if the current sorting order is ascending or @false if it
4074 It only makes sense to call this function if GetSortingColumn() returns
4075 a valid column index and not @c wxNOT_FOUND.
4077 @see SetSortingColumn()
4079 bool IsSortOrderAscending() const;
4082 Set the column to display the sorting indicator in and its direction.
4085 The column to display the sorting indicator in or @c wxNOT_FOUND to
4086 remove any currently displayed sorting indicator.
4088 If @true, display the ascending sort indicator, otherwise display
4089 the descending sort indicator.
4091 @see GetSortingColumn(), IsSortOrderAscending()
4093 void SetSortingColumn(int col
, bool ascending
= true);
4096 Remove any currently shown sorting indicator.
4098 This is equivalent to calling SetSortingColumn() with @c wxNOT_FOUND
4101 void UnsetSortingColumn();
4106 @name Accessors for component windows.
4108 Return the various child windows of wxGrid.
4110 wxGrid is an empty parent window for 4 children representing the column
4111 labels window (top), the row labels window (left), the corner window
4112 (top left) and the main grid window. It may be necessary to use these
4113 individual windows and not the wxGrid window itself if you need to
4114 handle events for them (this can be done using wxEvtHandler::Connect()
4115 or wxWindow::PushEventHandler()) or do something else requiring the use
4116 of the correct window pointer. Notice that you should not, however,
4117 change these windows (e.g. reposition them or draw over them) because
4118 they are managed by wxGrid itself.
4123 Return the main grid window containing the grid cells.
4125 This window is always shown.
4127 wxWindow
*GetGridWindow() const;
4130 Return the row labels window.
4132 This window is not shown if the row labels were hidden using
4135 wxWindow
*GetGridRowLabelWindow() const;
4138 Return the column labels window.
4140 This window is not shown if the columns labels were hidden using
4143 Depending on whether UseNativeColHeader() was called or not this can be
4144 either a wxHeaderCtrl or a plain wxWindow. This function returns a valid
4145 window pointer in either case but in the former case you can also use
4146 GetGridColHeader() to access it if you need wxHeaderCtrl-specific
4149 wxWindow
*GetGridColLabelWindow() const;
4152 Return the window in the top left grid corner.
4154 This window is shown only of both columns and row labels are shown and
4155 normally doesn't contain anything. Clicking on it is handled by wxGrid
4156 however and can be used to select the entire grid.
4158 wxWindow
*GetGridCornerLabelWindow() const;
4161 Return the header control used for column labels display.
4163 This function can only be called if UseNativeColHeader() had been
4166 wxHeaderCtrl
*GetGridColHeader() const;
4172 Returns @true if this grid has support for cell attributes.
4174 The grid supports attributes if it has the associated table which, in
4175 turn, has attributes support, i.e. wxGridTableBase::CanHaveAttributes()
4178 bool CanHaveAttributes() const;
4181 Get the minimal width of the given column/row.
4183 The value returned by this function may be different than that returned
4184 by GetColMinimalAcceptableWidth() if SetColMinimalWidth() had been
4185 called for this column.
4187 int GetColMinimalWidth(int col
) const;
4190 Returns the coordinate of the right border specified column.
4192 int GetColRight(int col
) const;
4195 Returns the coordinate of the left border specified column.
4197 int GetColLeft(int col
) const;
4200 Returns the minimal size for the given column.
4202 The value returned by this function may be different than that returned
4203 by GetRowMinimalAcceptableHeight() if SetRowMinimalHeight() had been
4204 called for this row.
4206 int GetRowMinimalHeight(int col
) const;
4212 @class wxGridUpdateLocker
4214 This small class can be used to prevent wxGrid from redrawing during its
4215 lifetime by calling wxGrid::BeginBatch() in its constructor and
4216 wxGrid::EndBatch() in its destructor. It is typically used in a function
4217 performing several operations with a grid which would otherwise result in
4218 flicker. For example:
4223 m_grid = new wxGrid(this, ...);
4225 wxGridUpdateLocker noUpdates(m_grid);
4226 m_grid-AppendColumn();
4227 // ... many other operations with m_grid ...
4230 // destructor called, grid refreshed
4234 Using this class is easier and safer than calling wxGrid::BeginBatch() and
4235 wxGrid::EndBatch() because you don't risk missing the call the latter (due
4236 to an exception for example).
4241 class wxGridUpdateLocker
4245 Creates an object preventing the updates of the specified @a grid. The
4246 parameter could be @NULL in which case nothing is done. If @a grid is
4247 non-@NULL then the grid must exist for longer than this
4248 wxGridUpdateLocker object itself.
4250 The default constructor could be followed by a call to Create() to set
4251 the grid object later.
4253 wxGridUpdateLocker(wxGrid
* grid
= NULL
);
4256 Destructor reenables updates for the grid this object is associated
4259 ~wxGridUpdateLocker();
4262 This method can be called if the object had been constructed using the
4263 default constructor. It must not be called more than once.
4265 void Create(wxGrid
* grid
);
4273 This event class contains information about various grid events.
4275 Notice that all grid event table macros are available in two versions:
4276 @c EVT_GRID_XXX and @c EVT_GRID_CMD_XXX. The only difference between the
4277 two is that the former doesn't allow to specify the grid window identifier
4278 and so takes a single parameter, the event handler, but is not suitable if
4279 there is more than one grid control in the window where the event table is
4280 used (as it would catch the events from all the grids). The version with @c
4281 CMD takes the id as first argument and the event handler as the second one
4282 and so can be used with multiple grids as well. Otherwise there are no
4283 difference between the two and only the versions without the id are
4284 documented below for brevity.
4286 @beginEventTable{wxGridEvent}
4287 @event{EVT_GRID_CELL_CHANGING(func)}
4288 The user is about to change the data in a cell. The new cell value as
4289 string is available from GetString() event object method. This event
4290 can be vetoed if the change is not allowed.
4291 Processes a @c wxEVT_GRID_CELL_CHANGING event type.
4292 @event{EVT_GRID_CELL_CHANGED(func)}
4293 The user changed the data in a cell. The old cell value as string is
4294 available from GetString() event object method. Notice that vetoing
4295 this event still works for backwards compatibility reasons but any new
4296 code should only veto EVT_GRID_CELL_CHANGING event and not this one.
4297 Processes a @c wxEVT_GRID_CELL_CHANGED event type.
4298 @event{EVT_GRID_CELL_LEFT_CLICK(func)}
4299 The user clicked a cell with the left mouse button. Processes a
4300 @c wxEVT_GRID_CELL_LEFT_CLICK event type.
4301 @event{EVT_GRID_CELL_LEFT_DCLICK(func)}
4302 The user double-clicked a cell with the left mouse button. Processes a
4303 @c wxEVT_GRID_CELL_LEFT_DCLICK event type.
4304 @event{EVT_GRID_CELL_RIGHT_CLICK(func)}
4305 The user clicked a cell with the right mouse button. Processes a
4306 @c wxEVT_GRID_CELL_RIGHT_CLICK event type.
4307 @event{EVT_GRID_CELL_RIGHT_DCLICK(func)}
4308 The user double-clicked a cell with the right mouse button. Processes a
4309 @c wxEVT_GRID_CELL_RIGHT_DCLICK event type.
4310 @event{EVT_GRID_EDITOR_HIDDEN(func)}
4311 The editor for a cell was hidden. Processes a
4312 @c wxEVT_GRID_EDITOR_HIDDEN event type.
4313 @event{EVT_GRID_EDITOR_SHOWN(func)}
4314 The editor for a cell was shown. Processes a
4315 @c wxEVT_GRID_EDITOR_SHOWN event type.
4316 @event{EVT_GRID_LABEL_LEFT_CLICK(func)}
4317 The user clicked a label with the left mouse button. Processes a
4318 @c wxEVT_GRID_LABEL_LEFT_CLICK event type.
4319 @event{EVT_GRID_LABEL_LEFT_DCLICK(func)}
4320 The user double-clicked a label with the left mouse button. Processes a
4321 @c wxEVT_GRID_LABEL_LEFT_DCLICK event type.
4322 @event{EVT_GRID_LABEL_RIGHT_CLICK(func)}
4323 The user clicked a label with the right mouse button. Processes a
4324 @c wxEVT_GRID_LABEL_RIGHT_CLICK event type.
4325 @event{EVT_GRID_LABEL_RIGHT_DCLICK(func)}
4326 The user double-clicked a label with the right mouse button. Processes
4327 a @c wxEVT_GRID_LABEL_RIGHT_DCLICK event type.
4328 @event{EVT_GRID_SELECT_CELL(func)}
4329 The given cell was made current, either by user or by the program via a
4330 call to SetGridCursor() or GoToCell(). Processes a
4331 @c wxEVT_GRID_SELECT_CELL event type.
4332 @event{EVT_GRID_COL_MOVE(func)}
4333 The user tries to change the order of the columns in the grid by
4334 dragging the column specified by GetCol(). This event can be vetoed to
4335 either prevent the user from reordering the column change completely
4336 (but notice that if you don't want to allow it at all, you simply
4337 shouldn't call wxGrid::EnableDragColMove() in the first place), vetoed
4338 but handled in some way in the handler, e.g. by really moving the
4339 column to the new position at the associated table level, or allowed to
4340 proceed in which case wxGrid::SetColPos() is used to reorder the
4341 columns display order without affecting the use of the column indices
4343 This event macro corresponds to @c wxEVT_GRID_COL_MOVE event type.
4344 @event{EVT_GRID_COL_SORT(func)}
4345 This event is generated when a column is clicked by the user and its
4346 name is explained by the fact that the custom reaction to a click on a
4347 column is to sort the grid contents by this column. However the grid
4348 itself has no special support for sorting and it's up to the handler of
4349 this event to update the associated table. But if the event is handled
4350 (and not vetoed) the grid supposes that the table was indeed resorted
4351 and updates the column to indicate the new sort order and refreshes
4353 This event macro corresponds to @c wxEVT_GRID_COL_SORT event type.
4357 @category{grid,events}
4359 class wxGridEvent
: public wxNotifyEvent
4363 Default constructor.
4367 Constructor for initializing all event attributes.
4369 wxGridEvent(int id
, wxEventType type
, wxObject
* obj
,
4370 int row
= -1, int col
= -1, int x
= -1, int y
= -1,
4371 bool sel
= true, const wxKeyboardState
& kbd
= wxKeyboardState());
4374 Returns @true if the Alt key was down at the time of the event.
4376 bool AltDown() const;
4379 Returns @true if the Control key was down at the time of the event.
4381 bool ControlDown() const;
4384 Column at which the event occurred.
4386 Notice that for a @c wxEVT_GRID_SELECT_CELL event this column is the
4387 column of the newly selected cell while the previously selected cell
4388 can be retrieved using wxGrid::GetGridCursorCol().
4390 virtual int GetCol();
4393 Position in pixels at which the event occurred.
4395 wxPoint
GetPosition();
4398 Row at which the event occurred.
4400 Notice that for a @c wxEVT_GRID_SELECT_CELL event this row is the row
4401 of the newly selected cell while the previously selected cell can be
4402 retrieved using wxGrid::GetGridCursorRow().
4404 virtual int GetRow();
4407 Returns @true if the Meta key was down at the time of the event.
4409 bool MetaDown() const;
4412 Returns @true if the user is selecting grid cells, or @false if
4418 Returns @true if the Shift key was down at the time of the event.
4420 bool ShiftDown() const;
4426 @class wxGridSizeEvent
4428 This event class contains information about a row/column resize event.
4430 @beginEventTable{wxGridSizeEvent}
4431 @event{EVT_GRID_CMD_COL_SIZE(id, func)}
4432 The user resized a column, corresponds to @c wxEVT_GRID_COL_SIZE event
4434 @event{EVT_GRID_CMD_ROW_SIZE(id, func)}
4435 The user resized a row, corresponds to @c wxEVT_GRID_ROW_SIZE event
4437 @event{EVT_GRID_COL_SIZE(func)}
4438 Same as EVT_GRID_CMD_COL_SIZE() but uses `wxID_ANY` id.
4439 @event{EVT_GRID_ROW_SIZE(func)}
4440 Same as EVT_GRID_CMD_ROW_SIZE() but uses `wxID_ANY` id.
4444 @category{grid,events}
4446 class wxGridSizeEvent
: public wxNotifyEvent
4450 Default constructor.
4454 Constructor for initializing all event attributes.
4456 wxGridSizeEvent(int id
, wxEventType type
, wxObject
* obj
,
4457 int rowOrCol
= -1, int x
= -1, int y
= -1,
4458 const wxKeyboardState
& kbd
= wxKeyboardState());
4461 Returns @true if the Alt key was down at the time of the event.
4463 bool AltDown() const;
4466 Returns @true if the Control key was down at the time of the event.
4468 bool ControlDown() const;
4471 Position in pixels at which the event occurred.
4473 wxPoint
GetPosition();
4476 Row or column at that was resized.
4481 Returns @true if the Meta key was down at the time of the event.
4483 bool MetaDown() const;
4486 Returns @true if the Shift key was down at the time of the event.
4488 bool ShiftDown() const;
4494 @class wxGridRangeSelectEvent
4496 @beginEventTable{wxGridRangeSelectEvent}
4497 @event{EVT_GRID_RANGE_SELECT(func)}
4498 The user selected a group of contiguous cells. Processes a
4499 @c wxEVT_GRID_RANGE_SELECT event type.
4500 @event{EVT_GRID_CMD_RANGE_SELECT(id, func)}
4501 The user selected a group of contiguous cells; variant taking a window
4502 identifier. Processes a @c wxEVT_GRID_RANGE_SELECT event type.
4506 @category{grid,events}
4508 class wxGridRangeSelectEvent
: public wxNotifyEvent
4512 Default constructor.
4514 wxGridRangeSelectEvent();
4516 Constructor for initializing all event attributes.
4518 wxGridRangeSelectEvent(int id
, wxEventType type
,
4520 const wxGridCellCoords
& topLeft
,
4521 const wxGridCellCoords
& bottomRight
,
4522 bool sel
= true, const wxKeyboardState
& kbd
= wxKeyboardState());
4525 Returns @true if the Alt key was down at the time of the event.
4527 bool AltDown() const;
4530 Returns @true if the Control key was down at the time of the event.
4532 bool ControlDown() const;
4535 Top left corner of the rectangular area that was (de)selected.
4537 wxGridCellCoords
GetBottomRightCoords();
4540 Bottom row of the rectangular area that was (de)selected.
4545 Left column of the rectangular area that was (de)selected.
4550 Right column of the rectangular area that was (de)selected.
4555 Top left corner of the rectangular area that was (de)selected.
4557 wxGridCellCoords
GetTopLeftCoords();
4560 Top row of the rectangular area that was (de)selected.
4565 Returns @true if the Meta key was down at the time of the event.
4567 bool MetaDown() const;
4570 Returns @true if the area was selected, @false otherwise.
4575 Returns @true if the Shift key was down at the time of the event.
4577 bool ShiftDown() const;
4583 @class wxGridEditorCreatedEvent
4585 @beginEventTable{wxGridEditorCreatedEvent}
4586 @event{EVT_GRID_EDITOR_CREATED(func)}
4587 The editor for a cell was created. Processes a
4588 @c wxEVT_GRID_EDITOR_CREATED event type.
4589 @event{EVT_GRID_CMD_EDITOR_CREATED(id, func)}
4590 The editor for a cell was created; variant taking a window identifier.
4591 Processes a @c wxEVT_GRID_EDITOR_CREATED event type.
4595 @category{grid,events}
4597 class wxGridEditorCreatedEvent
: public wxCommandEvent
4601 Default constructor.
4603 wxGridEditorCreatedEvent();
4605 Constructor for initializing all event attributes.
4607 wxGridEditorCreatedEvent(int id
, wxEventType type
, wxObject
* obj
,
4608 int row
, int col
, wxControl
* ctrl
);
4611 Returns the column at which the event occurred.
4616 Returns the edit control.
4618 wxControl
* GetControl();
4621 Returns the row at which the event occurred.
4626 Sets the column at which the event occurred.
4628 void SetCol(int col
);
4631 Sets the edit control.
4633 void SetControl(wxControl
* ctrl
);
4636 Sets the row at which the event occurred.
4638 void SetRow(int row
);