Ning Zhang's Blog

Change History:

• first published on 1/21/2008 for Silverlight 2/VS2008/Toolkit December 2008 Release.
• updated on 12/5/2009 for Silverlight 4/VS2010/Blend3/Toolkit November 2009 Release.

Controls in Silverlight runtime (ex. system.windows.dll) and SDK (ex. system.windows.controls.dll) have nice toolbox icons in Visual Studio and Blend. December 2008 release of Silverlight Toolkit added that for Toolkit controls too, as described in my previous post Design Time Features in Silverlight Toolkit:

This post explains how it is done in Silverlight 2 SDK, and in December 2008 release of the Silverlight Toolkit.

Control Icons in Run Time Assembly

The December 2008 Release of Silverlight Toolkit demonstrated how to embed toolbox icons for controls without using a design time assembly.

Open Silverlight.Controls.sln in Visual Studio (see previous post Design Time Feature Implementation in Silverlight Toolkit for more information on how to download the toolkit source):

Or open Controls.csproj in notepad:

<ItemGroup>
  <EmbeddedResource Include="Microsoft.Windows.Controls.AutoCompleteBox.Icon.png" />
  <EmbeddedResource Include="Microsoft.Windows.Controls.DockPanel.Icon.png" />
  <EmbeddedResource Include="Microsoft.Windows.Controls.Expander.Icon.png" />
  <EmbeddedResource Include="Microsoft.Windows.Controls.Label.Icon.png" />
  <EmbeddedResource Include="Microsoft.Windows.Controls.TreeView.Icon.png" />
  <EmbeddedResource Include="Microsoft.Windows.Controls.Viewbox.Icon.png" />
</ItemGroup>

Or open Microsoft.Windows.Controls.dll in reflector:

All three show that the custom toolbox icons are embedded resources in the run time assembly Microsoft.Windows.Controls.dll, with a particular naming convention. Take above Microsoft.Windows.Controls.Microsoft.Windows.AutoCompleteBox.Icon.png as an example:

• The first Microsoft.Windows.Controls is the root namespace, specified in controls.csproj file with line: <RootNamespace>System.Windows.Controls</RootNamespace>
• The next Microsoft.Windows.Controls.AutoCompleteBox is the fully qualified name of AutoCompleteBox class, including namespace but not assembly.
• The rest of the name, Icon.png, specify the icon resource type, as will be explained more later.

Control Icons in Design Time Assembly

The Silverlight 2 SDK demonstrated the approach of embedding control icons in design time assembly.

Open System.Windows.Controls.Design.dll in reflector (it is installed under %ProgramFiles%\Microsoft SDKs\Silverlight\v2.0\Libraries\Client):

Take above Controls.Design.Icons.Calendar.bmp as an example:

• Controls.Design is the root namespace, specified in its csproj file with line <RootNamespace>Controls.Design</RootNamespace>
• Icons is the subfolder where the Calendar.bmp file is in source tree
• Calendar.bmp is the name of the icon resource file in source tree

Control Icon Resource Naming Convention

So from above two examples, we can see that custom toolbox icons for controls are embedded resources in either run time assembly (so you don’t need to ship a design time assembly), or design time assembly (so you have flexibility to change icons, like localize it for a different culture, without touching the run time assembly). The tools (Visual Studio 2008 SP1 for now) try to find the icons based on a special naming convention:

1. Search for resources whose file name without extension matches the type name of the control, including the namespace, with a “[.icon*].{XAML | BMP| PNG | GIF | JPG | JPEG}” .
   1. Note that subdirectories affect the namespace in which embedded resources are found. For example, the Toolkit icons are put under a Microsoft.Windows.Controls subfolder, to avoid putting this long string in all icon file names; while the SDK put all icons under a Icons subfolder.
   2. Supported extensions and file types are: XAML, BMP, GIF, JPG, JPEG and PNG
   3. Recommended image size for Bitmap based file formats is 64×64.
   4. The [.icon*] in the naming convention is optional and allows you to specify multiple sizes of the image that is used as the icon. The match follows the following algorithm:
      1. Vector XAML
      2. If there is an exact match on size (both dimensions) use it
      3. Use the closest match based on size and aspect ratio
   5. If a given resource file is not valid XAML or a valid image file, the next match will be used until one is found.
2. If an image is not found in the same namespace as the control, a loose match based on the type name alone will be searched for against all of the resources, as in the SDK case.
3. Different hosts use different image sizes for their toolbox icon.
   1. Blend uses 24×24 for their large size and 12×12 for their small size (I don’t think this is working in Blend 2 SP1) .
   2. Cider (Visual Studio) uses 16×16 bmp files.

The blog post Specifying a Toolbox Icon for a Control in WPF Designer describes the naming convention in more details.

Update for Blend3 & VS2010

Since this post was first published on 1/21/2008, we’ve made two key improvements regarding control icons:

• Blend 3 shows icons for controls too: big icons (24×24) in Asset Library, and small icons (12×12) in Objects and Timeline.  See Silverlight Design Time: Toolkit July 2009 Release Update for more information.
• You can register your controls (and their associated icons) with Blend 3 and Visual Studio 2010. See Register Silverlight Controls with Visual Studio and Blend for more information.
• The naming convention for icon resource is revised together with the naming convention for design time assemblies. See Silverlight Design Time Assemblies for more information on the enhanced naming convention for design time assemblies. Please note that the search for icon resource is in reverse order of the loading order of design time metadata, i.e., Blend will search for embedded icon resource for a control with above icon resource naming convention in *.Expression.Design*.dll first; only if it fails will Blend search the shared *.Design*.dll second; and only if if fails again will it search the corresponding runtime dll for the embedded icon resource; and if all have failed, Blend will display the default icon for the control. Visual Studio 2010 does it in similar way, but searches *.VisualStudio.Design*.dll first.
• Blend and Visual Studio now support more icon format, and will scale the icon if the desired sized resource (24×24 and 12×12 for Blend, and 16×16 for VS) isn’t found.

Silverlight Toolkit use following naming conventions for embedding icon resources:

• use full names (namespace+type, ex. System.Windows.Controls.Calendar) instead of just type names (ex. Calendar) to avoid ambiguity.
• put icons for Blend in shared .design.dll, and icons for Visual Studio toolbox in .VisualStudio.Design*.dlls. This way, VS2010 can display the right toolbox icon if one exists in .VisualStudio.Design*.dll; if not, VS2010 can load the icon for Blend, scale it to 16×16, and display it in toolbox.
• put icon resource in runtime dll only as last resort (ex, to avoid shipping a design time assembly with only icon resource).

You can see the control icon resource naming convention in Silverlight Toolkit source code: