Hot text is clickable text the user can click to perform some action. Typically, clicking hot text brings up additional information pertaining to the text, although it can also execute a script, play a sound, or perform some other action.
The concept of hot text is used in numerous applications,
including web browsers. You use the <hot text>
command to add hot text
capabilities to your guide.
You should consider using hot text when:
If you want to make information available from a panel, but that information is associated with the panel as a whole rather than any particular word, use a button instead.
Users expect to get information, not perform an action, when clicking hot text. So it's probably not a good idea to use hot text to execute a script, unless all the script does is present information. For example, you might create an AppleScript to open a SimpleText document that contains a diagram, and trigger it when the user clicks hot text. Even though this is a script, from the user's perspective it's simply showing additional information, so it doesn't cause confusion.
Apple Guide doesn't display hot text in any special way, so you need to apply a format - a special color, style, font, or other indication - so that the user can tell which text is clickable.
The most common way of formatting hot text is to underline it. Many users are familiar from web browsers with the convention that underlined text is clickable. Apple also uses underlining in its guides to show which text is hot.
You can use color to mark hot text, but make sure this is not the only distinguishing characteristic of clickable text, because color differences aren't visible on black & white monitors and may not be perceived well by color-blind users. If you use color for hot text, also use underlining or some other characteristic.
To add underlining (or other styles) to the text of your panels, you edit your source files with a word processor that supports styled text, such as Word or MacWrite II. You'll also need to make sure that the <define format>
commands in your source files leave the style parameter blank; otherwise, the style parameter will override any styles you use.
The most common use of hot text in guides is to open a second Apple Guide window, usually a definition. The original window remains on the screen, so the user can simply close the definition window to go back to the task.
You must define a separate sequence for the second window (or use a sequence already defined elsewhere in your guide). This sequence can contain anything you want, but usually it's a good idea to make it a single panel. This diminishes the chance that the user will get sidetracked away from the original task.
To make text in a panel hot, you use the <hot text>
command immediately before the paragraph that contains the text. If the hot text is "lizard", and clicking it opens the sequence "lizard definition", your panel definition might look like this:
<define panel> "My Panel"
<format> "Full"
<hot text> "lizard", FIRST, LaunchNewSequenceNewWindow("lizard definition")
The physiology of the lizard is rich with meaning for the researcher. Lizard physiology holds deep lessons for our modern world.
<panel prompt> "Standard"
<end panel>
When the user clicks the word "lizard", a second window containing the sequence "lizard definition" opens on top of the original window.
Hot text can be made to send any event that Guide Script can handle. The command <launch new sequence new window>
described above is only one such event.
For example, suppose that when the user clicks the word "lizard", you want to run an AppleScript, perhaps one called "ShowLizard" that opens a SimpleText document containing a picture of a lizard. Your panel definition might look like:
<define panel> "My Panel"
<format> "Full"
<hot text> "lizard", FIRST, DoScript("Scripts:ShowLizard")
The physiology of the lizard is rich with meaning for the researcher. Lizard physiology holds deep lessons for our modern world.
<panel prompt> "Standard"
<end panel>
For a list of events built into Apple Guide, see Apple Guide Complete, pages 188-190. To find out how to define your own events, see pages 178-181.
The <hot object>
command makes the paragraph or graphic that follows it clickable. (Since Apple Guide defines hot areas as rectangles rather than regions, the whole rectangle surrounding the graphic or text block will be clickable, so this command isn't suitable for making graphics with very irregular shapes into clickable objects.) The <hot object>
command has one parameter, the event that is executed when the user clicks the object. As with the <hot text>
command, this can be any event that you can define in GuideScript, but it's most often either a DoScript or LaunchNewSequenceNewWindow command.
GuideMaker requires that you place a <hot text>
command immediately before the line that contains the hot text. When GuideMaker parses a <hot text>
command, it looks in the next logical line of the source file, and complains if the hot text is not found in that line.
For example, if there is hot text in the second paragraph of your panel, the <hot text>
command must be placed on the line above that second paragraph. Placing it at the beginning of the panel text will cause a compiler warning to be issued.
Assuming you have indicated hot text by underlining or some other style change in the text, the most common reasons for its not appearing are:
<define format> "Body", Column(6,65,330), "Espy Serif", 10, PLAIN, BLACK, LEFT, TRUE
PLAIN
in the fifth parameter, leaving it blank. This will prevent GuideMaker from overriding your styles. If your hot text highlights when you click it, but the event you've specified doesn't happen, the most likely cause is a typo in the event specification.
If the hot text doesn't highlight when you click it:
<hot text>
command immediately before the paragraph in which the text appears? The command will not work if there's more than one carriage return between it and the hot text; for example, you can't group all your <hot text>
commands at the beginning of a multi-paragraph panel.
<hot text>
command? If you use FIRST
as the second parameter of the command, and the phrase occurs earlier in the paragraph, this earlier occurrence will be the one that's hot. For example, in the panel
you intend the word "script", which is the last word of the panel, to be clickable. However, the string "script" appears earlier in this panel, in the word "AppleScript". The above panel, when compiled, will do nothing when the user clicks the word "script", but when the user clicks the second half of the word "AppleScript", the script definition sequence will appear. Possible workarounds include using LAST instead of FIRST, or including surrounding punctuation in the hot phrase (in this case, you could include the period, designating "script." as your hot text).
<define panel> "My Panel"
<format> "Full"
<hot text> "script", FIRST, LaunchNewSequenceNewWindow("script definition")
The AppleScript language is used to control Macintosh computers. To use AppleScript, you write a small computer program, called a script.
<panel prompt> "Standard"
<end panel>
<hot text>
command so it's immediately before the hard return.)