X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/27bb2c8cb78e39d8a4def1c349e0677fd32a2c06..1b7751aaa9a86d76a850b9267bc0c201e3cea30f:/interface/wx/grid.h?ds=sidebyside diff --git a/interface/wx/grid.h b/interface/wx/grid.h index 5fbea265ac..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, + 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 */ - wxGridCellFloatRenderer(int width = -1, int precision = -1); + 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: /** @@ -220,10 +395,10 @@ public: 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 + - 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 Notice that it must @em not modify the grid as the change could still be vetoed. @@ -257,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. @@ -287,6 +462,11 @@ public: */ virtual void StartingKey(wxKeyEvent& event); + /** + Returns the value currently in the editor control. + */ + virtual wxString GetValue() const = 0; + protected: /** @@ -295,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 @@ -303,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 { @@ -340,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 @@ -358,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 @@ -374,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 @@ -382,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); }; /** @@ -408,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); }; @@ -436,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 { @@ -481,9 +740,29 @@ 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. */ @@ -507,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; @@ -526,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. */ @@ -620,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 @@ -889,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 @@ -1035,6 +1710,87 @@ public: 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 @@ -1099,6 +1855,53 @@ struct wxGridSizesInfo }; + +/** + 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, + + /** + The default render style. + + Includes all except wxGRID_DRAW_SELECTION. + */ + wxGRID_DRAW_DEFAULT = wxGRID_DRAW_ROWS_HEADER | + wxGRID_DRAW_COLS_HEADER | + wxGRID_DRAW_CELL_LINES | + wxGRID_DRAW_BOX_RECT +}; + + + /** @class wxGrid @@ -1118,7 +1921,7 @@ struct wxGridSizesInfo 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 @@ -1174,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 @@ -1252,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); + //@} @@ -1494,10 +2354,18 @@ public: are using the grid to display tabular data and don't have thousands of columns in it. - Also note that currently @c wxEVT_GRID_LABEL_LEFT_DCLICK and - @c wxEVT_GRID_LABEL_RIGHT_DCLICK events are not generated for the column - labels if the native columns header is used (but this limitation could - possibly be lifted in the future). + 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); @@ -2086,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. */ @@ -2111,6 +2986,11 @@ public: */ bool IsColShown(int col) const; + /** + Returns @true if the cells can overflow by default. + */ + bool GetDefaultCellOverflow() const; + /** Returns the default height for column labels. */ @@ -2156,6 +3036,11 @@ public: */ 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. @@ -2199,7 +3084,9 @@ public: Hides the specified column. To show the column later you need to call SetColSize() with non-0 - width or ShowCol(). + 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. @@ -2209,11 +3096,21 @@ public: /** 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. @@ -2232,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); @@ -2270,7 +3167,9 @@ public: Hides the specified row. To show the row later you need to call SetRowSize() with non-0 - width or ShowRow(). + 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. @@ -2278,7 +3177,12 @@ public: void HideRow(int col); /** - Shows the previously hidden row by resizing it to non-0 size. + 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() */ @@ -2319,6 +3223,81 @@ public: */ 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); + //@} @@ -2385,7 +3364,7 @@ public: 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 resizeable again because it is + 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. @@ -2636,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); + //@} @@ -3222,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. @@ -3546,7 +4602,8 @@ 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_COL_MOVE(func)} The user tries to change the order of the columns in the grid by @@ -3570,6 +4627,12 @@ public: 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} @@ -3601,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(); @@ -3611,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(); @@ -3647,6 +4718,13 @@ public: 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 @@ -3849,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; +