X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/caac7804114079a6ab0dcf1a6c15f9fd8340e4a0..1b7751aaa9a86d76a850b9267bc0c201e3cea30f:/interface/wx/grid.h diff --git a/interface/wx/grid.h b/interface/wx/grid.h index 057ef18b7f..2bdabe866a 100644 --- a/interface/wx/grid.h +++ b/interface/wx/grid.h @@ -3,7 +3,7 @@ // Purpose: interface of wxGrid and related classes // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -18,12 +18,16 @@ @library{wxadv} @category{grid} - @see wxGridCellBoolRenderer, wxGridCellFloatRenderer, - wxGridCellNumberRenderer, wxGridCellStringRenderer + @see wxGridCellAutoWrapStringRenderer, wxGridCellBoolRenderer, + wxGridCellDateTimeRenderer, wxGridCellEnumRenderer, + wxGridCellFloatRenderer, wxGridCellNumberRenderer, + wxGridCellStringRenderer */ -class wxGridCellRenderer +class wxGridCellRenderer : public wxClientDataContainer, public wxRefCounter { public: + wxGridCellRenderer(); + /** This function must be implemented in derived classes to return a copy of itself. @@ -48,8 +52,39 @@ public: */ virtual wxSize GetBestSize(wxGrid& grid, wxGridCellAttr& attr, wxDC& dc, int row, int col) = 0; + +protected: + /** + The destructor is private because only DecRef() can delete us. + */ + virtual ~wxGridCellRenderer(); +}; + +/** + @class wxGridCellAutoWrapStringRenderer + + This class may be used to format string data in a cell. The too + long lines are wrapped to be shown entirely at word boundaries. + + @library{wxadv} + @category{grid} + + @see wxGridCellRenderer, wxGridCellBoolRenderer, + wxGridCellDateTimeRenderer, wxGridCellEnumRenderer, + wxGridCellFloatRenderer, wxGridCellNumberRenderer, + wxGridCellStringRenderer +*/ + +class wxGridCellAutoWrapStringRenderer : public wxGridCellStringRenderer +{ +public: + /** + Default constructor. + */ + wxGridCellAutoWrapStringRenderer(); }; + /** @class wxGridCellBoolRenderer @@ -58,7 +93,9 @@ public: @library{wxadv} @category{grid} - @see wxGridCellRenderer, wxGridCellFloatRenderer, wxGridCellNumberRenderer, + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellDateTimeRenderer, wxGridCellEnumRenderer, + wxGridCellFloatRenderer, wxGridCellNumberRenderer, wxGridCellStringRenderer */ class wxGridCellBoolRenderer : public wxGridCellRenderer @@ -70,6 +107,110 @@ public: wxGridCellBoolRenderer(); }; +/** + @class wxGridCellDateTimeRenderer + + This class may be used to format a date/time data in a cell. + The class wxDateTime is used internally to display the local date/time + or to parse the string date entered in the cell thanks to the defined format. + + @library{wxadv} + @category{grid} + + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellBoolRenderer, wxGridCellEnumRenderer, + wxGridCellFloatRenderer, wxGridCellNumberRenderer, + wxGridCellStringRenderer +*/ +class wxGridCellDateTimeRenderer : public wxGridCellStringRenderer +{ +public: + /** + Date/time renderer constructor. + + @param outformat + strptime()-like format string used the parse the output date/time. + @param informat + strptime()-like format string used to parse the string entered in the cell. + */ + wxGridCellDateTimeRenderer(const wxString& outformat = wxDefaultDateTimeFormat, + const wxString& informat = wxDefaultDateTimeFormat); + + + /** + Sets the strptime()-like format string which will be used to parse + the date/time. + + @param params + strptime()-like format string used to parse the date/time. + */ + virtual void SetParameters(const wxString& params); +}; + +/** + @class wxGridCellEnumRenderer + + This class may be used to render in a cell a number as a textual + equivalent. + + The corresponding text strings are specified as comma-separated items in + the string passed to this renderer ctor or SetParameters() method. For + example, if this string is @c "John,Fred,Bob" the cell will be rendered as + "John", "Fred" or "Bob" if its contents is 0, 1 or 2 respectively. + + @library{wxadv} + @category{grid} + + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, + wxGridCellFloatRenderer, wxGridCellNumberRenderer, + wxGridCellStringRenderer +*/ +class wxGridCellEnumRenderer : public wxGridCellStringRenderer +{ +public: + /** + Enum renderer ctor. + + @param choices + Comma separated string parameters "item1[,item2[...,itemN]]". + */ + wxGridCellEnumRenderer( const wxString& choices = wxEmptyString ); + + /** + Sets the comma separated string content of the enum. + + @param params + Comma separated string parameters "item1[,item2[...,itemN]]". + */ + virtual void SetParameters(const wxString& params); +}; + +/** + Specifier used to format the data to string for the numbers handled by + wxGridCellFloatRenderer and wxGridCellFloatEditor. + + @since 2.9.3 +*/ +enum wxGridCellFloatFormat +{ + /// Decimal floating point (%f). + wxGRID_FLOAT_FORMAT_FIXED = 0x0010, + + /// Scientific notation (mantise/exponent) using e character (%e). + wxGRID_FLOAT_FORMAT_SCIENTIFIC = 0x0020, + + /// Use the shorter of %e or %f (%g). + wxGRID_FLOAT_FORMAT_COMPACT = 0x0040, + + /// To use in combination with one of the above formats for the upper + /// case version (%F/%E/%G) + wxGRID_FLOAT_FORMAT_UPPER = 0x0080, + + /// The format used by default (wxGRID_FLOAT_FORMAT_FIXED). + wxGRID_FLOAT_FORMAT_DEFAULT = wxGRID_FLOAT_FORMAT_FIXED +}; + /** @class wxGridCellFloatRenderer @@ -78,19 +219,37 @@ public: @library{wxadv} @category{grid} - @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellNumberRenderer, + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, + wxGridCellEnumRenderer, wxGridCellNumberRenderer, wxGridCellStringRenderer */ class wxGridCellFloatRenderer : public wxGridCellStringRenderer { public: /** + Float cell renderer ctor. + @param width Minimum number of characters to be shown. @param precision Number of digits after the decimal dot. + @param format + The format used to display the string, must be a combination of + ::wxGridCellFloatFormat enum elements. This parameter is only + available since wxWidgets 2.9.3. */ - wxGridCellFloatRenderer(int width = -1, int precision = -1); + wxGridCellFloatRenderer(int width = -1, int precision = -1, + int format = wxGRID_FLOAT_FORMAT_DEFAULT); + + /** + Returns the specifier used to format the data to string. + + The returned value is a combination of ::wxGridCellFloatFormat elements. + + @since 2.9.3 + */ + int GetFormat() const; /** Returns the precision. @@ -103,7 +262,18 @@ public: int GetWidth() const; /** - Parameters string format is "width[,precision]". + Set the format to use for display the number. + + @param format + Must be a combination of ::wxGridCellFloatFormat enum elements. + + @since 2.9.3 + */ + void SetFormat(int format); + + /** + The parameters string format is "width[,precision[,format]]" where + @c format should be chosen between f|e|g|E|G (f is used by default) */ virtual void SetParameters(const wxString& params); @@ -126,7 +296,9 @@ public: @library{wxadv} @category{grid} - @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellFloatRenderer, + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, + wxGridCellEnumRenderer, wxGridCellFloatRenderer, wxGridCellStringRenderer */ class wxGridCellNumberRenderer : public wxGridCellStringRenderer @@ -147,7 +319,9 @@ public: @library{wxadv} @category{grid} - @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellFloatRenderer, + @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer, + wxGridCellBoolRenderer, wxGridCellDateTimeRenderer, + wxGridCellEnumRenderer, wxGridCellFloatRenderer, wxGridCellNumberRenderer */ class wxGridCellStringRenderer : public wxGridCellRenderer @@ -160,7 +334,6 @@ public: }; - /** @class wxGridCellEditor @@ -173,10 +346,12 @@ public: @library{wxadv} @category{grid} - @see wxGridCellBoolEditor, wxGridCellChoiceEditor, wxGridCellFloatEditor, - wxGridCellNumberEditor, wxGridCellTextEditor + @see wxGridCellAutoWrapStringEditor, wxGridCellBoolEditor, + wxGridCellChoiceEditor, wxGridCellEnumEditor, + wxGridCellFloatEditor, wxGridCellNumberEditor, + wxGridCellTextEditor */ -class wxGridCellEditor +class wxGridCellEditor : public wxClientDataContainer, public wxRefCounter { public: /** @@ -186,7 +361,13 @@ public: /** Fetch the value from the table and prepare the edit control to begin - editing. Sets the focus to the edit control. + editing. + + This function should save the original value of the grid cell at the + given @a row and @a col and show the control allowing the user to + change it. + + @see EndEdit() */ virtual void BeginEdit(int row, int col, wxGrid* grid) = 0; @@ -207,12 +388,34 @@ public: virtual void Destroy(); /** - Complete the editing of the current cell. If necessary, the control may - be destroyed. + End editing the cell. + + This function must check if the current value of the editing control is + valid and different from the original value (available as @a oldval in + its string form and possibly saved internally using its real type by + BeginEdit()). If it isn't, it just returns @false, otherwise it must do + the following: + - Save the new value internally so that ApplyEdit() could apply it. + - Fill @a newval (which is never @NULL) with the string + representation of the new value. + - Return @true - @return @true if the value has changed. + Notice that it must @em not modify the grid as the change could still + be vetoed. + + If the user-defined wxEVT_GRID_CELL_CHANGING event handler doesn't veto + this change, ApplyEdit() will be called next. */ - virtual bool EndEdit(int row, int col, wxGrid* grid) = 0; + virtual bool EndEdit(int row, int col, const wxGrid* grid, + const wxString& oldval, wxString* newval) = 0; + + /** + Effectively save the changes in the grid. + + This function should save the value of the control in the grid. It is + called only after EndEdit() returns @true. + */ + virtual void ApplyEdit(int row, int col, wxGrid* grid) = 0; /** Some types of controls on some platforms may need some help with the @@ -229,7 +432,7 @@ public: Draws the part of the cell not occupied by the control: the base class version just fills it with background colour from the attribute. */ - virtual void PaintBackground(const wxRect& rectCell, wxGridCellAttr* attr); + virtual void PaintBackground(wxDC& dc, const wxRect& rectCell, wxGridCellAttr& attr); /** Reset the value in the control back to its starting value. @@ -259,6 +462,11 @@ public: */ virtual void StartingKey(wxKeyEvent& event); + /** + Returns the value currently in the editor control. + */ + virtual wxString GetValue() const = 0; + protected: /** @@ -267,6 +475,24 @@ protected: virtual ~wxGridCellEditor(); }; +/** + @class wxGridCellAutoWrapStringEditor + + Grid cell editor for wrappable string/text data. + + @library{wxadv} + @category{grid} + + @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor, + wxGridCellEnumEditor, wxGridCellFloatEditor, + wxGridCellNumberEditor, wxGridCellTextEditor +*/ +class wxGridCellAutoWrapStringEditor : public wxGridCellTextEditor +{ +public: + wxGridCellAutoWrapStringEditor(); +}; + /** @class wxGridCellBoolEditor @@ -275,8 +501,10 @@ protected: @library{wxadv} @category{grid} - @see wxGridCellEditor, wxGridCellChoiceEditor, wxGridCellFloatEditor, - wxGridCellNumberEditor, wxGridCellTextEditor + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellChoiceEditor, wxGridCellEnumEditor, + wxGridCellFloatEditor, wxGridCellNumberEditor, + wxGridCellTextEditor */ class wxGridCellBoolEditor : public wxGridCellEditor { @@ -300,7 +528,7 @@ public: an empty string otherwise. */ static void UseStringValues(const wxString& valueTrue = "1", - const wxString& valueFalse = wxEmptyString) const; + const wxString& valueFalse = wxEmptyString); }; /** @@ -312,13 +540,17 @@ public: @library{wxadv} @category{grid} - @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellFloatEditor, - wxGridCellNumberEditor, wxGridCellTextEditor + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellBoolEditor, wxGridCellEnumEditor, + wxGridCellFloatEditor, wxGridCellNumberEditor, + wxGridCellTextEditor */ class wxGridCellChoiceEditor : public wxGridCellEditor { public: /** + Choice cell renderer ctor. + @param count Number of strings from which the user can choose. @param choices @@ -330,7 +562,10 @@ public: wxGridCellChoiceEditor(size_t count = 0, const wxString choices[] = NULL, bool allowOthers = false); + /** + Choice cell renderer ctor. + @param choices An array of strings from which the user can choose. @param allowOthers @@ -346,6 +581,33 @@ public: virtual void SetParameters(const wxString& params); }; +/** + @class wxGridCellEnumEditor + + Grid cell editor which displays an enum number as a textual equivalent + (eg. data in cell is 0,1,2 ... n the cell could be displayed as + "John","Fred"..."Bob" in the combo choice box). + + @library{wxadv} + @category{grid} + + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellBoolEditor, wxGridCellChoiceEditor, + wxGridCellTextEditor, wxGridCellFloatEditor, + wxGridCellNumberEditor +*/ +class wxGridCellEnumEditor : public wxGridCellChoiceEditor +{ +public: + /** + Enum cell editor ctor. + + @param choices + Comma separated choice parameters "item1[,item2[...,itemN]]". + */ + wxGridCellEnumEditor( const wxString& choices = wxEmptyString ); +}; + /** @class wxGridCellTextEditor @@ -354,22 +616,35 @@ public: @library{wxadv} @category{grid} - @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor, - wxGridCellFloatEditor, wxGridCellNumberEditor + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellBoolEditor, wxGridCellChoiceEditor, + wxGridCellEnumEditor, wxGridCellFloatEditor, + wxGridCellNumberEditor */ class wxGridCellTextEditor : public wxGridCellEditor { public: /** - Default constructor. + Text cell editor constructor. + + @param maxChars + Maximum width of text (this parameter is supported starting since + wxWidgets 2.9.5). */ - wxGridCellTextEditor(); + explicit wxGridCellTextEditor(size_t maxChars = 0); /** The parameters string format is "n" where n is a number representing the maximum width. */ virtual void SetParameters(const wxString& params); + + /** + Set validator to validate user input. + + @since 2.9.5 + */ + virtual void SetValidator(const wxValidator& validator); }; /** @@ -380,22 +655,32 @@ public: @library{wxadv} @category{grid} - @see wxGridCellEditor, wxGridCellNumberEditor, wxGridCellBoolEditor, - wxGridCellTextEditor, wxGridCellChoiceEditor + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellBoolEditor, wxGridCellChoiceEditor, + wxGridCellEnumEditor, wxGridCellNumberEditor, + wxGridCellTextEditor */ class wxGridCellFloatEditor : public wxGridCellTextEditor { public: /** + Float cell editor ctor. + @param width Minimum number of characters to be shown. @param precision Number of digits after the decimal dot. + @param format + The format to use for displaying the number, a combination of + ::wxGridCellFloatFormat enum elements. This parameter is only + available since wxWidgets 2.9.3. */ - wxGridCellFloatEditor(int width = -1, int precision = -1); + wxGridCellFloatEditor(int width = -1, int precision = -1, + int format = wxGRID_FLOAT_FORMAT_DEFAULT); /** - Parameters string format is "width,precision" + The parameters string format is "width[,precision[,format]]" where + @c format should be chosen between f|e|g|E|G (f is used by default) */ virtual void SetParameters(const wxString& params); }; @@ -408,8 +693,10 @@ public: @library{wxadv} @category{grid} - @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor, - wxGridCellFloatEditor, wxGridCellTextEditor + @see wxGridCellEditor, wxGridCellAutoWrapStringEditor, + wxGridCellBoolEditor, wxGridCellChoiceEditor, + wxGridCellEnumEditor, wxGridCellFloatEditor, + wxGridCellTextEditor */ class wxGridCellNumberEditor : public wxGridCellTextEditor { @@ -453,13 +740,33 @@ protected: @library{wxadv} @category{grid} */ -class wxGridCellAttr +class wxGridCellAttr : public wxClientDataContainer, public wxRefCounter { public: + /** + Kind of the attribute to retrieve. + + @see wxGridCellAttrProvider::GetAttr(), wxGridTableBase::GetAttr() + */ + enum wxAttrKind + { + /// Return the combined effective attribute for the cell. + Any, + + /// Return the attribute explicitly set for this cell. + Cell, + + /// Return the attribute set for this cells row. + Row, + + /// Return the attribute set for this cells column. + Col + }; + /** Default constructor. */ - wxGridCellAttr(); + wxGridCellAttr(wxGridCellAttr* attrDefault = NULL); /** Constructor specifying some of the often used attributes. */ @@ -479,7 +786,21 @@ public: void DecRef(); /** - See SetAlignment() for the returned values. + Get the alignment to use for the cell with the given attribute. + + If this attribute doesn't specify any alignment, the default attribute + alignment is used (which can be changed using + wxGrid::SetDefaultCellAlignment() but is left and top by default). + + Notice that @a hAlign and @a vAlign values are always overwritten by + this function, use GetNonDefaultAlignment() if this is not desirable. + + @param hAlign + Horizontal alignment is returned here if this argument is non-@NULL. + It is one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT. + @param vAlign + Vertical alignment is returned here if this argument is non-@NULL. + It is one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM. */ void GetAlignment(int* hAlign, int* vAlign) const; @@ -498,6 +819,29 @@ public: */ const wxFont& GetFont() const; + /** + Get the alignment defined by this attribute. + + Unlike GetAlignment() this function only modifies @a hAlign and @a + vAlign if this attribute does define a non-default alignment. This + means that they must be initialized before calling this function and + that their values will be preserved unchanged if they are different + from wxALIGN_INVALID. + + For example, the following fragment can be used to use the cell + alignment if one is defined but right-align its contents by default + (instead of left-aligning it by default) while still using the default + vertical alignment: + @code + int hAlign = wxALIGN_RIGHT, + vAlign = wxALIGN_INVALID; + attr.GetNonDefaultAlignment(&hAlign, &vAlign); + @endcode + + @since 2.9.1 + */ + void GetNonDefaultAlignment(int *hAlign, int *vAlign) const; + /** Returns the cell renderer. */ @@ -592,9 +936,365 @@ public: Sets the text colour. */ void SetTextColour(const wxColour& colText); + +protected: + + /** + The destructor is private because only DecRef() can delete us. + */ + virtual ~wxGridCellAttr(); +}; + +/** + Base class for corner window renderer. + + This is the simplest of all header renderers and only has a single + function. + + @see wxGridCellAttrProvider::GetCornerRenderer() + + @since 2.9.1 + */ +class wxGridCornerHeaderRenderer +{ +public: + /** + Called by the grid to draw the corner window border. + + This method is responsible for drawing the border inside the given @a + rect and adjusting the rectangle size to correspond to the area inside + the border, i.e. usually call wxRect::Deflate() to account for the + border width. + + @param grid + The grid whose corner window is being drawn. + @param dc + The device context to use for drawing. + @param rect + Input/output parameter which contains the border rectangle on input + and should be updated to contain the area inside the border on + function return. + */ + virtual void DrawBorder(const wxGrid& grid, + wxDC& dc, + wxRect& rect) const = 0; +}; + +/** + Common base class for row and column headers renderers. + + @see wxGridColumnHeaderRenderer, wxGridRowHeaderRenderer + + @since 2.9.1 + */ +class wxGridHeaderLabelsRenderer : public wxGridCornerHeaderRenderer +{ +public: + /** + Called by the grid to draw the specified label. + + Notice that the base class DrawBorder() method is called before this + one. + + The default implementation uses wxGrid::GetLabelTextColour() and + wxGrid::GetLabelFont() to draw the label. + */ + virtual void DrawLabel(const wxGrid& grid, + wxDC& dc, + const wxString& value, + const wxRect& rect, + int horizAlign, + int vertAlign, + int textOrientation) const; +}; + +/** + Base class for row headers renderer. + + This is the same as wxGridHeaderLabelsRenderer currently but we still use a + separate class for it to distinguish it from wxGridColumnHeaderRenderer. + + @see wxGridRowHeaderRendererDefault + + @see wxGridCellAttrProvider::GetRowHeaderRenderer() + + @since 2.9.1 + */ +class wxGridRowHeaderRenderer : public wxGridHeaderLabelsRenderer +{ +}; + +/** + Base class for column headers renderer. + + This is the same as wxGridHeaderLabelsRenderer currently but we still use a + separate class for it to distinguish it from wxGridRowHeaderRenderer. + + @see wxGridColumnHeaderRendererDefault + + @see wxGridCellAttrProvider::GetColumnHeaderRenderer() + + @since 2.9.1 + */ +class wxGridColumnHeaderRenderer : public wxGridHeaderLabelsRenderer +{ +}; + +/** + Default row header renderer. + + You may derive from this class if you need to only override one of its + methods (i.e. either DrawLabel() or DrawBorder()) but continue to use the + default implementation for the other one. + + @see wxGridColumnHeaderRendererDefault + + @since 2.9.1 + */ +class wxGridRowHeaderRendererDefault : public wxGridRowHeaderRenderer +{ +public: + /// Implement border drawing for the row labels. + virtual void DrawBorder(const wxGrid& grid, + wxDC& dc, + wxRect& rect) const; +}; + +/** + Default column header renderer. + + @see wxGridRowHeaderRendererDefault + + @since 2.9.1 + */ +class wxGridColumnHeaderRendererDefault : public wxGridColumnHeaderRenderer +{ +public: + /// Implement border drawing for the column labels. + virtual void DrawBorder(const wxGrid& grid, + wxDC& dc, + wxRect& rect) const; }; +/** + Default corner window renderer. + + @see wxGridColumnHeaderRendererDefault, wxGridRowHeaderRendererDefault + + @since 2.9.1 + */ +class wxGridCornerHeaderRendererDefault : public wxGridCornerHeaderRenderer +{ +public: + /// Implement border drawing for the corner window. + virtual void DrawBorder(const wxGrid& grid, + wxDC& dc, + wxRect& rect) const; +}; + +/** + Class providing attributes to be used for the grid cells. + + This class both defines an interface which grid cell attributes providers + should implement -- and which can be implemented differently in derived + classes -- and a default implementation of this interface which is often + good enough to be used without modification, especially with not very large + grids for which the efficiency of attributes storage hardly matters (see + the discussion below). + + An object of this class can be associated with a wxGrid using + wxGridTableBase::SetAttrProvider() but it's not necessary to call it if you + intend to use the default provider as it is used by wxGridTableBase by + default anyhow. + + Notice that while attributes provided by this class can be set for + individual cells using SetAttr() or the entire rows or columns using + SetRowAttr() and SetColAttr() they are always retrieved using GetAttr() + function. + + + The default implementation of this class stores the attributes passed to + its SetAttr(), SetRowAttr() and SetColAttr() in a straightforward way. A + derived class may use its knowledge about how the attributes are used in + your program to implement it much more efficiently: for example, using a + special background colour for all even-numbered rows can be implemented by + simply returning the same attribute from GetAttr() if the row number is + even instead of having to store N/2 row attributes where N is the total + number of rows in the grid. + + Notice that objects of this class can't be copied. + */ +class wxGridCellAttrProvider : public wxClientDataContainer +{ +public: + /// Trivial default constructor. + wxGridCellAttrProvider(); + + /// Destructor releases any attributes held by this class. + virtual ~wxGridCellAttrProvider(); + + /** + Get the attribute to use for the specified cell. + + If wxGridCellAttr::Any is used as @a kind value, this function combines + the attributes set for this cell using SetAttr() and those for its row + or column (set with SetRowAttr() or SetColAttr() respectively), with + the cell attribute having the highest precedence. + + Notice that the caller must call DecRef() on the returned pointer if it + is non-@NULL. + + @param row + The row of the cell. + @param col + The column of the cell. + @param kind + The kind of the attribute to return. + @return + The attribute to use which should be DecRef()'d by caller or @NULL + if no attributes are defined for this cell. + */ + virtual wxGridCellAttr *GetAttr(int row, int col, + wxGridCellAttr::wxAttrKind kind) const; + + /** + Setting attributes. + + All these functions take ownership of the attribute passed to them, + i.e. will call DecRef() on it themselves later and so it should not be + destroyed by the caller. And the attribute can be @NULL to reset a + previously set value. + */ + //@{ + + /// Set attribute for the specified cell. + virtual void SetAttr(wxGridCellAttr *attr, int row, int col); + + /// Set attribute for the specified row. + virtual void SetRowAttr(wxGridCellAttr *attr, int row); + + /// Set attribute for the specified column. + virtual void SetColAttr(wxGridCellAttr *attr, int col); + + //@} + + /** + Getting header renderers. + + These functions return the renderers for the given row or column header + label and the corner window. Unlike cell attributes, these objects are + not reference counted and are never @NULL so they are returned by + reference and not pointer and DecRef() shouldn't (and can't) be called + for them. + + All these functions were added in wxWidgets 2.9.1. + */ + //@{ + + /** + Return the renderer used for drawing column headers. + + By default wxGridColumnHeaderRendererDefault is returned. + + @see wxGrid::SetUseNativeColLabels(), wxGrid::UseNativeColHeader() + + @since 2.9.1 + */ + virtual const wxGridColumnHeaderRenderer& GetColumnHeaderRenderer(int col); + + /** + Return the renderer used for drawing row headers. + By default wxGridRowHeaderRendererDefault is returned. + + @since 2.9.1 + */ + virtual const wxGridRowHeaderRenderer& GetRowHeaderRenderer(int row); + + /** + Return the renderer used for drawing the corner window. + + By default wxGridCornerHeaderRendererDefault is returned. + + @since 2.9.1 + */ + virtual const wxGridCornerHeaderRenderer& GetCornerRenderer(); + + //@} +}; + +/** + Represents coordinates of a grid cell. + + An object of this class is simply a (row, column) pair. + */ +class wxGridCellCoords +{ +public: + /** + Default constructor initializes the object to invalid state. + + Initially the row and column are both invalid (-1) and so operator!() + for an uninitialized wxGridCellCoords returns false. + */ + wxGridCellCoords(); + + /** + Constructor taking a row and a column. + */ + wxGridCellCoords(int row, int col); + + /** + Return the row of the coordinate. + */ + int GetRow() const; + + /** + Set the row of the coordinate. + */ + void SetRow(int n); + + /** + Return the column of the coordinate. + */ + int GetCol() const; + + /** + Set the column of the coordinate. + */ + void SetCol(int n); + + /** + Set the row and column of the coordinate. + */ + void Set(int row, int col); + + /** + Assignment operator for coordinate types. + */ + wxGridCellCoords& operator=(const wxGridCellCoords& other); + + /** + Equality operator. + */ + bool operator==(const wxGridCellCoords& other) const; + + /** + Inequality operator. + */ + bool operator!=(const wxGridCellCoords& other) const; + + /** + Checks whether the coordinates are invalid. + + Returns false only if both row and column are -1. Notice that if either + row or column (but not both) are -1, this method returns true even if + the object is invalid. This is done because objects in such state + should actually never exist, i.e. either both coordinates should be -1 + or none of them should be -1. + */ + bool operator!() const; +}; /** @class wxGridTableBase @@ -673,9 +1373,14 @@ public: //@{ /** - Must be overridden to implement testing for empty cells. + May be overridden to implement testing for empty cells. + + This method is used by the grid to test if the given cell is not used + and so whether a neighbouring cell may overflow into it. By default it + only returns true if the value of the given cell, as returned by + GetValue(), is empty. */ - virtual bool IsEmptyCell(int row, int col) = 0; + virtual bool IsEmptyCell(int row, int col); /** Same as IsEmptyCell() but taking wxGridCellCoords. @@ -856,6 +1561,9 @@ public: /** Delete rows from the table. + Notice that currently deleting a row intersecting a multi-cell (see + SetCellSize()) is not supported and will result in a crash. + @param pos The first row to delete. @param numRows @@ -990,16 +1698,206 @@ public: */ virtual void SetColAttr(wxGridCellAttr *attr, int col); - //@} + //@} + + /** + Returns true if this table supports attributes or false otherwise. + + By default, the table automatically creates a wxGridCellAttrProvider + when this function is called if it had no attribute provider before and + returns @true. + */ + virtual bool CanHaveAttributes(); +}; + + + +enum wxGridTableRequest +{ + wxGRIDTABLE_REQUEST_VIEW_GET_VALUES = 2000, + wxGRIDTABLE_REQUEST_VIEW_SEND_VALUES, + wxGRIDTABLE_NOTIFY_ROWS_INSERTED, + wxGRIDTABLE_NOTIFY_ROWS_APPENDED, + wxGRIDTABLE_NOTIFY_ROWS_DELETED, + wxGRIDTABLE_NOTIFY_COLS_INSERTED, + wxGRIDTABLE_NOTIFY_COLS_APPENDED, + wxGRIDTABLE_NOTIFY_COLS_DELETED +}; + + +/** + @class wxGridTableMessage + + A simple class used to pass messages from the table to the grid. + + @library{wxadv} + @category{grid} +*/ +class wxGridTableMessage +{ +public: + wxGridTableMessage(); + wxGridTableMessage( wxGridTableBase *table, int id, + int comInt1 = -1, + int comInt2 = -1 ); + + void SetTableObject( wxGridTableBase *table ); + wxGridTableBase * GetTableObject() const; + void SetId( int id ); + int GetId(); + void SetCommandInt( int comInt1 ); + int GetCommandInt(); + void SetCommandInt2( int comInt2 ); + int GetCommandInt2(); +}; + + + +/** + @class wxGridStringTable + + Simplest type of data table for a grid for small tables of strings + that are stored in memory +*/ +class wxGridStringTable : public wxGridTableBase +{ +public: + wxGridStringTable(); + wxGridStringTable( int numRows, int numCols ); + + // these are pure virtual in wxGridTableBase + virtual int GetNumberRows(); + virtual int GetNumberCols(); + virtual wxString GetValue( int row, int col ); + virtual void SetValue( int row, int col, const wxString& value ); + + // overridden functions from wxGridTableBase + void Clear(); + bool InsertRows( size_t pos = 0, size_t numRows = 1 ); + bool AppendRows( size_t numRows = 1 ); + bool DeleteRows( size_t pos = 0, size_t numRows = 1 ); + bool InsertCols( size_t pos = 0, size_t numCols = 1 ); + bool AppendCols( size_t numCols = 1 ); + bool DeleteCols( size_t pos = 0, size_t numCols = 1 ); + + void SetRowLabelValue( int row, const wxString& ); + void SetColLabelValue( int col, const wxString& ); + wxString GetRowLabelValue( int row ); + wxString GetColLabelValue( int col ); +}; + + + + + + +/** + @class wxGridSizesInfo + + wxGridSizesInfo stores information about sizes of all wxGrid rows or + columns. + + It assumes that most of the rows or columns (which are both called elements + here as the difference between them doesn't matter at this class level) + have the default size and so stores it separately. And it uses a wxHashMap + to store the sizes of all elements which have the non-default size. + + This structure is particularly useful for serializing the sizes of all + wxGrid elements at once. + + @library{wxadv} + @category{grid} + */ +struct wxGridSizesInfo +{ + /** + Default constructor. + + m_sizeDefault and m_customSizes must be initialized later. + */ + wxGridSizesInfo(); + + /** + Constructor. + + This constructor is used by wxGrid::GetRowSizes() and GetColSizes() + methods. User code will usually use the default constructor instead. + + @param defSize + The default element size. + @param allSizes + Array containing the sizes of @em all elements, including those + which have the default size. + */ + wxGridSizesInfo(int defSize, const wxArrayInt& allSizes); + + /** + Get the element size. + + @param pos + The index of the element. + @return + The size for this element, using m_customSizes if @a pos is in it + or m_sizeDefault otherwise. + */ + int GetSize(unsigned pos) const; + + + /// Default size + int m_sizeDefault; + + /** + Map with element indices as keys and their sizes as values. + + This map only contains the elements with non-default size. + */ + wxUnsignedToIntHashMap m_customSizes; +}; + + + +/** + Rendering styles supported by wxGrid::Render() method. + + @since 2.9.4 + */ +enum wxGridRenderStyle +{ + /// Draw grid row header labels. + wxGRID_DRAW_ROWS_HEADER = 0x001, + + /// Draw grid column header labels. + wxGRID_DRAW_COLS_HEADER = 0x002, + + /// Draw grid cell border lines. + wxGRID_DRAW_CELL_LINES = 0x004, + + /** + Draw a bounding rectangle around the rendered cell area. + + Useful where row or column headers are not drawn or where there is + multi row or column cell clipping and therefore no cell border at + the rendered outer boundary. + */ + wxGRID_DRAW_BOX_RECT = 0x008, + + /** + Draw the grid cell selection highlight if a selection is present. + + At present the highlight colour drawn depends on whether the grid + window loses focus before drawing begins. + */ + wxGRID_DRAW_SELECTION = 0x010, /** - Returns true if this table supports attributes or false otherwise. + The default render style. - By default, the table automatically creates a wxGridCellAttrProvider - when this function is called if it had no attribute provider before and - returns @true. + Includes all except wxGRID_DRAW_SELECTION. */ - virtual bool CanHaveAttributes(); + wxGRID_DRAW_DEFAULT = wxGRID_DRAW_ROWS_HEADER | + wxGRID_DRAW_COLS_HEADER | + wxGRID_DRAW_CELL_LINES | + wxGRID_DRAW_BOX_RECT }; @@ -1023,7 +1921,7 @@ public: The default table class is called wxGridStringTable and holds an array of strings. An instance of such a class is created by CreateGrid(). - wxGridCellRenderer is the abstract base class for rendereing contents in a + wxGridCellRenderer is the abstract base class for rendering contents in a cell. The following renderers are predefined: - wxGridCellBoolRenderer @@ -1042,7 +1940,7 @@ public: - wxGridCellFloatEditor - wxGridCellNumberEditor - wxGridCellTextEditor - + Please see wxGridEvent, wxGridSizeEvent, wxGridRangeSelectEvent, and wxGridEditorCreatedEvent for the documentation of all event types you can use with wxGrid. @@ -1079,9 +1977,61 @@ public: The user won't be able to select any cells or rows in this mode. */ - wxGridSelectColumns + wxGridSelectColumns, + + /** + The selection mode allowing the user to select either the entire + columns or the entire rows but not individual cells nor blocks. + + Notice that while this constant is defined as @code + wxGridSelectColumns | wxGridSelectRows @endcode this doesn't mean + that all the other combinations are valid -- at least currently + they are not. + + @since 2.9.1 + */ + wxGridSelectRowsOrColumns + }; + + /** + Return values for GetCellSize(). + + @since 2.9.1 + */ + enum CellSpan + { + /// This cell is inside a span covered by another cell. + CellSpan_Inside = -1, + + /// This is a normal, non-spanning cell. + CellSpan_None = 0, + + /// This cell spans several physical wxGrid cells. + CellSpan_Main }; + /** + Constants defining different support built-in TAB handling behaviours. + + The elements of this enum determine what happens when TAB is pressed + when the cursor is in the rightmost column (or Shift-TAB is pressed + when the cursor is in the leftmost one). + + @see SetTabBehaviour(), @c wxEVT_GRID_TABBING + + @since 2.9.5 + */ + enum TabBehaviour + { + /// Do nothing, this is default. + Tab_Stop, + + /// Move to the beginning of the next (or the end of the previous) row. + Tab_Wrap, + + /// Move to the next (or the previous) control after the grid. + Tab_Leave + }; /** @name Constructors and Initialization @@ -1157,6 +2107,11 @@ public: bool SetTable(wxGridTableBase* table, bool takeOwnership = false, wxGridSelectionModes selmode = wxGridSelectCells); + /** + Receive and handle a message from the table. + */ + bool ProcessTableMessage(wxGridTableMessage& msg); + //@} @@ -1371,14 +2326,49 @@ public: /** Call this in order to make the column labels use a native look by using - wxRenderer::DrawHeaderButton() internally. + wxRendererNative::DrawHeaderButton() internally. There is no equivalent method for drawing row columns as there is not native look for that. This option is useful when using wxGrid for displaying tables and not as a spread-sheet. + + @see UseNativeColHeader() */ void SetUseNativeColLabels(bool native = true); + /** + Enable the use of native header window for column labels. + + If this function is called with @true argument, a wxHeaderCtrl is used + instead to display the column labels instead of drawing them in wxGrid + code itself. This has the advantage of making the grid look and feel + perfectly the same as native applications (using SetUseNativeColLabels() + the grid can be made to look more natively but it still doesn't feel + natively, notably the column resizing and dragging still works slightly + differently as it is implemented in wxWidgets itself) but results in + different behaviour for column and row headers, for which there is no + equivalent function, and, most importantly, is unsuitable for grids + with huge numbers of columns as wxHeaderCtrl doesn't support virtual + mode. Because of this, by default the grid does not use the native + header control but you should call this function to enable it if you + are using the grid to display tabular data and don't have thousands of + columns in it. + + Another difference between the default behaviour and the native header + behaviour is that the latter provides the user with a context menu + (which appears on right clicking the header) allowing to rearrange the + grid columns if CanDragColMove() returns @true. If you want to prevent + this from happening for some reason, you need to define a handler for + @c wxEVT_GRID_LABEL_RIGHT_CLICK event which simply does nothing (in + particular doesn't skip the event) as this will prevent the default + right click handling from working. + + Also note that currently @c wxEVT_GRID_LABEL_RIGHT_DCLICK event is not + generated for the column labels if the native columns header is used + (but this limitation could possibly be lifted in the future). + */ + void UseNativeColHeader(bool native = true); + //@} @@ -1612,7 +2602,7 @@ public: See wxGridTableBase::CanGetValueAs() and the @ref overview_grid for more information. */ - const wxString GetCellValue(const wxGridCellCoords& coords) const; + wxString GetCellValue(const wxGridCellCoords& coords) const; /** Returns a pointer to the current default grid cell editor. @@ -1915,6 +2905,8 @@ public: /** @name Column and Row Sizes + + @see @ref overview_grid_resizing */ //@{ @@ -1962,6 +2954,13 @@ public: */ void AutoSizeRows(bool setAsMin = true); + /** + Returns @true if the cell value can overflow. + + A cell can overflow if the next cell in the row is empty. + */ + bool GetCellOverflow(int row, int col) const; + /** Returns the current height of the column labels. */ @@ -1982,6 +2981,16 @@ public: */ int GetColSize(int col) const; + /** + Returns @true if the specified column is not currently hidden. + */ + bool IsColShown(int col) const; + + /** + Returns @true if the cells can overflow by default. + */ + bool GetDefaultCellOverflow() const; + /** Returns the default height for column labels. */ @@ -2022,6 +3031,16 @@ public: */ int GetRowSize(int row) const; + /** + Returns @true if the specified row is not currently hidden. + */ + bool IsRowShown(int row) const; + + /** + Sets the overflow permission of the cell. + */ + void SetCellOverflow(int row, int col, bool allow); + /** Sets the height of the column labels. @@ -2053,17 +3072,45 @@ public: /** Sets the width of the specified column. - Notice that this function does not refresh the grid, you need to call - ForceRefresh() to make the changes take effect immediately. - @param col The column index. @param width - The new column width in pixels or a negative value to fit the - column width to its label width. + The new column width in pixels, 0 to hide the column or -1 to fit + the column width to its label width. */ void SetColSize(int col, int width); + /** + Hides the specified column. + + To show the column later you need to call SetColSize() with non-0 + width or ShowCol() to restore the previous column width. + + If the column is already hidden, this method doesn't do anything. + + @param col + The column index. + */ + void HideCol(int col); + + /** + Shows the previously hidden column by resizing it to non-0 size. + + The column is shown again with the same width that it had before + HideCol() call. + + If the column is currently shown, this method doesn't do anything. + + @see HideCol(), SetColSize() + */ + void ShowCol(int col); + + + /** + Sets the default overflow permission of the cells. + */ + void SetDefaultCellOverflow( bool allow ); + /** Sets the default width for columns in the grid. @@ -2082,7 +3129,7 @@ public: @a resizeExistingRows is @true. If @a height is less than GetRowMinimalAcceptableHeight(), then the - minimal acceptable heihgt is used instead of it. + minimal acceptable height is used instead of it. */ void SetDefaultRowSize(int height, bool resizeExistingRows = false); @@ -2116,11 +3163,157 @@ public: */ void SetRowSize(int row, int height); + /** + Hides the specified row. + + To show the row later you need to call SetRowSize() with non-0 + width or ShowRow() to restore its original height. + + If the row is already hidden, this method doesn't do anything. + + @param col + The row index. + */ + void HideRow(int col); + + /** + Shows the previously hidden row. + + The row is shown again with the same height that it had before + HideRow() call. + + If the row is currently shown, this method doesn't do anything. + + @see HideRow(), SetRowSize() + */ + void ShowRow(int col); + + /** + Get size information for all columns at once. + + This method is useful when the information about all column widths + needs to be saved. The widths can be later restored using + SetColSizes(). + + @sa wxGridSizesInfo, GetRowSizes() + */ + wxGridSizesInfo GetColSizes() const; + + /** + Get size information for all row at once. + + @sa wxGridSizesInfo, GetColSizes() + */ + wxGridSizesInfo GetRowSizes() const; + + /** + Restore all columns sizes. + + This is usually called with wxGridSizesInfo object previously returned + by GetColSizes(). + + @sa SetRowSizes() + */ + void SetColSizes(const wxGridSizesInfo& sizeInfo); + + /** + Restore all rows sizes. + + @sa SetColSizes() + */ + void SetRowSizes(const wxGridSizesInfo& sizeInfo); + + /** + Set the size of the cell. + + Specifying a value of more than 1 in @a num_rows or @a num_cols will + make the cell at (@a row, @a col) span the block of the specified size, + covering the other cells which would be normally shown in it. Passing 1 + for both arguments resets the cell to normal appearance. + + @see GetCellSize() + + @param row + The row of the cell. + @param col + The column of the cell. + @param num_rows + Number of rows to be occupied by this cell, must be >= 1. + @param num_cols + Number of columns to be occupied by this cell, must be >= 1. + */ + void SetCellSize(int row, int col, int num_rows, int num_cols); + + /** + Get the size of the cell in number of cells covered by it. + + For normal cells, the function fills both @a num_rows and @a num_cols + with 1 and returns CellSpan_None. For cells which span multiple cells, i.e. + for which SetCellSize() had been called, the returned values are the + same ones as were passed to SetCellSize() call and the function return + value is CellSpan_Main. + + More unexpectedly, perhaps, the returned values may be @em negative for + the cells which are inside a span covered by a cell occupying multiple + rows or columns. They correspond to the offset of the main cell of the + span from the cell passed to this functions and the function returns + CellSpan_Inside value to indicate this. + + As an example, consider a 3*3 grid with the cell (1, 1) (the one in the + middle) having a span of 2 rows and 2 columns, i.e. the grid looks like + @code + +----+----+----+ + | | | | + +----+----+----+ + | | | + +----+ | + | | | + +----+----+----+ + @endcode + Then the function returns 2 and 2 in @a num_rows and @a num_cols for + the cell (1, 1) itself and -1 and -1 for the cell (2, 2) as well as -1 + and 0 for the cell (2, 1). + + @param row + The row of the cell. + @param col + The column of the cell. + @param num_rows + Pointer to variable receiving the number of rows, must not be @NULL. + @param num_cols + Pointer to variable receiving the number of columns, must not be + @NULL. + @return + The kind of this cell span (the return value is new in wxWidgets + 2.9.1, this function was void in previous wxWidgets versions). + */ + CellSpan GetCellSize( int row, int col, int *num_rows, int *num_cols ) const; + + /** + Get the number of rows and columns allocated for this cell. + + This overload doesn't return a CellSpan value but the values returned + may still be negative, see GetCellSize(int, int, int *, int *) for + details. + */ + wxSize GetCellSize(const wxGridCellCoords& coords); + //@} /** @name User-Resizing and Dragging + + Functions controlling various interactive mouse operations. + + By default, columns and rows can be resized by dragging the edges of + their labels (this can be disabled using DisableDragColSize() and + DisableDragRowSize() methods). And if grid line dragging is enabled with + EnableDragGridSize() they can also be resized by dragging the right or + bottom edge of the grid cells. + + Columns can also be moved to interactively change their order but this + needs to be explicitly enabled with EnableDragColMove(). */ //@{ @@ -2137,13 +3330,15 @@ public: bool CanDragColMove() const; /** - Returns @true if columns can be resized by dragging with the mouse. + Returns @true if the given column can be resized by dragging with the + mouse. - Columns can be resized by dragging the edges of their labels. If grid - line dragging is enabled they can also be resized by dragging the right - edge of the column in the grid cell area (see EnableDragGridSize()). + This function returns @true if resizing the columns interactively is + globally enabled, i.e. if DisableDragColSize() hadn't been called, and + if this column wasn't explicitly marked as non-resizable with + DisableColResize(). */ - bool CanDragColSize() const; + bool CanDragColSize(int col) const; /** Return @true if the dragging of grid lines to resize rows and columns @@ -2152,13 +3347,42 @@ public: bool CanDragGridSize() const; /** - Returns @true if rows can be resized by dragging with the mouse. + Returns @true if the given row can be resized by dragging with the + mouse. - Rows can be resized by dragging the edges of their labels. If grid line - dragging is enabled they can also be resized by dragging the lower edge - of the row in the grid cell area (see EnableDragGridSize()). + This is the same as CanDragColSize() but for rows. */ - bool CanDragRowSize() const; + bool CanDragRowSize(int row) const; + + /** + Disable interactive resizing of the specified column. + + This method allows to disable resizing of an individual column in a + grid where the columns are otherwise resizable (which is the case by + default). + + Notice that currently there is no way to make some columns resizable in + a grid where columns can't be resized by default as there doesn't seem + to be any need for this in practice. There is also no way to make the + column marked as fixed using this method resizable again because it is + supposed that fixed columns are used for static parts of the grid and + so should remain fixed during the entire grid lifetime. + + Also notice that disabling interactive column resizing will not prevent + the program from changing the column size. + + @see EnableDragColSize() + */ + void DisableColResize(int col); + + /** + Disable interactive resizing of the specified row. + + This is the same as DisableColResize() but for rows. + + @see EnableDragRowSize() + */ + void DisableRowResize(int row); /** Disables column moving by dragging with the mouse. @@ -2200,6 +3424,8 @@ public: /** Enables or disables column sizing by dragging with the mouse. + + @see DisableColResize() */ void EnableDragColSize(bool enable = true); @@ -2211,6 +3437,8 @@ public: /** Enables or disables row sizing by dragging with the mouse. + + @see DisableRowResize() */ void EnableDragRowSize(bool enable = true); @@ -2229,12 +3457,26 @@ public: */ void SetColPos(int colID, int newPos); + /** + Sets the positions of all columns at once. + + This method takes an array containing the indices of the columns in + their display order, i.e. uses the same convention as + wxHeaderCtrl::SetColumnsOrder(). + */ + void SetColumnsOrder(const wxArrayInt& order); + + /** + Resets the position of the columns to the default. + */ + void ResetColPos(); + //@} /** @name Cursor Movement - */ + */ //@{ /** @@ -2373,6 +3615,25 @@ public: */ void SetGridCursor(const wxGridCellCoords& coords); + /** + Set the grid's behaviour when the user presses the TAB key. + + Pressing the TAB key moves the grid cursor right in the current row, if + there is a cell at the right and, similarly, Shift-TAB moves the cursor + to the left in the current row if it's not in the first column. + + What happens if the cursor can't be moved because it it's already at + the beginning or end of the row can be configured using this function, + see wxGrid::TabBehaviour documentation for the detailed description. + + IF none of the standard behaviours is appropriate, you can always + handle @c wxEVT_GRID_TABBING event directly to implement a custom + TAB-handling logic. + + @since 2.9.5 + */ + void SetTabBehaviour(TabBehaviour behaviour); + //@} @@ -2659,7 +3920,7 @@ public: @see BlockToDeviceRect() */ - const wxRect CellToRect(const wxGridCellCoords& coords) const; + wxRect CellToRect(const wxGridCellCoords& coords) const; /** Returns the column at the given pixel position. @@ -2959,6 +4220,64 @@ public: */ bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true); + /** + Invalidates the cached attribute for the given cell. + + For efficiency reasons, wxGrid may cache the recently used attributes + (currently it caches only the single most recently used one, in fact) + which can result in the cell appearance not being refreshed even when + the attribute returned by your custom wxGridCellAttrProvider-derived + class has changed. To force the grid to refresh the cell attribute, + this function may be used. Notice that calling it will not result in + actually redrawing the cell, you still need to call + wxWindow::RefreshRect() to invalidate the area occupied by the cell in + the window to do this. Also note that you don't need to call this + function if you store the attributes in wxGrid itself, i.e. use its + SetAttr() and similar methods, it is only useful when using a separate + custom attributes provider. + + @param row + The row of the cell whose attribute needs to be queried again. + @param col + The column of the cell whose attribute needs to be queried again. + + @since 2.9.2 + */ + void RefreshAttr(int row, int col); + + /** + Draws part or all of a wxGrid on a wxDC for printing or display. + + Pagination can be accomplished by using sequential Render() calls + with appropriate values in wxGridCellCoords topLeft and bottomRight. + + @param dc + The wxDC to be drawn on. + @param pos + The position on the wxDC where rendering should begin. If not + specified drawing will begin at the wxDC MaxX() and MaxY(). + @param size + The size of the area on the wxDC that the rendered wxGrid should + occupy. If not specified the drawing will be scaled to fit the + available dc width or height. The wxGrid's aspect ratio is + maintained whether or not size is specified. + @param topLeft + The top left cell of the block to be drawn. Defaults to ( 0, 0 ). + @param bottomRight + The bottom right cell of the block to be drawn. Defaults to row and + column counts. + @param style + A combination of values from wxGridRenderStyle. + + @since 2.9.4 + */ + void Render( wxDC& dc, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + const wxGridCellCoords& topLeft = wxGridCellCoords( -1, -1 ), + const wxGridCellCoords& bottomRight = wxGridCellCoords( -1, -1 ), + int style = wxGRID_DRAW_DEFAULT ); + /** Sets the cell attributes for all cells in the specified column. @@ -2987,6 +4306,143 @@ public: //@} + + /** + @name Sorting support. + + wxGrid doesn't provide any support for sorting the data but it does + generate events allowing the user code to sort it and supports + displaying the sort indicator in the column used for sorting. + + To use wxGrid sorting support you need to handle wxEVT_GRID_COL_SORT + event (and not veto it) and resort the data displayed in the grid. The + grid will automatically update the sorting indicator on the column + which was clicked. + + You can also call the functions in this section directly to update the + sorting indicator. Once again, they don't do anything with the grid + data, it remains your responsibility to actually sort it appropriately. + */ + //@{ + + /** + Return the column in which the sorting indicator is currently + displayed. + + Returns @c wxNOT_FOUND if sorting indicator is not currently displayed + at all. + + @see SetSortingColumn() + */ + int GetSortingColumn() const; + + /** + Return @true if this column is currently used for sorting. + + @see GetSortingColumn() + */ + bool IsSortingBy(int col) const; + + /** + Return @true if the current sorting order is ascending or @false if it + is descending. + + It only makes sense to call this function if GetSortingColumn() returns + a valid column index and not @c wxNOT_FOUND. + + @see SetSortingColumn() + */ + bool IsSortOrderAscending() const; + + /** + Set the column to display the sorting indicator in and its direction. + + @param col + The column to display the sorting indicator in or @c wxNOT_FOUND to + remove any currently displayed sorting indicator. + @param ascending + If @true, display the ascending sort indicator, otherwise display + the descending sort indicator. + + @see GetSortingColumn(), IsSortOrderAscending() + */ + void SetSortingColumn(int col, bool ascending = true); + + /** + Remove any currently shown sorting indicator. + + This is equivalent to calling SetSortingColumn() with @c wxNOT_FOUND + first argument. + */ + void UnsetSortingColumn(); + //@} + + + /** + @name Accessors for component windows. + + Return the various child windows of wxGrid. + + wxGrid is an empty parent window for 4 children representing the column + labels window (top), the row labels window (left), the corner window + (top left) and the main grid window. It may be necessary to use these + individual windows and not the wxGrid window itself if you need to + handle events for them (this can be done using wxEvtHandler::Connect() + or wxWindow::PushEventHandler()) or do something else requiring the use + of the correct window pointer. Notice that you should not, however, + change these windows (e.g. reposition them or draw over them) because + they are managed by wxGrid itself. + */ + //@{ + + /** + Return the main grid window containing the grid cells. + + This window is always shown. + */ + wxWindow *GetGridWindow() const; + + /** + Return the row labels window. + + This window is not shown if the row labels were hidden using + HideRowLabels(). + */ + wxWindow *GetGridRowLabelWindow() const; + + /** + Return the column labels window. + + This window is not shown if the columns labels were hidden using + HideColLabels(). + + Depending on whether UseNativeColHeader() was called or not this can be + either a wxHeaderCtrl or a plain wxWindow. This function returns a valid + window pointer in either case but in the former case you can also use + GetGridColHeader() to access it if you need wxHeaderCtrl-specific + functionality. + */ + wxWindow *GetGridColLabelWindow() const; + + /** + Return the window in the top left grid corner. + + This window is shown only of both columns and row labels are shown and + normally doesn't contain anything. Clicking on it is handled by wxGrid + however and can be used to select the entire grid. + */ + wxWindow *GetGridCornerLabelWindow() const; + + /** + Return the header control used for column labels display. + + This function can only be called if UseNativeColHeader() had been + called. + */ + wxHeaderCtrl *GetGridColHeader() const; + + //@} + protected: /** Returns @true if this grid has support for cell attributes. @@ -3092,10 +4548,29 @@ public: This event class contains information about various grid events. + Notice that all grid event table macros are available in two versions: + @c EVT_GRID_XXX and @c EVT_GRID_CMD_XXX. The only difference between the + two is that the former doesn't allow to specify the grid window identifier + and so takes a single parameter, the event handler, but is not suitable if + there is more than one grid control in the window where the event table is + used (as it would catch the events from all the grids). The version with @c + CMD takes the id as first argument and the event handler as the second one + and so can be used with multiple grids as well. Otherwise there are no + difference between the two and only the versions without the id are + documented below for brevity. + @beginEventTable{wxGridEvent} - @event{EVT_GRID_CELL_CHANGE(func)} - The user changed the data in a cell. Processes a - @c wxEVT_GRID_CELL_CHANGE event type. + @event{EVT_GRID_CELL_CHANGING(func)} + The user is about to change the data in a cell. The new cell value as + string is available from GetString() event object method. This event + can be vetoed if the change is not allowed. + Processes a @c wxEVT_GRID_CELL_CHANGING event type. + @event{EVT_GRID_CELL_CHANGED(func)} + The user changed the data in a cell. The old cell value as string is + available from GetString() event object method. Notice that vetoing + this event still works for backwards compatibility reasons but any new + code should only veto EVT_GRID_CELL_CHANGING event and not this one. + Processes a @c wxEVT_GRID_CELL_CHANGED event type. @event{EVT_GRID_CELL_LEFT_CLICK(func)} The user clicked a cell with the left mouse button. Processes a @c wxEVT_GRID_CELL_LEFT_CLICK event type. @@ -3127,56 +4602,41 @@ public: The user double-clicked a label with the right mouse button. Processes a @c wxEVT_GRID_LABEL_RIGHT_DCLICK event type. @event{EVT_GRID_SELECT_CELL(func)} - The user moved to, and selected a cell. Processes a + The given cell was made current, either by user or by the program via a + call to SetGridCursor() or GoToCell(). Processes a @c wxEVT_GRID_SELECT_CELL event type. - @event{EVT_GRID_CMD_CELL_CHANGE(id, func)} - The user changed the data in a cell; variant taking a window - identifier. Processes a @c wxEVT_GRID_CELL_CHANGE event type. - @event{EVT_GRID_CMD_CELL_LEFT_CLICK(id, func)} - The user clicked a cell with the left mouse button; variant taking a - window identifier. Processes a @c wxEVT_GRID_CELL_LEFT_CLICK event - type. - @event{EVT_GRID_CMD_CELL_LEFT_DCLICK(id, func)} - The user double-clicked a cell with the left mouse button; variant - taking a window identifier. Processes a @c wxEVT_GRID_CELL_LEFT_DCLICK - event type. - @event{EVT_GRID_CMD_CELL_RIGHT_CLICK(id, func)} - The user clicked a cell with the right mouse button; variant taking a - window identifier. Processes a @c wxEVT_GRID_CELL_RIGHT_CLICK event - type. - @event{EVT_GRID_CMD_CELL_RIGHT_DCLICK(id, func)} - The user double-clicked a cell with the right mouse button; variant - taking a window identifier. Processes a @c wxEVT_GRID_CELL_RIGHT_DCLICK - event type. - @event{EVT_GRID_CMD_EDITOR_HIDDEN(id, func)} - The editor for a cell was hidden; variant taking a window identifier. - Processes a @c wxEVT_GRID_EDITOR_HIDDEN event type. - @event{EVT_GRID_CMD_EDITOR_SHOWN(id, func)} - The editor for a cell was shown; variant taking a window identifier. - Processes a @c wxEVT_GRID_EDITOR_SHOWN event type. - @event{EVT_GRID_CMD_LABEL_LEFT_CLICK(id, func)} - The user clicked a label with the left mouse button; variant taking a - window identifier. Processes a @c wxEVT_GRID_LABEL_LEFT_CLICK event - type. - @event{EVT_GRID_CMD_LABEL_LEFT_DCLICK(id, func)} - The user double-clicked a label with the left mouse button; variant - taking a window identifier. Processes a @c wxEVT_GRID_LABEL_LEFT_DCLICK - event type. - @event{EVT_GRID_CMD_LABEL_RIGHT_CLICK(id, func)} - The user clicked a label with the right mouse button; variant taking a - window identifier. Processes a @c wxEVT_GRID_LABEL_RIGHT_CLICK event - type. - @event{EVT_GRID_CMD_LABEL_RIGHT_DCLICK(id, func)} - The user double-clicked a label with the right mouse button; variant - taking a window identifier. Processes a - @c wxEVT_GRID_LABEL_RIGHT_DCLICK event type. - @event{EVT_GRID_CMD_SELECT_CELL(id, func)} - The user moved to, and selected a cell; variant taking a window - identifier. Processes a @c wxEVT_GRID_SELECT_CELL event type. + @event{EVT_GRID_COL_MOVE(func)} + The user tries to change the order of the columns in the grid by + dragging the column specified by GetCol(). This event can be vetoed to + either prevent the user from reordering the column change completely + (but notice that if you don't want to allow it at all, you simply + shouldn't call wxGrid::EnableDragColMove() in the first place), vetoed + but handled in some way in the handler, e.g. by really moving the + column to the new position at the associated table level, or allowed to + proceed in which case wxGrid::SetColPos() is used to reorder the + columns display order without affecting the use of the column indices + otherwise. + This event macro corresponds to @c wxEVT_GRID_COL_MOVE event type. + @event{EVT_GRID_COL_SORT(func)} + This event is generated when a column is clicked by the user and its + name is explained by the fact that the custom reaction to a click on a + column is to sort the grid contents by this column. However the grid + itself has no special support for sorting and it's up to the handler of + this event to update the associated table. But if the event is handled + (and not vetoed) the grid supposes that the table was indeed resorted + and updates the column to indicate the new sort order and refreshes + itself. + This event macro corresponds to @c wxEVT_GRID_COL_SORT event type. + @event{EVT_GRID_TABBING(func)} + This event is generated when the user presses TAB or Shift-TAB in the + grid. It can be used to customize the simple default TAB handling + logic, e.g. to go to the next non-empty cell instead of just the next + cell. See also wxGrid::SetTabBehaviour(). This event is new since + wxWidgets 2.9.5. @endEventTable @library{wxadv} - @category{grid} + @category{grid,events} */ class wxGridEvent : public wxNotifyEvent { @@ -3190,8 +4650,7 @@ public: */ wxGridEvent(int id, wxEventType type, wxObject* obj, int row = -1, int col = -1, int x = -1, int y = -1, - bool sel = true, bool control = false, bool shift = false, - bool alt = false, bool meta = false); + bool sel = true, const wxKeyboardState& kbd = wxKeyboardState()); /** Returns @true if the Alt key was down at the time of the event. @@ -3205,6 +4664,10 @@ public: /** Column at which the event occurred. + + Notice that for a @c wxEVT_GRID_SELECT_CELL event this column is the + column of the newly selected cell while the previously selected cell + can be retrieved using wxGrid::GetGridCursorCol(). */ virtual int GetCol(); @@ -3215,6 +4678,10 @@ public: /** Row at which the event occurred. + + Notice that for a @c wxEVT_GRID_SELECT_CELL event this row is the row + of the newly selected cell while the previously selected cell can be + retrieved using wxGrid::GetGridCursorRow(). */ virtual int GetRow(); @@ -3243,22 +4710,27 @@ public: This event class contains information about a row/column resize event. @beginEventTable{wxGridSizeEvent} - @event{EVT_GRID_COL_SIZE(func)} - The user resized a column by dragging it. Processes a - @c wxEVT_GRID_COL_SIZE event type. - @event{EVT_GRID_ROW_SIZE(func)} - The user resized a row by dragging it. Processes a - @c wxEVT_GRID_ROW_SIZE event type. @event{EVT_GRID_CMD_COL_SIZE(id, func)} - The user resized a column by dragging it; variant taking a window - identifier. Processes a @c wxEVT_GRID_COL_SIZE event type. + The user resized a column, corresponds to @c wxEVT_GRID_COL_SIZE event + type. @event{EVT_GRID_CMD_ROW_SIZE(id, func)} - The user resized a row by dragging it; variant taking a window - identifier. Processes a @c wxEVT_GRID_ROW_SIZE event type. + The user resized a row, corresponds to @c wxEVT_GRID_ROW_SIZE event + type. + @event{EVT_GRID_COL_SIZE(func)} + Same as EVT_GRID_CMD_COL_SIZE() but uses `wxID_ANY` id. + @event{EVT_GRID_COL_AUTO_SIZE(func)} + This event is sent when a column must be resized to its best size, e.g. + when the user double clicks the column divider. The default + implementation simply resizes the column to fit the column label (but + not its contents as this could be too slow for big grids). This macro + corresponds to @c wxEVT_GRID_COL_AUTO_SIZE event type and is new since + wxWidgets 2.9.5. + @event{EVT_GRID_ROW_SIZE(func)} + Same as EVT_GRID_CMD_ROW_SIZE() but uses `wxID_ANY` id. @endEventTable @library{wxadv} - @category{grid} + @category{grid,events} */ class wxGridSizeEvent : public wxNotifyEvent { @@ -3272,8 +4744,7 @@ public: */ wxGridSizeEvent(int id, wxEventType type, wxObject* obj, int rowOrCol = -1, int x = -1, int y = -1, - bool control = false, bool shift = false, - bool alt = false, bool meta = false); + const wxKeyboardState& kbd = wxKeyboardState()); /** Returns @true if the Alt key was down at the time of the event. @@ -3321,7 +4792,7 @@ public: @endEventTable @library{wxadv} - @category{grid} + @category{grid,events} */ class wxGridRangeSelectEvent : public wxNotifyEvent { @@ -3337,9 +4808,7 @@ public: wxObject* obj, const wxGridCellCoords& topLeft, const wxGridCellCoords& bottomRight, - bool sel = true, bool control = false, - bool shift = false, bool alt = false, - bool meta = false); + bool sel = true, const wxKeyboardState& kbd = wxKeyboardState()); /** Returns @true if the Alt key was down at the time of the event. @@ -3412,7 +4881,7 @@ public: @endEventTable @library{wxadv} - @category{grid} + @category{grid,events} */ class wxGridEditorCreatedEvent : public wxCommandEvent { @@ -3458,3 +4927,27 @@ public: void SetRow(int row); }; + +wxEventType wxEVT_GRID_CELL_LEFT_CLICK; +wxEventType wxEVT_GRID_CELL_RIGHT_CLICK; +wxEventType wxEVT_GRID_CELL_LEFT_DCLICK; +wxEventType wxEVT_GRID_CELL_RIGHT_DCLICK; +wxEventType wxEVT_GRID_LABEL_LEFT_CLICK; +wxEventType wxEVT_GRID_LABEL_RIGHT_CLICK; +wxEventType wxEVT_GRID_LABEL_LEFT_DCLICK; +wxEventType wxEVT_GRID_LABEL_RIGHT_DCLICK; +wxEventType wxEVT_GRID_ROW_SIZE; +wxEventType wxEVT_GRID_COL_SIZE; +wxEventType wxEVT_GRID_COL_AUTO_SIZE; +wxEventType wxEVT_GRID_RANGE_SELECT; +wxEventType wxEVT_GRID_CELL_CHANGING; +wxEventType wxEVT_GRID_CELL_CHANGED; +wxEventType wxEVT_GRID_SELECT_CELL; +wxEventType wxEVT_GRID_EDITOR_SHOWN; +wxEventType wxEVT_GRID_EDITOR_HIDDEN; +wxEventType wxEVT_GRID_EDITOR_CREATED; +wxEventType wxEVT_GRID_CELL_BEGIN_DRAG; +wxEventType wxEVT_GRID_COL_MOVE; +wxEventType wxEVT_GRID_COL_SORT; +wxEventType wxEVT_GRID_TABBING; +