TweetFollow Us on Twitter

Sprocket Menus 1
Volume Number:11
Issue Number:5
Column Tag:Getting Started

Sprocket Menus, Part 1

By Dave Mark, MacTech Magazine Regular Contributing Author

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

My February ’93 Getting Started column featured a program called MenuMaster. MenuMaster constructed a menu bar consisting of four menus: The traditional Apple, File, and Edit menus, as well as a special Options menu (Figure 1). Selecting the first item changes it from Change My Name to Change Me Back Again. Selecting the first item again changes it back to Change My Name.

Selecting Disable Me disables the second item and enables the third item. If you then select the newly enabled Enable Previous Item, it gets disabled and Disable Me is reenabled.

If you select Add Extra Menu, a new menu is inserted in the menu bar and Add Extra Menu is disabled. The new menu, titled Extra Menu, features a single item, Delete Me. Selecting Delete Me deletes the extra menu from the menu bar and reenables Add Extra Menu.

Finally, selecting Append Item adds an extra item (Can’t Delete Me...) to the end of the menu. As its names implies, there’s no way to delete this extra item.

Fig. 1. MenuMaster’s Options menu.

A Sprocket Version of MenuMaster

This month we’re going to use Sprocket to implement most of MenuMaster’s functionality. We’ll skip the ability to append an item to the end of a menu for two reasons. First, appending a single item to the end of a menu just isn’t done that often and isn’t particularly useful. More importantly (and probably for the same reason), Sprocket doesn’t give you an easy way to append a new item to a menu.

If you come up with a good reason to add this functionality to Sprocket (or if you have any comments or bugs to report), send e-mail to sprocket@hax.com.

As I mentioned last month, Sprocket based its menu-handling model on that used by OpenDoc. At the heart of this model is a replacement for the MENU resource type. A CMNU resource is just like a MENU resource, with one important addition. Each menu item features a command number. You’ll use this command number to refer to the item, instead of the more traditional method of specifying the menu the item belongs to, along with the item’s position in the menu (e.g., menu 129, item 4).

Figure 2. The CMNU resource, featuring a Cmd-Num field for each menu item.

Check out the ResEdit snapshot in Figure 2. It shows the CMNU resource that represents our new Options menu. The first menu item, Change My Name, is selected. The command number for this item is 1000. When the user selects this item, Sprocket will pass the associated command number (in this case, 1000) as a parameter to the routine HandleMenuCommand() (it’s in the file SprocketStarter.cp). Instead of creating a separate item dispatch routine for each menu (HandleAppleMenu(), HandleFileMenu(), etc.), you’ll create a single switch statement containing cases for all your commands.

Sprocket automatically creates a menu bar at application startup. In C++ terms, Sprocket constructs a TMenuBar object, which is implemented in the files TMenuBar.cp and TMenuBar.h. Here’s the TMenuBar class definition:

class TMenuBar
 {
public:
Resource ('MBAR' and 'CMNU') Utilities
 
 OSErr  GetNewMenuBar(short whichMBAR);
 MenuRefGetMenuFromCMNU(short whichMenu);
Menu command mapping functions

 MenuCommandID   GetCommand(MenuID menu, MenuItemID item);
 void   GetMenuAndItem(MenuCommandID commandNum, 
 MenuID * returnedMenu, MenuItemID * returnedItem);
 OSErr  RegisterCommand(  MenuCommandID commandNum, 
   MenuID menu, MenuItemID item);
 OSErr  UnregisterCommand(MenuCommandID commandNum);
Menu enable/disable routines for menu items

 void   EnableCommand(MenuCommandID commandNum, 
 Boolean enable);
 void   EnableAndCheckCommand(MenuCommandID commandNum, 
 Boolean enable, Boolean check);
 void   GetItemString(MenuCommandID commandNum,
 StringPtr itemString);
 void   SetItemString(MenuCommandID commandNum,
 StringPtr itemString);
helpful utility functions
 void   HideMenuBar();
 void   ShowMenuBar();
 void   RedrawIfNeeded();
 void   Invalidate();
 void   Validate();

private:
"globals"
 static Boolean  fgMenuBarNeedsRedraw;
 static Boolean  fgMenuBarHidden;
mapping tables
 TMenuCommandTable fCommandTable;
 TMenuItemTable  fMenuItemTable;
internal methods
 MenuHandle GetMenuHandleAndItemFromCommand(
 MenuCommandID commandNum, 
 MenuID *menu,MenuItemID *item);
 };

