Jensen Harris: An Office User Interface Blog : Developer

Using RibbonX with C++ and ATL

jensenh — Fri, 08 Dec 2006 18:00:00 GMT

Today's Guest Writer: Eric Faller

Eric is a Software Design Engineer on the Office User Experience team focused on user interface extensibility for Office developers.

Another source of frequently-asked RibbonX questions is around the complexity of writing an add-in in C++. Compared to the ease of use of C# or VB.NET, C++ requires a much deeper understanding of what's really going on under the covers and often involves hand-implementing much of the "magic" that the higher-level languages take care of automatically.

This post covers the details of RibbonX's communication with COM add-ins via the IRibbonExtensibility and IDispatch interfaces and shows an example of creating an add-in with ATL. It's primarily intended for C++ developers, but if you're writing an add-in with .NET you may find it useful to understand what the CLR is automatically doing for you under the hood.

IRibbonExtensibility

As soon as Office boots up a COM Add-In, it checks if it implements the IRibbonExtensibility interface on its main Connect class via a QueryInterface() call for IID_IRibbonExtensibility (defined in the MSO.DLL typelibrary). If it does, it takes the IRibbonExtensibility pointer and QI's it for the IDispatch interface and saves both pointers off in a safe place.

Note that Office queries the IRibbonExtensibility interface for IDispatch, instead of the main interface. Normally this is unimportant, but it allows complicated add-ins to split their IDispatch interfaces off onto multiple objects if they provide multiple IDispatch implementations. For example, Excel add-ins can provide User-Defined Functions (UDFs) via IDispatch, and they usually won't want to have all of their RibbonX callbacks and UDFs on the same object.

Next, RibbonX will call the IRibbonExtensibility::GetCustomUI() method and get the XML for each type of Ribbon that's currently open. Most applications have only one Ribbon that's open all the time (Word, Excel, PowerPoint and Access), but Outlook has many different Ribbon types, any number of which can be open at a given time. GetCustomUI() can be called at arbitrary points after the add-in boots if the user opens up a new type of Ribbon, so add-ins should not do any extraneous processing inside that function or assume that it will always be called immediately after the add-in boots. GetCustomUI() should simply fetch and return the appropriate XML, without any side effects.

Once the appropriate XML is parsed and applied, RibbonX will invoke the add-in's "onLoad" callback (if it exists), as well as any "get" callbacks (such as getEnabled, getVisible or getLabel). These callbacks are all invoked via the IDispatch pointer that was queried for above.

IDispatch

If you're unfamiliar with IDispatch-based interfaces, you may be curious how it is that Office can call arbitrary C++ functions in an add-in, given only their names. For example, consider a button specified with this XML:


<button id="MyButton" onAction="ButtonClicked"/>

In my add-in I can write a ButtonClicked() function, but once it's complied and linked, the "ButtonClicked" name is optimized away and we're left with just a memory address where the function's code begins. How does Office find and call the function? Obviously there's something magic going on, and it's known as IDispatch.

IDispatch is a COM interface used for "dispatching" function calls to objects when their types are unknown or need to be late-bound. It's the reason that this VBA code works even though the "word" variable is not strongly typed:


Dim word
Set word = Application 
word.CheckSpelling ("misspellled")

The IDispatch interface contains a whole bunch of methods which you can read all about in the documentation, but the main two to be concerned with are GetIDsOfNames() and Invoke().

The GetIDsOfNames() method provides a mapping between names (strings) and "DISPIDs", which are basically integers that represent functions or properties. With the example button above, Office will call into the add-in's GetIDsOfNames() method and ask "hey, do you implement the ButtonClicked function?", and the add-in with either say "yes I do, and it's DISPID number 2" (for example), or "no, I don't implement that function."

Once the function is found, the IDispatch::Invoke() method is used to actually call the function. Invoke() takes the DISPID of the function, an array of parameters, and gets the return value back. In our example Office will call the add-in's Invoke() method and say "call your ButtonClicked function with this IRibbonControl parameter and let me know how it goes."

Parameters and return values are passed around in VARIANT structs, which are basically big unions that can contain values of many different types. We could go into lots of detail about how to set up and use VARIANTs, but fortunately there are ATL classes that take care of all of this for us so there's normally no reason to worry about them.

That pretty much sums up the high-level overview of how IDispatch works, so let's see it in action and build a simple RibbonX add-in in C++ with ATL.

Building a simple C++/ATL RibbonX add-in

The steps for creating a C++ RibbonX add-in start off pretty much the same as for a C# add-in:

Open up Visual Studio
Click "New Project"
Select "Extensibility" under "Project types" and choose "Shared Add-in"
Give it a name and click OK:

Click to view full picture

Click through the wizard that shows up, making sure to check "Create an Add-in using Visual C++/ATL" and "I would like my Add-in to load when the host application loads."

Now you have an empty C++ add-in. Click "Build Solution" just to make sure that it all compiles OK with no problem.

Next, open up Class View, right-click on your CConnect class and select "Add -> Implement Interface…" In the dialog that pops up, select the "Microsoft Office 12.0 Object Library <2.4>" type library and add the "IRibbonExtensibility" interface from it:

Note: you may have an older type library registered instead (such as "Office 11.0 Object Library") if you previously had older versions of Office installed on the same computer. In those cases you can just browse to the "OFFICE12" version of MSO.DLL and select it manually.

Once you're done with that, Visual Studio should have auto-generated your GetCustomUI() function for you. Delete its "return E_NOTIMPL;" and paste in some valid code, like this:

