Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Apple Guide Complete / Part 4 - Scripting Guide Files

Chapter 10 - Guide Script Command Reference / Guide Script Command Descriptions

<Define Nav Button>
You can use the <Define Nav Button> command to define a navigation button and to specify an event function that Apple Guide calls when the user clicks the button.
<Define Nav Button> buttonName, buttonUpPict, buttonDownPict ,
                  dimmedButtonPict, buttonEvent
                  [, b&wUp] [, b&wDown] [, b&wDimmed]
buttonName
A text string specifying the name to associate with this button. Note that this name is not used by Apple Guide; you provide a button name only so that you can reference this button definition in the <Default Nav Button Set> or <Seq Nav Button Set> commands.
buttonUpPict
A resource ID, resource name, or filename that identifies the picture that defines the appearance of the navigation button in its active state (when the button is active and is not pressed). If you specify a resource ID or resource name, you must make the resource available to Guide Maker using the <Resource> command. If you specify a filename, the file must be in the same folder as your source files in order for Guide Maker to find the file.
buttonDownPict

A resource ID, resource name, or filename that identifies the picture that defines the appearance of the navigation button when the button is active, the cursor is in the button, and the user presses the mouse button. If you specify a resource ID or resource name, you must make the resource available to Guide Maker using the <Resource> command. If you specify a filename, the file must be in the same folder as your source files in order for Guide Maker to find the file.
dimmedButtonPict
A resource ID, resource name, or filename that identifies the picture that defines the appearance of the navigation button when the button is inactive (dimmed). Only navigation buttons that specify the constant DIMMABLE (rather than an event function) in the buttonEvent parameter are dimmable. Dimmable navigation buttons are inactive by default. To make a dimmable navigation button active on a specific panel, use the <Dimmable Button Data> command in the panel's definition.

If you specify a resource ID or resource name, you must make the resource available to Guide Maker using the <Resource> command. If you specify a filename, the file must be in the same folder as your source files in order for Guide Maker to find it.
buttonEvent
A name of an event function, event list, or a constant. Include any parameters expected by the function in parentheses following its name. You define event functions using the <Define Event> or <Define Event List> command. Guide Maker also provides built-in functions that you can specify in this parameter. When the user clicks the button, Apple Guide calls the function defined by this parameter; usually such a function is used to send a specific Apple event.

Rather than specifying an event function or event list, you can use the constant DIMMABLE in this parameter. Use the constant DIMMABLE to indicate that Apple Guide should launch a new sequence (as specified in a subsequent <Dimmable Button Data> command) when this button is active and the user clicks the button. You can specify only one dimmable navigation button per guide file. A navigation button that is defined using the constant DIMMABLE is called a dimmable navigation button.
b&wUp
A filename that, if provided, Apple Guide uses in place of the button appearance described by the buttonUpPict parameter only if the bit depth of the user's monitor is set to 4 bits or less. This parameter is optional and can be used only if you also specified a filename for the buttonUpPict parameter. However, if you specify a resource ID or resource name in the buttonUpPict parameter, you can still provide a black-and-white picture by importing a 'PICT' graphic whose resource ID is one greater than the resource ID of the color graphic.
b&wDown
A filename that, if provided, Apple Guide uses in place of the button appearance described by the buttonDownPict parameter only if the bit depth of the user's monitor is set to 4 bits or less. This parameter is optional and can be used only if you also specified a filename for the buttonDownPict parameter. However, if you specify a resource ID or resource name in the buttonDownPict parameter, you can still provide a black-and-white picture by importing a 'PICT' graphic whose resource ID is one greater than the resource ID of the color graphic.
b&wDimmed
A filename that, if provided, Apple Guide uses in place of the button appearance described by the dimmedButtonPict parameter only if the bit depth of the user's monitor is set to 4 bits or less. This parameter is optional and can be used only if you also specified a filename for the dimmedButtonPict parameter. However, if you specify a resource ID or resource name in the dimmedButtonPict parameter, you can still provide a black-and-white picture by importing a 'PICT' graphic whose resource ID is one greater than the resource ID of the color graphic.

