[Guest Post by Marty Andren, Premier Field Engineer at Microsoft]
As a Microsoft Premier Field Engineer / Office Developer, a question I’m often asked when helping customers develop VSTO solutions is how to customize the user interface when building out their application. This question is not as simple as it sounds, as the approach used will vary depending on which version of Visual Studio you are using, and which version of Office you are targeting for your particular application. There are a number of good references available on MSDN that address this very topic. I’ve listed out a couple of these below:
- Using Visual Studio 2013 (or 2012) to target Office 2010 or Office 2013
- Using Visual Studio 2010 to target Office 2007 or Office 2010
One area in particular where developers new to VSTO want a deeper understanding is how to work with ribbons and ribbon controls. When creating custom ribbons for a VSTO application, it’s generally easiest to start with the VSTO Ribbon Designer (unless you have a compelling need to use Ribbon XML for advanced functionality like overriding default Office commands or customizing the backstage). Adding a ribbon to your VSTO project is simple. As can be seen in the screenshot below, simply right click on the project in Solution Explorer, select Add > New Item, and choose Ribbon (Visual Designer) from the list of available options.
Having added a ribbon (and in the case of Outlook, having defined where it will show up), you can start dragging additional controls from the toolbox to customize the ribbon to meet your needs. Also note that converting a visual ribbon to an xml ribbon within Visual Studio is a very simple thing to do. Once you’ve completed customizing the visual ribbon in the designer window, simply right click on the ribbon in the designer, and select “Export to XML” from the popup menu.
Regardless of the type of ribbon added to the project, understanding how to define the icons presented on the controls contained in that ribbon is another area developers new to VSTO struggle with. In general, there are two possible options for doing this type of customization:
- Adding your own custom icons to your solution, and referencing them on the controls using the Image property.
- Leveraging the vast library of icons provided with Microsoft Office through the use of the OfficeImageId property.
The latter approach tends to be more commonly used, both because you don’t have to generate your own icons, and because the Office provided icons will look more natural inside of an Office application. As developers learn fairly quickly however, finding the right ID for the icon you wish to use can be a bit of a challenge. This is further complicated by the fact that the icon / id combinations can vary slightly from one version of Office to another (In general, the Office product team tries to keep the Id’s consistent from version to version to help ensure backward compatibility as new versions of Office are released, however there are times when an Id needs to be changed as the product evolves). To help developers out with this, Microsoft has published a couple useful resources that catalog all of the icons for a particular version of Office. I’ve listed out where to find these below:
- Office 2010 Add-In: Icons Gallery (Can also be used with Office 2013)
- Office 2007 Add-In: Icons Gallery
To see this in action, let’s work with the following example: Say your app exposes functionality to delete a report, and you want to use one of the standard Office images. You review the options in one of the icon galleries mentioned above, and decide that the Sheet Delete icon fits your needs nicely. To utilize this icon in a ribbon button of your application, you would select the button in the designer window, and from within the Properties window set the OfficeImageId to the ID of the image you’re looking to use (in this case, conveniently named “SheetDelete”):
It’s important to note that in the Ribbon Designer in Visual Studio, the button will just show up with a placeholder, but it will be replaced with the correct icon at runtime:
Note also that the same icon can be specified in Ribbon XML by setting the imageMso attribute as follows:
<button id="Button1" imageMso="SheetDelete" label="Delete Report" />
In addition to working with custom controls, there may also be times where you want to access the built-in controls in an Office application (to hide or disable a particular button on the ribbon for example). Finding the ID of the particular control in question can be as challenging as looking for the appropriate icon ID described above. Fortunately, Microsoft has published a few resources to help developers out in this area as well:
- Office 2013 Help Files: Office Fluent User Interface Control Identifiers
- Office 2010 Help Files: Office Fluent User Interface Control Identifiers
- 2007 Office System Document: Lists of Control IDs
- And, of course, the interactive "Icons Gallery" links from above (copying here for easy reference):
Let me close by saying that I would encourage VSTO developers to download all of these resources / reference materials, regardless of whether they are new or experienced in this space. I’ve found all of these to be extremely useful when developing VSTO solutions and I trust you will too.
Premier Field Engineer, Office Developer Lead
US PFE – East Region