WPF Office Ribbon control

WPF Office Ribbon MSDN

A while ago Microsoft introduced the Ribbon control in various programs like Microsoft Word, Microsoft Excel, …
What if you are a WPF developer and you want to create a piece of software that uses such a Ribbon control? Where can I find it? How do I implement it? Is it free?
Many questions are still unanswered. I hope to answer some of the questions with this post, but a full detailed explanation can be found in the Resources section at the bottom of this post.

Where to find the WPF Office Ribbon control?

The Ribbon control is not a part of Visual Studio 2010 (speaking about beta 1 at this moment) nor .NET 4.0, even Expression Blend doesn’t give us that control. The Ribbon control can be found at the Office UI Licensing Developer Center . Click on ‘License the Office UI‘. In the next steps you will need to fill in a form to agree with the license. This is because you are using a Control from the Office team :).

Note: If you are creating a commercial application, don’t forget to mention the license, because you are using a Ribbon control with a signed license!

Now go ahead and download the WPF Ribbon control and the first step of getting the control is done for free!

ramones- hey ho let's go

Adding the WPF Ribbon control

  • with Visual Studio 2010 (similar to VS 2008)

Open Visual Studio 2010 and create a WPF Application called MyRibbonApp. The first thing that we need to do is adding a reference to our Ribbon control (the RibbonControlsLibrary.dll file that you have just downloaded).

Adding the Reference

  1. Right-mouse click on your project in the Solution Explorer.
  2. Select: Add Reference…
  3. Select tab page ‘Browse’ and browse until you find your RibbonControlsLibrary.dll that you downloaded.
  4. Click OK and the library should be listed under your References in the Solution Explorer.

Using it in XAML

This is the code that we now have:

<Window x:Class="MyRibbonApp.Window1"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 Title="Window1" Height="300" Width="300">
 <Grid>

 </Grid>
</Window>

Add the Reference to the namespaces so that we can access our Ribbon control.

<Window x:Class="MyRibbonApp.Window1"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 xmlns:r="clr-namespace:Microsoft.Windows.Controls.Ribbon;assembly=RibbonControlsLibrary"
 Title="Window1"
 Height="600"
 Width="800">

Now we are ready to actually implement the Ribbon. First we need to change the Window tag to RibbonWindow:

<r:RibbonWindow x:Class="MyRibbonApp.Window1"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 xmlns:r="clr-namespace:Microsoft.Windows.Controls.Ribbon;assembly=RibbonControlsLibrary"
 Title="Window1"
 Height="600"
 Width="800">
 <Grid>

</Grid>
</r:RibbonWindow>

If you try to run the application now you will have an error:

Partial declarations of ‘MyRibbonApp.Window1′ must not specify different base classes

Open your codebehind file (Window1.xaml.cs) and add a reference and change the Window.

...
using Microsoft.Windows.Controls.Ribbon;

