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”.]
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