Leveraging the Default Preview Container

  • Article

To facilitate the SET REPORTBEHAVIOR 90 setting, Visual FoxPro ships with a default preview container factory application, ReportPreview.App. It is located in the HOME() directory along with the other tools, and is referenced by default in the _REPORTPREVIEW system variable.

This topic describes the capabilities of the Preview Container component delivered by ReportPreview.App, additional to the standard Preview Container API.

Prerequisites

Object Diagram

The following illustration shows the object diagram of the default preview container as it exists after the report engine has called the Show() method. Prior to that point, the oForm and oForm.Toolbar member objects may not have been instantiated:

Visual FoxPro Preview Object Diagram graphic

A proxy object is used because in order to support numerous clauses of the REPORT FORM… PREVIEW command in object-assisted mode, the preview may instantiate one of a number of specific form classes derived from the parent class frxPreviewForm as its oForm reference:

Class Name Derived From Notes

Form

n/a

Visual FoxPro base form class

frxBaseForm

Form

Implements error handling and large font support.

frxPreviewForm

frxBaseForm

Implements the Preview Container API.

.ShowWindow = 1 - in top-level form

frxPreviewAsTopForm

frxPreviewForm

.ShowWindow = 2 - As top-level form

frxPreviewInScreen

frxPreviewForm

.ShowWindow = 0 - In Screen

frxPreviewInDesktop

frxPreviewForm

.Desktop = .T.

The properties and methods described below are members of the frxPreviewProxy object.

Additional Properties and Methods

In addition to the standard preview container API, the default component returned by ReportPreview.App exposes other properties and methods that can be used to control the appearance of the Preview window when object-assisted reporting mode is used.

Properties

These properties control the initial state of the preview window only. If set to non-default values, these properties take precedence over any preferences restored from the resource file.

Property Name Type Description

Top

I

Specifies the vertical offset from the top of the main Visual FoxPro window of the of the preview form, in pixels.

Left

I

Specifies the left horizontal offset from the left side of the main Visual FoxPro window of the of the preview form, in pixels.

Width

I

Specifies the horizontal size of the preview form in pixels.

Height

I

Specifies the vertical size of the of the preview form, in pixels.

ToolbarIsVisible

L

Specifies that the preview window toolbar should be initially visible.

Caption

C

Specifies the caption of the preview window.

CanvasCount

I

Specifies the initial number of pages rendered on the preview form. Valid values are 1, 2, or 4.

ZoomLevel

I

Specifies the initial zoom level of the preview window. Possible values are:

1 - 10%

2 - 25%

3 -50%

4 - 75%

5 - 100% (default)

6 - 150%

7 - 200%

8 - 300%

9 - 500%

10 - whole page

CurrentPage

I

Specifies the initial page to render on the preview form. The default is 1. If it is greater than the number of pages available the last page will be displayed.

TopForm

L

Specfies whether the preview form should be a standalone top form. This will force a modeless (NOWAIT) preview session, and the toolbar is automatically docked at the top of the form. Default value is false (.F.).

TextOnToolbar

L

Specifies that the toolbar buttons should show text captions. Default value is false (.F.).

AllowPrintFromPreview

B

Specifies whether the Print button on the Preview tool bar or the Print command button on the short-cut menu is enabled for the Preview Container of the report listener object.

Methods

In addition to the methods specified by The Preview Container API , the default preview container also exposes all public methods of the base Form class.

The following additional methods can be called after the preview container is visible:

Method Description

SetCurrentPage( iPageNo )

Moves to a specific page number.

SetCanvasCount( iCount )

Adjusts the number of pages rendered on the preview form.

SetZoomLevel( iLevel )

Adjusts the scale of the rendered pages.

SetExtensionHandler( oRef )

Assigns an extension handler (See below)

The Extension Handler Interface

The default preview container has a specific mechanism that allows you to modify or extend the functionality of the preview user interface without subclassing or recompiling the source code.

You use SetExtensionHandler() to pass the default preview container a reference to an object that implements a specific set of "hook" methods that are invoked at specific points. See below for the API and sample usage.

Preview Extension Handler Properties

Property Description

PreviewForm