The first member function, GetNewMenuBar() uses the specified MBAR resource to build a new menu bar. Though this version of Sprocket only creates a single menu bar, this might not be the case in the future. For now, a pointer to the menu bar object is stored in the global gMenuBar. Take a minute to open up the file SprocketMain.cp and check out the code around line 363. This is where Sprocket creates the TMenuBar object based on the MBAR resource in SprocketStarter.rsrc.

The member function GetMenuFromCMNU() loads a CMNU resource and walks through it, one item at a time. It builds a traditional menu structure, passing each item’s command number to the RegisterCommand() member function, which adds the command to Sprocket’s menu command table. If you are going to take advantage of Sprocket’s menu command mechanism, you must register your menu item commands. If you base your menus on a CMNU resource, GetMenuFromCMNU() will register your menu items automatically. If the menus in your MBAR resource correspond to a CMNU resource, Sprocket will register the menu items automatically.

If you don’t want to use a CMNU resource, you can still add and delete your menus to and from the global menu bar yourself. For example, since a font or size menu will have a dynamic number of items, the CMNU resource just doesn’t make sense. We’ll look at that process in a future column.

The member function GetCommand() takes a menu and item ID and returns the associated command. GetMenuAndItem() takes a command and returns the associated menu and item ID.

If you want to delete a menu whose commands have been registered, you can use the UnregisterCommand() member function to, one-at-a-time, unregister the commands in that menu. Otherwise, you’ll orphan commands in the command table.

EnableCommand() and EnableAndCheckCommand() let you enable, disable, check, and uncheck a menu command. GetItemString() and SetItemString() allow you to retrieve and set an items name using its command.

HideMenuBar() and ShowMenuBar() let you hide and show the menu bar (what a concept!). Invalidate() marks the menu bar as needing to be redrawn. Validate() sets the menu bar as up to date. RedrawIfNeeded() redraws the menu bar if the invalid flag has been set. Note that RedrawIfNeeded() is called in Sprocket’s main event loop, so there’s no need for you to call it yourself.

This Month’s Resources

Sprocket gets its resources from four different resource files. CreditsBox.rsrc contains the resources used to build the Sprocket about box. StandardMenus.rsrc contains some standard MENU and CMNU resources. If you want to change any of these menus, copy the appropriate resource from StandardMenus.rsrc into SprocketStarter.rsrc and delete the original from StandardMenus.rsrc. Modify the version you copied into SprocketStarter.rsrc.

Sprocket.rsrc contains various resources used by Sprocket and should not be modified. SprocketStarter.rsrc is your resource center. Put all the resources you add to Sprocket there.

You’ll need to modify one resource and add three new ones to SprocketStarter.rsrc. First, open up MBAR 128 and add menu ID 1000 to the list already in place.

If you’re not using Projector (the sourced code control system), you might want to delete the ckid resources you’ll find in each of the resource files. That will get rid of the annoying link error complaining about the multiply-defined resource.

Next, you’ll create your three CMNU resources. The first represents the Options menu we want to add to the end of the menu bar. In general, when you add a new resource to Sprocket, you’ll start numbering your resources from 1000, instead of at 128 the way you normally would. This is just a convention, and might change as Sprocket grows up.

When you create CMNU 1000, be sure to change the resource ID in both places: once in the “Get Info” box and also in the “Edit Menu and MDEF ID” dialog.

Figure 3. CMNU 1000

Enter a command number of 1000 for the item Change My Name, 1001 for Disable Me, 1002 for Enable Previous Item, 1003 for Add Extra Menu, and 1004 for Beeps. Next, disable the item Enable Previous Item. After that, click on the Beeps item, check the has SubMenu checkbox and enter 100 as the submenu ID (Figure 4). Since submenu IDs are limited to a single byte, we won’t be able to give the submenu CMNU resource an ID greater than 1000. So much for sticking to conventions!

Figure 4. The Beeps item, with its submenu ID of 100 entered.

Next, create a new CMNU resource with an ID of 1001 (Once again, be sure to change the ID in both places). The menu will have a title of Extra Menu and a single item, Delete This Menu. Give the item Delete This Menu a command of 1007 (Figure 5).

Figure 5. CMNU 1001

Finally, create a CMNU resource with an ID of 100. Add two items, Beep Once with a command ID of 1005 and Beep Twice with a command ID of 1006 (Figure 6).

Figure 6. CMNU 100.

Save your changes and quit your resource editor.

Modifying the Source Code

Now launch CodeWarrior or Symantec C++ and edit SprocketStarter.h. Start by adding this global reference to the file:

extern Boolean   gItemNameChanged;

gItemNameChanged is a Boolean that indicates whether the item Change My Name has been selected. It tells us whether the item should read Change My Name or Change Me Back Again.

Next, add this enum to the file:

