For the past few years I’ve been responsible for maintaining a subsystem that allows a point-of-sale system to communicate with external applications. These external applications may display information gathered from the POS and poke inputs back into it. I was involved in the initial development of the subsystem back in 2004 or so, and when the other developers left for other positions it fell to me to continue enhancing and supporting the subsystem.

I wasn’t happy with the first implementation because of some design problems, but I couldn’t change the design too much without impacting existing integrations with the subsystem. Instead, over the course of a year or so I made several improvements to the bits of code that integrated the subsystem with other applications and improved the API that the subsystem exposes.

Considering the number of transactions it supports every day across hundreds of installations, I think the subsystem is rather fast and stable. Occasionally, however, whenever there is a performance issue with an application that uses the subsystem, the subsystem itself gets blamed, and I am usually called upon to investigate the issue. While there are some scenarios that can trigger bottlenecks with the subsystem, the problems I investigate are pretty much never the fault of the subsystem.

Finally, after having to explain the intricate technical details yet again, I decided to come up with an analogy to explain how the subsystem works, how it could be a bottleneck is some scenarios, and why it usually wasn’t the bottleneck in spite of the possibility. I e-mailed the analogy to all interested parties, and it seems to have had the desired effect. I’ve edited the analogy to remove specific product and subsystem names and provided it here. In the wrap-up, I changed the name of the subsystem to NPS, for Note-Passing Subsystem.

The Story of Olympic Note Passing

We’re going to imagine a strange sport called Olympic Note Passing. Two runners run around adjacent circular tracks: Runner A, and runner F. Each time runner A reaches the outside portion of the track he picks up a message that he will deliver to runner F. Runner F will then deliver this message to the other side of track F. Never mind why this happens; some sports are just unusual (think golf or curling).

Now, the first time this sport was introduced into the Olympics, the messages were passed from runner A to runner F via a specially designed, and somewhat magical, box. This box accepts messages via a device like a bill acceptor, and on the other side of the box is a device like a bill dispenser that spits out formatted, translated copies of the messages that were put into the other side. This way, runners from different nations that speak different languages can still participate in the sport and understand the messages being passed from A to F.

Runners on the two tracks could run at independent speeds, so that runner A could stop for just a moment and place a message into the box before taking off around the track again, and runner F could stop for just a moment to pick up any messages that were waiting.

The original practice of Olympic Note Passing

There was a problem with this magic box, however. If runner A was placing messages into one side of the box, runner F could not take any messages out of the box until A was finished. Likewise, if runner F was taking messages out, runner A couldn’t place any messages into the box. This turned out to be a problem because the runners had to keep stopping and waiting for each other.

This state of affairs threatened to kill the fledgling sport before it ever got started, since spectators didn’t want to see the two runners stopping, starting, and waiting for each other all the time, so the Olympic committee had to come up with a solution. One intrepid committee member suggested designing new magic boxes so that messages could be inserted and extracted at the same time, but the committee had already spent a lot of money designing the existing boxes, and any new boxes would have to be the same size, shape, and color as the existing boxes and would have to work EXACTLY the same way in every other respect. Furthermore, the guy that designed the original boxes was now working for NASCAR and doing equally silly things to the Car of Tomorrow.

The way the committee decided to fix this problem was to station a person on either side of the magic box: helper A, and helper F. Now, runner A just hands messages to helper A on the way around the track, and helper A inserts the message into the machine while runner A keeps moving. Likewise, helper F extracts any waiting messages from the machine and hands them off to runner F when he comes around the track. If helper A sees that the machine is busy and he can’t insert any messages, he will just put the new messages in his pocket until the machine is available. Helper F will pull messages out of the machine as soon as they are available and keep them in his pocket until runner F comes around the track. If helper F has no messages, he will wave runner F on around the track.

New and improved Olympic Note Passing

Now, we’ll bring all of this around to the actual NPS design. Runner A is an AwesomePOS system, and Runner F is FooApp. The magic box is NPS. The messages being passed through the magic box are NPS messages. The redesigned sport, with helper A and helper B, represents the new NPS integration design introduced at SuperCustomer in late 2009 and early 2010. The people stationed on either side of the magic box are the independent threads that are now running in AwesomePOS and FooApp that service the NPS message queue.