namespace MyRibbonApp
{
/// <summary>
/// Interaction logic for Window1.xaml
/// </summary>
public partial class Window1 : RibbonWindow
{
public Window1()
{
...

See how we access the Ribbon control using the r: that we defined in the namespace. You can change that if you want to but I’ll work with ‘r‘ here.
The reason that we have to change the Window to RibbonWindow is very simple. If you see Word 2007 or any other application using the Ribbon, you will see that the ‘Quick access toolbar’ is implemented in the Windowborder itself.
A default Window tag doesn’t allow us to add things like the Quick access toolbar directly to the windowborder.

Ribbon in a normal Window tag

The Ribbon itself will be placed inside a DockPanel. So replace the Grid with a DockPanel, insert the Ribbon control inside the grid and always dock the ribbon to the top!

The code should now look like this:

<r:RibbonWindow  x:Class="MyRibbonApp.Window1"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 xmlns:r="clr-namespace:Microsoft.Windows.Controls.Ribbon;assembly=RibbonControlsLibrary"
 Title="Window1"
 Height="600"
 Width="800">
 <DockPanel>
 <r:Ribbon DockPanel.Dock="Top" Title="teusje.wordpress.com">
 </r:Ribbon>
 </DockPanel>
</r:RibbonWindow>

Run your program (F5) and watch… you have your Ribbon!
Don’t worry if you see a black background, this is because we are using RibbonWindow. Just set an Background=”White” on the RibbonWindow and it will be fixed ;) .

Adding Tabs

The XAML code is very easy to understand. We just add 2 RibbonTabs inside our Ribbon:

<DockPanel>
 <r:Ribbon DockPanel.Dock="Top" Title="teusje.wordpress.com">
  <r:RibbonTab Label="Home" />
  <r:RibbonTab Label="Help" />
 </r:Ribbon>
</DockPanel>

Run your application (F5) and play around with your tabs (hover them, scroll with your mouse, etc..)

Ribbon RibbonTab

Adding content to the Tabs

In this step we will try to fill our tabs with some controls. Buttons and other controls are bundled together in a group called RibbonGroup. They hold controls that are similar. A group Clipboard could add Cut, Copy, Paste inside it, because they belong to each other. We will add these controls in our group using RibbonButton.

I’ll leave it up to you to discover different kind of buttons, most of them can be found by reading the official links and guidelines in the  Resources section at the bottom of this post.

The code for the Ribbon should look like this now:

<r:Ribbon DockPanel.Dock="Top" Title="teusje.wordpress.com">
 <!-- Home tab -->
 <r:RibbonTab Label="Home">
 <r:RibbonGroup Name="Clipboard">
 <r:RibbonButton />
 <r:RibbonButton />
 <r:RibbonButton />
 </r:RibbonGroup>
 </r:RibbonTab>
 <!-- Help tab -->
 <r:RibbonTab Label="Help" />
 </r:Ribbon>

Run your application by pressing F5 and move your mouse over the buttons. You will see a button highlight. :)

Ribbon RibbonGroup RibbonButton

Adding Commands

Now we are going to add Commands. RibbonCommands are designed to store the information like LabelTitles, ToolTips, Events, Images for the button… in one place. They can be reused or be moved to another file to keep your XAML code clean.

Change your 3 RibbonButtons to this code:

<r:RibbonGroup Name="Clipboard">
 <r:RibbonButton>
  <r:RibbonButton.Command>
   <r:RibbonCommand LabelTitle="Copy"
    ToolTipDescription="Copy something" />
  </r:RibbonButton.Command>
 </r:RibbonButton>
 <r:RibbonButton>
  <r:RibbonButton.Command>
   <r:RibbonCommand LabelTitle="Cut"
    ToolTipDescription="Cut something" />
  </r:RibbonButton.Command>
 </r:RibbonButton>
 <r:RibbonButton>
  <r:RibbonButton.Command>
   <r:RibbonCommand LabelTitle="Paste"
    ToolTipDescription="Paste something" />
  </r:RibbonButton.Command>
 </r:RibbonButton>
 </r:RibbonGroup>

Run your application now (F5). You will see that your buttons now have a name. If you want to add images  for your buttons you need to set the LargeImageSource and SmallImageSource attribute in your RibbonCommand. LargeImageSource needs images with an 48×48 size and SmallImageSource needs 16×16.
Have you noticed if you hover your buttons that they don’t have their highlight anymore? Don’t worry about this, this is we didn’t add ‘CanExecute’ and ‘Executed’ in our Command. We’ll do that later :).

Now imagine that you have 6 Tabs with on each tab around 15 buttons, your XAML code will become a big mess with all these RibbonCommands inside your menus! Also when you have a button in another tab that needs the same functionality as a button from another tab you need to copy/paste the same command. Duplicated code is not good we want to use our code again!

Using a ResourceDictionary for Commands

First of all we need to create a ResourceDictionary to store our commands. Create it just above your DockPanel, under the RibbonWindow opening tag:

<r:RibbonWindow  x:Class="MyRibbonApp.Window1"
 xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
 xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
 xmlns:r="clr-namespace:Microsoft.Windows.Controls.Ribbon;assembly=RibbonControlsLibrary"
 Title="Window1"
 Height="600"
 Width="800"
 Background="White">

 <r:RibbonWindow.Resources>
  <ResourceDictionary>
   <r:RibbonCommand x:Key="CopyCommand"
    LabelTitle="Copy"
    ToolTipDescription="Copy something" />
   <r:RibbonCommand x:Key="CutCommand"
    LabelTitle="Cut"
    ToolTipDescription="Cut something" />
   <r:RibbonCommand x:Key="PasteCommand"
    LabelTitle="Paste"
    ToolTipDescription="Paste something" />
  </ResourceDictionary>
 </r:RibbonWindow.Resources>

 <DockPanel>

Now remove the commands from your buttons and replace them with Command attribute that has a  reference to your ResourceDictionary. I added also a Name attribute.

<r:RibbonGroup Name="Clipboard">
<r:RibbonButton Name="Copy"
Command="{StaticResource CopyCommand}" />
<r:RibbonButton Name="Cut"
Command="{StaticResource CutCommand}" />
<r:RibbonButton Name="Paste"
Command="{StaticResource PasteCommand}" />
 </r:RibbonGroup>

Now you see that our RibbonButtons don’t contain the design stuff anymore but only a command reference. Run your application, it should be the same as our previous version.

In your Window1.xaml.cs (the code behind file) add the following event handler:

