TweetFollow Us on Twitter

Pin-up Menu
Volume Number:6
Issue Number:6
Column Tag:Pascal Procedures

"PinUpMenu" XCMD

By Steven Fuchs, Coram, NY

Interface the Music

The Problem with the Finder

Excessive Folderfication. How many readers suffer from this graphically oriented computer malady? As our hard drives grow larger we are faced with a delicate balance between maintaining enough folders to satisfy our need for organization, and so many levels of folders that finding a document requires the opening and closing of eight windows. Let’s not even mention a trip to the handy but discouraging “Find File” DA. Don’t get me wrong, I love folders as much as the next guy, but I believe many users would like to have the ability to reach through the folders to ‘grab’ a specific document.

Hypercard “Open Command”

Within the Hypertalk programming environment there exists the “Open ” command . The Open command when used with an application name as its parameter in the form “Open AppName” will launch that application in a manner similar to the Finder. In addition it can be passed a document name as a parameter in the form “Open DocName with AppName” which will cause the application to open to the specified document. This performance parallels the Finder and offers no distinct advantages. The Hypercard advantage lies in its knack for remembering the full pathnames of all documents and applications launched from within it in a “pathname memory”. When launching an application or document from Hypercard only it’s name must be given. Hypercard will search through its “pathname memory” until the correct path is found. If the document is not found Hypercard displays a modal dialog requesting the user’s aid in locating the file. If that search is successful then that pathname is added to the “pathname memory”. This “pathname memory” can be examined by looking at pages 2 through 4 of your Home stack. Here is stored the pathnames of stacks, applications, and documents respectively. If you recognize any folder names that have been changed or deleted, these can be safely removed to save time and disk space.

Introduce Pin-Up Menus

The XCMD to be described this month allows for quick selection from a set of pre-chosen commands, and is accessible from anywhere within Hypercard. The name of the XFCN is “PinUpMenu”, which can be altered by the Hypercard user for his or her own utility. The instance I will use as an example I have dubbed “The Pop-Up Finder”. Which is just what the doctor ordered for quickly launching applications and their documents from within Hypercard.

Figure 1.

Cards-Eye View

Call it Up

Upon invocation, PinUpMenu displays a small window, and waits patiently for a mousedown event (See Figure 1). If this mousedown occurs outside of the window , the window disappears and PinUpMenu has run its course. If this mousedown occurs within the window a pop-up menu (hierarchical if desired) appears and allows for the selection of any desired item. The returned value can then be processed by the script that called it. In the case of “The Pop-Up Finder” the selected application and document will be launched using Hypercards “Open” command.

Necessary Scripts, Options

The PinUpMenu XFCN must be called with at least 2 parameters (See Figure 2). The first parameter is a string which is drawn within the window. Use this parameter to differentiate between your particular implementations of PinUpMenu. Parameters 2 through 16 are used to build the menus, they accomplish this by following a few simple rules. Each parameter should be a Hypercard container which holds one or more items. An Hypercard item being a string delineated by commas. The first item in the list will be the name of that line in the parent menu, while any remaining items will be listed in order as the submenus of that line. If there is only one item in the parameter then that item will be listed alone.

The Returns

PinUpMenu is an XFCN, therefore it must be used within an assignment and will return a value to Hypercard. This value will consist of one or two items. If the original click is made outside of the window or the mouse is released outside of the menu, then “Cancel” is returned. If the mouse is released in the parent menu inside of an item with no submenus then the selection name is returned in a one item string. If the mouse is released in a submenu choice, the answer consists of a two item string, the parent item followed by the submenu item separated by a comma so that your script can process the return with little modification. Be warned, this type of construction will not allow for the use of commas in a menu, as Hypercard will interpret this as two different items.

Figure 2.

Amongst the Gears

Hierarchical Menus

