TweetFollow Us on Twitter

Help in a Balloon
Volume Number:5
Issue Number:6
Column Tag:System 7 Workshop

Related Info: Help Manager

Help Comes in a Balloon

By John R. Powers, III, Monte Sereno, CA

[John’s profession is to help people use and understand interactive multimedia. He, in turn, has the help of friends who include a wife, five sons, a dog, a cat, and two horses. No wonder he enjoys it so much. You can contact him on AppleLink at “JohnPowers”.]

Introduction

How many users really read the User’s Guide before using a computer program? While there are probably a few, I suspect that most are itching to get their hands on the software and don’t bother to read the instructions. The user stumbles along learning by trial and error and, when they absolutely have to, refer to the manual or on-line help. In the meantime they browse the interface asking “What is this?”, “What does it do?”, and “What happens when I click it?” Fortunately, Apple’s System 7.0 Balloon Help™ software program has come along to provide a way to answer the user’s questions.

Balloon Help, when properly implemented, allows users to browse the interface and discover an application’s functionality. It’s build into the System 7.0 Help Manager and is available to all applications. The System 7.0 Finder™ operating system software will already have Balloon Help available with over a thousand balloons. Thanks to some ingenious design, Apple has made it easy for you to add Balloon Help to your own application.

There are three ways that Balloon Help can be used in an application. The first is automatically provided by the Help Manager. When the user chooses “Show Balloons” from the always-present help icon, the Help Manager will display default balloons for the standard interface elements of your application. It will explain the close box, the zoom box, and other generic interface elements. This is the default and always provided when “Show Balloons” is active.

The second way is driven by help resources that you have stored in your application resource fork. The Help Manager scans the help resources and displays balloons for your menu items, windows, and dialogs. You decide which interface elements are supported and what is displayed for each. It is all resource driven so you don’t need to recompile your application. Localization is simplified because only the resources need to be changed. A new tool, BalloonWriter™ software program, has been provided by Apple to aid you in writing balloons for any application.

The third way is driven by procedure calls in your code. These are custom balloons. You track the mouse and make a call to the Help Manager to display a balloon. It is this third method that we will focus on.

Custom Balloons

I am going to use HyperCard® software program examples for a variety of reasons. First, it’s easy to create the interface elements in HyperCard. Second, using balloons to explain a card’s interface elements is extremely helpful to a user (you’ll become a believer once you add balloons to your stack - it really helps!) Second, default and standard balloons are not available for fields and buttons in a stack so custom balloons are the only solution. Balloon Help should be built into HyperCard but it isn’t, until it is we’ll just have to use a XFCN extension.

Our goals for adding Balloon Help to a stack are as follows:

1. Give the HyperTalk® scripting language full control over balloons. The script should be able to turn Balloon Help on and off, put any text into a balloon, and display the balloon at any card location.

2. Use the build-in features of the Help Manager to reduce the HyperTalk scripting burden.

3. Preserve the interface of Balloon Help so that the user makes a seamless transition from using Balloons outside the stack to within the stack.

Our approach is to use a command-driven XFCN to do the following:

• Turn Balloon Help on and off

• Show and remove balloons

• Optionally let the Help Manager track our cursor

To make our use of Balloon Help seamless we follow these rules:

• Balloons cannot be displayed unless Balloon Help is turned on. This can be done by the user’s choosing “Show Balloons” in the help menu or with a XFCN command. The appearance of a balloon should not surprise the user. They should always have control over whether or not balloons can be displayed.

• Removing balloons is done if any one of the following events happens: (1) the cursor leaves the object of interest, (2) Balloon Help is turned off, (3) the Help Manager displays another balloon.

Invoking Our Balloon

Here is an example of a balloon explaining a button:

The button script looks like this:

--1

on mouseEnter
 ShowABalloon “Click on this”¬
 && “button to see the version”¬
 && “identification of the XFCN.”¬
end mouseEnter

on mouseLeave
  RemoveABalloon
end mouseLeave

on mouseUp
 put Help(“!”) into msg box
end mouseUp

The button script invokes the handlers “ShowABalloon” and “RemoveABalloon”.

--2

