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 Viewer, the extensibility application programming interface (API) provides two methods—ShowWindow and HideWindow. These methods are available off of MapApplication.Current. The MapApplication.Current.ShowWindow method displays any FrameworkElement in a floating dialog window. To do so, simply pass the object you want to display to the method, along with the title of the dialog box. In addition to the dialog's content and title, the ShowWindow method accepts the following optional arguments:

The ShowWindow method also returns a reference to the FloatingWindow that is shown. Although the ShowWindow method's signature indicates a return type of object, within the Viewer and Application Builder this will reliably be a FloatingWindow instance.

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 have its background color based on the application’s theme colors, which are in turn configurable by users who are designing the application.

For an example of displaying the Silverlight UI in the Viewer, 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 Viewer that has the default theme, this dialog appears as follows:

Viewer standard dialog

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. 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:

  • Include a close button or similar 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, then sets its Visibility property to Visible.
NoteNote:

Since layouts will not necessarily include your UI, be sure to handle the case where FindControlInLayout returns null.

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.

For more information, see Creating a custom layout and the samples in the Controls section of the ArcGIS Viewer for Silverlight interactive samples.

Brushes

The Extensibility assembly includes a set of brushes that are used within the Viewer and Application Builder. 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:

Viewer brushes

Application Builder brushes

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 and/or onHideHandler parameter of the MapApplication.Current.ShowWindow method.

Copyright © 1995-2015 Esri. All rights reserved.
1/26/2015