Volume Number: 18 (2002)
Issue Number: 8
Column Tag: Mac OS X

Writing Contextual Menu Plugins for OS X, part 1

Implementing the new COM-compatible API

by Brent Simmons

The API for contextual menu plugins is different in OS X than in OS 8/9. It's COM-compatible--it's based on Microsoft's Component Object Model.

That should be enough to scare you off, but don't let it. The good news is you can deal with the COM interface once and re-use that code. The even better news is that this article will provide it for you so you won't have to write it in the first place.

After getting the COM parts out of the way, this article will show how to add a Copy Path menu command to the Finder's contextual menu. This command will copy the path of a selected file or folder onto the clipboard (a path as in /Users/john/myCat.tiff). The second article in this series will go further: it will show how to add submenus, work with text selections, and execute Unix commands.

You can download the source and project files for this article from

http://ranchero.com/downloads/mactech/CopyPathPluginSource.sit

The sample plugin is built with the April 2002 Developer Tools version of Project Builder.

Before we start coding, let's get the mile-high view of contextual menus on OS X.

The basic gist of contextual menus is that when you control-click on something--some files, a folder, some text--a menu appears with commands that do something with what you clicked on.

In other words, contextual menus act on a selection. You wouldn't, for example, put the Sleep command in a contextual menu, since Sleep doesn't act on a selection.

Also, you wouldn't put an Eject command in a menu that appears when text is selected. Though the Eject command acts on a selection, it doesn't act on text. An Eject command (or similar) should appear only when a removable disk is selected.

Contextual menu plugins are system-wide--almost, anyway. Not every app supports system contextual menus. But you'll find plenty that do, including Eudora, CodeWarrior IDE, BBEdit, Internet Explorer, and of course the Finder.

Plugins are bundles; they're CFPlugins. They can be installed at ~/Library/Contextual Menu Items/ or at /Library/Contextual Menu Items/. The first location makes a plugin accessible to a specific user; the second location makes a plugin accessible to all users.

Okay. Let's code.

A contextual menu plugin has three things it must do: add menu items when requested, run a chosen menu command, and satisfy the requirements of the COM-compatible API.

We'll start with the COM stuff, because it's not utterly thrilling--and, gotten out of the way once means it's out of the way forever. In fact, if you're in a hurry you can skip down to the UUIDs section below.

Think of COM as a framework for object-oriented plugins. Every plugin must implement the IUnknown interface. IUnknown is the base class; it implements interface querying and reference counting.

Specifically it implements three functions: addRef, which increments the reference count; release, which decrements the reference count and releases the object if the count goes to zero; and queryInterface, which is called to determine if a plugin implements a given interface.

Cocoa developers especially are familiar with reference counting. Each time a COM object is retained its reference count is incremented. When it's released, the reference count is decremented. When it goes to zero the object is disposed.

If you're not familiar with reference counting, you can think of it as a "friends" counter. Each time you get an addRef call, it's like someone ringing you up and saying, hey, I'm your friend. Each time you get a release call, it's like someone ringing you up and saying, hey, I'm no longer your friend. You keep a count of how many friends you have. When the count goes to zero you may as well not exist anymore. (It's a good thing people aren't COM objects.)

addRef, the first of the required IUnknown interface functions, is called to increment the reference count:

addRef
static ULONG addRef (void *pluginInstance)
   {
      tyPlugin *instance = (tyPlugin*) pluginInstance;
      (*instance).refCount += 1;
      return ((*instance).refCount);
   }

It gets a pointer to an instance of the plugin and bumps refCount. (Note that though it returns the reference count, this is just a convention, not something to be relied on.)

tyPlugin is a struct defined in CopyPathPlugin.h:
typedef struct tyPlugin {
   ContextualMenuInterfaceStruct *cmInterface;
   CFUUIDRef factoryId;
   UInt32 refCount;
   } tyPlugin;

The first element of the tyPlugin struct is a pointer to a struct that lays out the functions implemented by the plugin. factoryId is the unique ID of the plugin. refCount is the current reference count.

ContextualMenuInterfaceStruct, also defined in CopyPathPlugin.h, looks like this:

static ContextualMenuInterfaceStruct interfaceTable = {
   NULL,
   queryInterface,
   addRef,
   release,
   examineContext,
   handleSelection,
   postMenuCleanup
   };

The first item is some necessary padding. The next three functions--queryInterface, addRef, and release--are required by the IUnknown interface. The final three functions--examineContext, handleSelection, and postMenuCleanup--are required by the contextual menus plugin interface.

release, the second of the required IUnknown interface functions, is called to decrement the reference count. When the reference count goes to zero, the instance is disposed.

