Setting up the XFRX previewer

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:

• 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:

Object oDisplayDefaults has the following properties:

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.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

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:

USE 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 invoices OBJECT m.loSession
             
   m.loXFF = m.loSession.oxfDocument
   *
   * initialize the previewer
   *
   SET CLASSLIB TO xfrxlib ADDITIVE
   m.loPreview = CREATEOBJECT("frmMPPreviewer")
   m.loPreview.setExtensionHandler(CREATEOBJECT("MyExtensionHandler"))
   m.loPreview.windowType = 0
   m.loPreview.iBook = 0
   m.loPreview.PreviewXFF(loXFF)
   m.loPreview.show(1)
ENDIF
 
 
DEFINE CLASS MyExtensionHandler AS Custom
 
   PROCEDURE Export
      LPARAMETERS m.toXFF
      IF USED("_xfExportTypes")
         USE IN _xfExportTypes
      ENDIF
      *
      * define my export options list
      *
      CREATE CURSOR _xfExportTypes (name C(50), extension C(4), targetCode C(10))
      INSERT INTO _xfExportTypes VALUES ("HTML",  "html",  "HTML")
      INSERT INTO _xfExportTypes VALUES ("PDF",   "pdf",   "PDF")
      INSERT INTO _xfExportTypes VALUES ("Excel", "xls",   "XLS")
   ENDPROC
 
   PROCEDURE ExportOptions
      LPARAMETERS m.toXFF, m.toOptions
      IF m.toOptions.cTarget = "XLS"
         *
         * my own code to handle output to Excel
         *
         =MESSAGEBOX("exporting to "+m.toOptions.cOutputFile)
         RETURN .F.   && suppress the default behavior
      ELSE
         RETURN .T.   && continue with the default behavior
      ENDIF
 
  ENDPROC

ENDDEFINE

SET PATH TO xfrxlib
SET CLASSLIB TO xfrxlib
 
LOCAL m.loPreview, m.loSession, m.loExtensionHandler
 
m.loExtensionHandler = CREATEOBJECT("myExtensionHandler")
 
m.loPreview = CREATEOBJECT("frmMPPreviewer")
m.loSession=EVALUATE([xfrx("XFRX#LISTENER")])
 
*
* create a memory XFF file
*
m.lnRetVal = m.loSession.SetParams(,,,,,,"XFF")
IF m.lnRetVal = 0
   SELECT * ;
     FROM customers INNER JOIN orders ON customers.customerid = orders.customerid ;
                    INNER JOIN orderdetails ON orders.orderid = orderdetails.orderid ;
     orderORDER byBY customers.companyname, customers.customerID, orders.orderID ;
     INTO CURSOR custlist
           
   REPORT FORM custlist OBJECT loSession
ENDIF
 
*
* assign the extension handler
*
m.loPreview.setExtensionHandler(loExtensionHandler)
*
* preview the report
*
m.loPreview.previewXFF(m.loSession.oxfdocument)
m.loPreview.show(1)
 
DEFINE CLASS myExtensionHandler asAS CustomCUSTOM
   PROCEDURE Print
      LPARAMETERS m.toXFF
      RETURN .t. && continue with the default behavior
   ENDPROC
 
   PROCEDURE Export
      LPARAMETERS m.toXFF
      *
      * now you can process the XFF file
      *
      RETURN .F. && override the default behavior
   ENDPROC
ENDDEFINE

useUSE demoreps\invoices orderORDER customer
localLOCAL 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
IfIF 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(m.loXFF)
   m.loPreview.show(1)
ENDIF

DEFINE CLASS SampleExtensionHandler as Custom

   PROCEDURE BeforeExport
      LPARAMETERS m.toSession, m.toExportParameters

      m.toSession.setAuthor("Martin") && set the document author property
      IF m.toExportParameters.cTarget = "XLS" && (XLS or XLSPLAIN)
	 
         m.toSession.SetOtherParams("DISPLAY_GRID_LINES",.F.) && do not display gridlines in excel
      ENDIF
   ENDPROC


   PROCEDURE AfterExport
      LPARAMETERS m.toSession, m.toOptions
      IF m.toOptions.cTarget = "XLS"
         *COPY FILE (m.toOptions.coutputfile) TO ([anybackupfolder]\[anyfile.xls])
      ENDIF
   ENDPROC
	

