Toolbox Icons in Visual Studio 2008
[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 Windows Presentation Foundation (WPF) controls in Visual Studio. This topic describes how to name your Toolbox icons and how to include them as embedded resources.
Note
This topic is retained for backward compatibility with Visual Studio 2008. For Visual Studio 2010, see Toolbox Icons.
Supported File Types
The following table lists the supported file types for Toolbox icons in the WPF Designer for Visual Studio.
XAML
BMP
GIF
JPG
JPEG
PNG
Naming Convention
You associate a Toolbox icon with a custom control by following a naming convention. The WPF Designer for Visual Studio examines 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. 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
The WPF Designer uses a matching algorithm to find the best resource for a Toolbox icon. If a resource file is not valid XAML or a valid image file, the next match is used until one is found. XAML images cannot contain references to non-system types.
Fully-Matched Name
The Toolbox icon naming convention supports fully-matched resource names. For fully-matched names, you include the namespace in the Toolbox icon name by using the following convention Namespace.ControlName.Icon.Extension. For example, consider a control that is named ProseControl and is defined in the Proseware.Core.Controls namespace. A fully-matched PNG Toolbox icon for this control would be named Proseware.Core.Controls.ProseControl.Icon.png.
For resources, Visual Studio converts folders to namespaces automatically. Therefore, you can create a folder structure in your project that is the same as your namespace. Be aware that folders affect the namespace in which embedded resources are found. In the previous example, if the image file is in a subfolder named Icons, the WPF Designer would look for a Toolbox icon named Proseware.Core.Controls.Icons.ProseControl.Icon.png.
If an image is not found in the same namespace as the control, the WPF Designer searches for a loose match.
Loosely-Matched Name
If the WPF Designer does not find a fully-matched resource, it looks for loose matches in the assembly's embedded resources. In the previous example, the WPF Designer first searches for a file that has the fully-matched name Proseware.Core.Controls.ProseControl.Icon.Extension. If this search fails, the WPF Designer ignores the namespace and looks for a name based on the type name alone. In this example, the WPF Designer looks for any files in the resources named ProseControl.Icon.Extension. If this search fails, the WPF Designer begins searching from the default namespace. In this example, the WPF Designer looks for files named Proseware.ProseControl.Icon.Extension.
Multiple Image Sizes
Your Toolbox icon image file name may include an optional "Icon" field. This substring enables specifying multiple image sizes for the icon.
For the ProseControl control in the previous example, the WPF Designer finds the following images in the resources and selects the best match for size.
Proseware.Core.Controls.ProseControl.Icon.Large.png
Proseware.Core.Controls.ProseControl.Icon.Medium.png
Proseware.Core.Controls.ProseControl.Icon.ReallyLarge.png
You may also omit the period that follows "Icon" to specify the following file names.
Proseware.Core.Controls.ProseControl.IconLarge.png
Proseware.Core.Controls.ProseControl.IconMedium.png
Proseware.Core.Controls.ProseControl.IconReallyLarge.png
The WPF Designer selects the Toolbox icon based on the following rules.
Vector XAML.
Exact match on size in both dimensions.
Closest match based on size and aspect ratio.
The recommended image size for bitmap-based file formats is 64 pixels by 64 pixels.
The WPF Designer and Expression Blend use different image sizes for the Toolbox icon. Expression Blend uses 24x24 for the large icon size and 12x12 for the small size. The WPF Designer uses 16x16.
If the size desired by the host is 64x64 pixels, and Proseware.Core.Controls.ProseControl.Icon.Large.png is the best match based on size and aspect ratio, this file is used. All of the images in the assembly are examined. If there are two images with the same size and aspect ratio, the host decides which it uses.
See Also
Tasks
Walkthrough: Creating a Custom Toolbox Icon for a Control