wxGrid
wxGrid and its related classes are used for displaying and editing tabular
data. They provide a rich set of features for display, editing, and
interacting with a variety of data sources. For simple applications, and to
help you get started, wxGrid is the only class you need to refer to
directly. It will set up default instances of the other classes and manage
them for you. For more complex applications you can derive your own
classes for custom grid views, grid data tables, cell editors and
renderers. The
wxGrid classes overview has
examples of simple and more complex applications, explains the
relationship between the various grid classes and has a summary of the
keyboard shortcuts and mouse functions provided by wxGrid.
wxGrid has been greatly expanded and redesigned for wxWidgets 2.2
onwards. If you have been using the old wxGrid class you will probably
want to have a look at the
wxGrid classes overview to see
how things have changed. The new grid classes are reasonably backward-compatible
but there are some exceptions. There are also easier ways of doing many things compared to
the previous implementation.
Derived from
Include files
<wx/grid.h>
Window styles
There are presently no specific window styles for wxGrid.
Event handling
The event handler for the following functions takes a
wxGridSizeEvent parameter.
The ..._CMD_... variants also take a window identifier.
EVT_GRID_COL_SIZE(func) | The user resized a column by dragging it. Processes a wxEVT_GRID_COL_SIZE.
|
EVT_GRID_ROW_SIZE(func) | The user resized a row by dragging it. Processes a wxEVT_GRID_ROW_SIZE.
|
EVT_GRID_CMD_COL_SIZE(func) | The user resized a column by dragging it; variant taking a window identifier. Processes a wxEVT_GRID_COL_SIZE.
|
EVT_GRID_CMD_ROW_SIZE(func) | The user resized a row by dragging it; variant taking a window identifier. Processes a wxEVT_GRID_ROW_SIZE.
|
The event handler for the following functions takes a
wxGridRangeSelectEvent parameter.
The ..._CMD_... variant also takes a window identifier.
EVT_GRID_RANGE_SELECT(func) | The user selected a group of contiguous cells. Processes a wxEVT_GRID_RANGE_SELECT.
|
EVT_GRID_CMD_RANGE_SELECT(id, func) | The user selected a group of contiguous cells; variant taking a window identifier. Processes a wxEVT_GRID_RANGE_SELECT.
|
The event handler for the following functions takes a
wxGridEditorCreatedEvent parameter.
The ..._CMD_... variant also takes a window identifier.
EVT_GRID_EDITOR_CREATED(func) | The editor for a cell was created. Processes a wxEVT_GRID_EDITOR_CREATED.
|
EVT_GRID_CMD_EDITOR_CREATED(id, func) | The editor for a cell was created; variant taking a window identifier. Processes a wxEVT_GRID_EDITOR_CREATED.
|
See also
Function groups
Constructors and initialization
Display format
Selection functions
wxGrid::wxGrid
wxGrid()
Default constructor
wxGrid(
wxWindow* parent,
wxWindowID id,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxWANTS_CHARS,
const wxString& name = wxPanelNameStr)
wxGrid::~wxGrid
~wxGrid()
Destructor. This will also destroy the associated grid table unless you passed a table
object to the grid and specified that the grid should not take ownership of the
table (see
wxGrid::SetTable).
wxGrid::AppendCols
bool AppendCols(int numCols = 1, bool updateLabels = true)
Appends one or more new columns to the right of the grid and returns true if
successful. The updateLabels argument is not used at present.
wxGrid::AppendRows
bool AppendRows(int numRows = 1, bool updateLabels = true)
Appends one or more new rows to the bottom of the grid and returns true if
successful. The updateLabels argument is not used at present.
wxGrid::AutoSize
void AutoSize()
Automatically sets the height and width of all rows and columns to fit their contents.
Note
wxGrid sets up arrays to store individual row and column sizes when non-default sizes are used.
The memory requirements for this could become prohibitive if your grid is very large.
wxGrid::AutoSizeColumn
void AutoSizeColumn(int col, bool setAsMin = true)
Automatically sizes the column to fit its contents. If setAsMin is true the calculated width will
also be set as the minimal width for the column.
Note
wxGrid sets up arrays to store individual row and column sizes when non-default sizes are used.
The memory requirements for this could become prohibitive if your grid is very large.
wxGrid::AutoSizeColumns
void AutoSizeColumns(bool setAsMin = true)
Automatically sizes all columns to fit their contents. If setAsMin is true the calculated widths will
also be set as the minimal widths for the columns.
Note
wxGrid sets up arrays to store individual row and column sizes when non-default sizes are used.
The memory requirements for this could become prohibitive if your grid is very large.
wxGrid::AutoSizeRow
void AutoSizeRow(int row, bool setAsMin = true)
Automatically sizes the row to fit its contents. If setAsMin is true the calculated height will
also be set as the minimal height for the row.
Note
wxGrid sets up arrays to store individual row and column sizes when non-default sizes are used.
The memory requirements for this could become prohibitive if your grid is very large.
wxGrid::AutoSizeRows
void AutoSizeRows(bool setAsMin = true)
Automatically sizes all rows to fit their contents. If setAsMin is true the calculated heights will
also be set as the minimal heights for the rows.
Note
wxGrid sets up arrays to store individual row and column sizes when non-default sizes are used.
The memory requirements for this could become prohibitive if your grid is very large.
wxGrid::BeginBatch
void BeginBatch()
Increments the grid's batch count. When the count is greater than zero repainting of
the grid is suppressed. Each call to BeginBatch must be matched by a later call to
wxGrid::EndBatch. Code that does a lot of grid
modification can be enclosed between BeginBatch and EndBatch calls to avoid
screen flicker. The final EndBatch will cause the grid to be repainted.
wxGrid::BlockToDeviceRect
wxRect BlockToDeviceRect(
const wxGridCellCoords & topLeft,
const wxGridCellCoords & bottomRight)
This function returns the rectangle that encloses the block of cells
limited by TopLeft and BottomRight cell in device coords and clipped
to the client size of the grid window.
wxGrid::CanDragColMove
bool CanDragColMove()
Returns true if columns can be moved by dragging with the mouse. Columns can be moved
by dragging on their labels.
wxGrid::CanDragColSize
bool CanDragColSize()
Returns true if columns 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
wxGrid::EnableDragGridSize).
wxGrid::CanDragRowSize
bool CanDragRowSize()
Returns true if rows 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
wxGrid::EnableDragGridSize).
wxGrid::CanDragGridSize
bool CanDragGridSize()
Return true if the dragging of grid lines to resize rows and columns is enabled or false otherwise.
wxGrid::CanEnableCellControl
bool CanEnableCellControl() const
Returns true if the in-place edit control for the current grid cell can be used and
false otherwise (e.g. if the current cell is read-only).
wxGrid::CanHaveAttributes
bool CanHaveAttributes()
Do we have some place to store attributes in?
wxGrid::CellToRect
wxRect CellToRect(
int row,
int col)
wxRect CellToRect(
const wxGridCellCoords& coords)
Return the rectangle corresponding to the grid cell's size and position in logical
coordinates.
wxGrid::ClearGrid
void ClearGrid()
Clears all data in the underlying grid table and repaints the grid. The table is not deleted by
this function. If you are using a derived table class then you need to override
wxGridTableBase::Clear for this function to have any effect.
wxGrid::ClearSelection
void ClearSelection()
Deselects all cells that are currently selected.
wxGrid::CreateGrid
bool CreateGrid(int numRows, int numCols, wxGrid::wxGridSelectionModes selmode = wxGrid::wxGridSelectCells)
Creates a grid with the specified initial number of rows and columns.
Call this directly after the grid constructor. When you use this
function wxGrid will create and manage a simple table of string values
for you. All of the grid data will be stored in memory.
For applications with more complex data types or relationships, or for
dealing with very large datasets, you should derive your own grid table
class and pass a table object to the grid with
wxGrid::SetTable.
wxGrid::DeleteCols
bool DeleteCols(int pos = 0, int numCols = 1, bool updateLabels = true)
Deletes one or more columns from a grid starting at the specified position and returns
true if successful. The updateLabels argument is not used at present.
wxGrid::DeleteRows
bool DeleteRows(int pos = 0, int numRows = 1, bool updateLabels = true)
Deletes one or more rows from a grid starting at the specified position and returns
true if successful. The updateLabels argument is not used at present.
wxGrid::DisableCellEditControl
void DisableCellEditControl()
Disables in-place editing of grid cells.
Equivalent to calling EnableCellEditControl(false).
wxGrid::DisableDragColMove
void DisableDragColMove()
wxGrid::DisableDragColSize
void DisableDragColSize()
wxGrid::DisableDragGridSize
void DisableDragGridSize()
wxGrid::DisableDragRowSize
void DisableDragRowSize()
wxGrid::EnableCellEditControl
void EnableCellEditControl(bool enable = true)
Enables or disables in-place editing of grid cell data. The grid will issue either a
wxEVT_GRID_EDITOR_SHOWN or wxEVT_GRID_EDITOR_HIDDEN event.
wxGrid::EnableDragColSize
void EnableDragColSize(bool enable = true)
Enables or disables column sizing by dragging with the mouse.
wxGrid::EnableDragColMove
void EnableDragColMove(bool enable = true)
Enables or disables column moving by dragging with the mouse.
wxGrid::EnableDragGridSize
void EnableDragGridSize(bool enable = true)
Enables or disables row and column resizing by dragging gridlines with the mouse.
wxGrid::EnableDragRowSize
void EnableDragRowSize(bool enable = true)
Enables or disables row sizing by dragging with the mouse.
wxGrid::EnableEditing
void EnableEditing(bool edit)
If the edit argument is false this function sets the whole grid as read-only. If the
argument is true the grid is set to the default state where cells may be editable. In the
default state you can set single grid cells and whole rows and columns to be editable or
read-only via
wxGridCellAttribute::SetReadOnly. For single
cells you can also use the shortcut function
wxGrid::SetReadOnly.
wxGrid::EnableGridLines
void EnableGridLines(bool enable = true)
Turns the drawing of grid lines on or off.
wxGrid::EndBatch
void EndBatch()
Decrements the grid's batch count. When the count is greater than zero repainting of
the grid is suppressed. Each previous call to
wxGrid::BeginBatch must be matched by a later call to
EndBatch. Code that does a lot of grid modification can be enclosed between
BeginBatch and EndBatch calls to avoid screen flicker. The final EndBatch will
cause the grid to be repainted.
wxGrid::Fit
void Fit()
Overridden wxWindow method.
wxGrid::ForceRefresh
void ForceRefresh()
Causes immediate repainting of the grid. Use this instead of the usual wxWindow::Refresh.
wxGrid::GetBatchCount
int GetBatchCount()
Returns the number of times that
wxGrid::BeginBatch has been called
without (yet) matching calls to
wxGrid::EndBatch. While
the grid's batch count is greater than zero the display will not be updated.
wxGrid::GetCellAlignment
void GetCellAlignment(int row, int col, int* horiz, int* vert)
Sets the arguments to the horizontal and vertical text alignment values for the
grid cell at the specified location.
Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT.
Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM.
wxPerl note: This method only takes the parameters row and col and
returns a 2-element list ( horiz, vert ).
wxGrid::GetCellBackgroundColour
wxColour GetCellBackgroundColour(
int row,
int col)
Returns the background colour of the cell at the specified location.
wxGrid::GetCellEditor
Returns a pointer to the editor for the cell at the specified location.
wxGrid::GetCellFont
wxFont GetCellFont(
int row,
int col)
Returns the font for text in the grid cell at the specified location.
wxGrid::GetCellRenderer
Returns a pointer to the renderer for the grid cell at the specified location.
wxGrid::GetCellTextColour
wxColour GetCellTextColour(
int row,
int col)
Returns the text colour for the grid cell at the specified location.
wxGrid::GetCellValue
wxString GetCellValue(
const wxGridCellCoords& coords)
Returns the string contained in the cell at the specified location. For simple applications where a
grid object automatically uses a default grid table of string values you use this function together
with
wxGrid::SetCellValue to access cell values.
For more complex applications where you have derived your own grid table class that contains
various data types (e.g. numeric, boolean or user-defined custom types) then you only use this
function for those cells that contain string values.
wxGrid::GetColAt
int GetColAt(int colPos) const
Returns the column ID of the specified column position.
wxGrid::GetColLeft
int GetColLeft(int col) const
wxGrid::GetColLabelAlignment
void GetColLabelAlignment(int* horiz, int* vert)
Sets the arguments to the current column label alignment values.
Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT.
Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM.
wxPerl note: This method takes no parameters and
returns a 2-element list ( horiz, vert ).
wxGrid::GetColLabelSize
int GetColLabelSize()
Returns the current height of the column labels.
wxGrid::GetColLabelValue
Returns the specified column label. The default grid table class provides column labels of
the form A,B...Z,AA,AB...ZZ,AAA... If you are using a custom grid table you can override
wxGridTableBase::GetColLabelValue to provide
your own labels.
wxGrid::GetColMinimalAcceptableWidth
int GetColMinimalAcceptableWidth()
wxGrid::GetColMinimalWidth
int GetColMinimalWidth(int col) const
Get the minimal width of the given column/row.
wxGrid::GetColPos
int GetColPos(int colID) const
Returns the position of the specified column.
wxGrid::GetColRight
int GetColRight(int col) const
wxGrid::GetColSize
int GetColSize(int col)
Returns the width of the specified column.
wxGrid::GetDefaultCellAlignment
void GetDefaultCellAlignment(int* horiz, int* vert)
Sets the arguments to the current default horizontal and vertical text alignment
values.
Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE or wxALIGN_RIGHT.
Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE or wxALIGN_BOTTOM.
wxGrid::GetDefaultCellBackgroundColour
wxColour GetDefaultCellBackgroundColour()
Returns the current default background colour for grid cells.
wxGrid::GetDefaultCellFont
Returns the current default font for grid cell text.
wxGrid::GetDefaultCellTextColour
Returns the current default colour for grid cell text.
wxGrid::GetDefaultColLabelSize
int GetDefaultColLabelSize()
Returns the default height for column labels.
wxGrid::GetDefaultColSize
int GetDefaultColSize()
Returns the current default width for grid columns.
wxGrid::GetDefaultEditor
Returns a pointer to the current default grid cell editor.
wxGrid::GetDefaultEditorForCell
wxGrid::GetDefaultEditorForType
wxGrid::GetDefaultRenderer
Returns a pointer to the current default grid cell renderer.
wxGrid::GetDefaultRendererForCell
wxGrid::GetDefaultRendererForType
wxGrid::GetDefaultRowLabelSize
int GetDefaultRowLabelSize()
Returns the default width for the row labels.
wxGrid::GetDefaultRowSize
int GetDefaultRowSize()
Returns the current default height for grid rows.
wxGrid::GetGridCursorCol
int GetGridCursorCol()
Returns the current grid cell column position.
wxGrid::GetGridCursorRow
int GetGridCursorRow()
Returns the current grid cell row position.
wxGrid::GetGridLineColour
Returns the colour used for grid lines.
See also
wxGrid::GetDefaultGridLinePen
wxPen GetDefaultGridLinePen()
Returns the pen used for grid lines. This virtual function may be overridden in
derived classes in order to change the appearance of grid lines. Note that
currently the pen width must be 1.
See also
wxGrid::GetRowGridLinePen
wxPen GetRowGridLinePen(
int row)
Returns the pen used for horizontal grid lines. This virtual function may be
overridden in derived classes in order to change the appearance of individual
grid line for the given row row.
Example:
// in a grid displaying music notation, use a solid black pen between
// octaves (C0=row 127, C1=row 115 etc.)
wxPen MidiGrid::GetRowGridLinePen(int row)
{
if ( row%12 == 7 )
return wxPen(*wxBLACK, 1, wxSOLID);
else
return GetDefaultGridLinePen();
}
wxGrid::GetColGridLinePen
wxPen GetColGridLinePen(
int col)
Returns the pen used for vertical grid lines. This virtual function may be
overridden in derived classes in order to change the appearance of individual
grid lines for the given column col.
wxGrid::GridLinesEnabled
bool GridLinesEnabled()
Returns true if drawing of grid lines is turned on, false otherwise.
wxGrid::GetLabelBackgroundColour
Returns the colour used for the background of row and column labels.
wxGrid::GetLabelFont
Returns the font used for row and column labels.
wxGrid::GetLabelTextColour
Returns the colour used for row and column label text.
wxGrid::GetNumberCols
int GetNumberCols()
Returns the total number of grid columns (actually the number of columns in the underlying grid
table).
wxGrid::GetNumberRows
int GetNumberRows()
Returns the total number of grid rows (actually the number of rows in the underlying grid table).
wxGrid::GetOrCreateCellAttr
wxGrid::GetRowMinimalAcceptableHeight
int GetRowMinimalAcceptableHeight()
wxGrid::GetRowMinimalHeight
int GetRowMinimalHeight(int col) const
wxGrid::GetRowLabelAlignment
void GetRowLabelAlignment(int* horiz, int* vert)
Sets the arguments to the current row label alignment values.
Horizontal alignment will be one of wxLEFT, wxCENTRE or wxRIGHT.
Vertical alignment will be one of wxTOP, wxCENTRE or wxBOTTOM.
wxPerl note: This method takes no parameters and
returns a 2-element list ( horiz, vert ).
wxGrid::GetRowLabelSize
int GetRowLabelSize()
Returns the current width of the row labels.
wxGrid::GetRowLabelValue
Returns the specified row label. The default grid table class provides numeric row labels.
If you are using a custom grid table you can override
wxGridTableBase::GetRowLabelValue to provide
your own labels.
wxGrid::GetRowSize
int GetRowSize(int row)
Returns the height of the specified row.
wxGrid::GetScrollLineX
int GetScrollLineX() const
Returns the number of pixels per horizontal scroll increment. The default is 15.
See also
wxGrid::GetScrollLineY
int GetScrollLineY() const
Returns the number of pixels per vertical scroll increment. The default is 15.
See also
wxGrid::GetSelectionMode
wxGrid::wxGridSelectionModes GetSelectionMode() const
wxGrid::GetSelectedCells
wxGridCellCoordsArray GetSelectedCells() const
Returns an array of singly selected cells.
wxGrid::GetSelectedCols
wxArrayInt GetSelectedCols() const
Returns an array of selected cols.
wxGrid::GetSelectedRows
wxArrayInt GetSelectedRows() const
Returns an array of selected rows.
wxGrid::GetSelectionBackground
Access or update the selection fore/back colours
wxGrid::GetSelectionBlockTopLeft
wxGridCellCoordsArray GetSelectionBlockTopLeft() const
wxGrid::GetSelectionBlockBottomRight
wxGridCellCoordsArray GetSelectionBlockBottomRight() const
wxGrid::GetSelectionForeground
wxGrid::GetTable
Returns a base pointer to the current table object.
wxGrid::GetViewWidth
int GetViewWidth()
Returned number of whole cols visible.
wxGrid::HideCellEditControl
void HideCellEditControl()
Hides the in-place cell edit control.
wxGrid::InitColWidths
void InitColWidths()
Init the m_colWidths/Rights arrays
wxGrid::InitRowHeights
void InitRowHeights()
NB: never access m_row/col arrays directly because they are created
on demand, always use accessor functions instead!
Init the m_rowHeights/Bottoms arrays with default values.
wxGrid::InsertCols
bool InsertCols(int pos = 0, int numCols = 1, bool updateLabels = true)
Inserts one or more new columns into a grid with the first new column at the
specified position and returns true if successful. The updateLabels argument is not
used at present.
The sequence of actions begins with the grid object requesting the underlying grid
table to insert new columns. If this is successful the table notifies the grid and the
grid updates the display. For a default grid (one where you have called
wxGrid::CreateGrid) this process is automatic. If you are
using a custom grid table (specified with
wxGrid::SetTable)
then you must override
wxGridTableBase::InsertCols in your derived
table class.
wxGrid::InsertRows
bool InsertRows(int pos = 0, int numRows = 1, bool updateLabels = true)
Inserts one or more new rows into a grid with the first new row at the specified
position and returns true if successful. The updateLabels argument is not used at
present.
The sequence of actions begins with the grid object requesting the underlying grid
table to insert new rows. If this is successful the table notifies the grid and the
grid updates the display. For a default grid (one where you have called
wxGrid::CreateGrid) this process is automatic. If you are
using a custom grid table (specified with
wxGrid::SetTable)
then you must override
wxGridTableBase::InsertRows in your derived
table class.
wxGrid::IsCellEditControlEnabled
bool IsCellEditControlEnabled() const
Returns true if the in-place edit control is currently enabled.
wxGrid::IsCurrentCellReadOnly
bool IsCurrentCellReadOnly() const
wxGrid::IsEditable
bool IsEditable()
Returns false if the whole grid has been set as read-only or true otherwise.
See
wxGrid::EnableEditing for more information about
controlling the editing status of grid cells.
wxGrid::IsInSelection
bool IsInSelection(int row, int col) const
bool IsInSelection(const wxGridCellCoords& coords) const
Is this cell currently selected.
wxGrid::IsReadOnly
bool IsReadOnly(int row, int col) const
Returns true if the cell at the specified location can't be edited.
See also
wxGrid::IsReadOnly.
wxGrid::IsSelection
bool IsSelection()
Returns true if there are currently rows, columns or blocks of cells selected.
wxGrid::IsVisible
bool IsVisible(int row, int col, bool wholeCellVisible = true)
bool IsVisible(const wxGridCellCoords& coords, bool wholeCellVisible = true)
Returns true if a cell is either wholly visible (the default) or at least partially
visible in the grid window.
wxGrid::MakeCellVisible
void MakeCellVisible(int row, int col)
void MakeCellVisible(const wxGridCellCoords& coords)
Brings the specified cell into the visible grid cell area with minimal scrolling. Does
nothing if the cell is already visible.
wxGrid::MoveCursorDown
bool MoveCursorDown(bool expandSelection)
Moves the grid cursor down by one row. If a block of cells was previously selected it
will expand if the argument is true or be cleared if the argument is false.
Keyboard
This function is called for Down cursor key presses or Shift+Down to expand a selection.
wxGrid::MoveCursorLeft
bool MoveCursorLeft(bool expandSelection)
Moves the grid cursor left by one column. If a block of cells was previously selected it
will expand if the argument is true or be cleared if the argument is false.
Keyboard
This function is called for Left cursor key presses or Shift+Left to expand a selection.
wxGrid::MoveCursorRight
bool MoveCursorRight(