With this picture in mind, it should be a little more apparent why NPS is pretty much never the source of any performance issues in current implementations, but why it can be a performance bottleneck if the integration is not done carefully. If AwesomePOS or FooApp have to keep stopping and starting to deal with NPS, it can impact the performance of the entire system. With the new design, however, NPS is much less of a bottleneck since runners A and F can now keep moving around the track a lot more smoothly, but messages can still get from one side of track A to the other side of track F no more quickly than the slower runner can move.

Please don’t design sites that look like this:

Waste of space!

Rather, please design sites that look like this:

This uses space more effectively.

I’m not knocking Herb Sutter, here. I’m pretty sure he’s just using a stock template, but templates that don’t flow to fit the browser width really puzzle me. Is there a good reason for them that I’m just not aware of?

I stumbled onto a bit of code that will find all aliases for a given Cmdlet which I put it into a script named Find-Alias. That will let me type the following:

PS C:\>Find-Alias Get-ChildItem

CommandType     Name                     Definition
-----------     ----                     ----------
Alias           dir                      Get-ChildItem
Alias           gci                      Get-ChildItem
Alias           ls                       Get-ChildItem

Here is the script code:

param(
    [Parameter(Position=0, Mandatory=$true, ValueFromPipeline=$true, ValueFromPipeLineByPropertyName=$true)]
    [string]$Command)

Process
{
  get-alias | where-object {$_.Definition -match $Command}
}

Before I launch into the body of this essay, let me say that I think meetings are wonderful things. I’ll even go so far as to say that people in my field, software development, probably don’t have enough meetings. I have to qualify these opinions, however, by saying that they only apply to the right kinds of meetings. Regularly scheduled project status meetings that involve an entire team are definitely the wrong kind of meeting. They provide very little useful communication, and they kill productivity. There are better ways to accomplish the purpose of status meetings without actually having them.

What’s Wrong with Project Status Meetings?

A project status meeting usually involves a manager and a team. Each member of the team, in turn, provides an update on the tasks that member has been working on since the last meeting. The manager or other team members may ask for additional information or provide comments on these updates. Team members that have little or no involvement with the tasks that are being discussed just sit and listen (or sleep, or doodle, or do what I do occasionally — write code long-hand on a pad of paper).

In a particularly malignant version of the status meeting, several teams and their managers are in a meeting with a higher-level manager, but each individual team member still reports on his tasks. On one project, I had meetings like this on a weekly basis, with upwards of 40 different people in one room. It was dreadful.

What makes these meetings so dreadful for me is that I’m only an active participant for two or three minutes. For the rest of the time (an hour and a half, or more, once a week, on my last project) I don’t have any real involvement with what’s being discussed. I’m a captive. I can neither provide any useful commentary on the discussion nor gain any useful insight from it. Even worse, I’m a consultant that bills on an hourly basis. I hate wasting my client’s time on uselessness when I could be doing something more productive with it.

Why I Think We Do It This Way

For several reasons, holding a management position is thought of as being a few steps up the career ladder, above the lowly status of the worker bee. I happen to think this situation is unfortunate, but that will be the topic of a later essay. In any case, people currently in management are usually older than the people that they manage, and they usually learned what they know about office interaction when they were younger, or at the very least from people who are older than they are. This means that the habits that are ingrained in managers may reflect a technological state of the art that was current ten or twenty years ago, maybe more.

Before the advent of telephones, e-mail, instant messaging, and wikis, the only way to get a timely update from several members of a team was to gather the members of the team together at a pre-arranged time and place. Fortunately, the telephone pre-dates most people currently in management, so for widely dispersed teams the conference call is in common use.

I try to take advantage of status meetings held both in-person and via conference calls by arranging my schedule so that my virtual working hours fall during the times that the status meetings are held. I dial into the meeting on my cell, using a headset so that my hands can stay on the keyboard. I listen for my name, provide my update and any comments that are relevant, and for the rest of the time I’m writing code, debugging, documenting, or testing. I’m less productive than I would be if I didn’t have to split my brain between the meeting and other tasks, but at least my downtime isn’t a total loss.

A Better Way

Rather than holding status meetings in person or via conference calls, why not take advantage of that wonderful new invention called e-mail? Every team I’ve worked on since 1993 has had e-mail. It’s safe to say, in fact, that I would refuse to work on a team in which one or more members didn’t have an e-mail address. E-mail has reached a comfortable level of ubiquity.