private void OnIgnore(object sender, ExecutedRoutedEventArgs e)
 {
 // do nothing
 }

Now back to your Commands add the CanExecute parameter to each command and point it to OnIgnore:

<ResourceDictionary>
 <r:RibbonCommand x:Key="CopyCommand"
 LabelTitle="Copy"
 ToolTipDescription="Copy something"
 Executed="OnIgnore" />
 <r:RibbonCommand x:Key="CutCommand"
 LabelTitle="Cut"
 ToolTipDescription="Cut something"
 Executed="OnIgnore" />
 <r:RibbonCommand x:Key="PasteCommand"
   LabelTitle="Paste"
   ToolTipDescription="Paste something"
   Executed="OnIgnore" />
 </ResourceDictionary>

Run the application now (F5) and hover your buttons with your mouse. You see, they are fine now ;).

Ribbon RibbonButton mouse hover

Now go and add images to your buttons. (I will not do this you if you have time to do this, have fun :P ) As said before you should add in each Command a LargeImageSource and SmallImageSource. It can look like this:

<r:RibbonCommand x:Key="CopyCommand"
 LabelTitle="Copy"
 ToolTipDescription="Copy something"
 Executed="OnIgnore"
 LargeImageSource="Images/copyIcon48x48.png"
 SmallImageSource="Images/copyIcon16x16.png" />

You have seen that I used Executed in the Command. You can implement other events also like CanExecute. I point everything in this little tutorial  just to one event handler called OnIgnore, but normally you will have different events for each button.

Using GroupSizeDefinitions

Ever noticed when you open your Word 2007, when you resize Word that the RibbonButtons become bigger or smaller? Well this can be done with GroupSizeDefinitions.

Create this resource container inside your Ribbon tag, just like this:

...
<DockPanel>
 <r:Ribbon DockPanel.Dock="Top" Title="teusje.wordpress.com">
  <r:Ribbon.Resources>
   <r:RibbonGroupSizeDefinitionCollection x:Key="RibbonLayout">
    <r:RibbonGroupSizeDefinition>
     <!-- Control sizes: L,L,L -->
     <r:RibbonControlSizeDefinition ImageSize="Large" IsLabelVisible="True" />
     <r:RibbonControlSizeDefinition ImageSize="Large" IsLabelVisible="True" />
     <r:RibbonControlSizeDefinition ImageSize="Large" IsLabelVisible="True" />
    </r:RibbonGroupSizeDefinition>
    <r:RibbonGroupSizeDefinition>
     <!-- Control sizes: L,M,M -->
     <r:RibbonControlSizeDefinition ImageSize="Large" IsLabelVisible="True" />
     <r:RibbonControlSizeDefinition ImageSize="Small" IsLabelVisible="True" />
     <r:RibbonControlSizeDefinition ImageSize="Small" IsLabelVisible="True" />
    </r:RibbonGroupSizeDefinition>
    <r:RibbonGroupSizeDefinition>
     <!-- Control sizes: L,S,S -->
     <r:RibbonControlSizeDefinition ImageSize="Large" IsLabelVisible="True" />
     <r:RibbonControlSizeDefinition ImageSize="Small" IsLabelVisible="False" />
     <r:RibbonControlSizeDefinition ImageSize="Small" IsLabelVisible="False" />
    </r:RibbonGroupSizeDefinition>
    <!-- Collapsed -->
    <r:RibbonGroupSizeDefinition IsCollapsed="True" />
   </r:RibbonGroupSizeDefinitionCollection>
  </r:Ribbon.Resources>

 <!-- Home tab -->
...

Now add a GroupSizeDefinition to your groups. This GroupSizeDefinition called RibbonLayout is made for 3 buttons in a group. If you have groups with more buttons and you want to define how they should resize you can make another GroupSizeDefinition called OtherRibbonLayout for example.

<!-- Home tab -->
 <r:RibbonTab Label="Home">
 <r:RibbonGroup Name="Clipboard"
 GroupSizeDefinitions="{StaticResource RibbonLayout}">

This image from WindowsClient.net shows the effect/result (they used a definition for 4 buttons here):

Ribbon resize image from windowsclient.net

Implementing the RibbonQuickAccessToolBar (QAT)

Add this under your Ribbon.Resources tag:

<r:Ribbon.QuickAccessToolBar>
 <r:RibbonQuickAccessToolBar CanUserCustomize="True">
  <r:RibbonButton Command="{StaticResource CopyCommand}" r:RibbonQuickAccessToolBar.Placement="InCustomizeMenuAndToolBar" />
  <r:RibbonButton Command="{StaticResource CopyCommand}" r:RibbonQuickAccessToolBar.Placement="InCustomizeMenuAndToolBar" />
  <r:RibbonButton Command="{StaticResource CopyCommand}" r:RibbonQuickAccessToolBar.Placement="InCustomizeMenuAndToolBar" />
  <r:RibbonButton Command="{StaticResource PasteCommand}" r:RibbonQuickAccessToolBar.Placement="InToolBar" />
 </r:RibbonQuickAccessToolBar>
 </r:Ribbon.QuickAccessToolBar>

