[Up] Reference for unit 'Grids' (#lcl)

How to use Grids including StringGrids, DrawGrids and DbGrids.

Customizing Grids

Grids are components derived from the TCustomControl class and do not have a native widget associated with them. So they are not restricted by the look of the current interface theme. This can be both an advantage and a disadvantage: usually programmers want to create a uniform-look application. Lazarus grids are flexible enough to allow programmers to make them look similar to other native controls; alternatively they can customize the grid to obtain almost the same look in any platform or widget interface (with the exception of scroll bars, whose look is still determined by the current theme).

Some properties can affect the way the grid looks by acting when the cell is about to be painted in PrepareCanvas/OnPrepareCanvas by changing default canvas properties like brush color or font. Following is a list of such properties:

Properties and Events for Customizing Grids
Property Meaning
AlternateColor The user can change the background color that appears on alternate rows. This is to allow easy reading of grid rows data.
Color Sets the primary color used to draw non fixed cells' background.
FixedColor The color used to draw fixed cells' background.
Flat Eliminates the 3d look of fixed cells.
TitleFont Font used to draw the text in fixed cells.
TitleStyle

Changes the 3D look of fixed cells. There are 3 settings:

tsLazarus
The default look
tsNative
Tries to use an appearance that is in concordance with the current widgetset theme
tsStandard
A more contrasted look, like Delphi grids
AltColorStartNormal If True, alternate color is always in the second row after fixed rows; the first row after fixed rows will always be the default color. If False, default color is set to the first row as if there were no fixed rows.
BorderColor Sets the grid's border color used when Flat=True and BorderStyle is bsSingle.
EditorBorderStyle If set to bsNone under Windows the cell editors will not have the border, like in Delphi; set to bsSingle by default because the border can be theme specific in some widgetsets and to allow a uniform look.
FocusColor The color used to draw the current focused cell if UseXORFeatures is not set; by default this is clRed.
FocusRectVisible Turns on/off the drawing of focused cell.
GridLineColor Color of grid lines in non fixed area.
GridLineStyle Pen style used to draw lines in non fixed area, possible choices are: psSolid, psDash, psDot, psDashDot, psDashDotDot, psinsideFrame, psPattern, psClear; default is psSolid.
SelectedColor Color used to draw cell background on selected cells.
UseXORFeatures If set, focus rect is drawn using XOR mode so it should make visible the focus rect in combination with any cell color background. It also affects the way that moving columns look
DefaultDrawing Normally the grid prepares its grid canvas using properties according to the kind of cell that is being painted. If the user has written an OnDrawCell event handler, it is used to perform specified drawing operations for a given cell. DefaultDrawing (if set) also paints the cell background; if the user is taking full responsibility for drawing the cell it is better to turn off this so painting is not duplicated. In a StringGrid, if DefaultDrawing is set it draws the text in each cell.
AutoAdvance Where the cell cursor will go when pressing enter or tab/shift tab, or after editing.
ExtendedColSizing If True, the user can resize columns, not just at the headers, but anywhere along the column's height.

Other Properties that Affect Grid Appearance:

Options

This is a set of zero or more choices, with some elements that enable diverse functionality but others that are related directly with grid's look. Options can be set at design-time or run-time.

goFixedVertLine, goFixedHorzLine
Draws a vertical or horizontal line respectively, delimiting cells or columns in the fixed area; active by default.
goVertLine, goHorzLine
The same as previous, but for the normal browsable area. A grid can be made to simulate the visual appearance of a list box by removing both of these options.
goDrawFocusSelected
If this option is enabled, a selection background is painted in the focused cell in addition to the focused dotted rectangle. Please note: this doesn't work when the goRowSelect option is set; in such case the row is always painted as if goDrawFocusSelected is set.
goRowSelect
Selects the full row instead of individual cells.
goFixedRowNumbering
If set, grid will do numbering of rows in first fixed column.
goHeaderHotTracking
If set, the grid will try to show a different look when the mouse cursor is over any fixed cell. In order for this to work, desired cell zone needs to be enabled with the HeaderHotZones. Try combining this option with TitleStyle= tsNative to get themed hot tracking look.
goHeaderPushedLook
If set, this option enables a pushed look when clicking any fixed cell. The zone of "pushable" cells is enabled using HeaderPushedZones property.

Description of the Grid Drawing Process

Like other custom controls, the grid is drawn using the paint method. In general terms the grid is drawn by painting all rows, and each row by painting its individual cells. The process is as follows:

Grid Cell Selection

The location of a grid's current (focused) cell (or row) can be changed using keyboard, mouse or through code. In order to change cell focus successfully to another position, we must test the target position to see if it is allowed to receive cell focus. When using the keyboard, AutoAdvance performs part of the process by finding what should be the next focused cell. When using mouse clicks or moving by code, focus will not move from the current cell unless the target cell is permitted to receive focus.

The grid calls SelectCell to see if a cell can be focused: if this function returns True, then the target cell identified with arguments aCol and aRow can be focused (the current implementation of TCustomGrid simply returns True). TCustomDrawGrid and hence TDrawGrid and TStringGrid override this method and check first if a cell is any wider than 0; normally you don't want a 0 width cell selected so a cell with this characteristics is skipped automatically in the process of finding a suitable cell. The overridden method SelectCell also calls the user configurable event OnSelectCell: this event receives the cell coordinates as arguments and always returns a default result of True.

If a cell can be focused and we are sure a movement will take place, the method BeforeMoveSelection is called; this in turns triggers the OnBeforeSelection event. This method's arguments are the coordinates for the new focused cell; at this point any visible editor is hidden too. The "before" word means that selection is not yet changed and current focused coordinates can be accessed with grid.Col and grid.Row properties.

After that, the internal focused cell coordinates are changed and MoveSelection is called; this method's purpose (if set) is to trigger the OnSelection event (this is a notification that the focused cell has changed and the new cell coordinates are available through grid.row and grid.col properties).

Note that is not good to use the OnSelectCell event to detect cell focus changes, as this event will be triggered several times even for the same cell in the process of finding a suitable cell. Is better to use OnBeforeSelection or OnSelection events for this purpose.

Using Cell Editors

Users can specify what editor will be used for a cell using one of two methods.

  1. Using a custom column and selecting the ButtonStyle of the column. In this method the user can select the style of the editor that will be shown. Available values are: cbsAuto, cbsEllipsis, cbsNone, cbsPickList, cbsCheckboxColumn.
  2. Using the OnSelectEditor Grid Event

    Here the user specifies in the Editor parameter which editor to use for a cell identified by aCol, ARow in a TCustomDrawGrid derived grid or TColumn in TCustomDBGrid. The public EditorByStyle() function takes as parameter one of the following values: cbsAuto, cbsEllipsis, cbsNone, cbsPickList, cbsCheckboxColumn.

    This method takes precedence over the first one using custom columns. A Custom cell editor can be specified here, with values specific to the cell, row or column.

Description of Editor Styles

The following is a description of the editor styles. They are enumerated values of type TColumnButtonStyle and so they are prefixed by 'cbs'. This type was used to remain compatible with Delphi's DBGrid.


Version 3.2 Generated 2024-02-25 Home