This is an archive related to a previous version of Esri Maps for SharePoint. If you need the current version go to http://doc.arcgis.com/en/maps-for-sharepoint/.

Best practices: Designing and displaying dialog boxes

When designing and displaying dialog boxes in your map application, there are many factors to consider, such as how to display the user interface (UI); the overall design and theme; how to achieve smooth integration with the existing application framework; and whether there are actions you want to perform as the dialog box is closing or once it has closed, such as removing a layer from the map.

Displaying the UI

To display the UI (dialog box) within the Map Web Part, the extensibility application programming interface (API) provides two methods—ShowWindow and HideWindow. These methods are available from MapApplication.Current. The MapApplication.Current.ShowWindow method displays any FrameworkElement in a floating dialog box. Pass the object you want to display with the title of the dialog box as a string to the ShowWindow method to display a dialog box. The ShowWindow method optionally accepts a Boolean to determine whether the dialog box is modal, an event handler that is called when the dialog box has started closing, and a second event handler that is called when the dialog box completes closing. To close the dialog box, pass the same FrameworkElement to the MapApplication.Current.HideWindow method.

If you are implementing a command, display the UI as soon as the button is clicked (that is, the command is executed). If your command requires the user to interact with the map, the UI should indicate this.

When using ShowWindow, set the background of your UI to be transparent. The dialog box containing your UI will base its background color on the application’s theme colors, which are configurable by users who are designing the application.

For an example of displaying the Silverlight UI in the ArcGIS Map Web Part, suppose that you have implemented the UserControl with the default code-behind class and the Extensible Application Markup Language (XAML) as follows:

<UserControl x:Class="MyExtension.SimpleDialog"
     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
     xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
     xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
     mc:Ignorable="d"
     d:DesignHeight="300" d:DesignWidth="400">
     <Grid x:Name="LayoutRoot" Background="Transparent">
          <TextBlock Text="This is my Silverlight UI!" Margin="20" />
     </Grid>
</UserControl>

A tool that shows this control in a dialog box when the tool is executed would be implemented as follows:

[Export(typeof(ICommand))]
[DisplayName("Show A Simple Dialog")]
[Category("My Tools")]
[Description("Tool to show a simple dialog")]
[DefaultIcon("<Insert path to icon>")]
public class ShowDialogCommand : ICommand
{
     private SimpleDialog dialog = null;
     public void Execute(object parameter)
     {
          // Instantiate a new dialog if one does not already exist.
          dialog = dialog ?? new SimpleDialog();
 
          // Display the dialog.
          MapApplication.Current.ShowWindow("Simple Dialog", dialog);
     }    
 
     public bool CanExecute(object parameter)
     {
          // Return true so that the command is always enabled.
          return true;
     }
 
     public event EventHandler CanExecuteChanged;
}

In a Map Web Part that has the default theme, this dialog box appears as follows:

Viewer standard dialog box

Layout customization

Use layout customization to add UI (for example, panels) to the application that you don’t want to appear in a floating dialog box. If the UI should always be visible, include it in the layout. To give the user the ability to turn the UI on and off, you can do the following:

  • Include a close button or similar element on the UI that sets the Visibility property to Collapsed.
  • Create a tool (that is, implement ICommand) that finds the control by using MapApplication.Current.FindControlInLayout and then sets its Visibility property to Visible.

Do not programmatically walk the visual tree to dynamically add elements to the application. This approach requires the visual tree to be structured a particular way, and is thus inherently brittle. Code that does this may break from layout to layout and release to release.

Brushes

The Extensibility assembly includes a set of brushes that are used within the ArcGIS Map Web Part. Use the built-in brushes to color your UI. This keeps the colors of your UI consistent with those of the application and allows end users to configure them through the theme controls.

The following brushes are available:

  • BackgroundGradientBrush—In the default set of layouts, this is used as the primary background color. This is used as the background for dialog boxes and the side panel.
  • BackgroundStartGradientStopColorBrush—References the start color of BackgroundGradientBrush.
  • BackgroundEndGradientStopColorBrush—References the end color of BackgroundGradientBrush.
  • BackgroundTextColorBrush—Meant to be used for the color of text that is overlaid on the background brushes.
  • AccentColorBrush—In the default set of layouts, this color is used to contrast with the background colors, for example, on borders, scroll bars, and buttons.
  • AccentTextColorBrush—Meant to be used for the color of text that is overlaid on the background brushes.
  • SelectionColorBrush—This is intended to be used as the color of selected elements, for instance, to highlight the selected layer in Map Contents.
  • SelectionOutlineColorBrush—Meant to be used in conjunction with SelectionColorBrush to outline selections. This color is used to outline the selected layer in Map Contents.

Actions on closing the dialog box

To initiate an action when a window shown by your add-in is closed, pass an event handler to the onHidingHandler or onHideHandler parameter of the MapApplication.Current.ShowWindow method.

  • onHidingHandler—Allows you to perform some logic before the window has closed and, if necessary, cancels the window close operation. You might use this, for example, if the user closes the window during an operation and you want to prompt them as to whether they want to stop the operation.
  • onHideHandler—For performing logic after the window has closed. You might use this, for example, to remove a results layer from the map.