Name

Help Viewer

Synopsis

Since Help Viewer (see Figure 10-2) is essentially a browser, you can open up any local hypertext markup language (HTML) file with it (see the open command for Help Viewer). AppleScripters can thus use this program to either provide their scripts with their own HTML-based help systems or provide an alternate and perhaps quicker avenue to the Mac OS’s help files.

A Help Viewer window
Figure 10-2. A Help Viewer window

Syntax

tell app "Help Viewer"
   (* get the app to print various help topics or open HTML files here *)
end tell

Dictionary commands

Open alias list

One of the ways to open up a help file in Help Viewer is to send it an open Apple event with a list of aliases as a parameter (one alias, representing the file path to the page you want to open). The following example opens a page on Help Viewer search tips. You can also use open to open your own HTML files in Help Viewer, as long as you make sure to save the file path as an alias inside of a list (as in {my_alias}) before passing this parameter to open : 

tell application "Finder"
   (* path to the Help Viewer tips file *)
   set tips to 
      ((system folder as string) & "help:apple help
   viewer:hvtps.¬
      htm") 
      as alias
end tell
tell application "Help Viewer"
   activate -- bring it to the fore
   open {tips} -- use open followed by a list with one alias
end tell

Print alias list

You can use code similar to the prior example to send a print command to Help Viewer. Create an alias to the HTML file, or have the user choose the file to print using the choose file scripting addition. (Appendix A, is devoted to scripting additions.) This could be accomplished with the following code, which returns an alias type pointing to the file: 

choose file with prompt "Choose the Help Viewer html file" of type {"TEXT"}

Then pass a list containing the alias to the print command: 

print {the_alias}

Quit

This quits the Help Viewer app.

Run

This command opens Help Viewer so that you can send Apple events to it: 

tell application "Help Viewer" to run

Close

This command also quits Help Viewer, like Quit.

Search string

This searches the help files using a particular search term: 

tell app "Help Viewer" to search looking for "AppleScript"

If you want to search just one “book,” such as QuickTime Help, then pass the search command a string parameter: 

search "QuickTime Help" looking for "AppleScript"

looking for string

Follow the looking for labeled parameter with a string containing your search term, as in the following: 

search looking for "QuickTime" -- or ...

search looking for "QuickTime or AppleScript"

Help Viewer allows the use of the following boolean operators: and, +, or, |, not, !, and grouping with parentheses ( ). An example of grouping is searching for files containing “file type” or “file sharing” but not “file exchange”: 

search looking for "file + (type | sharing) ! exchange"

handle url string

An easy way to open up a file in Help Viewer is to use the handle url command followed by a string containing the file path. You can use file paths that are relative to the startup disk:System Folder:Help folder: 

handle url "Apple Help Viewer:hvtps.htm"

The latter command opens up the Help Viewer tips file. Using the open command appears to work better if you want to use absolute paths (e.g., “Macintosh HD:Desktop Folder:myfile.html”) or open up your own HTML files using this program (see open earlier in this chapter).

Dictionary classes

application

The Help Viewer application class has one element, a window object, and one property, which is an alias type of the current file that the Help Viewer window is showing at the time. You can access the window element by using this code: 

tell app "Help Viewer" to get name of window 1

This would return a string such as “Help Viewer Tips.” You can get the file path of whatever file happens to be displayed in Help Viewer at the moment with code such as the following: 

get current file as text

This code returns something like “Macintosh HD:System Folder:Help:Apple Help Viewer:hvtps.htm.”

window (window object)

You can get properties of the current Help Viewer window (see the window class description) by seizing this element with code such as: 

tell app "Help Viewer" to get name of window 1

The element can be referred to by either its name (window “Help Viewer Tips”) or its index (window 1).

Current file (alias)

Use this property to get the pathname of the file that Help Viewer currently displays.

window

A Help Viewer window has several common AppleScript window properties, but you cannot use the Help Viewer app to make a new window, as in the following: 

make new window ...

You can get the value of any of these properties with code such as: 

get bounds of window 1

collapsed (boolean)

You can hide all but the Help Viewer title bar by using this code: 

set collapsed of window 1 to true

bounds (bounding rectangle)

This property returns the bounding rectangle for the window. This is a list of coordinates (which you can change), such as {50, 79, 668, 611}. For instance, this Help Viewer window’s upper left corner is 50 pixels from the left edge of the screen and 79 pixels down.

closeable (boolean; read-only)

This is a true/false value that indicates whether the window has a close box (the little box in the upper left corner of the window).

titled (boolean; read-only)

If the window has a title in the title bar, this property is true.

index (integer)

This is the index property of the open Help Viewer window. Help Viewer loads new help files and search results into the same window, so this property is almost always 1: 

window 1

floating (boolean; read-only)

Most Help Viewer windows are not floating; in other words, you can place them behind other document windows on the desktop. This property value is false if the window is not floating.

modal (boolean; read-only)

A modal window (such as an Alert dialog message) has to be dismissed by the user before they can do anything else with their desktop objects. The main Help Viewer window returns false for this property.

resizable (boolean; read-only)

If the window can be resized then this property returns true.

zoomable (boolean; read-only)

This returns true if the Help Viewer window has a zoom box, as does the main Viewer window.

zoomed (boolean)

This returns true if the user has clicked the Help Viewer’s zoom box.

name (international text)

This gets the name of the window, which appears in its title bar. An example of the return value is “Mac Help.”

visible (boolean; read-only)

If the Help viewer window is open, which it is when the program is running, then this property returns true.

position (point; read-only)

This returns the upper-left corner coordinates of the window as a list type. An example of the return value is {29, 175}. The first number represents the number of pixels from the left side of the screen along the x-axis.

Examples

tell application "Help Viewer"
   activate -- make Help Viewer the active window
   set myhelp to "macintosh hd:desktop folder:machowto.htm" as alias 
   -- open up your own html file
   open {myhelp}  -- open command takes a list of aliases (or alias)
end tell

It is easier to use open rather than handle url if you want to use absolute file paths to open up different HTML files in Help Viewer.

If you want to create uniformity with the Mac OS’s help system, you can generate your own software program’s help files in HTML form, then use Help Viewer to display the files.