In this topic
By following the guidelines below, you can create add-ins for your users that will look and feel like they are part of the Explorer application along with the built-in functionality.
Explorer’s look and feel for dockable windows, dialogs and wizards is based on the Windows Vista design guidelines. Vista introduces some new UI components and styles that help to streamline and clarify the windows user interface. This document describes the standard graphical layout of dockable windows, dialogs and wizards to ensure a consistent look and feel to the application.
While these guidelines are based on Vista, the same principals apply to Windows XP. Cases where there might be incompatibilities when developing your add-in on XP are noted.
UI appearance
Fonts
Following the Windows Vista design guidelines, the standard font for user interface components such as DockableWindows or other forms or dialogs is Segoe UI. Use the following properties in Visual Studio:
- Font Name: Segoe UI
- Font Size: 8.25 points
- ForeColor: ControlText system color
This default font should be used throughout your UI unless otherwise noted in these guidelines –for example different standards are noted below for dialog headings.
Segoe UI Font on Windows XP
The Segoe UI font is available on the Vista operating system, but is not included on Windows XP by default. However, installing Office 2007 on Windows XP will install the Segoe UI font. In cases where the Segoe UI font is not present on a Windows XP machine, it is substituted with Microsoft Sans Serif. If you are developing add-ins on Windows XP and do not have the Segoe UI font, use Microsoft Sans Serif.
Note that in order for fonts to appear correctly on Windows XP machines, it is recommended that fonts are set to Clear Type in the windows Display Properties Effects dialog. To open this dialog, open the Control Panel, choose Display, choose the Appearance tab, and then click the Effects button. In the dialog that opens, then check the box next to ‘Use the following method to smooth the edges of screen fonts’, and choose Clear Type from the drop-down box below.
Buttons
Generally, buttons in dockable windows and dialogs should use the following sizes, unless noted elsewhere in this document:
- Buttons with a text caption should generally be 75 x 24 pixels.
- If a caption on a button is too long to fit within the standard size, the Width can be increased to accommodate the caption text. Do not increase the Height of the button in order to wrap text into multiple lines.
- Buttons with icons should be 24 x 24 pixels.
Help links
It’s often necessary to include a link on a dialog or wizard that takes users to a help topic related to the dialog. ArcGIS Explorer provides an online help system hosted in a web browser. You can provide help pages for your own help topics by hosting similar pages on your web server.
In your user interface, add a LinkLabel control to allow the user to open your help topic. Add this alongside a PictureBox control which displays a help icon.
The LinkLabel Text should be specific and relate to the dialog or form – for example in the Add Text File wizard in ArcGIS Explorer, the label text is ‘Help about adding text files’. Based again on the default font, ensure you are using the following properties for the LinkLabel control in Visual Studio:
- Font Name: Segoe UI
- Font Size: 8.25 points
- ForeColor: ControlText system color
- ActiveLinkColor: HotTrack system color
- LinkColor: HotTrack system color
- LinkVisited: False
In addition, the LinkLabel distance from the PictureBox showing the help icon should be 10 pixels.
Use the standard windows help icon as the image for the PictureBox – you can find this icon in the Visual Studio 2008 Image Library which is installed with Visual Studio. By default, this library of icons is installed to \...\Program Files\Microsoft Visual Studio 9\Common7\VS2008ImageLibrary\, and you can extract the icon from the Help.png image found in the \_Common Elements\Objects subfolder of the library. For more information about the Visual Studio 2008 Image Library, refer to MSDN.
Icons and images
ArcGIS Explorer uses a set of icons with a consistent look and feel. The Developer Kit install provides a set of icons you can use for your customizations. Using this set of icons where feasible helps your add-in maintain the look and feel of the core application. You can find these icons in the \Icons subfolder of the Developer Kit install location, and also refer to the ArcGIS Explorer Icons help topic for more information.
As described in this topic, you may wish to combine multiple icon components together to form new composite icons.
If your add-in adds Notes or other data using a specific symbol, an alternative pattern is to re-use the symbol of the data within the user interface. For example, if a Button on the Ribbon is used to add Notes with the School symbol, then you may wish to use the same School image for the Button, ComboBox, Gallery or DockWindow button on the Ribbon.
Tab order
When designing user interface components, careful attention should be given to the order in which controls will gain focus when the user presses Tab to move through the controls. The typical tab index order is left to right, then top to bottom.
Set the TabIndex property of the controls on the form to ensure the tabbing order of the controls is reflects the layout of the form.
Dockable window layout
Dockable windows house interactive user interfaces like the contents window, find window, measure window and so on. Each has a specific design associated with it. The following summarizes the styles to use for a dockable window.
Form properties
Dockable windows are UserControls with the following properties in addition to the general appearance and font properties noted above:
- BackColor: Window system color
- BorderStyle: FixedSingle
Note that dockable windows do not include main instructions.
Execute buttons
Common to many dockable windows is a command button that executes the main function of the add-in. This control is usually placed in the bottom right of the dockable window, as illustrated below in the Directions and Route dockable windows.
Note that the Text of the button should be specific to the add-ins functionality – for example ‘Get Route’ and ‘Get Directions’; avoid using button text like ‘Go’, ‘OK’ or ‘Execute’.
An alternative is to break functionality into smaller steps. For example, the Find window has an icon button to initiate the call to find a place. Once the list of found places is populated, the user can right-click and add any of the found places to the map as a Note. As the Find functionality is presented in multiple steps, there is no single execute button in the dockable window; instead functionality is split between icon buttons at the top left of the dockable window, and the context menu of the list box in the center.
Some dockable windows allow a shortcut of this interaction using the Enter key. For example, when using the Find dockable window, the user can press the Enter key while focus is on the main Textbox in order to execute the same functionality as clicking the Find icon button. You are encouraged to replicate this pattern of interaction by using the KeyUp or KeyDown events where appropriate to execute code when the Enter key is pressed.
Form and dialog layout
In addition to dockable windows, you may create other types of forms and dialogs as part of your add-in to display to the user. For example, a Button may show a wizard, or a modal dialog box.
Form properties
The following summarizes the properties to use for forms and dialogs in ArcGIS Explorer, in addition to the general appearance and font properties noted above:
- Text: This property sets the text shown in the title bar of the form, and should include the text from the button that opens the dialog; for example, the Manage Layers button on the Ribbon opens a dialog with the title Manage Layers.
- BackColor: Control system color
- FormBorderStyle: FixedDialog
- ShowIcon: False
- ShowInTaskbar: False
- MinimizeBox: False
- MaximizeBox: False
If you have a dialog that displays a long list of items in a control that might benefit from being sizable, you may wish to make an exception to the FormBorderStyle rule and make the dialog sizable. If you make the dialog sizable, set the FormBorderStyle property to Sizable and the SizeGripStyle property to Auto. Also, the control area and commit buttons should size and move as appropriate when the dialog is resized.
Control area
The control area houses the main instruction, other detailed text and required controls of the dialog. The control area may also include command links.
The control area is a Panel with a BackColor property set to the Window system color.
See the section below on main instructions and command links.
Button area
The area of the dialog below the control area should contain the commit buttons for the dialog or wizard, for example Back, Next, Finish and/or Cancel buttons.
The button area does not require an additional control to be added, as it is simply the area of the Form underneath the control area.
Commit buttons
The commit buttons dismiss the dialog. All dialogs include a Cancel or Close commit button. Most dialogs will also include one or more commit buttons that perform the action of the dialog.
Commit buttons should avoid generic Text properties where possible and should be specific to the action associated with them. For example, the commit button on the New Link dialog has a Text property of ‘Create’, rather than ‘OK’.
Main Instructions
Forms which present a dialog or a wizard type of interface to the user should include a main instruction – a prominently displayed caption that concisely explains what to do in the dialog box or wizard page. For example, the Add Geodatabase dialog has a main instruction ‘Select a geodatabase’.
Depending on the nature of the dialog or page, the instruction is a specific statement, direction or question. The main instruction should always communicate the user’s objective rather than focus on manipulating the UI itself. The main instruction can be augmented with more detailed information if required, but the main instruction should be sufficient to understand the function of the dialog or wizard page. For example, the Add Geodatabase dialog main instruction does not require a caption in addition to the main dialog, as the controls below are sufficiently clear. However the Application Configuration dialog gives more information to explain what an application configuration is.
Consider adding a main instruction to forms which you open from buttons, galleries or from controls on a dockable window by adding a Label control. Dockable windows themselves should not have a main instruction – for example the Find and Measure dockable windows do not have main instructions.
The main instruction should use a larger size of the default font. Use the following properties in Visual Studio for the main instruction Label control:
- Font Name: Segoe UI
- Font Size: 12 points
- ForeColor: HotTrack system color
If you add explanatory text below the main instruction, use the default font for the additional text.
Command Links
Command links are a special kind of button that used to make a choice from a set of mutually exclusive choices. They include a label and, if necessary, supplemental text which gives a clear indication of what choice the user is making by clicking them.
Command links are used extensively throughout the Vista user interface to simplify the presentation and flow of wizards and dialogs when more information is required in addition to simple choice captions. A good example is the use of command links in the Vista user interface is the additional information given in the Move File dialog when a file with the same name already exists at the new location – by presenting this additional information, the user can make an informed choice without leaving the dialog to investigate further.
When displayed on a dialog box, clicking a command link has the effect of making a choice and closing the dialog box. They provide a clearer user interface choice than making a choice and then choosing from a series of Yes/No/Cancel and OK/Cancel buttons dialogs that are often difficult to interpret.
Command links are natively supported on Windows Vista as part of the operating system (for further information see MSDN http://msdn.microsoft.com/en-us/library/aa511455.aspx). As ArcGIS Explorer is supported on Vista and XP operating systems, you should ideally use controls supported on all these platforms. You may be able to find third party controls which replicate the look and feel of Vista command links on a wider range of operating systems; alternatively you can create your own command links from Label, LinkLabel and PictureBox controls.
Add-in behavior
In addition to user interface appearance, ArcGIS Explorer has certain other behavior patterns which help to produce a consistent application experience. The information below will help you produce add-ins which behave in a similar manner to the core application.
Making use of application conditions
The ArcGIS Explorer application defines a number of possible application states, or 'conditions' which are then used by the Ribbon to determine which tabs or groups to display or hide, and which controls to enable or disable on the Ribbon. Application conditions are used to advertise to the user which functionality applies to the item the user has selected in the map.
Using conditions allows you to avoid writing boilerplate logic code for enabling or disabling add-ins based on application state. Controls on the Ribbon are highly visible to the user, and you may find this approach more effective than in other systems where you add commands to a context-menu (note that you can remove items from the existing context-menus using the Application Configuration Manager, you cannot add your own buttons to context-menus).
You can set a condition for a new add-in in the Visual Studio Tools for ArcGIS Explorer wizards when you create a new add-in project or item. Also see the ArcGIS Explorer Application Conditions topic for more information.
Showing progress
Any unit of work that blocks the UI and takes more than a couple of seconds to complete should always display the progress dialog to indicate to the user that the application is busy. For example, when you switch between 2D and 3D views, the progress dialog displays to indicate that the application is busy and also helps the user understand that no interaction with the application can take place until this operation is complete.
If you have an operation which blocks the UI thread, then you should use the ProgressHelper class in the ESRI.ArcGISExplorer.Application namespace. This class can be used to show the same progress dialog, providing a consistent user experience between built in and customized components.
See the Application namespace overview for more information on how to use the ProgressHelper class.
Setting form owner
You can set the owner of any forms or dialogs you open to be the ArcGIS Explorer application, which ensures that the application is set as the top-level window and parent of the form or dialog you have created.
The Windowproperty of the Application class in the ESRI.ArcGISExplorer.Application namespace returns an IWin32Window reference which you can either set as the Ownerproperty of a form, or pass into the Showor ShowDialogoverloaded methods of a MessageBox or Form.
Programming Patterns
The following programming patterns may also help you to provide a consistent application experience for your add-in users.
Programming for both the 2D and 3D display modes of the MapDisplay
In the majority of cases, the code you write performs the same actions, regardless of whether the Map is in 2D or 3D DisplayMode, for example when adding Notes, Graphics, Layers, working with items selected in the Contents window, connecting to tabular data, and so on. However there are a few cases in which you may want to take specific account of the DisplayMode.
Target property
If currently in 2D DisplayMode, then the MapDisplay.Target property will be null (Nothing in Visual Basic). In code which uses the Target property to find the current center of the map display, the MapDisplay.Center property can be used instead. This property was introduced at ArcGIS Explorer 1500 release, and returns the equivalent of the Target if in 3D, or the center of the map Extent if in 2D mode.
If writing add-ins for releases prior to 1500, Target and MapDisplay.Extent.GetCenter() can be used individually depending on the DisplayMode.
Tracking Result Geometries and Z values
If in 2D DisplayMode, geometries returned from tracking methods (TrackPoint, TrackVector, TrackPolyline, TrackPolygon and their asynchronous equivalents) will return geometries with no elevation values set (Z properties will be NaN); if in 3D mode, the Z will be set equal to the globe surface at the locations tracked.
Reprojecting Geometries
If a geometry has a different coordinate system to the MapDisplay in which it is drawn, it is automatically reprojected at draw time to display correctly in the MapDisplay. This automatic reprojection applies to the geometries used to draw Graphics, Notes, and MapItems. You do not need to add any code for these items to project correctly.
If you intend to work exclusively or predominately within a certain coordinate system, it might be beneficial to project geometries for use in Notes and Graphics to that coordinate system. See the How to project a geometry to a different coordinate system topic for more information on how and in which circumstances it is appropriate to reproject geometries.
Dealing with proxy servers
If your add-in may be used on a network which has proxy servers which require credentials, this can be dealt with using classes from the System.Net namespace, which is part of the .NET Framework. Instead of calling directly to a URL over http, you can use code like that shown below to allow users to enter credentials for the connection.
The code below uses the System.Net.HttpRequest class to attempt a connection to a resource over http, and traps any System.Net.WebExceptions that are thrown. By checking the StatusCode of the System.Net.WebResponse, the reason for the exception can be determined. If the exception is thrown because proxy authentication is required, the WebRequest can be recreated but this time setting the Proxy property of the request, and setting the Credentials of the Proxy using the default network credentials from the System.Net.CredentialCache.
[C#]
string urlString = ; //define the URL to load
// Create an XML document which will be filled from a call to a web service.
System.Xml.XmlDocument doc = new System.Xml.XmlDocument();
// Without accounting for proxy servers, you can load the XmlDocument directly:
// System.Xml.XmlDocument doc = new System.Xml.XmlDocument();
// To account for proxy servers, use an HttpWebRequest and WebResponse instead.
System.Net.HttpWebRequest webRequest = System.Net.WebRequest.Create(urlString)
as System.Net.HttpWebRequest;
System.Net.WebResponse webResponse = null;
try
{
webResponse = webRequest.GetResponse();
}
catch (System.Net.WebException exception)
{
System.Net.HttpWebResponse httpResponse = exception.Response as
System.Net.HttpWebResponse;
if ((httpResponse != null) && (httpResponse.StatusCode ==
System.Net.HttpStatusCode.ProxyAuthenticationRequired))
{
webRequest = System.Net.WebRequest.Create(urlString)as
System.Net.HttpWebRequest;
webRequest.Proxy = new System.Net.WebProxy();
webRequest.Proxy.Credentials =
System.Net.CredentialCache.DefaultNetworkCredentials;
webResponse = webRequest.GetResponse();
}
else
throw exception;
}
// Now load the WebResponse response stream into the XmlDocument.
doc.Load(webResponse.GetResponseStream());
webResponse.Close();
[VB.NET]
String urlString = ' define the URL to load
' Create an XML document which will be filled from a call to a web service.
Dim doc As System.Xml.XmlDocument = New System.Xml.XmlDocument()
' Without accounting for proxy servers, you can load the XmlDocument directly:
' Dim doc As System.Xml.XmlDocument = New System.Xml.XmlDocument()
' To account for proxy servers, use an HttpWebRequest and WebResponse instead.
Dim webRequest As System.Net.HttpWebRequest = CType(System.Net.WebRequest.Create(urlString), System.Net.HttpWebRequest)
Dim webResponse As System.Net.WebResponse = Nothing
Try
webResponse = webRequest.GetResponse()
Catch exception As System.Net.WebException
Dim httpResponse As System.Net.HttpWebResponse = CType(exception.Response, System.Net.HttpWebResponse)
If ((Not httpResponse Is Nothing) AndAlso (httpResponse.StatusCode = System.Net.HttpStatusCode.ProxyAuthenticationRequired)) Then
webRequest = CType(System.Net.WebRequest.Create(urlString), System.Net.HttpWebRequest)
webRequest.Proxy = New System.Net.WebProxy()
webRequest.Proxy.Credentials = System.Net.CredentialCache.DefaultNetworkCredentials
webResponse = webRequest.GetResponse()
Else
Throw exception
End If
End Try
' Now load the WebResponse response stream into the XmlDocument.
doc.Load(webResponse.GetResponseStream())
webResponse.Close()
You should also consider introducing a timeout, to prevent code hanging while waiting for a WebException to be thrown, if you find that this introduces a lengthy delay for users.