EvaluateContents Event

  • Article

Occurs just before ReportListener begins rendering objects for a band, for each layout element of Expression type, providing an opportunity to change its attributes.

PROCEDURE Object.EvaluateContents
LPARAMETERS nFRXRecno, oObjProperties

Parameters

Visual FoxPro passes the EvaluateContents event parameters in the following order:

  • nFRXRecno
    Integer data type, specifying the record number in the report or label definition file (frx or lbx) describing the layout element being rendered.

  • oObjProperties
    An object of Empty class, with members providing values relevant to adjusting the attributes of an Expression layout element.

    oObjProperties member Type Usage

    reload

    Logical, defaults to .F.

    Flag to alert the ReportListener if you make changes.

    Set this value to True (.T.) to notify the ReportListener of changes to any of the read/write members of oObjProperties.

    text

    Character, defaults to evaluated contents of the Expression layout element.

    You can change this value to change the rendered contents of the Expression at run time.

    value

    Variant, readonly

    This value provides the evaluated results of report expressions, including calculated fields, of the following data types:

    Double (B)

    Date (D)

    Float (F)

    Integer (I)

    Logical (L)

    Numeric (N)

    DateTime (T)

    Currency (Y)

    Null (X)

    For other data types, its contents is a null string ("").

    Expressions concatenated with the special operators ";" and "," may have elements of mixed type, and are considered character strings (type "C") in this context. For more information, see Trimming and Concatenating Expressions.

    fontname

    Character, defaults to the font stored in the report or label definition table for this layout element.

    You can change this value to change the font of the Expression at run time.

    fontstyle, fontsize

    Integer, default to the numeric style and size values stored in the report or label definition table for this layout element.

    You can change these values to change the size and style of the font used to render this Expression at run time.

    Recognized numeric values for oObjProperties.fontstyle are documented in the 60FRX.DBF table in the FILESPEC directory.

    For more information about 60FRX, see Table Structures of Table Files (.dbc, .frx, .lbx, .mnx, .pjx, .scx, .vcx).

    fillred, fillblue, fillgreen, penred, penblue, pengreen

    Integer, valid values 0 to 255, defaults to 255, defaults to the values stored in the report or label definition table, unless the table value was -1 to indicate "use default". If the table value was -1, the ReportListener substitutes the real value it intends to use.

    You can change these values to change the Red, Blue, and Green components of the Fill and Pen colors for an Expression element.

    For more information, see How to: Change Colors in Report Controls.

    If a non-valid value or non-numeric value is passed for any of the color properties, they revert to default values stored in the report definition table. No error occurs.

    fillalpha

    Integer, valid values 0 to 255, defaults to 0 when backstyle is transparent and 255 when backstyle is opaque.

    See Remarks below for information on using the alpha values of report layout elements. If a non-valid value or non-numeric value is passed for this value, it reverts to the default value as shown in this chart.

    For information on report backstyle settings (transparent and opaque), see How to: Change Opacity of Report Controls.

    penalpha

    Integer, valid values 0 to 255, defaults to 255 (opaque).

    See Remarks below for information on using the alpha values of report layout elements.

    If a non-valid value or non-numeric value is passed for this value, it reverts to the default value as shown in this chart.

    Note

    Microsoft reserves the right to invoke EvaluateContents for additional report and label layout elements, as needed, and to add to the oObjProperties members appropriately for these additional layout element types. You can use nFRXRecno to test for layout element type, as shown in the sample code in Render Method.

Remarks

Applies To: ReportListener Object.

Visual FoxPro calls EvaluateContents at the beginning of band processing, once for each Expression element. It is not guaranteed to be called exactly once; it may be called multiple times for evaluated expressions that span bands or pages if the Report System deems necessary (for example, if the expression includes _PAGENO).

Note

If you write code to try to forecast when EvaluateContents might be called multiple times, consider that not all band types support spanning pages. Refer to Report Bands for more information.

Tip

To enhance performance, Visual FoxPro does not call either AdjustObjectSize or EvaluateContents if it determines that there is no code in the ReportListener for the event. If you usually include placeholder code or generalized code in every event, consider omitting such code for these two events, especially if the class level is abstract (never directly instantiated). Only include code at the class levels that actually use this functionality. The performance cost for EvaluateContents increases with amount of text the native ReportListener provides in the oObjProperties.text member property, so it may vary with each call.

You can use this method to change various characteristics of Expression layout elements. However, you cannot change the width of the layout element, so you should adjust the font characteristics and contents of the Expression with this limitation in mind. If the layout element has been marked to stretch, it follows the same rules as Shape and Picture elements to which you make height adjustments in the AdjustObjectSize event. For more information, see AdjustObjectSize Event.

EvaluateContents gives you the means to change the Alpha value (transparency) of both the Pen and Fill values for an Expression. Report and label definition files store only RGB (Red, Green, Blue) components of color values, with a single setting for "opaque" or "transparent." Using EvaluateContents, you can provide more subtle color effects by direct manipulation of the Alpha value.

Tip

The ability to use Alpha color values when rendering is a feature provided by Microsoft Windows GDI+. For more information, see Using GDI+ in Reports.

Example

The following example cycles through different color combinations based for the odd and even instances of any report's Detail band Expressions, providing a "greenbar" output effect. It also applies some style attributes to elements not in Detail bands. Notice that these effects are applied only to Expressions (for example, labels in a Page Header band are not affected).

oReportListener = CREATEOBJECT("greenBar")
oReportListener.ListenerType = 1
REPORT FORM (GETFILE("frx")) PREVIEW OBJECT oReportListener 

#DEFINE DETAIL_BAND 4
#DEFINE BOLD_UNDERLINE_ITALIC 1+4+2
DEFINE CLASS greenBar AS ReportListener
   detailInstance = 0
   isDetail = .F.

   PROC BeforeBand(nBandObjCode, nFRXRecno)
     IF nBandObjCode = DETAIL_BAND
        THIS.detailInstance = THIS.detailInstance + 1
        THIS.isDetail = .T.
     ELSE
        THIS.isDetail = .F.     
     ENDIF
   ENDPROC

   PROC EvaluateContents(nFRXRecno, oProps)
       oProps.Reload = .T. 
       * re-load every time, in this example,
       * since we want to change every Expression
       IF THIS.isDetail
          IF THIS.detailInstance % 2 = 0 
             oProps.penRed = 0
             oProps.penBlue = 125
             oProps.penGreen = 0
          ELSE
             oProps.penRed = 0
             oProps.penBlue = 0
             oProps.penGreen = 0
             oProps.fillRed = 0
             oProps.FillBlue = 0
             oProps.FillGreen = 255
             oProps.FillAlpha = 125
              *half-transparent background color
          ENDIF
       ELSE   
          oProps.FontStyle = BOLD_UNDERLINE_ITALIC
       ENDIF
   ENDPROC
ENDDEFINE

See Also

Tasks

How to: Add Field Controls to Reports

Reference

ReportListener Object

Other Resources

Events (Visual FoxPro)
Language Reference (Visual FoxPro)