// Purpose: interface of wxGrid and related classes
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
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();
};
/**
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
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);
wxGridCellFloatEditor, wxGridCellNumberEditor,
wxGridCellTextEditor
*/
-class wxGridCellEditor
+class wxGridCellEditor : public wxClientDataContainer, public wxRefCounter
{
public:
/**
its string form and possibly saved internally using its real type by
BeginEdit()). If it isn't, it just returns @false, otherwise it must do
the following:
- # Save the new value internally so that ApplyEdit() could apply it.
- # Fill @a newval (which is never @NULL) with the string
+ - Save the new value internally so that ApplyEdit() could apply it.
+ - Fill @a newval (which is never @NULL) with the string
representation of the new value.
- # Return @true
+ - Return @true
Notice that it must @em not modify the grid as the change could still
be vetoed.
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:
/**
If allowOthers is @true, the user can type a string not in choices
array.
*/
- //@{
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
+ If allowOthers is @true, the user can type a string not in choices
+ array.
+ */
wxGridCellChoiceEditor(const wxArrayString& choices,
bool allowOthers = false);
- //@}
/**
Parameters string format is "item1[,item2[...,itemN]]"
{
public:
/**
- Default constructor.
+ Text cell editor constructor.
+
+ @param maxChars
+ Maximum width of text (this parameter is supported starting since
+ wxWidgets 2.9.5).
*/
- wxGridCellTextEditor();
+ explicit wxGridCellTextEditor(size_t maxChars = 0);
/**
The parameters string format is "n" where n is a number representing
the maximum width.
*/
virtual void SetParameters(const wxString& params);
+
+ /**
+ Set validator to validate user input.
+
+ @since 2.9.5
+ */
+ virtual void SetValidator(const wxValidator& validator);
};
/**
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}
*/
-class wxGridCellAttr
+class wxGridCellAttr : public wxClientDataContainer, public wxRefCounter
{
public:
/**
Sets the text colour.
*/
void SetTextColour(const wxColour& colText);
+
+protected:
+
+ /**
+ The destructor is private because only DecRef() can delete us.
+ */
+ virtual ~wxGridCellAttr();
};
/**
wxDC& dc,
wxRect& rect) const = 0;
};
+
/**
Common base class for row and column headers renderers.
//@}
};
+/**
+ 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();
};
+
+
+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
};
+
+/**
+ Rendering styles supported by wxGrid::Render() method.
+
+ @since 2.9.4
+ */
+enum wxGridRenderStyle
+{
+ /// Draw grid row header labels.
+ wxGRID_DRAW_ROWS_HEADER = 0x001,
+
+ /// Draw grid column header labels.
+ wxGRID_DRAW_COLS_HEADER = 0x002,
+
+ /// Draw grid cell border lines.
+ wxGRID_DRAW_CELL_LINES = 0x004,
+
+ /**
+ Draw a bounding rectangle around the rendered cell area.
+
+ Useful where row or column headers are not drawn or where there is
+ multi row or column cell clipping and therefore no cell border at
+ the rendered outer boundary.
+ */
+ wxGRID_DRAW_BOX_RECT = 0x008,
+
+ /**
+ Draw the grid cell selection highlight if a selection is present.
+
+ At present the highlight colour drawn depends on whether the grid
+ window loses focus before drawing begins.
+ */
+ wxGRID_DRAW_SELECTION = 0x010,
+
+ /**
+ The default render style.
+
+ Includes all except wxGRID_DRAW_SELECTION.
+ */
+ wxGRID_DRAW_DEFAULT = wxGRID_DRAW_ROWS_HEADER |
+ wxGRID_DRAW_COLS_HEADER |
+ wxGRID_DRAW_CELL_LINES |
+ wxGRID_DRAW_BOX_RECT
+};
+
+
+
/**
@class wxGrid
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
};
/**
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);
+
//@}
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);
*/
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.
*/
*/
bool IsColShown(int col) const;
+ /**
+ Returns @true if the cells can overflow by default.
+ */
+ bool GetDefaultCellOverflow() const;
+
/**
Returns the default height for column labels.
*/
*/
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.
Hides the specified column.
To show the column later you need to call SetColSize() with non-0
- width or ShowCol().
+ width or ShowCol() to restore the previous column width.
+
+ If the column is already hidden, this method doesn't do anything.
@param col
The column index.
/**
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);
Hides the specified row.
To show the row later you need to call SetRowSize() with non-0
- width or ShowRow().
+ width or ShowRow() to restore its original height.
+
+ If the row is already hidden, this method doesn't do anything.
@param col
The row index.
void HideRow(int col);
/**
- Shows the previously hidden row by resizing it to non-0 size.
+ Shows the previously hidden row.
+
+ The row is shown again with the same height that it had before
+ HideRow() call.
+
+ If the row is currently shown, this method doesn't do anything.
@see HideRow(), SetRowSize()
*/
Notice that currently there is no way to make some columns resizable in
a grid where columns can't be resized by default as there doesn't seem
to be any need for this in practice. There is also no way to make the
- column marked as fixed using this method resizeable again because it is
+ column marked as fixed using this method resizable again because it is
supposed that fixed columns are used for static parts of the grid and
so should remain fixed during the entire grid lifetime.
*/
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);
+
//@}
*/
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.
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}
/**
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();
type.
@event{EVT_GRID_COL_SIZE(func)}
Same as EVT_GRID_CMD_COL_SIZE() but uses `wxID_ANY` id.
+ @event{EVT_GRID_COL_AUTO_SIZE(func)}
+ This event is sent when a column must be resized to its best size, e.g.
+ when the user double clicks the column divider. The default
+ implementation simply resizes the column to fit the column label (but
+ not its contents as this could be too slow for big grids). This macro
+ corresponds to @c wxEVT_GRID_COL_AUTO_SIZE event type and is new since
+ wxWidgets 2.9.5.
@event{EVT_GRID_ROW_SIZE(func)}
Same as EVT_GRID_CMD_ROW_SIZE() but uses `wxID_ANY` id.
@endEventTable
void SetRow(int row);
};
+
+wxEventType wxEVT_GRID_CELL_LEFT_CLICK;
+wxEventType wxEVT_GRID_CELL_RIGHT_CLICK;
+wxEventType wxEVT_GRID_CELL_LEFT_DCLICK;
+wxEventType wxEVT_GRID_CELL_RIGHT_DCLICK;
+wxEventType wxEVT_GRID_LABEL_LEFT_CLICK;
+wxEventType wxEVT_GRID_LABEL_RIGHT_CLICK;
+wxEventType wxEVT_GRID_LABEL_LEFT_DCLICK;
+wxEventType wxEVT_GRID_LABEL_RIGHT_DCLICK;
+wxEventType wxEVT_GRID_ROW_SIZE;
+wxEventType wxEVT_GRID_COL_SIZE;
+wxEventType wxEVT_GRID_COL_AUTO_SIZE;
+wxEventType wxEVT_GRID_RANGE_SELECT;
+wxEventType wxEVT_GRID_CELL_CHANGING;
+wxEventType wxEVT_GRID_CELL_CHANGED;
+wxEventType wxEVT_GRID_SELECT_CELL;
+wxEventType wxEVT_GRID_EDITOR_SHOWN;
+wxEventType wxEVT_GRID_EDITOR_HIDDEN;
+wxEventType wxEVT_GRID_EDITOR_CREATED;
+wxEventType wxEVT_GRID_CELL_BEGIN_DRAG;
+wxEventType wxEVT_GRID_COL_MOVE;
+wxEventType wxEVT_GRID_COL_SORT;
+wxEventType wxEVT_GRID_TABBING;
+
projects / wxWidgets.git / blobdiff