Methods | Fields | This Package | All Packages

DataGrid Class

Implements a data-bound grid that is filled with data from an ADO recordset. The rows and columns in the grid represent the records and fields in the recordset.

Component
  |
  +--Control
       |
       +--DataGrid

package com.ms.wfc.data.ui

public class DataGrid
extends Control

Remarks

To bind the DataGrid control to a recordset, set its dataSource property (and optionally, the dataMember property). When the DataGrid control is bound, it is automatically populated with data.

Important   You cannot bind the DataGrid control to a recordset that has a forward-only cursor. The recordset must also support bookmarks.

If the recordset allows records to be edited, added, or deleted, you can set DataGrid control properties to determine whether the grid can be used to modify the recordset. For example, the allowUpdate and allowDelete properties indicate whether records can be edited or deleted via the grid. If both the allowAddNew and allowUpdate properties are set to true, the user can add a new row to the grid, which then adds a new record to the recordset. Changes made through the DataGrid control are automatically propagated to the recordset, and vice versa.

The cell in the grid that has focus is outlined with a heavy border, and is referred to as the current cell. To specify the current cell, the user can click it with the mouse or navigate to it using the keyboard. (The allowArrows, enterAction, and tabAction properties define which keys can move the current cell focus.) To programmatically specify the current cell, call setCurrentRow and setCurrentColumn. The intersection of the current row and the current column determines the current cell. (Note that changing the current row in the grid changes the current record in the underlying recordset, and vice versa.)

When a cell is current, its contents can be changed (provided the allowUpdate property is true and the recordset permits data changes). To put the current cell in edit mode, the user can press F2, click in the cell, or simply begin typing to replace the cell's contents. To exit edit mode, the user can press F2 again or click outside the cell.

When a cell enters edit mode, the columnEditing event is triggered. This event specifies the column that is being edited and the key that was pressed that triggered the edit. After the user finishes typing and exits edit mode, the following events are triggered, in the specified order:

• updating  Occurs before the underlying recordset is updated with the new value; no information about the update is provided.
• columnUpdating  Occurs before the recordset is updated with the new value. This event specifies the column that is being updated and the previous value of the cell.
• updated  Occurs after the recordset is updated with the new value; no information about the update is provided.
• columnUpdated  Occurs after the recordset is updated with the new value. This event specifies the column that was updated.
• columnEdited  Indicates that editing is complete. This event specifies the column that was edited.

If the actual data value in the cell remains unchanged, or if the user simply enters and exits edit mode without typing, only the columnEditing and columnEdited events are triggered.

Note   None of these events occur if you programmatically change a cell's value through setCurrentCellValue.

The DataGrid control supports the selection of entire rows or columns, but not the selection of individual cells. The user can select a row or column by clicking the row or column header; by pressing and holding down the CTRL key, multiple rows or columns can be selected. To programmatically select rows and columns, call setSelectedRows and setSelectedColumns.

Each column in the DataGrid control is a Column object, bound to a field in the underlying recordset. Each column maintains its own properties that are set independently of other columns. The properties of the DataGrid control can be used to define default attributes for all columns in the grid. Using the Column object properties, you can then customize individual columns as needed. For example, set the DataGrid control's font property to define the default font for all text in the grid; then, specify a different font for one of the columns by setting the Column object's font property. The column's property setting overrides the grid's setting for that particular column.

The DataGrid control identifies each column in the grid by a zero-based index. This index specifies the position of the column in the grid. By setting the column's index property, you can rearrange the columns in the grid. Note that every column has an index, even if you hide a column. For example, if you set the column's visible property to false, the column still has an index of 0. The column that the user now sees as the first column is still the second column in the grid, with an index of 1.

While a column in the grid is identified by its index, a row is identified by the bookmark of the record in the underlying recordset. For example, to programmatically change the current row in the grid, you call the setCurrentRow method and specify the bookmark of the corresponding record to be made current.

For the rows that are visible in the grid's current scroll position, you can determine the order in which a row is displayed by calling getDisplayIndex. When you pass a bookmark to this method, the zero-based display index of the corresponding row is returned (provided the row is currently visible).

For information about using the DataGrid control in the Forms Designer, see Binding Data with the DataGrid Control.