Colors and Styling for Visual Studio

Using color in Visual Studio

In Visual Studio, color is used primarily as a communication tool, not just as decoration. Use color minimally and reserve it for situations where you want to:

• Communicate meaning or affiliation (for example, platform or language modifiers)

• Attract attention (for example, indicating a status change)

• Improve readability and provide landmarks for navigating the UI

• Increase desirability

  Several options exist for assigning colors to UI elements in Visual Studio. Sometimes it can be difficult to figure out which option you’re supposed to use, or how to use it correctly. This topic will help you:

1. Understand the different services and systems used to define colors in Visual Studio.

2. Select the correct option for a given element.

3. Correctly use the option you have chosen.

   IMPORTANT: Never hardcode hex, RGB, or system colors to your UI elements. Using the services allows for flexibility in tuning hue. Additionally, without the service, you will not be able to take advantage of the theme-switching capabilities of the The VSColor Service.

Methods for assigning color to Visual Studio interface elements

Choose the method best suited to your UI elements.

Visual Studio themes

Visual Studio features three different color themes: light, dark, and blue . It also detects High Contrast mode, which is a system-wide color theme designed for accessibility.

Users are prompted to select a theme during their first use of Visual Studio and are able to switch themes later by going to Tools > Options > Environment > General and choosing a new theme from the “color theme” dropdown menu.

Users can also use Control Panel to switch their entire systems into one of several High Contrast themes. If a user selects a High Contrast theme, then the Visual Studio color theme selector no longer affects colors in Visual Studio, although any theme changes are saved for when the user exits High Contrast mode. For more information about High Contrast mode, see Choosing High Contrast colors.

The VSColor service

Visual Studio provides an environment color service, known as the VSColor service, which allows you to bind the color values of your UI elements to a named entry containing color values for each Visual Studio theme. This ensures that your colors will automatically change to reflect the current user-selected theme or system High Contrast mode. Use of the service means that the implementation of all theme-related color changes is handled in one place, and if you are using common shared colors from the service, your UI will automatically reflect new themes in future versions of Visual Studio.

Implementation

The Visual Studio source code includes several package definition files that contain lists of token names and the respective color values for each theme. The color service reads the VSColors defined in these package definition files. These colors are referenced in XAML markup or in code and then loaded through either the IVsUIShell5.GetThemedColor method or a DynamicResource mapping.

System colors

Common controls reference the system colors by default. If you want your UI to use system colors, such as when you are creating an embedded or standalone dialog, you don’t need to do anything.

Common shared colors in the VSColor service

Your interface elements should reflect the overall Visual Studio environment. By reusing the common shared colors that are appropriate for the UI component you’re designing, you ensure that your interface is consistent with other Visual Studio interfaces, and that your colors will update automatically when themes are added or updated.

Before using common shared colors, make sure that you understand how to use them correctly. Incorrect use of common shared colors might result in an inconsistent, frustrating, or confusing experience for your users.

User-customizable colors

See: Exposing colors for end users

Sometimes, you will want to allow the end user to customize your UI, such as when you are creating a code editor or design surface. Customizable UI components are found in the Fonts and Colors section of the Tools > Options dialog, where users can choose to change the foreground color, background color, or both.

Tools>Options dialog

The VSColor Service

Visual Studio provides an environment color service, also called the VSColor service or the shell color service. This service allows you to bind the color values of your UI elements to a name-value color set containing colors for each theme. The VSColor service must be used for all UI elements, so that colors automatically change to reflect the current user-selected theme, and so that UI bound to the environment color service will integrate with new themes in future versions of Visual Studio.

How the service works

The environment color service reads VSColors defined in the .pkgdef for the UI component. These VSColors are then referenced in XAML markup or code and are loaded through either the IVsUIShell5.GetThemedColor or a DynamicResource mapping.

Environment color service architecture

Accessing the service

There are several different ways to access the VSColor service, depending on what kind of color tokens you are using and what kind of code you have.

Predefined environment colors

From native code