enum
{
 mSubMenu = 100,
 mExtraMenu = 1001,
 
 cChangeName= 1000,
 cDisableMe = 1001,
 cEnablePrevious = 1002,
 cAddExtraMenu   = 1003,
 cBeeps = 1004,
 cBeepOnce= 1005,
 cBeepTwice = 1006,
 cDeleteExtraMenu= 1007
};

The first two constants specify the two CMNU resource IDs. The next 8 specify the menu command IDs. Notice that the menu constants start with a lower case “m” and the commands start with a lower case “c”. Unfortunately, the Apple event registry starts all its class names with a lower-case “c”, so be on the lookout for name collisions.

Next, add these three constants to the file:

const StringPtr kUnchangedName = "\pChange My Name";
const StringPtr kChangedName = "\pChange Me Back Again";
const short kLastMenu = 0;

The first two are just Pascal strings we used for the menu names. We really should have implemented these strings as ‘STR ’ resources to make the code easier to localize. In general, I try never to specify strings in code, but I guess I was just feeling a bit lazy.

The last constant will be used in our call of InsertMenu(), telling InsertMenu() to insert the menu at the end of the menu bar.

Next, edit the file SprocketStarter.cp. Start by adding this global definition at the top of the file:

Boolean gItemNameChanged = false;

Next, add these three lines to the beginning of the routine SetUpApplication():

MenuRef hierMenu;

hierMenu = gMenuBar->GetMenuFromCMNU( mSubMenu );
InsertMenu( hierMenu, -1 ); 

GetMenuFromCMNU() loads CMNU 100, registers all the commands, and returns a MenuHandle to a standard menu based on the CMNU resource. InsertMenu() inserts the resulting menu in the menu bar.

Finally, add the cases to handle our new commands to the switch in HandleMenuCommand() further down in SprocketStarter.cp. Here’s my edited copy of HandleMenuCommand():

HandleMenuCommand
void
HandleMenuCommand(MenuCommandID theCommand)
 {
 MenuRefextraMenu;
 OSErr  err;
 
 switch (theCommand)
 {
 case cAbout:
 AboutBox();
 break;
 
 case cNew:
 CreateNewDocument();
 break;
 
 case cOpen:
 OpenExistingDocument();
 break;
 
 case cPreferences:
 TPreferencesDialogWindow * prefsDialog = 
 new TPreferencesDialogWindow;
 break;
 
#ifqAOCEAware
 case cNewMailableWindow:
 TMailableDocWindow *aWackyThing = new TMailableDocWindow;
 break;
#endif

Here come the new commands. This first one switches the first menu item between Change My Name and Change Me Back Again. Notice that we’re using the global TMenuBar object to change the menus. If Sprocket ever gets modified to use more than one menu bar, we’ll have to modify this code to be sure we use the menu bar that contains the menu we want to work with. Of course, if that happens, you can count on some sample code in this column to show you how to do that.

 case cChangeName:
 if ( gItemNameChanged )
 gMenuBar->SetItemString( cChangeName, kUnchangedName );
 else
 gMenuBar->SetItemString( cChangeName, kChangedName );
 gItemNameChanged = ! gItemNameChanged;
 break;

This command disables Disable Me and enables Enable Previous Item.

 case cDisableMe:
 gMenuBar->EnableCommand( cDisableMe, false );
 gMenuBar->EnableCommand( cEnablePrevious, true );
 break;

This command does just the opposite.

 case cEnablePrevious:
 gMenuBar->EnableCommand( cDisableMe, true );
 gMenuBar->EnableCommand( cEnablePrevious, false );
 break;

This command disables the item that spawned this command in the first place (Add Extra Menu), then builds a new menu from the extra menu CMNU resource. We add the new menu to the end of the menu bar, then call Invalidate() to force the menu bar to get redrawn.

 case cAddExtraMenu:
 gMenuBar->EnableCommand( cAddExtraMenu, false );
 extraMenu = gMenuBar->GetMenuFromCMNU( mExtraMenu );
 InsertMenu( extraMenu, kLastMenu );

 gMenuBar->Invalidate();
 break;

This command deletes the extra menu we added with the previous command. First, we reenable the Add Extra Menu item. Notice that we didn’t have to retrieve the menu that this item belongs to. All we needed was the command. This definitely makes life a lot simpler.

 case cDeleteExtraMenu:
 gMenuBar->EnableCommand( cAddExtraMenu, true );

Since the TMenuBar class doesn’t support a DeleteCMNU() method, we’ll have to deregister the command by hand. A DeleteCMNU() method would step through all the items in the specified menu, calling UnregisterCommand() for each item. It would then delete the menu for us. Since our extra menu only contains a single item, it’s no big deal to do this by hand. Once we are done, we’ll force a menu bar redraw. Look for a DeleteCMNU() method in a future version of Sprocket.

 err = gMenuBar->UnregisterCommand( cDeleteExtraMenu );
 DeleteMenu( mExtraMenu );
 
 gMenuBar->Invalidate();
 break;

This next command corresponds to the parent menu of our hierarchical submenu. Normally, this command will never get called because the menu manager won’t detect a selection of the parent item of a submenu (Figure 7). There are times when this is useful, however. For example, imagine if you built a menu of applications, where each application item had a submenu listing some frequently used documents that can be opened by that application (NowMenus does this). If you select a document from a submenu, its parent application gets launched and opens the selected document. If you release the mouse with the application selected (without selecting a document from the submenu), you might want to launch the application without specifying a document.

The point here is this: Specify commands for all your menu items, even the hierarchical parent menus. A future version of Sprocket might include a workaround to execute commands associated with these currently orphaned items.

 case cBeeps:
 break;

Figure 7. A menu item with its submenu showing.
If the mouse button was released at this point, the Beeps item
(rather than either of the submenu items) would be selected.

These next two items are horribly technical. They beep either once or twice, depending on the item selected.

 case cBeepOnce:
 SysBeep( 20 );
 break;
 case cBeepTwice:
 SysBeep( 20 ); SysBeep( 20 );
 break;
 default:
 break;
 }
 }

