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:

"$(WindowsSdkToolsDir)\bin\uicc" "%(Identity)" "%(Filename).bin" /header:"%(Filename).h"
   /res:"%(Filename).rc2"

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

%(Filename).bin;%(Filename).h;%(Filename).rc2;%(Outputs)

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:

#ifdef APSTUDIO_INVOKED
/////////////////////////////////////////////////////////////////////////////
//
// TEXTINCLUDE
//

1 TEXTINCLUDE
BEGIN
    "resource.h\0"
END

2 TEXTINCLUDE
BEGIN
    "#include ""Ribbon.h""\r\n"
    "#ifndef APSTUDIO_INVOKED\r\n"
    "#include ""targetver.h""\r\n"
    "#endif\r\n"
    "#define APSTUDIO_HIDDEN_SYMBOLS\r\n"
    "#include ""windows.h""\r\n"
    "#undef APSTUDIO_HIDDEN_SYMBOLS\r\n"
    "\0"
END

3 TEXTINCLUDE
BEGIN
    "#include ""Ribbon.rc2""\r\n"
    "\0"
END

#endif    // APSTUDIO_INVOKED

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:

if (FAILED(CoInitialize(NULL)))
{
  ReportError(IDS_COINITIALIZE_FAILED);
  retVal = false;
  /* Fear of goto is highly irrational. Get over it. */
  goto exitinit;
}

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.

LoadAppSettings();

if (settings.isRibbon)
{
  CreateRibbon();
}

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

bool App::CreateRibbon()
{
  /* Attempt to create the ribbon framework interface. */
  HRESULT hr = CoCreateInstance(
    CLSID_UIRibbonFramework,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_PPV_ARGS(&pFramework));

  if (SUCCEEDED(hr))
  {
    /* Framework creation succeeded, so initialize the framework and
    create the ribbon. */

    /* The killRibbon flag controls the activation of message handling to fix a repaint
    problem that occurs when the ribbon is removed. */
    killRibbon = false;

    hr = pFramework->Initialize(GetHWND(), this);

    if (SUCCEEDED(hr))
    {
      hr = pFramework->LoadUI(GetModuleHandle(NULL), L"APPLICATION_RIBBON");

      if (SUCCEEDED(hr))
      {
        hr = pFramework->GetView(0, IID_PPV_ARGS(&pRibbon));

        if (SUCCEEDED(hr))
        {
          settings.isRibbon = true;
        }
      }
    }
  }

  if (FAILED(hr))
  {
    /* If ribbon creation or initialization failed, make sure that any interfaces are released
    and set to null so that the UI will fall back and use the menu instead. */
    CloseRibbon();
  }

  return SUCCEEDED(hr);
}

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.

SetDirty(false);
SetRedo(false);
EnableMenuItem(GetMenu(GetHWND()), ID_SHOW_RIBBON,
  IsRibbonSupported() ? MF_ENABLED : MF_GRAYED);

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:

bool App::IsRibbonSupported()
{
  bool isRibbonSupported = false;
  IUIFramework* pTmp = 0;

  /* Attempt to create the ribbon framework interface. */
  HRESULT hr = CoCreateInstance(
    CLSID_UIRibbonFramework,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_PPV_ARGS(&pTmp));

  if (SUCCEEDED(hr))
  {
    isRibbonSupported = true;
    pTmp->Release();
  }

  return isRibbonSupported;
}

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.

ULONG STDMETHODCALLTYPE App::AddRef()
{
  return InterlockedIncrement(&refCount);
}

ULONG STDMETHODCALLTYPE App::Release()
{
  return InterlockedDecrement(&refCount);
}

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

HRESULT STDMETHODCALLTYPE App::QueryInterface(
  REFIID riid,
  void **ppvObject)
{
  if (!ppvObject)
  {
    return E_INVALIDARG;
  }

  if (riid == IID_IUnknown)
  {
    *ppvObject = static_cast<IUnknown*>(static_cast(this));
  }
  else if (riid == __uuidof(IUICommandHandler))
  {
    *ppvObject = static_cast<IUICommandHandler*>(this);
  }
  else if (riid == __uuidof(IUIApplication))
  {
    *ppvObject = static_cast<IUIApplication*>(this);
  }
  else
  {
    *ppvObject = 0;
    return E_NOINTERFACE;
  }

  AddRef();
  return S_OK;
}

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.

