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.

RibbonX Control Type Tour, Part 2

jensenh — Thu, 13 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.

Hey everyone! Another week, another batch of RibbonX controls and attributes. You can use last week's markup wrapper to create valid XML from code snippets below.

CheckBox

The checkBox is one of the many new control types exposed in the Ribbon. It's got the same behavior as a toggleButton, but it has a completely different visual style. Checkboxes are useful for settings and options that don't change content in your document. ToggleButtons, like the built-in Bold button, are better for cases where you want the state of your selection reflected. Office 2007's most prominent built-in checkBoxes are on the View Tab.

Three checkBoxes. The mouse hovers over the second checkBox.

<group id="myGroup" label="Settings">
  <checkBox id="c1" label="Office Seat Heater" onAction="heater"/>
  <checkBox id="c2" label="Mouse Traction Control" onAction="traction"/>
  <checkBox id="c3" label="Keyboard Sport Mode" onAction="sport"/>
</group>

Unlike most other controls, a checkBox, when promoted to the QAT, keeps its label by default. Just right click a custom checkBox, select add to QAT, and voila, it's available so you can always get to it.

Custom checkBox on the QAT.

Separator

A separator is just that--a logical division between controls in your group. Separators have no label--just a unique ID. By themselves, they're not very interesting, but they can politely part controls that are too close for comfort within a group.

Separation in action.

<group id="myGroup" label="Settings">
  <checkBox id="c1" label="Office Seat Heater" onAction="heater"/>
  <checkBox id="c2" label="Mouse Traction Control" onAction="traction"/>
  <checkBox id="c3" label="Keyboard Sport Mode" onAction="sport"/>
  <separator id="s1"/>
  <button id="b1" imageMso="ExcelChartGallery1" size="large" label="Air/Fuel Mixture" />
</group>

LabelControl

The labelControl lets you put a text label in your group. The label provides a little extra information to make sure the user's on the right track, and often eliminates text duplication among the controls below it. Labels, like checkBoxes, are seen in very few places in the Office 2007 Ribbon.

Labels. Use sparingly.

<group id="myGroup" label="Settings">
  <labelControl id="lc1" label="HCI PowerToys" />
  <checkBox id="c2" label="Mouse Traction Control" onAction="traction"/>
  <checkBox id="c3" label="Keyboard Sport Mode" onAction="sport"/>
  <separator id="s1"/>
  <labelControl id="lc2" label="Ambiance" />
  <checkBox id="c4" label="Background Music" onAction="enableMusic"/>
  <checkBox id="c5" label="Mood Lighting" onAction="enableLights"/>
</group>

Tips & Launchers

To provide more information about a particular control on hover, you can use the tooltip (soon to be renamed screentip) and supertip attributes on controls. The tooltip works as you would expect, and the supertip is a multi-line text string.

Using the tooltip and supertip properties to explain traction control on mouse hover.

<group id="myGroup" label="Settings" >
  <labelControl id="lc1" label="HCI PowerToys" />
  <checkBox id="c2" label="Mouse Traction Control" onAction="traction" tooltip="Office 2007 Traction PowerToy" supertip="Enable enhanced mouse traction on snow, ice, and loose paper."/>
  <checkBox id="c3" label="Keyboard Sport Mode" onAction="sport"/>
  <separator id="s1"/>
  <labelControl id="lc2" label="Ambiance" />
  <checkBox id="c4" label="Background Music" onAction="enableMusic"/>
  <checkBox id="c5" label="Mood Lighting" onAction="enableLights"/>
  <advanced>
    <button id="b5" label="Settings Dialog" tooltip="Open settings dialog." supertip="All the power you expect from Office." onAction="dialog"/>
  </advanced>
</group>

The group shown above also has a "dialog launcher," in the bottom-right corner. This launcher opens a the full settings dialog. You declare the launcher by putting a button in the advanced section of a group.

