416.467.9100 | Dundas Data Visualization | Login
Welcome Guest
This is the support page for the legacy Dundas Dashboard application. For assistance with the current Dundas BI application please click here.
Dashboard v5.0

This site makes extensive use of JavaScript.

Please enable JavaScript in your web browser and reload the page before proceeding.

Map Examples and Notes

Hide navigation
Modified on Tue, 02 Apr 2013 10:36 AM
Click to return to: Documentation | Designing Dashboards | DV Controls | Map


The examples below show how to accomplish various tasks using the Dundas Dashboard Map control, or use some of its more advanced features.


Centering shape labels

If you import a world map shapefile, you may find that the text label for the United States shape is positioned at an unexpected location (⪚ over England). This is due to the following:

  • The United States shape is actually composed of multiple closed figures (⪚ Alaska, Hawaii, the continental U.S. border).
  • The combined bounds of these figures ranges from -180 degrees longitude to +180 degrees longitude.
  • The default labeling algorithm positions the text label at the center of the combined bounds, which puts the text label at 0 degrees longitude (⪚ over England).

To resolve this issue, you can use the Center Shape Labels feature:

  1. Go to the Properties grid for your map control in the Dashboard Designer screen.
  2. Under the Appearance section, expand the Labels properties.
  3. By default, centering of shape labels is turned off for performance reasons. To enable centering, set the Center Shape Labels property to True.

Labeling properties for the map control.

Labeling properties for the map control.

When centering is in effect, text labels are positioned over the largest figure (⪚ largest land mass) in each shape. In the case of the United States shape, the text label will be positioned over the continental U.S. figure.

Centering of shape labels in effect.

Centering of shape labels in effect.

Note: In Dundas Dashboard 2.5.0 or earlier, use the Enable Smart Labeling property instead.

Getting data values from a map element

This example shows how to get the values of data (⪚ dataset or KPI) bound to a map element such as a shape, path or symbol. The values are obtained via a script which can be invoked inside or outside of map control interactions.

The following steps show how to use the GetValue method of the DashboardMapElement class:

  1. Add a map control to your dashboard that displays a world map.
  2. Add a dataset to the map control. This dataset (⪚ WorldDataset) has a column of population figures (⪚ Population) for the countries of the world.
  3. Add a button control to the dashboard.
  4. Add a Click interaction script for the button as follows:

    DashboardMapShape shp = MapControl1.Shapes["United States"];
    object val = shp.GetValue("WorldDataset", "Population");
    string s = String.Format("Country: {0}\nPopulation: {1:N0}", shp.ToString(), val);
  5. Save, then preview your dashboard.

Getting data from a map shape when a button is clicked.

Getting data from a map shape when a button is clicked.

Accessing data-bound appearance properties from script

You can access the data-bound appearance properties of map elements such as shapes, symbols, paths and labels via scripting. Below is an example list of properties:

  • DashboardMapShape.DataBorderBrush
  • DashboardMapShape.DataBorderWidth
  • DashboardMapShape.DataFill
  • DashboardMapShape.Label.DataText
  • DashboardMapPath.DataStroke
  • DashboardMapPath.DataStrokeThickness
  • DashboardMapPath.Label.DataText
  • DashboardMapSymbol.DataFill
  • DashboardMapSymbol.DataHeight
  • DashboardMapSymbol.DataMarkerStyle
  • DashboardMapSymbol.DataStroke
  • DashboardMapSymbol.DataStrokeThickness
  • DashboardMapSymbol.DataWidth
  • DashboardMapSymbol.Label.DataText

Reset map element appearance using script

To reset an appearance property of a map element (e.g. shape) using scripting:

  1. Set the property value to null for brush properties, or to double.NaN for numeric values. For a symbol you can reset its marker style by setting it to MarkerShape.None.
  2. Invalidate the map element.

Example code:

// To reset a Brush (Fill, Stroke) set the brush to NULL first: MapControl1.Shapes"Canada".Fill = null; MapControl1.Shapes"Canada".Invalidate(false);

// To reset a double (Width, Height) set it to NaN first: MapControl1.Symbols"Toronto".Height = double.NaN; MapControl1.Symbols"Toronto".Invalidate(false);

// To reset a symbol shape, set it to MarkerShape.None first: MapControl1.Symbols"Toronto".MarkerStyle = MarkerShape.None; MapControl1.Symbols"Toronto".Invalidate(false);

Once the appearance property of a map element is reset, it will be re-calculated using the following priority rules:

  1. If the element property (⪚ Shape.Fill) has a local value set, this has the highest priority (unless it is set to null, NaN or None, in which case it is ignored).
  2. The data-bound value (⪚ Shape.DataFill) is next in priority if the element has had its appearance
    changed due to a data binding.
  3. The map default value (⪚ MapControl1.DefaultShapeFillBrush) has the lowest priority.

Scale and offset map elements

Map elements such as shapes, symbols and paths have properties that allow you to apply scaling, or offset their positions in pixel units:

  • X Scale - The scaling amount in the X (horizontal) direction. (Not available for symbols).
  • Y Scale - The scaling amount in the Y direction. (Not available for symbols).
  • X Offset - The amount (in pixels) to offset the element in the X direction. A positive value moves the element to the right.
  • Y Offset - The amount (in pixels) to offset the element in the Y direction. A positive value moves the element down.

These properties can be used through script or in the property grid to change the size and offset of map elements. The offset is in pixels (so a symbol can have an X and Y value, but a pixel offset, for example).

Shapes have an additional (advanced) property, Scale Around Largest Figure, which controls how scaling is performed. If a shape has multiple figures, the scaling operation can either scale around the largest figure in the shape (this is the default behavior) or it can scale around the geographic center of all the shapes. For example, a “USA” shape may consist of figures representing Alaska, Hawaii and the mainland USA. When you change the scale, the mainland USA figure will grow larger, while Hawaii and Alaska will be offset slightly, since the scaling center is around mainland USA. If you don't want this behavior but want the scaling to offset from the center of the shape (including all figures), then you can set this flag to False.

Scale and offset properties.

Scale and offset properties.


Asynchronous behavior

At viewing-time, when you change a map property or call a certain map method (e.g. via scripting), this may invalidate the map and cause it to be redrawn in a later rendering pass. This all happens asynchronously and it means that affected properties of the map will not be updated until the redraw has completed.

As an example, consider the following script:

MapControl1.Viewport.Zoom = 5; MapControl1.Viewport.IsAutoCenteringEnabled = false; MapControl1.Viewport.IsAutoCenteringEnabled = true; services.ShowMessage(MapControl1.Viewport.Zoom);

When you set the IsAutoCenteringEnabled property from false to true, the map viewport will re-center itself and reset its zoom level back to its default value. However, this all happens asynchronously so that when you run the above script, the message box is going to report that the zoom level is still at 5. This is because the actual property value won't be reset until the map has redrawn itself, which occurs some time after the showing of the message box.

Related topics

Click to return to: Documentation | Designing Dashboards | DV Controls | Map

About Dundas | Contact Us Follow us on Twitter! | Privacy Statement | Report Site Issues

Copyright © 2009-2014 Dundas Data Visualization, Inc.