STDMETHOD(GetCustomUI)(BSTR RibbonID, BSTR * RibbonXml)
{
  if (!RibbonXml)
    return E_POINTER; 

  *RibbonXml = SysAllocString(
    L"<customUI xmlns=\"http://schemas.microsoft.com/office/2006/01/customui\">"
    L" <ribbon>"
    L"   <tabs>"
    L"    <tab id=\"CustomTab\"" 
    L"         label=\"Custom Tab\">" 
    L"     <group id=\"CustomGroup\"" 
    L"            label=\"Custom Group\">" 
    L"       <button id=\"CustomButton\"" 
    L"               imageMso=\"HappyFace\""
    L"               size=\"large\"" 
    L"               label=\"Click me!\"" 
    L"               onAction=\"ButtonClicked\"/>" 
    L"     </group>" 
    L"    </tab>" 
    L"   </tabs>" 
    L" </ribbon>" 
    L"</customUI>" 
  ); 

  return (*RibbonXml ? S_OK : E_OUTOFMEMORY); 
}

Now, a real add-in would obviously not hard-code its XML like this (embedding it as a resource in the DLL would be much better), but this suffices for our simple demo. Don't do this at home!

At this point we should try to compile the add-in and see our dummy button sitting on the Ribbon. Unfortunately when I tried compiling at this stage, there were several compilation errors in the auto-generated code due to namespace conflicts between the MSO type library and other Windows headers. I did these things to fix it:

Open up "stdafx.h" and move the #import statement for MSO.dll from the bottom of the file up next to the #import statement for the Extensibility library inside the #pragma blocks (remove any 'no_namespace' annotations from that line as well)
Add "using namespace Office;" to the top of the Connect.h file.

Now we can build successfully and see our button:

If we click it we get an error saying "The callback function 'ButtonClicked' was not found," which makes sense since we haven't written that function or implemented it via IDispatch yet. Let's use ATL to do that now.

Unfortunately Visual Studio 2005 doesn't seem to have a "New ATL Interface" wizard, but we can get the same thing accomplished by creating a generic ATL class and then deleting the implementation. Click "Add Class…" on the Standard Toolbar and select "ATL Simple Object" in the ATL category. Name the object something like "CallbackInterface" and hit Finish.

Now in Class View we have several new objects: an ATL interface called "ICallbackInterface" and an implementation class called "CCallbackInterface." We don't need the implementation, so go ahead and delete all the CallbackInterface.* files from the Solution Explorer. ICallbackInterface is what we care about and it's defined in our add-in's IDL file.

Back in Class View, right-click on ICallbackInterface and select "Add -> Add Method…" In the Add Method Wizard, add a method named "ButtonClicked" with one [in] parameter of type IDispatch* called RibbonControl:

This parameter is the IRibbonControl object that's passed to all RibbonX callbacks. Since "IRibbonControl" isn't in the parameter type dropdown, we have to go with its base type, which is IDispatch (IRibbonControl is not a type supported by the VARIANT structure). If we need it later, we can always call QueryInterface() on it with IID_IRibbonControl and get it.

Now that our interface is defined, right click on the CConnect class and select "Implement Interface…" again to add ICallbackInterface along with IRibbonExtensibility. Double-click the ButtonClicked function in Class View to be taken to the auto-generated implementation. Swap out its placeholder content with something meaningful, like this:


STDMETHOD(ButtonClicked)( IDispatch * RibbonControl)
{ 
  // Add your function implementation here. 
  MessageBoxW(NULL,
     L"The button was clicked!", 
     L"Message from ExampleATLAddIn", 
     MB_OK | MB_ICONINFORMATION);

return S_OK;
}

Now when we compile we should see this MessageBox when we click the button. However, there are a couple of problems left before we can do that, the first of which is "error LNK2001: unresolved external symbol _LIBID_ExampleATLAddInLib." Since our DLL is both the source and consumer of our new typelibrary for ICallbackInterface, we need to link in the MIDL-generated C files for it. In Solution Explorer, add the "AddIn_i.c" file, which is the output from running MIDL on our AddIn.idl file. This new file will inherit the solution defaults for PCH files ("Use Precompiled Headers (/Yu)"), which isn't what we want, so right-click on it and switch the file to "Not Using Precompiled Headers".

The last work item is to set up the COM_MAP to properly route the IDispatch calls to our ICallbackInterface. In Connect.h, switch the IDispatch line in the COM_MAP to ICallbackInterface instead of IRibbonExtensibility:


BEGIN_COM_MAP(CConnect) 
  COM_INTERFACE_ENTRY2(IDispatch, ICallbackInterface) 
  COM_INTERFACE_ENTRY(AddInDesignerObjects::IDTExtensibility2) 
  COM_INTERFACE_ENTRY(IRibbonExtensibility) 
  COM_INTERFACE_ENTRY(ICallbackInterface) 
END_COM_MAP()

Once that's all built, try out the add-in and see that it works!

That's basically all there is to making a C++ RibbonX add-in with ATL. Obviously a more complicated add-in would have many more callbacks, but the only additional work would be to right-click on ICallbackInterface and select "Add Method.." for each one. Different types of callbacks have different parameters, so you just need to make sure that your callbacks match the C++-style signatures in the RibbonX documentation. A "getLabel" callback, for example, would have the same parameters, except it would have an additional "[out, retval] BSTR *Label" parameter for returning the label.

For more info about RibbonX, check out the documentation mentioned above, the Developer category on this blog, or the Office Discussion Groups if you have other questions not specifically related to the topics of this article.

Update: Eric has made the resulting Visual Studio 2005 project available for download.

RibbonX Image FAQ

jensenh — Mon, 27 Nov 2006 18:00:00 GMT

Today I'm delighted to present a new guest writer to the blog: Eric Faller, Software Design Engineer on the Office User Experience Team.

