TweetFollow Us on Twitter

Enhancing Your Application with NSStatusItem

Volume Number: 24 (2008)
Issue Number: 07
Column Tag: Application Development

Enhancing Your Application with NSStatusItem

How to utilize the NSStatusItem API to add functionalitys

by Marcus S. Zarra

Introduction

The user interface is arguably the hardest part of any application. This is especially true on OS X because we, as users, demand more of the developers of our applications. If the developer adds too many features and UI elements, then the application feels too busy or complicated. However if too few features are added then application is too primitive or simple.

Fortunately there are some choices. An application that would be considered too simple for the Dock might be perfect on the Dashboard or on the Menu Bar. Likewise, an application that is too busy to be a Dashboard widget might very well be perfectly at home in the Dock. But what if you are in the grey area between the Dock and the Menu Bar? While the design choices between these options ischoices between these options are beyond the scope of this article, I will present how to add a Menu Bar item – also known as a menu extra, menu item or menulet – to to your application and how to control it.

Menu Bar Items: Two Different Beasts

There are two different kinds of objects that can be placed on the menu bar in the upper right corner. First there is the kind that only Apple is allowedallows. The API is private and at the time of this article, third party developers are discouraged from using them.

The second kind that developers are encouraged to use is the NSStatusItem API. The NSStatusItem behaves decidedly different than the internal API that Apple uses. First, NSStatusItem objects cannot be dragged around the menu bar; second they cannot be removed from the menu bar with the mouse; and lastly, they are more "sluggish" than the Apple internal items when another item on the bar is moved or removed.

However, they are still an extremely useful UI element that can be utilized to great effect. The basic concept behind them is that they are a menu with an icon. In that respect, their behavior is very similar to NSMenuItem objects.

Building an NSStatusItem

While it is possible to build an NSStatusItem 100% in code, I prefer to use Interface Builder wherever whenever possible. This makes localizations easier and reduces the amount of code I need to maintain. Therefore, the first step to building an NSStatusItem is to build its menu in Interface Builder.

Building the Menu

To add a new menu to the project, I open the MainMenu.xib file and drag in a new NSMenu object (See Image 1). I normally rename the new menu to "Status Menu" or something similar to keep it clear which menu is which.


Image 1: Drag a new NSMenu into the nib

When an NSMenu is first added it contains three menu items. These items can be added to, removed from and changed as needed. For this example, I have changed the menu so that it has four items: Status, a separator, About and Quit. When I am done the menu looks like Image 2.


Image 2: The finished menu in IB

Now that the menu itself is complete it is time to write some code. For this example, the AppDelegate of my project will be responsible for the NSStatusItem. First, the header:

AppDelegate.h
#import <Cocoa/Cocoa.h>
@interface AppDelegate : NSObject {
   NSStatusItem *myStatusItem;
   IBOutlet NSMenu *myStatusMenu;
   IBOutlet NSMenuItem *myMenuStatusItem;
}
@end

Since both the about menu item and the quit menu item can be handled outside of the AppDelegate in this example, I have not added IBAction methods for them. Once the header has been written, it is time to go back to Interface Builder and link the references as shown in Image 3.

As for the About and Quit menus, they are linked to the Application object as follows:

About -> NSApplication -orderFrontStandardAboutPanel:
Quit -> NSApplication -terminate:

Once all of the linking is complete, I am done withwith the work with Interface Builder is complete;. tTime to move on to the AppDelegate. In this situation I prefer to initialize the NSStatusItem in the applicationDidFinishLaunching: method so that it appears as soon as the application is ready to start receiving events. Depending on an applications particular situation the initialization code can be placed in other locations.

AppDelegate.m
#import "AppDelegate.h"
@implementation AppDelegate
- (void)applicationDidFinishLaunching:(NSNotification*)notification
{
   myStatusItem = [[[NSStatusBar systemStatusBar] statusItemWithLength:NSSquareStatusItemLength] retain];
   
   NSImage *statusImage = [NSImage imageNamed:@"TheZ.tiff"];
   [myStatusItem setImage:statusImage];
   [myStatusItem setHighlightMode:YES];
   
   [myStatusItem setMenu:myStatusMenu];
   
   [myMenuStatusItem setTitle:NSLocalizedString(@"Special Status", @"status menu item text")];
}
@end

The first thing to notice in this code block is that NSStatusItem objects are not initialized directly. Rather, they are requested from an NSStatusBar object. The NSStatusBar object has a class level method that returns the system status bar from which I one can request a NSStatusItem.

