Dela via

Toolbox Icons and Embedded Resources

  • Artikel

This topic describes how to specify a custom Toolbox icon for your Windows Presentation Foundation (WPF) controls by using embedded resources.

Naming Convention

You associate a Toolbox icon with a custom control by following a naming convention. The Windows Presentation Foundation (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.

The following table lists the supported file types for Toolbox icons.

  • XAML

  • BMP

  • GIF

  • JPG

  • JPEG

  • PNG

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.

  1. Vector XAML.

  2. Exact match on size in both dimensions.

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

Other Resources

Using Resources