TXLeport Events

The pseudo-code below describes the algorithm of report generation:

When the process starts (Connect), the XL Report instance gets pointers to all Excel interfaces, opens the template workbook, and adds the XLRpt_TempSheet worksheet and the XLRpt_Module VBA module. Starting from this moment the following interfaces are accessible in XL Report event handlers: IXLSApp, IWorkbooks, IWorkbook, ITempSheet, INames and so on. If the xroRefreshParams option is on, the Params collection is refreshed. Then the OnBeforeBuild event is triggered. Here you can initialize report parameters and/or perform any operations before the datasets will be open. Then the VBA macro specified in the MacroBefore property is invoked. Just before this the OnMacro event is triggered in order to allow you to pass macro parameters. Then the template is analyzed, report parameters are transferred, NoRange-datasets are transferred, and standalone Range-datasets are transferred. Then comes the turn of nested Range-datasets. After data transfer the MacroAfter VBA macro is invoked being preceded with the OnMacro event. The report and sheet options are processed, and the AfterBuild event is triggered. Excel is shown and its interfaces are freed (Disconnect). In case of any exception, the OnError event is triggered thus allowing you to process the exception. Every step described above is preceded with the OnProgress event.

This is a standard event cycle for XL Report reporting. There are two events that can be triggered in following situations:

• OnTargetBookSheetName - an event triggered before a worksheet is added to the report workbook specified in the ReportTo method. You can change the name of the worksheet in corresponding event handler.
• OnBeforWorkbookSave - an event triggered before the report workbook is saved (if the xroAutoSave option is on). You can change the file and path name of the workbook or cancel saving.

OnAfterBuild

Is triggered after report generation.

Use the event handler in order to carry out some additional actions after report generation. All Excel interfaces are accessible here. See also the OnBeforeBuild event.

OnBeforeBuild

Is triggered before report generation.

Use the event handler in order to carry out some additional actions after report generation. All Excel interfaces are accessible here. Many XL Report users prepare template workbooks in this event. See also the OnAfterBuild event.

OnBeforeWorkbookSave

Is triggered in order to define the path and file name of the report workbook.

This event is triggered only if the xroAutoSave option is True. WorkbookName and WorkbookPath contain the path and file name of the report workbook. Both of them are not checked for existence. If the file exists an exception is fired. To save the report set Save = true, to prevent from saving set Save = false.

OnBreak

Allows canceling the report generation process.

Use this event in order to allow your users to cancel the report generation process. Set IsBreak to true if it is the case. Note. This event doesn't allow canceling long lasting VBA macros, in particular those specified in the MacroBefore and MacroAfter properties.

OnError

Is triggered in case of errors during report generation.

Use this event in order to override the standard exception processing behavior of XL Report. If IsRaised = false all the raised exceptions will be suppressed in the Report method. Default: IsRaised = true. Exception type can be determined by use of the Exception parameter and Is operator.

OnMacro

Is triggered before calling VBA procedures supplied in MacroBefore and MacroAfter properties.

Use this event if you need to pass some parameters to the VBA procedure. Assign the parameters' values to ArgXX in strict order, otherwise you get an exception. The DataSource parameter contains nil. If you make OnMacro event handler to be a common event handler for several instances of TxlReport class, you can use Tag property of the class and AMacroName - the name of the VBA procedure to be processed.

OnProgress

Accompanies every step of report generation.

Use this event to visualize report generation. Max contains the number of report generation steps. Position contains the number of the current step. Because template options are analyzed in consecutive order, so Max can be changed during report generation. After report generation, this event is triggered again with Position and Max both equal to zero. Example:

OnTargetBookSheetName

Is triggered in order to define the name of the worksheet being added to an existing workbook with the ReportTo method.

This event is triggered when the template worksheet is added to the target workbook . You can rename the worksheet by supplying the new name in the WorksheetName parameter. ISheet contains the interface to the worksheet, ITargetWorkbook contains the interface to the target workbook.