Basic Ribbon Wrapper

Basic Ribbon Wrapper

Today we will start looking at some code, but before we begin you might want to know where to find it.

The most updated version of "Windows Ribbon for WinForms" code will be at Github

It will include the latest version of the project code and samples of how to use its different features.

Let’s get started.

Creating .NET wrappers The first thing needed for using Windows Ribbon from .NET is converting the C++ / COM definitions to C# ones.

The files relevant to Ribbon are: UIRibbon.idl, UIRibbonKeydef.h and UIRibbonPropertyHelpers.h. Note that UIRibbon.h is not interesting since it is auto-generated from UIRibbon.idl by the MIDL compiler. All these files are installed with Windows 7 SDK or a newer Windows SDK.

I won’t discuss the details of the conversion since it’s a very mechanical process, just change every C++ type and convert it to its corresponding .NET equivalent. If you are interested in these details, there are endless sources of information on .NET interoperability.

Following the Windows API Code Pack convention, the file UIRibbon.idl was converted to 4 different files:

• RibbonProperties.cs – containing Ribbon properties definition

• RibbonCOMGuids.cs – containing all Ribbon related GUIDs

• RibbonCOMInterfaces.cs – containing Ribbon interfaces definitions

• RibbonCOMClasses.cs – containing Ribbon classes definitions

These files are my conversions of the COM interfaces and types used by Windows Ribbon Framework. These files may change as the project continues since surely, I had some conversions error that will be discovered only when I’ll try to use a certain feature.

The most updated version will be the one on Github.

How does the Windows Ribbon Framework work? The full details are provided in MSDN, which I recommend reading. Here I’ll only give a short overview so we are all on the same page.

To initialize a ribbon in your application you need to do the following:

1. Design your ribbon appearance using XAML-like markup.

2. Compile your XAML-like markup using Microsoft Ribbon Markup Compile, provided with Windows 7 SDK.

3. Have the binary output of the markup compiler stored as a (unmanaged) resource of your application.

4. On application load, CoCreateInstance the UIRibbonFramework class which implements IUIFramework interface.

5. Call framework.Initialize and pass it a reference to your implementation of the IUIApplication interface along with the HWND of your application window.

6. The IUIApplication interface supply a callback for the ribbon framework to call when it needs a command handler, for handling commands (represented as buttons, combos and the other usual controls).

7. Call framework.LoadUI which loads the pre-compiled resource and shows the actual ribbon.

What have I done, up until now?

In order to facilitate the use of the ribbon within .NET applications we will create a class that will be used as a façade for the Windows Ribbon Framework. Ribbon class is able to support applications with one or more ribbons on different forms. This class, named Ribbon, will be in charge of initialization and communication with the Windows Ribbon Framework.

The Ribbon class will provide an implementation of IUIApplication and handle all the COM details. The Ribbon class is derived from the System.Windows.Forms.Control class and handle the steps 4 to 7 written before. The Ribbon must be placed to a Windows Form directly with Top docking.

The idea is to have your application provide only the minimal required details for the ribbon to work.

The Ribbon class currently exposes 2 methods:

• InitFramework – receives the resource name that will be used to load the ribbon configuration.

• DestroyFramework – cleanup code, free Windows Ribbon Framework resources.

These methods are called by the Ribbon class when the handle is created and destroyed, respectively.

Summary

This post turned out to be quite long, so I think I’ll just stop here for now. I’ve put the library code on Github along with a sample application that uses the code to create a simple WinForms application with Ribbon support.

On my next post I’ll provide simple details on how to build your first WinForms Ribbon application using what we’ve developed so far.