wxGrid

wxGrid is a versatile and somewhat complex class for presenting information in a tabular form. You could make a property sheet out of a grid with name and value columns, create a general-purpose spreadsheet by adding your own formula evaluation code, show a table from a database, or display statistical data generated by your application. In some situations, you might consider wxGrid as an alternative to wxListCtrl in report mode, particularly if you need to display images or arbitrary graphics in cells.

A grid can display optional row and column headers, drawn in a similar way to the headers in a spreadsheet application. The user can drag column and row dividers, select one or more cells, and click a cell to edit it. Each cell in a grid has its own attributes for font, color, and alignment and also may have its own specialized renderer (for drawing the data) and editor (for editing the data). You can write your own renderers and editors: see include/wx/generic/ grid.h and src/generic/grid.cpp in your wxWidgets distribution for guidance. By default, a grid cell will use a simple string renderer and editor. If you have complex requirements for cell formatting, then rather than set attributes for each cell, you can create an "attribute provider" class that dynamically returns attributes for each cell when needed.

You can also create a potentially enormous "virtual" grid where storage is provided by the application, not by wxGrid. To do this, you derive a class from wxGridTableBase and override functions including GetValue, GetNumberRows, and GetNumberCols. These functions will reflect data stored in your application or perhaps in a database. Then plug the table into a grid using SetTable, and the grid will use your data. These more advanced techniques are demonstrated in samples/grid in your wxWidgets distribution, as shown in Figure 12-7.

Figure 12-7. wxGrid

Listing 12-3 shows an example of creating a simple grid with eight rows and ten columns.

Listing 12-3. Simple Use of wxGrid

 #include "wx/grid.h" // Create a wxGrid object wxGrid* grid = new wxGrid(frame, wxID_ANY,                           wxDefaultPosition, wxSize(400, 300)); // Then we call CreateGrid to set the dimensions of the grid // (8 rows and 10 columns in this example) grid->CreateGrid(8, 10); // We can set the sizes of individual rows and columns // in pixels grid->SetRowSize(0, 60); grid->SetColSize(0, 120 ); // And set grid cell contents as strings grid->SetCellValue(0, 0, wxT("wxGrid is good")); // We can specify that some cells are read-only grid->SetCellValue(0, 3, wxT("This is read-only")); grid->SetReadOnly(0, 3); // Colors can be specified for grid cell contents grid->SetCellValue(3, 3, wxT("green on grey")); grid->SetCellTextColour(3, 3, *wxGREEN); grid->SetCellBackgroundColour(3, 3, *wxLIGHT_GREY); // We can specify that some cells will store numeric  // values rather than strings. Here we set grid column 5  // to hold floating point values displayed with width of 6  // and precision of 2 grid->SetColFormatFloat(5, 6, 2); grid->SetCellValue(0, 6, wxT("3.1415")); // Set the grid size to the minimum required to show the content  grid->Fit(); // Set the parent frame client size to fit the grid frame->SetClientSize(grid->GetSize()); 

The wxGrid System of Classes

As you have probably gathered by now, wxGrid is not really a single classit's a set of interacting classes. Table 12-9 clarifies what's available and how the classes relate to each other.

Table 12-9. wxGrid Classes

wxGrid	The main grid window class, containing further windows that manage cells, rows, and columns.
wxGridTableBase	A base class enabling an application to provide data to a virtual grid. An instance of a derived class plugs into wxGrid with SetTable.
wxGridCellAttr	Holds visual attributes used to render a cell. You can implicitly change attributes using convenience functions such as SetCellTextColour. You can set attributes for a cell with SetAttr or for a whole row or column with SetRowAttr and SetColAttr. You can provide a GetAttr function in your table class to return attributes for a given cell.
wxGridCellRenderer	This class is responsible for actually drawing the cell in the grid. You can pass it to wxGridCellAttr (or use wxGrid::SetCellRenderer) to change the format of one cell, or youcan pass it to wxGrid::SetDefaultRenderer to change the appearance of all cells. This is an abstract class, and you will normally use one of the predefined derived classes or derive your own class from it. Examples include wxGridCellStringRenderer, wxGridCellNumberRenderer,wxGridCellFloatRenderer, and wxGridCellBoolRenderer.
wxGridCellEditor	This class is responsible for providing and manipulating the in-place edit controls for the grid. Instances of classes derived from wxGridCellEditor can be associated with the cell attributes for individual cells, rows, columns, or even for the entire grid. For example, use wxGrid::SetCellEditor to set an editor for one cell. Examples of editors include wxGridCellTextEditor, wxGridCellFloatEditor, wxGridCellBoolEditor, wxGridCellNumberEditor, and wxGridCellChoiceEditor.
wxGridEvent	Contains information about various grid events, such as mouse clicks on cells, data changing in a cell, a cell being selected, and a cell editor being shown or hidden.
wxGridRangeSelectEvent	This event is sent when the user selects a range of cells.
wxGridSizeEvent	This event class contains information about a row/column resize event.
wxGridEditorCreatedEvent	This event is sent when an editor is created.
wxGridCellCoords	A class representing a cell in the grid. Use Getrow and GetCol to retrieve its position.
wxGridCellCoordsArray	An array of wxGridCellCoords objects. This object is returned by the functions GetSelectedCell, GetSelectionBlockTopLeft, and GetSelectionBlockBottomRight.