HRESULT STDMETHODCALLTYPE App::OnViewChanged(
  UINT32 viewId,
  UI_VIEWTYPE typeID,
  IUnknown* pView,
  UI_VIEWVERB verb,
  INT32 uReasonCode)
{
  HRESULT hr = E_NOTIMPL;

  if (UI_VIEWVERB_CREATE == verb)
  {
    IUIRibbon* pRibbon = NULL;
    hr = pView->QueryInterface(IID_PPV_ARGS(&pRibbon));

    if (SUCCEEDED(hr))
    {
      LoadRibbonSettings(pRibbon);
      pRibbon->Release();
    }
  }
  else if (UI_VIEWVERB_SIZE == verb)
  {
    RECT rect = {};
    GetClientRect(GetHWND(), &rect);
    OnSize(GetHWND(), 0, rect.right - rect.left, rect.bottom - rect.top);
  }
  else if (UI_VIEWVERB_DESTROY == verb)
  {
    IUIRibbon* pRibbon = NULL;
    hr = pView->QueryInterface(IID_PPV_ARGS(&pRibbon));

    if (SUCCEEDED(hr))
    {
      SaveRibbonSettings(pRibbon);
      pRibbon->Release();
    }
  }

  return hr;
}

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.

HRESULT STDMETHODCALLTYPE App::OnCreateUICommand(
  UINT32 commandId,
  UI_COMMANDTYPE typeID,
  IUICommandHandler** commandHandler)
{
  if (commandHandler)
  {
    *commandHandler = static_cast<IUICommandHandler*>(this);
    AddRef();
    return S_OK;
  }

  return E_INVALIDARG;
}

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.

HRESULT STDMETHODCALLTYPE App::OnDestroyUICommand(
  UINT32 commandId,
  UI_COMMANDTYPE typeID,
  IUICommandHandler* commandHandler)
{
  return E_NOTIMPL;
}

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.

HRESULT STDMETHODCALLTYPE App::UpdateProperty(
  UINT32 commandId,
  REFPROPERTYKEY key,
  const PROPVARIANT *currentValue,
  PROPVARIANT *newValue)
{
  if (newValue)
  {
    if (key.fmtid == UI_PKEY_Enabled.fmtid)
    {
      if (commandId == ID_CMD_SAVE)
      {
        (*newValue).boolVal = IsDirty() ? VARIANT_TRUE : VARIANT_FALSE;
      }
      else if (commandId == ID_CMD_REDO)
      {
        (*newValue).boolVal = CanRedo() ? VARIANT_TRUE : VARIANT_FALSE;
      }
    }
  }

  return S_OK;
}

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.

HRESULT STDMETHODCALLTYPE App::Execute(
  UINT32 commandId,
  UI_EXECUTIONVERB verb,
  const PROPERTYKEY *key,
  const PROPVARIANT *currentValue,
  IUISimplePropertySet *commandExecutionProperties)
{
  if (verb == UI_EXECUTIONVERB_EXECUTE)
  {
    PostMessage(GetHWND(), WM_COMMAND, commandId, 0);
  }

  return S_OK;
}

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:

<Command Name="cmdNew" Id="0x0100" Symbol="ID_CMD_NEW" Keytip="N">
   <Command.LabelTitle>New</Command.LabelTitle>
   <Command.TooltipTitle>New (Ctrl+N)</Command.TooltipTitle>
   <Command.TooltipDescription>Create a new document</Command.TooltipDescription>
   <Command.LargeImages>
      <Image Source="images/New-icon-32.bmp" Id="101" Symbol="ID_NEW_LARGEIMAGE1" MinDPI="96" />
   </Command.LargeImages>
   <Command.SmallImages>
      <Image Source="images/New-icon-16.bmp" Id="102" Symbol="ID_NEW_SMALLIMAGE1" MinDPI="96" />
   </Command.SmallImages>