on ShowABalloon helpMessage
 put Help(“ShowBalloon”,¬
 helpMessage, prettyTip())¬
 into cd fld “helpResult”
 Be853Free helpMessage,¬
 prettyTip()
end ShowABalloon

on RemoveABalloon
 put Help(“RemoveBalloon”)¬
 into cd fld “helpResult”
end RemoveABalloon

The workhorses are ShowABalloon and RemoveABalloon, but to make things just perfect, we add two more handlers, “prettyTip” and “Be853Free”.

--3

function prettyTip
 -- Create a pretty location
 -- for the balloon tip.
 -- Use lower-right corner of
 -- button with a wee tweak.
 put the rect of the target¬
 into targetRect
 put item 3 of targetRect¬
 & “,” & item 4 of targetRect¬
 into tip
 subtract 10 from item 1 of tip
 subtract 10 from item 2 of tip
 return tip
end prettyTip

on Be853Free helpMessage, tip
 -- a -853 means that the
 --Help Manager detected a
 -- rapid cursor movement and,
 -- thinking that the cursor
 -- was just ‘passing thru’,
 -- did not display the balloon.
 -- We try again until successful.
 repeat until “-853”¬
 is not in cd fld “helpResult”
 put Help(“ShowBalloon”,¬
 helpMessage, tip)¬
 into cd fld “helpResult”
 end repeat
end Be853Free

PrettyTip calculates a location for the balloon tip that looks nice. This function can be made as sophisticated as you want, but the idea is to put the tip in a place that will not obscure the object.

Be853Free is one of those “gotchas” that you don’t discover until you actually use the Help Manager. It seems that the Help Manager is always tracking the cursor, just in case you move over a default or standard object and a balloon needs to be displayed. This is always happening. However, the Help Manager won’t display a balloon if you move across a hot spot too quickly. The assumption is that you will linger on a stop for a few milliseconds if you want some help otherwise you are just “passing thru”. As a result, the Help Manager is looking at the velocity of the cursor to determine if you are lingering or passing thru. If the velocity is too fast, it assumes that you don’t want a balloon flashing up and restrains itself. This process came about from a lot of careful tweaking and user studies. However, this can work against you when you are tracking the cursor yourself and putting up balloons. Our example above uses the “mouseWithin” message to indicate that the cursor is within the object. We invoke Balloon Help thru our XFCN. In the milliseconds that pass during this process, the cursor is probably still moving and the Help Manager may abort the balloon display. If it does, it returns a -853 result code. Our Be853Free handler persistently re-invokes the Help Manager until the balloon is finally displayed. In practice, this happens a lot, but only takes a few hundredths of a second. The user is never aware of a delay.

We could have solved the -853 result code issue in the XFCN by having the XFCN code persistently call the Help Manager until the -853 result code disappears. In the interest of giving the HyperTalk scripter more control, I elected to handle it in HyperTalk.

Into the Code

The actual code to invoke the Help Manager is fairly simple and is described in chapter 11 of Inside Macintosh Volume VI. Rather than load down this article with a lengthy code listing, I’ll walk you thru the process with an description, pseudo-code, and code snippets.

The first thing we do upon entry into the XFCN is to check for the “!” and “?” commands. This has become a fairly standard way for HyperTalk scripters to query the XFCN to determine version (!) and syntax (?).

Balloon Help obviously needs the Help Manager so we’ll need to use the Gestalt test for the Help Manager. To be really safe, we need to check for the Gestalt Manager first. The XFCN may be in a stack running on a pre-7.0 system and we don’t want any “unimplemented traps” crashes. The Compatibility chapter of Inside Macintosh Volume VI describes some simple tests for the Gestalt trap and how to test for the Help Manager.

We previously set some rules about when balloons can and cannot be displayed. From these rules we can make a decision table which describes the action to be taken for each of our four commands as follows:

Balloon Help

Command On Off

“On” -- turn on

“Off” turn off --

“ShowBalloon” show --

“RemoveBalloon” remove --

We use HMGetBalloons() to get the current state of Balloon Help. If Balloon Help is already off and we received a “ShowBalloon” or “RemoveBalloon” command then we ignore the command and return to HyperCard. If an “On” or “Off” command is received, then we use HMSetBalloons() to change the state.

The first test can be done as follows:

/* 4 */

