TStringGrid Control

TStringGrid

Description

Represents a grid control designed to simplify the handling of strings.

Remarks

Add a TStringGrid control to a form to present textual data in a tabular format. TStringGrid provides many properties to control the appearance of the grid, as well as events and methods that take advantage of the tabular organization of the grid in responding to user actions.

If the strings to be presented in a grid represent field values from the records in a dataset, use TDBGrid instead.

TStringGrid Properties

Property Cells(ARow, ACol: Integer): String (R/W)

Lists the strings for each cell in the grid. Use Cells to access the string within a particular cell. ACol is the column coordinate of the cell, and ARow is the row coordinate of the cell. The first row is row zero, and the first column is column zero. The ColCount and RowCount property values define the size of the array of strings.

Property Col: Integer (R/W)

Specifies the index of the column that contains the selected cell. Use Col at runtime to determine the current column in the grid. Setting Col moves focus to the cell in the current row that is in the new column. The first column has an index of 0, the second column an index of 1, and so on. The selected cell in the grid can be located by reading the Col property and the Row property to obtain the indexes of its column and row. When focus moves to the grid, the selected cell gets input focus.

Property Row: Integer (R/W)

Specifies the index of the row that contains the selected cell. Use Row at runtime to determine the current row in the grid. Setting Row moves focus to the cell in the current column that is in the new row. The first row has an index of 0, the second row an index of 1, and so on. The selected cell in the grid can be located by reading the Row property and the Col property to obtain the indexes of its row and column. When focus moves to the grid, the selected cell gets input focus.

Property ColWidths(Index: Integer): Integer (R/W)

Indicates the width (in pixels) of all the columns in the grid. Read ColWidths to determine the width of the cells in the column specified by the Index parameter. An index of 0 refers to the first column. Set ColWidths at runtime to change the width of an individual column.

If the width of a column has not been set explicitly by resizing with the mouse, or by using the ColWidths property, its width is DefaultColWidth. Use the ColCount property to determine the number of entries in the ColWidths array.

Property EditorMode: Boolean (R/W)

Determines whether the current cell can be edited. Set EditorMode to true, at runtime, to put the grid in edit mode. When EditorMode is true, the user can edit cells in the grid. When the user presses F2, EditorMode is set to true. When the user presses Enter, the value of EditorMode is toggled.

Note: EditorMode has no effect if the Options property does not include goEditing or if the Options property includes goAlwaysShowEditor.

Property TopRow: Integer (R/W)

Specifies the index of the first visible scrollable row in the grid. Read TopRow to determine the index of the first row in the scrollable region that is visible. Set TopRow to scroll the rows in the grid so that the row with index TopRow is the first row after the fixed rows.

Property ColCount: Integer (R/W)

Specifies the number of columns in the grid. Read ColCount to determine the number entries in the ColWidths array. Set ColCount to add or delete columns at the righthand side of the grid. The value of ColCount includes any fixed columns at the left of the grid as well as the scrollable columns in the body of the grid.

Property RowCount: Integer (R/W)

Specifies the number of rows in the grid. Read RowCount to determine the number entries in the RowHeights array. Set RowCount to add or delete rows at the bottom of the grid. The value of RowCount includes any fixed rows at the top of the grid as well as the scrollable rows in the body of the grid.

Property FixedCols: Integer (R/W)

Specifies the number of columns on the left of the grid that cannot be scrolled. Set FixedCols to create or get rid of nonscrolling columns. Nonscrolling columns appear at the left of the grid, and are always visible, even when the user scrolls the other columns in the grid. Use nonscrolling columns for displaying row titles or row numbers, or to implement a scroll lock that the user can set. Nonscrolling columns are visually distinct from the scrollable columns in the grid. They are painted with a separate background color, and their cells have a raised, 3-D look.

Note: Grids must include at least one scrolling column. Do not set FixedCols to a value greater than ColCount - 1.

Property FixedRows: Integer (R/W)

Specifies the number of rows on the top of the grid that cannot be scrolled. Set FixedRows to create or get rid of nonscrolling rows. Nonscrolling rows appear at the top of the grid, and are always visible, even when the user scrolls the other rows in the grid. Use nonscrolling rows for displaying column titles or column numbers. Nonscrolling rows are visually distinct from the scrollable rows in the grid. They are painted with a separate background color, and their cells have a raised, 3-D look.

Note: Grids must include at least one scrolling row. Do not set FixedRows to a value greater than RowCount - 1.

Property DefaultColWidth: Integer (R/W)

Determines the width (in pixels) of all columns that have not been explicitly resized. Set DefaultColWidth to change the size of all columns in the grid. When DefaultColWidth is set, columns that have been resized using the mouse or by setting the ColWidths property are given the DefaultColWidth as well. When new columns are added to the grid using the ColCount property, they are created with a width of DefaultColWidth.

Property Options: Set of grid options (R)

Specifies various display and behavioral properties of the grid. Set Options to include the desired properties for the grid.

Value	Meaning
goFixedVertLine	Vertical lines are drawn to separate the fixed (nonscrolling) columns in the grid.
goFixedHorzLine	Horizontal lines are drawn to separate the fixed (nonscrolling) rows in the grid.
goVertLine	Vertical lines are drawn to separate the scrollable columns in the grid.
goHorzLine	Horizontal lines are drawn to separate the scrollable rows in the grid.
goRangeSelect	Users can select ranges of cells at one time. goRangeSelect is ignored if Options includes goEditing.
goDrawFocusSelected	Cells with input focus are drawn with a special highlight color, just like selected cells without input focus. If goDrawFocusSelected is not included, the cell with input focus is distinguished by a focus rectangle, not by a special background color.
goRowSizing	Scrollable rows can be individually resized.
goColSizing	Scrollable columns can be individually resized.
goRowMoving	Scrollable rows can be moved using the mouse.
goColMoving	Scrollable columns can be moved using the mouse.
goEditing	Users can edit the contents of cells. When goEditing is included in Options, goRangeSelect has no effect.
goTabs	Users can navigate through the cells in the grid using Tab and Shift+Tab.
goRowSelect	Entire rows are selected rather than individual cells. If goRowSelect is included in Options, goAlwaysShowEditor has no effect.
goAlwaysShowEditor	The grid is locked into edit mode. The user does not need to use Enter or F2 to turn on EditorMode. If Options does not include goEditing, goAlwaysShowEditor has no effect. If Options includes goRowSelect, goAlwaysShowEditor has no effect.
goThumbTracking	The grid image updates while the user is dragging the thumb of the scroll bar. If goThumbTracking is not included, the image does not update until the user releases the thumb in a new position.

TStringGrid Events

Event OnSelectCell

Occurs before a cell in the grid is selected. Write an OnSelectCell event handler to specify whether any particular cell in the grid can be selected. The Col and Row parameters indicate the column and row indexes of the cell that is about to be selected. Set the CanSelect parameter to false to prevent the cell being selected.