ReportListener Decorator Foundation Class (TMM)

FXListener is a host class for the FX reporting subsystem. It provides a place for you to put extension-producing helper objects.

When designing report output extensions, it is important to distinguish between your opportunities to embellish multiple types of output with new content from your ability to create new output types using reportlisteners. 

New output types are typically created by deriving classes from the base class ReportListener, since only a ReportListener-derived object can receive messages from the VFP Report Engine.

Decorations of report content, on the other hand, generally do not have to be implemented directly in a reportlistener object and in general should not be. Attaching this type of code directly to a reportlistener limits your ability to share the decoration with multiple forms of output.


The Render method is critical to the actual display of any layout element. If any GFXs are loaded, FXListener loads its FFCGraphics member object with a GDIPlus handle to the current page before processing the GFXs during the Render event, so that individual GFX objects don't have to create their own.   Note that it loads a reference to an instance of the gpGraphics class from the _GDIPLUS.VCX library into its FFCGraphics member object by default.  You can supply a reference to any gpGraphics-derived class that you prefer.

FXListener also pays attention to the return value of the ApplyFX method, as it iterates through the GFXs collection, during the Render method; this is the only event for which the return value of the ApplyFX method is significant.   Because there is no guarantee of collection order, by convention the highest value returned by any GFX object in the set is applied. (This strategy is repeated in the approach used by FX and GFX objects in deciding what value to assign to CallEvaluateContents and CallAdjustObjectSize; when participants in the report run have an opportunity to "cast a vote" on invocation of a dynamic method, they should only move the value up, not down, lest they impair some other object's ability to work.)

The allowable values are #DEFINEd in REPORTLISTENERS.H, as follows:

#DEFINE OUTPUTFX_BASERENDER_AFTERRESTORE 0 
#DEFINE OUTPUTFX_BASERENDER_RENDER_BEFORE_RESTORE 1 
#DEFINE OUTPUTFX_BASERENDER_NORENDER 2 
#DEFINE OUTPUTFX_BASERENDER_RENDERXBASEONLY 3 

*&* The following two values may not have any 
*&* practical use, because Xbase listeners may not 
*&* have any practical way of making this distinction, 
*&* so the previous value should be used for now. 
*&* They are designated here for completeness: 
#DEFINE OUTPUTFX_BASERENDER_RENDERXBASEONLY_AFTER 4 
#DEFINE OUTPUTFX_BASERENDER_RENDERXBASEONLY_BEFORE 5 

#DEFINE OUTPUTFX_DEFAULT_RENDER_BEHAVIOR OUTPUTFX_BASERENDER_AFTERRESTORE             
            

FXListener does more than providing the necessary framework for the FX subsystem; it also implements some concrete examples of FX subsystem functionality.

While the SP2 CHM entry indicates that you will not instantiate this class directly, there are extremely good reasons to do so.  In fact, every time you SET REPORTBEHAVIOR 90  and instantiate a print or preview listener, the SP2 Report Output Application provides an instance of FXListener. This ensures availability of extension behavior, regardless of the base or extension output type you need for a report run.

Because the Report Output Application makes FXListener responsible for in-the-box implementation of print and preview behavior in SP2, FXListener undertakes to guarantee the availability certain FX and GFX implementations required for in-the-box behavior.  It unilaterally adds them to its collections if they are required for a report run. These implementations are:

• a Feedback FX object
• a MemberData Script processing FX object
• a Rotate processing GFX object
• a Render-suppression GFX object

While it undertakes to guarantee these features,  and while there are  default implementations of each in its class library, FXListener does not "own" the implementations.  It provides matching Class, ClassLib, and Module properties to allow you to specify the implementations you prefer. 


The Feedback FX object, fxTherm, provides the means for FXListener to take over the responsibilities of UpdateListener for user feedback during report processing.  FxTherm's code is almost entirely extracted from UpdateListener's code (as emended and improved for SP1 and SP2). Its development served as proof of concept that almost any type of report decoration, even one innately tied to many reporting events, as UpdateListener's display is, could be easily ported into an FX or GFX object rather than handled directly in a reportlistener-derived class.  It also serves to show how an object derived from any baseclass (in this case, a form) can implement the FX API  and participate in the FX reporting subsystem.

Along with its FFCGraphics member FXListener also offers some other common behavior to be shared across multiple effects:

• an instance of FRXCursor available to all,
• an open Memberdata cursor, which it requests from FRXCursor, and an exposed memberDataAlias property, from which all objects can extract whatever extension intelligence they require, 
• a runCollectorResetLevel property which, while not used by FXListener itself, exposes the new runCollector feature  to be  shared by all run participants. 

Please refer to   the whitepaper Data Visualization in Reports with VFP 9.0 SP2 for appropriate examples of FXListener's public methods, such as AddCollectionMember and RemoveCollectionMember, instructions on how to make FX and GFX objects available to the default reportlisteners, etc. The Examples section of the TMM docoid on the GFXExample class also has some notes about using AddCollectionMember and RemoveCollectionMember.

The following code excerpt shows how XMLListener checks the runCollectorResetLevel property at the conclusion of a report run, to decide whether it is time to reset the contents of the repository.  This evaluation takes into consideration whether the document being prepared is part of a chained report run that is not yet complete.