</Command>
<Command Name="cmdOpen" Id="0x0103" Symbol="ID_CMD_OPEN" Keytip="O">
   <Command.LabelTitle>Open</Command.LabelTitle>
   <Command.TooltipTitle>Open (Ctrl+O)</Command.TooltipTitle>
   <Command.TooltipDescription>Open a document</Command.TooltipDescription>
   <Command.LargeImages>
      <Image Source="images/Open-icon-32.bmp" Id="103" Symbol="ID_OPEN_LARGEIMAGE1" MinDPI="96" />
   </Command.LargeImages>
   <Command.SmallImages>
      <Image Source="images/Open-icon-16.bmp" Id="104" Symbol="ID_OPEN_SMALLIMAGE1" MinDPI="96" />
   </Command.SmallImages>
</Command>

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

#define ID_CMD_NEW 0x0100
#define ID_CMD_NEW_LabelTitle_RESID 60010
#define ID_CMD_NEW_Keytip_RESID 60011
#define ID_CMD_NEW_TooltipTitle_RESID 60012
#define ID_CMD_NEW_TooltipDescription_RESID 60013
#define ID_NEW_SMALLIMAGE1 102
#define ID_NEW_LARGEIMAGE1 101
#define ID_CMD_OPEN 0x0103
#define ID_CMD_OPEN_LabelTitle_RESID 60014
#define ID_CMD_OPEN_Keytip_RESID 60015
#define ID_CMD_OPEN_TooltipTitle_RESID 60016
#define ID_CMD_OPEN_TooltipDescription_RESID 60017
#define ID_OPEN_SMALLIMAGE1 104
#define ID_OPEN_LARGEIMAGE1 103

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.

IDC_APP_MENU MENU
BEGIN
    POPUP "&File"
    BEGIN
        MENUITEM "&New\tCtrl+N",                ID_CMD_NEW
        MENUITEM "&Open\tCtrl+O",               ID_CMD_OPEN
        MENUITEM "&Save\tCtrl+S",               ID_CMD_SAVE
        MENUITEM "Save &As...\tCtrl+Shift+S",   ID_CMD_SAVEAS
        MENUITEM SEPARATOR
        MENUITEM "E&xit\tAlt+F4",               ID_CMD_EXIT
    END
    POPUP "&Edit"
    BEGIN
        MENUITEM "&Undo\tCtrl+Z",               ID_CMD_UNDO
        MENUITEM "&Redo\tCtrl+Y",               ID_CMD_REDO
        MENUITEM SEPARATOR
        MENUITEM "Cu&t\tCtrl+X",                ID_CMD_CUT
        MENUITEM "&Copy\tCtrl+C",               ID_CMD_COPY
        MENUITEM "&Paste\tCtrl+V",              ID_CMD_PASTE
        MENUITEM "&Delete\tDel",                ID_CMD_DELETE
    END
    POPUP "&View"
    BEGIN
        MENUITEM "Zoom &In\tCtrl+Plus",         ID_CMD_ZOOMIN
        MENUITEM "Zoom &Out\tCtrl+Minus",       ID_CMD_ZOOMOUT
        MENUITEM "&Normal Zoom\t Ctrl+0",       ID_CMD_NORMALZOOM
        MENUITEM SEPARATOR
        MENUITEM "&Show Ribbon",                ID_SHOW_RIBBON
    END
    POPUP "&Help"
    BEGIN
        MENUITEM "&View Help\tF1",              ID_CMD_VIEWHELP
        MENUITEM "&About\tCtrl+?",              ID_CMD_ABOUT
    END
END

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.

void App::OnCommand(
  HWND hwnd,
  int id,
  HWND hwndCtl,
  UINT codeNotify)
{
  switch (id)
  {
  case ID_CMD_NEW:
    AppendText(L"New document\r\n");
    SetDirty(true);
    break;

  case ID_CMD_OPEN:
    AppendText(L"Open document\r\n");
    break;

    /* ... */
  }
}

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:

case ID_HIDE_RIBBON:
  /* I use PostMessage here because when I tried to remove the
  ribbon immediately after pressing the corresponding ribbon button,
  the UIRibbon code would die trying to process the WM_LBUTTONUP
  message on a ribbon window that no longer existed. This gets
  around that. */
  PostMessage(hwnd, AM_SHOW_MENU, 0, 0);
  break;

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:

case AM_SHOW_MENU:
  {
    /* Set this flag to trigger the repaint hack for DWM environments
    when the ribbon is removed. */
    killRibbon = true;
    CloseRibbon();
    PostMessage(GetHWND(), AM_RESTORE_MENU, 0, 0);
  }
  return 0;

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.

void App::CloseRibbon()
{
  /* If we have a ribbon, release it so that it will uninitialize cleanly. */
  if (pRibbon)
  {
    pRibbon->Release();
    pRibbon = 0;
  }

  /* Likewise, destroy and release the ribbon framework. */
  if (pFramework)
  {
    pFramework->Destroy();
    pFramework->Release();
    pFramework = 0;
  }

  settings.isRibbon = false;
}

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:

case AM_RESTORE_MENU:
  {
    SetMenu(GetHWND(), hMenu);

    /* This is hackish, but it sets the menu items to the proper state. In a real app
    I'd probably use some sort of signal/slots implementation to wire up this stuff. */
    SetDirty(IsDirty());
    SetRedo(CanRedo());
    EnableMenuItem(GetMenu(GetHWND()), ID_SHOW_RIBBON,
      IsRibbonSupported() ? MF_ENABLED : MF_GRAYED);
  }
  return 0;

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.

case ID_SHOW_RIBBON:
  PostMessage(hwnd, AM_SHOW_RIBBON, 0, 0);
  break;

This, in turn, activates a case in WndProc.

case AM_SHOW_RIBBON:
  {
    if (IsRibbonSupported())
    {
      /* Don't need the repaint hack anymore. */
      killRibbon = false;

      ShowWindow(GetHWND(), SW_HIDE);
      CreateRibbon();
      ShowWindow(GetHWND(), SW_SHOW);

      RECT rect = {};
      GetClientRect(GetHWND(), &rect);

      /* You aren't supposed to post a WM_SIZE message, but it's the only hack
      I could make work consistently to get the window to repaint correctly in
      all situations. */
      PostMessage(GetHWND(), WM_SIZE, 0,
        MAKELPARAM(rect.right - rect.left, rect.bottom - rect.top));
    }
  }
  return 0;

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.

bool App::SaveRibbonSettings(
  IUIRibbon* pRibbon)
{
  /* Build a path to an app-specific directory in the user's application
  data storage directory. */
  HRESULT hr = E_FAIL;
  WCHAR pPath[MAX_PATH] = {};

  if (BuildSettingsPath(pPath, L"ScratchRibbonProjectSettings.bin"))
  {
    IStorage* pStorage = 0;
    hr = StgCreateStorageEx(pPath, STGM_CREATE|STGM_SHARE_EXCLUSIVE|STGM_READWRITE,
      STGFMT_STORAGE, 0, NULL, NULL, __uuidof(IStorage), (void**)&pStorage);

    if (SUCCEEDED(hr))
    {
      IStream* pStream = 0;

      hr = pStorage->CreateStream(L"Ribbon",
        STGM_CREATE|STGM_READWRITE|STGM_SHARE_EXCLUSIVE,
        0, 0, &pStream);

      if (SUCCEEDED(hr))
      {
        hr = pRibbon->SaveSettingsToStream(pStream);
        pStream->Release();
      }

      pStorage->Release();
    }
  }

  return SUCCEEDED(hr);
}

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.

bool App::LoadRibbonSettings(
  IUIRibbon* pRibbon)
{
  HRESULT hr = E_FAIL;
  WCHAR pPath[MAX_PATH] = {};

  if (BuildSettingsPath(pPath, L"ScratchRibbonProjectSettings.bin"))
  {
    IStorage* pStorage = 0;

    hr = StgOpenStorageEx(
      pPath,
      STGM_READ|STGM_SHARE_DENY_WRITE,
      STGFMT_STORAGE,
      0, NULL, NULL,
      __uuidof(IStorage),
      (void**)&pStorage);

    if (SUCCEEDED(hr))
    {
      IStream* pStream = 0;
      hr = pStorage->OpenStream( L"Ribbon", NULL,
        STGM_READ|STGM_SHARE_EXCLUSIVE,0, &pStream);

      if (SUCCEEDED(hr))
      {
        LARGE_INTEGER liStart = {0, 0};
        ULARGE_INTEGER ulActual;
        pStream->Seek(liStart, STREAM_SEEK_SET, &ulActual);
        hr = pRibbon->LoadSettingsFromStream(pStream);
        pStream->Release();
      }

      pStorage->Release();
    }
  }

  return SUCCEEDED(hr);
}

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.