As a final note, you'll notice my COM Add-In's name, "RibbonX Demo," is in the footer of the super tooltip. This way, end-users can directly associate additional functionality with the add-in that provided it, giving credit where credit is due. Pressing F1 for help will take end-users to help on Office add-ins. Unfortunately, end-users would probably uninstall my add-in, because Mouse Traction Control isn't implemented. I hear we're working on it for Office 14. :)

RibbonX Control Type Tour, Part 1

jensenh — Thu, 06 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 look at the different types of buttons you can create with RibbonX. The Ribbon is a two-dimensional UI space, and as you can see from our built-in groups, there's a fair amount of variety in controls and control arrangement. The extensibility model exposes much of the richness and flexibility available in the different Ribbon control types, and buttons are no exception. I've included some code snippets that you can paste inside the following wrapper, to get valid customUI markup.

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">
  <ribbon>
    <tabs>
      <tab idMso="TabAddins">
        <!-- insert snippet here -->
      </tab>
    </tabs>
  </ribbon>
</customUI>

"It's just Buttons"

Ribbon extensibility, at its core, is about how developers can make a custom button show up in the Ribbon. Profound, isn't it? :) Anyway, A button can be small or large, and it can show or hide its label. It can also have a tooltip or a super tooltip. Like all custom controls in RibbonX that have images, you can copy the image for this button from a built-in control, using the imageMso property.

Four custom buttons. Each button snags its image from a built-in control.

<group id="myGroup" label="My Group"> <button id="b1" imageMso="WebInsertHyperlink" size="large" label="Surf the Net" onAction="surf"/> <button id="b2" imageMso="HappyFace" label="Smile" onAction="smile"/> <button id="b3" imageMso="FormatPainter" label="Paint" onAction="paint"/> <button id="b4" imageMso="AutoFilter" label="Filter" onAction="filter"/> </group>

You can also hide the labels on built-in buttons, so you get small 16x16 icons that appear quite like the icons on toolbars in non-Ribbon applications. Large buttons images are 32x32 pixels.

Hiding labels with the showLabel property.

<group id="myGroup" label="My Group">

  <button id="b1" imageMso="WebInsertHyperlink"
    size="large" label="Surf the Net" onAction="surf"/>

  <button id="b2" imageMso="HappyFace"
    showLabel="false" label="Smile" onAction="smile"/>

  <button id="b3" imageMso="FormatPainter"
    showLabel="false" label="Paint" onAction="paint"/> 

  <button id="b4" imageMso="AutoFilter"
    showLabel="false" label="Filter" onAction="filter"/>

</group>

ToggleButtons

The canonical example of a toggleButton is the Bold button. You can create your own toggleButtons, and you can make them behave just like the bold button by writing callbacks. By tweaking the XML from the first example, we get a pair of toggleButtons.

ToggleButtons stay down when you click them.

<group id="myGroup" label="My Group">

  <toggleButton id="b1" imageMso="WebInsertHyperlink"
    size="large" label="Surf the Net" onAction="surf"/>

  <button id="b2" imageMso="HappyFace"
    showLabel="false" label="Smile" onAction="smile"/>

  <toggleButton id="b3" imageMso="FormatPainter"
    showLabel="false" label="Paint" onAction="paint"/> 

  <button id="b4" imageMso="AutoFilter"
    showLabel="false" label="Filter" onAction="filter"/>

</group>

SplitButtons

SplitButtons combine the wonders of a one-click button with a set of choices in a menu. Here's a splitButton that I've placed in the Ribbon, using our existing button images.

Left: Hovering the button-half of a splitButton.
Right: Dropping the menu-half of a splitButton.

<group id="myGroup" label="My Group"> <splitButton id="mySplit" size="large"> <button id="b1" imageMso="WebInsertHyperlink" label="Surf the Net" onAction="surf"/> <menu id="splitMenu" itemSize="large"> <button id="b2" imageMso="HappyFace" label="Smile" onAction="smile" description="View pages about smiles."/> <button id="b3" imageMso="FormatPainter" label="Paint" onAction="paint" description="Learn to paint your house."/> <button id="b4" imageMso="AutoFilter" label="Filter" onAction="filter" description="Read about water purification."/> </menu> </splitButton> </group>

