ReportListener Base Foundation Class

  • Article

The _ReportListener class serves as the superclass for the other classes in _REPORTLISTENER.VCX, similar to the superclasses for other Visual FoxPro base classes available in _BASE.VCX.

Category Reporting

Default Catalog

Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners

Class

_ReportListener

Base Class

ReportListener

Class Library

_REPORTLISTENER.vcx

Parent Class

ReportListener (ReportListener Object)

Remarks

_ReportListener adds error handling similar to the _BASE classes and includes other core features specific to the responsibilities of ReportListener objects assisting the Report Engine during execution of a REPORT FORM or LABEL FORM command.

These responsibilities include:

  • DataSession handling. Object-Assisted Reporting requires potential manipulation of several different datasessions.

  • Assessment of report state. _ReportListener gives its descendant classes the ability to determine whether certain operations are safe to perform at a given moment. For example, during a report run, it is not safe to switch between different printers.

  • Chain of responsibility. _ReportListener implements a Chain of Responsibility pattern, also known as successorship, to allow multiple output formats during one report run.

  • Management of multiple reports. You can use _ReportListener as an object oriented wrapper for a REPORT FORM command or a collection of REPORT FORM commands in a sequence.

The following table lists public properties and methods added by this class to its parent class, ReportListener.

Properties and methods Description

addReport Method

Adds to the class's collection of ReportFileNames, optionally associating REPORT FORM clauses and a ReportListener for the specified report.

Syntax: addReport(cFRXName [, cClauses[, toListener]])

Return Values: None

Parameters: 

cFRXName provides the name of the report or label file to run.

cClauses provides the optional clauses for this report run, including scope, range, and windowing instructions.

oListener provides an optional reference to be added by _ReportListener when executing this specific report.

appName Property

Holds an application name string for use in user feedback.

Default "VFP Report Listener"

Remarks: See REPORTLISTENERS_LOCS.H, which provides the localizable value to which this property is set in the class' Init method. Descendent classes in _REPORTLISTENERS.vcx override this setting with additional #DEFINEd values in REPORTLISTENERS_LOCS.H.

clearErrors Method

Resets the class's error status.

Syntax: clearErrors()

Return Values: None

Parameters: None.

Remarks: Some subclasses may not function normally after a report run fails. This method is useful for re-setting the state of _ReportListener before a subsequent report run.

getLastErrorMessage Method

Provides information about the last error that occurred.

Syntax: getLastErrorMessage()

Return Values: cErrorMessage

Parameters: None.

isSuccessor Property

Indicates whether this ReportListener is chained to one or more others to provide output during a report run. When .T., this ReportListener was not the object referenced in the REPORT FORM command OBJECT clauses.

Default .F.

lIgnoreErrors Property

Provides a flag to determine how this class handles activities subsequent to an error.

Default .F.

Remarks:   This property ensures that _ReportListener and its descendant classes follow the _BASE error handling model.

prepareErrorMessage Method

Organizes common error information values (nError, cMethod, nLine, cName, cMessage, cCodeLine) into a coherent string for presentation to the user.

Syntax: prepareErrorMessage(nError, cMethod, nLine, cName, cMessage, cCodeLine)

Return Values: cErrorMessage

Parameters: 

You can derive all the parameters to this method except cName from native Visual FoxPro error-handling functions or the equivalent properties of an object of Exception Class (Visual FoxPro). The cName parameter represents the name you would like to present in the error message string as identifying your application.

For example:

LOCAL oListener, oError
oListener = ;
NEWOBJECT("_ReportListener", ;
   "_REPORTLISTENER")
TRY
 * … run some commands here
CATCH TO oError
   IF NOT (ISNULL(oError))
      oListener.DoMessage(;
        oListener.PrepareErrorMessage(;
            oListener.ErrorNo, ;
            oListener.Procedure, ;
            oListener.LineNo, ;
            "My application", ;
            oError.Message, ;
            oError.LineContents))
   ENDIF
FINALLY
   * more commands here