void App::SetDirty(bool isDirtyInit)
{
  isDirty = isDirtyInit;

  if (pFramework)
  {
    pFramework->InvalidateUICommand(ID_CMD_SAVE, UI_INVALIDATIONS_STATE, NULL);
  }

  HMENU hMenu = GetMenu(GetHWND());

  if (hMenu)
  {
    EnableMenuItem(hMenu, ID_CMD_SAVE, isDirty ? MF_ENABLED : MF_GRAYED);
  }
}

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.

void App::OnSize(
  HWND hwnd,
  UINT state,
  int cx,
  int cy)
{
  /* Adjust any child windows in the client area to match the new size. */
  AdjustClientArea(cx, cy);

  /* Hack to correctly repaint in DWM environments when the ribbon is removed. */
  if (killRibbon && state != SIZE_MINIMIZED)
  {
    SetWindowPos(hwnd, NULL, 0, 0, 0, 0,
      SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED);
  }
}

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

void App::AdjustClientArea(
  int cx,
  int cy)
{
  /* Adjust the size of the edit window to fit into the client area.
  Take the size of the ribbon into consideration, if there is one. */
  UINT32 ribbonHeight = 0;

  if (pRibbon)
  {
    pRibbon->GetHeight(&ribbonHeight);
  }

  SendMessage(hEdit, WM_SETREDRAW, 0, 0);
  MoveWindow(
    hEdit,
    0, ribbonHeight,
    cx,
    cy - ribbonHeight,
    TRUE);
  int textLen = GetWindowTextLength(hEdit);
  SendMessage(hEdit, EM_SETSEL, static_cast<WPARAM>(textLen), static_cast<LPARAM>(textLen));
  SendMessage(hEdit, WM_SETREDRAW, 1, 0);
  RedrawWindow(hEdit, NULL, NULL, RDW_ERASE | RDW_FRAME | RDW_INVALIDATE | RDW_ALLCHILDREN);
  SendMessage(hEdit, EM_SCROLLCARET, 0, 0);
}

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.

case WM_SIZING:
  {
    /* Hack to correctly repaint in DWM environments when the ribbon is removed. */
    if (killRibbon)
    {
      switch (wParam)
      {
      case WMSZ_TOP:
      case WMSZ_TOPLEFT:
      case WMSZ_TOPRIGHT:
        {
          PRECT pRect = reinterpret_cast<PRECT>(lParam);
          SetWindowPos(GetHWND(), NULL,
            pRect->left, pRect->top,
            pRect->right - pRect->left, pRect->bottom - pRect->top,
            SWP_NOMOVE | SWP_NOZORDER | SWP_FRAMECHANGED);
        }
        break;

      default:
        DefWindowProc(GetHWND(), msg, wParam, lParam);
      }

      return TRUE;
    }

    return DefWindowProc(GetHWND(), msg, wParam, lParam);
  }

case WM_ACTIVATE:
  {
    /* Hack to correctly repaint in DWM environments when the ribbon is removed. */
    if (killRibbon)
    {
      if (wParam != WA_INACTIVE)
      {
        SetWindowPos(GetHWND(), NULL,
          0, 0, 0, 0,
          SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED);
      }

      return FALSE;
    }

    return DefWindowProc(GetHWND(), msg, wParam, lParam);
  }

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