There are a few interesting things going on in the image above. First, you might notice that the menu items are large, and each item is displaying its description. You get this visual when you set your menu's itemSize to large -- we call this a "rich menu." You'll also notice that the HappyFace icon is a bit blurry. Wondering why? We didn't create, for Office 2007, a 32x32 version of this icon, because none of the applications use it. Office is scaling up the built-in 16x16 icon. (We could probably write a separate blog entry about the origins of the built-in HappyFace icon.) By the same token, if your add-in only has a large icon, and it needs to display the icon on a small button, Office will scale it down.

Button Arrangement

So you can have big and small buttons, and you can set properties like visibility, enabled state, and the label dynamically. What else can you do? Well you've probably noticed the fancy runs of buttons on some of the tabs in the Ribbon applications. You can create your own buttonGroups in RibbonX as well. Just wrap your buttons in this tag, and you get that neat visual style, a throwback to the days of toolbars. For the example below I also grabbed a couple built-in Office controls, using idMso, and these buttons work as you would expect.

Matching the toolbar-esque visual style. The last six buttons are in buttonGroups.

<group id="myGroup" label="My Group"> <button id="r1" label="Vanilla Button" imageMso="Cut" /> <buttonGroup id="myBGroup"> <button id="b1" imageMso="WebInsertHyperlink" label="Surf the Net" onAction="surf"/> <button id="b2" imageMso="HappyFace" label="Smile" onAction="smile" /> </buttonGroup> <buttonGroup id="myBGroup2"> <button id="b3" imageMso="FormatPainter" label="Paint" showLabel="false" onAction="paint" /> <toggleButton idMso="Bold"/> <button id="b4" imageMso="AutoFilter" label="Filter" showLabel="false" onAction="filter" /> <toggleButton idMso="Italic"/> </buttonGroup> </group>

Custom Button Images

If you're an icon buff, you'll be excited to know that RibbonX now supports icon images with 32-bits -- 8 bits for red, green, and blue, and 8 bits for an alpha (transparency) channel. The "M" below is a 24-bit PNG with transparency. The soft edge of the shadow is preserved, thanks to the alpha channel. When you hover over the buttons, or when you click on them, you get all of the visual effects of the Ribbon for free.

Custom button with alpha channel.

<group id="myGroup" label="My Group">
  <button id="M" size="large" label="The M Button" 
    getImage="getM"/>
</group>

In the sample above, my C# callback, getM, grabs the PNG file, converts it to an IPictureDisp, and returns it to Office. In CommandBars, transparency was governed by the mask property -- which allowed to you "mask off" pixels in your button's picture property. Before picture and mask, we had copyFace and pasteFace, which are currently deprecated, because calls to these functions overwrite the user's clipboard.

So that's a quick preview of a few things you can do with buttons in the Ribbon. Stay posted for more exciting control types.

Hollywood Meets Office Add-ins

jensenh — Thu, 30 Mar 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.

One of the key design features of RibbonX is the "pull" model, a model where Office asks add-in controls for their state. Though different than the "push" model of CommandBars, the pull model enables a number of scenarios for add-ins such as end-user customization, a separation between UI and core solution code, and better performance.

The model is straightforward--Office asks you for information about your controls--it "pulls" this information from your solution. Typically, Office asks for control properties that you did not declare up front in your customUI markup. Let's say you've got a button that should only be enabled when a certain condition is present. You write a function that returns true when your button is enabled. In your customUI markup, you associate this function with your button.

When Office first loads your button, and the button is on screen, Office calls back to your code to see if the button should be enabled. Office doesn't ask again, unless you indicate that your state has changed, by calling IRibbonUI.Invalidate, which invalidates all of your custom controls, or IRibbonUI.InvalidateControl, which invalidates a particular control. The function that Office calls is called a callback.

The interaction between Office and your add-in is best summarized in the following excerpt from a screenplay:

Add-in:   Hi Excel! Here's some customUI markup.
           ...
	  <button id="ButtonOne" label="Hello World!" 
	    getEnabled=”enabledState” onAction="sayHello"
            imageMso="HappyFace" />
	   ...
	
