Setting up XFRX previewer

This section has been added to reflect changes in XFRX ver. 11.3. If you are using previous XFRX versions, please see Using XFCont class paragraph below in this chapter.

There are several ways how you can setup the XFRX previewer. You can either use the already prepared standalone previewing component or start with the basic classes of the previewer component to add the previewing capabilities to your own forms.

The following subchapters describe using three classes implemented in XFRXLIB.VCX which you can use as a starting point to implement the XFRX previewer in your application:


frmMPPreviewer

cntXFRXMultiPage

XFCont

Implemented as a form (the easiest setup)

Yes

No

No

Implemented as a container (can be embedded into existing forms)

No

Yes

Yes

supports multi-tab interface

Yes

Yes

No

supports embedded toolbar

Yes

Yes

No


  • XFCont is the basic XFRX previewer class. It is implemented as a container object and supports searching, hyperlinks, bookmarks, printing and exporting.
  • cntXFRXMultiPage class extends the XFCont class functionality with multi-tab interface – it can display multiple previewer tabs in a page frame class. It also supports a (fake) embedded toolbar, which is a toolbar-like control at the top of the container, which is very useful if the previewer form is not inside the main VFP screen.
  • frmMPPreviewer is a form class that implements cntXFRXMultiPage and serves as a “proxy” to the cntXFRXMultiPage class features. If all you need is a full screen report previewer, this one is the easiest to setup.


Default settings

A new objects-type property has been added to the XFCont, cntXFRXMultipage and frmMPPreviewer classes:

NameDescriptionXFRX
version 
cLanguageLanguage shortcut (csy, sk, de, fr, tr, it)
cImageFolder 

Folder with images for XFRX preview.

Subfolder 32x32 contains icons 32x32 px.
Subfolder 48x48 contains icons 48x48 px.
Subfolder 96x96 contains icons 96x96 px.

16.1.4 
oDisplayDefaultsDisplay default options.
oPrinterOptionsPrint default options.17.0.0
oExportOptionsExport default options.17.0.0
oEmailOptionsE-mail default options.17.0.0
lVFP8 Switch for backware compatibility with previous VFP versions in VFP 9.0. Default value is .F.  17.3.1
nDPIPreviewQualityDPI preview quality. Default value is 300.17.3.0
iOpen

Controls the visibility "Open" item in shortcut popup, button in toolbar and embedded toolbar. The allowed values are:
0 - hide (default value)
1 - show

Allowed extension are: tiff, xff, xml and pdf.

21.0.0
CSSUsers's CSS file for styling bookmark's and search's list.21.0.0
CSSBaseBase XFRX CSS file for styling bookmark's and search's list.21.0.0

Object oDisplayDefaults has the following properties:

NameTypeDescriptionXFRX
version 
StartingPageinteger The 1st page to show in the previewer. Default value is 1.
DefaultOutputFileNamestring The default output file name when exporting from the previewer.
PagesPerSheetstring Encoded pages per sheet layout value. Default value: 1x1.
Allowed values: 1x1, 2x1, 2x2, 3x1, 3x2, 4x2.

ZoomFactorinteger The zoom factor. default value = 100. -1 = fit to width, -2 = fit page.
The zoom factor will be used only of PagesPerSheet is 1x1, otherwise it defaults to -2.

FindColor 

integerBackground color  of searched text17.0.0 
aFindStringarrayA array contains strings for  highlight. The array  can has one column - than  background color will be yelow for all strings.
Or can has two columns - than second column contains background color for string.
19.0.0
nOutlineTypeintegerOutline type:
0 - Page and report bookmarks (hierarchy)
1 - Only bookmarks from report
2 - Only bookmarks to pages
3 - List page and report bookmarks
19.0.0
nOutlineEngineintegerOutline engine:
0 - Trying use IE, if failed, use listbox
1 - use IE always
2 - use listbox always
19.0.0

UnderlinehyperlinksOnPrint

 
 numberHyperlin decoration:

.NULL. - for backware compatiblity (default value)
0 - no decoration for hyperlinks
1 - display "normal" hyperlinks in blue, but do not decorate custom event hyperlinks (green)
2 - decorate both blue and green hyperlinks

19.1.0


Example:

m.loPreview = CREATEOBJECT("frmMPPreviewer")
m.loPreview.oDisplayDefaults.StartingPage = 2
m.loPreview.oDisplayDefaults.DefaultOutputFileName = "invoice15_09"
m.loPreview.oDisplayDefaults.ZoomFactor = -1
m.loPreview.oDisplayDefaults.PagesPerSheet = "1x1"
m.loPreview.lVFP8=.T. && don't use XFRX#LISTENER
m.loPreview.PreviewXFF(loXFF)
m.loPreview.show(1)

