Digital Alchemy Mercutio MDEF


* Overview
* Inside Mercutio(pdf)
* Internationalization
* Licensing Description
* Software License(pdf)

* Current version: 1.5.1
* Download Now!
* Release Notes
* Known Problems
* Version History

* Register!
* Registered Users

* Technical Support
* Mailing Lists
* Report a Bug


Feature Overview

The Mercutio MDEF is a Menu DEFinition resource that allow Macintosh developers to easily and elegantly extend the power of their application menus. Mercutio allows menus to have multiple-modifier key-equivalents (e.g. shift-command-C), custom icons, item callbacks, and other goodies. This page presents an overview Mercutio's features and functionality.

The Mercutio MDEF is free to developers who give appropriate credit and send us a copy of the final software. See software license for details.

Table of Contents

Mercutio Features
A technical description of Mercutio's features.
System Requirements
What Mercutio needs in order to run.
Sample usage
An example of how to integrate Mercutio into your project.
Mercutio and Non-U.S. Keyboards
This is a technical summary of the problems using Mercutio with Non-U.S. keyboards and how I plan to deal with this.

Feature summary

  • Better support for icons:
    • Support for all types of icons, including icon suites, even under System 6.
    • Small (16 x 16) and large (32 x 32) icons, including color icons.
    • You can have SICNs in hierarchical menu items.
  • Support for all keys on the keyboard:
    • Support for all 4 modifier keys (command, shift, option, control).
    • Support for non-printing keys (function keys, page up/down, arrow keys, etc).
    • Removed command-key requirement (can have control-A as an equivalent).
  • Dynamic items: items whose contents change depending on what modifier keys are being held down (e.g. when the option key is held down, Save becomes Save All).
  • Application callback routine to let you decide on the fly what the item contents should be.
  • User-definable style mapping: developer determines which style bits are used as feature flags
  • Supports non-western scripts, including right-to-left writing systems.
  • 99% compatible with standard MDEF, including:
    • System 7's Balloon Help and True Gray.
    • Color menus.
    • Dvorak keyboard support.
    • Geneva-9 point popup menus.
  • Full support for Xmnu resource; includes TMPL resources for ResEdit and Resorcerer.
  • Xmnu with resource ID 0 lets you set default settings for all Mercutio menus.
  • MDEF recognized by resource ID (19999) so you can delete the resource name before shipping.


Extended Icon Support

Mercutio supports a wide variety of icon types and sizes, including color icons ('cicn') and System 7 icon suites ('icl8', 'ICN#', etc.).

Icons screenshot

Icon Suites

There is limited system software support for icon suites under System 6. However, Mercutio tries to use whatever icon resources are available. If a 'icl8' is found for a given menu item, it will be converted to a 'CICN' and used as the item's icon. Similarly, if an 'ICON' resource is not found, Mercutio will look for a 'ICN#' resource with the same ID. This means you can develop one set of icons that will work for both System 6.0.4 and System 7.

Small icons

The System MDEF lets you include small icons (16 by 16 pixels, usually stored as sicn resources) into menu items by putting $1E into the cmdChar field of the menu item record. Unfortunately, this doesn't allow you to use small icons in menu items with key equivalents or hierarchical submenus, since they also use the cmdChar field. To address this issue, Mercutio draws all icons with IDs of 500 and above as small icons.

Extended key equivalents

Mercutio supports an extended set of key equivalents for menu items. This includes additional modifier keys as well as the non-printing keys on the keyboard (e.g. function keys).

The Mercutio MDEF supports Option, Shift and Control as modifiers in addition to the Command-key. Caps-lock is not supported.

The Mercutio MDEF supports non-printing keys such as the function keys, page up, page down, arrow keys, tab and delete. Note that certain non-printing keys have symbolic representations in the menu (e.g. the arrow keys are represented by iconic arrows) and others are spelled out in full-text.

Key combinations screenshot
Non-printing keys screenshot

In order to take advantage of Mercutio's features, you must use the provided MDEF_MenuKey routine instead of the standard Menu Manager MenuKey routine. This is the only change you must make to your code in order to use Mercutio (you may make additional changes to take advantage of other features).

Dynamic Items

Dynamic menu items are items that change appearance and behavior depending on what modifier keys are being held down. This is useful for closely-related commands, rarely-used commands, power-user commands, or other situations where you want to provide functionality without cluttering your menus.

