ReportListener XML Display-Style Foundation Class
The XmlDisplayListener class tunes XmlListener's default VFP Report XML schema settings suitably for presentation output needs. For full information on the VFP Reporting XML Schema and its options, see Using VFP Report Output XML.
XmlDisplayListener also adds image-file-publishing capabilities:
You can copy the image files used in your report to a new location.
You can save images rendered during the report from general fields or image control references, which were not based on files, to files on disk.
These capabilities are useful when you are preparing reporting output to be published or packaged for display on the Web or for further processing by another publishing application.
See ReportListener HTML Foundation Class for sample code.
| Category | Reporting |
|---|---|
Default Catalog |
Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners |
Class |
XmlDisplayListener |
Base Class |
ReportListener |
Class Library |
_REPORTLISTENER.vcx |
Parent Class |
XmlListener (ReportListener XML Foundation Class) |
XmlDisplayListener, General Fields, and Image Controls
When processing images that did not come from a file on disk, XmlDisplayListener always provides a copy on disk for your use. By default, these files are placed in the same location as your generated report output file, but you can set this location to a different folder, using the XmlDisplayListener.externalFileLocation property. The folder you nominate for this use must exist; otherwise, XmlDisplayListener ignores the instruction.
Tip
When preparing to publish web documents, you will often want to set the location of the image files to a separate directory from the main output file. It is a good idea to set the location as a relative reference, such as ".\images." XmlDisplayListener understands these references to be relative to your main output file.
XmlDisplayListener must save a separate image to disk every time the report renders an image. Because these images may be different for every record in your report, it uses a generated filename convention to name the files. You can adjust these filenames by adding a base filename, to which XmlDisplayListener adds its generated portion as a suffix. This distinguishes your image files from other files from different report runs.
By default, the base class ReportListener does not send full image information to its derived classes. You must request the appropriate information, using the ReportListener.SendGDIPlusImage property.
At the start of a report run, XmlDisplayListener checks to see if there are any General fields in your report design. If it finds references to General fields, it sets .SendGDIPlusImage temporarily, if necessary, and restores the value later.
In Visual FoxPro 9, report designs can include expressions that reference Image controls, as well as general fields and image files on disk. If the Report Engine finds an expression representing an Image control object associated with an Image layout control while it processes your report, it uses the image information in the Image control's PictureVal property. For more information, see PictureVal Property.
XmlDisplayListener cannot know that your report layout expressions may represent Image controls (rather than indirect references to image files on disk) when it evaluates your FRX. For this reason, if you use expressions representing Image controls, unless there are also General fields in your report, you must set its XmlDisplayListener.SendGDIPlusImage explicitly. This explicit instruction will cause the ReportListener to provide the necessary image information as it renders your report. With this property set, XmlDisplayListener detects the GDPlusImage handle the first time it receives one and, if it has not done so earlier, it will set the other, associated attributes required to save the files to disk.
XmlDisplayListener and File-based images
By default, XmlDisplayListener simply references any file-based images on disk using the original filename and providing full path information to the source file. However, you can instruct XmlDisplayListener to publish a copy of your image files to its .externalFileLocation on disk, so you can move the image files with your main XML output file later. To tell XmlDisplayListener you wish to copy the image files, use its .copyImageFilesToExternalFileLocation property.
Remarks
XmlDisplayListener adds the following public properties to its parent class, XmlListener. XmlDisplayListener adds no public methods.
| Properties and methods | Description |
|---|---|
externalFileLocation Property |
Optionally assigns a UNC or file system path, either relative or absolute, the XML result will assign to any external files, such as images, referenced in the main XML output file. Default |
copyImageFilesToExternalFileLocation Property |
Indicates whether file-based images should be copied to a common location from their original locations on your disk, for reference as image sources in the XML output. Default |
imageSrcAttr Property |
Supplies the name of the XML attribute used to show filename copied, or generated for non-file based images, at run time. Default |
formattingChanges Property |
Reference in which classes can store information about actions taken to apply changes to object formatting attributes dynamically during a report run. Default |
See Also
Reference
Visual FoxPro Foundation Classes A-Z
ReportListener XML Foundation Class
ReportListener Object