case WM_NCCALCSIZE:
  {
    LRESULT result = DefWindowProc(GetHWND(), msg, wParam, lParam);

    /* Hack to correctly repaint in DWM environments when the ribbon is removed. */
    if (killRibbon && wParam)
    {
      MARGINS margins = {};
      DwmExtendFrameIntoClientArea(GetHWND(), &margins);

      RECT adjustedRect = {};
      AdjustWindowRectEx(&adjustedRect, GetWindowStyle(GetHWND()),
        TRUE, GetWindowExStyle(GetHWND()));

      LPNCCALCSIZE_PARAMS pParams = (LPNCCALCSIZE_PARAMS)lParam;
      pParams->rgrc[0].top = pParams->rgrc[1].top + (-adjustedRect.top);
    }

    return result;
  }

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.

On top of all that, Blogger is yanking the rug out from under me with some changes to how it updates certain sites, and I want to get that resolved before I add any significant new content. I just wanted to let everyone know that the project isn’t dead; in fact, there have been several times over the last few weeks when I’ve needed a utility like Ripsaw, so this is definitely going to get done eventually.

I’m implementing this project with Visual Studio 2010, which is still in beta as of this writing. You may download the solution, projects, and source code if you’d like to follow along, but if you haven’t downloaded and installed the 2010 beta yet, you’ll need to adapt the code to your IDE and C++ compiler of choice if you wish to build it (I recommend Visual Studio 2008).

class ATL_NO_VTABLE RipsawFile :
   public CComObjectRootEx<CComMultiThreadModel>,
   public CComCoClass<RipsawFile, &CLSID_RipsawFile>,
   public ISupportErrorInfo,
   public IConnectionPointContainerImpl<RipsawFile>,
   public CProxy_IRipsawEvents<RipsawFile>,
   public IDispatchImpl<IRipsawFile, &IID_IRipsawFile, &LIBID_RipLib, /*wMajor =*/ 1, /*wMinor =*/ 0>

#pragma once
#include <comutil.h>

template <class Root, class T, const IID* piid = &__uuidof(T),
   const GUID* plibid = &ATL::CAtlModule::m_libid,
   WORD wMajor = 1, WORD wMinor = 0,
   class tihclass = ATL::CComTypeInfoHolder>
class IRipsawObjectImpl :
   public Root,
   public ATL::IDispatchImpl<T, piid, plibid, wMajor, wMinor, tihclass>
{
public:
   /* Internal public implementation */
   IRipsawObjectImpl() : isOpen(FALSE)
   {
   }

   virtual ~IRipsawObjectImpl()
   {
   }

public:
   /* IRipsawObject interface */
   HRESULT STDMETHODCALLTYPE get_Name(
      __out BSTR* pName)
   {
      if (!pName)
      {
         return E_INVALIDARG;
      }

      {
         ObjectLock(this);
         *pName = NULL;
      }
      return S_OK;
   }

   HRESULT STDMETHODCALLTYPE get_IsOpen(
      __out VARIANT_BOOL* pRetVal)
   {
      if (!pRetVal)
      {
         return E_INVALIDARG;
      }

      LONG retVal = 0;
      InterlockedExchange(&retVal, isOpen);
      *pRetVal = retVal ? VARIANT_TRUE : VARIANT_FALSE;
      return S_OK;
   }

   HRESULT STDMETHODCALLTYPE Close()
   {
      _bstr_t fileName;

      VARIANT_BOOL tmpIsOpen = VARIANT_FALSE;
      get_IsOpen(&tmpIsOpen);

      if (tmpIsOpen)
      {
         ObjectLock(this);
         put_IsOpen(FALSE);
         BSTR name = 0;
         get_Name(&name);
         Notify_Close(name);
         SysFreeString(name);
      }

      return S_OK;
   }

   HRESULT STDMETHODCALLTYPE WaitForUpdate(
      __in ULONG timeout,
      __out BSTR* pNewData)
   {
      if (!pNewData)
      {
         return E_INVALIDARG;
      }

      *pNewData = NULL;
      return S_OK;
   }

protected:
   /* Internal protected implementation */
   HRESULT STDMETHODCALLTYPE put_IsOpen(
      __in VARIANT_BOOL value)
   {
      InterlockedExchange(&isOpen, value);
      return S_OK;
   }

   virtual HRESULT Notify_Open(BSTR fileName)
   {
      return S_OK;
   }

   virtual HRESULT Notify_Close(BSTR fileName)
   {
      return S_OK;
   }

   virtual HRESULT Notify_Update(BSTR updateData)
   {
      return S_OK;
   }

   LONG isOpen;
};

