Walkthrough: Providing Metadata for Toolbox Icons

  • Article

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

This walkthrough shows how to provide Toolbox icons for different designers, such as Visual Studio and Expression Blend, in a Windows Presentation Foundation (WPF) custom control library. When you add the custom control to a designer's Toolbox, the appropriate icon appears next to the control's name.

The WPF Designer for Visual Studio enables providing custom Toolbox icons for different designers. For example, you can target different icons for your custom control in Visual Studio and Expression Blend. The icons provided by the design-time implementation override the default icon in the control's runtime assembly.

In this walkthrough, you perform the following tasks:

  • Create a WPF custom control library project with an embedded icon bitmap.

  • Create a separate assembly for design-time metadata that overrides the default Toolbox icon.

  • Test the control's icon at design time.

When you are finished, you will know how to replace the default run-time icon for a custom control at design-time.

Note

The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, choose Import and Export Settings on the Tools menu. For more information, see Visual Studio Settings.

Prerequisites

You need the following components to complete this walkthrough:

  • Visual Studio 2012 RC.

Creating a Custom Control with a Toolbox Icon

To create a custom Toolbox icon for a control, you add an image as an embedded resource to the control's project.

To create a custom control with a Toolbox icon

  1. Create a new WPF Custom Control Library project in Visual Basic or Visual C# named TailspinToysControlLibrary.

  2. Rename the CustomControl1 code file to TailspinToysControl.

  3. Add a Toolbox icon named TailspinToysControl.icon.bmp as an embedded resource. For more information, see Walkthrough: Creating a Custom Toolbox Icon for a Control.

  4. Using the Text Tool, paint DEFAULT in the bitmap, which indicates when the Toolbox loads the control assembly's default icon.

  5. Set the project's output path to "..\TailspinToysControlLibrary\bin\".

  6. Build the solution.

Creating the Design-time Metadata Assembly

Design-time code is deployed in special metadata assemblies. For this walkthrough, the custom metadata is supported by Visual Studio and Expression Blend and is deployed in an assembly named TailspinToysControlLibrary.Design.

To create the design-time metadata assembly

  1. Create a design-time assembly named TailspinToysControlLibrary.Design. For more information, see Walkthrough: Providing Custom Design-time Metadata.

  2. Open the RegisterMetadata code file in the Code Editor.

  3. Replace the automatically generated code with the following code. This code creates an AttributeTable that attaches the custom design-time attributes to the TailspinToysControl class.

    using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

using Microsoft.Windows.Design;
using Microsoft.Windows.Design.Features;
using Microsoft.Windows.Design.Metadata;

using TailspinToysControlLibrary;

// The ProvideMetadata assembly-level attribute indicates to designers
// that this assembly contains a class that provides an attribute table. 
[assembly: ProvideMetadata(typeof(TailspinToysControlLibrary.Design.RegisterMetadata))]
namespace TailspinToysControlLibrary.Design
{
    internal class RegisterMetadata : IProvideAttributeTable
    {
        // Called by the designer to register any design-time metadata. 
        public AttributeTable AttributeTable
        {
            get
            {
                AttributeTableBuilder builder = new AttributeTableBuilder();

                // Set ToolboxBrowsableAttribute to true to display your custom control 
                // in the Toolbox and in the Choose Items... dialog box. 
                builder.AddCustomAttributes(typeof(TailspinToysControl), new ToolboxBrowsableAttribute(true));

                return builder.CreateTable();
            }
        }
    }
}

  4. Save the solution.

Creating the Design-time Toolbox Icons

Now that you have a design-time assembly, you can create your custom Toolbox icons and add them to the project as embedded resources. You will create two icons, one for Visual Studio and one for Expression Blend.

