Render Method

  • Article

Occurs when ReportListener is ready to provide output for a layout element in a report or label.

oReportListener.Render(nFRXRecNo,;
                       nLeft,nTop,nWidth,nHeight,;
                       nObjectContinuationType, ;
                       cContentsToBeRendered, GDIPlusImage)

Parameters

  • nFRXRecno
    Specifies the record number in the report or label definition file (frx or lbx) describing the layout element being rendered.
  • nLeft
    Specifies the column coordinate, in units of 1/960 inch (960 dpi), of the rectangle on the current page in which this occurrence of the layout element will be rendered.
  • nTop
    Specifies the row coordinate, in units of 1/960 inch (960 dpi), of the rectangle on the current page in which this occurrence of the layout element will be rendered.
  • nWidth
    Specifies the width, in units of 1/960 inch (960 dpi), of the rectangle on the current page in which this occurrence of the layout element will be rendered.
  • nHeight
    Specifies the height, in units of 1/960 inch (960 dpi), of the rectangle on the current page in which this occurrence of the layout element will be rendered.

  • nObjectContinuationType
    Indicates the current continuation state for the rendered element. When layout elements span pages, they are rendered in multiple sections (once for each page).

    Note

    Continuation can occur for layout elements of Expression (Field), Shape, or Line type. Although Labels and Pictures can span bands in a report, they cannot span pages and ReportListener renders them only once. Not all band types support spanning pages. Refer to Report Bands for more information.

    The following table lists the possible values for nObjectContinuationType.

    Value Continuation Type

    0

    Complete (no continuation).

    1

    Start of layout element occurrence, will not finish on the current page.

    2

    Mid-element, neither started nor finished on the current page.

    3

    End of element, completed on the current page.

  • cContentsToBeRendered
    Indicates the text to be rendered for Expression (Field) and Label layout elements. For Picture layout elements sourced from a file, cContentsToBeRendered contains the filename.

    When specifying a filename for an image, ReportListener provides cContentsToBeRendered as a DBCS string, which is the standard format for strings in Visual FoxPro. However, when indicating text to be rendered, ReportListener provides cContentsToBeRendered as a Unicode string, appropriately translated to the correct locale using any regional script information associated with this layout control in its report definition file (frx) record.

    If your derived class sends the text value through some additional processing, such as storage in a table, you can use the STRCONV() function, and its optional regional script parameter, to convert the string to DBCS first. For more information, see STRCONV( ) Function.

    Note

    You set the default regional script for a report in the Report Properties dialog box. For more information, see Page Layout Tab, Report Properties Dialog Box (Report Builder). You can also set regional script settings for individual layout controls, when you select other font attributes. For more information, see How to: Change Font Settings in Report Controls.

  • GDIPlusImage
    Provides a handle to the GDI+ graphics handle when a Picture layout is sourced from a non-file-based image (a General field or an Image control).

    When the ReportListener renders a different type of layout element, or when you do not set the value of its SendGDIPlusImage property to 1 or higher, this parameter has the value 0. For more information, see SendGDIPlusImage Property.

Return Value

None.

Remarks

Applies To: ReportListener Object.

ReportListener calls Render once for each occurrence of each layout element to be rendered, potentially multiple times for some layout element types that span pages.

Note

During report processing, if you use a Print When expression on a layout element, the Report System evaluates this expression to decide whether each occurrence of a layout element should appear. If Print When evaluates to False (.F.) for a specific occurrence of a layout object, the element does not appear and the ReportListener does not call Render.

Note

If Print When evaluates to True (.T.), you can change the rendered contents of some layout elements using the AdjustObjectSize and EvaluateContents (for example, changing the text of an Expression layout control to a null-length string, or making it transparent). As a result of this activity, you may not see any rendered result in the report output. However, the ReportListener still calls Render in this situation.

Special Features of Visual FoxPro GDI+ Rendering

ReportListener objects use Microsoft Windows GDI+ to render to output devices. GDI+ allows the output to be device-independent, which means the same rendering mechanism is used whether you are previewing report content, printing it, or saving it to an image file.

ReportListener exposes some special features of GDI+ that provide opportunities for you to customize text rendering. For example, the ReportListener's DynamicLineHeight property allows you to leverage GDI+ dynamic line-spacing for rendering text. ReportListener also exposes GDI+ StringTrimming options, which allow you to determine how text is rendered when it does not fit into the space you allotted for an expression control in the report layout. For more information, see DynamicLineHeight Property and Using GDI+ in Reports.

Example

Some parameters are only appropriate for some layout element types. You can use the first parameter, nFRXRecno, to check the report definition file (frx) and determine the layout element type. You can then augment the Render process appropriately for the current element type.

The following example is similar to the code used by the ReportListener XML Display-Style Foundation Class to copy file-based images to disk when the ReportListener renders them. It uses the nFRXRecNo parameter to ascertain the layout element type. If the element is a Picture, it checks the cContentsToBeRendered parameter to see if the file is available for copying. It then defers to the native ReportListener class's code to continue rendering the image to the standard output device.

PROCEDURE Render(nFRXRecNo,;
                 nLeft,nTop,nWidth,nHeight,;
                 nObjectContinuationType, ;
                 cContentsToBeRendered, GDIPlusImage)

   LOCAL llCopyImage, lcFile

   IF THIS.CopyImageFilesToExternalFileLocation 
      THIS.SetFRXDataSession()
      GO nFRXRecNo IN FRX
      IF FRX.ObjType = FRX_OBJTYP_PICTURE AND ;
         FRX.Offset # FRX_PICTURE_SOURCE_GENERAL AND ;
         FILE(cContentsToBeRendered)
         llCopyImage = .T.
      ENDIF
      THIS.SetCurrentDataSession()
   ENDIF   
   
   IF llCopyImage
      lcFile = FORCEPATH(cContentsToBeRendered, ;
          FULLPATH(THIS.ExternalFileLocation, ;
          ADDBS(JUSTPATH(THIS.TargetFileName))))
      IF NOT FILE(lcFile)
         COPY FILE (cContentsToBeRendered) TO (lcFile)
      ENDIF   
   ENDIF
    
   DODEFAULT(nFRXRecNo,;
             nLeft,nTop,nWidth,nHeight,;
             nObjectContinuationType, ;
             cContentsToBeRendered, GDIPlusImage)
ENDPROC

See Also

Reference

ReportListener Object
EvaluateContents Event
AdjustObjectSize Event
Print When Tab, Report Control Properties Dialog Box (Report Builder)

Other Resources

Methods (Visual FoxPro)
Language Reference (Visual FoxPro)