The shell provides a service that gives access to the COLORREF of the colors. The service/interface is:

IVsUIShell2::GetVSSysColorEx(VSSYSCOLOR dwSysColIndex, DWORD *pdwRGBval)

In the file VSShell80.idl, the enumeration __VSSYSCOLOREX has shell color constants. To use it, pass in as the index value either one of the values from the enum __VSSYSCOLOREX documented in MSDN or a regular index number that the Windows system API, GetSysColor, accepts. Doing this gets back the RGB value of the color that should be used in the second parameter.

If storing a pen or brush with a new color, you must AdviseBroadcastMessages (off of the Visual Studio shell) and listen for WM_SYSCOLORCHANGE and WM_THEMECHANGED messages.

// To access the color service in native code, you'll make a call that resembles this:
pUIShell2->GetVSSysColorEx(VSCOLOR_COLOR_NAME, &rgbLOCAL_COLOR);

NOTE: The COLORREF values returned by GetVSSysColorEx() contain just R,G,B components of a theme color. If a theme entry uses transparency, the alpha-channel value is discarded before returning. Therefore, if the environment color of interest needs to be used in a place where transparency channel is important, you should use IVsUIShell5.GetThemedColor instead of IVsUIShell2::GetVSSysColorEx, as described later in this topic.

From managed code

Accessing the VSColor service through native code is fairly straightforward. If you are working through managed code, however, determining how to use the service can be tricky. With that in mind, here is a C# code snippet demonstrating this process:

private void VSColorPaint(object sender, System.Windows.Forms.PaintEventArgs e)
{
    //getIVSUIShell2
    IVsUIShell2 uiShell2 = Package.GetService(typeof(SVsUIShell)) as IVsUIShell2;
    Debug.Assert (uiShell2 != null, "failed to get IVsUIShell2");

    if (uiShell2 != null)
    {
        //get the COLORREF structure
        uint win32Color;
        uiShell.GetVSSysColorEx(VSSYSCOLOREX.VSCOLOR_SMARTTAG_HOVER_FILL, out win32Color);

        //translate it to a managed Color structure
        Color myColor = ColorTranslator.FromWin32((int)win32Color);
        //use it
        e.Graphics.FillRectangle(new SolidBrush(myColor), 0, 0, 100, 100);
    }
}

If you are working in Visual Basic, use:

Dim myColor As Color = ColorTranslator.FromWin32((Integer)win32Color)

From WPF UI

You can bind to Visual Studio colors through values exported into the Application's ResourceDictionary. Below is an example of using resources from the color table as well as binding to the environment font data in XAML.

<Style TargetType="{x:Type Button}">
    <Setter Property="TextBlock.FontFamily"
            Value="{DynamicResource VsFont.EnvironmentFontFamily}" />
    <Setter Property="TextBlock.FontSize"
            Value="{DynamicResource VsFont.EnvironmentFontSize}" />
    <Setter Property="Background"
            Value="{DynamicResource VsBrush.EnvironmentBackgroundGradient}" />
</Style>

Helper classes and methods for managed code

For managed code, the shell’s Managed Package Framework library (Microsoft.VisualStudio.Shell.12.0.dll) contains a couple of helper classes facilitating the use of themed colors.

The helper methods in the Microsoft.VisualStudio.Shell.VsColors class in MPF include GetThemedGDIColor() and GetThemedWPFColor(). Those helper methods return the color value of a theme entry as System.Drawing.Color or System.Windows.Media.Color, to be used in WinForms or WPF UI.

IVsUIShell5 shell5;
Button button = new Button();
button.BackColor = GetThemedGDIColor(shell5, SolutionExplorerColors.SelectedItemBrushKey);
button.ForeColor = GetThemedGDIColor(shell5, SolutionExplorerColors.SelectedItemTextBrushKey);