if(!HMGetBalloons()
 && (cmpStr(cmd,”ShowBalloon”)
 ||cmpStr(cmd,”RemoveBalloon”)))
 {
 paramPtr->returnValue = nil;
 return;
 }

We return an empty result because, according to our rules, this is not an error condition.

The “On” and “Off” commands can be processed with a simple instruction like the following:

/* 5 */

if((turnOn=cmpStr(cmd, “On”))
 || cmpStr(cmd, “Off”))
 err = HMSetBalloons(turnOn);

The variable “turnOn” get set to true if the command was “On” and false if it wasn’t. If either command was present, the new state of Balloon Help is set to the value of “turnOn”.

We save the biggest job for last - the processing of the “ShowBalloon” command. The call to the appropriate Help Manager routine is easy, but the overhead in translating the HyperCard parameters to something suitable for the Help Manager requires some work.

The first parameter is the command, “ShowBalloon”. The two additional parameters are the balloon text and the tip location.

A Pascal string is only one possibility for balloon content. Balloon Help will also accept PICT resource IDs, STR# resource IDs, TextEdit handles, picture handles, stylized text resource IDs, and STR resource IDs. We took the easy route and just passed a Pascal string.

The HMShowBalloon procedure requires a HMMessageRecord consisting of a message type identifier and the message string, handle, or ID depending on the type. In our case the message type identifier is “khmmString” and the message string is a Str255 Pascal string. We create our Pascal string by copying the HyperCard parameter handle into a Str255 as follows:

/* 6 */

HLock(paramPtr->params[1]);
strcpy((char *) str,
 paramPtr->params[1]);
HUnlock(paramPtr->params[1]);
c2pstr(str);

The preparation of the tip location is a bit harder because it is passed from HyperCard as a string containing the horizontal and vertical coordinates separated by a comma. We need to parse the string to separate the elements and form them into a type “Point”. The new extended XCMD interface provided with HyperCard 2.0 includes a callback to perform this chore for you. Its Pascal definition is as follows:

{7}

PROCEDURE StrToPoint(
 paramPtr: XcmdPtr;
 str: Str255;
 VAR pt: Point);

Once we have the text string and the tip location, we can set the defaults for the other parameters and call HMShowBalloon. The complete Pascal definition is as follows:

{8}

FUNCTION HMShowBalloon(
 message: HMMessageRecord;
 tip: Point;
 alternativeRect: RectPtr;
 tipProc: Ptr;
 theProc: Integer;
 varCode: Integer;
 method: Integer): OSErr;

The “message” and “tip” are the text string and the tip location. The remaining parameters provide opportunities to customize the balloons. You can change the relationship of the tip to the balloon, the shape and appearance of the balloon, and the handling of the screen bits beneath the balloon. HMShowBalloon has provided a great deal of flexibility to allow you to add your own personality to Balloon Help. The values used in our example are as follows:

message khmmString and
 the text from HyperCard
tipthe point from HyperCard
alternativeRect  see below
tipProc nil
theProc 0
varCode 0
method  kHMRegularWindow

The use of these parameters is described in the Help Manager chapter in Inside Macintosh Volume VI. The “alternativeRect” parameter has a dual function and an interesting “gotcha” so we’ll look at that further.

Using the “alternativeRect”

“alternativeRect” is used to define a “hot rectangle” for the Help Manager to use in tracking the cursor. If the cursor leaves the hot rectangle while the balloon is showing, the Help Manager will automatically remove the balloon. Removing a balloon when the cursor leaves the relevant area is the standard interface for Balloon Help. Our example earlier in this article used the “mouseLeave” handler to perform this operation for us. If we pass the rectangle of the object to the Help Manager, the Help Manager will do it for us automatically. This is one less thing that the HyperCard handlers need to do and it conforms to our rules for Balloon Help operation.

“alternativeRect” also has an interesting dual function. If we send a “ShowBalloon” for a tip location in which the resulting balloon will be off-screen, then the Help Manager will attempt to relocate the balloon. The Help Manager uses the “alternativeRect” to define the area where we want the tip of the balloon and attempts to move the balloon so that all of the balloon is on-screen. The “alternativeRect” need not be the same rectangle as our object. If we make “alternativeRect” smaller than our object, then we have a better chance of having the Help Manager fit the balloon on screen. If we make “alternativeRect” larger than our object, then we have a better change of not having our object obscured. There is a lot of flexibility in using “alternativeRect” and, fortunately, it is fairly easy in HyperCard to define object rectangles and try them out with the XFCN. Experimentation is recommended.

