Export (0) Print
Expand All

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.

You do this by:

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

  • Setting the MSOButton parameter in the AddNamedCommand2 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.

NoteNote

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.

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:

    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. 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 you to use the built-in Resource Editor.

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

  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:

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

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

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

  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

  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.

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.

using System;
using Extensibility;
using EnvDTE;
using EnvDTE80;
using Microsoft.VisualStudio.CommandBars;
using System.Resources;
using System.Reflection;
using System.Globalization;

namespace MyAddin1
{
    public class Connect : Object, IDTExtensibility2, IDTCommandTarget
    {
        public Connect()
        {
        }

    public void OnConnection(object application, ext_ConnectMode 
    connectMode, object addInInst, ref Array custom)
    {
        _applicationObject = (DTE2)application;
        _addInInstance = (AddIn)addInInst;
        if(connectMode == ext_ConnectMode.ext_cm_UISetup)
        {
            object []contextGUIDS = new object[] { };
            Commands2 commands = 
             (Commands2)_applicationObject.Commands;
            string toolsMenuName;

            try
            {
                ResourceManager resourceManager = new 
                ResourceManager("MyAddin1.CommandBar", 
                Assembly.GetExecutingAssembly());
                CultureInfo cultureInfo = new 
                  System.Globalization.CultureInfo
                  (_applicationObject.LocaleID);
                string resourceName =  String.Concat(cultureInfo.
                TwoLetterISOLanguageName, "Tools");
                toolsMenuName = 
                resourceManager.GetString(resourceName);
            }
            catch
            {
                toolsMenuName = "Tools";
            }

            CommandBar menuBarCommandBar = 
            ((CommandBars)_applicationObject.CommandBars)["MenuBar"];

            CommandBarControl toolsControl = 
            menuBarCommandBar.Controls[toolsMenuName];
            CommandBarPopup toolsPopup = (CommandBarPopup)toolsControl;

            try
            {
                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);

                if((command != null) && (toolsPopup != null))
                {
                    command.AddControl(toolsPopup.CommandBar, 1);
                }
            }
            catch
            {
            }
        }
    }

    public void OnDisconnection(ext_DisconnectMode disconnectMode, ref 
      Array custom)
    {
    }

    public void OnAddInsUpdate(ref Array custom)
    {
    }

    public void OnStartupComplete(ref Array custom)
    {
    }

    public void OnBeginShutdown(ref Array custom)
    {
    }
            
    public void QueryStatus(string commandName, 
      vsCommandStatusTextWanted neededText, ref vsCommandStatus status, 
      ref object commandText)
    {
        if(neededText == 
        vsCommandStatusTextWanted.vsCommandStatusTextWantedNone)
        {
            if(commandName == "MyAddin1.Connect.MyAddin1")
            {
                status = 
                (vsCommandStatus)vsCommandStatus.
                vsCommandStatusSupported|vsCommandStatus.
                vsCommandStatusEnabled;
            return;
            }
        }
    }

    public void Exec(string commandName, vsCommandExecOption 
    executeOption, ref object varIn, ref object varOut, ref bool 
    handled)
    {
        handled = false;
        if(executeOption == 
          vsCommandExecOption.vsCommandExecOptionDoDefault)
        {
            if(commandName == "MyAddin1.Connect.MyAddin1")
            {
                handled = true;
                System.Windows.Forms.MessageBox.Show("Add-in ran.");
                return;
            }
        }
    }
    private DTE2 _applicationObject;
    private AddIn _addInInstance;
    }
}

See Also

Community Additions

ADD
Show:
© 2014 Microsoft