The Preview Container API

Articolo
07/09/2007

When previewing a report or label layout in object-assisted mode, a ReportListener requires an additional component to supply the preview user interface. This component is called a preview container and is written in Visual FoxPro code, and it is therefore completely customizable.

There are two ways a ReportListener instance gets a preview container when it needs one:

Your code explicitly assigns an object reference to the ReportListener's PreviewContainer property.
The ReportListener object asks for an object reference from the Preview Container Object Factory application referenced by the _REPORTPREVIEW System Variable.

The Preview Container API

An object of ReportListener class expects the following methods to be implemented by the object assigned to its PreviewContainer property:

PreviewContainer Method	Parameter	Description
SetReport()	oListenerRef	The ReportListener object will invoke this method, passing it a reference to itself so that the preview container code can call back to listener methods. SetReport() may be called before the report has completed processing, so this method should store the parameter value for later reference. SetReport() may be called with a .NULL. value, in which case the preview container should clear any internal references to a previously passed report listener object, and reset itself.
Show()	[ iModality ]	The ReportListener object will call this method when the report engine is ready to display the preview interface and allow the user to navigate through the report or label output. The iModal parameter is the same as that passed to a form's Show Method (Visual FoxPro).

SetReport()

oListenerRef

The ReportListener object will invoke this method, passing it a reference to itself so that the preview container code can call back to listener methods.

SetReport() may be called before the report has completed processing, so this method should store the parameter value for later reference.
SetReport() may be called with a .NULL. value, in which case the preview container should clear any internal references to a previously passed report listener object, and reset itself.

Show()

[ iModality ]

The ReportListener object will call this method when the report engine is ready to display the preview interface and allow the user to navigate through the report or label output. The iModal parameter is the same as that passed to a form's Show Method (Visual FoxPro).

Although not referenced by any external program, an object implementing the Preview Container API should have an internal reference to the report listener object passed to the object via the .SetReport() method.

PreviewContainer Property	Type	Description
oReport	Object	The .SetReport() and .Show() methods are called at different times. In order for the preview container to have access to various report listener properties at the time the Show() method is called, it should save the report listener reference passed in SetReport() to an internal property.

An object of ReportListener class also expects to receive messages from an object assigned to its PreviewContainer property:

ReportListener Method	Parameter	Description
OnPreviewClose()	lPrint	The ReportListener expects that its OnPreviewClose() method will be called when the preview user interface is closed or otherwise dismissed by the user. The PreviewContainer object can send the lPrint parameter to indicate whether the user chose to print from the preview. Exactly which PreviewContainer method makes the call is not important. If the PreviewContainer object is a form, or has an interface similar to a form's, some candidate methods would be Hide(), Release(), QueryUnload(), and Destroy().

OnPreviewClose()

lPrint

The ReportListener expects that its OnPreviewClose() method will be called when the preview user interface is closed or otherwise dismissed by the user. The PreviewContainer object can send the lPrint parameter to indicate whether the user chose to print from the preview.

Exactly which PreviewContainer method makes the call is not important. If the PreviewContainer object is a form, or has an interface similar to a form's, some candidate methods would be Hide(), Release(), QueryUnload(), and Destroy().

It takes a few lines of code to put it all together:

* Instantiate your preview container implmentation
oMyPreview = NEWOBJECT("MyPreviewContainer","MyClassLib")
* Instantiate a ReportListener (or your own derived class)
oListener  = CREATEOBJECT("ReportListener")
* Tell the listener to render all pages and use a preview container:
oListener.ListenerType = 1
* Give the listener a reference to your preview container:
oListener.PreviewContainer = m.oMyPreview
* Run the report:
REPORT FORM myreport OBJECT m.oListener

For an example of a simple preview container implementation, see Creating a Custom Preview Container.

The _REPORTPREVIEW Object Factory

The code shown above covers the case where a ReportListener is explicitly assigned a preview container reference prior to running the report. If the ReportListener does not have a preview container reference, and requires one, it obtains one by calling out to the application or program referenced by the _REPORTPREVIEW system variable.

The program referenced by _REPORTPREVIEW must do the following:

Accept a parameter, passed by reference from the report engine.
Assign to the parameter an object reference to an instance of a class which implements the preview container API.
Return.

Example:

* Program suitable for _REPORTPREVIEW:
LPARAMETER loRef
loRef = NEWOBJECT("MyPreviewContainer","MyClassLib")
return

The program in _REPORTPREVIEW is invoked when you issue the following types of Visual FoxPro commands:

REPORT FORM or LABEL … PREVIEW when SET("REPORTBEHAVIOR") has the value 90.
REPORT FORM or LABEL … OBJECT <oRef> when oRef.ListenerType has the value 1 and you have not assigned a value to oRef.PreviewContainer.
REPORT FORM or LABEL … OBJECT TYPE 1 when the ReportListener assigned by the listener factory specified by _REPORTOUTPUT does not already have a value assigned to its PreviewContainer member.

The Preview Container API

The Preview Container API

The _REPORTPREVIEW Object Factory

See Also

Reference

Other Resources

Risorse aggiuntive