ReportListener User Feedback Foundation Class
This class provides user-configurable feedback during the report runs. . The Report Output Application uses UpdateListener as its designated default ReportListener class for Print and Preview output (ListenerType values 0 and 1).
Category |
Reporting |
|---|---|
Default Catalog |
Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners |
Class |
UpdateListener |
Base Class |
ReportListener |
Class Library |
_REPORTLISTENER.vcx |
Parent Class |
_ReportListener (ReportListener Base Foundation Class) |
Remarks
UpdateListener's design has the following goals:
Ease of localization and customization. All the captions and messages UpdateListener displays during a report run, as well as the dimensions of its display window are exposed as public properties. UpdateListener dynamically validates any changes you make to its base configuration and adjusts its display elements to match.
Sophisticated feedback information about the report in progress. UpdateListener overrides the base ReportListener.UpdateStatus calls, which occur on each page, to display more finely-tuned information about report progress according to the report scope. Its feedback mechanism distinguishes between the initial calculation pass and the subsequent rendering pass, using the ReportListener.TwoPassProcess and ReportListener.CurrentPass properties. For more information, see ReportListener Object Properties, Methods, and Events.
Availability of report timing information. UpdateListener uses its reportStartRunDatetime and reportStopRunDatetime properties to display optional timing information during a report run, but you can also use them after the conclusion of the report run.
Ability to pause and continue report runs. UpdateListener handles Escape presses during report runs for this purpose during report runs. It saves and restores your keypress-handling code appropriately.
No dependencies on external classes. UpdateListener uses a single protected method, createTherm(), to create its feedback display window. There are no external library forms or classes; this class creates and configures the window entirely within the code of the createTherm() method.
Note
This design goal stems from Report Output Application's use of UpdateListener as the default ReportListener for the traditional output formats for reports and labels (Print and Preview). Your subclass can override createTherm() and adapt the DoStatus() method code that writes to it.
The following table lists public properties added by this class to its parent class, _ReportListener. UpdateListener adds no public methods.
Properties |
Description |
|---|---|
includeSeconds Property |
Indicates whether the default user feedback message should include timing data. Default .T. |
initStatusText Property |
Provides the user message shown when user feedback first appears. Default "Initializing... " Remarks: See REPORTLISTENERS_LOCS.H, which provides the localizable value to which this property is set in the class' Init method. |
prepassStatusText Property |
Provides a user feedback message for use when the report is in a pre-generation pass to calculate _PAGETOTAL. Default "Running calculation prepass... " Remarks: See REPORTLISTENERS_LOCS.H, which provides the localizable value to which this property is set in the class' Init method. |
reportStartRunDatetime Property |
A datetime value indicating when the last report generation run began. Default DTOT({}) |
reportStopRunDatetime Property |
A datetime value for use at the conclusion of a report run, empty during a report, storing when the last report generation run ended. Default DTOT({}) |
runStatusText Property |
Provides a user message shown during the course of a report run. Default "Creating output..." Remarks: See REPORTLISTENERS_LOCS.H, which provides the localizable value to which this property is set in the class' Init method. |
secondsText Property |
Provides the text message included to describe the time value in the default user feedback message during a report, when IncludeSeconds is .T. Default SPACE(1) + "secs " Remarks: See REPORTLISTENERS_LOCS.H, which provides the localizable value to which this property is set in the class' Init method. |
thermCaption Property |
Holds an evaluated expression for use in the user feedback message shown during a report run. If this expression includes "cMessage," the contents of the argument provided to DoStatus will be included in the result of the evaluation. This value overlays UpdateListener's progress bar. Default [cMessage+ " "+ TRANSFORM(INT(THIS.PercentDone*100)) + "%" + IIF(NOT THIS.IncludeSeconds, "" , " "+TRANSFORM(IIF(THIS.IsRunning,DATETIME(), THIS.ReportStopRunDateTime)-THIS.ReportStartRunDateTime)+" " + THIS.SecondsText)] Remarks: When you adjust this value, UpdateListener attempts to evaluate a result, including a "dummy" value for cMessage if necessary. If it cannot evaluate your result at the time you set the value of the property, it will retain the previous value. |
thermFormCaption Property |
Holds the value used to set the title of the user feedback form. Default "" Remarks: UpdateListener evaluates this value at the start of each report run. If you have set it to a non-empty value, UpdateListener does not adjust your setting. If you do not supply a value, UpdateListener sets the value using the ReportListener.PrintJobName property. If its PrintJobName property is empty, it uses ReportListener.CommandClauses.File, the name of the running report file, instead. To the resulting value it adds a localizable string, by default "Press Esc to cancel... ", to indicate the user's ability to pause or cancel the report with this keystroke. |
thermFormHeight Property |
Holds the height of the user feedback form, in pixels. Default 40 |
thermFormWidth Property |
Holds the width of the user feedback form, in pixels. Default 356 |
thermMargin Property |
Holds the value (in pixels) used to determine the difference between the size of the user feedback window and the thermometer bar it displays. Default 5 |
Example
The following example turns off the default feedback for an HTMLListener and chains it together with an UpdateListener for the same user feedback you would get for printing or previewing by default.
The code adjusts the feedback form's caption and instructs UpdateListener not to include seconds in the user feedback for this report. Then it briefly shows the feedback form, so you can check the results of these changes, using UpdateListener.initStatusText to supply a message.
The example code then runs a report, showing UpdateListener's feedback form to update the user about progress as the HTML file is generated.
After the report run, the code brings up the HTML file in a VisualFoxPro window for quick verification. It displays the timing results of the report run, leveraging _ReportListener's augmented version of the ReportListener.DoMessage method and HtmlListener.AppName to provide a title for the message window.
LOCAL oUpdate, oHtml
* create the ReportListeners:
oHtml = NEWOBJECT("HtmlListener","_REPORTLISTENER.VCX")
oUpdate = NEWOBJECT("UpdateListener","_REPORTLISTENER.VCX")
* customize them both:
oHtml.QuietMode = .T.
oUpdate.ThermFormCaption = "My Listener Demo"
oUpdate.IncludeSeconds = .F.
oUpdate.DoStatus(oUpdate.initStatusText)
WAIT WINDOW TIMEOUT 3 "Notice the window title... "
* make one the successor of the other:
oHtml.successor = oUpdate
* run the report:
REPORT FORM ? OBJECT oHtml
* show results:
MODIFY FILE (oHtml.TargetFileName) NOWAIT
oUpdate.DoMessage("Total Report Time: " + ;
TRANSFORM(oUpdate.reportStopRunDatetime - ;
oUpdate.reportStartRunDatetime) + ;
Update.secondsText,0,oHTML.appName )
See Also
Concepts
Guidelines for Using Visual FoxPro Foundation Classes
Reference
Visual FoxPro Foundation Classes A-Z