Welcome to MSDN Blogs Sign in | Join | Help

News

Using RibbonX with C++ and ATL

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:

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

  5. Click to view full picture

  6. 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:

  1. 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)
  2. 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.

Windows, Office, and Exchange Business Launch

Today is the official business launch of Windows Vista, the 2007 Office system, and Exchange Server 2007.

This means that as of today, businesses can get these products and start deploying them within their organization.

The consumer launch is scheduled for January 30—that's when you'll be able to go into retail stores and buy shrink-wrapped copies of Office and Windows.

You can read all about the business launch, see videos, and participate in the forums here: http://msnewday.com/

Steve Ballmer sent out mail to everyone at Microsoft commemorating today's business launch. Here's in part what he wrote:

"Eleven years ago, Microsoft launched Windows 95 and Office 95 and introduced an era of unprecedented opportunity, transforming the way people do business, share information, and communicate. Today, in New York I announced the business availability of Windows Vista, the 2007 Office System, and Exchange Server 2007. This announcement marks the beginning of the most significant launch in company history, with more than 1 billion people expected to use these products in the next decade.

"The launch of Windows Vista, the 2007 Office System, and Exchange Server 2007 is an important milestone in our company's history. The result of incredibly hard work, phenomenal perseverance, and remarkable innovation, they are the most advanced work that Microsoft has ever done. For the last three decades, Microsoft has delivered technologies that embody our belief in the power of software to change the world. Windows Vista, the 2007 Office system, and Exchange Server 2007 continue this great tradition and I want to congratulate everyone who worked on these products—thank you for your dedication and commitment to making today possible."

You can also read the external version of the mail that was posted on Microsoft.com.

Want to experience Office 2007 for yourself? Today might be a great day to try taking the new Office for a test drive.

Or, if you want to download a fully-functional trial version, those will be posted online tomorrow, December 1.

RibbonX Image FAQ

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:

  1. IPictureDisp objects
  2. System.Drawing.Bitmap objects
  3. 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:

  1. 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).

  2. 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.

  3. 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

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

Developer Resources for Office 2007 RTM

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

The Office 2007 UI Bible

I've published over 200 posts on this blog since I started it last September.

With all of those posts, it can be hard to remember what you've read and what you haven't… and it can be hard for new people to jump in and figure out where to start reading.

I've been meaning to sit down and create a kind of table of contents for all of the posts here—a starting point for people to read about the Office 2007 UI.

But then, I found out that someone already did the work for me. Patrick Schmid, a OneNote MVP and friend of the Office 2007 UI, put together what he called the Office UI Bible on his blog—a fully organized catalog of many of my posts.

And so with Patrick's kind permission I reprint here the catalog of Office 2007 UI posts (so far.)

I hope you find it useful—and thanks, Patrick!

Why a New UI for Office 2007?

Overview of the New UI

Ribbon UI Elements

The Size of the Ribbon, Screen Real-Estate, Ribbon Scaling, and Minimization

Migrating to Office 2007

UI Themes and Visuals

Keyboard Control of the Ribbon

New Fonts for Office 2007

Customizing Office 2007 (Add-ins, RibbonX)

Note that most examples shown in the following posts need to be updated for use with the RTM version.

From First Sketches to the Final Design

Design Tenets

Design Ponderings

An Inside Look Into UI Design, Usability, Development and Testing at Microsoft

Office Themes

New Features in Office 2007 Involving the New UI

Miscellaneous

The Office 2007 UI team

Office 2007 Released to Manufacturing

I'm proud to announce that last Friday, November 3 at approximately 2:30 PM, we signed off on build 4518.1014 as the 2007 Microsoft Office system and released it to manufacturing.

This was followed by a ship party for everyone in Office including a few minutes of speeches, the traditional sounding of the RTM siren, and plenty of champagne (much of which I ended up wearing.) The rain even stopped for a few hours!

You can read the official press release here

This release has been such a great pleasure to work on. It was more than three years ago when Julie walked into my office (I barely knew her at the time) and asked if I wanted to come over to the user experience team to help figure out if there was something better than menus and toolbars. I had no idea what an adventure I was about to embark on!

Three years later and we've shipped a product that I'm so proud of.

In the near future, we'll be sharing more of the research we've been doing on Beta 2 and B2TR deployments around the world. Just last week, we got back the most recent round of data from ~4000 people in long-term enterprise deployments of Beta 2 in the United States, Europe, and Asia. The results are positive beyond what I would have dared to dream.

To those of you who have been active in the beta program and here on the blog, and to everyone who sent feedback on the betas, thank you. Your feedback truly made the product better than it ever could have been without you.

To the app teams and partner teams around Office and at Microsoft who helped make this release possible, thank you. This couldn't have happened without your ideas and support.

And to those of you on the UEX team, whose ingenuity, consummate engineering, missed weekends, and tireless attention to detail made it all possible—thank you! We did it!

How to get it?

Office 2007 products will be available at retail early in 2007, so you'll be able to get your hands on them soon. Business customers will be able to get Office 2007 through the volume licensing program before the end of the year.