Excel :   Great, I've applied it to the Ribbon. By the way, 
          it looks like you have set a callback for the enabled 
          state of ButtonOne. I'll call back to your function, 
          enabledState, the first time your button is on screen.

Time passes, user clicks on custom tab

Excel :   The user clicked on your tab, your button is appearing.
          Calling enabledState, is ButtonOne enabled?

Add-in:   Yes.

Excel :   Ok great, I won't ask you again until your state changes.

*Time passes, user does something

Add-in:   My state changed.  I'm calling Invalidate.

Excel :   Ok, calling enabledState, is ButtonOne enabled?

Add-in:   Yes.

Excel :   I won't ask you again until state changes.

Go to *, until user closes the app.

Ok, so that wasn't too exciting. But it's an illustration of how pull works. Add-ins can return just about all of the properties you can declare in markup, like the images, labels, descriptions, screentips, visibility, and enabled state of controls, through callbacks. For dynamic controls, like galleries and comboboxes, callbacks return the items that populate these controls.

The pull model affords several benefits for developers. The first is free end-user customization. If an end-user wants to promote a custom gallery to the quick access toolbar, she can. This behavior is completely transparent to the solution developer. Since code is never tied to the location of a control, callbacks for the state, label, or other properties still work even if the control is on the QAT. If your control was copied elsewhere in the world of CommandBars, you would have to write code to update the state of your control in both locations.

If you've ever developed a complex solution with a large amount of UI, you probably understand the benefit of keeping core application code and the UI separate -- the benefit is that the UI remains easy to change. Because of the "location agnostic" nature of the pull model, RibbonX developers get this benefit as well. You (or a UI designer) can rearrange your UI without ever touching your core application code.

We're also making add-ins more performant (in our own small way) with the pull model. In CommandBars, you could waste time updating controls that were not available or visible to the user. With RibbonX, if you tell us your state has changed, we only ask you for the new state of your controls if it is applicable -- that is, if your controls are visible to the user. If your controls are not on the screen (perhaps they're on a different tab) there's not reason to keep these hidden controls up to date.

As a final note, the RibbonX implementation of the pull model brings add-ins much closer to how the applications have always worked internally. It should be no surprise that the Office apps follow this very same design pattern: If something changes, the on-screen controls get updated. When the state changes in an add-in, or in the application, Office updates its UI to reflect the new state.

I'm sure some of you are wondering about the Hollywood-quality screenplay I'm writing regarding Office add-ins. Does anyone have any connections to get it submitted? A tentative title could be "Don't call us, we'll call you."

Good Service for Add-ins

jensenh — Thu, 23 Mar 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.

For Office 2007, we built the UI extensibility model around a simple idea: If your add-in or solution is installed, its UI customizations are present. If it's uninstalled, its customizations are no longer present. I would venture to guess that this is how anyone would expect UI extensibility to work.

In Office 2003, you had to take a few extra steps to make sure your add-in behaved in this reasonable manner. As a first line of defense, you created controls as temporary, ensuring that they would not be persisted beyond the current session. If you changed anything built-in, you needed to write code to clean up your changes on uninstall. A tricky task, because you didn't know what other add-ins, or the user, had done to customize the UI. You could set various protection bits to shield yourself from modification by users, and you could call ".reset" on built-in toolbars to get them back to a default state. But you might have just reset another add-ins customizations on a built-in toolbar. And how does the end user get that add-in back? Perhaps by reinstalling the add-in?

In many ways, the CommandBars OM is a free-for-all. Any add-in can show up, change the UI (whether built-in or from another add-in), and then disappear. In Office 2003, these changes are persisted in Word and Excel in the Normal template and the Excel11.xlb file. As many of you know, the quickest way to reset your UI in these applications is to delete Normal.dot or Excel11.xlb. And for those of you that didn't know that, there's a chance that you're harboring UI customizations in those files from add-ins you uninstalled long ago.

