ProGuide Style Guide

Language:      C# and Visual Basic
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <[email protected]>
Organization:  Esri, http://www.esri.com
Date:          12/30/2016
ArcGIS Pro:    1.4
Visual Studio: 2013, 2015

This guide is a reference for styling UI Components in your add-in and configuration. ArcGIS Pro provides developers with various XAML Styles to use for styling WPF UI components. ArcGIS Pro Framework will use the correct styling for the Dark and Light themes when the built-in Pro Styles are used. Refer to the UI Controls listed below for their available ESRI styles.

Certain UI elements such as TextBlocks, radio buttons, etc do not need any styling. ArcGIS Pro will automatically style them using the "Default" style. Certain UI elements such as Buttons, ListBoxes will have to be styled so that they work well within ArcGIS Pro.

• User Control
• Windows
• Brushes
• Button
• Check boxes
• Colors
• Combo boxes
• DataGrid
• Expanders
• Galleries
• Hyperlinks
• Label
• List Box
• Message boxes
• Radio Buttons
• Textblocks
• Textbox

---

ArcGIS Pro XAML styles should be used as DynamicResources while styling the UI elements in an add-in. Add this code snippet to your xaml so that these Dynamic resources will load in Design mode in Visual Studio.

<UserControl ...
      xmlns:extensions="clr-namespace:ArcGIS.Desktop.Extensions;assembly=ArcGIS.Desktop.Extensions"
      ...>
<UserControl.Resources>
  <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
     <extensions:DesignOnlyResourceDictionary Source="pack://application:,,,/ArcGIS.Desktop.Framework;component\Themes\Default.xaml"/>
            </ResourceDictionary.MergedDictionaries>
      </ResourceDictionary>
 </UserControl.Resources>

User Control

Default Style: Yes

Avoid setting a background brush for a User Control. User controls will automatically inherit the correct background brush for Light and Dark themes. If you do have to set the background, use one of these Esri brushes.

To style UI elements within the user control, refer to the TextBlocks, Brushes, buttons, etc., sections in this wiki.

###Windows

Default Style: Yes

Custom windows within add-ins should derive from ArcGIS.Desktop.Framework.Controls.ProWindow to inherit a correctly styled Title Bar and background (by default, in Visual Studio a custom window will be derived from System.Windows.Window). If you do have to set the window background, use one of these Esri brushes.

Note that in the example code below the System.Windows.Window has been changed to a ArcGIS.Desktop.Framework.Controls.ProWindow:

<controls:ProWindow x:Class="Geocode.GeocodeWindow"
     …
     xmlns:controls="clr-namespace:ArcGIS.Desktop.Framework.Controls;assembly=ArcGIS.Desktop.Framework"
     …
     Height="150" Width="420" Title="Geocode">