/// <summary>
/// Gets a System.Drawing.Color value from the current theme for the given color key.
/// </summary>
/// <param name="vsUIShell">The IVsUIShell5 service, used to get the color's value.</param>
/// <param name="themeResourceKey">The key to find the color for.</param>
/// <returns>The current theme's value of the named color.</returns>
public static System.Drawing.Color GetThemedGDIColor(this IVsUIShell5 vsUIShell, ThemeResourceKey themeResourceKey)
{
   Validate.IsNotNull(vsUIShell, "vsUIShell");
   Validate.IsNotNull(themeResourceKey, "themeResourceKey");

   byte[] colorComponents = GetThemedColorRgba(vsUIShell, themeResourceKey);

   // Note: The Win32 color we get back from IVsUIShell5.GetThemedColor is ABGR
   return System.Drawing.Color.FromArgb(colorComponents[3], colorComponents[0], colorComponents[1], colorComponents[2]);
}

private static byte[] GetThemedColorRgba(IVsUIShell5 vsUIShell, ThemeResourceKey themeResourceKey)
{
   Guid category = themeResourceKey.Category;
   __THEMEDCOLORTYPE colorType = __THEMEDCOLORTYPE.TCT_Foreground
   if (themeResourceKey.KeyType == ThemeResourceKeyType.BackgroundColor || themeResourceKey.KeyType == ThemeResourceKeyType.BackgroundBrush)
   {
      colorType = __THEMEDCOLORTYPE.TCT_Background;
   }

   // This call will throw an exception if the color is not found
   uint rgbaColor = vsUIShell.GetThemedColor(ref category, themeResourceKey.Name, (uint)colorType);
   return BitConverter.GetBytes(rgbaColor);
}
public static System.Windows.Media.Color GetThemedWPFColor(this IVsUIShell5 vsUIShell, ThemeResourceKey themeResourceKey)
{
   Validate.IsNotNull(vsUIShell, "vsUIShell");
   Validate.IsNotNull(themeResourceKey, "themeResourceKey");

   byte[] colorComponents = GetThemedColorComponents(vsUIShell, themeResourceKey);

    return System.Windows.Media.Color.FromArgb(colorComponents[3], colorComponents[0], colorComponents[1], colorComponents[2]);
}

The class can also be used to obtain VSCOLOR identifiers for a given WPF color resource key, or vice versa.

public static string GetColorBaseKey(int vsSysColor);
public static bool TryGetColorIDFromBaseKey(string baseKey, out int vsSysColor);

The methods of VsColors class query the VSColor service to return the color value each time they are invoked. To obtain a color value as System.Drawing.Color, an alternative with better performance is to instead use the methods of the Microsoft.VisualStudio.PlatformUI.VSThemeColor class, which caches the color values obtained from the VSColor service. The class subscribes internally to shell broadcast messages events, and discards the cached value when a theme changing event occurs. Also, the class provides a .NET-friendly event to subscribe to theme changes. Use the ThemeChanged event to add a new handler, and use the GetThemedColor() method to obtain color values for the ThemeResourceKeys of interest. A sample code could look like this:

public MyWindowPanel()
{
    InitializeComponent();

    // Subscribe to theme changes events so we can refresh the colors
    VSColorTheme.ThemeChanged += VSColorTheme_ThemeChanged;

    RefreshColors();
}

private void VSColorTheme_ThemeChanged(ThemeChangedEventArgs e)
{
    RefreshColors();

    // Also post a message to all the children so they can apply the current theme appropriately
    foreach (System.Windows.Forms.Control child in this.Controls)
    {
        NativeMethods.SendMessage(child.Handle, e.Message, IntPtr.Zero, IntPtr.Zero);
    }
}

private void RefreshColors()
{
    this.BackColor = VSColorTheme.GetThemedColor(EnvironmentColors.ToolWindowBackgroundColorKey);
    this.ForeColor = VSColorTheme.GetThemedColor(EnvironmentColors.ToolWindowTextColorKey);
}

protected override void Dispose(bool disposing)
{
    if (disposing)
    {
        VSColorTheme.ThemeChanged -= this.VSColorTheme_ThemeChanged;
        base.Dispose(disposing);}
}