Till Next Month

There are still some concepts that we need to get into regarding Sprocket and menus. For example, when do you make the decision about which menu items you will enable and disable to ensure that things are set up correctly before a user makes a selection from a menu. How should the frontmost window affect which menu items are enabled or disabled? We’ll explore these important issues in next month’s column. See you then!

 
AAPL
$531.70
Apple Inc.
+0.53
MSFT
$39.99
Microsoft Corpora
+0.05
GOOG
$534.81
Google Inc.
+6.19

MacTech Search:
Community Search:

Software Updates via MacUpdate

TeamViewer 9.0.28116 - Establish remote...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds, or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for... Read more
Viber 4.1.0 - Send messages and make cal...
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,... Read more
Apple iOS 7.1.1 - The latest version of...
The latest version of iOS can be downloaded through iTunes. Apple iOS 7 brings an all-new design and all-new features. Simplicity Simplicity is often equated with minimalism. Yet true simplicity is... Read more
1Password 4.3 - Powerful password manage...
1Password is a password manager that uniquely brings you both security and convenience. It is the only program that provides anti-phishing protection and goes beyond password management by adding Web... Read more
Lens Blur 1.3.0 - True out-of-focus boke...
Let Lens Blur transform your existing photo into true SLR-quality out-of-focus bokeh effect! Everyone needs a gorgeous personalized background for a social profile, blog, Web/UI design, presentation... Read more
VMware Fusion 6.0.3 - Run Windows apps a...
VMware Fusion allows you to create a Virtual Machine on your Mac and run Windows (including Windows 8.1) and Windows software on your Mac. Run your favorite Windows applications alongside Mac... Read more
Tweetbot 1.5.1 - Popular iOS twitter cli...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
Mac DVDRipper Pro 4.1.7 - Copy, backup,...
Mac DVDRipper Pro is the DVD backup solution that lets you protect your DVDs from scratches, save your batteries by reading your movies from your hard disk, manage your collection with just a few... Read more
PDFpenPro 6.2 - Advanced PDF toolkit for...
PDFpenPro allows users to edit PDF's easily. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Create... Read more
PDFpen 6.2 - Edit and annotate PDFs with...
PDFpen allows users to easily edit PDF's. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Features... Read more

Latest Forum Discussions

See All

