Supporting the Ribbon and Menus

(I’ve posted a version of this article on Code Project.)

I’ve finally come back to Ripsaw, in a round-about way. I’ve started working on the client application again as a way to investigate the Windows Ribbon Framework. Originally, I had planned to create a Ribbon implementation for Windows 7 and later, and a menu-based implementation for earlier Windows versions, or for users that preferred a menu over the Ribbon.

Scratch Ribbon Project

After I played around with the API a while, I realized it would be fairly simple to support both the Ribbon and the traditional menu in one executable. In this article I’ll describe a sample app that I put together that shows how to accomplish support for both command-selection methods.

(Download the source code)
(Download the executable)
(Download the Visual C++ 2010 Redistributable)

A Few Words about the Ribbon

The Ribbon was first introduced with Microsoft Office 2007 as a way to tame the huge menu and toolbar hierarchy that had evolved to present all of the suite’s features to its users. It then made its way into Windows 7 in the Paint and Wordpad applets, and can now be found in several third-party applications.

As with most things Microsoft does, it seems that users either love or hate the Ribbon. I happen to love it, since I’ve always disliked toolbars and I find menus clumsy, at best. Since everyone doesn’t share this opinion, and it’s relatively cheap to include a menu, and since I want to support XP, Vista, and Windows 7 with a single executable, I’ll try to satisfy as many people as I can by allowing users to select the command presentation method they prefer.

The Project

The application we’ll be working with began its life as an adaptation of a scratch program that Raymond Chen uses as a framework for example programs in his articles. I adapted it to my own very thin C++ wrapper and added some things that I like to have in fully featured applications, then set about making it work with the Ribbon. You may download the Visual C++ 2010 Express project and follow along below.

License

There is no license. This code is public-domain code, and may be used in any manner without restrictions. I offer no guarantees or warranties at all.

Prerequisites

First of all, you’ll need Visual C++ 2010 Express (which is free) or one of its more sophisticated versions (which are not free) in order to compile the project. If you prefer to use a different compiler you’ll have to adapt the code and project as necessary. You’ll also need the Windows 7 SDK version 7.1. Finally, in order to see the Ribbon interface you’ll need to run the application on Windows 7 or on Windows Vista SP2 or later with the Platform Update installed. When the application runs on Vista SP1 or earlier it will only display the traditional menu.

Configuring Visual Studio Projects for Ribbon Support

Supporting the Ribbon in Visual Studio takes a little setup. First of all, once the SDK is installed, you need to change a setting in any new project in Visual Studio 2010 to take advantage of the SDK:

Choosing the Windows 7.1 SDK Platform Toolset in Visual Studio 2010

Next, you’ll need to add a new XML file to your project to contain your Ribbon markup. The Ribbon is defined by an XML markup schema described in detail on MSDN. This XML is compiled by a tool provided in the Windows 7.1 SDK, UICC. After you’ve added the XML file to your project, open the Property Pages for the file and change the “Item Type” property in the General properties to “Custom Build Tool.” Apply the setting, then in the Custom Build Tool>General settings change the command line to something like the following:

Next, define the outputs from the UICC compiler in the “Outputs” property:

Make sure that you apply these changes for both the Debug and Release builds.

Changing the compiler settings for Ribbon markup in Visual Studio

Finally, you’ll need to add the output of the UICC compiler to the project’s main resource script. These need to go in a particular location in the resource file. In Visual Studio 2010 Professional, switch to the resource view (Ctrl+Shift+E), right-click on the resource script, and select “Resource Includes” from the context menu. Add the header file produced by UICC (for example, Ribbon.h) at the top in the “Read-only symbol directives” window, and add the resource script produced by UICC (for example, Ribbon.rc2) to the Compile-time directives window, as shown below:

Visual Studio 2010 Professional resource includes window

In Visual C++ 2010 Express, you’ll need to edit the resource script code directly since there is no resource editor. Right-click on the resource script in the Solution Explorer and select “View Code” from the context menu. Find the TEXTINCLUDE sections and edit them as highlighted below:

