ProGuide Style Guide - Esri/arcgis-pro-sdk GitHub Wiki

Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <[email protected]>
Organization:  Esri, http://www.esri.com
Date:          10/06/2024
ArcGIS Pro:    3.4
Visual Studio: 2022

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
• Toggle button
• Check boxes
• Colors
• Combo boxes
• DataGrid
• Expanders
• Galleries
• Hyperlinks
• Image
• Label
• List Box
• List View
• 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>

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.

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
    {

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_TextMenuBrush uses the color white(#FFFFFF) for Light theme and dark gray (#D1D1D1) (the reverse) for Dark theme. This is true of all the other brushes. Each brush has a light and dark equivalent.

Available Esri Brushes

Default Style: No
Available Styles:

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.

• Button with border

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

• Large Arrow Button

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

• Small Arrow Buttons

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

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

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

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

• Borderless Arrows

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

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

Default Style: No
Available Styles:

Toggle buttons have no default style. You have to apply one of the available Esri styles listed above to a toggle buton element.

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

• Simple toggle button

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

• Map and Layout tray toggle button

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

Default Style: Yes Available Styles:

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

<CheckBox Content="CheckBox" Background="{DynamicResource Esri_BackgroundHoverSelectedBrush}" 
        Foreground="{DynamicResource Esri_TextMenuBrush}" 
        BorderBrush="{DynamicResource Esri_BorderHoverBrush}"></CheckBox>

<CheckBox Style="{DynamicResource Esri_CheckboxToggleSwitch}"  Content="Toggle Switch"></CheckBox>

<CheckBox Style="{DynamicResource Esri_CheckboxTrayButtonHeader}"></CheckBox>

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_TextControlBrush}" BorderThickness="1">
       <Border.Effect>
         <DropShadowEffect Color="{DynamicResource Esri_Color_Gray145}" Opacity="0.4"/>
      </Border.Effect>
     ...
    </Border>

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.

<ComboBox Background="{DynamicResource Esri_BackgroundPressedBrush}" 
          Foreground="{DynamicResource Esri_TextMenuBrush}">
                <ComboBoxItem >Item1</ComboBoxItem>
                <ComboBoxItem >Item2</ComboBoxItem>
                <ComboBoxItem >Item3</ComboBoxItem>
</ComboBox>

Default style: No
Available styles:

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

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

Default Style: No
Available Styles:

• Expander without a border

<Expander Style="{DynamicResource Esri_ExpanderBorderless}">
..
 </Expander>

• Expander with a border

<Expander Style="{DynamicResource Esri_Expander}">
..
 </Expander>

• Expander with a gripper

<Expander Style="{DynamicResource Esri_ExpanderGripper}">
..
 </Expander>

• Expander with a plus button

<Expander Style="{DynamicResource Esri_ExpanderPlus}">
..
 </Expander>

• Expander with plus button and gripper

<Expander Style="{DynamicResource Esri_ExpanderGripperPlus}">
..
 </Expander>

Default Style: Yes
Available styles: Esri_GalleryItemBackgroundBrush, Esri_TextGalleryItemBrush

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.

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:

Changes the background brush of the gallery item to 'Esri_ControlBackgroundBrush' (white) in Dark and High Contrast Mode. In the light theme it is transparent.

Changes the foreground brush of the text to a dark gray in light and Dark theme. System color is used in High Contrast mode.

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

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*	Color*
	Regular	12pt	Use XAML Hyperlink element	#548953

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

Default Style: No

Use this Image style for images displayed on a Tray button UI.

 <Image Source="pack://application:,,,/AddInName;component/Images/TrayButtonImage32.png" 
        Style="{DynamicResource Esri_ImageTrayButton}" Height="32" Width="32"></Image>

Default Style: Yes
Default Font Family: Segoe UI

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

<Label Content="My Label" Background="{DynamicResource Esri_BackgroundPressedBrush}" 
                          Foreground="{DynamicResource Esri_TextControlBrush}"></Label>

Default style: No
Available Styles:

A ListBox control has no default Esri style. You have to use the available List box styles 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.

<ListBox ItemContainerStyle="{DynamicResource Esri_ListBoxItemHighlightBrush}"
         BorderBrush="{DynamicResource Esri_TextControlBrush}" BorderThickness="2">
         ...
</ListBox>

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

The Esri_ListBoxPanelIndicator is a custom horizontal ListBox style for strings that adds a separator between the items and draws custom repeat (scroll) buttons when necessary. The items in the List box are of type TabControl topic20573.html. Override the TabControl's Text property to create strings to add to the list box. You can also override the TabControl class' ToolTip property to provide tooltip information for the items in the Listbox.

This style is often used in conjunction with the TabIndicator control.

XAML definition of the Listbox:

<ListBox x:Name="primaryNavigator" DockPanel.Dock="Left" 
               Style="{DynamicResource Esri_ListBoxPanelIndicator}"
               ItemsSource="{Binding PrimaryMenuList}" 
               SelectedIndex="{Binding SelectedPanelHeaderIndex, Mode=TwoWay}"
               IsSynchronizedWithCurrentItem="True"/>

Initialize the TabControl collection in code:

protected Dockpane1ViewModel() //view model constructor
        {
            PrimaryMenuList.Add(new TabControl() { Text = "PaneHeader1", Tooltip = "PaneHeader1 Tooltip" });
            PrimaryMenuList.Add(new TabControl() { Text = "PaneHeader2", Tooltip = "PaneHeader2 Tooltip" });
            //initialize view model to show content when headers are clicked
            _paneH1VM = new PaneHeader1ViewModel();
            _paneH2VM = new PaneHeader2ViewModel();
            _selectedPanelHeaderIndex = 0;
            CurrentPage = _paneH1VM;
        }

Default style: No
Available Styles:

A List view control has no default Esri style. Pro will provide default styling for the list view items if the content is text. This includes mouse over behavior and selection highlight. If the list view items need to be styled, Esri brushes and colors should be used. To style list view items using an Esri style, use Esri_ListBoxItemHighlightBrush.

<ListView ItemContainerStyle="{DynamicResource Esri_ListBoxItemHighlightBrush}"
         BorderBrush="{DynamicResource Esri_TextControlBrush}" BorderThickness="2">
         ...
</ListView >

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");

Default Style: Yes

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

<RadioButton  Content="Add" Background="{DynamicResource Esri_BackgroundPressedBrush}" 
              Foreground="{DynamicResource Esri_TextInfoBrush}" 
              BorderBrush="{DynamicResource Esri_TextStyleSubduedBrush}"></RadioButton>

Default Style:Yes
Default Font Family: Segoe UI
Style name: See table below

If a style is not specified for a textblock element in an add-in, ArcGIS Pro will use the Esri_TextBlockRegular 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.

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

• Default text

<TextBlock Style="{DynamicResource Esri_TextBlockRegular}">Default text</TextBlock>

• H1 Content Header

<TextBlock Style="{DynamicResource Esri_TextBlockH1}">H1 TextBlock</TextBlock>

• H2 Content Header

<TextBlock Style="{DynamicResource Esri_TextBlockH2}">H2 TextBlock</TextBlock>

• H3 Content Header

<TextBlock Style="{DynamicResource Esri_TextBlockH3}">H3 TextBlock</TextBlock>

• H4 Content Header

<TextBlock Style="{DynamicResource Esri_TextBlockH4}">H4 TextBlock</TextBlock>

• H5 Content Header

<TextBlock Style="{DynamicResource Esri_TextBlockH5}">H5 TextBlock</TextBlock>

• H6 Content Header

<TextBlock Style="{DynamicResource Esri_TextBlockH6}">H6 TextBlock</TextBlock>

• H7 Content Header

<TextBlock Style="{DynamicResource Esri_TextBlockH7}">H7 TextBlock</TextBlock>

• Dockpane heading

<TextBlock Style="{DynamicResource Esri_TextBlockDockPaneHeading}">Dockpane heading</TextBlock>

• Dockpane header

<TextBlock Style="{DynamicResource Esri_TextBlockDockPaneHeader}">Dockpane header</TextBlock>

• Dialog header

<TextBlock Style="{DynamicResource Esri_TextBlockDialogHeader}">Dialog header</TextBlock>

• Dialog text

<TextBlock Style="{DynamicResource Esri_TextBlockDialog}">Dialog text</TextBlock>

• Backstage title

<TextBlock Style="{DynamicResource Esri_TextBlockBackStageTitle}">Backstage title</TextBlock>

• Backstage header

<TextBlock Style="{DynamicResource Esri_TextBlockBackStageHeader}">Backstage header</TextBlock>

• Backstage sub-header

<TextBlock Style="{DynamicResource Esri_TextBlockBackStageSubHeader}">Backstage Sub-Header text</TextBlock>

• Backstage group header

<TextBlock Style="{DynamicResource Esri_TextBlockBackStageGroupHeader}">Backstage group header</TextBlock>

• Tray button header

<TextBlock Style="{DynamicResource Esri_TextBlockTrayButtonHeader}">Tray button header</TextBlock>

• Tray button default text

<TextBlock Style="{DynamicResource Esri_TextBlockTrayButton}">Tray button header</TextBlock>

Default Style: Yes
Default Font Family: Segoe UI

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

<TextBox Background="{DynamicResource Esri_BackgroundPressedBrush}" 
         Foreground="{DynamicResource Esri_TextStyleDefaultBrush}"></TextBox>