Common methods and properties

Even though you can use different classes to provide the previewing capabilities in your application, all classes share most of the properties and methods you can use to control and customize them.

Controlling multi-tab preview features

The properties and methods described in this paragraph are implemented in cntXFRXMultiPage and frmMPPreviewer classes. The multi-tab features are not implemented in XFCont class.

Property / Method

Usage

lShowTabForOneReport

(property)

Possible values:

  • .F. (default) – the tab with page captions is hidden if only one report is previewed. It will became automatically visible when the second report gets previewed.
  • .T. – the tab with page captions is always visible.

PreviewXFF

(method)

Syntax:

PreviewXFF(toXFF, tcCaption, tnPageNo)

Call this method to preview the XFF file in the previewer. You can call this method multiple times, which would either add new reports as new pages or replace existing pages, depending on parameters.

Parameters:

   toXFF

    The reference of a XFF file that is going to be previewed 

  tcCaption (optional)

The caption of the page with this report if previewing multiple reports. 

  tnPageNo(optional)

    The page on which the XFF file is going to be previewed. If this parameter is empty or greater than the number of existing pages, a new page is added. If a page with this number already exists, it will be replaced.

RemovePage

(method)

Syntax:

RemovePage(tnPageNo)

Removes a page from the previewer. 

Parameters:

  tnPageNo (optional)

    The number of the page to remove. If the parameter is empty or the number is greater than the number of existing pages, the last one is removed.

Registering an extension handler

The extension handler allows for extending the functionality of the basic classes without need of creating subclasses. All you need is to create a custom class, which implements certain methods. The custom class is registered with the XFRX previewer class (using SetExtensionHandler method) and the previewer calls the extension methods on appropriate events.

Currently supported event methods are:

Method

Usage

 XFRX
version
KeyPress

This method is called from KeyPress() method of xfcont class.

Parameters:

   toXFF – the handler of the XFF file that is being previewed
   nKeyCode – Contains a number that identifies the key pressed
   nShiftAltCtrl - Sets a particular bit if a modifier key is held down while pressing the key specified by nKeyCode



ToolbarOnInit  

This method is called from ShowToolbar() method of xfcont class. 

Parameters:

   toToolbar – object reference to embeded toolbar


EmbeddedToolbarOnInit

This method is called from PreviewXFF() method of cntXFRXMultiPage class. 

Parameters:

   toToolbar – object reference to embeded toolbar

19.1.0

StatusbarOnInit 

This method is called from LastInited() method of xfcont class. 

Parameters:

   toXFF – the handler of the XFF file that is being previewed
   toToolbar – object reference to embeded toolbar

19.1.0
BeforeRenderPage

This method is called before rendering page of xfcont class.

Parameters:

   m.loXFCont - the handler of the XFCont class.
   m.loXFF - the handler of the XFF file that is being previewed
   m.liPage - Page number
   m.lnDPIPreviewQuality -  DPI preview quality
   m.laFindString - A array contains strings for   highlight  (background color yelow).

21.0.0
AfterRenderPage

This method is called after rendering page of xfcont class.

Parameters:

   m.loXFCont - the handler of the XFCont class.
   m.loXFF - the handler of the XFF file that is being previewed
   m.liPage - Page number
   m.lnDPIPreviewQuality -  DPI preview quality
   m.laFindString - A array contains strings for   highlight  (background color yelow).
   m.liEMFHadle - EMF GDI+ handle 

21.0.0
KeyPress example
USE demoreps\invoices ORDER customer
LOCAL m.loSession, m.lnRetval, m.loXFF, m.loPreview, m.loScripts
m.loSession=EVALUATE([xfrx("XFRX#LISTENER")])
m.lnRetVal = m.loSession.SetParams(,,,,,,"XFF") && no name = just in memory
IF m.lnRetVal = 0
   REPORT FORM demoreps\invoices OBJECT m.loSession
   *
   * the XFRX#DRAW object reference is stored in oxfDocument property
   *
   m.loXFF = m.loSession.oxfDocument
   *
   * initialize the previewer 
   *
   SET PATH TO xfrxlib
   SET CLASSLIB TO xfrxlib ADDITIVE 
   m.loPreview = CREATEOBJECT("frmMPPreviewer")
   *
   * setup the extension handler
   *
   m.loPreview.oExtensionHandler = CREATEOBJECT("SampleExtensionHandler")
   m.loPreview.windowtype = 1 
   m.loPreview.iTool = 2 && embedded toolbar
   m.loPreview.PreviewXFF(loXFF)
   m.loPreview.show(1)