Once I have my newthe NSStatusItem request is complete, it is possibleI am able to set its image, highlight mode and menu. The image is the image that is displayed on the Menu Bar and is has a 16x16 resolutionimage. The highlight mode determines whether or not the image is highlighted when clicked. The default is "NO", which is not appropriate when a menu is attached so I have set it to YES in the sample code. The last call to myStatusItem passes it the menu that isI constructed and referenced in Interface Builder. This will be the menu that the NSStatusItem displays when it is clicked.

The last line of the applicationDidFinishLaunching: method is a call to the status menu item that isI referenced from Interface Builder. This call changes the text of that menu item. Note that the sample code doesI have not disabled this menu. Since it does not have a target or action it will be displayed grayed out already so there is no need to disable it.

Controlling The Menu

In various situations it is appropriate to make changes to the NSStatusItem or one of its menu items. In this example, I have intentionally linked the *myStatusMenuItem ivar to one of the NSMenuItem objects on the menu so that it can be changed during the life of the program. To illustrate this change, I added a button to the main window that when clicked would change this menu item:


Image 3: Linking the AppDelegate to the Menu

AppDelegate.h
-(IBAction)changeMenu:(id)sender;
AppDelegate.m
-(IBAction)changeMenu:(id)sender;
{
  [myMenuStatusItem setTitle:NSLocalizedString(@"Changed Status", @"statuc menu item changed text")];
}

With this addition to the application, the status menu item will change to "Changed Status".

It is also possible to change the image that is displayed on the Menu Bar

AppDelegate.h
-(IBAction)purpleZ:(id)sender;
-(IBAction)blackZ:(id)sender;
AppDelegate.m
-(IBAction)purpleZ:(id)sender;
{
   [myStatusItem setImage:[NSImage imageNamed:@"ThePurpleZ.tiff"]];
}
-(IBAction)blackZ:(id)sender;
{
   [myStatusItem setImage:[NSImage imageNamed:@"TheZ.tiff"]];
}

In the example application, I added these actions are added to the Format menu rather than buttons on the main window.

Lastly, if it is desired to have the NSStatusItem as an option rather than a requirement in the application, it is possible to remove the menu item from the bar:

AppDelegate.h
-(IBAction)removeStatusItem:(id)sender;
-(IBAction)addStatusItem:(id)sender;
AppDelegate.m
-(IBAction)removeStatusItem:(id)sender;
{
   [[NSStatusBar systemStatusBar] removeStatusItem:myStatusItem];
   myStatusItem = nil;
}
-(IBAction)addStatusItem:(id)sender;
{
   if (myStatusItem) return;
   myStatusItem = [[[NSStatusBar systemStatusBar] statusItemWithLength:NSVariableStatusItemLength] retain];
   
   [myStatusItem setImage:[NSImage imageNamed:@"TheZ.tiff"]];
   [myStatusItem setHighlightMode:YES];
   [myStatusItem setMenu:myStatusMenu];
   
   [myMenuStatusItem setTitle:NSLocalizedString(@"Special Status", @"status menu item text")];
}
-(BOOL)validateMenuItem:(NSMenuItem*)item
{
   if ([item action] == @selector(removeStatusItem:)) {
      return (myStatusItem != nil);
   }
   if ([item action] == @selector(addStatusItem:)) {
      return (myStatusItem == nil);
   }
   return YES;
}

The code to remove the status item is very simple. Just one call to NSStatusBar -removeStatusItem: and it is gone. Since there is no way to add the existing item back to the bar it is prudent to set the ivar to nil at this time.

To add the NSStatusItem back to the bar, the example I simply copiesd the code from the applicationDidFinishLaunching: method. Ideally this should be abstracted so that the code is not duplicated.

Lastly, I addedthere is a -validateMenuItem: method to make sure that only one status item is ever added and just as importantly, that the application is not trying to remove a non-existent item I do not try to remove a non-existent item.

Now, with the addition of a checkbox in the preferences linked to NSUserDefaults, it is trivial to add a user preference on whether or not to show the status item. OneI could then add logic to the applicationDidFinishLaunching: method to decide whether or not a NSStatusItem needs to be initialized based on the NSUserDefault.

Conclusion

That is all there is to the NSStatusItem API. Hopefully, one day, Apple will allow third party developers to utilize their internal status items so that we can legitimately produce menu bar items that are feature comparable to the system items. Until then, NSStatusItem is a solid API that we can utilize.