release
static ULONG release (void *pluginInstance)
   {
      tyPlugin *instance = (tyPlugin*) pluginInstance;
      (*instance).refCount -= 1;
      if ((*instance).refCount == 0) {      
         deallocateInstance (instance);
         return (0);
         }
      return ((*instance).refCount);
   }

The important part is where it checks if refCount has gone to zero and in that case calls deallocateInstance.

deallocateInstance
static void deallocateInstance (tyPlugin *pluginInstance)
   {
      CFUUIDRef factoryId = (*pluginInstance).factoryId;
      free (pluginInstance);
   
      if (factoryId) {
         CFPlugInRemoveInstanceForFactory (factoryId);
         CFRelease (factoryId);
         } 
   }

The instance is passed to free which deallocates the memory. Then the instance is disassociated from its factory ID and the factory ID reference is released.

How are instances allocated in the first place? The system calls the factory function pluginFactory to create new instances of the plugin object. It knows to call pluginFactory because in the Application Settings in Project Builder we've specified pluginFactory as the name of the factory method.

Choose Edit Active Target from the Project menu; click on the Bundle Settings tab; click on the Expert button (in the upper right of the window). Expand the CFPluginFactories line and underneath you'll see the UUID of this plugin with a value of pluginFactory.

Here's pluginFactory itself:

pluginFactory
void* pluginFactory (CFAllocatorRef allocator,
   CFUUIDRef typeId)
   {
      #pragma unused (allocator)
      if (CFEqual (typeId, kContextualMenuTypeID))
         return (allocateInstance (kCMPlugInFactoryId));
      return (NULL);
   }

First it does a sanity-check (via CFEqual) that what's wanted is a contextual menu plugin, then it calls allocateInstance to actually allocate a new instance.

allocateInstance
static tyPlugin* allocateInstance (CFUUIDRef factoryId)
   {
      tyPlugin *newInstance;
      newInstance = (tyPlugin*) malloc (sizeof (tyPlugin));
      (*newInstance).cmInterface = &interfaceTable;
      (*newInstance).factoryId = CFRetain (factoryId);   
      CFPlugInAddInstanceForFactory (factoryId);
      (*newInstance).refCount = 1;
   
      return (newInstance);
   }

Malloc allocates the memory for a new instance, then the elements of the struct are filled in. cmInterface gets a pointer to the interface table (a ContextualMenuInterfaceStruct). The factory ID is set and retained via CFRetain. The instance is associated with this factory ID via CFPlugInAddInstanceForFactory. refCount is set to 1 and the instance is returned.

queryInterface, the third and last of the required IUnknown interface functions, is called to check to see if a given plugin implements a given interface.

queryInterface
static HRESULT queryInterface (void* pluginInstance,
   REFIID iid, LPVOID* ppv)
   {
      if (isGoodInterface (iid)) {
         addRef (pluginInstance);
         *ppv = pluginInstance;
         return (S_OK);
         }
      *ppv = NULL;
      return (E_NOINTERFACE);
   }

If the interface is one that this plugin implements, then the reference count is incremented (via addRef) and a pointer to the plugin instance is returned. Otherwise an error code (E_NOINTERFACE) is returned.

isGoodInterface checks to see that the requested interface is either IUnknown or the contextual menu plugin interface.

isGoodInterface
static Boolean isGoodInterface (REFIID iid)
   {
      CFUUIDRef interfaceId =
         CFUUIDCreateFromUUIDBytes (NULL, iid);
      Boolean flGoodInterface = false;
      
      if (CFEqual (interfaceId, kContextualMenuInterfaceID))
         flGoodInterface = true;
      if (CFEqual (interfaceId, IUnknownUUID))
         flGoodInterface = true;
   
      CFRelease (interfaceId);
      return (flGoodInterface);
   }

It creates a CFUUIDRef that can be compared to the contextual menu interface ID and the IUnknown ID. If it matches either interface ID, then it's an interface that this plugin implements. isGoodInterface returns true if there's a match, false otherwise.

This is the only COM thing you have to re-do for each plugin you create. Luckily, it's a piece of cake, just slightly tedious.

A UUID is a universally unique identifier that identifies your plugin. In this sample it appears in CopyPathPlugin.h as the following un-aesthetic lines:

/*The unique ID for this plugin:
CEEFF462-6C32-11D6-A15C-0050E4591B3C*/
#define kCMPlugInFactoryId (CFUUIDGetConstantUUIDWithBytes \
   (NULL, 0xCE, 0xEF, 0xF4, 0x62, 0x6C, 0x32, 0x11, 0xD6, \
   0xA1, 0x5C, 0x00, 0x50, 0xE4, 0x59, 0x1B, 0x3C))

