| Parameter | Description |
|---|---|
| hoGridItemMetrics | Handle to a cCJReportRecordItemMetrics object. Manipulate the properties of this objecty to modify the display attributes of the cell being painted. |
| iRow | Row number of the row whose cell is being painted |
| sValue | Cell text to be painted |
Procedure OnSetDisplayMetrics Handle hoGridItemMetrics Integer iRow String ByRef sValue
This event is called every time a cell is painted and it can be used to modify the value to be displayed, customize colors, fonts and alignment. It can also be used to place images within a cell.
OnSetDisplayMetrics passes the row number of the row being painted, the value to be shown and a bound COM object (cCJGridRecordItemMetrics). You use this object's COM methods to change colors, change fonts or place an icon/image in the cell.
| Property | Meaning |
|---|---|
| ComBackColor | The background color of a cell. |
| ComColumnAlignment | Text and icon alignment of a cell. Combine the following XTPColumnAlignment flags to achieve the desired alignment: (xtpAlignmentDefault, xtpAlignmentLeft, xtpAlignmentCenter, xtpAlignmentRight, xtpAlignmentVCenter, xtpAlignmentWordBreak, xtpAlignmentIconLeft, xtpAlignmentIconCenter, xtpAlignmentIconRight, xtpAlignmentIconTop, xtpAlignmentIconVCenter, xtpAlignmentIconBottom). * |
| ComFont | Font used to display the text of a cell. |
| ComForeColor | The color of the a cell's text. |
| ComGroupRowIcon | Groups are not supported. |
| ComGroupRowIconAlignment | Groups are not supported. |
| ComItemIcon | Cell's icon index. This would allow you to display a different image in each cell. The images must first be loaded into the grid's image list (see AddImage). |
| ComText | The cell's text. This may produce unpredictable results. It is recommended that you set the cell's data source value instead of manipulating this property. |
| ComVirtualRowFlags | Not supported. Do not change this value. |
| ComVirtualRowLevel | Not supported. Do not change this value. |
This example would display all quantity values less than 3 in red.
Procedure OnSetDisplayMetrics Handle hoMetrics Integer iRow String ByRef sValue
If (sValue < 3) Begin
Set ComForeColor of hoMetrics to clRed
End
End_Procedure
Since the value parameter is passed by reference, you can manipulate this to change the value being displayed.
The following example would test if the passed value is "" and change this to "unknown"
Note: This technique will change the value that is displayed in the grid cell, but does not change the cell's underlying data value as stored in the datasource. You would normally use this technique in a non-editable column. If the displayed value is edited, then the resulting value would be saved back to the datasource and become the cell's actual data value.
Procedure OnSetDisplayMetrics Handle hoMetrics ;
Integer iRow String ByRef sValue
If (sValue = "") Begin
Move "unknown" to sValue
End
End_Procedure
In order to change a cell's font attributes you must access the font COM object referenced in the passed cCJGridRecordItemMetrics object's ComFont property. The font COM object can be bound to a DataFlex cComStdFont object and this can be used to manipulate the font attributes.
In the following example, whenever the column value = "New York", then the text is displayed in italics.
Object oState is a cCJGridColumn
Set piWidth to 100
Set psCaption to "State"
Procedure OnSetDisplayMetrics Handle hoMetrics Integer iRow String ByRef sValue
Variant vFont
Handle hoFont
If (Uppercase(sValue) = "NEW YORK") Begin
Get Create (RefClass(cComStdFont)) to hoFont
Get ComFont of hoMetrics to vFont
Set pvComObject of hoFont to vFont
Set ComItalic of hoFont to True
Send Destroy of hoFont
End
End_Procedure
End_Object
Note that a DataFlex cComStdFont object is created, bound to the cell's font COM object. The cell's font is manipulated and then the DataFlex object is destroyed.
To change display attributes, such as font, of the entire grid, rather than conditionally changing the font of individual cells, use phoReportPaintManager.
Because this paint event occurs when the data is being displayed and not when it is being loaded, you should only rely on values actually in your datasource. In other words, don't use global table buffers or data dictionary buffers. By using virtual columns, you can base your customizations on data in your datasource that will never appear as a column. Also, because this is part of a cell paint event (and there can be many cells painted at any time), you want to keep this event as fast as possible.
For example, if you wanted highlight all "active" customers, even though an "active" column will never appear, you could do the following:
// virtual column
Object oActive is a cDbCJGridColumn
Entry_Item Customer.Active
Set pbVisible to False
Set pbShowInFieldChooser to False
End_Object
Object oNameCol is a cDbCJGridColumn
Set piWidth to 183
Set psCaption to "Customer Name"
Entry_Item Customer.Name
Procedure OnSetDisplayMetrics Handle hoGridItemMetrics Integer iRow String ByRef sValue
String sActive
Get RowValue of oActive iRow to sActive
If (sActive="A") Begin
Set ComForeColor of hoGridItemMetrics to clRed
End
End_Procedure
End_Object
Images can be displayed in each cell by setting the passed cCJGridRecordItemMetrics object's ComItemIcon property. This should be set to the image index of an image that was previously loaded in the grid's image list via the AddImage message.
The following example shows two images being loaded into a grid's image list as the grid object is activated. The "danger" icon is diaplayed in the customer number column if the balance is above $5,000. The "warning" icon is displayed if the balance is above $3,000.
Object oCustNames is a cCJGrid
Set Size to 192 343
Set Location to 4 5
Property Integer piImageAva
Property Integer piImageNotAva
Object oNumberCol is a cCJGridColumn
Set piWidth to 78
Set psCaption to "Number"
Entry_Item Customer.Number
Procedure OnSetDisplayMetrics Handle hoGridItemMetrics Integer iRow String ByRef sValue
Number nDue
Forward Send OnSetDisplayMetrics hoGridItemMetrics iRow sValue
Get RowValue of oCreditRiskCol iRow to nDue
If (nDue > 5000) Begin
Set ComItemIcon of hoGridItemMetrics to (piImageAva(Self))
End
Else If (nDue > 3000) Begin
Set ComItemIcon of hoGridItemMetrics to (piImageNotAva(Self))
End
End_Procedure
End_Object
Object oCreditRiskCol is a cCJGridColumn
Set pbVisible to False
Set pbShowInFieldChooser to False
Entry_Item Customer.Balance
End_Object
Procedure LoadIcons
Integer iImage
Get AddImage "ChkOnE.bmp" 0 to iImage
Set piImageAva to iImage
Get AddImage "ChkOffE.bmp" 0 to iImage
Set piImageNotAva to iImage
End_Procedure
Procedure Activating
Forward Send Activating
Send LoadIcons
End_Procedure
End_Object
The column object oCreditRiskCol is created only to store the value that we will test in the customer number column's OnSetDisplayMetrics event. We set the pbVisible and pbShowInFieldChooser properties to False to make this a hidden "virtual" column.
The two icons that were used in this example were 16x16 pixels in size. The image size should not exceed the grid's fixed row height, otherwise the image will be clipped or may not appear. The fixed row height is determined by the grid's font.
If you want to display images that exceed the fixed height of a grid row, then you will need to set the column's pbMultiLine property to True in order to ensure that the grid does not enforce a fixed row height. This will allow the grid row size to increase according to the size of the image that you display in that column.
| Note: | When the grid control does not have a fixed row height, then painting efficiency is no longer optimized. If possible, it is better to keep image size within the row height boundaries and keep pbMultiLine set to False. |