How to: Display a Custom Icon on the Add-In Button

Visual Studio add-ins are deprecated in Visual Studio 2013. You should upgrade your add-ins to VSPackage extensions. For more information about upgrading, see FAQ: Converting Add-ins to VSPackage Extensions.

You can replace the default icon (a smiley-face) that displays next to your add-in command with an icon that is not one of the predefined standard icons as outlined in How to: Change the Default Icon for an Add-In.

You do this by:

• Adding the icon bitmap as a resource in your project.

• Setting the MSOButton parameter in the AddNamedCommand2 method to false (which notifies the method to look for the icon bitmap).

• Referencing the ID number of that resource in the commandbar portion of your add-in project.

The procedure below demonstrates how to add a custom icon to the add-in button.

To add a custom bitmap as an add-in button icon to a add-in project

1. Open an existing add-in solution, or create a new add-in solution in Visual Studio.

2. Add a new resource file to your add-in project. To do this:

   1. Right-click the add-in project in Solution Explorer.

   2. Select New Item on the Add menu.

   3. Select Resources File in the Templates list and click the Add button. Leave its default name (Resources1.resx).

      This starts the Visual Studio Resource Editor.

3. If the resource file does not appear in Solution Explorer, click the Show All Files button on the tool bar.

4. Add-ins require an integer value as the bitmap argument. Setting this property allows you to edit the resource file and name its bitmap resource with a numeric identifier, something you cannot do when the .resx file is part of add-in project.

5. In the Resource Editor, click Add Resource, and from the dropdown select New Image, then BMP Image. For now, leave its default name (Image1.bmp).

   Alternatively, you can select an existing bitmap image that is 16 x 16 pixels and either 16 Color or True Color. Custom icons for add-ins must be 16 x 16 pixels and be either 16-color or True Color.

6. In the bitmap properties window, change both the Height and Width properties to 16. Set the Colors property to either 16 Color or True Color.

7. If you created a new bitmap, edit the picture in the Resource Editor.

8. Open the Connect class for the add-in. In the OnConnection method in the AddNamedCommand2 line, change the MSOButton parameter value from true to false, and the Bitmap parameter value from 59 to 1. For example:

   command = commands.AddNamedCommand2(_addInInstance, "MyAddin1", " 
   MyAddin1", "Executes the command for MyAddin1", False, 1, Nothing, 
   CType(vsCommandStatus.vsCommandStatusSupported, Integer) + 
   CType(vsCommandStatus.vsCommandStatusEnabled, Integer), 
   vsCommandStyle.vsCommandStylePictAndText, 
   vsCommandControlType.vsCommandControlTypeButton)
   

   Command command = commands.AddNamedCommand2(_addInInstance, 
   "MyAddin1", "MyAddin1", "Executes the command for MyAddin1", false, 
   1, ref contextGUIDS, 
   (int)vsCommandStatus.vsCommandStatusSupported+(int)vsCommandStatus.
   vsCommandStatusEnabled, (int)vsCommandStyle.vsCommandStylePictAndText, 
   vsCommandControlType.vsCommandControlTypeButton);
   

   Setting the MSOButton argument to false forces the add-in to look to a resource file for its button bitmap. The number, 1, will be the identifier for that bitmap. (It is set in a later step.)

9. When you are done, select Save All on the File menu, select Build Solution on the Build menu, and then unload the project. To do this, right-click the project node in Solution Explorer and then click Unload Project.

10. In File Explorer, use Notepad to edit the Resource1.resx file.

11. Search for all instances of "Image1" and change them to "1." When you are done, save the file.

12. In the \Resources folder for the add-in, change the bitmap file name from Image1.bmp to 1.bmp.

13. Reload the add-in project again (by right-clicking the project node in Solution Explorer and clicking Reload Project) and run it.

14. Click the Tools menu.

    The add-in appears on the Tools menu along with your custom icon.

To add a custom bitmap as an add-in button icon to a native Visual C++ add-in

1. Follow the same procedures as outlined above, but change the following items.

2. Create a new Visual C++ Win32 DLL project.

3. Add a Resource File (.rc).

4. In Resource View, add a bitmap (16 x 16) and give it a numeric ID.

   The bitmap must be 16 x 16 pixels and either 16 color or True Color.

5. Update the AddNamedCommand2 method in Connect.cpp with MSOButton set to VARIANT_FALSE, and Bitmap set to the bitmap ID you previously assigned.

6. Build the DLL.

7. Create a subfolder "1033" (for English locale) in the native add-in DLL directory.

8. Copy the satellite DLL to the "1033" directory.

9. Open AddIn.rgs and add two reg key values "SatelliteDllName" and "SatelliteDllPath." For example:

   HKCU
   {
      NoRemove 'SOFTWARE'
      {
         NoRemove 'Microsoft'
         {
            NoRemove 'VisualStudio'
            {
               NoRemove '8.0'
               {
                  NoRemove 'AddIns'
                  {
                     ForceRemove 
                       'NativeAddinCustBitmap.Connect'
                        {
                          val LoadBehavior = d 0
                          val CommandLineSafe = d 0
                          val CommandPreload = d 1
                          val FriendlyName = s 'NativeAddinCustBitmap'
                          val Description = s 'NativeAddinCustBitmap 
                            Description'
                          val SatelliteDllName = s  
                            'NativeAddinCustBitmapUI.dll'
                          val SatelliteDllPath = s 
                            'C:\Test\CustomBitmap\NativeAddinCustBitmap
                            \NativeAddinCustBitmap\Debug'
                        }
                     }
                  }
               }
            }
         }
      }
   

   In "SatelliteDllPath" do not add the locale ID in the path. It will be automatically appended at runtime.

10. Rebuild the add-in to register the updated information.

See Also

Tasks

How to: Change the Default Icon for an Add-In

How to: Expose an Add-In as a Button on the Toolbar

Concepts

Displaying Add-Ins on Toolbars and Menus