ENDTRY

removeReports Method

Removes report filenames as well as associated clauses and ReportListener references from this class's various collections.

Syntax: removeReports()

Return Values: None

Parameters: None.

reportUsesPrivateDataSession Property

Provides a flag to indicate whether this report shares the data session from which it was executed or maintains a private data session.

Default .F.

runReports Method

Executes a series of REPORT FORM commands according to the instructions in the internal ReportFileNames, ReportClauses, and ReportListeners collections. Optionally clears collection after run and issues the REPORT FORM commands without OBJECT references. Syntax:.runReports([lRemoveReportsAfterRun[, lOmitListenerReferences]])

Return Values: None

Parameters: 

lRemoveReportsAfterRun determines whether the class's internal collection of reports is cleared after the runReports method executes its sequence of REPORT FORM commands.

lOmitReferences determines whether the method includes OBJECT references on each REPORT FORM command.

Remarks: Specifying .T. as the second argument to this method takes precedence over any ReportListener reference the method might otherwise add to your REPORT FORM commands unilaterally. However, it does not necessarily mean your reports will run without ReportListener assistance. If you have used the command SET REPORTBEHAVIOR 90 before using this method, the Report Engine will still get a reference to a ReportListener of the appropriate type from Report Output Application and add it to your REPORT FORM commands. You may also have specified the OBJECT clause for one or more REPORT FORM commands when you added these commands into _ReportListener's collection of reports to run.

If you did not specify tlOmitReferences as .T., _ReportListener checks each REPORT FORM command before executing it to see if you have already included an OBJECT clause in your command. If you have done so, your OBJECT clause takes effect; ReportListener you have specified will be the object reference used for this command.

If you have not included an OBJECT clause, you may have stored in its internal ReportListener collection when you added this REPORT FORM command to its internal collection. _ReportListener adds this reference to your REPORT FORM command if necessary.

If you have not specified a ReportListener when adding the report, and have not specified lOmitReferences as .T.,_ReportListener adds a reference to itself in an OBJECT <ref> clause in the REPORT FORM command.

setSuccessorDynamicProperties Method

Provides a hook for the class to share information changed by the Report Engine with a succession of ReportListeners during a report run.

Syntax: setSuccessorDynamicProperties()

Return Values: None

Parameters: None.

Remarks: Abstract at this class level.

sharedGdiplusGraphics Property

Provides a read/write copy of the Engine's GDIPlusGraphics handle which the ReportListener can share with a succession chain.

Default 0

sharedOutputPageCount Property

Provides a read/write copy of the Engine's OutputPageCount property which the ReportListener can share with a succession chain.

Default 0

sharedPageHeight Property

Shares information gathered by the GetPageHeight method with other ReportListeners linked in a succession chain.

Default 0

sharedPageNo Property

Provides a read/write copy of the Engine's PageNo property which the ReportListener can share with a succession chain.

Default 0

sharedPageTotal Property

Provides a read/write copy of the Engine's PageTotal property which the ReportListener can share with a succession chain.

Default 0

sharedPageWidth Property

Shares information gathered by the GetPageWidth method with other ReportListeners linked in a succession chain.

Default 0

successor Property

Stores an object reference to the next ReportListener in a succession chain.

Default .NULL.

Remarks: See the topic on UpdateListener (ReportListener User Feedback Foundation Class) for an example of ReportListeners in a succession chain.

Example

The following code example shows how you can use _ReportListener to manage a collection of REPORT FORM commands. XmlListener is a subclass of _ReportListener, so it can use this capability. In this example, you chain two reports together to generate a single XML document.

LOCAL ox
ox = NEWOBJECT("XmlListener","_ReportListener")
ox.AddReport(GETFILE("frx"),"NOPAGEEJECT")
ox.AddReport(GETFILE("frx")
ox.RunReports(.T.)

See Also

Reference

Visual FoxPro Foundation Classes A-Z
ReportListener Object

Concepts

Guidelines for Using Visual FoxPro Foundation Classes