If you're running the Beta 2 Technical Refresh, the good news is that you can keep using that build for quite some time: the client build expires on March 31, 2007, and the server products expire on May 15, 2007.

What's Next?

Between now and retail availability, I'm going to do a series of posts documenting the creation of the Office 2007 user interface from the earliest prototypes all the way to the final product.

Final Schema for RibbonX-based Solutions

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.

Where Have I Gone?

I know in my last post I said that I'd be gone for a few days… and now those few days have stretched into a few weeks.

One of the reasons I've been off the blog for a while is that we've been extremely busy putting the final touches on Office 2007. Now is the time when every bug needs to be tracked down and squashed with utmost priority. And with Windows Vista also in the home stretch, there's a lot going on around here.

I've also been fortunate to spend much of the last month traveling around the world and here within the United States, talking to customers and the press about Office 2007. Last week I was in Singapore talking to folks from all around Asia; it was fun to show an almost-finished Office 2007 to a group of people to whom the new UI was totally unknown. I always seem to learn something from people who are seeing the new interface for the first time; it's why we put so much of an emphasis throughout the design process in soliciting fresh perspectives.

Now I'm finally back in Seattle for a while, so I will be writing regularly again.

For you developers out there, later in the week I'll post the final Office 2007 schema for Ribbon development which you can use to author solutions which will work with the RTM version. Happily, very little modification will be required to move solutions forward which you author against B2TR.

Taking a Few Days Off

You may have noticed that I haven't posted for the last week.

I wish I could say that I've been on a fabulous vacation, but in reality, I spent two weeks on the road, talking to people about the Office 2007 UI.

That trip, combined with an extremely busy time trying to help finish up Office and getting it ready to ship, means that I've had less time to write as of late. So, I decided to take a little break after the flurry of posts around the release of Beta 2 Technical Refresh.

I'll be back posting regularly in a few days.

In the meantime, if you're looking for some reading material, check out the new Word team blog. They've posted six articles over the last two weeks; hopefully they'll keep up that pace and write much more about one of Office's most-used programs.

Many of you have also written to me asking where you can get support for Office 2007 Beta 2 TR. The best place to ask a question or get help with a problem is in the Office Discussion Groups on microsoft.com. There's a group for just about every program and area in Office, so give it a try if you're having a problem.

Probably the most common problem I've seen reported is a known issue in B2TR: a dialog box on the launch of Word stating that "Building Blocks.dotx" is corrupt, followed by many of the Word galleries being empty.

Fortunately, it's easy to fix this. Close Word, navigate to the "%appdata%\Microsoft\Document Building Blocks" folder and delete "Building Blocks.dotx." You can find the solution to this and many other common problems on Patrick Schmid's blog.

RibbonX Updates for B2TR

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!

Beta 2 Technical Refresh Available Now

This morning, the Beta 2 Technical Refresh of the 2007 Microsoft Office system became available for download.

You can download it now from the Microsoft Download Center.

(The download link above is the main download link. You also view the list of all available Beta 2 Technical Refresh updates for client and server by clicking the Beta 2 Technical Refresh link on this page.)

You must have Beta 2 installed in order to patch it to Beta 2 Technical Refresh, so don't uninstall Beta 2.

Why a patch instead of a full release? Primarily because we need to test the patching technology broadly, and this is a great chance to make sure it works well. Patching is the way we release updates to Office after it ships, so making sure it works well is an important part of the beta process.

Please also consider downloading the Send a Smile Feedback Tool to tell us what you think about Office 2007. If you already had it installed from Beta 2, you can continue to use it in B2TR.

In my post yesterday, I posted a list of the most substantive changes to the user interface in the new build. Consider this by no means a full list of changes in B2TR—just those in the UI.

I've also posted a list of Ribbon Control IDs for use with B2TR for RibbonX developers. These should also show up on MSDN sometime in the next few weeks. It's a 1.3 MB download (.zip file) if you need to grab it now.

Note: If you're having trouble installing the patch, try following the instructions in this article.

Note 2: Patrick Schmid is keeping a great log of solutions to issues people are encountering with B2TR.

Beta 2 Technical Refresh Available Tomorrow

This morning, we announced that starting tomorrow (Thursday, Septemeber 14) you'll be able to download the Beta 2 Technical Refresh build of Office 2007 (build 4407.1005).

Note: There's a newer post now with the download link. You can keep reading, though, to see a list of what's new in the Technical Refresh user interface.

I'm travelling on the east coast this week (New York, Boston, D.C.) and I've been using this build extensively and can honestly say that it's been very stable for me. I'm used to running bleeding-edge builds at work, so it takes a trip like this to really notice how far along the quality is in this build vs. where it was in Beta 2 and earlier betas (or a random daily build.)

If you're running Windows Vista RC1, you'll be happy to know that B2TR works great on RC1 (unlike the much earlier Office Beta 2, which has some problems on Vista RC1.)

B2TR represents an iterative step forward for the UI design—a refinement and polishing of each component. The UI is now totally feature complete, and you will see only cosmetic differences between B2TR and the final version in most areas.