Your QAT will now look like this:

Ribbon QuickAccessToolbar QAT

If you hover your mouse over the left side of the Window you will see that your 4 little buttons will highlight.

Ribbon QAT buttons in toolbar

It’s just because I didn’t implement the LargeImageSource and SmallImageSource that you don’t see an Icon for the button. ;)

Also watch the details, in the dropdown you have 3 items and in the Toolbar above you have 4 buttons.We did this with:

r:RibbonQuickAccessToolBar.Placement="InCustomizeMenuAndToolBar"
and

r:RibbonQuickAccessToolBar.Placement="InToolBar"

Creating an ApplicationMenu

Add the ApplicationMenu between your ribbon resources and your QuickAccessToolbar like this:

...
</r:Ribbon.Resources>

 <r:Ribbon.ApplicationMenu>
 <r:RibbonApplicationMenu>
 <r:RibbonApplicationMenu.Command>
 <r:RibbonCommand
 Executed="OnIgnore"
 LabelTitle="Application Button"
 LabelDescription="Close the application."
 ToolTipTitle="MyRibbonApp"
 ToolTipDescription="Click here to use my menu."
 ToolTipFooterTitle="Help"
 ToolTipFooterDescription="Press F1 for more help." />
 </r:RibbonApplicationMenu.Command>
 <r:RibbonApplicationMenuItem Command="{StaticResource CopyCommand}" />
 <r:RibbonApplicationMenuItem Command="{StaticResource CopyCommand}" />
 <r:RibbonApplicationMenuItem Command="{StaticResource CutCommand}" />
 <r:RibbonApplicationMenuItem Command="{StaticResource CopyCommand}" />
 <r:RibbonApplicationMenuItem Command="{StaticResource CopyCommand}" />
 <r:RibbonSeparator />
 <r:RibbonApplicationMenuItem Command="{StaticResource PasteCommand}" />
 <r:RibbonApplicationMenu.Footer>
 <DockPanel LastChildFill="False">
 <r:RibbonButton DockPanel.Dock="Right"
 Margin="2"
 Command="{StaticResource CopyCommand}" />
 <r:RibbonButton DockPanel.Dock="Right"
 Margin="2"
 Command="{StaticResource PasteCommand}" />
 </DockPanel>
 </r:RibbonApplicationMenu.Footer>
 </r:RibbonApplicationMenu>
 </r:Ribbon.ApplicationMenu>

 <r:Ribbon.QuickAccessToolBar>
...

You see that we implemented a Command inside the ApplicationMenu itself. We did this because we will only need this command there, no other control will ever need it so sometimes not everything has to be in your resources.

If you hover your ApplicationMenu you will see a nice ToolTip:

Ribbon ApplicationMenu Tooltip

If you want to style the ApplicationMenuTooltip a bit more you can use ToolTipFooterImageSource, SmallImageSource, etc... just explore it yourself ;)

If you click your menu you will see something like this:

Ribbon ApplicationMenu

Adding Office 2007 Style

Add this code in your RibbonWindow Resources:

<r:RibbonWindow.Resources>
 <ResourceDictionary>
 <ResourceDictionary.MergedDictionaries>
 <ResourceDictionary Source="/RibbonControlsLibrary;component/Themes/Office2007Blue.xaml" />
 </ResourceDictionary.MergedDictionaries>

Your Ribbon will now have the Office 2007 Blue styles:

Ribbon Office2007 Blue Style

Office 2007 Blue style:

 <ResourceDictionary Source="/RibbonControlsLibrary;component/Themes/Office2007Blue.xaml" />

Office 2007 Black style:

 <ResourceDictionary Source="/RibbonControlsLibrary;component/Themes/Office2007Black.xaml" />

Office 2007 Silver style:

 <ResourceDictionary Source="/RibbonControlsLibrary;component/Themes/Office2007Silver.xaml" />

You

Well now YOU have to create a Command for every button or thing that you want in your Ribbon control. You can add icons/images for the buttons with LargeImageSource and SmallImageSource inside your Command.

Check out the Resource links, they have more information on how to build your Ribbon control and they explain several buttons.

Resources

Source Code download:

MyRibbonApp

MyRibbonApp (Hope this one works)

RENAME .doc TO .zip !!! (wordpress doesn't allow me to upload .zip files).


I hope you liked this little Ribbon tutorial. :)