Zeebox is Now Beamly TV – Still Offers t...
Zeebox is Now Beamly TV – Still Offers the Same Social Networking TV Fun, Plus a New Look Posted by Rob Rich on April 22nd, 2014 [ permalink ] | Read more »
Bandai Namco Unveils Upcoming Slate of M...
At their recent Global Gamers’ Day event, Bandai Namco was largely focused on their console and PC offerings for the upcoming year. However mobile still had a small presence, with some upcoming titles revealed by the company – though few were in a... | Read more »
The Story Behind Grammar Girl’s Grammar...
Learning is so much more rewarding when it’s also fun. That’s part of the reason why recent educational app, Grammar Pop HD, garnered such a positive review from us last week. The brainchild of Mignon Fogarty, otherwise known as Grammar Girl, we... | Read more »
Pinnacle Studio for iPhone Review
Pinnacle Studio for iPhone Review By Jennifer Allen on April 22nd, 2014 Our Rating: :: SIMPLY POWERFULiPhone App - Designed for the iPhone, compatible with the iPad Video editing while on the move has never been so convenient.   | Read more »
Taste Savant Review
Taste Savant Review By Jennifer Allen on April 22nd, 2014 Our Rating: :: TASTY RECOMMENDATIONSiPhone App - Designed for the iPhone, compatible with the iPad In need of some new restaurant recommendations? This app will be ideal,... | Read more »
Where’s My Water? Featuring XYY Adds Mor...
Where’s My Water? Featuring XYY Adds More Than Just Sheep to the Liquid Physics Puzzler Posted by Rob Rich on April 22nd, 2014 [ permalink ] | Read more »
FarmVille 2: Country Escape Review
FarmVille 2: Country Escape Review By Jennifer Allen on April 22nd, 2014 Our Rating: :: STEADY FARMINGUniversal App - Designed for iPhone and iPad FarmVille is bigger and brighter than ever before, but don’t expect it to sway you... | Read more »
Doctor Who: Legacy receives big update,...
Doctor Who: Legacy receives big update, adds Perk System and more Posted by Tre Lawrence on April 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Strongarm Universal Mount Hardware Revie...
Made by: Viatek Price: $14.99 for 2 Hardware/iOS Integration Rating: 3.5 out of 5 stars Usability Rating: 4 out of 5 stars Reuse Value Rating: 3.75 out of 5 stars Build Quality Rating: 3.5 out of 5 stars Overall Rating: 3.69 out of 5 stars | Read more »
Boxer Review
Boxer Review By Campbell Bird on April 21st, 2014 Our Rating: :: KO YOUR INBOXUniversal App - Designed for iPhone and iPad Turn your inbox into a task list or tune it to your own needs with this highly customizable, user friendly... | Read more »

Price Scanner via MacPrices.net

Updated iPad Price Trackers
We’ve updated our iPad Price Tracker and our iPad mini Price Tracker with the latest information on prices and availability from Apple and other resellers. Using a mobile device? We’ve also updated... Read more
Everything You Wanted To Know And Probably Mo...
Macworld UK’s Lou Hattersley takes a look inside Apple’s A7 System On Chip (SoC) , noting that its processor module is much more powerful than other smartphone chipsets. He notes that the A7 was a... Read more
Mavericks Now Runs Half Of Internet Connected...
Computerworld’s Greg Keizer reports that half of all Macs that went online in March were running OS X Mavericks with Version 10.9 accounting for the largest adoption percentage of any individual OS X... Read more
WinZip Mac 3 Simplifies Cloud Sharing And Pri...
WinZip has announced WinZip Mac 3, a new file sharing app that makes it simple to manage, protect and share files across email and the cloud. With direct support for Dropbox and Google Drive,... Read more
2.5GHz Mac mini, Apple refurbished, available...
The Apple Store has Apple Certified Refurbished 2.5GHz Mac minis available for $509, $90 off MSRP. Apple’s one-year warranty is included, and shipping is free. Read more
13-inch MacBook Pro, Apple refurbished, avail...
The Apple Store continues to offer Apple Certified Refurbished 13″ 2.5GHz MacBook Pros (4GB RAM/500GB HD) for $999 which is $200 off MSRP. Apple’s one-year warranty is included, and shipping is free. Read more
15-inch MacBook Pros (refurbished) available...
The Apple Store has Apple Certified Refurbished October 2013 15″ Retina MacBook Pros available starting at $1699, with models up to $400 off MSRP. Apple’s one-year warranty is standard, and shipping... Read more
$100 off cellular iPad minis plus free $20 gi...
Best Buy is discounting cellular iPad minis with Retina Displays by $100 on their online store for a limited time. They’ll also throw in a free $20 Best Buy gift card. Choose free shipping or free... Read more
Updated Price Trackers
We’ve updated our Mac Price Trackers with the latest information on prices, bundles, and availability on systems from Apple’s authorized internet/catalog resellers: - 15″ MacBook Pros - 13″ MacBook... Read more
Apple refurbished MacBook Airs available for...
The Apple Store has Apple Certified Refurbished 2013 MacBook Airs available for up to $200 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is free... Read more

Jobs Board

*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
*Apple* Inc. Research Data Specialist - Appl...
…of Worldwide Market Research & Intelligence. The team is responsible for conducting Apple branded consumer market research. It is also responsible for analyzing data Read more
*Apple* Automotive Parts Department position...
Apple Automotive is one of the fastest growing dealer…and it shows. Consider making the switch to the Apple Automotive Group today! At Apple Automotive, we Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.