Overview

This topic discusses scripting in the Code Editor.

The Code Editor (see figure below) is used to write VB.NET or C# script that is executed when the project is run.

 

Figure 1: Code Editor.

 

There are several events that can be coded against, and the events are displayed in the order by which they are fired.

The Code Editor utilizes the full API of the Gauge control, and the events have parameters that allow for programmatic access to various gauge objects. These event parameters can be seen in the syntax statement, and are also displayed in the Code Window of the editor.

Please refer to the Programmers Reference chapter for a detailed listing of the control's API.

Opening the Code Editor

To open the Code Editor right-click over a Gauge control object and select the View Code... menu item. Alternatively you can click on the View Code... button in the Advanced tab of either the Gauge Designer or Sub-Gauge Designer dialogs.

Source Code Tab

Use this tab to write your script. Events that already have script associated with them will display a  icon next to them.

The gaugeContainer parameter represents the Gauge control. To access gauges, indicators, ranges, etc. use this gaugeContainer parameter and its collections. For example, to access the first range of the control's first circular gauge you would use the following: gaugeContainer.CircularGauges(0).Ranges(0).FillColor = Color.Wheat.

If there is script written for an event and you choose to change the language via the language selector then you will receive a warning (see figure below), indicating that this change will result in compilation errors. This occurs since the previously written script used a different .NET language (changing the language will not result in existing script being converted to the new language).

 

Figure 2: Warning resulting from change in language when script for an event already exists.

 

Available Events

The following briefly lists and describes the events and their parameters that are raised in the editor:

Event	Description	Parameters
PostInitialize	Raised once, right after the control has been initialized. All default properties have been set, but the data has not yet been added.	gaugeContainer: represents the Gauge control, and is the root object of the API.   codeParams: user-defined code parameters.
PostApplyData	Raised once, after all data has been added to the control's Values collection from SQL Server.	gaugeContainer: represents the Gauge control, and is the root object of the API.   codeParams: user-defined code parameters.

Illegal Keywords

(C#)

Keyword	Suggested Replacement
this	Use the sender parameter object to refer to the element being scripted against.
base	No replacement, it is not possible to access the base class.

 

(VB.NET)

Keyword	Suggested Replacement =  = true;
Me	Use the sender parameter object to refer to the element being scripted against.
MyBase	No replacement, it is not possible to access the base class.
vbCrLf	Use a "\n" inside of the text in order to break to a new line.

Exceptions and Try...Catch Statements

Compile-time exceptions are caught by the editor at compile-time, and the error is indicated in the Build Window.

Run-time exceptions, however, are not thrown by the editor. If a run-time exception occurs then no more code after the offending line will be executed.

We recommend using Try...Catch statements in order to handle run-time exceptions. A handy debugging method is to use the Catch statement, and output the error message as a label of the control (e.g. gaugeContainer.Labels[0].Text = ex.Message.ToString();).

Example

In the PostApplyData event we get the last value assigned to the control's Values collection, and then we append this value to the Gauge title.

We assume that one circular gauge has been added to the control (i.e. container).

[Visual Basic]

' We append the string value of the first pointer to the gauge label.
Dim lastValue As Double = gaugeContainer.CircularGauges(0).Pointers(0).Value
gaugeContainer.Labels(0).Text += lastValue.ToString()

 

[C#]

// We append the string value of the first pointer to the gauge label.
double lastValue = gaugeContainer.CircularGauges[0].Pointers[0].Value;
gaugeContainer.Labels[0].Text += lastValue.ToString();

Code Parameters

Code parameters, which are user-defined name-value pairs that make code easier to understand, can be defined by clicking on the Code Parameters tab of the Code Editor (see figure below).
 

Figure 2: Code Parameters tab.
 

The image above displays a Watermark code parameter that has been defined for the "Watermark" report parameter. Now referencing this code parameter will result in the value of the "Watermark" report parameter being used (see figure below).

Figure 3: Using the "Watermark" code parameter in the Code Editor.

External Assemblies

Use this tab to add references to any external assemblies required by your code.

To add and remove references use the  and  buttons, respectively.

To change the order by which assemblies are referenced use the  and  buttons.

See Also

 

 

---

Copyright © 2005 - 2008, Dundas Data Visualization, Inc. and others.