With these changes in place, the resource script will include the control IDs created by the UICC compiler so that you may reuse them in your menu resource.

Running the Application

As I mentioned earlier, this project began as a scratch application. The idea was to have a starting point for new applications that would provide a lot of the boring, boilerplate stuff so that I could concentrate on the interesting bits of new applications. Figuring out how to integrate the Ribbon and make it work was not entirely straightforward, which I found disappointing. The answers to my questions were usually somewhere out on the Internet, but never in one place. That’s why I decided to write this article to help those of you who might be having the same struggles I had.

After you’ve downloaded the Visual C++ 2010 Express project, open it in Express, build it, and run it. Or, if you prefer, just download the executable and run it. On Windows 7, and on Windows Vista SP2 or later with the Platform Update installed, you’ll see a window with a Ribbon control across the top. In the View tab of the Ribbon is a button that will allow the user to switch to a traditional menu bar. The View menu has a corresponding option to allow the user to display the Ribbon again. Most of the other commands will simply output a line of text in the client area describing the option that was selected.

Scratch Ribbon Project Menu on Windows 7

On Windows XP, and on Windows Vista without the Platform Update, you’ll instead see a window with a traditional menu. The “Show Ribbon” menu option is disabled because the application detects that the Ribbon API is not supported on those platforms.

Scratch Ribbon Project on Windows XP

Examining the Code

I won’t go into too much detail about the usual Windows API elements of the code, or about the minimalist C++ framework it uses. I also won’t get into the details of the Ribbon markup, which is covered in detail in the MSDN Ribbon documentation. Instead, I’ll cover the bits of the code related to supporting the Ribbon and the menu.

The application’s initialization is performed in the App::Initialize method. The first order of business is initializing COM:

The comment about goto is a subject of another article entirely, so we’ll ignore that for now. It’s necessary to initialize COM because the Ribbon API is a set of COM objects that implement the various Ribbon interfaces (IUIFramework, IUIRibbon, etc.). A little further down in the initialization method the code reads the saved user settings, if they exist, then checks to see if the application should be using the Ribbon. The setting will be true by default, no matter what OS the application is running on, so the application will call the CreateRibbon method.

The CreateRibbon method uses the Ribbon API’s COM objects to initialize and show the Ribbon.

If the COM objects are created and their methods are called successfully, the API will remove the main window’s menu and display a Ribbon in its place. This method will fail on platforms that do not implement the Ribbon API, and since the application displays a menu on its main window by default, that menu will remain in place.

Next, the initial states of the various command options are set.

The ID_SHOW_RIBBON constant represents the menu selection that enables the Ribbon when the UI is displaying the menu bar. This function uses the return value of the IsRibbonSupported method to enable or disable the menu item. That method is implemented as follows:

All the method does is attempt to create a COM object provided by the Ribbon API. If the attempt fails, the method returns false. This will always fail on XP and on Vista without the Platform Update, unless of course some enterprising developer implements all the necessary COM interfaces and objects on those platforms.

Implementing the COM Interfaces

The Ribbon API requires an application using the Ribbon to implement two COM interfaces: IUIApplication and IUICommandHandler. The IUIApplication interface defines callbacks into the application that are called by the Ribbon API. The IUICommandHandler interface is called for each command that is exposed on the Ribbon.

The Scratch Ribbon Project implements both interfaces in the App object. This need not be the case, but it makes the shared implementation with the menu bar a little easier to accomplish. An alternative implementation would be to create a unique IUICommandHandler implementation for each command.

First of all, in the App class declaration in ScratchRibbonProject.h, the relevant methods are declared. The definitions are in ScratchRibbonProject.cpp, and we will examine each of them in turn.

First, we need to implement IUnknown since all COM interfaces derive from this interface. The AddRef and Release methods are fairly straightforward.

Next is QueryInterface, which should return a pointer to the requested interface if the object implements it.

