Overview

This topic deals with client-side image maps, which are used to implement gauge interactivity. A client-side image map is a standard HTML element that is used to define interactive areas within an image displayed by a browser (e.g., Internet Explorer, FireFox, etc.). Each image map contains a collection of map areas, and each map area defines an interactive region that can be used for:

Navigating to different pages (drill-down).
Handling client-side map area events such as OnClick, OnMouseEnter, OnMouseLeave, etc.
Displaying tool tips.

Numerous gauge elements can have associated map areas, including: gauge container, circular gauges, linear gauges, scales, pointers, state indicators, and numeric indicators. In addition, custom map areas that have end-user defined coordinates can also be created by using the MapAreas collection property of the root GaugeContainer object.

Creating a Client-Side Image Map

Image map areas will be automatically created if the MapEnabled property of the root GaugeContainer object is set to True and:

One of the gauge elements has a non-empty ToolTip, Href, or MapAreaAttributes property. In this case, the position of the image map is determined by the shape of the gauge element.
The MapAreas collection property of the gauge container is not empty, and contains one or more custom MapArea objects. In this case, the dimensions of the image map are set by you.

Note
The gauge image map will only be rendered when the gauge's RenderType property is set to ImageTag. A gauge image map can be displayed using binary streaming, which results in faster gauge rendering, but a different technique must be used for the image map creation.

For more information refer to the topic on Client-Side Maps and Binary Streaming.

By default, the MapEnabled property of the gauge container is set to True. To disable an image map: do not set the ToolTip, Href, and MapAreaAttributes properties of the relevant gauge element; or set the MapEnabled property to False.

For custom image maps the shape is determined by the MapArea.Shape property.

Map Area Properties

Gauge container, circular gauges, linear gauges, scales, pointers, state indicators, and numeric indicator objects have the following map area properties:

ToolTip: A string that will be shown when the end-user's cursor is over the map area. Line breaks for the tooltip may be used (a 
 character sequence at design-time, and the relevant ASP.NET language's line break/carriage return expression at run-time (e.g., vbCrLf for VB.NET).
Href: A link to another page that is loaded when the end-user clicks on the map area.
MapAreaAttributes: Other map area attributes, such as "target", etc. It can also be used to handle client-side map area events using JavaScript. Note that this string will be added at the end of the AREA tag.

Example

We set the Tooltip, Href, and MapAreaAttributes properties of a circular gauge.

Visual Basic	Copy Code
GaugeContainer1.CircularGauges("Default").ToolTip = "Circular gauge tooltip." GaugeContainer1.CircularGauges("Default").Href = "http://www.dundas.com" GaugeContainer2.CircularGauges("Default").MapAreaAttributes = "TARGET='_blank'"

Visual Basic

Copy Code

GaugeContainer1.CircularGauges("Default").ToolTip = "Circular gauge tooltip."
GaugeContainer1.CircularGauges("Default").Href = "http://www.dundas.com"
GaugeContainer2.CircularGauges("Default").MapAreaAttributes = "TARGET='_blank'"

C#	Copy Code
GaugeContainer1.CircularGauges["Default"].ToolTip = "Circular gauge tooltip."; GaugeContainer1.CircularGauges["Default"].Href = "http://www.dundas.com"; GaugeContainer2.CircularGauges["Default"].MapAreaAttributes = "TARGET='_blank'";

Copy Code

GaugeContainer1.CircularGauges["Default"].ToolTip = "Circular gauge tooltip.";
GaugeContainer1.CircularGauges["Default"].Href = "http://www.dundas.com";
GaugeContainer2.CircularGauges["Default"].MapAreaAttributes = "TARGET='_blank'";

Using Keywords

Special keywords, which are case sensitive, can be inserted in the ToolTip, Href, or MapAreaAttributes string properties of Pointer, Scale, Range, CircularGauge, LinearGauge, GaugeLabel, GaugeImage, NumericIndicator, and StateIndicator objects (not applicable to custom map areas, which are stored in the GaugeContainer.MapAreas collection). These keywords will then be replaced with the element data they represent (see table below).

