Logo
HOWTO: Handling buttons and toolbars user customizations from a Visual Studio add-in

Author: Carlos J. Quintero (Microsoft MVP) Applies to: Microsoft Visual Studio .NET 2002
Date: July 2008   Microsoft Visual Studio .NET 2003
Updated: March 2013   Microsoft Visual Studio 2005
      Microsoft Visual Studio 2008
      Microsoft Visual Studio 2010
      Microsoft Visual Studio 2012
Introduction

This article explains how to handle buttons and toolbars customizations that the user can perform in Visual Studio with the user interface provided by an add-in.

More Information

The article HOWTO: Adding buttons, commandbars and toolbars to Visual Studio .NET from an add-in explained how to create commands, toolbars and buttons from a Visual Studio add-in, either with a temporary user interface or with a permanent one:

  • With a temporary user interface, the add-in creates its toolbars and buttons when loaded, and delete them when unloaded (that is, when the add-in is not loaded, there is no user interface). For add-ins with a single toolbar and few buttons, this scenario is recommendable.
  • With a permanent user interface, the toolbars and buttons are created once in the add-in lifetime and are not deleted when the add-in is unloaded (only when it is uninstalled). For add-ins with lots of toolbars and buttons, creating the user interface each time that the add-in is loaded can be time consuming, so it may pay off to use the permanent user interface approach, at the risk of confusing the user maintaining the user interface even if the add-in is unloaded through the Add-In Manager.

In both scenarios, commands are created once in the add-in lifetime and remain created until the uninstaller deletes them. This is needed to preserve the keyboard bindings that the user may have created for the commands.

However, the article assumed that the toolbars and buttons created by the add-in would not be changed by the user. Since Visual Studio allows a rich customization of the user interface, if an add-in provides many toolbars and buttons, chances are that the user will want to perform some customization with the mechanism provided by Visual Studio. When clicking the Tools, Customize... menu, two things happen in Visual Studio:

  • Visual Studio shows a Customize dialog window with two tabs: Toolbars and Commands.
  • Visual Studio enters in customization mode, allowing the user to right-click on any toolbar button and change its properties (text, image, begin group, etc.), to delete toolbar buttons, to move them, to drag commands from the Commands tab to any toolbar, etc.