DESCRIPTION
The <Define Nav Button> command defines a navigation button that you can later associate with a sequence. To do this, after defining the navigation button, you must define a navigation button set by using the <Define Nav Button Set> command and then associate this navigation button set with a specific sequence using the <Default Nav Button Set> or <Seq Nav Button Set> commands.
The appearance of the button is determined by the buttonUpPict, buttonDownPict, and dimmedButtonPict parameters. In addition, you can specify replacement pictures using the b&wUp, b&wDown, and b&wDimmed parameters, which Apple Guide uses according to the bit depth of the user's monitor. Note that if Apple Guide displays a black-and-white button, it uses the frame created for the color button. All pictures describing the button's appearance should have the exact same size. Because the navigation bar is a fixed height and because navigation buttons should use the Apple Guide font, the navigation buttons you define should have a height of 18 pixels. The navigation bar has a fixed width and height, and the navigation arrows always appear on the right; therefore you should size and design your buttons to fit within this area. You should use 10-point Espy Serif font for any text in navigation buttons (for Roman script systems).
When creating a navigation button in a graphics application, make sure your button graphic doesn't contain any extra white space around the edges (such as a bounding box); that is, when the button is copied, the graphic should represent its precise shape. When Guide Maker places a button graphic in the navigation bar, it places the graphic and then fills the remaining area with the navigation bar background pattern.
Navigation buttons are always associated with a sequence and are displayed on every panel in the sequence.
For buttons that specify the DIMMABLE constant in the buttonEvent parameter, Apple Guide displays the navigation button in its inactive state. Therefore, for each panel definition that uses this kind of navigation button, you must include a <Dimmable Button Data> command on those panels in which the navigation button is active. Navigation buttons such as the Huh? button typically specify the DIMMABLE constant, as the Huh? button is often active on only a subset of panels in a sequence.
For buttons that specify event functions or event lists in the buttonEvent parameter, Apple Guide displays the navigation button in its active state by default. Therefore, for each panel definition that uses this kind of navigation button, the button must always be active. Navigation buttons such as the GoStart button are typically always active.
Navigation buttons appear in the navigation bar, in the location determined by the <Define Nav Button Set> command.
The file Standard Setup is provided with Guide Maker. This file contains descriptions of the Huh? and GoStart navigation buttons, and defines three navigation button sets. If you include the Standard Setup file in your build file, you can automatically use these two navigation buttons or any of the three navigation button sets, as needed in your source files.

SPECIAL CONSIDERATIONS
If you do not explicitly specify a black-and-white picture for the button's up, down, or dimmed appearance, and the guide file contains a 'PICT' graphic whose resource ID is one greater than one of the button's color 'PICT' graphics, Apple Guide uses this 'PICT' graphic as the button's black-and-white picture.

EXAMPLES
#example that uses the Huh? button. 
# The Huh? button is defined in the Standard Setup file as:
# (Standard Setup also contains the black-and-white versions for
#  the button in 'PICT' resources with resource IDs 1102, 1112, 1122)
#<Define Nav Button> "Huh?", 1101, 1111, 1121, DIMMABLE

<Define Panel> "Panel 2"
#the Huh? button should be active on this panel, 
# so use the <Dimmable Button Data> command
# (when this navigation button is active and the user clicks 
# this button, Apple Guide launches a new sequence in a new window)
   <Dimmable Button Data> "Huh?", "Name of sequence to launch"
<End Panel>
<Define Sequence> "Sequence with Huh? button"
   #use this nav button set for this sequence
   <Seq Nav Button Set> "Huh? Only"
   <Panel> "Panel 1"    #Huh? button inactive
   <Panel> "Panel 2"    #Huh? button active
   <Panel> "Panel 3"    #Huh? button inactive
<End Sequence>
#example of a navigation button that uses the DIMMABLE constant
# (this kind of navigation button is inactive by default)
<Define Nav Button>  "Why?", "upWhyPict", "downWhyPict", \xAC
                     "dimmedWhyPict", DIMMABLE, \xAC
                     "b&wUpWhyPict", "b&wDownWhyPict", \xAC
                     "b&wDimmedWhyPict"
#define a nav button set that uses the Why? button and
# specify the Why? button as the middle navigation button
<Define Nav Button Set> "Why Nav Button Set", \xAC
                        "GoStart", "Why?"
<Define Panel> "Panel 2"
#the Why? button should be active on this panel, 
# so use the <Dimmable Button Data> command
# (when this navigation button is active and the user clicks 
# this button, Apple Guide launches the sequence in a new window)
   <Dimmable Button Data> "Why?", "sequence to launch"
<End Panel>
#Another example of a navigation button
# This button uses an event function. 
# This kind of button is always active.
# The GoStart button is defined in Standard Setup file as:
#<Define Nav Button> "GoStart", 1103, 1113, 1123, GoStart()
# the GoStart function is also defined in Standard Setup as:
#<Define Event> "GoStart", 's***', 'help', 'stac'
<Define Sequence> "Sequence with GoStart button"
   #use the GoStart Only nav button set for this sequence
   <Seq Nav Button Set> "GoStart Only"
   <Panel> "Panel A"    #GoStart button always active
   <Panel> "Panel B"    #GoStart button always active
<End Sequence>
#Another example of a navigation button.
#This button uses an event function, 
# this kind of button is always active.
<Define Nav Button> "Other", "upOtherPict","downOtherPict",\xAC
                     "dimmedOtherPict", DoOther(), \xAC
                     "b&wUpOtherPict", "b&wDownOtherPict",\xAC
                     "b&wDimmedOtherPict"
#define nav button set that uses an Other button
<Define Nav Button Set> "Other Nav Button Set", \xAC
                         "Other"

<Define Sequence> "Sequence with Other button"
   #use this nav button set for this sequence
   <Seq Nav Button Set> "Other Nav Button Set"
   <Panel> "Panel A"    #Other button always active
   <Panel> "Panel B"    #Other button always active
<End Sequence>
SEE ALSO
For information on <Define Nav Button Set>, <Default Nav Button Set>, or <Seq Nav Button Set> commands, see page 10-80, page 10-32, and page 10-43, respectively.
For information on the <Define Event> and <Define Event List> commands, see page 10-178 and page 10-181, respectively.
The <Dimmable Button Data> command is described next.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.