Skip to content

ProGuide Style Guide

Jump to bottom
UmaHarano edited this page Nov 6, 2024 · 22 revisions 
Language:      C#
Subject:       Framework
Contributor:   ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
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.

Contents

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.

Dockpane

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
    {

DarkBackground_DialogColor

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

Button

Default Style: No
Available Styles:

Style name Button
Esri_Button Simple button with border
Esri_ButtonBorderless Simple borderless button
Esri_ButtonClose Close button
Esri_ButtonBack Back button
Esri_ButtonBackSmall Small back button
Esri_ButtonForwardSmall Small forward button
Esri_ButtonUpSmall Small up button
Esri_ButtonDownSmall Small down button
Esri_ButtonUpSmallBorderless Borderless up button
Esri_ButtonForwardSmallBorderless 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

Buttons

  • Button with border
 <Button Style="{DynamicResource Esri_Button}">
   Button
 </Button>

Arrow Buttons

Arrow Buttons

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

Toggle button

Default Style: No
Available Styles:

Style name Toggle Button
Esri_ButtonToggle Simple toggle button
Esri_ToggleButtonTrayButton Map and Layout tray toggle button

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>

Check Boxes

Default Style: Yes Available Styles:

Style name Checkbox
Default Simple check box.
Esri_CheckboxToggleSwitch Toggle switch check box
Esri_CheckboxTrayButtonHeader Map and Layout tray buttons toggle check box

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

Dockpane

Default checkbox

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

Toggle switch checkbox

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

Tray buttons toggle check box

CheckboxTrayButton

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

Colors

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.

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

DataGrid

Default style: No
Available styles:

Style name Data grid
Esri_DataGrid Data Grid
Esri_DataGridHeaderless Turns off both row and column headers
Esri_DataGridRowHeaderless Turns off Row headers
Esri_DataGridColumnHeader Applies style to the data grid column header
Esri_DataGridRowHeader Applies style to the data grid row header
Esri_DataGridRow Applies style for the entire row such selection, mouseover, keyboard focus
Esri_DataGridCell Applies style to the individual cell such as selection, mouseover, border

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}">
  ..
  />

DataGrid

Expanders

Default Style: No
Available Styles:

Style name Expander
Esri_ExpanderBorderless Expander without a border
Esri_Expander Expander with a border
Esri_ExpanderGripper Expander with a gripper
Esri_ExpanderPlus Expander with a plus button
Esri_ExpanderGripperPlus Expander with plus button and gripper

Expanders

Expanders

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

Galleries

Default Style: Yes
Available styles: Esri_GalleryItemBackgroundBrush, Esri_TextGalleryItemBrush

Style name Gallery
Esri_GalleryItemBackgroundBrush Background brush of the gallery item
Esri_TextGalleryItemBrush Foreground brush of the gallery item text

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.

RibbonGalleryDark_Type1

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:

Esri_GalleryItemBackgroundBrush

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.

Esri_TextGalleryItemBrush

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>

custom-gallery

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* Color*
Links Regular 12pt Use XAML Hyperlink element #548953 
        <TextBlock>
            <Hyperlink NavigateUri="http://esri.com/">
                  Esri
             </Hyperlink>
        </TextBlock>

Image

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>

TrayButtonImageStyle.png

Label

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>

List Box

Default style: No
Available Styles:

Style name List Box
Esri_ListBoxItemHighlightBrush List box item
Esri_ListBoxPanelIndicator Horizontal ListBox style for strings with a separator between items

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.

List Box with Text items

TextOnlyListBox

<ListBox ItemContainerStyle="{DynamicResource Esri_ListBoxItemHighlightBrush}"
         BorderBrush="{DynamicResource Esri_TextControlBrush}" BorderThickness="2">
         ...
</ListBox>
List Box with custom items

CustomItemsListBox

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

List box panel indicator with separators.

TextOnlyListBox

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

List View

Default style: No
Available Styles:

Style name List View
Esri_ListBoxItemHighlightBrush List view item

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 >

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.

MessageBox

 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.

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

Textblocks

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.

Available Styles

Style Description
Esri_TextBlockRegular Default text
Esri_TextBlockH1 H1 Content Header
Esri_TextBlockH2 H2 Sub Content Header
Esri_TextBlockH3 H3 Content Header
Esri_TextBlockH4 H4 Sub Content Header
Esri_TextBlockH5 H5 Expander Header
Esri_TextBlockH6 H6 Input Fields and table>
Esri_TextBlockH7 H7 Sub Text
Esri_TextBlockDockPaneHeading Dockpane heading
Esri_TextBlockDockPaneHeader Dockpane Header
Esri_TextBlockDialogHeader Dialog Header
Esri_TextBlockDialog Dialog text
Esri_TextBlockBackStageTitle Backstage title
Esri_TextBlockBackStageHeader Backstage header
Esri_TextBlockBackStageSubHeader Backstage SubHeader
Esri_TextBlockBackStageGroupHeader Backstage group header

TextBlocks

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

RegularTextBlocks

  • Default text
Attribute Value
Font Family Segoe UI
Font size 12pt
Font weight Normal
Foreground brush Esri_TextStyleDefaultBrush 
<TextBlock Style="{DynamicResource Esri_TextBlockRegular}">Default text</TextBlock>
  • H1 Content Header
Attribute Value
Font Family Segoe UI
Font size 20pt
Font weight Bold
Foreground brush Esri_Gray155 
<TextBlock Style="{DynamicResource Esri_TextBlockH1}">H1 TextBlock</TextBlock>
  • H2 Content Header