As a parting comment, if I wanted my entire application to run as a menu bar item (without a Dock icon ala Twitterific), that only requires one small addition to the Info.plist:

Info.plist
<key>LSUIElement</key>
<string>1</string>

And the application will not bounce in the dock at all. I do not recommend that for this example application as it is not designed to run in that manner but there are plenty of applications that this is perfectly suited for.

NOTE: This change cannot be made to an application on the fly. So if you wanted to make the Dock icon optional also it would require an application restart and probably some trickery with the Finder as the Finder does tend to "cache" the Info.plist file for applications.


Marcus S. Zarra is the owner of Zarra Studios, based out of Colorado Springs, Colorado. He has been developing Cocoa software since 2003, Java software since 1996, and has been in the industry since 1985. Currently Marcus is producing software for OS X. In addition to writing software, he assists other developers by blogging about development and supplying code samples.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

OmniOutliner Pro 5.8.5 - Pro version of...
OmniOutliner Pro is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually designed to help you think. It's... Read more
OmniOutliner Essentials 5.8.5 - Organize...
OmniOutliner Essentials (was OmniOutliner) is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually... Read more
Quicken 6.3.0 - Complete personal financ...
Quicken makes managing your money easier than ever. Whether paying bills, upgrading from Windows, enjoying more reliable downloads, or getting expert product help, Quicken's new and improved features... Read more
Viber 15.8.0 - Send messages and make fr...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
Butler 4.4.2 - Hot key, menu, and keywor...
Butler makes it easier for you to perform a wide variety of potentially recurring tasks. Just arrange these tasks in Butler's fully customizable configuration and assign one or more triggers to a... Read more
GIMP 2.10.24 - Powerful, free image edit...
GIMP is a multi-platform photo manipulation tool. GIMP is an acronym for GNU Image Manipulation Program. The GIMP is suitable for a variety of image manipulation tasks, including photo retouching,... Read more
ScreenFlow 10.0.3 - Create screen record...
ScreenFlow is powerful, easy-to-use screencasting software for the Mac. With ScreenFlow you can record the contents of your entire monitor while also capturing your video camera, microphone and your... Read more
Notability 10.4.5 - Note-taking and anno...
Notability is a powerful note-taker to annotate documents, sketch ideas, record lectures, take notes and more. It combines, typing, handwriting, audio recording, and photos so you can create notes... Read more
Day One 6.7 - Maintain a daily journal.
Day One is an easy, great-looking way to use a journal / diary / text-logging application. Day One is well designed and extremely focused to encourage you to write more through quick Menu Bar entry,... Read more
Vallum 4.0.3 - $15.00
Vallum is a little tool that helps you monitor and block apps connections and throttle apps bandwidth. It is able to intercept connections at the application layer, and hold them while you decide... Read more

Latest Forum Discussions

See All

The 5 Best Mobile Stealth Action Games
Action games are a hard sell on mobile, and they get even harder if the more precision they require. Stealth games are one such subgenre that just doesn’t feel like it could work well on small touchscreens where you’re prone to being distracted or... | Read more »
Exos Heroes' latest update introduc...
LINE Games has announced that several pieces of content in their popular RPG, Exos Heroes, have received changes to celebrate the summer season. There is also a new story event to tackle called Memorial Saga that follows Ramge, the Prince of North... | Read more »
Infinity Island is a cutesy idle game fr...
Infinity Island is a brand new idle game from Luca Redwood that is available now for iOS and Android. You might be familiar with Redwood from their previous games, 10000000, You Must Build A Boat and Photographs. [Read more] | Read more »
Infinite Galaxy is a deep sci-fi strateg...
The collapse of the Empire is nigh. In its wake, remnants of the epic intergalactic struggle float through the debris in space, as lawless pirates sow seeds of discord and loyalist groups strike terror into the hearts of innocent civilians. In the... | Read more »
Injustice 2 Mobile's latest update...
Warner Bros Games and NetherRealm Studios have released a major update for their fighting game, Injustice Mobile 2. It sees the arrival of a brand new character, Vixen, to the game alongside changes to the existing progression system. [Read more] | Read more »
Pokemon Go's August events have bee...
Following Pokemon Go Fest 2021, it's time to look ahead to August and the events that will take place in Niantic's AR game throughout the month. There's a new Research Breakthrough encounter, 1 PokeCoin bundles and a bunch more. [Read more] | Read more »
Overboard!, Inkle's reverse whodunn...
Inkle's fresh approach on the whodunnit mystery genre, Overboard! is now available for Android devices followings its release on iOS. The game has received predominately positive reviews since it launched. It holds a healthy Metacritic score... | Read more »
There's never been a better time to...
We were obviously big fans of Genshin Impact when it launched last year, so much so that it grabbed our Game of the Year award. Since that time, though, the game (and our enthusiasm fo it) had gone somewhat quiet. [Read more] | Read more »
Homeworld Mobile's first regional b...
Since the initial announcement all the way back in 2019, we've not heard an awful lot about Homeworld Mobile. But now, there appears to be some movement as the game's first regional beta test is now live. [Read more] | Read more »
Masketeers: Idle Has Fallen's impen...
Appxplore has announced that their popular RPG Masketeers: Idle Has Fallen will soon receive a major update that introduces a Guild system alongside another feature called Sigils. The developers hope this will add more excitement to the game by... | Read more »