As I wrote in June, there are a number of changes in B2TR, ranging from minor tweaks to relatively significant improvements. In particular, we've made nearly 1000 individual improvements to the content in the Ribbon—everything from redesigning the Home tab of PowerPoint to subtle changes to scaling or labels to work better on small monitors. Most of these changes are, of course, very minor, but they add up to a new level of fit and finish in the overall user experience.

Some of the more significant improvements to the user interface in Beta 2 Technical Refresh:

I hope you'll give the new build a try and tell us what you think. A full list of new features and improvements to the entire product (not just the user interface) will be available along with the download tomorrow.

Thanks so much for your feedback which made these changes possible.

The Quick Customize Menu

One of the new features in the upcoming Office 2007 Beta 2 Technical Refresh that I haven't written about yet is something we call the Quick Customize Menu.

As you may know, the Quick Access Toolbar is a customizable part of the UI in which you can add features for quick access. Simply right-click any control in the Ribbon, or any group of controls, and choose "Add to Quick Access Toolbar" to add it to the QAT. There's also a customize dialog box where you can add many commands at once.

So, it's pretty easy to add things to the Quick Access Toolbar. But we wanted to go a step further, and make it even easier for people to add a few features we believe will be among the most-frequently added.

We created a list of around ten features per-program, using the Customer Experience Improvement Program data from Beta 1, B1TR, and Beta 2 to help inform this decision.

Next to the QAT is a little arrow. In the long-term deployments of Beta 1 we did last year, one of the behaviors we noticed was that people first clicked on the arrow to try customize in many cases. Unfortunately, what you saw when you clicked this arrow was a rather fallow menu containing only two commands: open the customize dialog box, or move the QAT below the Ribbon.

So in Beta 2 Technical Refresh, we built a Quick Customize menu on to the arrow which lets you quickly add a core set of features to the QAT. (You can, of course, still right-click anything in the Ribbon or Office Menu to add it to the QAT as well.)

What's on the menu? Well, a lot of good stuff. For instance, the "New" icon which directly opens a new blank document. And the beloved but dangerous "Quick Print", which immediately sends your entire document to the default printer.

One you might be surprised about in Word is "Draw Table"—but only if you consider English alone. "Draw Table" is extensively used in East Asian languages, where tables are frequently used to structure and control the text flow of a document. This is one of those cases where the usage data for a particular feature is vastly dependent on the locale you're in and the input language you're using.

Each program has a slightly different menu; the Excel menu, for instance, contains Sort Ascending and Sort Descending. On the PowerPoint menu, you'll find "Start Slide Show."

The Quick Customize Menu is not a revolution—but it's a nice affordance to improve the discoverability of customization for beginner/intermediate users who are most likely to want to add just a few simple commands to their Quick Access Toolbar.

(Want to read more about customization? There's a whole article here.)

Things of Beauty

One of our goals for the Office 2007 user interface was to make it easier to create beautiful output.

In many circumstances, you are judged by the quality of the output you create. And software that helps you create beautiful output makes you look smart and feel good.

Many of the features of the new UI, including the Ribbon, galleries, and Live Preview, were designed together to create an environment in which you can discover and easily use the power of Office's formatting capabilities. Add to this the new Office 2007 graphics engine, and suddenly in a few clicks, you can create beautiful-looking output without learning to be a Photoshop expert.

Every kind of object in Office 2007 (table, chart, picture, drawing, etc.) has an overall gallery on its first contextual tab which allows you to set the overall style for the object.


Every object has a gallery of overall styles available

Although you can continue tweaking and formatting to get highly customized results, the default choices are designed to be beautiful right out-of-the-box; with one click you can achieve graphics designer-quality results.

From time to time I've shown some of these styles on my blog—a chart or two, a SmartArt diagram, or a table, for instance. We've been working on the contents of these galleries quite a bit since Beta 2, and in the upcoming Beta 2 Technical Refresh you will notice improved styles in many areas.

The one place we probably spent the most time was in updating the Picture Styles gallery. Pictures are among the most frequently inserted objects into an Office document or e-mail message, and so we wanted to have a set of pictures styles which were really beautiful and broadly useful. The placeholder content in Beta 2 was fine, but we didn't think they were as good as they could be.

So, over the course of a few months, people across a number of teams (including my team, the OfficeArt team, the Office Design Group, and other interested parties) worked together to create a new set of breathtaking picture styles for Office.

You'll see the full set of twenty-eight styles debut in the Beta 2 Technical Refresh. They showcase much of what you can do with the new graphics engine—inner shadows, outer shadows, reflections, 3D rotation, soft edges, bevels, and much more—to create a set of beautiful general-purpose styles. In the ease-of-use category: each of them can be applied with a single click and previewed just by hovering over them.

To give you a taste of what to expect, here are nine of the styles applied to some of the default pictures shipped in Windows Vista RC1:


Nine of the twenty-eight picture styles that will debut in Beta 2 TR.
(Click to enlarge - 1.4 MB)

Note: In your own documents, I don't recommend putting nine different styles directly next to one other. :)

The new picture styles can be used whenever you insert or select a picture in Word, Outlook, PowerPoint, and Excel.

By the way, the best place to learn about the graphics and themes capabilities of Office 2007 is the PowerPoint and OfficeArt blog.

More Posts Next page »