Submenus and Pop-Up Menus themselves are very easy to create and call up. They are created just as are other menus are, with a call to NewMenu. Although GetNewMenu and a resource could have been used, I have decided to create all windows and menus “on the fly”. I believe that XCMD’s should function this way whenever possible, simplifying the resource fork of the users Home stack as well as avoiding numbering conflicts between other external commands. To invoke a parent menu and the associated set of submenus , all you must do is call up the parent menu. The Mac toolbox handles the correct hiliting and displaying of the submenus. In order to alert the toolbox as to what you consider to be the correct hilighting and display two things must be done. First the command key field of the item you wish to give a submenu to should be set to $1B. This is a character which Apple has reserved to represent Hierarchical menus, it consists of the now familiar triangle pointing to the right. Secondly, set the item mark field of that same item to the menu id of the submenu and that’s it. The final step is to call InsertMenu(TheMenu,-1) for each of the submenus, and for the main menu in our case since it is a pop-up menu. By specifying -1 as the second parameter you tell the Mac not to put this menu in the Menubar, but to add it to the menu list anyway. Then call PopUpMenuSelect or MenuSelect and it will take care of the details from there. A very important consideration is that the menu id of a submenu may not be greater than 255, since that value must be a character placed into the item field. Passing a number larger will at the very least not work, and in the worst case cause some major problems.

Stealing Events

While PinUpMenus (or any other external code) is in control, Hypercard is in a semiconscious state so we will have to process events in its stead. This is no problem while running under the Finder, since the Menu Manager refreshes the screen beneath menus. However, if running under MultiFinder update events being generated through application switching will not be handled. This results in white blotches in the Hypercard window. The solution is very simple. By sending Hypercard the message ‘Go to this card’ we can force Hypercard to update itself, without interrupting our goings on (Thanks to Joe Zuffoletto and his article in Feb and March 1989 MacTutor for that handy tip). This however does not update the message box or the tool/pattern windoids. If this causes a problem the windoids can be restored by simply hiding and showing them again once PinUpMenu has run its course. Since the PinUpMenu XFCN serves no real purpose running in the background I plead guilty with explanation to not devising a more graceful alternative.

Saying Goodbye

Cleaning up the stack before returning to Hypercard is very important for any external code. I make sure all menuhandles not used are set to nil. This helps to determine which items have submenus, allowing us to avoid the unpleasant symptoms of deleting a menu which is not there or not deleting a menu that is. When writing external code it is important to dispose of all handles and pointers before returning. The leaving of unneeded blocks of memory lying around the heap for Hypercard to skirt is a very unMac-Like way of programming. In addition the window must be disposed of, and last but certainly not least the GrafPort must be reset to its state before the XFCN ran. If all of these have been done correctly then Hypercard should return without difficulty.

Getting Fancy

Simplicity equals Power

The structure of the XFCN, while remaining simple may be confusing to some developers not familiar with nesting procedures and functions. Under ordinary circumstances this is not necessary, and not often used. When writing a XFCN (or any other code resource) global variables are not allowed. By declaring the important variables in MAIN and then nesting all of the other routines, these variables can be treated as globals by the nested routines.

To sum up the actions of PinUpMenu in a nutshell besides creating a window it merely deciphers Hypercard item lists and calls AppendMenu for each of these. Simplicity yes but where is the power in that? Well, for those of you familiar with AppendMenu’s inherent power the answer is one simple word. Metacharacters. By passing these Metacharacters through Hypercard to PinUpMenus, all of the effects which can be used to make menus more clear can be used.

Staying in Metacharacter