Choosing High Contrast colors

Overview

Windows uses several high-contrast system-level themes that increase the color contrast of text, backgrounds, and images, making elements appear more distinct on the screen. For accessibility reasons, it is important that Visual Studio interface elements respond correctly when users switch to a High Contrast theme.

Only a handful of system colors can be used for High Contrast themes. When choosing your system color names, remember the following tips:

1. Choose system colors that have the same semantic meaning as the element that you are coloring. For instance, if you are choosing a high-contrast color for text within a window, use WindowText and not ControlText.

2. Choose foreground/background pairs together or you will not be confident that your color choice will work in all High Contrast themes.

3. Determine which parts of your UI are the most important and ensure that content areas will stand out. You will lose a lot of detail that subtle differences in color hue would normally distinguish, so the use of strong border colors is common to define content areas, because there are no color variants for different content areas.

System color set

The table at WPF Team Blog: SystemColors Reference indicates the complete set of system color names, and the corresponding hues displayed in each theme.

When applying this limited set of colors to your UI, it is expected that you will lose subtle details that were present in the “normal” themes. Here is an example of UI with subtle gray colors that are used to distinguish areas within a tool window. When paired with the same window displayed in High Contrast mode, you can see that all the backgrounds are the same hue and the borders of those areas are indicated by border alone:

Example of how subtle details are lost when in High Contrast

Choosing text colors in an editor

Colorized text is used in an editor or on a design surface to indicate meaning, such as allowing for easy identification of groups of similar items. In a High Contrast theme, however, you do not have the ability to differentiate between more than three text colors. WindowText, GrayText and HotTrackText are the only colors available on WindowBackground surfaces. Since you cannot use more than three colors, carefully choose the most important differences that you want to display when in High Contrast mode.

Hues for each of the token names allowed on an editor surface, as they appear in each High Contrast theme:

High Contrast editor comparison

Examples of the editor surface in the Blue theme:

Editor in Blue theme

Editor in High Contrast #1 theme

Usage patterns

Many common UI elements already have high-contrast colors defined. You can reference these usage patterns when choosing your own system color names, so that your UI elements are consistent with similar components.

Exposing colors for end users

Overview

Sometimes you will want to allow the end user to customize your UI, such as when you are creating a code editor or design surface. The most common way to do this is by using the Tools > Options dialog. Unless you have highly specialized UI that requires special controls, the easiest way to present the customization is through the Fonts and Colors page within the Environment section of the dialog. For each element that you expose for customization, the user can choose to change the foreground color, background color, or both.

Building a VSPackage for your customizable colors

A VSPackage can control the fonts and colors through custom categories and display items on the Fonts and Colors property page. When using this mechanism, VSPackages must implement the IVsFontAndColorDefaultsProvider interface and its associated interfaces.

In principle, this mechanism can be used to modify all existing display items and the categories that contain them. However, it should not be used to modify the Text Editor category or its display items. For more information on the Text Editor category, see Font and Color Overview.

To implement custom categories or display Items, a VSPackage must:

• Create or identify categories in the registry. The IDE's implementation of the Fonts and Colors property page uses this information to correctly query for the service supporting a given category.

• Create or identify groups in the registry (optional). It might be useful to define a group, which represents the union of two or more categories. If a group is defined, the IDE automatically merges subcategories and distributes display items within the group.

• Implement IDE support.

• Handle font and color changes.

To create or identify categories

Construct a special type of category registry entry under [HKLM\SOFTWARE\Microsoft \Visual Studio\<Visual Studio version>\FontAndColors\<Category>]. <Category> is the non-localized name of the Category.

Populate the registry with two values:

The service specified in the registry must provide an implementation of IVsFontAndColorDefaults for the corresponding category.

To create or identify groups

Construct a special type of category registry entry under [HKLM\SOFTWARE\Microsoft \Visual Studio\<Visual Studio version>\FontAndColors\<group>]. <group> is the non-localized name of the group.