To generate a new UUID, launch Terminal.app, and on the command line type uuidgen and hit Return. Underneath will appear a new UUID. (See Figure 2.)

When you go to create your own plugins, copy the UUID generated by uuidgen into your code as in the sample. Then do the tedious bit of copy-and-paste needed to make it look like the above.

Then choose Edit Active Target from the Project menu; click the Bundle Settings tab; click the Expert button. Your UUID should appear in two places (as in this sample): under CFPlugInFactories and under CFPlugInTypes. (See Figure 3.)

Enough COM. Let's do the fun part, the contextual menus interface.

Contextual menu plugins must implement three functions beyond the three required IUnknown interface functions.

examineContext is called to give the chance for the plugin to add commands to the menu that's being built. The plugin can see what the current context is, and decide what commands to add or not add.

handleSelection is called to actually run the command the user chose.

postMenuCleanup is called afterward in case the plugin has any cleanup to do.

You don't own the contextual menu, you just get the chance to add one or more commands. It's a shared menu: the system may add commands and other plugins may add commands.

This sample plugin will add a Copy Path command when a file or folder is selected in the Finder. examineContext is the first of the required contextual menus interface functions.

examineContext
static OSStatus examineContext (void *pluginInstance,
   const AEDesc *context, AEDescList *commandList)
   {
      if (getFileObject (context, nil))
         return (addCommandToMenu (commandList));
      if (getFileObjectFromList (context, nil))
         return (addCommandToMenu (commandList));
      return (noErr);
   }

Here's an important point: though we said above that we want this command to appear only in the Finder, in fact we'll do something smarter. Let's not care if it it's the Finder or not, let's care only that it's a file or folder object that's selected.

That way, if someone writes a Finder replacement that supports system contextual menus, this plugin will work there too.

A general rule of thumb is that the important part of the context is the type or types of objects selected. The application is of lesser importance, when it's even important at all. In this sample we don't care if it's Apple's Finder, John Doe's cool replacement Finder, or any other app that presents file objects.

context is an Apple event descriptor describing the object or objects selected. What we want to know is if it's a file or folder selected. To do that we see if the object either is or can be coerced to a descriptor of typeAlias (which points to a file or folder).

So examineContext calls getFileObject which returns true if context is already of typeAlias or can be coerced to typeAlias. (It may be of typeFSS, for instance.)

