// 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
{
int row, int col) = 0;
};
+/**
+ @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);
+ wxGridCellFloatRenderer(int width = -1, int precision = -1,
+ int format = wxGRID_FLOAT_FORMAT_DEFAULT);
+
+ /**
+ Returns the specifier used to format the data to string.
+
+ The returned value is a combination of ::wxGridCellFloatFormat elements.
+
+ @since 2.9.3
+ */
+ int GetFormat() const;
/**
Returns the precision.
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
{
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 fills
- @a newval with the representation of the new value in the string form,
- if necessary saves it using its real type internally, and returns @true.
+ 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(const wxString& oldval, wxString* newval) = 0;
+ virtual bool EndEdit(int row, int col, const wxGrid* grid,
+ const wxString& oldval, wxString* newval) = 0;
/**
Effectively save the changes in the grid.
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
{
@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
{
class wxGridCellAttr
{
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.
*/
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.
*/
void SetTextColour(const wxColour& colText);
};
+/**
+ 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
virtual bool CanHaveAttributes();
};
+/**
+ @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;
+};
/**
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
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
};
+ /**
+ 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
+ };
/**
@name Constructors and Initialization
/**
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);
/**
@name Column and Row Sizes
+
+ @see @ref overview_grid_resizing
*/
//@{
@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 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);
*/
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.
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
/**
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}
projects / wxWidgets.git / blobdiff