ReportListener User Feedback Foundation Class

Articolo
07/09/2007

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.PercentDone100)) + "%" + 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 )

ReportListener User Feedback Foundation Class

Remarks

Example

See Also

Reference

Concepts

Risorse aggiuntive