Here is what I propose: On a regular basis (for example, before noon every Monday) each team member would send an e-mail to the team’s manager and copy every other member of the team. The subject of the e-mail would clearly state that it contains a weekly status update: "Status Update for 2011/01/31." The body of the e-mail would contain a suitably detailed list of that team member’s assigned tasks and their status. It might also list the accomplishments of the past week and the problems that are retarding progress on current tasks.

Each team member could read these status updates at some point in the day and perhaps send a follow-up e-mail to other relevant team members to provide additional comments or ask questions. A meeting could be scheduled among interested parties if a topic needed to be discussed in more depth, or a meeting may just happen spontaneously in a phone call or around a whiteboard.

This kind of arrangement provides several advantages. First of all, it eliminates the need to synchronize everyone’s schedule around an event at a particular time and place every week (or every day, if a team is particularly dysfunctional). Second, it allows a great deal of flexibility in providing status updates to the team. Some people might compose their e-mails on Friday afternoon, some on Sunday evening, and some at 11:47 on Monday morning. Whatever fits into each person’s style and schedule will work.

Finally, and most importantly to me, if one is really in a flow and madly banging away at the keyboard in a productive state that I like to call "code falling out of the fingers," there’s no need to stop that state of productivity to listen to someone else drone about something which has little or no connection to whatever problem that person is thinking about. Each team member can reach a comfortable stopping point and deal with writing or reading the status e-mails on his own time.

An Aside: Flow Is King

In software development, particularly, achieving and maintaining flow is crucial for productivity. I worked on a project a while back that had a project status meeting every day at 11:00 AM. This REALLY killed my flow, because I like to spend the first part of each morning taking care of busy work, and by 9:30 or 10:00 I want to be in a really deep flow that may last until 1:00 or 2:00 in the afternoon, or whenever my hunger pangs finally remind that it’s time for lunch. Once, when my wife and I were engaged, she surprised me at my office while I was in this flow state. It took several seconds for me to even recognize her, and a few more seconds to be able to shift gears into human-to-human conversation. The flow state can be that deep!

If you’re a manager, you want your team members to be able to achieve and maintain a state of flow. Please, try to avoid doing anything that might interrupt it.

The Right Kinds of Meetings

As I wrote earlier, not all meetings are bad. I am a big fan of meetings in which all of the participants are focused on a particular issue. The meeting need not have a published agenda; that can often be a bad sign. All that’s needed is a clear statement of what the meeting needs to accomplish. For example, "We need to figure out what databases contain the data we need to gather for the migration from product ABC to product XYZ." That’s a meeting that has a chance of getting something done.

Another favorite of mine is the ad-hoc meeting, where two or three people might be discussing an idea or a problem, and before long they’re scribbling on a whiteboard or sitting around a computer trying out ideas.

What these kinds of meetings have in common is that all of the participants are engaged. They’re working toward a common goal so that they can get work done based on the output of the meeting. Project status meetings, in my experience anyway, never meet this description.

Why Not Try It?

I don’t know why, but I have yet to convince a manager that holds conventional status meetings to switch to e-mail updates instead. I’d like to hear from some managers about this idea. Why might it not work? Are there downsides that I’m just not seeing?

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.

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.

To bring you up to speed, Ripsaw is a log-viewing utility for Windows that I initially wrote about six years ago, but never released widely. I’ve decided to rewrite it and discuss each step of the rewrite here.

Implementing the API

The initial Ripsaw implementation was a monolithic (albeit small) application, but this time I want to separate the log-reading mechanism from the log-viewing UI. There are times when I’d like to use the log-reading capabilities of Ripsaw from JavaScript or PowerShell, and I’d also like to write more than one viewer application around the log reader. There are at least three possible technologies for this API:

1. C DLL
2. COM
3. .NET

Okay, there are a lot more that I could choose from, but for the machines I’m targeting these are the most likely candidates. A DLL exporting C functions would be the simplest to write and would be easy to integrate with most programming languages, but in order to use that sort of API from JavaScript (or similar languages) I’d have to write a COM wrapper. A .NET implementation would be COM-callable, but it would require having .NET installed on the target machine, and sometimes the systems I debug don’t have .NET installed (hard to believe, I know, but true). COM, however, is ubiquitous on Windows, fairly straightforward, can be used from JavaScript with ease, and is easily callable from .NET if I had a reason to do so later on. Therefore, I’ll implement Ripsaw’s non-UI behavior in a COM library.

What About Registration?

