C# Class ESRI.ArcGIS.Client.Toolkit.Legend

The Legend Control is a User Interface (UI) control which provides useful narrative and graphic descriptions for understanding what is being viewed in the Map. It displays the Layer.ID name, sub-layer name(s) (via the LayerInfo.Name Property), and any associated graphical symbols with their Label(s) (using the LayerItemViewModel.LegendItems Collection). Additionally, ToolTip information can obtained revealing detailed Layer information (such as: Layer.ID, LayerItemViewModel.SubLayerID, LegendItemViewModel.Label, LegendItemViewModel.Description, LayerItemViewModel.MinimumResolution, LayerItemViewModel.MaximumResolution, etc.) when the user hovers the cursor over a Layer/sub-Layer name in the Legend. In its default mode of operation, end-users interact with the Legend Control to expand and collapse the nodes to view as much information as desired about a particular Layer.

In most use cases, developers typically only need to set a few core Properties in order to have a Legend that displays useful information about the Layers in the Map. The core properties are:

The Legend Control is highly customizable such that developers can override the default behavior of the various DataTemplates to alter the behavior of the control to make it behave like a TOC. A TOC provides the same useful narrative and graphical information as a Legend but adds the extra functionality of allowing users to turn on/off the visibility of individual Layers (and their sub-Layers where applicable). Depending on the developers creativity even other specialized functions can be programmed into the DataTemplates to perform functions like: controlling the opacity of individual Layers (and their sub-Layers where applicable), setting thresholds at which scale a particular Layer is visible, allowing for a specific Layer to be selected and highlighted in the Map, and more. Additional details on what parts of the Legend Control can be customized by the various DataTemplate Properties will be discussed later in this document.

The Legend Control can be created at design time in XAML or dynamically at runtime in the code-behind. The Legend Control is one of several controls available in the Toolbox in Visual Studio when the ArcGIS API for Silverlight is installed, The Legend Control is one of several controls available in the Toolbox in Visual Studio when the ArcGIS Runtime SDK for WPF is installed, There are no controls that can be dragged into the XAML design surface from the Toolbox as part of the ArcGIS Runtime SDK for Windows Phone installation. Developers need to type the correct syntax in the XAML to have the controls appear in the visual designer, see the following screen shot:

The default appearance of the Legend Control can be modified using numerous inherited Properties from System.Windows.FrameworkElement, System.Windows.UIElement, and System.Windows.Controls. An example of some of these Properties include: .Height, .Width, .BackGround, .BorderBrush, .BorderThickness, .Foreground, .HorizontalAlignment, .VerticalAlignment, .Margin, .Opacity, .Visibility, etc.

Note: You cannot change the core behavior of the sub-components (i.e. Image, ToolTipService, StackPanel, TextBlock, DataTemplate, Grid, ContentControl, ContentPresenter, ESRI.ArcGIS.Client.Toolkit.Primitives.TreeViewExtended, etc.) of the Legend Control using standard Properties or Methods alone. To change the core behavior of the sub-components and their appearance of the Control, developers can modify the Control Template in XAML and the associated code-behind file. The easiest way to modify the UI sub-components is using Microsoft Expression Blend. Then developers can delete/modify existing or add new sub-components in Visual Studio to create a truly customized experience. A general approach to customizing a Control Template is discussed in the ESRI blog entitled: Use control templates to customize the look and feel of ArcGIS controls. A specific code example of modifying the Control Template of the Legend Control to can be found in the Legend.Map Property document.

Rather than edit the full Control Template of the Legend Control, ESRI has exposed three DataTemplates Properties where developers can target the UI customization to a more limited scope. Each DataTemplate and a description of what part of the Legend Control it has bearing over is listed here:

It should be noted that it is possible to customize one or more of the Legend Control DataTemplates at the same time. There are established default values for each DataTemplate, so setting one will not necessarily override the others that have been set by default. Significant testing should be done on all of the Layers in the customized application to ensure that the desired behavior has been achieved. Some Layers have different behavior in rendering items in the Legend and should be tested thoroughly.

The following screen shot demonstrates which part of the Legend Control corresponds to the three DataTemplates. The Layer (ID = "United States") that is being displayed is an ArcGISDynamicMapServiceLayer with three sub-Layers (ushigh, states, and counties). The information found in the ArcGIS Services Directory about the ArcGISDynamicMapServiceLayer corresponds to what is shown in the Map and Legend Controls.

TIP: It is typically necessary for developers to specify the Layer.ID name for Layers in the Map Control. This can be done in XAML or code-behind. If a Layer.ID value is not specified, then a default Layer.ID value is provided based upon the URL of the ArcGIS Server map service.