The “gotcha” in using the “alternativeRect” is that HMShowBalloon requires a pointer to the “alternativeRect”, but does not copy the rect into its own data structures. This requires the calling program to preserve the rect so that the pointer remains valid. Remember, the Help Manager is tracking the cursor and the “alternativeRect” after the HMShowBalloon call is executed. It needs the “alternativeRect” for an indefinite period until the cursor leaves the “alternativeRect”. Since HMShowBalloon does not copy or preserve “alternativeRect”, we must. In a standard application, we would probably put the “alternativeRect” in a global or other persistent data structure. However, we don’t have that luxury in a XFCN. No globals are allowed. To solve this problem, we must create a handle in the heap and save it between XFCN calls. All this is required because HMShowBalloon does not copy our “alternativeRect”.

To make it even dicier, the pointer containing the “alternativeRect” must remain available until HMShowBalloon is through with it. And it has to remained in a “locked” state. We really don’t know when HMShowBalloon is through with the “alternativeRect” pointer because we can’t test for the existence of specific balloons. In other words, once we create storage for the “alternativeRect” it can never go away unless Balloon Help is turned off. Fortunately, since the Help Manager allows only one balloon to be shown at a time, we need only one stash for “alternativeRect”. Having this tiny structure locked in the heap imposes some risk of fragmentation, but I’ve never observed any problems with this. How to save a smidgen of data between XCMD calls has been described in previous articles. Essentially, it involves allocating some storage on the application heap, locking it, storing the “alternativeRect”, converting the handle reference to ASCII, and storing the ASCII form in a HyperCard global. See the bibliography for articles describing this process ad nauseam.

In addition to the difficulties in saving the “alternativeRect”, the rect has to be converted from a HyperCard rect stored as a string of comma-separated values (left, top, right, bottom) to a QuickDraw rect stored as a Macintosh® computer rect structure (top, left, bottom, right). And, if all that wasn’t enough, the QuickDraw rect must be converted from HyperCard’s Local coordinates to Global coordinates. This requires two LocalToGlobal calls, one for each corner (top-left and bottom-right). There is no need to save the GrafPort or set the GrafPort since the Local coordinate system is already HyperCard’s. The Extended XCMD Interface includes a callback to convert a Pascal string passed by HyperCard into a Rect.

The “varCode”

Another interesting parameter is “varCode”. This parameter lets you specify the arrangement of the tip on the balloon. You have eight choices, from 0 to 7, representing two variants of the tip from each of four possible corners. This is very useful for placing the tip and balloon in a location that will not obscure the object being described. The following diagram shows the best variant for each direction of entry into the object.

To determine direction, you will need to either calculate the relative location of the tip in the “alternativeRect” or track cursor movement. The former will probably yield more consistent results and the latter more attractive results, the choice is yours.

Summary

Balloon Help is going to bring a new and enormously useful method of helping the user understand how to use your application or stack. You can either add balloons by creating balloon resources (“standard” balloons) or call the Help Manager directly (“custom” balloons). We have shown some basic techniques in adding custom balloons to HyperCard by using an XFCN. The basic model can turn Balloon Help on, turn it off, show a balloon, and remove a balloon. Extensions include adding hot rects, variants on the balloon shape and tip location, custom tips, custom balloon window definitions, and using PICTs, STR#, and other types of resources.

Adding balloons to your application or stack, even if they are only the standard balloons, will make it a lot easier for your user. It helps you explain your interface elements and your application’s functionality. It puts more control in the hands of your user and that’s what we are here for.

Finally, writing balloons will help you. It should be required duty in Macintosh programming boot camp. It an excellent exercise in user-oriented thinking and clarity. Go ahead. Write some balloons and send them to a friend today.

Bibliography

Inside Macintosh Volume VI. Chapter 3, Compatibility.

Inside Macintosh Volume VI. Chapter 11, The Help Manager.