wxGrid Events

Table 12-10 lists the major grid events you can catch. Note that each EVT_GRID_... macro also has a form EVT_GRID_CMD_... that takes an identifier and can be used by an ancestor of the grid to avoid the need for deriving a new class.

Table 12-10. wxGrid Events

EVT_GRID_CELL_LEFT_CLICK(func)	The user clicked a cell with the left mouse button.
EVT_GRID_CELL_RIGHT_CLICK(func)	The user clicked a cell with the right mouse button.
EVT_GRID_CELL_LEFT_DCLICK(func)	The user double-clicked a cell with the left mouse button.
EVT_GRID_CELL_RIGHT_DCLICK(func)	The user double-clicked a cell with the right mouse button.
EVT_GRID_LABEL_LEFT_CLICK(func)	The user clicked a label with the left mouse button.
EVT_GRID_LABEL_RIGHT_CLICK(func)	The user clicked a label with the right mouse button.
EVT_GRID_LABEL_LEFT_DCLICK(func)	The user double-clicked a label with the left mouse button.
EVT_GRID_LABEL_RIGHT_DCLICK(func)	The user double-clicked a label with the right mouse button.
EVT_GRID_CELL_CHANGE(func)	The user changed the data in a cell.
EVT_GRID_SELECT_CELL(func)	The user moved to and selected a cell.
EVT_GRID_EDITOR_HIDDEN(func)	The editor for a cell was hidden.
EVT_GRID_EDITOR_SHOWN(func)	The editor for a cell was shown.
EVT_GRID_COL_SIZE(func)	The user resized a column by dragging it.
EVT_GRID_ROW_SIZE(func)	The user resized a row by dragging it.
EVT_GRID_RANGE_SELECT(func)	The user selected a group of contiguous cells.
EVT_GRID_EDITOR_CREATED(func)	The editor for a cell was created.

wxGrid Member Functions

The following is a selection of the most significant wxGrid functions, grouped by functionality. For a complete reference, and for the members of other related classes, please refer to the reference manual.

Functions for Creation, Deletion, and Data Retrieval

These functions relate to creation and deletion of the grid and its cells and interaction with the data in its table.

AppendCols and AppendRows append columns and rows, respectively, to the right or bottom of the grid. You can also use InsertCols and InsertRows to insert them at a given position. If you are using a table, you need to override similarly named functions in your table class.

Use GetNumberCols and GetNumberRows to return the number of columns or rows in the grid table associated with the grid.

CreateGrid 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.

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. ClearSelection deselects all cells that are currently selected.

Use DeleteCols and DeleteRows to delete columns and rows, respectively.

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. Similarly, 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 wxGridTable Base::GetRowLabelValue to provide your own labels. Use SetColLabelValue and SetRowLabelValue to the set the label for a given column or row.

GetCellValue 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 SetCellValue to access cell values. For more complex applications where you have derived your own grid table class, you only use this function for cells that contain string values.

Presentation Functions

These functions relate to the way the grid is displayed.

Use BeginBatch and EndBatch to suppress painting between these calls. Painting will only be done when GetBatchCount returns zero.

EnableGridLines turns the drawing of grid lines on or off. Call GridLinesEnabled to determine if they are on or off.

ForceRefresh causes immediate repainting of the grid. Use this instead of the usual wxWindow::Refresh.

Call Fit to fit the grid window to the smallest size required, given the current number of rows and columns.

GetCellAlignment gets the arguments to the horizontal and vertical text alignment values for the grid cell at the specified location. GetColLabel Alignment gets the current column label alignment, and GetrowLabelAlignment gets the current row label alignment. GetdefaultCellAlignment gets the default alignment for a cell. These functions have corresponding setters. Horizontal alignment will be one of wxALIGN_LEFT, wxALIGN_CENTRE (wxALIGN_CENTER), or wxALIGN_RIGHT. Vertical alignment will be one of wxALIGN_TOP, wxALIGN_CENTRE (wxALIGN_CENTER), or wxALIGN_BOTTOM.

GetCellBackgroundColour returns the background color of the cell at the specified location. GetdefaultCellBackgroundColour returns the default background color for the grid. Get the label background color with GetLabel BackgroundColour. These functions have corresponding setters.

GetCellFont gets the font for text in the grid cell at the specified location, and GetdefaultCellFont gets the default font. GetLabelFont gets the font used for row and column labels. These functions have corresponding setters.

GetCellTextColour returns the text color for the grid cell at the specified location. Use GetdefaultCellTextColour to get the default cell text color and GetLabelTextColour to get the label text color. Corresponding setters are provided.