To be callable from script, the object’s interface should be OLE-automation compatible, so we’ll declare it as such in our IDL:

[
   oleautomation,
   uuid(2D486A73-E912-4078-9F38-678226E4A0BD),
   dual,
   pointer_default(unique)
]
interface IRipsawFile : IDispatch
{
}

The interface is also derived from IDispatch to support late-binding, which means that scripting languages can discover the methods and properties of the interface at runtime.

Before we can write the test script we’ll need decide what basic methods a Ripsaw object needs to implement. A single Ripsaw object will represent a connection to a file, and the object will fire events whenever the file changes so that listeners can take an action based on the update (change the display, parse the update, etc.). At a minimum, then, we need to be able to open a file and close a file.

interface IRipsawFile : IDispatch
{
   [id(1)] HRESULT Open(
      [in] BSTR fileName,
      [out,retval] VARIANT_BOOL* pSuccess);

   [id(2)] HRESULT Close();
}

The Open method will accept a path to a file and return a Boolean indicating the success or failure of the method call. The Close method will close any existing connection, and we won’t bother to check for a return code from that method.

Now, it would probably be useful to be able to query a property of the object for the name of the file to which it is connected, and perhaps another property to check if the object is currently opened or closed. Let’s add those properties:

interface IRipsawFile : IDispatch
{
   [id(1), propget] HRESULT Name(
      [out,retval] BSTR* pName);

   [id(2), propget] HRESULT IsOpen(
      [out,retval] VARIANT_BOOL* pRetVal);

   [id(3)] HRESULT Open(
      [in] BSTR fileName,
      [out,retval] VARIANT_BOOL* pSuccess);

   [id(4)] HRESULT Close();
}

Okay, not bad so far. We can open a file, query for the status, query for the name, and close the file. That’s no good if we can’t catch events fired by the object. We need to define a dispinterface that specifies the events that the object can fire at its clients:

[ uuid(6671C129-C761-42F3-AB2F-D12C33D95160) ]
dispinterface _IRipsawEvents
{
properties:
methods:
   [id(1)] HRESULT Open([in] BSTR fileName);
   [id(2)] HRESULT Close([in] BSTR fileName);
   [id(3)] HRESULT Update([in] BSTR updateData);
};

The Open event fires when a file is opened successfully, of course. Close fires when a file is closed, and Update naturally fires when the file changes. The Update notification will also pass along the data that was gathered from the last file update.

Okay, based on those interfaces, our script might look like this:

var ripsaw = WScript.CreateObject("PMP.RipsawFile", "ripsaw_");

if (ripsaw)
{
   ripsaw.Open("testfile.log");

   if (ripsaw.IsOpen)
   {
      WScript.Echo("Ripsaw file is open: '" + ripsaw.Name + "'");

      /* Uh-oh... */

      ripsaw.Close();

      if (!ripsaw.IsOpen)
      {
         WScript.Echo("Ripsaw file is closed: '" + ripsaw.Name + "'");
      }
      else
      {
         WScript.Echo("ERROR: Ripsaw file reported open");
      }
   }
   else
   {
      WScript.Echo("ERROR: Ripsaw file reported closed");
   }
}
else
{
   WScript.Echo("ERROR: Failed to create Ripsaw file");
}

function ripsaw_Open(fileName)
{
   WScript.Echo("ripsaw_Open(" + fileName + ")")
}

function ripsaw_Close(fileName)
{
   WScript.Echo("ripsaw_Close(" + fileName + ")")
}

function ripsaw_Update(data)
{
   WScript.Echo("ripsaw_Update(" + data + ")")
}

First of all, I’ll explain what all this means for those of you that are new to JavaScript — err, JScript — under Windows Script Host (WSH). The first line creates a COM object based on its ProgID, or programmatic identifier. This is a string that resolves, through the registry, to a GUID that uniquely identifies a COM library that provides the requested functionality.

