THyperGrid |
|
ThgOnButtonClick = procedure( Sender : TObject; ACol , ARow : Longint ) of object;
This event occurs when a column's control type includes the button type and a user clicks on the cell's button. The grid must be editable in order for this event to be fired. The ACol and ARow parameters specify the coordinates of the affected cell.
ThgOnCellEdited = procedure( Sender : TObject; ACol , ARow : Longint ) of object;
This event occurs when a cell's text is changed by the user. It does not fire if the text remains the same. The ACol and ARow parameters specify the coordinates of the affected cell. Note that in some cases this event does not fire, it is not 100% consistent. For example, if the cell is edited and the user immediately presses Ctrl-Page Down, the event will not happen.
ThgOnChangeCellAttributes = procedure( Sender : TObject; ACol , ARow : Longint;
Column : ThgHeading; State : ThgCellStates;
var AColor : TColor; AFont : TFont; var HAlign : TAlignment; var VAlign : ThgVAlignment;
var OuterBevel , InnerBevel : TPanelBevel ) of object;
Note: When using this event, you must add the units HgColumn, HgGlobal and ExtCtrls to your uses clause.
This is one of the most powerful events of THyperGrid since it allows you to dynamically specify the exact formatting characteristics of each and every cell. This event is fired immediately before each cell is painted. By changing the var parameters in this event, you can alter the look of the grid at will. Before this event is fired, THyperGrid populates all of the parameters with the proper values depending on the cell's state and any settings stored in the Column object. For example, if the cell is selected, AColor will be the default selection color. But, you have the option, by using this event, to change any of the values.
| ACol, ARow | The coordinates of the cell that is being painted. |
| Column | The specific column object belonging to the cell. If the cell is a Heading, Column will point to a ThgHeading object, otherwise, Column will point to a ThgColumn object. This can be determined from the State parameter below. |
| State | The state of the cell: ThgCellState = ( hgcsSelected ,
hgcsFocused , hgcsFixed , hgcsHeading ) hgcsSelected means that the cell is selected. |
| AColor | The background color of the cell. |
| AFont | The font that will be used to draw the text in the cell. |
| HAlign | The horizontal alignment of the text in the cell. |
| VAlign | The vertical alignment of the text in the cell, as follows: ThgVAlignment = ( hgvaTop , hgvaCenter , hgvaBottom ) |
| OuterBevel, InnerBevel | Allow you to bevel the cell, similar to a standard TPanel component. |
The following example will change all odd rows that are not fixed, headings or selected to have clInfoBk as the background color and bold font. Note that the focused cell is selected, and as such, will be painted in the default way.
procedure TForm1.HyperGrid1ChangeCellAttributes(Sender: TObject; ACol,
ARow: Integer; Column: ThgHeading; State: ThgCellStates;
var AColor: TColor; AFont: TFont; var HAlign: TAlignment;
var VAlign: ThgVAlignment; var OuterBevel, InnerBevel: TPanelBevel);
begin
if Odd( ARow ) and
not ( hgcsFixed in State ) and
not (hgcsSelected in State ) and
not ( hgcsHeading in State ) then
begin
AColor := clInfoBk;
AFont.Style := [ fsBold ];
end;
end;
ThgOnChangeCellBorders = procedure( Sender : TObject; ACol , ARow : Longint;
Column : ThgHeading; State : ThgCellStates;
TopBorder , RightBorder , BottomBorder , LeftBorder : ThgBorder ) of object;
Note: When using this event, you must add the units HgColumn and HgGlobal to your uses clause.
Before each cell is painted, THyperGrid fires this event to allow you to specify borders for each cell. With this event, you can create a variety of borders around individual cells or ranges of cells. The ACol, ARow, Column and State parameters are the same as for the OnChangeCellAttributes event above. The rest are ThgBorder objects describing each border around the cell.
ThgBorder has three properties:
Style : ThgBorderStyle
Width : Integer
Color : TColor
Style is of the following type:
ThgBorderStyle = ( hgbrdNone , hgbrdSolid , hgbrdDash , hgbrdDot , hgbrdDashDot ,
hgbrdDashDotDot , hgbrdDouble )
The style determines what kind of border to paint, where hgbrdNone is the default which does not draw a border. Width is the width of the border in pixels and Color is the color of the border. The following example will draw a solid red border around row 3.
procedure TForm1.HyperGrid1ChangeCellBorders(Sender: TObject; ACol,
ARow: Integer; Column: ThgHeading; State: ThgCellStates; TopBorder,
RightBorder, BottomBorder, LeftBorder: ThgBorder);
begin
if ARow = 3 then
begin
if ACol = 0 then
with LeftBorder do
begin
Style := hgbrdSolid;
Color := clRed;
Width := 1;
end;
if ACol = Pred( HyperGrid1.ColCount ) then
with RightBorder do
begin
Style := hgbrdSolid;
Color := clRed;
Width := 1;
end;
with TopBorder do
begin
Style := hgbrdSolid;
Color := clRed;
Width := 1;
end;
with BottomBorder do
begin
Style := hgbrdSolid;
Color := clRed;
Width := 1;
end;
end;
end;
It may seem like a lot of code to write for something so simple, yet it is extremely flexible.
ThgOnComboSelection = procedure( Sender : TObject; ACol , ARow : Longint ) of object;
This event occurs when an item is selected in a cell's combo box either by clicking, using the keyboard or accepting a suggestion.
ThgOnGetDisplayText = procedure( Sender : TObject; ACol , ARow : Longint;
Column : ThgColumn; var S : string; var Convert : Boolean ) of object;
Note: When using this event, you must add the unit HgColumn to your uses clause.
THyperGrid allows you to specify formats for cells' text in the Columns property, in this way, you can display formatted strings. For example, you can put "18" in a cell, and specify that it be displayed with a format of two decimal places, so the grid would actually display "18.00"
Whenever a cell is about to be painted, THyperGrid calls OnDisplayText to retrieve the text that will be displayed in the grid. The actual contents of the cell are placed in the S parameter, which you can modify with this event. If the Convert parameter is set to True and the Column has special formatting enabled for the cell, THyperGrid will attempt to convert S using the given formatting, otherwise S will be drawn for the cell. When used properly, this event can be very powerful.
The following example will change the text displayed in the first column of the grid according to a single letter. So, the user can simply type "R" in the cell, and "Red" will be displayed. This can be used to store codes in the grid, but actually show descriptions.
procedure TForm1.HyperGrid1DisplayText(Sender: TObject; ACol,
ARow: Integer; Column: ThgColumn; var S: String; var Convert: Boolean);
var
DS : string;
begin
if ( ACol = 0 ) and ( ARow >= HyperGrid1.FixedRows ) then
begin
DS := Uppercase( S );
if DS = 'R' then
S := 'Red'
else if DS = 'B' then
S := 'Blue'
else if DS = 'Y' then
S := 'Yellow';
end;
end;
If you use a conversion routine, for example, DateToStr and it fails, raising an EConvertError within this event's code, THyperGrid will automatically trap it and call the following event, OnConversionError.
ThgOnConversionError = procedure( Sender : TObject; ACol , ARow : Longint;
Column : ThgColumn; var S : string ) of object;
Note: When using this event, you must add the unit HgColumn to your uses clause.
This event occurs either when a) a cell has special formatting in the Column object and THyperGrid fails to convert it or b) the code attached to the OnDisplayText event raises an EConvertError exception. Changing the S parameter gives you a chance to display a special string for an error, or you can leave it as is and display the original text.
Note: Since these events are called whenever a cell is painted, and the IDE stops each time an exception is raised,you can get into an infinite loop very quickly. To remedy this, simply turn off "Break on exception" in the environment options. With Delphi 4, you can be more sophisticated and instead specify that only EConvertError be ignored.
ThgOnEnterCell = procedure( Sender : TObject; ACol , ARow : Longint ) of object;
Whenever a cell gains focus, this event occurs.
ThgOnExitCell = procedure( Sender : TObject; ACol , ARow : Longint;
var CanExit : Boolean ) of object;
Whenever a cell loses focus, this event is fired. By setting CanExit to False, you can prevent the cell from losing focus.
ThgOnFixedCellClick = procedure( Sender : TObject; ACol , ARow , HeadingIndex :
Longint;
Button : TMouseButton; Shift : TShiftState; X , Y : Integer ) of object;
If the HyperColumnClick property of the grid is set to True, users are allowed to click on any fixed cell, as if it were a button. When the user does so, this event is fired. ACol and ARow are the affected cells, if the cell is a Heading, HeadingIndex will contain its index in the Headings property, otherwise it will be -1. Button, Shift, X and Y are the same as for any other mouse event.
Note: With this feature, fixed cell clicks now serve three purposes:
1) Moving a column or row if goColMoving or goRowMoving are set,
2) Resizing a column or row if goColSizing or goRowSizing are set and
3) Button-like clicks.
Because of this, a small space in each fixed cell has to be saved for each purpose ( if it is enabled ) and the area left for button-like clicks can be very small. This is why it may seem difficult to click on a fixed cell at times. The tricks are: to aim for the middle of the cell, disable all moving and sizing that is not necessary, or make the cells just a bit bigger.
ThgOnGetSuggestion = procedure( Sender : TObject; ACol , ARow : Longint;
CellText : string; var Suggestion : string ) of object;
This event is called when either:
a) A cell is set to contain a combo box and auto suggest is set to false or
b) any text is entered into a cell that does not contain a combo box.
The event allows you to ofer suggestions to the user as he/she types text into a cell. The CellText parameter contains the text that is typed into the cell, and the Suggestion parameter allows you to specify a suggestion for the text. If you leave Suggestion blank, none will be made. Suggestions appear as hints above the cell while the user is typing, they can be accepted by the user by hitting the Enter key, or, if AutoAcceptSuggestion is set to True, automatically when the cell is exited.
The example below, suggests "Yes" when the user types "y" or "Y' and "No" when the user types "n" or "N". This can make data entry into the grid a snap.
procedure TForm1.HyperGrid1GetSuggestion(Sender: TObject; ACol,
ARow: Integer; CellText: String; var Suggestion: String);
begin
if ACol = 1 then
begin
if Uppercase( CellText ) = 'Y' then
Suggestion := 'Yes'
else if Uppercase( CellText ) = 'N' then
Suggestion := 'No';
end;
end;
ThgOnGetReadOnly = procedure( Sender : TObject; ACol , ARow : Longint;
var ReadOnly : Boolean ) of object;
This event allows you to make specific cells read only. Simply set ReadOnly to True and the cell will be so.
ThgOnGetCellImage = procedure( Sender : TObject; ACol , ARow , HeadingIndex : Longint;
var PictureOrImageList : TObject; var ImageIndex : Integer;
var Position : ThgImagePosition; var HAlign : TAlignment;
var VAlign : ThgVAlignment; var Margin : Integer ) of object;
Note: When using this event, you must add the units HgColumn and HgGlobal to your uses clause.
This is another of THyperGrid's very powerful events, as it allows you to place a picture into each cell, and format it however you desire. This event is called before each cell is painted, and by changing the parameters you can place a picture in the cell, together with text, and/or controls.
The ACol, ARow and HeadingIndex parameters are the same as in other events, if the cell is a heading cell, HeadingIndex will be its index in the Headings property, otherwise, it will be -1.
PictureOrImageList is of type TObject and, as the name implies, can point to either a TPicture, or a TImageList. In the case that it is an image list, the next parameter, ImageIndex, specifies which image to use from the list.
Position is defined as follows:
ThgImagePosition = ( hgipLeft , hgipRight , hgipTop , hgipBottom )
This lets you specify where the image will be realtive to the other cell contents, either to the left, to the right, top or bottom. The alignment parameters, HAlign and VAlign let you position the image even further.
If the image is placed at the top or bottom of the cell, the HAlign parameter lets you arrange it to the left, center or right. If the image is at the left or right, you can use VAlign to move the image to the top, center or bottom.
Margin lets you add a margin between the image an the rest of the contents. If the image is at the top or bottom, the margin will be applied above and below the image, otherwise it will be applied to the left and right of the image.
The example below places the first image in the image list in cell 0,0 to the left of the text and centered vertically, it's that easy!
procedure TForm1.HyperGrid1GetCellImage(Sender: TObject; ACol, ARow,
HeadingIndex: Integer; var PictureOrImageList: TObject;
var ImageIndex: Integer; var Position: ThgImagePosition;
var HAlign: TAlignment; var VAlign: ThgVAlignment; var Margin: Integer);
begin
if ( Acol = 0 ) and ( ARow = 0 ) then
begin
PictureOrImageList := ImageList1;
ImageIndex := 0;
Position := hgipLeft;
VAlign := hgvaCenter;
end;
end;
ThgOnEnterCell = procedure( Sender : TObject; ACol , ARow : Longint ) of object;
This event is fired when a row receives focus.
ThgOnExitCell = procedure( Sender : TObject; ACol , ARow : Longint;
var CanExit : Boolean ) of object;
Whenever a row loses focus, this event is fired. By setting CanExit to False, you can prevent the row from losing focus.