Cocoa Dev Central

By Rustam Muginov

// What you should understand before creating a MenuExtra

1. This is the software which is using private, undocumented MacOS X API. Where are no any guarantees what this software would work in the following major MacOS X versions.
2. In the MacOS X 10.2, Apple made some effort to prevent third-party MenuExtra being loaded. Under MacOS 10.2, you would need to use Menu Extra Enabler from Unsanity or MenuCracker from james_007_bond.
3. The NSMenuExtra class is the subclass of NSStatusItem, which is the recommended way of putting custom menus to the right side of the menu bar. Although not as convinient and powerful as NSMenuExtra (you can not Command-drag to rearrange or remove NSStatusItem, you have to have a running application to keep it in the menu bar, e.t.c.), it is still documented (at least partialy) and recommended way. Perharbs you should consider if NSStatusItem is sufficient for your requirements first. A nice tutorial is available at Cocoa Dev Central.

// Available implementations of NSMenuExtra

Where are several implementations available with source code. They are:

1. Application Menu Switcher by Frank Vercruesse
2. ClassicSpy by Konstantin Anoshkin
3. MenuMeters by Alex Harper

They are very valuable examples, but personaly I've found that they are a bit too complex for the beginner. Another drawback, they are all distributed under GNU License, making it impossible for shareware/commercial developer to use their source code.

You will definitly want to look at their source code at a later time to learn more about the NSMenuExtra functionality.

// Reverse-engineering the API

The NSMenuExtra class resides in the SustemUIPlugin private framework. Objective-C keeps plenty of information about class names, inheritance, methods, e.t.c., so it is possible to get this information from the compiled binary. To obtain this framework API, we would use very useful class-dump utility by Steve Nygard. It is available here or here. Download the archive and unpack it. The class-dump is a command-line utility, so we will run it in terminal. If you put the "class-dump" binary inside the /Applications folder, then the command line would be /Applications/class-dump -e /System/Library/PrivateFrameworks/SystemUIPlugin.framework/Versions/A/SystemUIPlugin > SystemUIPlugin.h. Run this command, and check inside your home folder. You would find the "SystemUIPlugin.h" file in it.

We need to do some editing before it will be compilable. Open it in Project Builder and look at its nice content. First, add the #import <AppKit/AppKit.h> just under the comments. Then, correct the following:

1. Remove the "?" sign in the struct declarations in the NSMenuExtra and NSDockExtra interfaces
2. Replace the "expanded" struct _NSRect types in the initWithFrame and drawRect methods of NSMenuExtraView class. They should be:
   - initWithFrame:(NSRect)fp12 menuExtra:fp28;
   - (void)drawRect:(NSRect)fp12;
   

Now we have the API to the NSMenuExtra (and the whole SystemUIPlugin) private framework.

// Creating the project

Create a new ProjectBuilder project using the Cocoa Bundle template. Name it "Sample". We need to tune some parameters, so select the "Targets" tab and click the "Sample" target.

1. In Settings/Expert View, change the "WRAPPER_EXTENSION" from "bundle" to "menu"
2. In Info.plist entries/Basic Information, set Identifier to something like "com.MyCompany.SampleMenu"
3. In Info.plist entries/Cocoa Specific, set the Principal class to "SampleMenuExtra".

We are done with project settings. Now click the "Files" tab. Add the "SystemUIPlugin.framework" either by drag-n-dropping it from Finder or via "Project/Add FrameWorks..." menu. Then remove the "main.c" file from the project. Now copy the "SystemUIPlugin.h" file from your home folder to the project folder and add it to Classes group.

// Creating source files

Our project will have two classes.

Create the new class from the "Objective-C class" template. Name it "SampleMenuExtra". In the header import the "SystemUIPlugin.h" and make our class a subclass of NSMenuExtra. Add the @class SampleMenuExtraView; forward declaration. We will add only two instance variable to our class:
NSMenu *theMenu;
SampleMenuExtraView *theView;

In the .m file import two interfaces - SampleMenuExtra.h and SampleMenuExtraView.h (we will make it later). We will implement three methods here.

- (id)initWithBundle:(NSBundle *)bundle
{
    self = [super initWithBundle:bundle];
    if( self == nil )
        return nil;
        
    // we will create and set the MenuExtraView
    theView = [[SampleMenuExtraView alloc] initWithFrame:
        [[self view] frame] menuExtra:self];
    [self setView:theView];
    
    // prepare "dummy" menu, without any actions
    theMenu = [[NSMenu alloc] initWithTitle: @""];
    [theMenu setAutoenablesItems: NO];
    [theMenu addItemWithTitle: @"1" action: nil keyEquivalent: @""];
    [theMenu addItemWithTitle: @"2" action: nil keyEquivalent: @""];
    [theMenu addItemWithTitle: @"3" action: nil keyEquivalent: @""];

    return self;
}

- (void)dealloc
{
    [theMenu release];
    [theView release];
    [super dealloc];
}

Finally, menu is just an accessor called by system when our menu need to be drawn.

- (NSMenu *)menu
{
    return theMenu;
}

Now create another class, SampleMenuExtraView, using the Objective-C class template. In the header add #import "SystemUIPlugin.h". Make the class a subclass of NSMenuExtraView.

In the source file, we will implement a single method. This method will be called when our menu extra has to draw its "title picture". We will not make something that is very complex and will just draw a circle that is sligtly smaller then the rect itself.

- (void)drawRect:(NSRect)rect
{
    [[NSColor purpleColor] set];
    NSRect smallerRect = NSInsetRect( rect, 4.0, 4.0 );
    [[NSBezierPath bezierPathWithOvalInRect: smallerRect] fill];
}

Thats all of the class implementation!

Build the project. You will get a link warning that can be ignored. Now go to your build folder. You will see the "Sample.menu" bundle in it. Double-click it and enjoy.

// Removing MenuExtra

You can simply Command-drag the menu extra away from the menu bar. Then you have done it, the SystemUIServer still keep the cached information about the menuextra though. So if you change and recompile it, it will load the old version. Also, you would not be able to put the menuesxtra into the Trash and empty it because file is busy. You will need to stop the SystemUIServer with the terminal killall SystemUIServer command. This command will kill the process and MacOS X will automaticaly relaunch the SystemUIServer but without your menuextra. If you are doing some code editing/recompilation, remember to kill SystemUIServer before you run a changed menuextra.

// Where to go next?

The example above is very basic. It only demonstrates a "minimal" menu extra. What you would like to do is assign a target and action to menu command. Also, it is worth to load two images (general and "menu down") at the menuextra initialization and use them to draw in the SampleMenuView draw method. Use isMenuDown to check if user pressed the mouse in our menu.

Finally, study the already mentioned menu extras and check what they do.