Palmer, Jim. Interface Issues for Balloon Help. Apple Direct, December 1990, p.15ff.

Powers, John R. Mac To Mainframe with HyperCard. MacTutor, June 1990, p.10ff.

Powers, John R. Communicating With HyperCard. MacTech Quarterly, Spring 1990, p.36ff.

Acknowledgement

Thanks to Randy Carr, the creator of the System 7.0 Help Manager, for his counsel.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Dropbox 193.4.5594 - Cloud backup and sy...
Dropbox is a file hosting service that provides cloud storage, file synchronization, personal cloud, and client software. It is a modern workspace that allows you to get to all of your files, manage... Read more
Google Chrome 122.0.6261.57 - Modern and...
Google Chrome is a Web browser by Google, created to be a modern platform for Web pages and applications. It utilizes very fast loading of Web pages and has a V8 engine, which is a custom built... Read more
Skype 8.113.0.210 - Voice-over-internet...
Skype is a telecommunications app that provides HD video calls, instant messaging, calling to any phone number or landline, and Skype for Business for productive cooperation on the projects. This... Read more
Tor Browser 13.0.10 - Anonymize Web brow...
Using Tor Browser you can protect yourself against tracking, surveillance, and censorship. Tor was originally designed, implemented, and deployed as a third-generation onion-routing project of the U.... Read more
Deeper 3.0.4 - Enable hidden features in...
Deeper is a personalization utility for macOS which allows you to enable and disable the hidden functions of the Finder, Dock, QuickTime, Safari, iTunes, login window, Spotlight, and many of Apple's... Read more
OnyX 4.5.5 - Maintenance and optimizatio...
OnyX is a multifunction utility that you can use to verify the startup disk and the structure of its system files, to run miscellaneous maintenance and cleaning tasks, to configure parameters in the... Read more
Hopper Disassembler 5.14.1 - Binary disa...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more

Latest Forum Discussions

See All

Zenless Zone Zero opens entries for its...
miHoYo, aka HoYoverse, has become such a big name in mobile gaming that it's hard to believe that arguably their flagship title, Genshin Impact, is only three and a half years old. Now, they continue the road to the next title in their world, with... | Read more »
Live, Playdate, Live! – The TouchArcade...
In this week’s episode of The TouchArcade Show we kick things off by talking about all the games I splurged on during the recent Playdate Catalog one-year anniversary sale, including the new Lucas Pope jam Mars After Midnight. We haven’t played any... | Read more »
TouchArcade Game of the Week: ‘Vroomies’
So here’s a thing: Vroomies from developer Alex Taber aka Unordered Games is the Game of the Week! Except… Vroomies came out an entire month ago. It wasn’t on my radar until this week, which is why I included it in our weekly new games round-up, but... | Read more »
SwitchArcade Round-Up: ‘MLB The Show 24’...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for March 15th, 2024. We’re closing out the week with a bunch of new games, with Sony’s baseball franchise MLB The Show up to bat yet again. There are several other interesting games to... | Read more »
Steam Deck Weekly: WWE 2K24 and Summerho...
Welcome to this week’s edition of the Steam Deck Weekly. The busy season has begun with games we’ve been looking forward to playing including Dragon’s Dogma 2, Horizon Forbidden West Complete Edition, and also console exclusives like Rise of the... | Read more »
Steam Spring Sale 2024 – The 10 Best Ste...
The Steam Spring Sale 2024 began last night, and while it isn’t as big of a deal as say the Steam Winter Sale, you may as well take advantage of it to save money on some games you were planning to buy. I obviously recommend checking out your own... | Read more »
New ‘SaGa Emerald Beyond’ Gameplay Showc...
Last month, Square Enix posted a Let’s Play video featuring SaGa Localization Director Neil Broadley who showcased the worlds, companions, and more from the upcoming and highly-anticipated RPG SaGa Emerald Beyond. | Read more »
Choose Your Side in the Latest ‘Marvel S...
Last month, Marvel Snap (Free) held its very first “imbalance" event in honor of Valentine’s Day. For a limited time, certain well-known couples were given special boosts when conditions were right. It must have gone over well, because we’ve got a... | Read more »
Warframe welcomes the arrival of a new s...
As a Warframe player one of the best things about it launching on iOS, despite it being arguably the best way to play the game if you have a controller, is that I can now be paid to talk about it. To whit, we are gearing up to receive the first... | Read more »
Apple Arcade Weekly Round-Up: Updates an...
Following the new releases earlier in the month and April 2024’s games being revealed by Apple, this week has seen some notable game updates and events go live for Apple Arcade. What The Golf? has an April Fool’s Day celebration event going live “... | Read more »

