ReportListener Object

The Preview Container API

The simplest possible preview example does not use the Preview Container API at all, but uses methods of the ReportListener object to demonstrate the essential mechanism behind the API.

The following commands set up a target Shape object, run a report in object-assisted mode, and use the methods of the ReportListener object to display the first page of the report on the target shape:

Copy Code

* Set up a target for the preview rendering: _SCREEN.AddObject("canvas","Shape") _SCREEN.canvas.Width = 250 _SCREEN.canvas.Height = 300 * Create a base ReportListener and buffer the entire report: rl = NEWOBJECT("ReportListener") rl.ListenerType = 3 && Buffer all pages, do not preview automatically * Process the report: REPORT FORM (_SAMPLES+"\solution\reports\colors.frx") OBJECT rl * Render page 1 to the target: rl.OutputPage( 1, _SCREEN.canvas, 2 )

After executing these statements in the Command Window, you will see a thumbnail-size image of the report rendered on the surface of the screen.

Things to note:

• The third parameter passed to the ReportListener's OutputPage() method is 2, which indicates that the target handle passed in the second parameter is a Visual FoxPro object reference - the Shape control.

• The Shape object did not have to be visible in order for the report to display.

• Either a Container or a Shape control can be used as the target.

• Dragging the command window over the preview erases it from the screen, because when the screen receives a paint message, it repaints itself with no knowledge of the preview rendering.

The next step is to encapsulate the process described above into a class that implements the preview container API, allowing you to re-use the previewing logic.

The following example program, simplepreview.prg, contains a class definition which also uses a Shape object as the render target, this time on a form class that implements the preview container API:

Copy Code

*----------------------------------------- * simplepreview.prg *----------------------------------------- DEFINE CLASS SimplePreview AS Form Caption = "Click for next page" ListenerRef = .NULL. PageNo = 1 AllowOutput = .F. ADD OBJECT Canvas AS Shape WITH ; Top = 12, Left = 8, ; Height = 252, Width = 209, ; Name = "Canvas" PROCEDURE Canvas.Click WITH THISFORM IF .PageNo < .ListenerRef.OutputPageCount .PageNo = .PageNo + 1 .Refresh() ENDIF ENDWITH ENDPROC PROCEDURE SetReport LPARAMETER oListenerRef THIS.ListenerRef = oListenerRef ENDPROC PROCEDURE QueryUnload IF NOT ISNULL( THIS.ListenerRef ) THIS.ListenerRef.OnPreviewClose(.F.) THIS.ListenerRef = .NULL. ENDIF THIS.Hide() NODEFAULT ENDPROC PROCEDURE Paint IF NOT ISNULL( THIS.ListenerRef ) THIS.ListenerRef.OutputPage( THIS.PageNo, THIS.Canvas, 2 ) ENDIF ENDPROC ENDDEFINE

This class implements the two methods of the preview container API by explicitly defining a SetReport() method; and by being derived from the Form base class, which already has an appropriate Show() method.

Things to note:

• This class resolves the repainting issues of the previous example by adding code to the form's Paint() event to ensure that the preview image is redrawn when required.

• The Reportlistener object will call SetReport(), passing a reference to itself when it requires the preview container to perform basic non-report-specific initialization. SetReport() will also be called with null (.NULL.) when its OnPreviewClose() method is invoked.

• The code in the QueryUnload() event informs the report listener that you have finished viewing the report, and then nulls out the reference to the report listener object to avoid a dead-lock condition that would prevent the form from closing.

• The code in the Shape.Click() method uses the report listener's OutputPageCount property to ensure that the preview does not request a page that does not exist.

The following code demonstrates how to re-use a preview container component, by instantiating the SimplePreview class and assigning it to the PreviewContainer property of a ReportListener object. Try in the Command Window:

	Copy Code
pc = NEWOBJECT("SimplePreview", "simplepreview.prg") rl = NEWOBJECT("ReportListener") rl.ListenerType = 1 && Buffer all pages, use preview container rl.PreviewContainer = pc REPORT FORM (_SAMPLES+"\solution\reports\colors.frx") OBJECT rl REPORT FORM (HOME()+"Tools\Filespec\60frx2.frx") OBJECT rl

After running this code, you will observe that the SimplePreview form is displayed automatically. This is because the report listener object invoked the PreviewContainer.Show() method after the report has completed processing.

If you change the last line of the example above to include the NOWAIT clause, you will observe that the preview form is no longer modal when it is displayed. The report listener object recognizes the NOWAIT clause and invokes Show(0) instead of Show(1).

Hide or Release?

• In SimplePreview.prg above, the QueryUnload() event suppresses default behavior with NODEFAULT and manually hides the form by calling Hide().

This is for two reasons:

• There is an outstanding reference to the form held by the report listener PreviewContainer property which means that, without additional code, the form won't close and release when you click the close box. The close box will disable and the form will stay visible.

• The Hide() allows the preview container to be re-used in successive report previews, as the previous example code shows.

If you do not wish your custom preview container to stay available for further report previews with the report listener, you can modify the QueryUnload method as shown below:

	Copy Code
PROCEDURE QueryUnload IF NOT ISNULL( THIS.ListenerRef ) THIS.ListenerRef.PreviewContainer = .NULL. THIS.ListenerRef.OnPreviewClose(.F.) THIS.ListenerRef = .NULL. ENDIF ENDPROC

This alternative implementation results in the preview container being discarded after one report preview. Try the steps above again in the Command Window with the revised preview container class, and you will see that only the first preview uses SimplePreview. The second report run reverts to the default preview container because the ReportListener object detects that it no longer has a reference in its PreviewContainer property and requests a new one via _REPORTPREVIEW.

You can replace the default preview container used by object-assisted reporting preview in Visual FoxPro by adding the following lines to the top of the program containing the SimplePreview class definition introduced earlier in this topic:

	Copy Code
*----------------------------------------- * Add to the top of simplepreview.prg *----------------------------------------- LPARAMETER loPreviewContainerRef * parameter is passed by reference loPreviewContainerRef = CREATEOBJECT("SimplePreview") RETURN DEFINE CLASS SimplePreview AS Form ...

This program is now suitable for assigning to _REPORTPREVIEW, specifying the preview container to be returned to Visual FoxPro whenever one is requested by a ReportListener object performing a REPORT… PREVIEW in object-assisted mode.

You can test it out in the Command Window:

	Copy Code
_REPORTPREVIEW = "simplepreview.prg" SET REPORTBEHAVIOR 90 REPORT FORM (HOME()+"Tools\Filespec\60frx2.frx") preview

See Leveraging the Default Preview Container

Reference