Best Practices: Designing and displaying dialogs

When designing and displaying dialogs in your map application, there are many factors to consider such as how to surface the 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 is closing or once it has closed, such as removing a layer from the map.

Displaying a user interface (dialog)

To surface UI within the Map Web Part, the extensibility API provides two methods—ShowWindow and HideWindow. These methods are available off of MapApplication.Current. ShowWindow will display any FrameworkElement in a floating dialog window. To do so, pass the object you want to display to the ShowWindow method. This method also takes the title of the dialog as a string, and optionally accepts a boolean to determine whether the dialog is modal, an event handler that is called when the dialog has started closing, and a second event handler that is called when the dialog completes closing. To close the dialog, simply pass the same FrameworkElement to the HideWindow.

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 tell them this.

When using ShowWindow, the background of your UI should usually be transparent. The dialog containing your UI will have its own background color, which is made to be consistent with the colors of the application. The background color of the dialog taps into the application’s theme colors, which are configurable by users who are designing the end application.

For an example of displaying Silverlight UI in the Map Web Part, suppose that you have implemented the UserControl with the default code-behind class and the XAML markup shown below:

<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 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 will appear as follows:

Viewer standard dialog

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

Never programmatically walk the visual tree to dynamically add elements to the application. This approach will require 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

Use the built-in brushes to color your UI. The Extensibility assembly includes a set of brushes that are used within the Map Web Part. Users can manipulate the color of these brushes by configuring the theme colors, which in turn will set the colors of the application. Wherever possible, you should use the same set of brushes within your UI. This will keep the colors of your UI consistent with those of the application, as well as allow end-users to configure them. To use these brushes, add the following to a Resources collection in your add-in:

<ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
        <ResourceDictionary Source="/ESRI.ArcGIS.Client.Extensibility;component/Themes/Common.Theme.xaml" />
    </ResourceDictionary.MergedDictionaries>
</ResourceDictionary>

The following brushes are available:

Actions on closing the dialog

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.

8/12/2011