Apple Guide

Name

Apple Guide

Syntax

tell application "Apple Guide"
   GoViewTopicAreas (* when a Guide window is open, go to the topics panel *)
   (* do other stuff with an open Apple Guide *)
end tell

Dictionary commands

Animate

If an animation object like a QuickTime movie exists in the open Apple Guide window, then this command is a signal for it to execute its animation. The following is an example of animate :

tell app "Apple Guide" to animate

Your script raises an error if you use this command and the open Apple Guide window does not have an animation.

Close

This command closes all the Apple Guide windows and the running database of help files. But it doesn’t close the Apple Guide program, which is still running invisibly in the background. You can still send the program an Apple event to open another application’s Guide files, for instance. Use Quit if you want to completely quit the Guide program so that it doesn’t use the machine’s memory anymore.

DoCoach

This command draws the coach mark that is defined for the current Apple Guide window, or it has no effect if the current panel has not defined a coach mark. If any of the Topics, Index, or Look For Apple Guide panels are active then this command raises an error.

CoachID integer: This optional parameter draws the coach mark associated with a particular id number, if any is defined for the active Guide panel or window.

DoHuh

If the beveled button with the “Huh?” label is active in the lower left corner of the Guide window, then issuing this command is the equivalent of clicking the “Huh?” button:

tell app "Apple Guide" to DoHuh

GoBack

This command closes an “oops” topic and returns to the Guide window that preceded the active oops panel. What’s an oops topic, you ask? When the Apple Guide instructs the user to initiate a command such as File → Print and the user moves to the next instructive panel without doing the requested command, then Apple Guide usually displays another panel with the oops label and some text that repeats the instructions.

GoNext

This command moves to the next Apple Guide window.

GoNextUnconditionally

Unlike GoNext, this command goes to the next window regardless of whether the user has followed the previous panel’s instructions.

GoNextToPanel

This command goes to the next numbered panel, as in:

tell app "Apple Guide" to GoNextToPanel PanelNumber 5

Specify the panel number with the PanelNumber labeled parameter. If there is not a panel number 5 (because the active set of Apple Guide windows only has four panels), then Apple Guide ignores the command.

GoNextToFirst

This command goes to the first panel in the Guide sequence.

GoNextToLast

This command goes to the last panel in the Guide sequence.

GoPrevious

This command goes to the window preceding the active Guide panel; it’s the same as clicking the left arrow button in the lower region of an Apple Guide panel.

GoPreviousUnconditionally

This goes to the window preceding the active Guide panel, but doesn’t evaluate any of the help program’s qualifiers such as whether the user followed on-screen instructions. This command has the same effect as clicking the left arrow button in the lower region of an Apple Guide panel.

GoStart

This goes back to the beginning of a help sequence, such as an Apple Guide Topics window.

HidePanel

This minimizes a help window (makes it smaller on the desktop).

ShowPanel

This command expands or maximizes a minimized guide window. The command is ignored if the panel is already maximized.

TogglePanel

If the panel is minimized this command maximizes it, and vice versa. It has the same effect as clicking the zoom box (first control in upper right corner) on the Guide panel.

GoViewIndex

This command goes to the access window’s Index view, which has the same effect as clicking the Index button. If the access window is not open then this command raises an error. The access window is the upper level Guide window. See GoViewLookFor and GoViewTopicAreas.

GoViewLookFor

This command goes to the access window’s Look For view (which is the same as clicking the Look For button). If the access window is not open then this command raises an error. See GoViewIndex and GoViewTopicAreas.

string string

The string labeled parameter for this command 7forces a search for the string and presents some topic results:

GoViewLookFor string "grep"

GoViewTopicAreas

This goes to the access window’s Topics view, which also happens when you click the Topics button in the access window. If the access window is not open then this command raises an error. See GoViewIndex and GoViewLookFor.

Open

Use the Open command, followed by a database file-specification labeled parameter, to open a new Apple Guide help system. Save the path to the Guide file in a file specification variable, and then follow the open database syntax with the variable and any of the two optional parameters.

Here’s a syntax example:

tell app "Apple Guide" to open database filespec string "grep"
ViewNumber 4

This command forces a search of the filespec Guide file for the term “grep” and presents the results in a Look For access window. Notice that the target application for the example’s command is “Apple Guide”, not “BBEdit 5.0.” When you use AppleScript, the program’s Guide file is controlled through the Apple Guide application. BBEdit’s dictionary does not identify any Apple events for controlling help files.