ENDDEFINE 

useUSE demoreps\invoices orderORDER customer
localLOCAL 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
IfIF m.lnRetVal = 0
   REPORT FORM demoreps\invoices objectOBJECT 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 asAS CustomCUSTOM

   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 bookmarks

The bookmark panel behavior is controlled by the iBook property:

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:

Displaying progress bar 

useUSE demoreps\invoices orderORDER customer
localLOCAL 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
IfIF m.lnRetVal = 0
   REPORT FORM demoreps\invoices objectOBJECT 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

defineDEFINE classCLASS progress asAS customCUSTOM
   procedurePROCEURE updateProgress
      lparaLPARAM m.ta,m.tb, m.tc
      waitWAIT windowWINDOW nowaitNOWAIT "Page #: "+alltALLT(strSTR(m.tb))+" Report #: "+alltALLT(strSTR(m.ta))+" ("+alltALLT(strSTR(m.tc))+"%)"
   ENDPROC
enddefENDDEF

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
toViewer
m.loPreview.previewXFF(m.loXFF)                 && loXFF is XFF file reference
m.loPreview.show(1)                          && show the form as modal

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:

   Code Block
   linenumbers true
   procedurePROCEDURE Destroy thisformThisform.cntXFRX.clearLink() endprocENDPROC

   
   

3. When running the form, make sure the XFRXLIB.VCX class library is referenced in SET CLASSLIB command:

   Code Block
   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

   Code Block
   linenumbers	true
   PROCEDURE Destroy thisformThisform.cntXFRX.clearLink() endproc ENDPROC

   
   

3. When running the form, make sure the XFRXLIB.VCX class library is referenced in SET CLASSLIB command:

   Code Block
   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.

15.1.5.1.1 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:

