How to: Display a Custom Icon on the Add-in Button http://msdn.microsoft.com/en-us/library/ms228771(VS.80,printer).

aspx

©2009 Microsoft Corporation. All rights reserved.

Visual Studio Automation and Extensibility

How to: Display a Custom Icon on the Add-in Button
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 [
http://msdn.microsoft.com/en-us/library/ms165626(VS.80).aspx ] .

You do this by:

Placing the icon bitmap as a resource in a satellite DLL file.

Setting the MSOButton parameter in the AddNamedCommand2 [ http://msdn.microsoft.com/en-us

/library/envdte80.commands2.addnamedcommand2(VS.80).aspx ] method to false (which notifies
the method to look in the satellite DLL 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.

Note

The dialog boxes and menu commands you see might differ from those described in Help depending on
your active settings or edition. These procedures were developed with the General Development Settings
active. To change your settings, choose Import and Export Settings on the Tools menu. For more
information, see Visual Studio Settings [ http://msdn.microsoft.com/en-us/library/zbhkx167(VS.80).aspx
].

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.

If you create a new add-in, be sure to check the "Would you like to create command bar UI for your
Add-in?" option.

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

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

b. Select New Item on the Add menu.

c. 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. Click the Show All Files button on tool bar of Solution Explorer.

4. In the properties for Resource1.resx, set the Build Action property to None.

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 then select BMP Image on the New Image menu. 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. Right-click the Resource1.resx file in Solution Explorer and select Exclude From Project.

Doing this prevents unnecessary compiler errors. The file does not need to be in the project. This allows

1 sur 7 18/06/2009 18:47

How to: Display a Custom Icon on the Add-in Button http://msdn.microsoft.com/en-us/library/ms228771(VS.80,printer).aspx

you to use the built-in Resource Editor.

9. Open the Connect class for the add-in. In the OnConnection [ http://msdn.microsoft.com/en-us/library
/extensibility.idtextensibility2.onconnection(VS.80).aspx ] 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:

Visual Basic Copy Code

C# Copy Code

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

10. When you are done, select Save All on the File menu, select Build Solution on the Build menu, and then
close the solution.

11. In Windows Explorer, use Notepad to edit the Resource1.resx file.

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

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

14. Use ResGen and Assembly Linker (AL) to build the satellite DLL. To do this:

a. On the Start menu, point to All Programs, point to Microsoft Visual Studio 2005, point to
Visual Studio Tools, and then click Visual Studio Command Prompt.

This sets certain environment variables so that you can more easily reference Visual Studio tools.

b. At the command prompt, go to the folder containing the .resx file and type Resgen
Resource1.resx.

Resgen is a utility that compiles the specified .resx file into a .resources file. For more information,
see Resource File Generator (Resgen.exe) [ http://msdn.microsoft.com/en-us/library
/ccec7sz1(VS.80).aspx ] .

c. Again, at the command prompt, type the following: Al.exe /embed:Resource1.resources

/culture:en-US /out:<Add-In Name>.resources.dll.

Replace <Add-In Name> with the name of your add-in. For example, if your add-in project is
named MyAddin1, then the /out: switch would be /out:MyAddin1.resources.dll. If the /out: name
does not match the name of your project, then the resource DLL will not be found.

Assembly Linker (Al.exe) converts the specified .resources file into a satellite resource DLL that you
can reference in your add-in. (You can change the /culture switch to a language other than English.)
For more information, see Assembly Linker (Al.exe) [ http://msdn.microsoft.com/en-us/library
/c405shex(VS.80).aspx ] .

15. Using Windows Explorer, browse to the add-in's DLL directory (usually the \bin folder) and create a
folder named en-US (for English US, because you typed en-US as the culture value in Al).

16. Copy the <Add-In Name>.resources.dll file to the new en-US folder.

17. In Visual Studio, open the add-in project again and run it.

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

2 sur 7 18/06/2009 18:47

How to: Display a Custom Icon on the Add-in Button http://msdn.microsoft.com/en-us/library/ms228771(VS.80,printer).aspx

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:

Copy Code

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.

Example

Following is a full add-in code example for a Visual Basic/Visual C#/Visual J# add-in that references a custom
icon contained in a satellite resource DLL.

Visual Basic Copy Code

3 sur 7 18/06/2009 18:47

How to: Display a Custom Icon on the Add-in Button http://msdn.microsoft.com/en-us/library/ms228771(VS.80,printer).aspx

4 sur 7 18/06/2009 18:47

How to: Display a Custom Icon on the Add-in Button http://msdn.microsoft.com/en-us/library/ms228771(VS.80,printer).aspx

C# Copy Code

5 sur 7 18/06/2009 18:47

How to: Display a Custom Icon on the Add-in Button http://msdn.microsoft.com/en-us/library/ms228771(VS.80,printer).aspx

6 sur 7 18/06/2009 18:47

How to: Display a Custom Icon on the Add-in Button http://msdn.microsoft.com/en-us/library/ms228771(VS.80,printer).aspx

See Also

Tasks
How to: Change the Default Icon for an Add-in [ http://msdn.microsoft.com/en-us/library
/ms165626(VS.80).aspx ]
How to: Expose an Add-in as a Button on the Toolbar [ http://msdn.microsoft.com/en-us/library
/ms165627(VS.80).aspx ]
Concepts
Displaying Add-Ins on Toolbars and Menus [ http://msdn.microsoft.com/en-us/library/ms165623(VS.80).aspx ]

Tags:

Community Content

Showing the icon change Last Edit 9:50 PM by Craig Skibo - MSFT

Once an icon has changed, it may not appear within the user interface. This is because the Add-in needs to be
reset after the code change is made. When an Add-in is created, the value /resetaddin Namespace.ClassName
is added to the debug settings for the command line parameter to devenv.exe. If you delete your .user file in
the directory containing the project file, or receive your project files from source code control, then this
setting may not be there and you will need to manually add it to the project proeprties. This switch causes
Visual Studio to discard changes to command bars created by the supplied Add-in, and regenerate that
information.

Tags:

7 sur 7 18/06/2009 18:47