Published Thursday, September 14, 2006 9:50 AM by martin

Office 2007 Ribbon Extensibility - Loading Images

When you extend the ribbon in an Office 2007 application, there are a number of different ways for your code to supply images for the controls in your extension.  In an attempt to enumerate them all, I've listed some xml fragments below with a description of how each approach works...

<button imageMso="PrintPreview" />

This attribute allows you to specify one of Office's own control images to be used in your control.  You can download the complete list of Office control IDs here.

<button getImageMso="GetMyControlImageMso" />

This similar attribute causes the application to invoke a callback function that you supply, in this case called GetMyControlImageMso.  Your function should return an Office control ID, just as above.  This approach allows you to decide on an image to use at runtime.

To load your own custom images for use in your controls, you have to provide a callback function that returns an object of type IPictureDisp.  There are plenty of examples of doing that out there, so I won't muddy the waters with another one here, just search for "ribbon" and "IPictureDisp".  All of the following approaches depend on a callback function that can return an IPictureDisp for your image...

<customUI xmlns="..." loadImage="OnLoadImage" />

Using this attribute on the root element of your ribbon xml specifies a single callback function that will be called whenever the application needs to fetch the image for one of your controls.  In this case, the OnLoadImage callback function takes a string parameter, to tell it exactly which image is required.  Each control in your xml specifies the image it needs using the image="..." attribute, as follows...

<button image="myButtonImage" />

In this case, the application will call OnLoadImage and pass in the string "myButtonImage".

<button getImage="GetMyButtonImage" />

This approach allows you provide a separate callback function for each control.  In this case, my button will use the function GetMyButtonImage to fetch its image, in IPictureDisp format of course.

For controls that belong inside a container of some sort, such as galleries, combos, and drop-downs, a slightly different approach is used...

<gallery getItemImage="GetMyGalleryItemImage" />

In this example, you supply a callback function that can fetch images for the application, in IPictureDisp format.  Your callback function takes an integer parameter, specifying the index within the gallery of the item whose image is being sought.

There.  That's quite a few different possibilities for just loading images :-)