Change and get the color used for grid lines with SetGridLineColour and GetGridLineColour.

SetColAttr and SetRowAttr set the cell attributes for all cells in the given column or row.

To set the format used for a particular column, use SetColFormatBool, SetColFormatNumber, SetColFormatFloat, and SetColFormatCustom.

Functions for Setting and Getting wxGrid Metrics

The following functions use pixel dimensions.

AutoSize automatically sets the height and width of all rows and columns to fit their contents. You can also use AutoSizeColumn, AutoSizeColumns, AutoSizeRow, and AutoSizeRows.

CellToRect returns the rectangle corresponding to the grid cell's size and position.

Use SetColMinimalWidth and SetRowMinimalHeight to set the column and row minimum dimensions, and retrieve them with GetColMinimalWidth and GetrowMinimalHeight.

Use these functions for getting a variety of dimensions in pixels: GetColLabelSize, GeTDefaultColLabelSize, GeTDefaultColSize, GetColSize, GetdefaultRowLabelSize, GeTRowSize, GeTDefaultRowSize, and GeTRowLabelSize. There are corresponding setters.

If you need extra space around the grid, call SetMargins.

If you need to find the column or row for a given x or y pixel position, use XToCol and YToRow. To find the column whose right edge is closest to a given x position, use XToEdgeOfCol. To find the row whose bottom edge is close to the given y position, use YToEdgeOfRow.

Selection and Cursor Functions

These functions let you control the grid cursor (current focus position) and selection.

GetGridCursorCol and GetGridCursorRow return the current column and row positions of the cursor. Set the cursor position with SetGridCursor.

You can move the cursor one row or column at a time with MoveCursor Down, MoveCursorLeft, MoveCursorRight, and MoveCursorUp. To do the same thing but to skip to the next non-empty cell in the row or column, use MoveCursor DownBlock, MoveCursorLeftBlock, MoveCursorRightBlock, and MoveCursorUpBlock.

Move a page at a time with MovePageDown and MovePageUp, where a page is determined by the size of the grid window.

GetSelectionMode returns one of wxGrid::wxGridSelectCells (the default mode where individual cells are selected), wxGrid::wxGridSelectRows (selections consist of whole rows), and wxGrid::wxGridSelectColumns (selections consist of whole columns). Set the selection mode with SetSelectionMode.

You can retrieve all selected cells with GetSelectedCells, which returns a wxGridCellCoordsArray object containing the cells GetSelectedCols and GetSelectedRows. Because a user can select several non-contiguous blocks of cells, both GetSelectionBlockTopLeft and GetSelectionBlockBottomRight return a wxGridCellCoordsArray. You can identify the blocks by iterating through these arrays.

Call IsInSelection with with a row and column or wxGridCellCoords object to determine whether the cell is within the selection. IsSelection returns TRue if there are any selections in the grid.

Select everything in the grid with SelectAll, select a whole column with SelectCol, and select a whole row with SelectRow. You can select a rectangular block with SelectBlock, passing the top-left and bottom-right cell coordinates as either four integers or two wxGridCellCoords objects.

Miscellaneous wxGrid Functions

These functions deal with various other types of wxGrid functionality.

GetTable retrieves the table associated with the grid, holding the actual data displayed by the grid. If you use CreateGrid, wxGrid creates a table of string data itself. Alternatively, you can use SetTable to set your own table object.

GetCellEditor and SetCellEditor get and set a pointer to the editor for the cell at the specified location. Call GetdefaultEditor and SetDefaultEditor to get and set the default editor used for all cells.

GetCellRenderer and SetCellRenderer get and set a pointer to the renderer for the grid cell at the specified location. Call GeTDefaultRenderer and SetDefaultRenderer to get and set the default renderer used for all cells.

ShowCellEditControl and HideCellEditControl show and hide the edit control for the cell at the current cursor position. This is normally done automatically when the user clicks on a cell to edit it or presses Enter or Escape (or clicks on another window) to finish editing. SaveEditControlValue transfers the value of the in-place edit control to the cellyou may want to call this before closing a grid or retrieving values from a grid to make sure the grid reflects the latest edits.

EnableCellEditControl 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 when this function is called. Call IsCellEditControl Enabled to determine if the cell can be edited. IsCurrentCellReadOnly returns true if the current cell is read-only.

EnableDragColSize enables or disables column sizing by dragging with the mouse. EnableDragGridSize enables or disables row and column resizing by dragging gridlines with the mouse. EnableDragRowSize enables or disables row sizing by dragging with the mouse.

EnableEditing sets the whole grid as read-only if the argument is false. If the argument is true, the grid is set to the default state where cells may be edited. 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 convenience function wxGrid::SetReadOnly. Call IsEditable to determine whether the grid is editable.

You can make a cell read-only with SetReadOnly and retrieve its read-only status with IsReadOnly.

IsVisible returns true if the cell is wholly or partially visible in the grid window. You can make sure a cell is visible by calling MakeCellVisible.