oreilly.comSafari Books Online.Conferences.


AddThis Social Bookmark Button

Inside Contextual Menu Items, Part 1

by Steven Disbrow

Editor's note: In this first installment of a two-article series, Steven Disbrow helps you limber up your right-clicking finger and describes handy power user tips for two-button mousing on Mac OS X. In Part 2 this coming Tuesday, he'll show you how to create your own CMIs using Xcode.

I think it's safe to say that Apple Computer, Inc. makes the best one-button mouse in the world.

Yes indeed, Apple's Pro Mouse is truly a joy to use ... for about five minutes. After that, most folks over the age of five unplug the thing, put it in a drawer and hook up a two-, three-, four-, or five-button mouse so that they can get some real work done.

Given Apple's recent attempts to woo Windows users to the Mac platform, it's a wonder that Apple still doesn't offer a mouse with two (or more) buttons, not even as an option for "switchers." This would be a very smart move because if there's one thing that Window users love, it's right-clicking on things.

You see, in Windows, clicking the second (also called the "right") mouse button on an object almost always brings up a special menu containing options directly related to the object on which you are right-clicking. For example, right-clicking on a disk will bring up a menu allowing you to format the disk, eject the disk (if it's a removable disk), or rename the disk, among other options. These special menus are called contextual menus because their contents depend on the context in which they were invoked. (For example, you get a slightly different menu if you right-click on a folder rather than a disk.)

Mac OS X to the Rescue

Now, it's true that the Mac OS has had the ability to pull up a contextual menu or two for a while now. (I believe it was Mac OS 8 that introduced this ability.) But with Apple selling us nothing but one-button mice and forcing us to hold down the Control key when clicking (called "control-clicking") to invoke a contextual menu, or to install special drivers to use a two-button mouse, it's always seemed more of a "Me too!" implementation than a real attempt to catch up with this very cool Windows feature. Fortunately, with the release of Mac OS X, that changed in a big way!

Related Reading

Mac OS X: The Missing Manual, Panther Edition
By David Pogue

Even though Apple still insists on shipping nothing but one-button mice, Mac OS X has been supporting multi-button mice since the beginning. With Mac OS X, you no longer need special drivers to use these mice. Just plug in your multi-button mouse and not only does Mac OS X recognize that second button, but just about any object you right-click on in the Finder will have a contextual menu full of options that apply to that object. (Better still, any additional buttons on your mouse can be used in other parts of Mac OS X. For example, Exposé functions can be mapped to one of your additional mouse buttons. But that's another article.)

Of course, since Apple just recently got serious about contextual menus, the contextual menus in Mac OS X generally aren't as feature-filled as their Windows equivalents. Fortunately, Mac OS X has a solution for that as well; it allows you to create and install your own contextual menu items!

Once installed, a contextual menu item (CMI) will be called by Mac OS X whenever the user right-clicks the mouse. The CMI will then have an opportunity to examine the context in which it was invoked and report back to Mac OS X whether or not it should be included in the final contextual menu that the user sees. For example, a CMI could be written to only appear when the user right-clicks in a particular application (Safari, perhaps) or when the user right-clicks on a particular type of object (such as an Adobe PDF file). Programmer-created CMIs can have sub-menus (and sub-sub-menus) and can generally do anything that a clever programmer can trick them into doing.

In fact, there are already tons of cool, "can't live without 'em" CMIs available for Mac OS X. Just go to your favorite Mac software download site (such as MacUpdate or Version Tracker) and search for "contextual menu" and "CM". You'll get back dozens of neat CMIs that you can download and install on your system to make your life easier.

Installing Contextual Menu Items by Hand

Most CMIs that you download will come with an installer program that takes care of all the gory details of installation. However, some will require you to install your new CMI by hand. Fortunately there are only two places on your system where a CMI can go, so it's incredibly easy to do. Where you install your CMI depends on which of the users on your Mac you want to have access the CMI.

If you want every user on your Mac to have access to the new CMI, copy the CMI file into the /Library/Contextual Menu Items folder. (Note that CMI files will have an extension of .plugin, so look for a file with this extension in the materials that came with your CMI download. Checking any "Read Me" file that came with the download would be a good idea too!) You'll find this folder by double-clicking on your boot drive and then double-clicking on the Library folder.

If there isn't a Contextual Menu Items folder inside of the Library folder, simply create it and copy the CMI .plugin file into the new folder. (Note that you'll need administrator access to create this folder and/or copy a file into it.) Once the file is copied, all users of the system will have access to the new CMI the next time they log in. (You'll need to log out and back in yourself to gain access to the CMI.) Figure 1 shows the path to this folder on my system, along with the CMI that lives there. (Yes, it's one that I wrote myself.)

Path for system wide

If you want only certain users to have access to the CMI, each user will need to copy it into the Library/Contextual Menu Items folder in their home directory. (You'll usually see this denoted like this: ~/Library/Contextual Menu Items. The tilde (~) denotes the path to the home folder of the current user.) So, let's say that you want to be the only one on your system that can use the CMI you've just downloaded. Open your boot drive, then open the Users folder. Inside there, you'll see a list of folders with names matching the names of the users on your system.

In this case, double-click on the folder with your user name (it should have a house icon rather than a generic folder icon) to open it. Inside there, you should find a Library folder. Open that and look for a Contextual Menu Items folder. If it exists, copy the CMI's .plugin file into it. If not, create the folder and copy the .plugin file into the new folder. Then log out and back in to make the CMI available to all your applications. That's all there is to it! Figure 2 (below) shows the path to my ~/Library/Contextual Menu Items folder.

Path to location for single user CMI installation.
(Click for larger view)

Deleting a Contextual Menu Item

Getting rid of a CMI is simplicity itself: just delete the .plugin file and then log out and back in. That's it!

Troubleshooting Contextual Menu Items

Most CMIs will probably work as advertised, but occasionally you'll run across one that doesn't work the way you expect. So, wrapping up, I'd like to offer some tips for troubleshooting CMI installations.

First and foremost, it's important to realize that some Mac OS X applications don't support the CMI framework that Apple has defined, so any CMIs that you install simply won't be available from inside these applications. Most of the "big name" applications work fine, but two that don't work are Mozilla (and its derivatives, such as Firefox) and Dreamweaver MX 2004.

Why don't these applications work with CMIs? I honestly don't know the answer, but I suspect that it has to do with the fact that both are fairly old applications and that they haven't been completely moved over to use the new programming frameworks that Apple provides. Hopefully, this will change in the near future.

Another place that your Mac OS X CMIs won't work is inside the X11 environment. This isn't surprising, however: X11 is a completely different windowing system from Aqua, with its own contextual menu system. It doesn't know anything about the Mac OS X CMI framework and probably never will.

So, if those are the cases where a CMI simply won't work, what about the times when a CMI "works" all too well and behaves in bizarre ways? Well, there's a simple way to troubleshoot CMIs and avoid just this situation.

When I was talking about installing a CMI, at the end of the process I said that you should log out and back in to make the CMI available to all of your applications. The key part of this is the phrase "all of your applications." You see, in Mac OS X, each application loads your installed CMIs when that application is executed. So, for example, if you have the Finder and Safari running and you have GreatCM.plugin version 1.0 installed on your system, both of them have loaded GreatCM.plugin version 1.0. If however, you download and install GreatCM.plugin version 2.0, and then fire up, say, TextEdit, without first logging out and back in, the Finder and Safari will still be using version 1.0, but TextEdit will have loaded version 2.0!

Now, you could quit and restart both the Finder and Safari, so that everybody has version 2.0 loaded, but if you've got a lot of applications running, it's a lot easier just to log out and back in. (It's smarter, too! The new version could, for example, make changes to a shared preference file that would totally confuse version 1.0.)

However, you can use this behavior to your advantage. For example, if you download and install a new CMI, you don't have to log out and back in just to test it. Simply fire up a sacrificial application and test the CMI there before logging out and back in. (I like to use the Console because if there's a crash, that's the application I'll start next to track down what went wrong. Remember however, that these are contextual menu items, so your sacrificial application should be one that the CMI would normally work with.) If the CMI doesn't perform to your liking, simply kill the sacrificial application, delete the CMI's .plugin file, and you're back in business!

That's All For Now!

I hope you've found this introduction to contextual menu items interesting. In my next article, I'll show you how to actually program a contextual menu item so you can extend the power of your system with just a simple (right) click!

Steven Disbrow is the President of EGO Systems, Inc., a computer consulting firm in Chattanooga, TN.

Return to the Mac DevCenter