Price Scanner via MacPrices.net

Apple Education is offering $100 discounts on...
If you’re a student, teacher, or staff member at any educational institution, you can use your .edu email address when ordering at Apple Education to take $100 off the price of a new M3 MacBook Air.... Read more
Apple Watch Ultra 2 with Blood Oxygen feature...
Best Buy is offering Apple Watch Ultra 2 models for $50 off MSRP on their online store this week. Sale prices available for online orders only, in-store prices may vary. Order online, and choose... Read more
New promo at Sams Club: Apple HomePods for $2...
Sams Club has Apple HomePods on sale for $259 through March 31, 2024. Their price is $40 off Apple’s MSRP, and both Space Gray and White colors are available. Sale price is for online orders only, in... Read more
Get Apple’s 2nd generation Apple Pencil for $...
Apple’s Pencil (2nd generation) works with the 12″ iPad Pro (3rd, 4th, 5th, and 6th generation), 11″ iPad Pro (1st, 2nd, 3rd, and 4th generation), iPad Air (4th and 5th generation), and iPad mini (... Read more
10th generation Apple iPads on sale for $100...
Best Buy has Apple’s 10th-generation WiFi iPads back on sale for $100 off MSRP on their online store, starting at only $349. With the discount, Best Buy’s prices are the lowest currently available... Read more
iPad Airs on sale again starting at $449 on B...
Best Buy has 10.9″ M1 WiFi iPad Airs on record-low sale prices again for $150 off Apple’s MSRP, starting at $449. Sale prices for online orders only, in-store price may vary. Order online, and choose... Read more
Best Buy is blowing out clearance 13-inch M1...
Best Buy is blowing out clearance Apple 13″ M1 MacBook Airs this weekend for only $649.99, or $350 off Apple’s original MSRP. Sale prices for online orders only, in-store prices may vary. Order... Read more
Low price alert! You can now get a 13-inch M1...
Walmart has, for the first time, begun offering new Apple MacBooks for sale on their online store, albeit clearance previous-generation models. They now have the 13″ M1 MacBook Air (8GB RAM, 256GB... Read more
Best Apple MacBook deal this weekend: Get the...
Apple has 13″ M2 MacBook Airs available for only $849 today in their Certified Refurbished store. These are the cheapest M2-powered MacBooks for sale at Apple. Apple’s one-year warranty is included,... Read more
New 15-inch M3 MacBook Air (Midnight) on sale...
Amazon has the new 15″ M3 MacBook Air (8GB RAM/256GB SSD/Midnight) in stock and on sale today for $1249.99 including free shipping. Their price is $50 off MSRP, and it’s the lowest price currently... Read more

Jobs Board

Early Preschool Teacher - Glenda Drive/ *Appl...
Early Preschool Teacher - Glenda Drive/ Apple ValleyTeacher Share by Email Share on LinkedIn Share on Twitter Read more
Senior Software Engineer - *Apple* Fundamen...
…center of Microsoft's efforts to empower our users to do more. The Apple Fundamentals team focused on defining and improving the end-to-end developer experience in Read more
Relationship Banker *Apple* Valley Main - W...
…Alcohol Policy to learn more. **Company:** WELLS FARGO BANK **Req Number:** R-350696 **Updated:** Mon Mar 11 00:00:00 UTC 2024 **Location:** APPLE VALLEY,California Read more
Medical Assistant - Surgical Oncology- *Apple...
Medical Assistant - Surgical Oncology- Apple Hill WellSpan Medical Group, York, PA | Nursing | Nursing Support | FTE: 1 | Regular | Tracking Code: 200555 Apply Now Read more
Early Preschool Teacher - Glenda Drive/ *Appl...
Early Preschool Teacher - Glenda Drive/ Apple ValleyTeacher Share by Email Share on LinkedIn Share on Twitter Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.