We wanted to move to a model where solutions didn't have to worry about what other add-ins were doing--a model that didn't leave the user with a bunch of "dead" buttons cluttering the UI. And if we could pull it off, it would be nice if this played well with end-user customization. Sure, it was possible to author a well-behaved add-in with CommandBars, but it often involved a number of special steps, among them setting protection bits, and in the case of Word, using the CustomizationContext variable.

So we decided to move most persistence away from the application, and instead associate it with the add-ins and solutions. With RibbonX, add-ins provide Office with markup to customize the Ribbon, as you saw in last week's post. Since a solution's UI customizations are defined in XML, we can keep track of who's done what. For example, if we have three add-ins, each supplying markup to change the user interface, and add-in #2 gets uninstalled, we can remove its UI changes, because we know exactly what each add-in did. We do this in a manner transparent to developers--we've squarely taken on the burden of UI "housekeeping."

With the UI as markup attached to solutions, we've also enabled a number of scenarios that were complicated or required extra code in Office 2003 to work properly. One of our favorite examples is document switching in Excel. In Excel 2003, you can attach a toolbar to a document. If you have two such documents open, with focus on one of them, you see both toolbars. As you switch between documents in Word 2003, however, the attached toolbars appear and disappear appropriately. If you wanted to get the same behavior in Excel, you would need to write code to show and hide the toolbars. In fact, if you ever want the attached toolbars to go away, even after the Excel workbook is closed, you need to write code--in Excel 2007, it just works as you would expect.

With Book 1 selected, there are no customizations present.

When you select Book 2, the customizations magically appear, in this case, a custom tab, and a new group on the Sheet tab.

RibbonX works with both COM and VBA solutions, and we have endeavored to make the model as similar as possible between the two. You can create both application-level and document-level solutions with this model. If you want to create an application-level solution--that is, UI customizations that are visible for all open documents, you can create a COM Add-In, a VBA Excel Add-in (.xlam), a VBA PowerPoint Add-in (.ppam) or a Word Global Template (.dotm). Document level solutions can be authored as individual documents: .docx, .xlsx, .pptx--or the matching macro-enabled formats.

COM Add-Ins

COM Add-ins come in many flavors, including C#, C++, VB6, and VB.Net. On load of a COM Add-in, Office asks for your customUI markup via a method on the new IRibbonExtensibility interface, and this markup gets applied to the Ribbon.

VBA Solutions

If you have built a VBA-based solution, be it a document, an add-in, or global template, Office looks for the customUI part in your new file format document. Once found, the customUI gets applied to the Ribbon.

Support for the Quick Access Toolbar

For all RibbonX add-ins, the user is free to add controls to the Quick Access Toolbar by right-clicking on them. When the solution or document is gone, the control no longer appears on the Quick Access Toolbar. Of course, you don't need to write a single line of extra code to make this work--we've written those lines here at Microsoft. :)

Hello World group on the QAT

Demand Loading

Ribbon Extensibility is also designed to support "demand loading" of COM Add-Ins. So if you set your COM Add-In as demand-loaded, on first boot, we get (and cache) your XML, and on subsequent boots, your add-in isn't loaded until someone clicks on one of your controls. This allows you to minimize your solution's impact on application boot. Of course, we clear the cache if your add-in is ever uninstalled, again, all transparent to you.

Last month I had the pleasure of traveling to the UK for some visits with customers and partners. While gathering feedback and understanding customer scenarios, I had a chance to ride on the London Underground, a marvel of engineering, efficiency, and design. When in the Tube, I would often hear announcements like, "There is a good service on the Jubilee Line," which meant that the Jubilee Line trains were on time, as one would expect. Well I'm proud to say that Office 2007 will also offer "good service" with regard to add-in UI customizations--that is, they will come and go as you expect.

Hello World, For Real

jensenh — Thu, 16 Mar 2006 17:00:00 GMT

Today I present guest writer Savraj Dhanjal, Program Manager on the Office User Experience Team. He is one of the members of our team focused on user interface extensibility for Office developers.

Articles on the Office 2007 user interface developer story will be published every Thursday for the next few weeks.

