Toolbox Icons

  • Article

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

You can include Toolbox icons with your custom WPF and Silverlight controls in Visual Studio and Expression Blend. This topic describes how to name your Toolbox icons and how to include them as embedded resources.

Supported File Types

The following list shows the supported file types for Toolbox icons in the WPF Designer for Visual Studio. 

  • BMP

  • GIF

  • JPG

  • JPEG

  • PNG

Note

Expression Blend supports only .png files.

Naming Convention

You associate a Toolbox icon with a custom control by following a naming convention. Design tools examine the embedded resources in the control's assembly for an appropriately named image file.

In the simplest case, you add the Toolbox icon image file as an embedded resource to your control's project. Name it ControlName.Extension, and in the Properties window, set its Build Action to Embedded Resource. The WPF Designer searches for a resource with a file name that matches the type name of the control. For more information, see Walkthrough: Creating a Custom Toolbox Icon for a Control.

Note

For backward compatibility, Visual Studio 2010 supports the naming convention used by Visual Studio 2008. For more information, see Toolbox Icons in Visual Studio 2008.

Visual Studio 2010 supports the following naming convention for Toolbox icons. The substrings in square brackets ([]) are optional.

[AnyString]Namespace.ControlName[.Product][.AnyString].Extension

When a designer searches for Toolbox icons, it matches the Namespace, ControlName, and Product substrings. If Namespace and ControlName do not match your control, the icon will not display in the Toolbox.

The Product substring may be used by a designer to filter out icons for other products. For example, Visual Studio prefers icons that have Product set to "VisualStudio".

The following list shows example Toolbox icon naming conventions you can use for Visual Studio and Expression Blend icons.

  • Namespace.ControlName.VisualStudio.Extension

  • Namespace.ControlName.VisualStudio.AnyString.Extension

  • Namespace.ControlName.Expression.png

  • Namespace.ControlName.Expression.AnyString.png

If no icons are found that fit the previous names, the following names are searched.

  • Namespace.ControlName.Extension

  • Namespace.ControlName.AnyString.Extension

The following list shows example Toolbox icon names for a control named TailspinToysControl in the TailspinToysControlLibrary namespace. Additional optional information about the image format is added, but is not used by designers.

  • TailspinToysControlLibrary.TailspinToysControl.VisualStudio.24bit.48x48.bmp

  • TailspinToysControlLibrary.TailspinToysControl.Expression.4bit.16x16.png

After a designer finds Toolbox icons, the icon that most closely matches the designer's target icon size is loaded for display. The following list shows the order in which matching criteria are applied.

  1. Select icons with the designer specified in the icon name over icons without a designer specified. For example, the WPF Designer prefers icons that have "VisualStudio" in their name over those that have "Expression". 

  2. Select the icon that is the closest match to the rendering size. The Visual Studio Toolbox loads the icon closest to 16x16 pixels, and then maps that icon to 24-bit color depth.

  3. Select the icon that was found first.

Overriding Default Toolbox Icons

You can use the WPF Designer extensibility framework to override Toolbox icons that are embedded in a control's runtime assembly. For more information, see Walkthrough: Providing Metadata for Toolbox Icons.

See Also

Tasks

Walkthrough: Providing Metadata for Toolbox Icons

Concepts

Toolbox Icons in Visual Studio 2008