With that chore out of the way, we can move on to the interesting interfaces. The IUIApplication interface specifies three methods: OnViewChanged, OnCreateUICommand, and OnDestroyUICommand. The OnViewChanged method is called by the Ribbon framework when the state of a Ribbon View changes. The verb parameter specifies the action performed by the view.

The method is called with the UI_VIEWVERB_CREATE and UI_VIEWVERB_DESTROY verb constants at Ribbon initialization and tear-down, respectively. This implementation uses those calls to load the ribbon settings when the Ribbon view is created and save them when it is destroyed. We’ll look at the LoadRibbonSettings and SaveRibbonSettings methods a little later on.

The UI_VIEWVERB_SIZE indicates that the Ribbon’s size has changed (for example, the ribbon has been minimized). The application may need to respond to this notification to adjust any other windows that need to be moved or resized based on the new Ribbon size. In this example, the method adjusts the client area by calling the OnSize message handler.

The OnCreateUICommand method is called by the Ribbon framework for each command specified in the Ribbon markup. The application must return a pointer to an IUICommandHandler interface that will handle each particular command. In this application, all of the commands are serviced by the App object instance, so we just return the requested pointer and increment the reference count.

The OnDestroyUICommand method is called each time a command is destroyed. This would give the application an opportunity to clean up its command handlers, if necessary, but in our case there’s nothing to do.

Finally, we need to implement the two methods of the IUICommandHandler interface, which will be shared by all of the Ribbon commands in our application. The UpdateProperty method is called by the framework to request an update to a command’s state. As an example of how to modify the enabled/disabled state, this application changes the state of the Save and Redo commands based on flags maintained by the App object.

At last, we come to the method that connects activation of the Ribbon commands to actual application code. The Execute is called with an execution verb constant of UI_EXECUTIONVERB_EXECUTE when the application needs to respond to a command event. This application posts a WM_COMMAND message equivalent to what would have been sent if the command had been selected from a menu. This, in turn, triggers the WM_COMMAND handler in the WndProc method.

The Ribbon XML

The Ribbon.xml file contains the markup that defines the application’s Ribbon. This file is compiled by UICC and included in the resource script. Each command has an Id attribute that specifies a numeric value sent to the application when the command is activated. This value is associated with the Symbol attribute in the Ribbon.h file generated by UICC. Following are the definitions for the “New” and “Open” commands:

When this XML is compiled, the following constants will be defined in Ribbon.h:

Most of these constants are used by various string and image resources, but the constants that will be used in the menu are ID_CMD_NEW and ID_CMD_OPEN.

The Menu Resource

Earlier, we modified ScratchRibbonProject.rc to include Ribbon.h so that the constants defined in that header by the Ribbon compiler could also used by the menu resource.

The menu items defined in the menu resource now share the same numeric identifiers defined in Ribbon.xml. Activating any of these items, either on the Ribbon or the menu, will trigger the same handlers in the OnCommand message handler.

Swapping the Ribbon and the Menu

When the application is run for the first time on a platform that supports the Ribbon, the application displays the Ribbon by default. Activating the Show Ribbon command on the View tab will cause the Ribbon to be removed from the window, and the menu bar will be shown in its place. The identifier for that command is ID_HIDE_RIBBON, and when it is activated the following code is executed in the OnCommand method:

This puts the AM_SHOW_MENU message (an application-defined message) into the message queue, and that is handled by the following code in App::WndProc:

This code sets a flag (killRibbon) to activate special message handling in order to work around some painting problems (which we’ll examine later). It then calls the CloseRibbon method.

This method releases the pRibbon object, if set, calls the Destroy method of the pFramework object, releases the pFramework object, and sets the pointers to null. Finally, it updates the settings object to note that the ribbon is not being used.

The last thing that the AM_SHOW_MENU handler does is post an AM_RESTORE_MENU message, which is handled as follows:

This restores the menu bar to the window with SetMenu and enables or disables the menu items as necessary.

Going the other direction, if the user selects the Show Ribbon option from the View menu, the ID_SHOW_RIBBON case in OnCommand is triggered.

