Microsoft's OfficeUI Ribbon: Adding non-button controls

There are quite a few controls included with the new Microsoft OfficeUI Ribbon library. I recently wanted to incorporate this into a prototype application I was working on. All the examples I found showed how to use it with a button but I wanted a richer UI than just buttons on the ribbon. I did some web searching and found precious little information on using other controls and I did not find any documentation. Using the little information I did find, a lot of reverse engineering and some trial and error, I finally came up with something that works. Therefore, in an effort to help someone else, here are some things I discovered.

First, I wanted a simple mini-form for doing text searches. All it needed was an edit box, a go button and a couple check boxes in a ribbon group. Here is a screen shot of what I wanted:


In my first attempt, I knew I needed a group to put the controls in, so I naively added one to my ribbon and added the desired controls. The designer immediately became unstable. I was able to compile after stopping and restarting the IDE. However, when running the application, I got a null reference exception loading the form.

Through some routine diagnostic sleuthing, I determined the cause: having multiple groups without assigning GroupSizeDefinitions. If there is only one group, it will work properly without defining a GroupSizeDefinition. However, with more than one group, each group must have a GroupSizeDefinition assigned. I hope that Microsoft will fix this bug before the final release.

In spite of fixing the null reference problem, the layout did not work as desired. Things did not size appropriately. Controls did not position the way I wanted. It was a UI mess.

I had gone to a session at PDC2008 where they demonstrated the control so I went to find that presentation. A bit of information was gleaned from slide 36 [pptx] of session PC45 where the ItemsPanel property was discussed. Unfortunately it was entirely too brief and ended up somewhat misleading. It did give me a clue to start looking for other things though.

After a bit of searching, reading blog articles and forum posts, I found the key to figuring this out in a short post by Mike Cook. I found it best to add an ItemsPanel to the RibbonGroup containing a UniformGrid. The controls then went in this container.

In order to get the controls formatted the way I wanted, I needed to put each row in a DockPanel. However, the only things that can go in a RibbonGroup are things that implement IRibbonControl. To handle this, I created two of my own controls that extend DockPanel and implement IRibbonControl. This ended up working well because I needed to add additional code to each one to work the way I wanted and this helped encapsulate this code.

In formatting the top line, the first thing I found was the RibbonButton, used for the Go function, always assumes there is an image associated with it. For the purposes of this form, I wanted the image to the left of the label, associated with the entire line, not over on the right associated with the button. In order to turn this off, I had to find the image in the button's template and set its Visibility to Collapsed.

After getting the button's image removed, the next thing I found was the RibbonTextBox sizes the text box to its content. This seemed ugly to me and I did not find any way of altering this behavior with simple property settings so I started investigating the VisualTree for the control. After some trial and error, I found I could set the Width of a Border inside the RibbonTextBox and the internal TextBox would remain that size. This strikes me as a pretty ugly and fragile hack, but it works. I hope that this will improve before the final release.

The second row is more straightforward with just two RibbonCheckBoxes on it. It does have a slight oddity though. The Executed property must have a method assigned to it for the check box to be active. The issue is, in this particular use case, I did not need to have anything happen when the user checks the box so there is a required method that has nothing in it. This seems silly to me.

At the end of the day, I was able to get what I wanted out of the library. I think it looks nice for the user and functions well. But, it is not terribly pretty for the programmer and there was quite a bit of frustration getting it to work as I intended, mostly due to poor and lacking documentation. I hope someone else finds this useful. If there are any errors or omissions, please leave a comment to let me know and I will do my best to correct it.

Source code

The ribbon control is publicly available on the OfficeUI web site after agreeing to a long, overwhelming license. (Here are the how-to-get instructions.) As I understand it, this is going to be bundled into the base System.Windows name space with CLR 4.0, so I'm not quite sure why there's such an onerous license on it at this point.

Here is complete source code [zip] for this article. Note that it does contain a reference to RibbonControlsLibrary, the package containing the Ribbon controls, which is not included due to licensing restrictions. In order for this to compile, you need to get this library from Microsoft (see links above) and then update this project to point to your copy of it.

Microsoft's OfficeUI Ribbon: Application template

I've been working with the recently released Ribbon control from Microsoft's Office UI group. There are several cookie-cutter setup steps to get an application ribbon aware. In order to facilitate setting up a new application, I made a Visual Studio 2008 template that creates a blank application containing a ribbon bar with some empty controls.

Here is the template file. Copy this zip file to My Documents\Visual Studio 2008\Templates\ProjectTemplates\Visual C#. When Visual Studio is started, the New project dialog displayed when File | New | Project... will have a new Ribbon Application option under My Templates. Select this to create a skeleton ribbon application.

When the application is created, an error will be displayed indicating the ribbon control library cannot be found. This is because this library needs to be acquired directly from Microsoft. To get it you need to go to the OfficeUI web site. (Here are the how-to-get instructions.)

Once the library is downloaded and installed on your computer, go to the new ribbon application's References, remove RibbonControlsLibrary and then add it in again, pointing to the location on your computer.

The skeleton application contains a Close option on the application menu to stop the application. There is a single tab with a single group containing a single button. Finally, there is a single button on the quick access toolbar. These all can be used as templates to easily add more.

More information on creating Visual Studio templates can be found on the MSDN site. (Thanks to paranoid ferret for the pointers on to how to create templates.)