Custom command bitmaps 101

This is the tutorial I promised on how to create buttons with custom UI in the VS object model.


A common question that I get is how can you add a custom bitmap to a command placed on a tool bar and have that bitmap support transparency. Getting this to work is not very complicated, but getting everything just right so the transparency works can be a little tricky.


To make this work, you are going to need VS with VC for the DLL that contains the bitmap, and an Add-in written in any supported language; such as C#, VB, or VC. The first step is to run the Add-in wizard, making sure to select the option to create a command and put a button on the tool bar (check the first checkbox on page 4 of the wizard). After finishing the wizard, right click on the solution node and select Add | New Project. Select Visual C++ Project in the tree on the right of the Add New Project dialog box, and Win32 Project on the left of this dialog box. Enter a project name; I suggest something like ProjectNameUI, where ProjectName is the name of the Add-in you are creating.


In the wizard that appears, select Application Settings, and then select the DLL radio button. After pressing the Finish button, a VC DLL project will be added to the solution, the starting point for a Satellite DLL project. To create the resources, right click on the project you just added, select Add | Add New Item, and add a new “Resource File (.rc)” item to the project. This will add a resource file to the project and show the Resource View tool window. Right click the top node of the resource added, select Add | Add Resource, select Bitmap, and then click the New button. This will add a bitmap to the resources. By default, the bitmap is too big for our needs, so open the properties window and type 16 into both the Height and Width properties. You can also enter the value 1 for the ID property.


Using the drawing tools, draw your bitmap, but do not use the lime green color, we will use this for the transparent color. To set the correct transparent color, select lime green in the Colors tool window then select Image | Adjust Colors. In the dialog box shown, enter 0 for red and blue, and 254 for green, then press OK. You can now fill in the transparent areas with the lime green color. With your bitmap created, you are now ready to make the modifications to the Add-in so it can load the Satellite DLL and the custom bitmap.


In the Add-in source code, find the AddNamedCommand method call, which by default should look something like this:


Command command = commands.AddNamedCommand(addInInstance, "MyAddin9", "MyAddin9", "Executes the command for MyAddin9", true, 59, ref contextGUIDS, (int)vsCommandStatus.vsCommandStatusSupported+(int)vsCommandStatus.vsCommandStatusEnabled);

You will want to modify the true value so that it reads false, and change the value 59 to the value you entered for the ID value in the properties window, which, if you are following along with this tutorial, is the value 1.


The last steps are to make the changes so that your Add-in can load the Satellite DLL. When the Add-in wizard was run, a file named ReCreateCommands.reg was created in the project directory. If you open this file, it will look like this:


REGEDIT4 [HKEY_CURRENT_USER\SOFTWARE\Microsoft\VisualStudio\7.1\AddIns\MyAddin9.Connect]



Add these entries, supplying the appropriate Satellite DLL name where appropriate (the name of the project I created was MyAddin9), then merge the file ReCreateCommands.reg into the registry:



"SatelliteDLLPath"="C:\\Documents and Settings\\craigs\\My Documents\\Visual Studio Projects\\MyAddin9"

Lastly, you need to put the Satellite DLL in the correct location. In the value given by SatelliteDLLPath in the .reg file, create a folder with the name of the VS locale you are running. For example, I am running US English VS, so I created a folder named C:\Documents and Settings\craigs\My Documents\Visual Studio Projects\MyAddin9\1033 since 1033 is the code for US English. Then copy the Satellite DLL into that folder.


After following these steps, you will have a button on the tool bar which uses a custom bitmap, and has a transparent color.