This, in turn, activates a case in WndProc.

I ran into a number of painting problems in this code, and I eventually decided to just hide the window, restore the Ribbon, then show the window again. This is a little bit jarring, but until I can find a workaround for the painting problems it’s effective enough. (If you find a better workaround, please let me know.) I felt particularly dirty about posting a WM_SIZE message, but that was the only reliable way I could find to adjust the client area properly. When I saw that the same technique was used in WTL 8.0, I didn’t feel so bad anymore.

Saving and Restoring Ribbon Settings

Above, we saw that the OnViewChanged method calls LoadRibbonSettings when the Ribbon is initialized and SaveRibbonSettings when the ribbon is destroyed. The SaveRibbonSettings method creates an IStream object on a file in the user’s application data directory and passes that stream to the pRibbon->SaveSettingsToStream method. The Ribbon framework will write its settings into this stream, after which the SaveRibbonSettings method releases the IStream and IStorage objects.

At Ribbon initialization the LoadRibbonSettings opens the Ribbon stream in the file created by SaveRibbonSettings and passes it to pRibbon->LoadSettingsFromStream. This will restore the previously saved state of the Ribbon.

Enabling and Disabling Ribbon Commands

To demonstrate how to disable Ribbon commands, the Save and Redo commands will change state based on the other commands chosen by the user. The Save command is disabled until the New or Undo commands are activated, and the Redo command is disabled until the Undo command is activated.

The state of the Save command is controlled by a dirty flag set in the App object. If the current “document” is flagged as dirty, and therefore a candidate for a save operation, the Save command should be enabled. To set or clear the dirty flag the application calls the SetDirty method of the App object.

This method modifies both the menu and Ribbon commands. It first checks to see if the pFramework pointer is non-null. If it is, it points to an instance of the IUIFramework interface implemented by the Ribbon API. It uses the pointer to call the InvalidateUICommand method, specifying that the ID_CMD_SAVE command should be invalidated. This instructs the framework to call the application’s implementation of IUICommandHandler::UpdateProperty, which will set the state of the command based on the dirty flag.

Various Clean-up Tasks

All that we have left to cover are the various clean-up actions to restore the client area and handle some painting problems. First of all, there is a read-only edit control in the main window’s client area to display the descriptions of the selected Ribbon or menu commands. This control needs to be resized to fit around the Ribbon control when the main window is resized or the Ribbon size changes. This is accomplished by handling the WM_SIZE message.

The AdjustClientArea function accepts the client width and height and adjusts the edit window to find around the Ribbon.

AdjustClientArea calls pRibbon->GetHeight in order to get the height of the Ribbon, and then adjusts the size of the edit window accordingly.

The OnSize method also checks to see if the killRibbon flag is set. This flag is set when the user hides the ribbon and restores the menu. If the flag is set, OnSize calls SetWindowPos to trigger a WM_NCCALCSIZE message.

There are also handlers for WM_SIZING and WM_ACTIVATE that check the killRibbon flag and call SetWindowPos if it is set. If it is not, they defer handling to DefWindowProc.

The WM_NCCALCSIZE handler does some additional work to draw the frame correctly.

When the Ribbon is restored, the killRibbon flag is cleared and normal processing occurs for these messages.

Final Thoughts, Future Changes

I only have a couple of annoyances with this code. First of all, I have to check the validity of each command message in OnCommand since the keyboard accelerators are not synchronized with the corresponding Ribbon commands as they would be with the menu. This is a minor complaint, though. The more annoying issue is that the ribbon graphics increase the size of the executable. For the users that prefer to use the menu this is a waste of memory, but I could get around that problem by keeping the Ribbon resources in a separate DLL. I haven’t tried implementing that yet, but I’ll post an update where when I do.

I’ve covered a lot of ground here, so please leave a comment if anything is still unclear.

Note: This project uses the Must Have Icons by VisualPharm.

Share

Leave a Reply

Your email address will not be published. Required fields are marked *

*