Within the structure of the Mac OS menus may have some different characteristics. Each menu item may be drawn in a different style, may have an icon, may be enabled or disabled, and can have a command key associated with it. These can be added by a developer with little problem, by being specified in a resource file, or added through the AppendMenu call with Metacharacters. A metacharacter is a character which is not part of the actual text. Instead it allows for special distinctions to be made for a menu item. To add an icon to a menu item use the “^” character followed by the icons number less 256. To mark an item with a check mark or some such character, place an exclamation point (!) followed by the character before your item. The less than symbol (<) followed by either B,I,U,O,S sets the style of that item to the corresponding standard style. A slash (/) will associate a command key with that item, and a left parentheses (() will disable the item. If you don’t quite understand this you should get Inside Macintosh Volume 1 (which you should have anyway) and read page 352, where it is all explained very well.

K.I.S.S.

The most important aspect of menus is to add simplicity to your programs, or in this case stacks, menus should serve, not confuse. This means keeping styles, icons, item marks, and command keys to a minimum. By the way any command key equivalents used in PinUpMenus won’t work from Hypercard, since they only exist while the XFCN is running (i.e. while you are holding the mouse button down). If you must use command key equivalents you will have to trap for them yourself from within the scripts.

In Summation

Advantages and Other Uses

The Pop-Up Finder represents a speedy way to launch any desired application and/or document. But this is not the only use for our versatile little XFCN. Since PinUpMenu accepts its parameters as Hypercard item lists, scripts can use it to process and display whatever information they desire. I have written a script which determines the names of all objects in the present card and presents them in menu format. The object which is selected then opens its script for editing. I have also used it as a Pop-Up home stack, presenting the user with a variety of stack categories and names, going to whichever one is selected. For those of you who have taken the time to type this all in, or sent away for the source code, I believe the PinUpMenu represents a very useful XFCN, it makes no great departure from the mandated user interface standard yet allows for a customizable method of processing and choosing your Hypercard data. Hope you like it.

Listing:  XCMDUtil.PUM

unit XCMDUtils;

interface
 uses
 XCMDIntf;
 type
 Str31 = string[31];

 function PasToZero (paramPtr: XCmdPtr;
  str: Str255): Handle;

 procedure ZeroToPas (paramPtr: XCmdPtr;
 zeroStr: Ptr; var pasStr: Str255);

 procedure SendCardMessage (paramPtr: XCmdPtr; 
 msg: Str255);

implementation

 procedure DoJsr (addr: ProcPtr);
 inline
 $205F, $4E90;

 procedure SendCardMessage;
 begin
 with paramPtr^ do
 begin
 inArgs[1] := ORD(@msg);
 request := xreqSendCardMessage;
 DoJsr(entryPoint);
 end;
 end;

 function PasToZero;
 begin
 with paramPtr^ do
 begin
 inArgs[1] := ORD(@str);
 request := xreqPasToZero;
 DoJsr(entryPoint);
 PasToZero := Handle(outArgs[1]);
 end;
 end;

 procedure ZeroToPas;
 begin
 with paramPtr^ do
 begin
 inArgs[1] := ORD(zeroStr);
 inArgs[2] := ORD(@pasStr);
 request := xreqZeroToPas;
 DoJsr(entryPoint);
 end;
 end;

end.
Listing:  PinUpMenu.p

unit PinUpMain;
{--This is the source code of the PinUpMenu XFCN--}
{--Written by Steven Fuchs--}
{--PO Box 129, Coram, NY 11727--}

interface
 uses
 XCMDIntF, XCMDUtils;
 procedure MAIN (ParamPtr: XCMDPtr);
implementation
 type
 MenuArray = array[0..15] of MenuHandle;
 StrArray = array[0..15] of str255;

 procedure MAIN (ParamPtr: XCMDPtr);
 var
 TheMenus: MenuArray;
 TheParams: StrArray;
 PinUpWindow: WindowPtr;
 OldPort: GrafPtr;
 EndRect: rect;
 Name, TheAnswer: str255;
 item: longint;

{--HandleDrawing is a simple routine to draw our windows string--}
 procedure HandleDrawing;
 begin
 MoveTo(PinUpWindow^.portrect.left + 2, PinUpWindow^.portrect.bottom 
- 4);
 DrawString(Name);
 end;

{--HandleThisUpdate determines the correct action to take in  response--}
{--to an Update Event,  if the window is ours it calls HandleDrawing, 
if--}
{--it is the Hypercard main window, it calls SendCardMessage, otherwise--}
{--(most likely one of the tool pallettes) it removes the message--}
 procedure HandleThisUpdate (LilWindow: WindowPtr);
 begin
 BeginUpdate(LilWindow);
 if WindowPtr(LilWindow) = OldPort then
 SendCardMessage(ParamPtr, ‘Go to this card’)
 else if WindowPtr(LilWindow) = PinUpWindow then
 HandleDrawing
 else
 ValidRect(LilWindow^.portrect);
 EndUpdate(LilWindow);
 end;

{--GetParams is responsible for transferring parameters--}
{--sent to MAIN into our variables: Name, and TheParams arrray}
 function GetParams: boolean;
 var
 NumOfMenus, z: integer;
 begin
 NumOfMenus := ParamPtr^.ParamCount - 1;
 GetParams := NumOfMenus >= 1;
 ZeroToPas(ParamPtr, ParamPtr^.params[1]^, Name);
 for z := 1 to 15 do
 if z <= NumOfMenus then
 begin
 ZeroToPas(ParamPtr, ParamPtr^.params[z + 1]^, TheParams[z]);
 TheParams[z] := Include(‘,’, TheParams[z], length(TheParams[z]) + 1);
 end
 else
 TheParams[z] := ‘’;
 end;

{--ReturnWindowRect must determine length of string “Name”--}
{--Size the rectangle so the string fits nicely inside, and locate it 
so that--}
{--it appears in the same spot regardless of screen size--}
 procedure ComputeWindowRect;
 var
 DummyPt: point;
 begin
 SetPt(DummyPt, 150, 100);
 SetRect(EndRect, 0, 0, stringwidth(Name) + 20, 17);
 LocaltoGlobal(DummyPt);
 OffsetRect(EndRect, DummyPt.h, DummyPt.v);
 end;

{--CreateWindow does just that, creating the window for us and setting 
up the default drawing characteristics--}
 procedure CreateWindow;
 var
 LongOne: LongInt;
 begin
 PinUpWindow := NewWindow(nil, EndRect, ‘The Course’, false, 3, nil, 
false, LongOne);
 SetPort(PinUpWindow);
 TextFont(0);
 TextSize(12);
 ShowWindow(PinUpWindow);
 SelectWindow(PinUpWindow);
 end;

{--HitCameInWindow holds our event loop, where it waits for a mousedown--}
{--if this mousedown is within the window we return true, otherwise false.--}
 function HitCameInWindow: boolean;
 var
 Event: EventRecord;
 begin
 HitCameInWindow := false;
 repeat
 SystemTask;
 if GetNextEvent(EveryEvent, Event) then
 case Event.What of
 MouseDown: 
 if PtInRect(Event.Where, EndRect) then
 HitCameInWindow := true;
 UpdateEvt: 
 HandleThisUpdate(WindowPtr(event.message));
 ActivateEvt: 
 HandleDrawing;
 otherwise
 end
 until Event.What = Mousedown;
 end;

{--ReturnAndMaul is our parsing function, it reads the first item from--}
{--the string indicated by Index and returns it. It then deletes that 
item--}
 function ReturnAndMaul (Index: integer): str255;
 var
 ThePlace: integer;
 begin
 ThePlace := Pos(‘,’, TheParams[Index]);
 if ThePlace = 0 then
 ReturnAndMaul := ‘’
 else
 begin
 ReturnAndMaul := str255(copy(TheParams[Index], 1, ThePlace - 1));
 delete(TheParams[Index], 1, ThePlace);
 end;
 end;

{--CreateSubMenu does just that, creating the menu with NewMenu and sets 
the correct fields in the main menu to indicate the submenu exists--}
 procedure CreateSubMenu (Index: integer);
 var
 swf, saf: char;
 begin
 swf := chr($1B);
 saf := chr(240 + Index);
 TheMenus[Index] := NewMenu(240 + Index, ‘ASubMenu’);
{--Tell Mac OS we have a submenu--}
 SetItemCmd(TheMenus[0], Index, swf);
{--Tell Mac OS which Menu it is--}
 SetItemMark(TheMenus[0], Index, saf);
 end;

{--AddAllItems calls ReturnAndMaul repeatedly until there is nothing--}
{--left of string indicated by Index.  Each of items up until--}
{--that point is appended to the end of the submenu.--}
 procedure AddAllItems (TIndex: integer);
 var
 stripe: str255;
 x: integer;
 begin
 repeat
 stripe := ReturnAndMaul(TIndex);
 if stripe <> ‘’ then
 AppendMenu(TheMenus[TIndex], Stripe);
 until stripe = ‘’;
{--Insert our menu into hierarchical portion of MenuList--}
 InsertMenu(TheMenus[TIndex], -1);
 end;

{--BuildThoseMenus is the top layer, it creates the main menu and adds 
the items, decides if that item needs submenus and if so calls the procedures 
to add them--}
 procedure BuildThoseMenus;
 var
 Increment: integer;
 ScaredStr: str255;
 begin
 TheMenus[0] := NewMenu(240, ‘MainMenu’);
 for increment := 1 to 15 do
 begin
 TheMenus[increment] := nil;
 ScaredStr := ReturnAndMaul(increment);
 if ScaredStr <> ‘’ then
 begin
 AppendMenu(TheMenus[0], ScaredStr);
 if Pos(‘,’, TheParams[increment]) <> 0 then
 begin
 CreateSubMenu(increment);
 AddAllItems(increment);
 end;
 end;
 end;
{--Insert main menu into PopUp portion of Menu List--}
{--Same call as for hierarchical menus--}
 InsertMenu(TheMenus[0], -1);
 end;

{--ConvertAnswer takes the longint returned from PopUpMenuSelect and 
Converts it to the proper string for return to Hypercard--}
 function ConvertAnswer (TheL: longInt): str255;
 var
 ThePrimary, TheSecondary: str255;
 begin
 if TheL = 0 then
 ConvertAnswer := ‘Cancel’
 else if HiWord(TheL) = 240 then
 begin
 GetItem(TheMenus[HiWord(TheL) - 240], LoWord(TheL), TheSecondary);
 ConvertAnswer := TheSecondary;
 end
 else
 begin
 GetItem(TheMenus[0], HiWord(TheL) - 240, ThePrimary);
 GetItem(TheMenus[HiWord(TheL) - 240], LoWord(TheL), TheSecondary);
 ConvertAnswer := Str255(concat(ThePrimary, ‘,’, TheSecondary))
 end;
 end;

{--CleanUpMess takes care of the very important work of cleaning up the--}
{--heap before handing the reins back to Hypercard--}
 procedure CleanUpMess;
 var
 x: integer;
 begin
 DisposeWindow(PinUpWindow);
 for x := 0 to 15 do
 if TheMenus[x] <> nil then
 begin
 DeleteMenu(240 + x);
 DisposeMenu(TheMenus[x]);
 end;
 end;

{--Here is the code for the procedure MAIN, it acts at the highest level 
farming out almost all of the tasks to its other procedures and functions--}
 begin
 GetPort(OldPort);
 TheAnswer := ‘Cancel’;
 if GetParams then
 begin
 ComputeWindowRect;
 CreateWindow;
 BuildThoseMenus;
 if HitCameInWindow then
 begin
 Item := PopUpMenuSelect(TheMenus[0], EndRect.bottom + 4, EndRect.left, 
0);
 TheAnswer := ConvertAnswer(Item);
 end;
 SetPort(OldPort);
 CleanUpMess;
 end;
 ParamPtr^.returnvalue := PastoZero(ParamPtr, TheAnswer);
 end;
end.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

How to be a star in Britney Spears: Amer...
If you've ever wanted to be a star, baby, then you've probably already checked out Britney Spears: American Dream and are happily making your way up the charts. But fame doesn't come easy, and everyone needs a helping hand sometimes. So we've got... | Read more »
AppSpy is hiring a part time Staff Write...
| Read more »
How to save lives in ER Surgery Simulato...
A serious earthquake has struck a nearby town in ER Surgery Simulator - Emergency Doctor, and it’s up to you to save the victims. [Read more] | Read more »
Tips and tricks to get a high score in G...
Ketchapp Games loves the endless runner genre. And its newest game, Gravity Switch, is no exception. Gravity Switch takes a fresh approach, though, as you move a block, suspended in zero gravity, safely through a maze of shifting pillars. If the... | Read more »
Tips and tricks to get a high score in S...
Smash Fu is a high-paced tile-tapping game that requires quick reflexes and some practice. You’ll have to smash bricks with the skill of a seasoned black belt to get a high score. To raise the stakes a bit, you’ll also have to avoid tapping any... | Read more »
How to keep the ball rolling in Dropple
If you're new to the minimalist puzzler Dropple, you may find yourself struggling to make it beyond the first couple of steps before your ball falls into the endless abyss below. [Read more] | Read more »
How not to die in Traffic Rider
Traffic Rider, an Out Run-esque game in which your ride a motorcycle recklessly into trffic, might not seem particularly complicated. [Read more] | Read more »
How to adjust your chess game for Regici...
At first glance you might likenWarhammer 40,000: Regicide to Chess - and you'd be right. Regicideputs its own spin on the classic board game though, so some of your tried and true methods may not work quite so well here. [Read more] | Read more »
Rush Rally 2 (Games)
Rush Rally 2 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: -- Rush Rally 2 is the most authentic and thrilling rally simulation on your mobile, all running at an astounding 60fps. Console... | Read more »
Warhammer 40000: Regicide (Games)
Warhammer 40000: Regicide 1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: ++NOTE: Optimized for with iPad Air, iPad mini 2, iPhone 5 and up. ++ "“This game has no right to be as good as it... | Read more »

Price Scanner via MacPrices.net

Textkraft Professional Becomes A Mobile Produ...
The new update 4.1 of Textkraft Professional for the iPad comes with many new and updated features that will be particularly of interest to self-publishers of e-books. Highlights include import and... Read more
SnipNotes 2.0 – Intelligent note-taking for i...
Indie software developer Felix Lisczyk has announced the release and immediate availability of SnipNotes 2.0, the next major version of his productivity app for iOS devices and Apple Watch.... Read more
Pitch Clock – The Entrepreneur’s Wingman Laun...
Grand Rapids, Michigan based Skunk Tank has announced the release and immediate availability of Pitch Clock – The Entrepreneur’s Wingman 1.1, the company’s new business app available exclusively on... Read more
13-inch 2.9GHz Retina MacBook Pro on sale for...
B&H Photo has the 13″ 2.9GHz Retina MacBook Pro (model #MF841LL/A) on sale for $1599 including free shipping plus NY tax only. Their price is $200 off MSRP. Amazon also has the 13″ 3.9GHz Retina... Read more
Apple price trackers, updated continuously
Scan our Apple Price Trackers for the latest information on sales, bundles, and availability on systems from Apple’s authorized internet/catalog resellers. We update the trackers continuously: - 15″... Read more
Clearance 12-inch Retina MacBooks available s...
B&H Photo has dropped prices on leftover 2015 12″ Retina MacBooks with models now available starting at $999. Shipping is free, and B&H charges NY tax only: - 12″ 1.1GHz Gray Retina MacBook... Read more
Check Apple prices on any device with the iTr...
MacPrices is proud to offer readers a free iOS app (iPhones, iPads, & iPod touch) and Android app (Google Play and Amazon App Store) called iTracx, which allows you to glance at today’s lowest... Read more
New 2016 13-inch 256GB MacBook Air on sale fo...
B&H Photo has the new 13″ 1.6GHz/256GB MacBook Air (model MMGG2LL/A) on sale for $1149 including free shipping plus NY sales tax only. Their price is $50 off MSRP. Amazon has the 13″ 1.6GHz/256GB... Read more
Apple refurbished iPad Air 2s available start...
Apple has Certified Refurbished iPad Air 2 available starting at $339. Apple’s one-year warranty is included with each model, and shipping is free: - 128GB Wi-Fi iPad Air 2: $499 - 64GB Wi-Fi iPad... Read more
Accenture and Vatican Opera Romana Pellegrina...
Accenture has announced that the official mobile application for the Extraordinary Jubilee Year of Mercy declared by Pope Francis has been built and launched by Accenture Mobility, part of Accenture... Read more

Jobs Board

ISCS *Apple* ID Site Support Engineer - APP...
…position, we are looking for an individual who has experience supporting customers with Apple ID issues and enjoys this area of support. This person should be Read more
Automotive Sales Consultant - Apple Ford Linc...
…you. The best candidates are smart, technologically savvy and are customer focused. Apple Ford Lincoln Apple Valley is different, because: $30,000 annual salary Read more
*Apple* Support Technician II - Worldventure...
…global, fast growing member based travel company, is currently sourcing for an Apple Support Technician II to be based in our Plano headquarters. WorldVentures is Read more
Restaurant Manager (Neighborhood Captain) - A...
…in every aspect of daily operation. WHY YOU'LL LIKE IT: You'll be the Big Apple . You'll solve problems. You'll get to show your ability to handle the stress and Read more
Editor, *Apple* News - APPLE (United States...
Job Summary The Apple News team is looking for a passionate...a news organization. Description * Program Top Stories in Apple News * Post on Apple News Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.