Interface Elements for Desktop > Report Designer > Report Designer for WinForms > Create Reports > Miscellaneous Report Management Capabilities > Handle Events via Scripts
This document describes the basic principles of scripting, which can be performed by handling the events of a report, and its bands and controls.
This documents consists of the following sections.
Scripting Overview
Scripts are program commands, placed within the event handlers of the required report elements. And, when the corresponding event occurs (e.g. a mouse click), the script code runs.
You can write scripts for a report or any of its elements (bands and controls), to be executed when the report is being previewed, printed or exported.
Although when in the Report Designer, virtually any task can be accomplished without scripting (Conditionally Change a Control's Appearance, Conditionally Change a Label's Text and Conditionally Hide Bands), scripting is made available to extend the standard functionality as far as may be required. And, scripting is the only way to calculate custom summaries (this is detailed in the last section of this document).
Every report element has a set of script events, which are individual for each element's type. For example, the events of the Detail band are shown in the following image.
After you click (New) for an event (e.g. the Before Print, which is the most used), the Scripts Tab is switched on, where you can manage and edit all the report's scripts.
In this tab, for a selected event, a script template is auto-added, in the language specified via the Script Language property of the report.
You can verify that your report's scripts are valid, by clicking Validate. The validation result is then displayed in the Scripts Errors Panel.
Note that scripts are saved to a file along with the report's layout (for details on this, refer to Back Up the Current Layout Before Modifying It).
Scripting Specifics
1.Scripting language
The report scripts may be written in one of the following languages that the .NET framework supports - C#, Visual Basic and J#. Since J# is not installed with the framework installation, by default, make sure it is present before writing code in it. The scripting language is specified via the Script Language property of the Report object. It is set to C#, by default.
2.Scripting scope
Script execution is performed in the following way:
The report engine generates a temporary class in memory. The names of the variables are defined by the Name properties of the controls and objects they represent. When the script is preprocessed, its namespace directives are cut from the script code and added to the namespace, where the temporary class is defined.
After preprocessing, all scripts are placed in the code of the temporary class. Then, the resulting class is compiled in memory, and its methods are called when events occur.
Scripting offers many advantages: you can declare classes (they will become inner classes), variables, methods, etc. A variable declared in one script is accessible in another script, because it is, in fact, a variable of the temporary class.
3.Reference External Assemblies
The Script References property of the Report object specifies the full paths (including the file names) to the assemblies that are referenced in the scripts used in a report. These paths should be specified for all the assemblies that are included in scripts via the using (C#), Imports (Visual Basic) or import (J#) directives.
Note
Usually, you don't need include any assembles, because most standard assemblies that you may require in scripts are already referenced by the Report Designer.
Example: Custom Summary
In this example, we will display the total number of product unit packs in a group.
To perform this, execute steps similar to the ones described in Add Totals to a Report, except that for the summary field, you should set the Function property to Custom.
Then, the additional events are added to the label's Scripts property.
You can handle these events in the following way.
Finally, switch to the Preview Tab, and view the result.
See Also
Count the Number of Records in a Report or a Group
Cancel Printing If a Report Does Not Contain Any Records
Limit the Number of Records per Page
Copyright (c) 1998-2016 Developer Express Inc. All rights reserved.
Send Feedback on this topic to DevExpress.