To create the design-time Toolbox icon for Visual Studio

  1. Add a new bitmap file to the TailspinToysControlLibrary.Design project. Name the bitmap file TailspinToysControlLibrary.TailspinToysControl.VisualStudio.24bit.48x48.bmp.

  2. In the Properties window, set the bitmap's Colors property to 24 bit.

  3. Using the Text Tool, paint METADATA in the bitmap, which indicates when the icon is set from designer metadata.

  4. In Solution Explorer, select the bitmap file.

  5. In the Properties window, set the Build Action property to Embedded Resource.

  6. Add a new bitmap file to the TailspinToysControlLibrary.Design project. Name the bitmap file TailspinToysControlLibrary.TailspinToysControl.Expression.4bit.48x48.bmp.

    Note

    Blend loads only .png files as icons, so you use the external Paint program to create the Blend icon.

  7. Right-click in the Image Editor and select Open External Editor from the shortcut menu.

    The Paint application opens.

  8. Using the Text Tool, paint BLEND in the bitmap, which indicates the icon is for use in Expression Blend's Assets window.

  9. Save the image as a .png file.

  10. In Solution Explorer, right-click the TailspinToysControlLibrary.Design project, point to Add, and select Existing Item from the shortcut menu.

  11. In the Add Existing Item dialog box, select TailspinToysControlLibrary.TailspinToysControl.Expression.4bit.48x48.png and then click Add.

  12. In Solution Explorer, select the .png image file.

  13. In the Properties window, set the Build Action property to Embedded Resource.

  14. Delete the empty TailspinToysControlLibrary.TailspinToysControl.Expression.4bit.48x48.bmp bitmap file.

  15. Build the solution.

Testing the Toolbox Icons

Test your custom Toolbox icon by adding TailspinToysControl to the Toolbox.

To test the Toolbox icon

  1. Add a new WPF Application project in Visual Basic or Visual C# named TestApplication to the solution.

    MainWindow.xaml opens in the WPF Designer. In the Toolbox, TailspinToysControl appears in the TailspinToysControlLibrary Controls tab. The default control icon is displayed.

    Default Toolbox icon

    Note

    The icon embedded in the control's run-time assembly is not displayed. This is a limitation of the Toolbox auto-population feature.

  2. In the Toolbox, right-click TailspinToysControl, select Delete from the shortcut menu, and then click OK.

    TailspinToysControl is removed from the Toolbox.

  3. In the Toolbox, right-click the TailspinToysControlLibrary Controls tab and then select Choose Items from the shortcut menu.

    The Choose Toolbox Items dialog box opens.

  4. Click the WPF Components tab. For more information, see Choose Toolbox Items, WPF Components.

  5. Click Browse and navigate to the TailspinToysControlLibrary\TailspinToysControlLibrary\bin folder.

  6. Double-click TailspinToysControlLibrary.dll to select it.

    Details of the TailspinToysControlLibrary assembly appear in the Choose Toolbox Items dialog box. Your custom design-time icon appears in the TailspinToysControl group box.

    Choose Toolbox Items dialog box with custom icon

  7. Click OK.

    TailspinToysControl appears in the Toolbox with the TailspinToysControlLibrary.TailspinToysControl.VisualStudio.24bit.48x48.bmp icon, which overrides the icon in the run-time assembly.

    Custom Toolbox icon

Next Steps

  • You can also load your custom control and design-time assembly in Expression Blend. Starting in Expression Blend 4, your TailspinToysControlLibrary.TailspinToysControl.Expression.4bit.48x48.png icon displays in the Assets window when you add a project reference to the TailspinToysControlLibrary.dll assembly.

  • You can deploy your run-time and design-time assemblies by using the AssemblyFoldersEx registration procedure. For more information, see Deploying a Custom Control and Design-time Assemblies.

See Also

Tasks

Walkthrough: Providing Custom Design-time Metadata

Walkthrough: Creating a Custom Toolbox Icon for a Control

Reference

AttributeTable

Concepts

Toolbox Icons

Deploying a Custom Control and Design-time Assemblies

Providing Design-time Metadata

Other Resources

Choose Toolbox Items, WPF Components