Eric is one of the developers on our team who helped to design and implement RibbonX, the user interface extensibility model for Office developers.

Today's Guest Writer: Eric Faller

Some of the most commonly asked questions around RibbonX deal with how to load and get images to display properly in the Ribbon. This FAQ about images assumes that you're already familiar with writing RibbonX add-ins. If you're just getting started, check out the official documentation or the Developer category on this blog.

Alpha channels, masks, color keys, oh my!

The most significant change in Office 2007 is the switch to use images with alpha channels, instead of the masks or color keys used in previous Office releases. If that sentence sounds confusing, you're not alone. What are all these different technologies and what problem are they trying to solve?

The problem at hand is: how do we specify which parts of our images are transparent and should let the background color of the Ribbon show through? Before tackling that question, we should look at why it's even necessary to do this in the first place.

In the past, many add-in writers bypassed the entire issue by copying the background color of Office's UI and using that as the background color in their image. There are a couple of reasons this doesn't work very well. If the user switches their UI theme colors, or a new release of Office uses a different color, the icon suddenly looks out of place. For example, consider the following add-in image which looked good on gray toolbars but looks out of place in the Ribbon without transparency:

As we can see, in order for an add-in to look professional, it's going to need to pay attention to transparency. Let's look at what features previous releases of Office offered to solve this problem.

Color keys

One way to solve this problem is to mark a certain color in the image as the "color key" and pretend that that color is transparent when drawing the image in the UI. The "hot pink" color is often used for this task since it doesn't occur very often in real icons:

The problems with this approach might be obvious. Back in the day when 16-color icons were the norm, an entire color had to be wasted as the transparent color. This color also had to be kept track of separately from the image itself: the image didn't contain the entire information needed to draw it properly. One way to work around this was to pick a specific pixel, such as the top-left corner, and use that as the color key, which led to the obvious problem of the top-left corner being unavailable for actual image content.

Picture & Mask

The CommandBars system solved the main problems with color keys by requiring add-ins to provide two different images to make up their icons: the "Picture" and "Mask" properties. The Picture image contained the color data of the icon, and the Mask was a black-and-white image that specified which pixels should be transparent. The Pictures and Masks were combined when drawing the final image on the UI. For example:

The most obvious drawback with this system is that you need to draw and keep track of two images per icon.

Another problem with both the Mask and Color Key systems is that they only allow for a single level of transparency: a pixel is either transparent or it's not. There's no room for a pixel to be "half-transparent." In today's world of rich, visual user interfaces, that's just not good enough anymore.

Alpha channels

Alpha channels are a concept from computer graphics which involves adding another "channel" to each image to keep track of transparency information (along with the Red, Green and Blue channels). Each pixel contains a 4th "color" value which keeps track of how transparent it is, on a scale from completely opaque to completely transparent. When each individual pixel can have varying levels of transparency, it's possible to create nice smooth looking images.

For example, here's what our "A" image looks like when it's drawn in the Ribbon with an alpha channel:

The main problem with alpha channel-enabled images is that it's difficult to create them and make them look good. For example, Microsoft Paint does not support alpha channels so you will need to turn to professional-level software such as Photoshop (or free alternatives such as Paint.NET) to draw them.

File formats

Another hurdle to using alpha channels is that common file formats do not support them uniformly:

