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:
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:
- Include a close button or similar on the UI that sets the Visibility property to Collapsed
- Create a tool (i.e. implement ICommand) that finds the control by using MapApplication.Current.FindControlInLayout, then sets its Visibility property to Visible. Note:
Since layouts will not necessarily include your UI, be sure to handle the case where FindControlInLayout returns null.
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:
- BackgroundGradientBrush—in the default set of layouts, this is used as the primary background color. This is used as the background for dialogs 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. This color is used, for example, on borders, scrollbars, 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. This color is used, 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
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.
- onHidingHandler allows you to perform some logic before the window has closed and, if necessary, cancel the window close operation. You might use this, for example, if the user closes the window during an operation and you wish to prompt them as to whether they want to abort the operation.
- onHideHandler is for performing logic after the window has closed. You might use this, for example, to remove a results layer from the map.