public partial class GeocodeWindow : ProWindow
    {

Brushes

In most cases ArcGIS Pro will set the correct default foreground and background brushes. However, if you do need to explicitly set the foreground or background colors you must use an Esri brush . "Esri" brushes will resolve to the correct Light or Dark color variant depending on the corresponding theme of Pro.

For example, Esri_White uses the color white for Light theme and the color black (the reverse) for Dark theme. Vice versa for Esri_Black. This is true of all the other brushes. Each brush has a light and dark equivalent.

Available Esri Brushes

Button

Default Style: No
Available Styles:

Style name	Button
Esri_SimpleButton	Simple button with border
Esri_SimpleBorderlessButton	Simple borderless button
Esri_CloseButton	Close button
Esri_BackButton	Back button
Esri_BackButtonSmall	Small back button
Esri_ForwardButtonSmall	Small forward button
Esri_UpButtonSmall	Small up button
Esri_DownButtonSmall	Small down button
Esri_BorderlessUpButton	Borderless up button
Esri_ForwardButtonSmall2	Borderless forward button

Buttons have no default style. You have to apply one of the available Esri styles listed above to a button element.

Do not specify button attributes such as Foreground, Background, unless you want to override the Esri styles.

####Buttons

• Button with border

 <Button Style="{DynamicResource Esri_SimpleButton}">
   Button
 </Button>

• Borderless button

 <Button Style="{DynamicResource Esri_SimpleBorderlessButton}">
   Button
 </Button>

• Close button

 <Button Style="{DynamicResource Esri_CloseButton}">
 </Button>

Arrow Buttons

• Large Arrow Button

 <Button Style="{DynamicResource Esri_BackButton}">
 </Button>

• Small Arrow Buttons

 <Button Style="{DynamicResource Esri_BackButtonSmall}">
 </Button>

 <Button Style="{DynamicResource Esri_ForwardButtonSmall}">
 </Button>

 <Button Style="{DynamicResource Esri_UpButtonSmall}">
 </Button>

 <Button Style="{DynamicResource Esri_DownButtonSmall}">
 </Button>

• Borderless Arrows

 <Button Style="{DynamicResource Esri_BorderlessUpButton}">
 </Button>

 <Button Style="{DynamicResource Esri_ForwardButtonSmall2}">
 </Button>

###Check Boxes

Default Style: Yes

If needed, style the individual properties such as Background/Foreground by using Esri brushes. FontFamily property will be ignored.

<CheckBox Content="CheckBox" Background="{DynamicResource Esri_Blue}" 
        Foreground="{DynamicResource Esri_Green2}" 
        BorderBrush="{DynamicResource Esri_Red1}"></CheckBox>

Colors

Most of the time colors are already set in the default and explicit control styles. For example, you do not need to set the color for a hyperlink control or a button's hover color. When you do need to set a color, make sure you are using an Esri color .

In the majority of cases you will be working with brushes, not with WPF Colors. But in certain situations you may need colors. Esri colors are prefixed with "Esri_Color_". Example: A drop shadow or other highlight color for custom styling of list box items, hover text colors or tooltips.

Available Esri Colors

     <Border BorderBrush="{DynamicResource Esri_Gray155}" BorderThickness="1">
       <Border.Effect>
         <DropShadowEffect Color="{DynamicResource Esri_Color_Gray145}" Opacity="0.4"/>
      </Border.Effect>
     ...
    </Border>

###Combo Box

Default Style: Yes

ArcGIS Pro provides default styling for text content of a Combo box control, including mouse over behavior and selection highlight. If needed, style the individual properties such as Background/Foreground by using Esri brushes. FontFamily property will be ignored.

<ComboBox Background="{DynamicResource Esri_Blue}" 
          Foreground="{DynamicResource Esri_Green2}">
                <ComboBoxItem >Item1</ComboBoxItem>
                <ComboBoxItem >Item2</ComboBoxItem>
                <ComboBoxItem >Item3</ComboBoxItem>
</ComboBox>

###DataGrid

Default style: No
Available styles: Esri_DataGridStyle

In a DataGrid control, delete any properties setting the AlternateBackgroundColor. The Esri_DataGridStyle sets these properties so they are NOT needed.

  <DataGrid Style="{DynamicResource Esri_DataGridStyle}"
          ScrollViewer.CanContentScroll="True"      
          AutoGenerateColumns="True"
          HorizontalAlignment="Stretch"
          HeadersVisibility="Column"
          ItemsSource="{Binding Path=GdbDefinitions, Mode=OneWay}">
  ..
  />

###Expanders

Default Style: No
Available Styles:

Style name	Expander
Esri_ExpanderHeader	Header can be defined as a string or element in expander
Esri_ExpanderNoBorder	Expander without a border
Esri_ExpanderWithBorder	Expander with a border
Esri_ExpanderWithGripper	Expander with a gripper
Esri_ExpanderWithPlusButton	Expander with a plus button
Esri_ExpanderWithPlusButtonAndGripper	Expander with plus button and gripper

###Galleries

Default Style: Yes
Available styles: GalleryItemBackground, GalleryItemTextStyle

Default background and text styling for gallery items

By default, each item in a gallery has a transparent background in the light theme and a dark background in the dark theme in Pro.

Custom background and text styling for gallery items

In some cases, your gallery items will not display clearly in the Dark theme because the items are also dark. You can use the custom Esri Gallery styling in these cases. For example, in ArcGIS Pro the North Arrow gallery for Layouts displays all the items with a white background. If you need a white background for each item in a gallery in dark theme, you can style these items using the following Esri styles:

#####GalleryItemBackground Changes the background color of the gallery item to Esri_White in Dark and High Contrast Mode. In the light theme it is transparent.

#####GalleryItemTextStyle Changes the foreground color of the text to Esri_Gray155 in Dark theme and in the light theme. System color is used in High Contrast mode.

<DataTemplate x:Key="InlineGalleryItemTemplate">
    <Grid Background="{DynamicResource GalleryItemBackground}" ..>
        <Grid.RowDefinitions>
           ...
        </Grid.RowDefinitions>         
          <TextBlock Foreground="{DynamicResource GalleryItemText}" .../>
   </Grid>
</DataTemplate>

###Hyperlinks

Default Style: Yes

ArcGIS Pro will automatically style a WPF Hyperlink element in an add-in. The styling used by Pro for hyperlinks is listed below.

Style	Type	Weight*	Size*	Brush*
	Regular	12pt	Use XAML Hyperlink element	Esri_Green4

        <TextBlock>
            <Hyperlink NavigateUri="http://esri.com/">
                  Esri
             </Hyperlink>
        </TextBlock>

###Label

Default Style: Yes

If needed, style the individual properties such as Background/Foreground by using Esri brushes. FontFamily property will be ignored.

<Label Content="My Label" Background="{DynamicResource Esri_Blue}" 
                          Foreground="{DynamicResource Esri_Green2}"></Label>

List Box

Default style: No
Style name: Esri_HighlightListBoxItem

A ListBox control has no default Esri style. You have to use the Esri_HighlightListBoxItem Esri style to style a ListBox control. Pro will provide default styling for the list box items if the content is text. This includes mouse over behavior and selection highlight. If the list box items need to be styled, Esri brushes and colors should be used.

List Box with Text items

<ListBox ItemContainerStyle="{DynamicResource Esri_HighlightListBoxItem}"
         BorderBrush="{DynamicResource Esri_Gray160}" BorderThickness="2">
         ...
</ListBox>

List Box with custom items

 <DataTemplate x:Key="BookmarkListItem" DataType="{x:Type mapping:Bookmark}">
        <StackPanel Orientation="Vertical" Background="Transparent">
          <Image Source="{Binding Thumbnail}"
                                Width="96" Height="96" Stretch="Fill" Margin="5"
                                DockPanel.Dock="Left" ToolTip="{Binding Name}">
            <Image.Effect>
              <DropShadowEffect Color="{DynamicResource Esri_Color_Gray145}" BlurRadius="14" ShadowDepth="4.5">
              </DropShadowEffect>
            </Image.Effect>
          </Image>
          <StackPanel Orientation="Horizontal" Margin="5" >
            <TextBlock Text="{Binding Name}" Margin="5,0,0,0" Style="{DynamicResource RegularText}" />
            <Button x:Name="DeleteButton" Width="16" Height="16"  Margin="0" Style="{DynamicResource Esri_SimpleBorderlessButton}" 
                        ToolTip="{Binding RelativeSource={RelativeSource Mode=FindAncestor, AncestorType=UserControl}, Path=DataContext.DelBookmarkToolTip}"
                        Command="{Binding RelativeSource={RelativeSource Mode=FindAncestor, AncestorType=UserControl}, Path=DataContext.DelBookmarkCommand}" >
              <Image Stretch="None" Width="16" Height="16" VerticalAlignment="Top" Source="pack://application:,,,/ArcGIS.Desktop.Resources;component/Images/BookmarkRemove16.png"/>
            </Button>
          </StackPanel>
        </StackPanel>
      </DataTemplate>

###Message Boxes

Default Style: Yes

Message boxes cannot be styled. Use ArcGIS.Desktop.Framework.Dialogs.MessageBox to get the Pro look and feel for Message box functionality.

 ArcGIS.Desktop.Framework.Dialogs.MessageBox.Show(
                    "Please add the 'States' layer to the TOC from the Pro community samples AdminData.gdb geodatabase.",
                    "Cannot find US States");

###Radio Buttons

Default Style: Yes

If needed, style the individual properties such as Background/Foreground by using Esri brushes. FontFamily property will be ignored.

<RadioButton  Content="Add" Background="{DynamicResource Esri_Blue}" 
              Foreground="{DynamicResource Esri_Green2}" 
              BorderBrush="{DynamicResource Esri_Red1}"></RadioButton>

Textblocks

Default Style:Yes
Style name: See table below

If a style is not specified for a textblock element in an add-in, ArcGIS Pro will use the RegularText style. ArcGIS Pro has many TextBlock styles defined that can be used in an add-in. Refer to the table below for the available styles and the appropriate UI text element for which it should be used.

If needed, style the individual properties of the TextBlock such as Background/Foreground by using Esri brushes.

####Available Styles

Style	Type	Weight*	Size*	Brush*
DockPaneHeader		Light	18pt	Esri_Gray145
RegularText		Normal	12pt	Esri_Gray155
H3TextBlock		SemiBold	14pt	Esri_Gray155
H4TextBlock		SemiBold	13pt	Esri_Gray145
H5TextBlock		SemiBold	11pt	Esri_Gray160
H6TextBlock		Normal	11pt	Esri_Gray155
H7TextBlock		Light	11pt	Esri_Gray155

*Brush, Weight and Size are for reference only. Font Styles have the correct color applied and should not be modified.

<TextBlock Style="{DynamicResource DockPaneHeader}" Text="Dockpane Header" />
<TextBlock Style="{DynamicResource RegularText}" Text="Default font" />
<TextBlock Style="{DynamicResource H3TextBlock}" Text="H3 content Header" />
<TextBlock Style="{DynamicResource H4TextBlock}" Text="H4 Sub content Header" />
<TextBlock Style="{DynamicResource H5TextBlock}" Text="H5 Expander header" />
<TextBlock Style="{DynamicResource H6TextBlock}" Text="H6 Input fields and tables" />
<TextBlock Style="{DynamicResource H7TextBlock}" Text="H7 sub text" />
       

###Textbox

Default Style: Yes

If needed, style the individual properties such as Background/Foreground by using Esri brushes. FontFamily property will be ignored.

<TextBox Background="{DynamicResource Esri_Blue}" 
         Foreground="{DynamicResource Esri_Green2}"></TextBox>