Format	Supports Transparency?
BMP	No (technically Yes, but most libraries don't load it properly)
JPEG	No
GIF	Single level only (no semi-transparency)
PNG	Yes - full support

PNG is the only common file format with full alpha channel support and widespread tool support. It's the recommended format for storing RibbonX images.

So, you might be wondering "Which file formats does RibbonX support?"

RibbonX operates on bitmap objects in code, not on files on the disk. It's the add-in which actually loads the files and returns the bitmap objects to RibbonX. Thus, an add-in can use whatever file format it wants when it is loading its images.

A better way to think about the question might be, "What file formats do the libraries I'm using support?" Unfortunately the answer can be a bit complicated because the libraries for different languages and technologies (VBA, C++, .NET, etc.) vary widely in their support for image file formats and alpha channels. GDI+ can be used from both native C++ code as well as managed C#/VB.NET code and it supports loading all common file formats, so it's the recommended library to use to load images.

If you're using VBA, you might think you're out of luck since the native VB APIs like LoadPicture() don't support PNG files, and you can't use GDI+ without mucking around with importing Win32 functions and types. Fortunately, VBA add-ins live in the new Open XML format files (except for in Access), and they can refer to files directly in those ZIP packages. RibbonX will do the work of automatically loading those files out of the packages, so most VBA code should not need to worry about loading image files. In this case RibbonX uses GDI+ to load those files, so any file format supported by GDI+ is supported in Open XML files (almost all formats). VBA add-ins will only need to load images themselves if they want to dynamically switch icons at runtime (this is not recommended by the UI guidelines since this almost never happens in the built-in Office UI.)

16-bit vs. 32-bit

Several things can go wrong in an add-in while it's loading its images before it passes them off to RibbonX. These usually involve the in-memory format used to store the image.

When storing an image in memory, how should the pixel data be represented? In the past, a wide variety of options were available (palletized, 4-bit, 16-bit, 24-bit, etc...), but today the most commonly encountered formats are 16 bits per pixel (bpp) and 32 bpp.

Remember that with alpha channels, each pixel stores its transparency value along with the color data. With 16-bit formats, 5 bits are usually allocated for each of the Red, Green and Blue channels (sometimes 6 bits for Green), leaving only 0 or 1 bits for alpha, which isn't enough. Thus, when an image is loaded into memory in 16-bit format, its alpha channel is usually compacted or deleted completely. Obviously this isn't what we want, so in our RibbonX add-ins, we need to always load images into memory in 32-bit formats, allocating 8 bits each for the Red, Green, Blue, and Alpha channels

So, if the file format you're using (PNG, for example) includes the full 32-bit pixel data, why would the image become compacted to only 16 bits when loading into memory? Unfortunately this happens more than one might expect.

DIB vs. DDB

Windows has a concept of "Device-Dependent Bitmaps" (DDBs) and "Device-Independent Bitmaps" (DIBs). The "device" referenced here is the graphics card and display on the computer. Today most displays can be set to either 16-bit mode or 32-bit mode. If your display is in 16-bit mode, DDBs will be in 16-bit format ("dependent" on the device), while DIBs will usually be 32-bit (since they are "independent" of the mode the device is actually in). If your display is in 32-bit mode, DDBs will be 32-bit and DIBs will usually be too, so there's no practical difference between DDBs and DIBs. Writing your code assuming there is no difference is often a cause of difficult bugs.

A commonly encountered problem is "My RibbonX icon looks fine on my computer, but on my tester's computer it looks horrible," or "It looks fine everywhere except over Remote Desktop, where it looks bad." In this case the tester's computer is probably running a 16-bit display. Remote Desktop and Terminal Services also default to 16-bit display modes in many cases.

The root of the problem is that the add-in is loading its images as DDBs, and on the 16-bit displays, the pixel data gets compacted to 16-bits and the alpha channel is thrown away. On 32-bit displays, the DDBs are equivalent to DIBs, and the pixels are loaded into 32 bits and everything works fine.

The fix is to make sure that your code always loads images as DIBs, never DDBs. Unfortunately for us, most Win32 image loading functions will create DDBs by default. This can be overridden by making sure to pass in LR_CREATEDIBSECTION to functions which take that flag, such as LoadImage(), CopyImage(), etc.. If you want to know whether you have a DIB or a DDB, you can call GetBitmap() on your HBITMAP with a DIBSECTION structure and test if that succeeds or fails.

Fortunately, if you are writing a .NET managed add-in and are using GDI+ to load your images, you don't have to worry about this because GDI+ uses DIBs internally.

IPictureDisp vs. System.Drawing.Bitmap

Once you have your image all loaded up, how do you return it to RibbonX? If you take a look at the return value of the "getImage" and "loadImage" functions, you'll see that it's a generic "object" type (or "IUnknown" in unmanaged code). The following types of values are accepted:

IPictureDisp objects
System.Drawing.Bitmap objects
Strings (equal to the "imageMso" value of a built-in icon to use)

The 3rd option can be used if you want to re-use a built-in image. The first two require loading your own image and are more complicated.

The type of value you should return depends on the language you are using to write your add-in:

VB6/VBA: IPictureDisp is the "COM name" of Picture, which is the native VB image type. You can just take the return value from the VB LoadPicture() function and return it (LoadPicture does not support PNG files, though, see the discussion above).
C/C++ and other native code: IPictureDisp is your best bet. IPictureDisp objects are really just wrappers around HBITMAPs or HICONs, which are the native Win32 image types. You can either create IPictureDisps directly using functions like OleLoadPicture(), or indirectly by filling in a PICTDESC structure with an HBITMAP and calling OleCreatePictureIndirect() to convert it to an IPictureDisp. You can get the HBITMAP from any image-loading function you want, but GDI+ is the recommended library since it supports PNG files.
C#/VB.NET and other managed code: System.Drawing.Bitmap is the native type of .NET languages, so it's easiest to just return Bitmap objects directly. If for some reason you want to convert them to IPictureDisp objects, you could do so using the AxHost.GetIPictureDispFromPicture() method.

Right now you might be wondering to yourself, "If Office is a native unmanaged application, how does it know what a managed System.Drawing.Bitmap object is?" This is a good question, and the answer is that it actually doesn't know. Through the magic of COM interop, the .NET Bitmap object is converted to a COM-compatible IDispatch interface which can be manipulated by Office. RibbonX takes this IDispatch object and checks if there is a "GetHbitmap()" function available on the interface. If there is, it uses Invoke() to call that function and get an HBITMAP object that corresponds to the original Bitmap object.

So in reality, RibbonX functions are not limited to returning System.Drawing.Bitmap objects, they can actually return any objects which have functions named "GetHbitmap." If for some reason you needed to, you could create your own class with a GetHbitmap() function and use that instead of System.Drawing.Bitmap.

Bitmaps vs. Icons

Some add-in writers store their UI icons in .ICO files and load them into HICON or System.Drawing.Icon objects.

RibbonX can load .ICO files from Open XML format files, and it will accept HICON-based IPictureDisps, but its icon support is somewhat limited and it doesn't accept System.Drawing.Icon objects at all.

Several RibbonX features do not work with icon-based images, such as the automatic "graying out" of images when their respective buttons are disabled, so it's recommended that add-ins provide bitmaps instead of icons. If you have a System.Drawing.Icon object, you can convert it to a Bitmap using the .ToBitmap() method.

getImage vs. loadImage

Another common question is "Why are there both getImage and loadImage functions? Which should I use?"

The answer is that you should almost always use loadImage, except when you need to dynamically change your controls' images at runtime, in which case you should use getImage on those controls.

loadImage provides these advantages over getImage:

If multiple controls use the same image, loadImage is called only once, saving time and space.
If a control is invalidated (for example, in order to change its enabled state), loadImage is not uselessly called again.
Arbitrary strings can be specified in the "image" property and passed to loadImage (for example, a resource ID or filename), but with getImage you're stuck with the ID of the specific control you're interested in.

The main advantage of getImage is that its return value can be invalidated using IRibbonUI.InvalidateControl() and changed dynamically at runtime. Once an image is set with loadImage, it's permanent.

Further reading

For more information, check out the official RibbonX documentation.

If you have specific support questions unrelated to this article, try the Office Discussion Groups.

Licensing the 2007 Microsoft Office User Interface

jensenh — Wed, 22 Nov 2006 00:00:00 GMT

For the last year or so, one of the questions I've been asked again and again has been: "Can I use the new Office user interface in my own product?"

On one hand, it's an immensely satisfying question to hear, because it means that others in the industry believe in the value of what we've built and see how the sound UI research we've done can benefit their own products. Creating the new user interface has been our team's passion for the last three years, and we love sharing the fruits of this hard work.

On the other hand, the new Office user interface was a huge investment by Microsoft and the resulting intellectual property belongs to Microsoft.

As a result, I've never been totally comfortable answering questions about whether people can use the new UI or not publicly because, honestly, I didn't really know the answer. You might have noticed I've been pretty quiet on the subject.

Internally, though, more than a year ago we started talking about how we could share the design work we've done more broadly in a way that also protects the value of Microsoft's investment in this research and development.

Well, I'm pleased to finally be able to definitively answer the question. Today, we're announcing a licensing program for the 2007 Microsoft Office system user interface which allows virtually anyone to obtain a royalty-free license to use the new Office UI in a software product, including the Ribbon, galleries, the Mini Toolbar, and the rest of the user interface.

Last week, I recorded a video along with Judy Jennison, the lawyer who has been spearheading the licensing effort, to chat about the UI license in detail. Take a look, or keep reading to learn more.

(If you ever wondered what my office looks like, here's your chance!)

Watch the Channel 9 video about the Office 2007 UI License

How does the license work?

It's pretty simple really. First, you visit the Office UI Licensing web site. On this page, you'll find some information about the licensing program, a downloadable copy of the license to peruse at your leisure, and further contact information.

If you choose to implement the Office UI, you sign up for the program by accepting the license terms and giving us a little bit of information about your product. There's no fee, you don't owe Microsoft any royalties, and the license is perpetual—meaning that the terms won't change.

This should give you the confidence you need to build a business or product on top of the Office UI platform, secure in the knowledge that you've licensed the technology and research you're using in your product.

You must follow the guidelines, though.

Included with the license you'll find the 2007 Microsoft Office System User Interface Guidelines. This 120+ page document includes all of the information you need to implement Office-style UI; think of it as the specification for how the UI needs to work in your product.

To stay within the terms of the license, you must follow these guidelines.

We want to ensure that when someone implements the Ribbon (for example) that they do so the right way… and in a way consistent with how it works in Office.

There's tremendous value in making sure that we all use these models in a consistent way, because it helps to ensure that people have predictable user experiences moving between Office-style user interfaces.

In the guidelines you'll find REQUIRED sections and OPTIONAL sections. The REQUIRED sections are exactly that—sections that you must implement in order to stay within the letter of the license.

Within each section, you'll see things you MUST implement, things you SHOULD implement, and BEST PRACTICES. Just like it sounds, you must implement the UI as specified by the MUSTs in the document to comply with the terms of the license. We highly recommend implementing the SHOULD sections, and also adhering to the BEST PRACTICES wherever possible. Doing so will make you as consistent as possible with the way Office works.

The 120+ page guidelines document is confidential, so you'll need to visit the licensing site and agree to a short evaluation license before downloading it. But we created a little preview version of one of the sections to give you a flavor of what the guidelines are like.

The particular section we excerpted for the preview is Ribbon Resizing, which details the way in which the Ribbon must scale up and down to adjust to varying horizontal resolutions. The actual guidelines document contains similar information for the entire UI.

Download the 2007 Microsoft Office System UI Guidelines Preview (1.39 MB)

If your goal is to get as close to the Office UI as possible, you'll probably have no trouble complying with the guidelines. The guidelines are just there to help make that process easier and to give you a checklist for the parts of the UI you need to implement in order to comply with the license.

What's the catch?

For almost everyone, there's no catch at all. Just sign up for the license, and follow the guidelines. That's all there is to it.

You can use the UI in open source projects as long as the license terms are consistent with our license. You can use it on any platform: Windows, Mac, Linux, etc. If you're an ISV, you can build and sell a set of controls based on the new Office UI.

There's only one limitation: if you are building a program which directly competes with Word, Excel, PowerPoint, Outlook, or Access (the Microsoft applications with the new UI), you can't obtain the royalty-free license.

Why this exclusion?

Microsoft spent hundreds of millions of dollars on the research, design, and development of the new Office user interface.

We're allowing developers to license this intellectual property and take advantage of these advances in user interface design without any fee whatsoever.

But we want to preserve the innovation for Microsoft's productivity applications that are already using the new UI.

Summary

I am really excited to finally see this program launch. There's nothing our team wants more than to see the concepts and designs introduced in Office benefit others in the software industry. I believe in the new user interface, and I believe in its suitability to a large number of software applications.

I think the license strikes the right balance between allowing developers to use the new Office UI and protecting Microsoft's rights as the company who paid all of us to work on it.

For More Information

2007 Microsoft Office System User Interface Licensing web site
User Interface Guidelines Preview (A short excerpt of the actual guidelines)
Channel 9 video discussion with more about the UI and the UI license
Press release and Q & A about the licensing announcement
Frequently asked questions

Developer Resources for Office 2007 RTM

jensenh — Mon, 13 Nov 2006 18:00:00 GMT

Now that we've released Office 2007 to manufacturing, developers can get started modifying their solutions so that they're ready to test with the released version of Office.

Final versions of the RibbonX schema and Control ID list will be published on MSDN soon, but that can take a while—so I'll continue to publish developer resources here first so that you don't have to wait.

First, the entire set of Office 2007 Control ID lists. I'm putting these up in two different formats: .xls (97-2003 format) and .xlsx (2007 format.)

You only need one of these files; the contents of them are the same aside from the different format of the files.

Download Office 2007 RTM Control ID List (Excel 97-2003 Format)

Download Office 2007 RTM Control ID List (Excel 2007 Format)

The list of Control IDs hasn't changed too much from the Beta 2 Technical Refresh, but there are around 75 changes—any one of which could potentially break your solution. To help you see at-a-glance what changed since B2TR, we put together a list of just the changes.

Download List of Control ID List Changes between B2TR and RTM

The Control ID lists can be useful even if you aren't a developer. For example, we added a column for Group Policy ID in each of the lists; this ID number is the ID you need to disable Office commands via group policy.

Finally, it's worth mentioning again: a few weeks ago we released the RTM customUI schema for RibbonX. If you didn't catch it then, you might want to download it now:

Download Office 2007 RTM customUI Schema

Final Schema for RibbonX-based Solutions

jensenh — Thu, 26 Oct 2006 17:00:00 GMT

This morning, I posted the final customUI XML schema for creating Office 2007 RibbonX-based solutions.

You can use this schema to develop solutions that will work with the upcoming final release of Office 2007; it will also continue to work just fine with Beta 2 Technical Refresh. The changes from the previous version I posted are all minor (and in fact I updated the B2TR link in a previous post to point to the updated RTM schema as well.)

Download the RTM customUI Schema

This updated version will also find its way onto MSDN in the coming weeks, but I wanted you guys to have access to it first.

RibbonX Updates for B2TR

jensenh — Fri, 15 Sep 2006 17:00:00 GMT

Today's Guest Writer: Savraj Dhanjal

Savraj is a Program Manager on the Office User Experience team focused on user interface extensibility for Office developers.

As you may have discovered, we made a few tweaks to the UI developer story in Beta 2 Technical Refresh.

The biggest change is the updated Control ID list we published yesterday. We've updated the name of nearly every command in Office to be more logical, searchable, and easy to understand. If you are interested in finding out the ID numbers of commands for use with Group Policy, you can find them in these lists as well, in the Policy ID column.

We do not expect to change these IDs again for RTM, so (cross our fingers) this is the final list for Office 2007. We hope you find the new Excel-based lists easier to use and more flexible than the text files released with Beta 2.

Download Office 2007 B2TR Control ID List

If you have Beta 2 UI customizations which use a large number of built-in control IDs, manually updating each ID will take a while. So we wrote a command-line tool, UpdateIdMso, that takes a customUI xml file containing Beta 2 ID's and outputs a file with updated B2TR IDs. We hope this tool will make the upgrade process a bit easier for you.

Download UpdateIdMso Tool

We also have a new customUI schema for B2TR. The schema has only a couple of notable changes. We renamed the fileMenu tag to officeMenu and also changed advanced to dialogBoxLauncher. We made these changes to ensure that the developer model matches the final feature names in the product.

Download B2TR customUI Schema

Along with the control ID list, another reference we've created is the Office 2007 Icons Gallery. Open this file and you'll get a new group on the Developer tab in Excel, filled with galleries of the icons you can reuse in your Office 2007 solutions. Just click an icon, and you'll learn its control ID. Use this ID with the imageMso attribute to copy our icons to your controls.

Download Office 2007 Icons Gallery

Perhaps the most interesting functionality we added in B2TR is the ability to execute built-in controls by control ID, and the ability to query control properties by control ID.

For example, if you want to find out if the Save button is enabled, just call:

application.CommandBars.GetEnabledMso("FileSave")

and we'll return a boolean with the answer. And if you want to programmatically execute an obscure command that has no object model equivalent, just fire off:

application.CommandBars.ExecuteMso("MyObscureControlID")

The other functions are GetImageMso, GetLabelMso, GetPressedMso, GetScreentipMso, GetSupertipMso, and GetVisibleMso.

The VBA object browser lists the function parameters and return values, which will also be detailed on our MSDN site when it is updated in the coming weeks.

Thanks and let us know if you have questions. Happy solution-building!

Ribbon Extensibility: A VBA Sample

jensenh — Thu, 01 Jun 2006 17:00:00 GMT

Today's Guest Writer: Savraj Dhanjal

Savraj is a Program Manager on the Office User Experience team focused on user interface extensibility for Office developers.

Now that you've got Beta 2, you can download and open RxDemo.xlsm, a new file format document that uses RibbonX and works on Beta 2.

If you haven't changed your Macro security settings from the default, you'll receive a security alert. If you trust the document, click "Enable Content..." After carefully reading the ensuing dialog box, select "Enable this content." If everything worked, you can now click around on the custom controls. Notice the items added to the Office Menu, the custom "RibbonX" tab that can be made visible on from the add-ins tab, and the various controls that you should recognize from previous blog posts.

Take a look at the code behind the buttons in VBA, and if you want to look at the markup behind the document, I suggest you try out the Custom UI editing tool, a tool that lets you insert and edit images and the customUI part in new file format documents. There are some comments in the code as well as a number of explanatory super tooltips in this sample, so take a look and enjoy!

RibbonX Resources

jensenh — Thu, 25 May 2006 17:00:00 GMT

Today's Guest Writer: Savraj Dhanjal

Savraj is a Program Manager on the Office User Experience team focused on user interface extensibility for Office developers.

Yesterday Jensen linked to the Ribbon developer center. It's where we are bringing together all of our content on Ribbon Extensibility. I just wanted to highlight some of the key resources on the site.

Customizing the Ribbon For Developers, Part 1 takes you through the details of building a solution that customizes the Ribbon. If you're new to the whole idea, which you probably are, start here.

Customizing the Ribbon For Developers, Part 2 includes a complete reference for every valid tag and attribute in a valid custom UI file. It also includes a FAQ with answers to common questions. For example, it tells you how to turn on RibbonX-related error messages. (Application Options > Advanced > General > Show add-in user interface errors.)

The site also includes an overview document and a half-hour screencast that details ribbon customization via the extensibility model.

The Beta 2 Schema will also be on the site shortly. For those of you that can't wait for it, I've attached it here.

Finally, the one document I hope every solution author reads is the Style Guide for Solutions and Add-ins. It'll give you a basic idea of how to think about your add-in or solution in the context of the new user interface. The style guide is really about the cliché "with great power comes great responsibility," a quote that appears on blogs.msdn.com quite often.

Please take a look at the documents and let us know what you think. They'll get updated between now and RTM for sure. Are there any particular samples that you would like to see?

RibbonX Control Type Tour, Part 3

jensenh — Thu, 27 Apr 2006 17:00:00 GMT

Today's Guest Writer: Savraj Dhanjal

Savraj is a Program Manager on the Office User Experience team focused on user interface extensibility for Office developers.

This week, we'll take a look at the gallery control. It's one of the most important controls in the new Office 2007 user experience, and we've exposed a good chunk of core gallery functionality for you to use in your own Office-based solutions.

As you may have read in the many blog postings already written about galleries, the purpose of a gallery is to roll up features which would have taken many clicks into a gallery of choices that lets you get the same result in just one click.

In the example add-in I'm going to show, I've mocked up a gallery that allows you to insert pictures in one click, instead of opening a dialog, navigating the file tree, and selecting an image. I've dropped this gallery on the Insert tab in Word after the Illustrations group, because that's where it fits in best with the surrounding features.

The nature photos gallery, courtesy RibbonX
(Click to enlarge)

<gallery id="nature" 
    label="Nature Photos"
    size="large"
    imageMso="FlyoutAnchorMovie"
    onAction="nature_OnAction"
    getItemCount="nature_getItemCount"
    getItemImage="nature_getItemImage"
    getItemLabel="nature_getItemLabel"
    showItemLabel="false"/>

The anchor for a gallery is similar to that of a menu in that it can be small or large. In this case, I'm using a large, built-in film strip icon, with the imageMso attribute. As I've previously written, our controls use callbacks to specify dynamic properties like labels, and in some cases, the content of the control. The gallery control asks callbacks for the items that populate the gallery, unless the gallery contains statically declared items. In my example above, a callback returns 150x150 pixel PNG images converted to an IPictureDisp for each item.

One of the neat features of our gallery control is that it can automatically scale your images. The original PNG images used in my example are 150 pixels square. By specifying a new itemHeight and itemWidth the gallery will resize the images. I also changed the return value of my getItemCount callback to return sixteen items instead of nine. The gallery creates a 4x4 grid for a group of sixteen items.

Sixteen items and smaller images
(Click to enlarge)

<gallery id="nature"
    label="Nature Photos"
    size="large"
    imageMso="FlyoutAnchorMovie"
    onAction="nature_OnAction"
    getItemCount="nature_getItemCount"
    getItemImage="nature_getItemImage"
    getItemLabel="nature_getItemLabel"
    itemHeight="75"
    itemWidth="75"
    showItemLabel="false"/>

You can also scale up images, of course. In the next example, the gallery is enlarging the 150-pixel square images to 200-pixel square images. The gallery control can also resize images without preserving the aspect ratio of the original image, but because it doesn't look great I didn't include a screenshot. :)

You can also specify the number of rows and columns the gallery should display. In this case, I've got just one column and two rows.

Scaling up images, setting rows and columns
(Click to enlarge)

<gallery id="nature"
    label="Nature Photos" 
    size="large" imageMso="FlyoutAnchorMovie"
    onAction="nature_OnAction"
    getItemCount="nature_getItemCount"
    getItemImage="nature_getItemImage"
    getItemLabel="nature_getItemLabel"
    itemHeight="200"
    itemWidth="200"
    rows="2"
    columns="1"
    showItemLabel="false"/>

You can also choose to display labels on gallery items. The example below contains labels for each item, resizes the images to be much smaller, and is set to show ten rows.

Showing labels on gallery items
(Click to enlarge)

<gallery id="nature"
    label="Nature Photos"
    size="large"
    imageMso="FlyoutAnchorMovie"
    onAction="nature_OnAction"
    getItemCount="nature_getItemCount"
    getItemImage="nature_getItemImage"
    getItemLabel="nature_getItemLabel"
    itemHeight="20"
    itemWidth="20"
    rows="10"
    columns="1"
    showItemLabel="true"/>

Just like in many of the built-in galleries it Office 2007, you can also add buttons to the bottom of a gallery. Typically these buttons would configure what appears in the gallery or open a related settings dialog box.

Buttons at the bottom
(Click to enlarge)

<gallery id="nature"
    label="Nature Photos"
    size="large" 
    imageMso="FlyoutAnchorMovie"
    onAction="nature_OnAction"
    getItemCount="nature_getItemCount"
    getItemImage="nature_getItemImage"
    getItemLabel="nature_getItemLabel"
    rows="2"
    columns="2"
    showItemLabel="false">
    
    <button id="b222"
      imageMso="Save"
      label="Save selection to Nature Photos Server..."/>
    
    <button id="b229"
      imageMso="Dollar"
      label="Purchase more photos..."/>




</gallery>

That's the high-level overview of the functionality provided by the gallery control. We can't wait to see how you'll use it in the solutions you create!

Finding a New Purpose

jensenh — Thu, 20 Apr 2006 17:00:00 GMT

Today's Guest Writer: Savraj Dhanjal

Savraj is a Program Manager on the Office User Experience team focused on user interface extensibility for Office developers.

Today we're going to take a break from control types to highlight one of the more powerful features exposed by RibbonX: Command Repurposing.

In our research to understand how people were using extensibility in Office 2003, we found that developers at corporations often modified the built-in UI. Beyond adding a few buttons to the menus and toolbars, developers fundamentally changed the behavior of built-in buttons. If you're not familiar with Office development, you might ask, "Why in the world would someone do that?"

Imagine the international law firm of Faller, Mogilevsky, and Luu. FML doesn't want its employees printing Word documents or PowerPoint presentations unless they conform to the firm's strict standards for document formatting and style. To ensure standards are met, FML's software development team builds, as one of their many add-ins, a solution that overrides a click on the Print button. Clicking on Print now runs FML's code that checks the document for errors. If there are any errors, the user is notified. If not, the code sends the document to the printer.

You can imagine this same scenario applying to the Save button. FML wants to make sure all the metadata attached to a document is properly formatted before the user saves it. So FML takes over the Save button as well. When the user clicks Save, FML's code runs, updates metadata, and permits Office to continue with the built-in Save operation.

A few ways to do it today

There are a few ways to do this in Office 2003. The first way is through specially named macros in Word. Hit Alt-F11, select Insert > Module in the Visual Basic Editor, and paste the following macro into the code window.

Sub FileSave()
MsgBox ("Surprise! This works!")
End Sub

Test the macro by pressing F5 while your insertion point is inside the macro code. If you see the message box, it works. Now select Save from Word's File Menu. Surprise, it really does work. Every time you select "Save" Word will run your Macro and display a message box, instead of the built-in Save command. As yet another testament to Office as a platform, this behavior was introduced well before 1996, as part of WordBasic. The Word MVP's have a nice write-up on this behavior, and there are a number of other special macro names. Since this functionality pre-dated CommandBars, it only works in Word, and it hooks all instances of the Save button, including the one on the toolbar, as well as the control key shortcuts. So if you hit CTRL-S, the macro runs. The same goes for a click on the floppy disk icon in the Standard Toolbar. Isn't that neat? With three lines of VBA code (in Word) you can change the behavior of Save.

If you wanted to match this precise behavior using CommandBars, you would need to find each instance of the Save button and give it a new "onAction" macro, and the user might have customized the interface, so you'll have to find all instances of it. The following code snippet changes the onAction of the Save button on just the Standard Toolbar. After you run the Macro below, the Save button in the Toolbar and the Save button in the File Menu will do different things, and this method doesn't capture CTRL-S.

Sub newSaveAction()
Application.CommandBars("Standard").Controls("Save").OnAction = "surprise"
End Sub

Sub surprise()
MsgBox ("Surprise!")
End Sub

Run the first macro above, and then a click on the Save button will call the second one. This general idea works in all of the Applications with CommandBars.

But wait, there's more!

It shouldn't surprise you that there's one more way to do this. If I want to take over the Print button in Office 2003, I can listen for the button click event. Once the right control comes through this event, I can run some code and decide whether the built-in action should continue. The following code repurposes the Print button on Word's File Menu. Just copy and paste the code below into the Visual Basic Editor (Alt-F11), and run the first Macro.

Private WithEvents buttonEvent As CommandBarButton

Sub RunMe()
Set buttonEvent = Application.CommandBars(
  "Menu Bar").Controls("File").Controls("Print...")
End Sub

Private Sub buttonEvent_Click(ByVal Ctrl As
  CommandBarButton, CancelDefault As Boolean)
MsgBox ("File has errors.")
CancelDefault = True
End Sub

After you run the macro called RunMe a click on the Print button in the File Menu will yield a message box that says "File has errors." The code above sets cancelDefault to true to cancel the default action, in this case, printing. If you set CancelDefault to false the built-in action will continue after you close the message box. With the event-based method, you get an additional feature of continuing or stopping the built-in event, and this works in VBA and COM for all of the applications.

Enter RibbonX...

The sample code to repurpose the built-in Save and Print buttons, in RibbonX, looks like this:

CustomUI Markup

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"><commands> <command idMso="Save" onAction="mySave"/> <command idMso="Print" onAction="myPrint"/> </commands> </customUI>

C# Code

public void mySave(IRibbonControl control, ref bool
    CancelDefault)
{
    MessageBox.Show("Hello!");
    CancelDefault = true;
}

public void myPrint(IRibbonControl control, ref bool
    CancelDefault)
{
    MessageBox.Show("Hello!");
    CancelDefault = false;
}

As you can see from the markup, we've endeavored to make it as simple as possible. Just tell us the control IDs of the built-in controls you would like to repurpose in the <commands> section. A click on that command, wherever it appears in the user interface, will trigger the onAction callback you specify. Your onAction callback can then, just like the buttonClick_event, decide whether to continue with the built-in functionality.

We've also added a little more functionality -- control over state. You can specify if this control should always be disabled, or give us a callback to manage the enabled state.

CustomUI Markup

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">

<commands>
  <command idMso="Save" enabled="false"/>
  <command idMso="Print" getEnabled="myState"/>
</commands>

</customUI>

In the example above, the Save button is permanently disabled, and the Print button gets its state from the "AND" of its built-in state and the getEnabled callback "myState." When both Office says it's enabled, AND when your callback says it's enabled, the control is enabled. If either your code or Office says the Print button should be disabled, it's disabled.

In RibbonX, just give us one line of XML and you completely own what happens when the control is clicked. Best of all, in Word and PowerPoint, keyboard shortcuts are also captured, a marked improvement over Office 2003 events behavior.