Database file specification: The database labeled parameter uses a file specification object, which contains the file path to an Apple Guide file.
string string: The labeled parameter string (which takes a string type) allows the script to force a database search for the particular string term. Using this parameter with the open command is the equivalent of the user going to the Look For access window, entering the string in the edit field, and clicking the search button. So a single AppleScript command substitutes for at least three manual interactions with the Apple Guide.
ViewNumber integer: Follow this labeled parameter with an integer representing one of six choices of views that will be displayed: 1=Full Howdy, 2=Topic Areas, 3=Index, 4=LookFor, 5=Single Howdy, 6=Single Topics. For example, Figure 10-1 represents the Full Howdy view.

OpenPanelOnly

This command opens the presentation window (as opposed to an access view such as Index) associated with the panel id number provided with the panelId labeled parameter. You also have to provide the database labeled parameter with this command if a Guide database isn’t already open.

PanelId integer

This is a number representing the id of the panel to open:

OpenPanelOnly PanelID 4.

Database file specification or string pathname:

Include this labeled parameter if Apple Guide is not already running or if you are changing Guide files:

OpenPanelOnly PanelID 4 Database filespec

Apple recommends that scripters use a file specification type rather than a string type for identifying the Guide file.

OpenPanelOnlyAnother

You can open a panel in a new window using this command, as long as a Guide file is already open. In other words, an already opened presentation window will not close as a result of OpenPanelOnlyAnother.

PanelId integer

Identify the panel to open in a new Guide window with this labeled parameter:

OpenPanelOnlyAnother PanelID 4

OpenPanelOnlyReplacement

This replaces any existing windows with the presentation window identified with the PanelId labeled parameter. The parameter is required, as shown in the following:

OpenPanelOnlyReplacement PanelId 4

PanelID integer: Include the id of the panel that will open.

OpenWithSequence

If you know the sequence id of a particular sequence of Guide presentation windows, then you can use this command to test it:

OpenWithSequence Database filespec SequenceID 4

Database file specification

Save the Guide file’s path (a string such as “macintosh hd:BBEdit 5.0:BBEdit 5.0:BBEdit Guide”) to a variable of type file specification, then use the variable for the Database labeled parameter:

OpenWithSequence Database filespec SequenceID 1

SequenceID integer

This is a required labeled parameter whose integer represents the id of the sequence of panels to launch.

PanelNumber integer

Optionally, include the id of the panel that starts off the sequence:

OpenWithSequence Database filespec SequenceID 1 PanelNumber 2

OpenNamedSequence

This is like the previous command, except that you name the sequence with a string, rather than providing a sequence id number. The following is a syntax example:

OpenNamedSequence Database filespec SequenceName "printhlp" PanelNumber 2

Database file specification

Save the Guide file’s path (a string such as “macintosh hd:BBEdit 5.0:BBEdit 5.0:BBEdit Guide”) to a variable of type file specification, then use the variable for the Database labeled parameter:

OpenNamedSequence Database filespec SequenceName "printhlp"

SequenceName string

This is the name of the sequence to initiate on the desktop.

PanelNumber integer

Optionally, include the id of the panel that will start off the sequence:

OpenNamedSequence Database filespec SequenceName "printhlp" PanelNumber 2

OpenWithSequenceAnother

This is designed to display a sequence of panels without closing any existing windows, but a Guide file or database must already be open.

SequenceID integer

This is a required labeled parameter whose integer represents the id of the sequence of panels to launch.

PanelNumber integer

Optionally, include the id of the panel that starts off the sequence:

OpenWithSequenceAnother SequenceID 1 PanelNumber 2

OpenWithSequenceOops

This command initiates a new sequence of panels in an open Guide window, hiding but not closing the original window. A GoBack command returns the user to the prior window. The particular Guide database must already be open.

SequenceID integer: This is a required labeled parameter whose integer represents the id of the sequence of panels to launch.

OpenWithSequenceReplacement

This closes any existing access or presentation windows and starts a new sequence in another presentation window. A syntax example is:

OpenWithSequenceReplacement SequenceID 1 PanelId 2

SequenceID integer

This is a required labeled parameter whose integer represents the id of the sequence of panels to launch.

PanelNumber integer

Optionally, include the id of the panel that starts off the sequence:

OpenWithSequenceReplacement SequenceID 1 PanelId 2

PlaySound

This sends the open Guide file a PlaySound Apple event and includes the id of the sound data as a labeled parameter:

tell app "Apple Guide" to PlaySound SoundId 4

SoundId integer: This is a number representing the id of the sound data in the database. This labeled parameter is required.

Quit

This closes any open windows and terminates the Apple Guide app. Unlike close, Quit does not leave Apple Guide silently running in the background, using its megabyte or so of memory.

QuitFront