I’d still like to be able to run Ripsaw from a USB drive without having to install anything on the machine I’m debugging or examining, which means I’d like to avoid the hassle of having to run regsvr32 on the target machine before I can use Ripsaw. Fortunately, there is registration-free COM, which will let me run a Ripsaw viewer that loads the Ripsaw COM library with the aid of a manifest. This will let me keep a viewer and the Ripsaw library in a directory on my USB drive so I can just plug it in and run the viewer without having to register or install anything.

Supporting Scripting in the Viewer

Since Ripsaw’s log-reading capability will be implemented in COM, I’ll be able to write JavaScript apps that can watch for data from a log file, and these scripts can either parse the data or take actions based on the data. Not only would this be useful apart from a viewer, but it might also be useful inside a viewer. I could define script actions to operate on log lines, highlight them, parse them, etc., while I’m watching a log in the viewer. To take advantage of this I’ll add JavaScript support to the Windows Ripsaw viewer, along with the capability to load pre-defined scripts that act on log data.

Viewer Implementation

In keeping with my requirement for making Ripsaw light and portable, I don’t want to use .NET for the main viewer implementation. I might create a Windows Forms or WPF viewer later on once .NET becomes more widespread on the systems I mainly work on (point-of-sale terminals and servers for grocery stores), or for when I’m debugging in a controlled environment, but for the main console and GUI viewers I’ll use C++ as the development language. COM is still a bit of a pain to use from C++, at least compared to JavaScript or .NET, but it won’t be too bad.

Multiprocessor Support

Fortunately, the newer POS terminals and servers that are being installed today have multi-core processors, and I definitely want to take advantage of that today. I want to architect the core Ripsaw library to take advantage of multiple threads of execution spread across multiple processors or processor cores. I already write multi-threaded, multi-process systems for these machines, and these systems tend to be heavily instrumented, so sometimes I’m watching several different log files at once during a testing or debugging session. I don’t want to slow a system down too much when I start up the viewer, and loading down one core of a multi-core processor with a log viewer would certainly be a bad thing.

Okay, Can We Start Coding Now?

Actually, I already have been doing some prototyping, which helped me decide on the details I’ve described above. Now that I’ve sorted out some of the lower-level requirements, in the next article I’ll start defining the Ripsaw log-reader COM interface.

Split the App Into DLLs

The original Ripsaw was a 32-bit Windows application contained in a single executable. This made it easy to carry around on a USB drive and run on machines that I needed to debug. The downsides were that I had to link the C runtime library into the executable, and application was one monolithic entity that couldn’t be easily extended.

For the new Ripsaw I’m going to build it to use the C runtime in a DLL. For most of the machines I work with this will require carrying around the C runtime distributable, but I’m willing to do that as long as I don’t have to install anything on the terminal. I’m not completely up to speed with side-by-side assemblies; I prefer to just place the VS 2010 C runtime DLL in the same directory as the executable and run the app, but I’ll have to verify that’s still supported. (Edit: It is. Duh!) So far SxS has caused me a lot of grief, but that’s probably because I haven’t bothered to really understand it.

Create a Ripsaw API

Since I’m splitting out the C runtime, I’m also going to separate most of Ripsaw’s non-visual functionality into a separate API DLL. Not only will this make the core functionality more testable and enforce separation of UI, but I’ll be able to build more than one user interface around it. I’d like to build a command-line application as well as a graphical application. Sometimes you just can’t beat raw text.

Embrace 64-bit

Even though nearly all of my professional development is still 32-bit, I want to build Ripsaw to compile for both 32-bit and 64-bit architectures. I’ll need to do this eventually anyway, and this is a good time to start.

Support Extensibility

My original plans for Ripsaw included the ability to create filters for processing log output as it arrived in the application. Perhaps only lines containing certain values would be displayed, or maybe certain words would be shown in a particular color or font. Rather than trying to build every possible behavior into Ripsaw, I’ll publish an extensibility interface so that I can add features later on (or you can add them) without having to change the core API or UI.

Create a Windows 7 UI

The main UI that I’ll use will be a 32-bit graphical application targeting Windows XP, but I’d also like to take advantage of some of the new Windows 7 user interface controls such as the ribbon. I’m not inclined to try to serve both interface styles from one application, so after I finish the primary UI I’ll create a version that is specific to Windows 7. Since I’m putting most of the non-visual behavior into a separate DLL I’ll be free to experiment with different interfaces anyway.

Coming Up

In the next few articles I’ll delve into some more development specifics such as language and library choices.