Using the ToolboxBitmap attribute from Managed C++

Introduction

This is a very brief note on associating a bitmap image with a component or user control from a Managed C++ project. The C# technique is more straightforward and is already documented in the standard help. Doing this in C++ is initially a pain, because there are few (if any) sample projects around, that do this. It took me quite a while to find a post on one of the newsgroups that provided the solution. Once you know what to look for, you'll find the right posts, so the idea of this article is just to provide a quick hit for people searching on ToolboxBitmap.

Aim

Write a Managed C++ component (i.e. derived from System::ComponentModel::Component) or some variation of user control that has a customized toolbox bitmap associated with it. The bitmap should be embedded as a resource (not specified in a run-time distributed file).

Steps

1. Write the component and design a 16*16 bitmap.

2. Add the bitmap

   The bitmap must be added as an embedded resource. (Various posts on the newsgroups describe using .resx files - I couldn't get this to work).

   1. Make sure the 16*16 bitmap is in the project directory.
   2. Make sure the bitmap is named as follows:

      Namespace.ClassName.bmp

      The .NET framework relies on this naming convention to find your resource when displaying the bitmap on the toolbox.

   3. Add the bitmap to the project as follows:
      1. Go to the project settings property pages.
      2. Go to the Linker\Input settings page.
      3. Select "Embed Managed Resource File" and enter the name of your bitmap.

3. Associate the bitmap with the class

   You need to add ToolboxBitmap attribute to your class. For example, if you have the following class:

   MC++

   __gc public class Port : public System:: System::ComponentModel::Component

   ...add the attribute as follows:

   MC++

   [ToolboxBitmap(__typeof(Port))]
   __gc public class Port : public System:: System::ComponentModel::Component

   You must also forward declare the class, otherwise the compiler will fail. E.g.:

   MC++

   __gc public class Port;

   MC++

   [ToolboxBitmap(__typeof(Port))]
   __gc public class Port : public System:: System::ComponentModel::Component

   The ToolboxBitmap attribute resides in the System::Drawing namespace, so you may need to add a using clause at the top of the file. E.g.:

   using namespace System::Drawing;

   That's it. You can now build the project.

4. Adding to the toolbox

   Once the project is built, close the solution. Then, on the Toolbox right-click and select Add/Remove Items. On the .NET Framework Components page, select Browse and find your DLL assembly. Select it, and close the Customize Toolbox dialog. A greyed-out image of your component will appear on the toolbox list. If a greyed out 'cog' is shown, it means that the framework has failed to find your image (see diagnostics below). Otherwise, your component is ready for dragging-and-dropping.

5. Diagnostics

   If you find that the icon does not show correctly on the toolbar, there is a quick way to determine if it is visible from your assembly.

   1. Run ILDASM (on my machine this is: C:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin\ildasm.exe).
   2. From the menu, open your assembly.
   3. Double-click the MANIFEST item - a new window will pop-up.
   4. You should now try to find your bitmap. For example, one of mine appears as:
      MC++

      .mresource public CDS.ParallelPortDrv.Port.bmp
      {
      }

   5. You will hopefully be able to determine what the problem is, from here. For example, if no bitmap resource is listed, it means that the bitmap was not correctly embedded as a managed resource. If the bitmap exists, you should be able to verify that the naming convention is correct. Remember that, all namespaces must be used followed by the class name, followed by ".bmp".