This is a back-reference to the preview form. If this property does not exist, it will be created by the default preview container via an ADDPROPERTY() call, and assigned a reference to the preview form. The preview container nulls out the back reference automatically before releasing to avoid an object reference loop that might prevent it from doing so.

Useful properties of .PreviewForm:

  • .PreviewForm.oReport references the active report listener

  • .PreviewForm.Toolbar references the preview form's toolbar object.

Preview Extension Handler Methods

These methods must be implemented by a candidate Extension Handler.

Method Description

AddBarsToMenu( cPopupName, iNextBarNum )

This method is called from the preview form's RightClick() event, directly prior to the ACTIVATE POPUP (m.cPopupName) statement, so you can potentially remove menu bars or redefine them.

cPopupName is the name of the popup.

iNextBarNum is the next available bar number.

Because you cannot use the THIS keyword in a popup ON SELECTION.. command, the preview form makes a reference to itself available in a variable oRef.

HandledKeyPress( nKey, nModifier )

This method is called from the preview form's Keypress() event. Return true (.T.) if you wish to replace the default response to a specific key press. This method is called before the preview form's native keypress handling, so you may override selected keypress events.

Show( iStyle )

This method is called from the preview form's Show() method. You will be able to manipulate the preview toolbar through the THIS.PreviewForm.Toolbar reference. The toolbar actually gets created in the preview form's Init() event but as the extension handled has not been assigned at that point, the Show() is the best place for configuration and decoration code.

Note that the toolbar itself also has a PreviewForm back-reference to the preview form, so you could add command buttons with Click() code like THIS.Parent.PreviewForm.ExtensionHandler.MyCustomMethod().

Paint()

Called from the preview form's Paint() event, after the preview has finished rendering the pages.

Release()

Called from the preview form's Release() event. Returning false (.F.) from this method will prevent the preview form from closing.

Example: Customizing the preview container using an Extension Handler

The following example customizes the appearance of the preview window and also implements an extension handler that removes the ability to change the number of pages rendered simultaneously on the preview form.

* Obtain an instance of the default preview container:
pc = .NULL.
DO (_REPORTPREVIEW) WITH pc

* Set some initial properties:
WITH pc
    .Caption = "My Custom Preview Window"
    .ZoomLevel = 4   && 75%
    .CanvasCount = 1
ENDWITH

* Create an instance of an Extension Handler:
xh = NEWOBJECT("MyRetroPreview")

* Assign it to the preview container:
pc.SetExtensionHandler( m.xh )

* Set up a report listener and give it our preview:
rl = NEWOBJECT("Reportlistener")
rl.ListenerType = 1
rl.PreviewContainer = pc

* Run a report:
REPORT FORM (_SAMPLES+"\solution\reports\colors.frx") OBJECT rl 
RETURN

*---------------------------------------------
* Extension Handler Class:
*---------------------------------------------
DEFINE CLASS MyRetroPreview AS Custom

    PROCEDURE AddBarsToMenu( cPopup, iNextBar )
        * Remove the option to change page count:
        RELEASE BAR 8 OF (m.cPopup)
    ENDPROC

    PROCEDURE Show( iStyle )
        * Remove the option to change page count:
        THIS.PreviewForm.Toolbar.opgPageCount.Visible = .F.
        THIS.PreviewForm.CanvasCount = 1
    ENDPROC

    PROCEDURE HandledKeyPress( nKeyCode, nShiftAltCtrl )
        RETURN .F.
    ENDPROC

    PROCEDURE Paint()
    ENDPROC

    PROCEDURE Release()
        RETURN .T.
    ENDPROC

ENDDEFINE

Use of the Resource File

The default preview container uses the current resource file (as returned by SET("RESOURCE",1) ) to remember the size, position, number of pages visible, zoom level, etc., for each report file.

The window and toolbar preferences are stored in the FOXUSER table with an ID of "9REPPREVIEW". Window and Toolbar position and size preferences are saved independently for each individual report file. The position and state of the preview toolbar is common to all report previews. If the resource file is not available, or read-only, then the window preferences are not saved.

See Also

Tasks

Creating a Custom Preview Container

Reference

SET REPORTBEHAVIOR Command
ReportListener Object

Concepts

Understanding Visual FoxPro Object-Assisted Reporting