ActiveReports 18 .NET Edition
Report Authors / Report Controls / Report Controls in Page/RDLX Report / Map
In This Topic
    Map
    In This Topic

    The Map data region is a professional edition feature that shows your business data against a geographical background. You can create different types of map, depending on the type of information you want to communicate in your report.

    Maps consist of a title, a viewport for specifying the center point and scale, legend for interpreting data, distance scale to represent real world distance, and color scale for representing the meaning of colors used in maps. Lets us learn these in detail in the next section.

    Note:

    • Map control is not supported by WebDesigner for now.
    • MESCIUS inc. does not provide access to Tile Providers; please ensure that you have a valid license before using it.

    Structure

    Map Structure

    Title

    Map Title describes the theme or subject of the map. The purpose of map title is to tell the viewer of what he is looking at. You can add multiple titles to the Map using the MapTitleDesigner Collection Editor. For more information, see Add a Title to the Map tutorial.

    Viewport

    Viewport refers to the area on the map where data is displayed against a geographical background. It specifies the coordinates, projection system, parallels and meridians, center point, and scale of the map. In other words, it is a map element that actually displays geographical data and occupies most area of the map control depending on the location and dock position of other map elements. By default, color scale and distance scale appear inside the viewport, and the map legend appears outside the viewport. For information on customizing the viewport, see Modify the Appearance of the Viewport tutorial.

    Map Viewport Dialog Properties

    The Map Viewport dialog lets you set properties with the following pages.

    Coordinate system: Specify the coordinate system of the viewport. Select from Planar, Geographic, or select the <Expression...> option to open the Expression Editor and create an expression.

    Projection: Specify the projection of the map. Tile layers must use the Mercator projection.

    Minimum X: Specify the minimum X coordinate of the map in degrees.

    Maximum X: Specify the maximum X coordinate of the map in degrees.

    Minimum Y: Specify the minimum Y coordinate of the map in degrees.

    Maximum Y: Specify the maximum Y coordinate of the map in degrees.

    Projection Center X: Specify the X coordinate of the projection center in degrees.

    Projection Center Y: Specify the Y coordinate of the projection center in degrees.

    Minimum zoom: Specify the minimum zoom value.

    Maximum zoom: Specify the maximum zoom value.

    Map resolution: Enables the viewport to simplify vector data for polygon and line layers.

    Show grid lines below the map: Specify whether to show the grid lines above or below the content of the map.

    Hide meridians: Specify whether to hide meridians.

    Interval: Specify the spacing between the grid lines in degrees.

    Line

    • Style: Choose from None, Dotted, Dashed, Solid, Double, Groove, Ridge, Inset, WindowInset, Outset, or select the <Expression...> option to open the Expression Editor and create an expression.
    • Width: Specify the width of the line.
    • Color: Select a Web or custom color for the line.

    Show labels: Specify whether to show labels for meridians on the map.

    Format: Specify the format string to display numeric labels.

    Position: Specify the position of the meridians on the map.

    Font

    • Family: Choose the font family name.
    • Size: Choose the size in points for the font.
    • Style: Choose Normal or Italic.
    • Weight: Choose from Lighter, Thin, ExtraLight, Light, Normal, Medium, SemiBold, Bold, ExtraBold, Heavy, and Bolder.
    • Color: Select a Web or custom color for the font.
    • Decoration: Choose from None, Underline, Overline, LineThrough, or select the <Expression...> option to open the Expression Editor and create an expression.

    Hide parallels: Specify whether to hide parallels.

    Interval: Specify the spacing between the grid lines in degrees.

    Line

    • Style: Choose from None, Dotted, Dashed, Solid, Double, Groove, Ridge, Inset, WindowInset, Outset, or select the <Expression...> option to open the Expression Editor and create an expression.
    • Width: Specify the width of the line.
    • Color: Select a Web or custom color for the line.

    Show labels: Specify whether to show labels for parallels on the map.

    Format: Specify the format string to display numeric labels.

    Position: Specify the position of the parallels on the map.

    Font

    • Family: Choose the font family name.
    • Size: Choose the size in points for the font.
    • Style: Choose Normal or Italic.
    • Weight: Choose from Lighter, Thin, ExtraLight, Light, Normal, Medium, SemiBold, Bold, ExtraBold, Heavy, and Bolder.
    • Color: Select a Web or custom color for the font.
    • Decoration: Choose from None, Underline, Overline, LineThrough, or select the <Expression...> option to open the Expression Editor and create an expression.

    Center and zoom: Specify how the map viewport zooms and centers during the report processing.

    • Custom
    • Center map to show a map element
    • Center map to show a map layer
    • Center map to show all map elements

    View Center X: Specify the X coordinate of the current view center.

    View Center Y: Specify the Y coordinate of the current view center.

    Zoom level: Specify the zoom level of the map view.

    Border

    • Style: Choose an enumerated style for the border.
    • Width: Set a width value in points between 0.25pt and 20pt.
    • Color: Select a Web or custom color for the border.

    Background

    • Color: Select a color to use for the background of the Viewport.
    • Gradient: Select a color to use for the border, or select the <Expression...> option to open the Expression Editor and create an expression that evaluates to a .NET color.
    • Gradient End Color: Select a color to use for the end color of the background gradient.
    • Pattern: Select the hatching pattern of a report control.

    Shadow offset: Specify the size of the shadow. Shadow offsets are drawn to the right and below an element.

    Legend

    A legend on a map provides valuable information to users for interpreting the map data visualization rules such as color, size, and marker type differences for map elements on a layer. By default, a single Legend item already exists in the legends collection which can be used by all layers to display items. You can also create additional legends to use them individually with layers that have associated rules to display items in the legend. Legends are added in the LegendDesigner Collection Editor. For more information, see Add a Legend to the Map tutorial.

    Distance Scale

    A distance scale helps a user to understand the scale of the map. Distance on a map is not the same as the actual real-world distance, so a distance scale shows that a certain distance on the map equals a certain distance in a real-world. In distance scale, the distance is displayed in both miles and kilometers. The scale range and values are automatically calculated using the viewport boundaries, projection type, and zoom level. For more information, see Set the Distance Scale on a Map tutorial.

    Map Distance Scale Dialog Properties

    The Map Distance Scale dialog lets you set properties with the following pages.

    Location

    • Position: Specify the docking position of the distance scale panel. Choose from TopCenter, TopLeft, TopRight, LeftTop, LeftCenter, LeftBottom, RightTop, RightCenter, RightBottom, BottomRight, or select the <Expression...> option to open the Expression Editor and create an expression.
    • Show distance scale outside the viewport: Specify whether the panel is docked inside or outside of the map viewport.

    Scale

    • Color: Select the fill color for the distance scale bar.
    • Border color: Select the border color for the distance scale bar.

    Border

    • Style: Choose from None, Dotted, Dashed, Solid, Double, Groove, Ridge, Inset, WindowInset, or Outset.
    • Width: Choose the width of the border line.
    • Color: Select a color for the border.

    Background

    • Color: Select a color to use for the background of the distance scale.
    • Gradient: Select a color to use for the border, or select the <Expression...> option to open the Expression Editor and create an expression that evaluates to a .NET color.
    • Gradient End Color: Select a color to use for the end color of the background gradient.
    • Pattern: Select the hatching pattern of the distance scale panel from the list of patterns, or select the <Expression...> option to open the Expression Editor and create an expression.

    Shadow offset: Specify the size of the shadow of the distance scale panel. Shadow offsets are drawn to the right and below an element.

    Family: Choose the font family name.

    Size: Choose the size in points for the font.

    Style: Choose Normal or Italic, or select the <Expression...> option to open the Expression Editor and create an expression.

    Weight: Choose from Lighter, Thin, ExtraLight, Light, Normal, Medium, SemiBold, Bold, ExtraBold, Heavy, and Bolder.

    Color: Select a Web or custom color for the font.

    Decoration: Choose from None, Underline, Overline and LineThrough, or select the <Expression...> option to open the Expression Editor and create an expression.

    Initial visibility

    • Visible: The distance scale is visible when the report runs.
    • Hidden: The distance scale is hidden when the report runs.
    • Expression: Use an expression with a Boolean result to decide whether the distance scale is visible. True for hidden, false for visible.

    Action

    Select one of the following actions to perform when a user clicks on the distance scale element.

    • None: The default behavior is to do nothing when a user clicks the distance scale element at run time.
    • Jump to URL: Select this option and provide a valid URL to create a hyperlink to a Web page.
    • Jump to bookmark: Select this option and provide a valid Bookmark ID to allow the user to jump to the report control with that Bookmark ID.
    • Jump to report: For drill-through reporting, select this option and provide the name of a local report, the relative path of a report in another folder, or the full path of a report on another server.
    • Apply Parameters: Select the Name, the Type, and the Value of the parameter to set a parameter value through user action. See Actionable Parameters for more information.

    Color Scale

    A color scale helps a user to understand the range of colors that are used for data visualization on a layer. A map has just one color scale and multiple layers can provide data for it. For information, see Set the Color Scale on a Map tutorial.

    Map Color Scale Dialog Properties

    The Map Color Scale dialog lets you set properties with the following pages.

    Location

    • Position: Specify the docking position of the color scale panel. Choose from TopCenter, TopLeft, TopRight, LeftTop, LeftCenter, LeftBottom, RightTop, RightCenter, RightBottom, BottomRight, or select the <Expression...> option to open the Expression Editor and create an expression.
    • Show color scale outside the viewport: Specify whether the panel is docked inside or outside of the map viewport.

    Color bar

    • Border color: Specify the outline color for color scale divisions.
    • Range gap color: Specify color to fill color divisions for undefined range values.

    Display: Specify whether to display color scale labels on the color scale panel. Select from Auto, ShowMiddleValue, ShowBorderValue, or select the <Expression...> option to open the Expression Editor and create an expression.

    Hide end labels: Specify whether to display first and last labels on the color scale panel.

    Format: Specify the format string to display numeric labels.

    Placement: Speciy the position of the color scale labels on the color scale panel. Select from Alternate, Top, Bottom, or select the <Expression...> option to open the Expression Editor and create an expression.

    Interval: Specify the frequency of the labels on the color scale panel. A value of 0 means no labels are displayed.

    Tick mark length: Specify the length of the tick marks on the color scale panel.

    Text: Specify the text of the color scale panel.

    Font

    • Family: Choose the font family name.
    • Size: Choose the size in points for the font.
    • Style: Choose Normal, Italic or select the <Expression...> option to open the Expression Editor and create an expression.
    • Weight: Choose from Lighter, Thin, ExtraLight, Light, Normal, Medium, SemiBold, Bold, ExtraBold, Heavy, and Bolder.
    • Color: Select a Web or custom color for the font.
    • Decoration: Choose from None, Underline, Overline, LineThrough, or select the <Expression...> option to open the Expression Editor and create an expression.

    Border

    • Style: Choose from None, Dotted, Dashed, Solid, Double, Groove, Ridge, Inset, WindowInset, or Outset.
    • Width: Specify the width of the border.
    • Color: Specify a color for the border.

    Background

    • Color: Select a color to use for the background of the distance scale.
    • Gradient: Specify whether and how to use color gradients in the color scale background. Select from None, LeftRight, TopBottom, Center, DiagonalLeft, DiagonalRight, HorizontalCenter, VerticalCenter, or select the <Expression...> option to open the Expression Editor and create an expression.
    • Gradient End Color: Select a color to use for the end color of the background gradient.
    • Pattern: Select the hatching pattern of the color scale panel from the list of patterns, or select the <Expression...> option to open the Expression Editor and create an expression.

    Shadow offset: Specify the size of the shadow of the color scale panel. Shadow offsets are drawn to the right and below an element.

    Family: Choose the font family name.

    Size: Choose the size in points for the font.

    Style: Choose Normal, Italic or select the <Expression...> option to open the Expression Editor and create an expression.

    Weight: Choose from Lighter, Thin, ExtraLight, Light, Normal, Medium, SemiBold, Bold, ExtraBold, Heavy, and Bolder.

    Color: Select a Web or custom color for the font.

    Decoration: Choose from None, Underline, Overline, LineThrough, or select the <Expression...> option to open the Expression Editor and create an expression.

    Initial visibility

    • Visible: The color scale is visible when the report runs.
    • Hidden: The color scale is hidden when the report runs.
    • Expression: Use an expression with a Boolean result to decide whether the color scale is visible. True for hidden, false for visible.

    Action

    Select one of the following actions to perform when a user clicks on the color scale element.

    • None: The default behavior is to do nothing when a user clicks the color scale element at run time.
    • Jump to URL: Select this option and provide a valid URL to create a hyperlink to a Web page.
    • Jump to bookmark: Select this option and provide a valid Bookmark ID to allow the user to jump to the report control with that Bookmark ID.
    • Jump to report: For drill-through reporting, select this option and provide the name of a local report, the relative path of a report in another folder, or the full path of a report on another server.
    • Apply Parameters: Select the Name, the Type, and the Value of the parameter to set a parameter value through user action. See Actionable Parameters for more information.

    Important Properties

    By clicking on the Map control, you can set its properties in the Properties panel.

    Property Description
    AccessibleDescription Enter the alternative description of the control for use by accessibility client application. The property on exporting the report adds the ‘alternative text’ in PDF and ‘alt’ attribute in HTML.
    AntiAliasing Select the anti-aliasing type from All, None, Text, or Graphic.
    BorderColor Choose a color for the border from the Color Picker.
    BorderStyle Select a style for the border.
    BorderWidth Enter a value or expression to set the width of the border.
    Calander Select the type of calendar you want to use.
    ColorScale Specify the range of colors that are used for data visualization on a layer. See the Color Scale section for details.
    DistanceScale Specify a certain distance on the map that equals a certain distance in the real-world. See the Distance Scale section for details.
    Language Choose the language of the map.
    Layers Specify the layers (Polygon layer, Point layer, Line layer, Tile layer) used to display data on the map. See the Map Layers section for details.
    Legends Specify the map data visualization rules, such as color, size, and marker type differences, for map elements on a layer. See the Legends section for details.
    MaximumSpatialElementCount Specify the maximum number of spatial elements that are allowed in the Map. By default, the value is set to 20000.
    MiximumTotalPointCount Specify the maximum total number of map points in all spatial elements that are allowed in the Map.
    NumeralLanguage Choose the numeral language.
    NumeralVariant Choose numeral variant from 1-7.
    PageBreak Set the Page Break.
    ShadowIntensity Entre a value or expression to specify the intensity of the shadow throughout the map. By default, the value is set to 25.
    Size Set the Width and Height of the map.
    TextAntiAliasingQuality Select the text anti- aliasing quality to High, Normal, or SystemDeafult.
    TileLanguage Choose the primary language of the map tiles.
    Titles Specify the theme or subject of the map. See the Title section for details.
    ViewPort Specify the coordinates, projection system, parallels and meridians, center point, and scale of the map. See the Viewport section for details.

    Map Dialog Properties

    You can set the Map properties in the Map dialog. To open it, with the Map selected on the report, under the Properties panel, click the Property dialog link.

    Name: Enter a name for the map that is unique within the report. This name is called in code. You can only use underscore (_) as a special character in the Name field. Other special characters such as period (.), space ( ), forward slash (/), back slash (\), exclamation (!), and hyphen (-) are not supported.

    Tooltip: A textual label for the report item used to include TITLE or ALT attributes in HTML reports.

    Antialiasing: Select the smoothing mode to apply to all map control elements. Choose All, None, Text, Graphic, or select the <Expression...> option to open the Expression Editor and create an expression. 

    Antialiasing quality: Select the quality for antialiasing. Choose High, Normal, SystemDefault, or select the <Expression...> option to open the Expression Editor and create an expression.

    Initial visibility

    • Visible: The map is visible when the report runs.
    • Hidden: The map is hidden when the report runs.
    • Expression: Use an expression with a Boolean result to decide whether the map is visible. True for hidden, false for visible.

    Visibility can be toggled by another report item: Select this check box to display a toggle image next to another report item. This enables the drop-down box below where you can specify the TextBox control that toggles the visibility of the map. The user can click the toggle item to show or hide this map.

    Border

    • Style: Choose from None, Dotted, Dashed, Solid, Double, Groove, Ridge, Inset, WindowInset, or Outset.
    • Width: Specify the width of the border.
    • Color: Select a Web or custom color for the font.

    Background

    • Color: Select a color to use for the background of the map.
    • Gradient: Specify whether and how to use color gradients in the color scale background. Select from None, LeftRight, TopBottom, Center, DiagonalLeft, DiagonalRight, HorizontalCenter, VerticalCenter, or select the <Expression...> option to open the Expression Editor and create an expression.
    • Gradient End Color: Select a color to use for the end color of the background gradient.
    • Pattern: Select the hatching pattern of a report control.

    Element name: Enter a name to be used in the XML output for this map.

    Output: Choose Auto, Yes, or No to decide whether to include this map in the XML output. Choosing Auto exports the contents of the map.

    Add a Map to a Report

    1. From the Visual Studio toolbox, drag a Map control onto the design surface.
    2. In the Select a Map Template wizard that appears, select a map template from the following options:
      Select a Map Template wizard

      • Empty map: An empty map without any predefined data. 
      • USA map: A map with the predefined polygon layer that contains the embedded spatial data with the USA map.
      • From ESRI file: Select from your local .shp file, the shapefile spatial data format that complies with the Environmental Systems Research Institute, Inc. (ESRI). An ESRI Shapefile is a collection of files, where a .shp file defines the geographical or geometrical shapes and the .dbf file provides attributes for the shapes in the .shp file. To successfully add spatial data using this option, both files (.shp and .dbf) must be copied to the same folder. ESRI files are available on public domain data sources on the Web, including government and university sites. For more information, checkout the TIGER/Line Geodatabases article.

    For more information on adding a map, see tutorial on Map Data Region in Reports.

    Add Data to a Map

    The Map data region uses two types of data - spatial data and analytical data

    Spatial Data

    Spatial data is a set of coordinates that defines a map element. Each map layer must have spatial data of one of the following types - a polygon, a line, or a point.

    Spatial data can be either embedded in a map or can be linked to a map layer. The only difference between the two is that while having the spatial data embedded in a map, there is no separate file to locate or to keep track of when you move the report between projects or machines.

    Analytical Data

    Analytical data is the data that you want to visualize on the map, for example, tourist attractions in a city or product sales by region. For analytical data, you can associate it with map elements by indicating match fields in the Match box of the Map Layer Data Properties dialog. You can use one or more fields in the Match box of the Map Layer Data Properties dialog; for each spatial data field you must indicate a unique analytical data field. This data is optional.

    You can get analytical data from the following types of data sources.

    See Add Data to a Map tutorial.

    Map Layers

    A map is a collection of layers that display data on the map control.

    A map can have one or more layers. You can load these layers on top of each other to create a more detailed map. For example, a polygon layer can represent the borders of a country, a line can represent transportation routes, a point can represent the locations and a tile can add a virtual earth background on the map. See Use Map Layers for more information.

    Map layer element appearance:

    Map Layer Data Dialog

    The Map layer Data dialog is used to set up spatial and analytical data for the map control. For more information on spatial and analytical data, see Add Data to a Map.

    Spatial data source: Select one of the spatial data source connection types:

    • Embedded: The map layer data is loaded from the .shp data source that you embed into the map layer by indicating the .shp file in the Import spatial data from file: field. This field appears below when you select this option.

      Spatial fields: Use the plus sign button to add a field, and the X button to delete a field. For each newly added spatial field, you must specify the name and type in the corresponding fields below.

      Field name: Enter a name of a spatial field.

      Field type: Select the type of a spatial field from the list.

    • Linked: The map layer data is linked to the .shp file and is uploaded at report rendering. You select this type of data source by indicating the .shp file in the File Name field that appears.
    • Dataset: The map layer data is loaded from the data source of the report. In the Dataset field and in the Field name field that appear below, select a dataset from the bound data source and a dataset field.
      Caution: In Field name, simply type the name of the dataset field that contains spatial data. For example, enter the dataset field name as StateName, not as =[StateName]. 
    • Analytical data: The map layer data is loaded from the the analytical dataset of the bound report data source. In the Field name field that appears below, you must set the name of the data field that contains spatial data in the Analytical dataset.
    Caution: In Field name, enter the data field name as =[StateName], not as StateName. 

    Dataset: Select the dataset for the analytical data to be displayed on the map layer.

    Match: Use the plus sign button to add a relationship between a spatial data field and an analytical data field.

    Spatial field: A field with spatial data that specifies an element on the map surface, for example, boundaries of a country.

    Analytical field: A field with analytical data that displays information on the related map element, for example, the country population.

    The Filters page of the Map Layer Data Properties dialog allows you to filter the data that is included in the map. Use the plus sign button to add a filter, and the arrow and X buttons to move or delete filters. You need to provide three values to add a new filter to the collection.

    Expression: Enter the expression to use for evaluating whether data should be included in the map.

    Operator: Select from the following operators to decide how to compare the expression to the left with the value to the right:

    • Equal Only choose data for which the value on the left is equal to the value on the right.
    • Like Only choose data for which the value on the left is similar to the value on the right.
      For more information on using the Like operator, see the MSDN Web site.
    • NotEqual Only choose data for which the value on the left is not equal to the value on the right.
    • GreaterThan Only choose data for which the value on the left is greater than the value on the right.
    • GreaterThanOrEqual Only choose data for which the value on the left is greater than or equal to the value on the right.
    • LessThan Only choose data for which the value on the left is less than the value on the right.
    • LessThanOrEqual Only choose data for which the value on the left is less than or equal to the value on the right.
    • TopN Only choose items from the value on the left which are the top number specified in the value on the right.
    • BottomN Only choose items from the value on the left which are the bottom number specified in the value on the right.
    • TopPercent Only choose items from the value on the left which are the top percent specified in the value on the right.
    • BottomPercent Only choose items from the value on the left which are the bottom percent specified in the value on the right.
    • In Only choose items from the value on the left which are in the array of values specified on the right.
      Selecting this operator enables the Values list at the bottom.
    • Between Only choose items from the value on the left which fall between the pair of values you specify on the right. Selecting this operator enables two Value boxes instead of one.

    Value: Enter a value to compare with the expression on the left based on the selected operator. For multiple values used with the Between operator, the lower two value boxes are enabled.

    Values: When you choose the In operator, you can enter as many values as you need in this list.

    Value: Enter a value to compare with the expression on the left based on the selected operator. For multiple values (used with the In and Between operators) separate values using commas.

    Color, Marker, and Size Rules

    Rules apply properties to a layer when the layer has map elements that have a relationship to analytical data. For example, the color rule varies map element color based on color palette, color range, custom colors, and further specify the distribution option to control display values.

    The type of rule depends on the layer type. For example, use point size rules to vary bubble size based on population.

    See Use Color Rule, Marker Rule, and Size Rule for more information.

    See Also