// Purpose: interface of wxGrid and related classes
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@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.
*/
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
@library{wxadv}
@category{grid}
- @see wxGridCellRenderer, wxGridCellFloatRenderer, wxGridCellNumberRenderer,
+ @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
+ wxGridCellDateTimeRenderer, wxGridCellEnumRenderer,
+ wxGridCellFloatRenderer, wxGridCellNumberRenderer,
wxGridCellStringRenderer
*/
class wxGridCellBoolRenderer : public wxGridCellRenderer
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
@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.
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);
@library{wxadv}
@category{grid}
- @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellFloatRenderer,
+ @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
+ wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
+ wxGridCellEnumRenderer, wxGridCellFloatRenderer,
wxGridCellStringRenderer
*/
class wxGridCellNumberRenderer : public wxGridCellStringRenderer
@library{wxadv}
@category{grid}
- @see wxGridCellRenderer, wxGridCellBoolRenderer, wxGridCellFloatRenderer,
+ @see wxGridCellRenderer, wxGridCellAutoWrapStringRenderer,
+ wxGridCellBoolRenderer, wxGridCellDateTimeRenderer,
+ wxGridCellEnumRenderer, wxGridCellFloatRenderer,
wxGridCellNumberRenderer
*/
class wxGridCellStringRenderer : public wxGridCellRenderer
};
-
/**
@class wxGridCellEditor
@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:
/**
/**
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;
virtual void Destroy();
/**
- Complete the editing of the current cell. If necessary, the control may
- be destroyed.
+ End editing the cell.
- @return @true if the value has changed.
+ 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
+
+ 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
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.
*/
virtual void StartingKey(wxKeyEvent& event);
+ /**
+ Returns the value currently in the editor control.
+ */
+ virtual wxString GetValue() const = 0;
+
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
@library{wxadv}
@category{grid}
- @see wxGridCellEditor, wxGridCellChoiceEditor, wxGridCellFloatEditor,
- wxGridCellNumberEditor, wxGridCellTextEditor
+ @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
+ wxGridCellChoiceEditor, wxGridCellEnumEditor,
+ wxGridCellFloatEditor, wxGridCellNumberEditor,
+ wxGridCellTextEditor
*/
class wxGridCellBoolEditor : public wxGridCellEditor
{
an empty string otherwise.
*/
static void UseStringValues(const wxString& valueTrue = "1",
- const wxString& valueFalse = wxEmptyString) const;
+ const wxString& valueFalse = wxEmptyString);
};
/**
@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
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
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
@library{wxadv}
@category{grid}
- @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor,
- wxGridCellFloatEditor, wxGridCellNumberEditor
+ @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
+ wxGridCellBoolEditor, wxGridCellChoiceEditor,
+ wxGridCellEnumEditor, wxGridCellFloatEditor,
+ wxGridCellNumberEditor
*/
class wxGridCellTextEditor : public wxGridCellEditor
{
@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);
};
@library{wxadv}
@category{grid}
- @see wxGridCellEditor, wxGridCellBoolEditor, wxGridCellChoiceEditor,
- wxGridCellFloatEditor, wxGridCellTextEditor
+ @see wxGridCellEditor, wxGridCellAutoWrapStringEditor,
+ wxGridCellBoolEditor, wxGridCellChoiceEditor,
+ wxGridCellEnumEditor, wxGridCellFloatEditor,
+ wxGridCellTextEditor
*/
class wxGridCellNumberEditor : public wxGridCellTextEditor
{
@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.
*/
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;
*/
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.
*/
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
/**
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
By default this function is simply forwarded to
wxGridCellAttrProvider::SetColAttr().
- The table takes ownership of @a attr, i.e. will call DecRef() on it.
- */
- virtual void SetColAttr(wxGridCellAttr *attr, int col);
+ The table takes ownership of @a attr, i.e. will call DecRef() on it.
+ */
+ 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
};
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
- wxGridCellFloatEditor
- wxGridCellNumberEditor
- wxGridCellTextEditor
-
+
Please see wxGridEvent, wxGridSizeEvent, wxGridRangeSelectEvent, and
wxGridEditorCreatedEvent for the documentation of all event types you can
use with wxGrid.
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
bool SetTable(wxGridTableBase* table, bool takeOwnership = false,
wxGridSelectionModes selmode = wxGridSelectCells);
+ /**
+ Receive and handle a message from the table.
+ */
+ bool ProcessTableMessage(wxGridTableMessage& msg);
+
//@}
/**
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 UseNativeHeader()
+ @see UseNativeColHeader()
*/
void SetUseNativeColLabels(bool native = true);
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);
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.
/**
@name Column and Row Sizes
+
+ @see @ref overview_grid_resizing
*/
//@{
*/
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.
*/
*/
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.
*/
*/
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.
/**
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.
@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);
*/
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().
*/
//@{
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
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.
/**
Enables or disables column sizing by dragging with the mouse.
+
+ @see DisableColResize()
*/
void EnableDragColSize(bool enable = true);
/**
Enables or disables row sizing by dragging with the mouse.
+
+ @see DisableRowResize()
*/
void EnableDragRowSize(bool enable = true);
*/
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
- */
+ */
//@{
/**
*/
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);
+
//@}
@see BlockToDeviceRect()
*/
- const wxRect CellToRect(const wxGridCellCoords& coords) const;
+ wxRect CellToRect(const wxGridCellCoords& coords) const;
/**
Returns the column at the given pixel position.
*/
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.
//@}
+
+ /**
+ @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.
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.
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
{
*/
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.
/**
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();
/**
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();
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_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
{
*/
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.
@endEventTable
@library{wxadv}
- @category{grid}
+ @category{grid,events}
*/
class wxGridRangeSelectEvent : public wxNotifyEvent
{
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.
@endEventTable
@library{wxadv}
- @category{grid}
+ @category{grid,events}
*/
class wxGridEditorCreatedEvent : public wxCommandEvent
{
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_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;
+
projects / wxWidgets.git / blobdiff