Today's Guest Writer: Savraj Dhanjal

I'm Savraj Dhanjal, and I'm a program manager on the Office User Experience team. At the start of the Office 2007 product cycle, I worked on the technical framework that underlies the new user interface, and then I started working on UI extensibility--making sure existing solutions still work and can be updated to work well with the Ribbon.

You've probably asked yourself: "when am I going to learn about how to create my own ribbon tabs, groups, and controls, so I can harness the power of the New UI in my Office 2007 add-ins and solutions?"

You've read about all of the cool aspects of the new user interface from this blog, so as a developer, you want to know how you can update your solutions to work with the new UI. If you're not a developer, well, you may still find the discussion interesting.

Enter the new UI extensibility model, code-named RibbonX. Optimized for common developer scenarios, we built RibbonX from the ground up, just like the new user interface itself.

As with all of the components of the new UI, the extensibility story was subject to the same "first-principles" scrutiny that every other feature received. Did we even need a developer story for Office 2007? Was it really used in the past? Would custom Task Panes be the solution which obviated the need for a UI extensibility story?

Many of these questions came up because the last time UI extensibility was actively worked on was early in 1996, when the shared UI team rolled out the CommandBars object model. CommandBars attempted to unify the various UI extensibility models of the applications. After its release, we made a few tweaks, but as far as we were concerned, it was done, and most of the original people that worked on it moved on.

In researching the question of whether the UI extensibility story was a necessary component of Office 2007, we began to realize how silly the question was in the first place. It became quite apparent that, in the ten years since CommandBars, hundreds of thousands, if not millions of solutions were built on Office, and almost all of them changed the UI in some way. Even though the first Office Developer Conference was in 2005, the notion of Office as a platform had been around almost as long as Office itself.

So it was obvious that we needed a developer story. Again, like all of our other features, we wanted to know what didn't make sense with the existing model, so the new model would be free of these issues. Furthermore, we wanted to understand what developers were trying to accomplish, so that we could optimize for common scenarios. We turned to our customers, partners, and MVPs to understand the problems with, and uses of, UI extensibility today.

We viewed the entire spectrum of Office extensibility, from the small freeware add-in that sprinkled a few buttons in the menus, to the whole hog remake of Excel that created a fully customized application. We uncovered issues with solution localization, control repurposing, end-user customization, consistency between the Office applications, and “housekeeping”--making sure buttons only appear when your solution is loaded, and disappear when unloaded. We found that it was hard to create a well-behaved add-in, and the right way to do it differed between the applications.

We also found developers isolating menu and toolbar changes from the core of a solution. Developers created solutions where the UI is represented in a text or proprietary XML, so the UI can be updated without the overhead of rebuilding and redeploying an add-in. At first we thought it amazing, until we remembered that keeping UI separate from code is a good development practice. In fact, the Ribbon internally is built on markup--Office developers can change the layout of the Ribbon without going near core application code.

Taking all of this in, the extensibility feature crew was tasked with building an extensibility story while UI itself was still being designed. We knew that our model should focus on consistency across all applications, close integration into the new UI, optimization for common scenarios, and allow for well-behaved add-ins by default.

The feature crew set to work and exposed an XML schema that allows developers to create their own tabs, groups, and almost a dozen different control types, far more than the set of five custom controls offered by CommandBars. Since add-ins give us markup that contains customizations, it's easy for us to fix all of the housekeeping issues: when the add-in disappears, the UI disappears with it, and then markup is also easier to localize, understand, and manage.

Here's the XML required for the special group shown above.

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"> <ribbon> <tabs> <tab idMso="TabEnterData"> <group id="myGroup" label="My Code" insertBeforeMso="GroupEditingTools"> <button id="myButton" label="Hello World!" onAction="Hi" size="large" imageMso="WebInsertHyperlink" /> </group> </tab> </tabs> </ribbon> </customUI>

In many ways, the model continues to evolve and improve, and we on the extensibility crew are still hard at work building the extensibility model, so stay tuned for more posts on how you can harness the power of the new UI.