Attribute Value
Font Family Segoe UI
Font size 15pt
Font weight Light
Foreground brush Esri_TextStyleDefaultBrush 
<TextBlock Style="{DynamicResource Esri_TextBlockH2}">H2 TextBlock</TextBlock>
  • H3 Content Header
Attribute Value
Font Family Segoe UI
Font size 14pt
Font weight SemiBold
Foreground brush Esri_Gray155 
<TextBlock Style="{DynamicResource Esri_TextBlockH3}">H3 TextBlock</TextBlock>
  • H4 Content Header
Attribute Value
Font Family Segoe UI
Font size 13pt
Font weight SemiBold
Foreground brush Esri_Gray145 
<TextBlock Style="{DynamicResource Esri_TextBlockH4}">H4 TextBlock</TextBlock>
  • H5 Content Header
Attribute Value
Font Family Segoe UI
Font size 12pt
Font weight SemiBold
Foreground brush Esri_Gray160 
<TextBlock Style="{DynamicResource Esri_TextBlockH5}">H5 TextBlock</TextBlock>
  • H6 Content Header
Attribute Value
Font Family Segoe UI
Font size 11pt
Font weight Normal
Foreground brush Esri_Gray155 
<TextBlock Style="{DynamicResource Esri_TextBlockH6}">H6 TextBlock</TextBlock>
  • H7 Content Header
Attribute Value
Font Family Segoe UI
Font size 11pt
Font weight Light
Foreground brush Esri_Gray155 
<TextBlock Style="{DynamicResource Esri_TextBlockH7}">H7 TextBlock</TextBlock>

Dockpane TextBlocks

DockpaneTextBlocks

  • Dockpane heading
Attribute Value
Font Family Segoe UI
Font size 15pt
Font weight Regular
Foreground brush Esri_TextStyleDefaultBrush 
<TextBlock Style="{DynamicResource Esri_TextBlockDockPaneHeading}">Dockpane heading</TextBlock>
  • Dockpane header
Attribute Value
Font Family Segoe UI
Font size 15pt
Font weight Regular
Foreground brush Esri_TextStyleDefaultBrush 
<TextBlock Style="{DynamicResource Esri_TextBlockDockPaneHeader}">Dockpane header</TextBlock>

Dialog TextBlocks

DialogTextBlocks

  • Dialog header
Attribute Value
Font Family Segoe UI
Font size 16pt
Font weight Light
Foreground brush Esri_Gray145 
<TextBlock Style="{DynamicResource Esri_TextBlockDialogHeader}">Dialog header</TextBlock>
  • Dialog text
Attribute Value
Font Family Segoe UI
Font size 14pt
Font weight Normal
Foreground brush Esri_Gray155 
<TextBlock Style="{DynamicResource Esri_TextBlockDialog}">Dialog text</TextBlock>

Backstage TextBlocks

BackstageTextBlocks

  • Backstage title
Attribute Value
Font Family Segoe UI
Font size 42pt
Font weight Light
Foreground brush Esri_TextCaptionActiveBrush 
<TextBlock Style="{DynamicResource Esri_TextBlockBackStageTitle}">Backstage title</TextBlock>
  • Backstage header
Attribute Value
Font Family Segoe UI
Font size 24pt
Font weight Light
Foreground brush Esri_TextStyleDefaultBrush 
<TextBlock Style="{DynamicResource Esri_TextBlockBackStageHeader}">Backstage header</TextBlock>
  • Backstage sub-header
Attribute Value
Font Family Segoe UI
Font size 20pt
Font weight Light
Foreground brush Esri_TextCaptionActiveBrush 
<TextBlock Style="{DynamicResource Esri_TextBlockBackStageSubHeader}">Backstage Sub-Header text</TextBlock>
  • Backstage group header
Attribute Value
Font Family Segoe UI
Font size 17pt
Font weight Normal
Foreground brush Esri_TextStyleDefaultBrush 
<TextBlock Style="{DynamicResource Esri_TextBlockBackStageGroupHeader}">Backstage group header</TextBlock>

Tray button textblocks

TrayButtonTextBlocks.png

  • Tray button header
Attribute Value
Font Family Segoe UI
Font size 14pt
Font weight Normal
Foreground brush Esri_TextStyleDefaultBrush 
<TextBlock Style="{DynamicResource Esri_TextBlockTrayButtonHeader}">Tray button header</TextBlock>
  • Tray button default text
Attribute Value
Font Family Segoe UI
Font size 12pt
Font weight Normal
Foreground brush Esri_TextStyleDefaultBrush 
<TextBlock Style="{DynamicResource Esri_TextBlockTrayButton}">Tray button header</TextBlock>

Textbox

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>

      ArcGIS Pro SDK for Microsoft .NET Framework              Home | API Reference | Requirements | Download | Samples

Home

Developing with ArcGIS Pro

    Migration

Framework

    Add-ins

    Configurations

    Customization

    Styling

Arcade

Content

CoreHost

DataReviewer

Editing

Geodatabase

    3D Analyst Data

    Plugin Datasources

    Topology

    Linear Referencing

    Object Model Diagram

Geometry

    Relational Operations

Geoprocessing

Knowledge Graph

Layouts

    Reports

Map Authoring

    3D Analyst

    CIM

    Graphics

    Scene

    Stream

    Voxel

Map Exploration

    Map Tools

Networks

    Network Diagrams

Parcel Fabric

Raster

Sharing

Tasks

Workflow Manager Classic

Workflow Manager

Reference

Clone this wiki locally