localLOCAL 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
   *
   thisformThisform.cntXFRX.reset()
   m.loSession.setotherparams(thisformThisform.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")
loReportThisform.oReport = xfrx("XFRX#DRAW")
IF thisformThisform.oReport.openDocument("file.xff")
   thisformThisform.cntXFRX.reset()
   m.lnRetVal = m.loSession.SetParams(,,,,,,"CNT")
   IF m.lnRetVal = 0
      m.loSession.setOtherParams(thisformThisform.cntXFRX)
      m.loSession.TransformReport(thisformThisform.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")
thisformThisform.oReport = xfrx("XFRX#DRAW")
IF thisformThisform.oReport.openDocument("file.xff")
   thisformThisform.cntXFRX.reset()
   m.loSession.XFRXPreviewer = thisformThisform.cntXFRX
   m.loSession.previewReport(thisformThisform.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:

useUSE demoreps\sales
localLOCAL 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 objectOBJECT 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 asAS CustomCUSTOM
 
   oPreviewContainer = null.NULL.
 
   PROCEDURE ToolbarOnInit
      LPARAMETERS m.toToolbar
      LOCAL m.button
      IF m.toToolbar.AddObject("mybutton", "commandbutton")
         BINDEVENT(m.toToolbar.mybutton, "click" , thisThis, "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 = "thisThis.oPreviewContainer.Name: "+thisThis.oPreviewContainer.Name+CHR(13)
      m.lcString = m.lcString + "current page: "+TRANSFORM(thisThis.oPreviewContainer.nPageNo)+CHR(13)
      m.lcString = m.lcString + "XFRX#DRAW Object: "+thisThis.oPreviewContainer.oXFRXWriter.Name+CHR(13)
      m.lcString = m.lcString + "Page count: "+TRANSFORM(thisThis.oPreviewContainer.oXFRXWriter.PageCount)+CHR(13)
      WAIT WINDOW m.lcString
   
*      this*This.oPreviewContainer.oXFRXWriter.PrintDocument(...)
*      this*This.oPreviewContainer.oXFRXWriter.SavePicture(...)
   ENDPROC

ENDDEFINE

Printing from the previewer

By default, when users click the “Print” button in the previewer toolbar (), the Print method of the XFCont class is called. This method displays a dialog box with a printer selection and allows for entering a page range:

When a XFF file is previewed, the corresponding XFRX#DRAW reference is accessible via oXFRXWriter property of the previewer class instance.

If you would like to change the way the previewer reacts to the print event, you can either setup an extension handler (please see Registering an extension handler paragraph above in this chapter for more information) . There are three events that extension handler can implement:

The print parameter object has the following methods:

The print parameter object has the following properties:

See also: Printing XFF files chapter on page 46 for more information about printing the content of XFF files.

Exporting reports from the previewer

Similarly to printing, when users click the “Export” button in the previewer toolbar (), the Export method of the XFCont class is called. This method displays a dialog box with output type and a file name selection and converts the XFF file that is being previewed to the output document:

If you would like to create your own custom exporting solution, you can either setup an extension handler (please see Registering an extension handler paragraph above in this chapter for more information) or you can create a child of the XFCont class and override the Export method.  There are five events that extension handler can implement:

The export parameter object has the following properties:

E-mail support in the XFRX previewer

An email icon has been added to the XFRX previewer toolbar. It is disabled by default for backward compatibility and can be enabled by setting the iEmail property of the previewer class [xfCont, cntXFRXMultiPage or frmMPPreviewer] to 1. If you click the email icon, it runs the Email method of the xfCont class. By default it displays a simple dialog box asking for email address, subject, body, etc. and uses VFPWinsock library to send the email.

Following are sample of the two most common scenarios:

Suppress the default behavior and handle the email event on your own

LOCAL m.loPreview
m.loPreview = CREATEOBJECT("frmMPPreviewer")
m.loPreview.iEmail = 1 && show the email icon
m.loPreview.oExtensionHandler = CREATEOBJECT("SampleExtensionHandler")
m.loPreview.PreviewXFF(LOCAL m.loXFF) && preview the document 
m.loPreview.show(1)
 
DEFINE CLASS SampleExtensionHandler asAS CustomCUSTOM
 
   PROCEDURE Email
      LPARAMETERS  m.loXFF[, [m.opt[, m.oProgress]]
      * loXFF - XFF file reference
      * m.opt - email options (since XFRX 17.0.0)
      * m.oProgress - XFRX progress object (since XFRX 17.0.0)
      LOCAL m.loSession, m.lcFileName
      m.loSession=EVALUATE([xfrx("XFRX#INIT")])
      m.lcFileName = Addbs(Sys(2023))+"test.pdf" && temporary file name
      IF m.loSession.SetParams(m.lcFileName,,.T.,,,,"PDF") = 0 && the 3rd parameter says we do not want to preview the PDF
         m.loSession.TransformReport(m.loXFF)
      
         LOCAL m.sm
         SET PROCEDURE TO vfpwinsock ADDITIVE 
         m.sm = Createobject("vfp_winsock_send_mail")
         m.sm.smtp_host = "your.smtp.server.here" &&&<<<<<<<<<<<<<<<<<<<< put your smtp server here
         m.sm.From = "eqeus@eqeus.com" 
         m.sm.To = "eqeus@eqeus.com"
         m.sm.subject = "Email test"
         m.sm.silence = .T.
         m.sm.attaCHMENT = m.lcFileName
         IF !m.sm.Send()
            =MESSAGEBOX(m.sm.erreur,16,"xfrx test")
         ELSE
            =MESSAGEBOX("Message was sent",0,"xfrx test")
            ERASE (m.lcFileName)
         ENDIF
      ENDIF 
      RETURN .F.
   ENDPROC
 
ENDDEFINE

DEFINE CLASS SampleExtensionHandler asAS CustomCUSTOM
 
   PROCEDURE EmailOptions
      LPARAMETERS  m.loXFF, m.loOptions
      m.loOptions.cSMTP_HOST = "mail.your_domain.com"
      m.loOptions.cFrom = "eqeus@eqeus.com"
   ENDPROC
 
ENDDEFINE

thisThis.cntXFRX.setLanguage("DE")

=m.loPreview.setLogFile(<tcLogFile>)