CrossPlatform GUI Programming with wxWidgets [Electronic resources] نسخه متنی

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.

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.

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.

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.