ENDIF

DEFINE CLASS SampleExtensionHandler AS CUSTOM

   PROCEDURE KeyPress(m.loXFCont, m.nKeyCode, m.nShiftAltCtrl)
      * hotkey for print P (112-p, 80-P)
      IF INLIST(m.nKeyCode, 112, 80)
         m.loXFCont.Print()
      ENDIF
   ENDPROC
ENDDEFINE 

Showing / hiding left panel (bookmarks)

The left panel behavior is controlled by the iBook property:

Property

Usage

iBook

Controls if the left panel should be displayed in the previewer. The allowed values are:

  • -1 = Hide left panel
  • 0 = Show left panel in minimize mode
  • 1 = Show left panel with bookmark list
  • 2 = Show left panel with bookmark list if bookmarks defined in the report, otherwise show left panel in minimize mode (default)

Showing / hiding previewer toolbars

There are two toolbars in the previewer control – one is placed at the bottom of the control, the other one is available as a floating toolbar panel, which by default docks at the top of the main window, or, alternatively, as an “embedded toolbar”. All three classes implement iTool and ShowStatus properties that control visibility of the toolbars:

Property

Usage

 XFRX version

classMainToolbar

The class name of the toolbar. The default value is “xfrxToolbar”. You can create a child of the default xfrxToolbar class (defined in xfrxlib.vcx) and use this property to instruct the previewer to use your class rather than the default one.

This property works for the “real” toolbar – if iTool property is 0 or 1. if iTool is set to 2, cmdEmbeddedToolbar container class is used as the “embedded” toolbar.

Class xfrxToolbar32 is for icons 32x32 px.
Class xfrxToolbar48 is for icons 48x48 px.
Class xfrxToolbar96 is for icons 96x96 px.


ClassMainStatusBar

The class name of the status bar or embdded toolbar. The default value is “cntembeddedtoolbar”. You can create a child of the default cntembeddedtoolbarr class (defined in xfrxlib.vcx) and use this property to instruct the previewer to use your class rather than the default one.

Class cntembeddedtoolbar32 is for icons 32x32 px.
Class cntembeddedtoolbar48 is for icons 48x48 px.
Class cntembeddedtoolbar96 is for icons 96x96 px.

17.3 

iTool