Keyword	Replaced by	Applicable To
#INPUTVALUE1, #INPUTVALUE2, etc.	Current value of the value source, where "1", "2", etc. is the index of the value in the Values collection.	All elements.
#POINTERVALUE1, #POINTERVALUE2, etc.	Value of the indexed pointer will be displayed (e.g., values from the Pointer.Value property). "1", "2", etc. is the index of the pointer in the Pointers collection of the gauge.	LinearGauge and CircularGauge objects.
#VALUE	Current value of the element.	Pointers, Scales, NumericIndicator, and StateIndicator objects.
#VAL	The value of the scale.	Scale
#STATE	Current indicator's State name.	StateIndicator objects
{#VAL:#0.00}	Formatted scale value.	Scale

Optional .NET Framework formatting strings can also be added at the end of the keyword. For example, the keyword "#VALUE{C2}" will be replaced with the value formatted as currency with 2 decimal numbers. Refer to the "Formatting Types" topic in your MSDN documentation for further information.

The following are several scenarios where these keywords would be helpful:

Passing querystring parameters in a URL for drill-down.
Showing values as tool tips.

When setting tooltips, line breaks may also be used (e.g., a 
 character sequence at design-time, and the relevant ASP.NET language's line break/carriage return expression at run-time, such as vbCrLf for VB.NET).

Creating End-user Defined Map Areas

The MapAreas collection of the gauge container can be used to add end-user defined map areas, and provide interactive abilities such as drill down, tool tips, and client-side events for any end-user defined region within the gauge container. An image map will be automatically generated if the MapAreas collection is not empty and the MapEnabled property of the gauge is set to True.

Each MapArea object in this collection defines an interactive region using the Shape and Coordinates properties. The number of coordinates specified by the Coordinates array property depends on the shape of the map area:

Circle: Three coordinates must be provided: "x1,y1,r". x1,y2 are the coordinates of the center of the circle and r is the radius of the circle.
Rectangle: Four coordinates must be provided: "x1,y1,x2,y2". x1,y1 are the coordinates of the upper-left corner of the rectangle and x2,y2 are the coordinates of the lower-right corner of the rectangle.
Polygon: Two or more x and y pairs may be provided: "x1,y1,x2,y2...xn,yn". Each x,y pair represents the coordinates of one vertex of the polygon.

When the map area's shape and coordinates are defined, the ToolTip, Href, or MapAreaAttributes properties can then be set to provide the required interaction for the area.

Note
If two map regions are overlapped, the first map area in the collection will have priority.

Example

We set the Tooltip, Href, and MapAreaAttributes properties of a custom map area. The map area is rectangular, with X,Y coordinates of (50 pixels, 50 pixels) for the top-left corner, and X,Y coordinates of (100 pixels, 100 pixels) for the bottom-right corner of the rectangle. Note that the gauge container has its top-left corner set at (0,0) pixels.

Visual Basic	Copy Code
Imports Dundas.Gauges.WebControl ... ' Create MapArea object. Dim myArea As New MapArea ' Set the shape. myArea.Shape = MapAreaShape.Rectangle ' Create array for coordinates. Dim coordinates(4) As Single coordinates(0) = 50 coordinates(1) = 50 coordinates(2) = 100 coordinates(3) = 100 myArea.Coordinates = coordinates ' Set map area tooltip and href. myArea.ToolTip = "Click on the gauge to see more details." myArea.Href = "http://www.dundas.com" ' Add map area into the collection. GaugeContainer1.MapAreas.Add(myArea)

Visual Basic

Copy Code

Imports Dundas.Gauges.WebControl
...
' Create MapArea object.
Dim myArea As New MapArea

' Set the shape.
myArea.Shape = MapAreaShape.Rectangle

' Create array for coordinates.
Dim coordinates(4) As Single
coordinates(0) = 50
coordinates(1) = 50
coordinates(2) = 100
coordinates(3) = 100
myArea.Coordinates = coordinates

' Set map area tooltip and href.
myArea.ToolTip = "Click on the gauge to see more details."
myArea.Href = "http://www.dundas.com"

' Add map area into the collection.
GaugeContainer1.MapAreas.Add(myArea)

C#	Copy Code
using Dundas.Gauges.WebControl; ... // Create MapArea object. MapArea myArea = new MapArea(); // Set the shape. myArea.Shape = MapAreaShape.Rectangle; // Create array for coordinates. Single [] coordinates = new Single[4]; coordinates[0] = 50; coordinates[1] = 50; coordinates[2] = 100; coordinates[3] = 100; myArea.Coordinates = coordinates; // Set map area tooltip and href. myArea.ToolTip = "Click on the gauge to see more details."; myArea.Href = "http://www.dundas.com"; // Add map area into the collection. GaugeContainer1.MapAreas.Add[myArea];

Copy Code

using Dundas.Gauges.WebControl;
...
// Create MapArea object.
MapArea myArea = new MapArea();

// Set the shape.
myArea.Shape = MapAreaShape.Rectangle;

// Create array for coordinates.
Single [] coordinates = new Single[4]; 
coordinates[0] = 50;
coordinates[1] = 50;
coordinates[2] = 100;
coordinates[3] = 100;
myArea.Coordinates = coordinates;

// Set map area tooltip and href.
myArea.ToolTip = "Click on the gauge to see more details.";
myArea.Href = "http://www.dundas.com";

// Add map area into the collection.
GaugeContainer1.MapAreas.Add[myArea];

Dundas Gauge for ASP.NET	Send comments on this topic
Client-Side Image Maps
See Also

Overview

Creating a Client-Side Image Map

Map Area Properties

Example

Using Keywords

Creating End-user Defined Map Areas

Example

See Also