If getFileObject returns false, then examineContext calls getFileObjectFromList. If context is an AEDescList, then it checks to see if the first item in the list is of typeAlias or can be coerced to typeAlias. The reason we do this is because in testing we discovered that context is always an AEDescList when selecting even just one file or folder in the Finder. We could perhaps have gotten away with assuming that that would always be true, and skipped the call to getFileObject, but then a future version of the Finder might break our plugin. (Or the plugin might not work with other apps where context isn't always an AEDescList.)

This function checks to see if a descriptor is of typeAlias or can be coerced to typeAlias.

getFileObject
static Boolean getFileObject (const AEDesc *desc,
   AEDesc *resultDesc)
   {
      AEDesc tempDesc = {typeNull, NULL};
      Boolean flFile = false;
      OSErr err = noErr;
   
      if ((*desc).descriptorType == typeAlias) {
         if (resultDesc != nil)
            return (AEDuplicateDesc (desc, resultDesc) == noErr);   
         else
            return (true);
         } 
   
      err = AECoerceDesc (desc, typeAlias, &tempDesc);
      if ((err == noErr) &&
         (tempDesc.descriptorType == typeAlias)) {      
         flFile = true;
   
         if (resultDesc != nil)
            flFile =(AEDuplicateDesc (&tempDesc, resultDesc)
               == noErr);
         } 
      AEDisposeDesc (&tempDesc);
      return (flFile);
   }

If context is already of typeAlias, then we know it's a file or folder, and the function returns true. The function checks (*desc).descriptorType to determine the type of the context descriptor.

If context can be coerced to typeAlias (via AECoerceDesc), then again the function returns true. Otherwise it returns false.

Note that this function will make a copy of context (via AEDuplicateDesc) in resultDesc if the caller wants. This will be used later when the plugin is called to run our menu command (via handleSelection).

getFileObjectFromList

This function gets a file object from a list (an AEDescList).

Listing 10: getting a file object from an AEDescList

static Boolean getFileObjectFromList (const AEDesc *desc,
   AEDesc *resultDesc)
   {   
      Boolean flFile = false;
      long numItems = 0;
      OSErr err = noErr;
      AEKeyword keyword;
      AEDesc tempDesc = {typeNull, NULL};
   
      if ((*desc).descriptorType != typeAEList)
         return (false);
   
      err = AECountItems (desc, &numItems);   
      require_noerr (err, getFileObjectFromList_fail);
      if (numItems == 1) {   
         err = AEGetNthDesc (desc, 1, typeWildCard,
            &keyword, &tempDesc);
         if (err == noErr) {
            flFile = getFileObject (&tempDesc, nil);         
            if ((flFile) && (resultDesc != nil))
               AEDuplicateDesc (&tempDesc, resultDesc);      
            AEDisposeDesc (&tempDesc);
            } 
         } 
      getFileObjectFromList_fail:
      return (flFile);
   }

First it makes sure that context is in fact an AEDescList. Then it counts the number of items in the list via AECountItems. If the number of items is one, then it gets the first item (AEGetNthDesc), then calls getFileObject to see if that first object is of typeAlias or can be coerced to typeAlias.

As with getFileObject, this function will return a copy of the file object in resultDesc as a typeAlias descriptor if the caller wishes. But for examineContext we don't want a copy, we just want to know if it's a file object or not.

Back to examineContext: if either getFileObject or getFileObjectFromList return true, then it calls addCommandToMenu to add the Copy Path command to the contextual menu.

The contextual menu being built is passed to examineContext as an AEDescList. To add a command to the menu, addMenuCommand creates an AERecord and adds the command string and command ID. Then it adds the record to the end of commandList.

addCommandToMenu
static OSStatus addCommandToMenu (AEDescList *commandList)
   {
      AERecord command = {typeNull, NULL};
      Str255 commandString = copyPathCommand;
      OSErr err = noErr;
      SInt32 commandId = 2000;
   
      err = AECreateList (NULL, 0, true, &command);
      require_noerr (err, addCommandToMenu_complete_fail);
      err = AEPutKeyPtr (&command, keyAEName, typeChar,
         &commandString [1], commandString [0]);
      require_noerr (err, addCommandToMenu_fail);
   
      err = AEPutKeyPtr (&command, 'cmcd',
         typeLongInteger, &commandId, sizeof (commandId));
      require_noerr (err, addCommandToMenu_fail);
      /*0 means add to end of list.*/
      err = AEPutDesc (commandList, 0, &command); 
      addCommandToMenu_fail:
      AEDisposeDesc (&command);
      addCommandToMenu_complete_fail:
      return (err);
   }

The command is created via AECreateList. AEPutKeyPtr is used to add the text of the command and its command ID. (This sample doesn't actually use the command ID, since there's just one menu command--but if you have more than one command the command ID is quite useful.)

Finally the command record is added to the end of the command list via AEPutDesc.

After cleaning up, addCommandToMenu returns, then examineContext returns. Then we move on to implementing handleSelection.

This function, the second function required by the contextual menu interface, is called to run a contextual menu command. In this sample we run the Copy Path command. Our version of handleSelection looks like this:

handleSelection
static OSStatus handleSelection (void *pluginInstance,
   AEDesc *context, SInt32 commandId)
   {
      AEDesc aliasDesc = {typeNull, NULL};
      char path [MAXPATHLEN];
      OSErr err = noErr;
      if (!getAliasDesc (context, &aliasDesc))
         return (noErr);
      if (getPathStringFromAlias (&aliasDesc, path))
         writePathToClipboard (path);
      AEDisposeDesc (&aliasDesc);
      return (err);
   }

It takes a pointer to the plugin instance, a pointer to the context (the same context that examineContext gets, a description of the selected object(s)), and the command ID of the menu command that was chosen.

Just as in examineContext, we want to get a descriptor of typeAlias from context. So getAliasDesc is called to get a typeAlias descriptor. If it fails, the plugin does nothing.

Once it has the descriptor, it calls getPathStringFromAlias to get the path to the file object as a C string. Then it calls writePathToClipboard to write the path string to the clipboard. After cleaning up it returns.

Backing up... here's getAliasDesc:

getAliasDesc
static Boolean getAliasDesc (const AEDesc *desc,
   AEDesc *resultDesc)
   {
      if (getFileObject (desc, resultDesc))
         return (true);   
      return (getFileObjectFromList (desc, resultDesc));
   }

It calls getFileObject and getFileObjectFromList, which are the same functions we used in examineContext to determine if a file object was selected. The difference here is that the second parameter to these functions is not null, it's a pointer to a descriptor that should become a typeAlias descriptor--a file object.

handleSelection then calls getPathStringFromAlias:

getPathStringFromAlias
static Boolean getPathStringFromAlias (const AEDesc *desc,
   char *path)
   {
      FSRef fileRef;
      Size dataSize = AEGetDescDataSize (desc);
      AliasHandle aliasRef;
      Boolean flChanged = false;
      OSErr err = noErr;
   
      aliasRef = (AliasHandle) NewHandle (dataSize);
      if (aliasRef == nil)
         return (false);
   
      err = AEGetDescData (desc, *aliasRef, dataSize);   
      require_noerr (err, getFileObjectFromAlias_fail);
   
      err = FSResolveAlias (NULL, aliasRef,
         &fileRef, &flChanged);
      require_noerr (err, getFileObjectFromAlias_fail);
   
      err = FSRefMakePath (&fileRef, (UInt8*) path,
         MAXPATHLEN);
   
      getFileObjectFromAlias_fail:   
      DisposeHandle ((Handle) aliasRef);
      return (err == noErr);
   }

It allocates a new AliasHandle via NewHandle, then gets its data by calling AEGetDescData to get it from the typeAlias descriptor.

Then it gets an FSRef from the AliasHandle by calling FSResolveAlias.

Then it gets a path string from the FSRef by calling FSRefMakePath. (Note: MAXPATHLEN is defined in sys/param.h, which is included by CopyPathPlugin.h.)

It returns after cleaning up.

Finally handleSelection calls writePathToClipboard which writes the path string to the clipboard.

writePathToClipboard
static void writePathToClipboard (char *path)
   {
      ScrapRef scrap;
      ClearCurrentScrap ();
      GetCurrentScrap (&scrap);
      PutScrapFlavor (scrap, kScrapFlavorTypeText,
         kScrapFlavorMaskNone, strlen (path),
         (const void*) path);
   }

It clears the current scrap (clipboard), gets a reference to the current scrap, then writes the string as text to the scrap via PutScrapFlavor. Simple.

That's it for implementing handleSelection.

This function is the third and last function required by the contextual menu interface. If the plugin had any cleanup to do after running the command, this would be the place to do it. But since there's no cleanup to do (in this sample), postMenuCleanup is a no-op:

postMenuCleanup
static void postMenuCleanup (void *pluginInstance)
   {
      /*This plugin has no cleanup to do.*/
   }

After building your plugin, you'll find it in the build directory in the project directory. Copy it to ~/Library/Contextual Menu Items/. You may need to create the Contextual Menu Items folder if it doesn't already exist.

If you're replacing a plugin that's already installed, first trash the old version, then copy the new version into the Contextual Menu Items folder.

You'll need to quit and restart the Finder before it will see the new version of the plugin. What I do is put an AppleScript script in my dock that looks like this:

tell application "Finder"
   quit
end tell

OS X is just a bit unpredictable when it runs this script. Sometimes the Finder quits twice. Sometimes the Finder restarts, sometimes not. No harm is apparent. If the Finder doesn't restart, click the Mac smiley face icon in the Dock and the Finder will launch.

If you'd rather, you can log out then log back in instead, which also restarts the Finder.

To test this plugin, install it as above, then control-click (or right-click if you have a two-button mouse) on one file or folder in the Finder. You should see a Copy Path command in the menu that appears. Choose the command, then choose Show Clipboard from the Finder's Edit menu. The clipboard contents should be text, the path to the object you clicked on. Try doing a paste in another app just to make sure everything works as expected.

Tip: for debugging plugins I use printf calls. The output appears in Console.app, which you can find in the /Applications/Utilities/ directory.

As you've seen, implementing contextual menu plugins in OS X is not terribly difficult, it's just that the COM-compatible interface is not obvious. Given sample code and an understanding of how the COM interface works, you can concentrate on the code that's unique to your plugin.

In the next article we'll go farther, we'll show how to build a submenu, how to send an update event to the Finder, how to handle selected text (in apps such as BBEdit and Internet Explorer), and how to call a Unix command from a menu command.

• Apple sample code:

  http://developer.apple.com/samplecode/Sample_Code/Human_Interface_Toolbox/SampleCMPlugIn.htm

• CoreFoundation Plugin Services: http://developer.apple.com/techpubs/macosx/CoreFoundation/PluginServices/Plug_in_ServicesConcTask/index.html

• Contextual Menu Workshop is a free framework for creating OS X contextual menus:

  http://homepage.mac.com/tkukiel/cmworkshop.html

Brent Simmons is a Seattle-based independent Mac OS X developer and writer, a fan of both Cocoa and Carbon. He runs a Mac developer news weblog at ranchero.com; he can be contacted at brent@ranchero.com.