Populate the registry with two values:

The service specified in the registry must provide an implementation of T:Microsoft.VisualStudio.Shell.Interop.IVsFontAndColorGroup for the corresponding group.

To implement IDE support

Implement GetObject, which returns either an IVsFontAndColorDefaults interface or an T:Microsoft.VisualStudio.Shell.Interop.IVsFontAndColorGroup interface to the IDE for each category or group GUID supplied.

For every category it supports, a VSPackage implements a separate instance of the IVsFontAndColorDefaults interface.

The methods implemented through IVsFontAndColorDefaults must provide the IDE with:

• Lists of display items in the category

• Localizable names for display items

• Display information for each member of the category

  NOTE: Every category must contain at least one display item.

  The IDE uses the T:Microsoft.VisualStudio.Shell.Interop.IVsFontAndColorGroup interface to define a union of several categories.

  Its implementation provides the IDE with:

• A list of the Categories that make up a given group

• Access to instances of IVsFontAndColorDefaults supporting each Category within the group

• Localizable group names

Updating the IDE

The IDE caches information about Font and Color settings. Therefore, after any modification of the IDE Font and Color configuration, ensuring that the cache is up to date is a best practice.

Updating the cache is done through the IvsFontAndColorCacheManager interface and can be performed globally or just on selected items.

Handling font and color changes

To properly support the colorization of text that a VSPackage displays, the colorization service supporting the VSPackage must respond to the user-initiated changes made through the Fonts and Colors properties page.

To do this, a VSPackage must:

• handle IDE-generated events by implementing the IVsFontAndColorEvents interface. The IDE calls the appropriate method following user modifications of the Fonts and Colors page. For example, it calls the OnFontChanged method if a new font is selected.

  OR

• poll the IDE for changes. This can be done through the system-implemented IVsFontAndColorStorage interface. Although primarily for support of persistence, the GetItem method can obtain font and color information for Display Items. For more information on font and color settings, see the MSDN article Accessing Stored Font and Color Settings.

  NOTE: To ensure that polling results are correct, use the IVsFontAndColorCacheManager interface to determine if a cache flush and update are needed prior to calling the retrieval methods of the IVsFontAndColorStorage interface.

Registering custom font and color Category without implementing interfaces

The following code example demonstrates how to register the custom font and color Category without implementing interfaces:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0Exp\FontAndColors\CSharp Tool Window]
"Package"="{F5E7E71D-1401-11D1-883B-0000F87579D2}"
"Category"="{9FF46859-A47E-47bf-8AC5-EC3DBE69D1FE}"
"ToolWindowPackage"="{7259e420-6241-4e0d-b535-5b820671d183}"

    "NameID"=dword:00000064

NOTE:

• "NameID" = the resource ID of the localized category name in your package

• "ToolWindowPackage" = Package GUID

• "Category"="{9FF46859-A47E-47bf-8AC5-EC3DBE69D1FE}" is just an example and the actual value can be a new GUID provided by the implementer.

Set the Font and Color property category GUID

The code example below demonstrates setting Category GUIDs.

// m_pView is your IVsTextView
IVsTextEditorPropertyCategoryContainer spPropCatContainer =
(IVsTextEditorPropertyCategoryContainer)m_pView;
if (spPropCatContainer != null)
{
  IVsTextEditorPropertyContainer spPropContainer;
  Guid GUID_EditPropCategory_View_MasterSettings =
  new Guid("{D1756E7C-B7FD-49a8-B48E-87B14A55655A}");
  hr = spPropCatContainer.GetPropertyCategory(
  ref GUID_EditPropCategory_View_MasterSettings, out spPropContainer);
  if(hr == 0)
  {
    hr = spPropContainer.SetProperty(VSEDITPROPID.VSEDITPROPID_ViewGeneral_FontCategory, catGUID);
    hr = spPropContainer.SetProperty(VSEDITPROPID.VSEDITPROPID_ViewGeneral_ColorCategory, catGUID);
  }
}