The second parameter to CreateObject tells the scripting engine to wire events provided by the object to functions that start with the specified prefix. In our script, we want to handle the Open, Close, and Update notifications, so we created functions named ripsaw_Open, ripsaw_Close, and ripsaw_Update to catch these events. Since they all start with the “ripsaw_” prefix, the script engine will call them when any of the corresponding events are fired by our object.

If you looked carefully at the script, you noticed that I inserted a comment: “Uh-oh.” That’s because the script has no way of sitting and waiting for an update other than looping in a tight loop, and that is almost never a good idea. The script would waste CPU time doing nothing while we wait for the file to be updated. In other languages we have access to message loops, WaitForSingleObject, and other means of yielding CPU until an event occurs, but not in WSH. We need something better. What we’ll do is add a method to our object which, when called, will do absolutely nothing until an update occurs. We’ll call it WaitForUpdate.

interface IRipsawFile : IDispatch
{
   [id(1), propget] HRESULT Name(
      [out,retval] BSTR* pName);

   [id(2), propget] HRESULT IsOpen(
      [out,retval] VARIANT_BOOL* pRetVal);

   [id(3)] HRESULT Open(
      [in] BSTR fileName,
      [out,retval] VARIANT_BOOL* pSuccess);

   [id(4)] HRESULT Close();

   [id(5)] HRESULT WaitForUpdate(
      [in] ULONG timeout,
      [out,retval] BSTR* pNewData);
}

The first parameter is a timeout, in milliseconds, so that the function will return if no updates arrive in the specified amount of time. We’ll take a page from Win32 and say that a value of 0xFFFFFFFF will tell the method to wait forever. If the timeout expires, the method will return a null BSTR; otherwise, the return value will be the new data from the last file update. We’ll modify the heart of our script to call the new method:

      WScript.Echo("Ripsaw file is open: '" + ripsaw.Name + "'");

      var timeout = 5000;
      WScript.Echo("Waiting for data...");
      var newData = ripsaw.WaitForUpdate(timeout);

      if (newData)
      {
         WScript.Echo("Waited for data:", newData);
      }
      else
      {
         WScript.Echo("Timed out after waiting for data for " + timeout + " milliseconds");
      }

      ripsaw.Close();

In a real script we’ll probably call WaitForUpdate in a loop, but for now we’ll just wait for one update before exiting.

Generalizing the Interface

This looks good for files, but perhaps later on we’d like to extend Ripsaw to listen to other sources of events, like the Windows Event Log (the first Ripsaw actually did that for a while, but I backed out the feature to focus on files). It would be a good idea to go ahead and factor out the common methods and properties into a base interface that could be extended by other event sources.

[
   oleautomation,
   uuid(0270FDFF-56AF-42ec-9971-AE8DCB0DAB36),
   dual,
   pointer_default(unique)
]
interface IRipsawObject : IDispatch
{
   [id(1), propget] HRESULT Name(
      [out,retval] BSTR* pName);

   [id(2), propget] HRESULT IsOpen(
      [out,retval] VARIANT_BOOL* pRetVal);

   [id(3)] HRESULT Close();

   [id(4)] HRESULT WaitForUpdate(
      [in] ULONG timeout,
      [out,retval] BSTR* pNewData);
};

[
   oleautomation,
   uuid(2D486A73-E912-4078-9F38-678226E4A0BD),
   dual,
   pointer_default(unique)
]
interface IRipsawFile : IRipsawObject
{
   [id(10)] HRESULT Open(
      [in] BSTR fileName,
      [out,retval] VARIANT_BOOL* pSuccess);
};

Later on, if we define an interface for listening to event logs, we’ll derive that interface from IRipsawObject and define an Open method specific to event logs. We’ll also assign a special ProgID to event log objects so our client applications can create them:

var ripsaw = WScript.CreateObject("PMP.RipsawEventLog", "ripsaw_");

Next Steps

Now we have an interface, and we have a script to exercise that interface. What we need next is some real code to implement the interface and a binary that the script can load and run. We’ll start on a preliminary implementation in the next article. Until then, you can download the IDL and the script file and look them over. Please leave a comment with any suggestions you may have.