Controls the visibility of the toolbar at the top. The allowed values are:

  • -1 = Disable toolbar
  • 0 = The toolbar will be enabled but hidden. It can be invoked via right click shortcut menu
  • 1 = The toolbar will be enabled and visible. (default)
  • 2 = The toolbar will be displayed as embedded to the form (available only in cntXFRXMultiPage and frmMPPreviewer classes.


ShowStatus

Controls the visibility of the toolbar at the status bar of the previewer container. The allowed values are:

  • .T. = show the toolbar (default)
  • .F. = hide the toolbar

Displaying progress bar 


PropertyUsage
oprogressThe object instance of XFRX progress bar
USE demoreps\invoices ORDER customer
LOCAL m.loSession, m.lnRetval, m.loXFF, m.loPreview, m.loScripts
m.loSession=EVALUATE([xfrx("XFRX#LISTENER")])
m.lnRetVal = m.loSession.SetParams(,,,,,,"XFF") && no name = just in memory
IF m.lnRetVal = 0
   REPORT FORM demoreps\invoices OBJECT m.loSession
   *
   * the XFRX#DRAW object reference is stored in oxfDocument property
   *
   m.loXFF = m.loSession.oxfDocument
   *
   * initialize the previewer 
   *
   SET PATH TO xfrxlib
   SET CLASSLIB TO xfrxlib ADDITIVE 
   m.loPreview = CREATEOBJECT("frmMPPreviewer")
   *
   * setup the extension handler
   *
   m.loPreview.oExtensionHandler = CREATEOBJECT("SampleExtensionHandler")
   m.loPreview.oprogress=createobject("progress")
   m.loPreview.PreviewXFF(loXFF)
   m.loPreview.show(1)
ENDIF

DEFINE CLASS progress AS CUSTOM
   PROCEURE updateProgress
      LPARAM m.ta,m.tb, m.tc
      WAIT WINDOW NOWAIT "Page #: "+ALLT(STR(m.tb))+" Report #: "+ALLT(STR(m.ta))+" ("+ALLT(STR(m.tc))+"%)"
   ENDPROC
ENDDEF


Using frmMPPreviewer class

This class serves as a standalone (fullscreen) previewer window. All you need to do to make it work is to pass it a reference to the XFF file to preview, using the previewXFF method, as described in Controlling multi-tab preview features paragraph above. (If you are not sure how to create a XFF file reference, please read chapters 17.0: Initializing the XFRX#DRAW class instance and 16.3: Creating temporary XFF files). Here is a very simple “Hello World” example:

LOCAL m.loPreview
SET CLASSLIB TO XFRXLIB.VCX ADDITIVE 
m.loPreview = CREATEOBJECT("frmMPPreviewer") && create the previewer object
m.loPreview.previewXFF(m.loXFF)              && loXFF is XFF file reference
m.loPreview.show(1)                          && show the form as modal

Make sure to set all properties (like iTool, ShowStatus, etc.) before you call PreviewXFF(…) otherwise they won’t be used.

Using cntXFRXMultiPage class

  1. Add an instance of cntXFRXMultiPage class (of XFRXLIB.VCX) into your form. Adjust the size of the cntXFRXMultiPage class object container as you need. The previewer, including the status bar, icons and scroll bars will be displayed in the container. If you resize the container in runtime, its content is automatically adjusted.
  2. When the form is about to be released, the cntXFRXMultiPage class instance needs to do some cleanup. To enable that please call the class instance’s clearLink() method from form’s destroy method:

    PROCEDURE Destroy
       Thisform.cntXFRX.clearLink()
    ENDPROC
  3. When running the form, make sure the XFRXLIB.VCX class library is referenced in SET CLASSLIB command:

    SET CLASSLIB TO XFRXLIB.VCX ADDITIVE
  4. Call the PreviewXFF method to preview a XFF file, as described in Controlling multi-tab preview features paragraph above.
  5. By default, cntXFRXMultiPage is using an instance of the XFCont class for each page. Should you like to make it use a different class (eg. a subclass of XFCont) put the class name to the ClassPreviewPage property of the cntXFRXMultiPage instance.


Using XFCont class

  1. Add an instance of XFCONT class (of XFRXLIB.VCX) into your form. Adjust the size of the XFCONT class container as you need. The previewer, including the status bar, icons and scroll bars will be displayed in the container. If you resize the container in runtime, its content is automatically adjusted.

  2. When the form is about to be released, the XFCONT class instance needs to do some cleanup. To enable that please call the XFCont class instance’s clearLink() method from form’s destroy method:

    PROCEDURE

    PROCEDURE Destroy Thisform.cntXFRX.clearLink() ENDPROC
  3. When running the form, make sure the XFRXLIB.VCX class library is referenced in SET CLASSLIB command:

    SET CLASSLIB TO XFRXLIB.VCX ADDITIVE

VFP 8.0 approach

In VFP 8.0, there are two options how to preview report in the previewer. The options differ in the calling mechanism, although internally they both work exactly the same.

Generating the “CNT” output type

The approach is using the standard syntax of calling XFRX, without explicitly using the XFRX#DRAW class (although it is used in the background). You cannot open an existing XFF file with this approach – you always need to run a report that will be previewed.

  1. Do not send anything as the output file name

  2. Use “CNT” as the output type parameter in the SetParams method call

  3. Call Reset method of the previewer container class

  4. Call SetOtherParams method of the XFRXSession class instance with the reference of XFCont instance as a parameter


Example:

LOCAL m.loSession, m.lnRetval 
loSession= xfrx("XFRX#INIT") 
m.lnRetVal = m.loSession.SetParams(,,,,,,"CNT") 
IF m.lnRetVal = 0 
   * * we are assuming the XFCont container is 
   * available as thisform.cntXFRX 
   * Thisform.cntXFRX.reset() 
   m.loSession.setotherparams(Thisform.cntXFRX) 
   m.loSession.ProcessReport("report") 
   m.loSession.finalize() 
ENDIF

Using the XFRX#DRAW class

The advantage of this method is that you can preview an existing XFF file – the XFF file is opened and “converted” to “CNT” output type via the TransformReport method:

Example:

LOCAL m.loSession 
m.loSession= xfrx("XFRX#INIT") 
Thisform.oReport = xfrx("XFRX#DRAW") 
IF Thisform.oReport.openDocument("file.xff") 
   Thisform.cntXFRX.reset() 
   m.lnRetVal = m.loSession.SetParams(,,,,,,"CNT") 
   IF m.lnRetVal = 0 
      m.loSession.setOtherParams(Thisform.cntXFRX) 
      m.loSession.TransformReport(Thisform.oReport) 
   ENDIF 
ENDIF

VFP 9.0 Approach

In VFP 9.0 the logic is the same, just the syntax is a little bit different – the reference to the XFCont object is copied to XFRXPreviewer property of the XFRXListener class instance and then previewReport method with the XFRX#DRAW reference as parameter is called:

LOCAL m.loSession
m.loSession= xfrx("XFRX#LISTENER")
Thisform.oReport = xfrx("XFRX#DRAW")
IF Thisform.oReport.openDocument("file.xff")
   Thisform.cntXFRX.reset()
   m.loSession.XFRXPreviewer = Thisform.cntXFRX
   m.loSession.previewReport(Thisform.oReport)
ENDIF

Hyperlink decoration

A new property has been added to the XFCont, cntXFRXMultipage and frmMPPreviewer classes: UnderlineHyperlinksOnPrint. You can use the following values:
0 - no decoration for hyperlinks
1 - display "normal" hyperlinks in blue, but do not decorate custom event hyperlinks (green)
2 - (default value) decorate both blue and green hyperlinks

To support this in the print output, the PrintDocument method of the XFRX#DRAW class has a new parameter, tnUnderlineHyperlinksOnPrint, with the same values and logic.


Custom buttons

This feature is implemented using the extension handler mechanism: A new method is now supported - ToolbarOnInit, which is invoked at the time the toolbar is initialized. In this method the extension handler can add new buttons to the previewer and their click events can be bound with other methods in the extension handler. A new property is now supported, too - oPreviewContainer. If it is available, the previewer will automatically fill it with the XFCont object reference for easier access to the previewer properties in the custom buttons click event methods.

Example:


USE demoreps\sales
LOCAL m.loSession, m.lnRetval, m.loXFF, m.loPreview, m.loScripts
m.loSession=EVALUATE([xfrx("XFRX#LISTENER")])
m.lnRetVal = m.loSession.SetParams(,,,,,,"XFF") && no name = just in memory
IF m.lnRetVal = 0
   REPORT FORM demoreps\sales OBJECT m.loSession
   *
   * the XFRX#DRAW object reference is stored in oxfDocument property
   *
   m.loXFF = m.loSession.oxfDocument
   *
   * initialize the previewer
   *
   SET PATH TO xfrxlib
   SET CLASSLIB TO xfrxlib ADDITIVE
   m.loPreview = CREATEOBJECT("frmMPPreviewer")
   *
   * setup the extension handler
   *
   m.loPreview.oExtensionHandler = CREATEOBJECT("SampleExtensionHandler")
   m.loPreview.windowtype = 1
   m.loPreview.iTool = 2 && embedded toolbar
   *m.loPreview.iTool = 1 && standard toolbar
   m.loPreview.PreviewXFF(m.loXFF)
   m.loPreview.show(1)
ENDIF
 
DEFINE CLASS SampleExtensionHandler AS CUSTOM
 
   oPreviewContainer = .NULL.
 
   PROCEDURE ToolbarOnInit
      LPARAMETERS m.toToolbar
      LOCAL m.button
      IF m.toToolbar.AddObject("mybutton", "commandbutton")
         BINDEVENT(m.toToolbar.mybutton, "click" , This, "ButtonClicked")                       
         m.toToolbar.mybutton.tabindex = 1
         m.toToolbar.mybutton.Visible = .t.
         IF UPPER(m.totoolbar.BaseClass)!="TOOLBAR"
            m.toToolbar.mybutton.left = m.toToolbar.cmdQuit.left
            m.toToolbar.cmdQuit.left = m.toToolbar.mybutton.left + m.toToolbar.mybutton.width
         ENDIF                           
      ENDIF
   ENDPROC
 
   PROCEDURE ButtonClicked
      LOCAL m.lcString
      m.lcString = "This.oPreviewContainer.Name: "+This.oPreviewContainer.Name+CHR(13)
      m.lcString = m.lcString + "current page: "+TRANSFORM(This.oPreviewContainer.nPageNo)+CHR(13)
      m.lcString = m.lcString + "XFRX#DRAW Object: "+This.oPreviewContainer.oXFRXWriter.Name+CHR(13)
      m.lcString = m.lcString + "Page count: "+TRANSFORM(This.oPreviewContainer.oXFRXWriter.PageCount)+CHR(13)
      WAIT WINDOW m.lcString
   
      *This.oPreviewContainer.oXFRXWriter.PrintDocument(...)
      *This.oPreviewContainer.oXFRXWriter.SavePicture(...)
   ENDPROC

ENDDEFINE