Price Scanner via MacPrices.net

Verizon offers $200 discount on new Apple M1...
Verizon will take up to $200 off the price of an M1-powered Cellular iPad Pro with select trade-in and monthly payment plan (24 months). The fine print: “Less $100 promo credit applied to account... Read more
Record low prices on Apple’s 13″ M1 MacBook A...
Amazon is offering a $150 discount on Apple’s 13″ M1 MacBook Airs with 7-Core GPUs and 8-Core CPU. With Amazon’s discount, their price drops to only $849 with free shipping. Their prices are the... Read more
Save up to $140 on an M1 Mac mini at Apple wi...
Apple has a full line of standard configuration M1 Mac minis available in their Certified Refurbished section starting at only $589 and up to $140 off MSRP. Each mini comes with Apple’s one-year... Read more
Here are the details of Apple’s sales tax hol...
Apple is participating in the 2021 sales tax holiday again this year. In certain states on certain days customers are eligible to save on the sales tax for items purchased on Apple’s online store.... Read more
Apple has 13″ M1 MacBook Pros available for $...
Apple has a full line of 2020 13″ M1 MacBook Pros available Certified Refurbished, starting at only $1099 and up to $230 off original MSRP. These are the cheapest M1 MacBook Pros for sale today at... Read more
Our exclusive Apple Price Trackers help you f...
Our Apple award-winning price trackers are the best place to look for the lowest prices and latest sales on all the latest Apple gear. Scan our price trackers for the latest information on sales,... Read more
The best deal on 13″ M1 MacBook Airs are thes...
Apple has a full line of 2020 13″ M1 MacBook Airs available, Certified Refurbished, starting at only $849 and up to $190 off original MSRP. These are the cheapest M1 MacBook Airs for sale today at... Read more
Reminder: Take advantage of Apple’s Back to S...
Take advantage of Apple’s Back to School promotion for 2021. As part of this promotion, Apple will include one free pair AirPods (with charging case) with the purchase of a MacBook Air, MacBook Pro,... Read more
Sunday Sale: Amazon is offering record-low pr...
Amazon has Apple’s entire MacBook lineup on sale today for record low prices, with models available starting at $899 and up to $500 off Apple’s MSRP. Shipping is free. These are the same MacBook Pros... Read more
Sunday Sale: Apple Pencil 2 for only $99, sav...
Amazon has the Apple Pencil 2 on sale today for only $99 shipped. Their price is $30 off Apple’s MSRP, and it’s the lowest price available for an Apple Pencil 2 anywhere. For the latest prices and... Read more

Jobs Board

*Apple* Support Specialist - Robert Half Tec...
…organization in Lawrenceville, New Jersey is in need of a highly experienced Apple Support Specialist! The Apple Support Specialist will be responsible for Read more
Geek Squad *Apple* Consultation Professiona...
**818649BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store Number or Department:** 001045-Mountain View-Store Read more
Head of *Apple* Product Development - DISH...
…the potential to power a connected world. What you'll be doing As the Apple Product Development lead, you will make strong contributions to the product and feature Read more
Medical Assistant (CMA, RMA, LPN) - *Apple*...
…Health Fairview has an immediate opening for a Medical Assistant/LPN at the M Health Fairview Apple Valley Clinic located in Apple Valley, MN. This is a 1.0 FTE Read more
Geek Squad *Apple* Consultation Professiona...
**818139BR** **Job Title:** Geek Squad Apple Consultation Professional **Job Category:** Store Associates **Store Number or Department:** 000535-Portsmouth-Store Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.