[Up] |
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:
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:
|
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.
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:
As the drawing process is running, the visual state of each cell is adjusted according to grid options and position within grid. The visual state is retained in a variable of type TGridDrawState which is a set with following elements:
gdSelected | The cell will have a selected look. |
gdFocused | The cell will have a focused look. |
gdFixed | Cell have to be painted with fixed cell look. |
gdHot | the mouse is over this cell, so paint it with hot tracking look |
gdPushed | the cell is being clicked, paint it with pushed look |
DrawCell - The DrawCell method is virtual and may be overridden in descendent grids to do custom drawing. The information passed to DrawCell helps to identify which particular cell is being painted, the physical area occupied on the screen and its visible status. See DrawCell reference for details. For each cell the following occurs:
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.
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.
cbsEllipsis - This editor style is the most generic one. A button with ellipsis (...) appears in the editing cell and the programmer can use the OnEditButtonClick grid event to take any programmed action when the user presses the button. For example a calendar dialog could pop up to allow the user to select a specific date, a file open dialog could appear to find files, or a calculator could appear so the user could enter the numeric result of calculations, etc.
cbsPickList - Used to present the user with a list of values that can be entered. This editor style is implemented using TPickListCellEditor, a component derived from TCustomComboBox. The list of values that are shown is filled in one of two ways depending on the method used to select the editor style.
When using custom columns, programmers can enter a list of values using the PickList property for the column.
cbsCheckboxColumn - This editor style is at the moment only available in TDBGrid. If a field's contents associated with the column are restricted to a pair of values, for example, yes-no, True-false, on-off, 1-0, etc. then cbsCheckboxColumn is used to modify the appearance of a column by using a check box representation that the user can toggle by using a mouse click or pressing the SPACE key.
Version 3.2 | Generated 2024-02-25 | Home |