Several commercial applications use this kind of menu. For example, the THINK Pascal(R) "Run" menu changes its appearance if the shift-key is held down. You can accomplish the same thing using Mercutio. The main difference is that Mercutio will also display the modifier keys being held down.

Dynamic items screenshot Dynamic items screenshot

Callback Items

Callback items allow you to determine the contents of a menu item at runtime. This is for situations where you don't know the contents of the item ahead of time. For example, a "File Type" menu might include icons from applications that the user has on the hard drive; you could use dynamic items to pull the icons out of the Desktop Database at runtime.

Mercutio allows you to associate a callback procedure with a Mercutio menu, and flag certain items as callback items. Before drawing any callback item, Mercutio will load in the item data (item text, icon handle, item modifiers, enabled state, etc.) from the MENU resource, then call the callback procedure in your application to give you the opportunity to modify the data before the item is displayed.

Since the contents of the menu item is completely up to you, no screen shot has been included. The sample code shows how to have a menu item that displays the current time (and updates it second by second!).


Mercutio is compatible with virtually all of the features of the System MDEF. This includes color menus, balloon help, System 7 "true gray" disabled items, popup menu support, etc.

Color menus screenshot

Feature Selection

Mercutio provides a number of features that redefine the appearance and behavior of Macintosh menus. Mercutio uses a technique called style-bit remapping to control these features on a menu item by menu item basis. That is, the style bits for a particular menu item are used to turn specific features (e.g. option-key, callback item, small icon, etc.) on and off.

Since style bits can't be used to flag text styles and features at the same time, and since Mercutio provides quite a few features that could eat up most of the style bits, the features that are available through style-bit remapping for a given menu are controlled feature templates. Different menus can have different feature templates, so for one menu, the condense style might flag the Shift-key, whereas for another menu it would falg the Option-key.

Sample usage

To get an idea of what is involved in integrating Mercutio into your application, here's the "QuickStart" section from the manual.

For those of you that want to get started right away, here are the five basic steps to integrate Mercutio into your application:

  1. Copy the resources in the Mercutio 1.2.MDEF file into your applications resource file. There are 3 resources that are needed: the Mercutio MDEF resource, and the .MDEF Font NFNT and FOND resources.
  2. Change the MDEF field in your MENU resources to 19999, the resource ID of the Mercutio MDEF. Dont change this resource number.
  3. If you are programming in Pascal, add the Mercutio API.p file to your project. If you are programming in C, add the Mercutio API.c and Mercutio API.h files to your project.
  4. Replace any calls to the toolbox MenuKey routine with the with new MDEF_MenuKey call. This replacement is needed in order to parse the additional modifier keys. Most likely you will have an event loop routine that looks something like this:

    CASE event.what OF
    	keyDown, AutoKey:
    		theKey := BitAnd(Event.message, charCodeMask);
    		IF (BitAnd(Event.modifiers, CmdKey) = CmdKey) THEN BEGIN
    			menuResult := menuKey(theKey);
    			if HiWord(menuResult) <> 0 THEN BEGIN
    		ELSE BEGIN { cmd not down; handle typing if needed }

    which should be changed to look like this:

    CASE event.what OF
       keyDown, AutoKey:
          theKey := BitAnd(Event.message, charCodeMask);

    menuResult := MDEF_MenuKey(Event.message, Event.modifiers, hAnMDEFMenu); if HiWord(menuResult) <> 0 THEN BEGIN ProcessMenu(menuResult); HiliteMenu(0); END; ELSE BEGIN { wasnt caught by the menus } ...

    Note: the third parameter to the MDEF_MenuKey routine must be a handle to a menu that is using the Mercutio MDEF.
  5. Recompile your application.
Thats it! Run your program. Any menu item in condense style with show an option key modifier in addition to the command key; any menu item in extend style with show an shift key modifier in addition to the command key. If you want to use additional modifier keys or Mercutio features, you'll need to set the feature preferences for the menu.

System requirements

  • The Mercutio MDEF works under System 6.0.4 or later, with or without Color QuickDraw. Mercutio is fully compatible with System 7, and supports all the features of the System MDEF.

  • Integrating the MDEF into your program shouldn't take more than 15 minutes.
  • Sample code is provided for Metrowerks Pascal and C.

Last modified by RMF at 18:59 PM on 02/26/1998. © Copyright 1996-2000, Digital Alchemy, All Rights Reserved.
This site was built on a Macintosh using BBEdit and CometPage.