We will review the customizations that the user can perform, and how an add-in can handle them with a temporary and a permanente user interface scenario. As you will notice, in the permanent user interface scenario everything is handled by Visual Studio (as it does with its own built-in user interface) while in the temporary user interface scenario an add-in must handle the customization when loading/unloading the add-in (there are no customization events to do it meantime):

  • Making invisible a toolbar of the add-in: the user can perform this customization at any time (customization mode is not required) just right-clicking on any toolbar and unchecking the desired toolbar in the list.

    - Temporary user interface: when unloaded, before deleting the toolbar, the add-in should examine the Visible property of the CommandBar and store its state in the Windows registry or somewhere else, to restore the same visibility state when the add-in is loaded again.

    - Permanent user interface: no action is required since Visual Studio will persist the user interface.
  • Deletion of a toolbar or commandbar of the add-in: the user can perform this customization in the Customize dialog window, Toolbars tab, selecting the toolbar and clicking the Delete button.

    - Temporary user interface: it is unfortunate that Visual Studio allows to delete temporary toolbars of add-ins, because when unloaded, the add-in will try to delete the toolbar and an exception will be thrown, and a mechanism for the user to make invisible undesired toolbars already exists, as explained in the previous paragraph. Anyway, in this case the add-in must catch and ignore the exception silently, take note of this fact for the following time that it is loaded. When the add-in is loaded again, then create the toolbar but make it invisible (hoping that if the user doesn't see it, it won't go to the Customize dialog window to delete it again). Alternatively, the add-in can choose not to create it because the user deleted it, but in that case the user can't recreate it easily unless she knows where the add-in stores that information to reset it.

    - Permanent user interface: no action is required since Visual Studio will persist the user interface.
  • Changing the size or position of a toolbar of the add-in: the user can perform this customization at any time (customization mode is not required) undocking the toolbar using the grip to the left of the toolbar.

    - Temporary user interface: when unloaded, before deleting the toolbar, the add-in should examine the RowIndex, Position, Top, Left, Width and Height properties of the CommandBar and store its state in the Windows registry or somewhere else, to restore the same state when the add-in is loaded again.

    - Permanent user interface: no action is required since Visual Studio will persist the user interface.
  • Creation of a new toolbar: the user can perform this customization in the Customize dialog window, Toolbars tab, and clicking the New... button. Once the toolbar is created, the user can place buttons on it as explained later.

    - Temporary user interface: no action is required since Visual Studio will persist the user interface.

    - Permanent user interface: no action is required since Visual Studio will persist the user interface.
  • Deletion of a button of the add-in from one of its toolbars or commandbars: using Visual Studio 2005 or higher, the user can perform this customization in the Customize dialog window, Commands tab, Rearrange Commands button, selecting the toolbar or menu bar, selecting the button and clicking the Delete button. Using any version of Visual Studio, the user can perform this customization by entering in customization mode and while the Customize dialog window is shown, right-clicking the desired button and clicking the Delete menu entry of the context menu.

    - Temporary user interface: when unloaded, if the add-in deletes the toolbar without deleting its buttons first (which is the fastest approach), then this customization would be lost. In this case the add-in should provide among its options its own dialog window to allow the user select which buttons should be visible and instruct the user to use it rather than the mechanism provided by Visual Studio. Otherwise the add-in should delete the buttons before deleting the toolbar (which is slower). When trying to delete an already deleted button the add-in must catch and ignore the exception silently and take note of this fact for the following time that it is loaded. When the add-in is loaded again, then create the toolbar without that button. In this case the add-in should provide a way to allow the user to restore the buttons of its toolbars.

    - Permanent user interface: no action is required since Visual Studio will persist the user interface.
  • Addition of a button external to the add-in to one of its toolbars: using Visual Studio 2005 or higher, the user can perform this customization in the Customize dialog window, Commands tab, Rearrange Commands button, selecting the toolbar or menu bar, and clicking the Add... button. Using any version of Visual Studio, the user can perform this customization entering in customization mode and while the Customize dialog window is shown, select the Commands tab, Add-ins section, and drag and drop a command from the list on the toolbar.

    - Temporary user interface: this customization will be lost since it is difficult for the add-in to become aware of external buttons placed on its toolbar, and even more difficult to try to restore them when the add-in is loaded again.

    - Permanent user interface: no action is required since Visual Studio will persist the user interface.
  • Addition of a button of the add-in to a toolbar not belonging to it: this customization is performed with the same procedure described in the last paragraph.

    - Temporary user interface: no action is required since Visual Studio will persist the user interface. When the user clicks the button on the toolbar, Visual Studio will load the add-in if it is not loaded and will execute the command (at least using the latest Visual Studio versions, older ones seem to cause an error).

    - Permanent user interface: no action is required since Visual Studio will persist the user interface.
  • Changing the position of a button of the add-in on one of its toolbars: using Visual Studio 2005 or higher, the user can perform this customization in the Customize dialog window, Commands tab, Rearrange Commands button, selecting the toolbar or menu bar, and clicking the Move Up... and Move Down... buttons. Using any version of Visual Studio, the user can perform this customization entering in customization mode and while the Customize dialog window is shown, drag and drop a button between two positions on the toolbar.

    - Temporary user interface: this customization is difficult to handle since it requires the add-in to enumerate the buttons on its toolbars when unloaded, identify each one (by caption or using the Tag property of the CommandBarButton), store the order information somewhere and use it to recreate the toolbar the next time that it is loaded. Alternatively the add-in could use the same dialog window suggested before to select the visible buttons to allow also to change the position of buttons and instruct the user about it. Another option is to instruct the user to create a separate toolbar with the desired buttons and hide the toolbar provided by the add-in.

    - Permanent user interface: no action is required since Visual Studio will persist the user interface.

Go back to the 'Resources for Visual Studio .NET extensibility' section for more articles like this


Top