Legacy Document

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

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

/ Creating Buttons

<3D Button>

You can use the <3D Button> command to place a 3D button on a panel. You must specify the graphic associated with this button, the location of the button on the panel, and an event function that Apple Guide calls when the user clicks the button.

<3D Button> buttonUpPict, buttonDownPict, buttonLoc, buttonEvent
            [, b&wUp] [,b&wDown]

buttonUpPict

A resource ID, resource name, or filename that identifies the picture that defines the appearance of the button in its normal state (that is, when the button 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 button when 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.

buttonLoc

A constant specifying either the button's general location or its coordinates relative to the current pen location.

To describe the button's coordinates, use the Point function. The current pen location's horizontal coordinate is the left edge of the current format; the vertical coordinate corresponds to the bottom edge of the last object not specifically placed using coordinates.

You can also use these constants to describe the button location:
LEFT
CENTER
RIGHT

If you specify one of these constants, Guide Maker justifies the button accordingly within the current format.

buttonEvent

A name of an event function or event list. 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.

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.

DESCRIPTION

The <3D Button> command places a button on a panel and specifies an event function that Apple Guide calls when the user clicks the button. The button's appearance is determined by the buttonUpPict and buttonDownPict parameters. In addition, you can specify replacement pictures using the b&wUp, and b&wDown parameters, which Apple Guide uses according to the bit depth of the user's monitor. All pictures describing the button's appearance should have the exact same size. Note that if Apple Guide displays a black-and-white button, it uses the frame created for the color button. In general, you should always provide both a color and black-and-white version of the button.

Buttons appear inline with the surrounding text. If you specify the button's location using the constants LEFT, CENTER, or RIGHT, Guide Maker positions the button in the current format, and left-justifies, right-justifies, or centers the button, accordingly. You can also specify the button's location relative to the current pen position by specifying a specific point. For example, if you specify the button location as Point(50,100), Guide Maker positions the button 50 pixels to the right and 100 pixels down from the current pen location.

SPECIAL CONSIDERATIONS

If you use the <3D Button> command, it must always appear between the
<Define Panel> and <End Panel> commands.

If you do not explicitly specify a black-and-white picture for the button's up or down appearance and the guide file happens to contain 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

#define doButton1Action as an event function that sends to 
# the app with signature 'WAVE' (SurfWriter) the Apple event
# defined by event class 'sfwr' and event ID 'act1'
<Define Event> "doButton1Action", 'WAVE', 'sfwr', 'act1'

#define doButton2Action as an event function
<Define Event> "doButton2Action, 'WAVE', 'sfwr', 'act2'
<Define Panel> "Example Panel"
   To accomplish this task, do this:

   Very informative instructions here.

   #place Button1 right-justified on panel
   <3D Button> "Button1UpPict", "Button1DownPict", RIGHT, \xAC
               doButton1Action(), \xAC
               "Button1B&WUpPict", "Button1B&WDownPict"
   #Button2's appearance is defined by: 
   # the 'PICT' w/ resource ID 2010 -- the color buttonUpPict
   # the 'PICT' w/ resource ID 2012 -- the color buttonDownPict
   # Guide Maker automatically looks in the guide file for 'PICT's
   # with resource ID's one greater than the specified color 'PICT's;
   # in this case, it looks for resource IDs of 2011 for the b&wUp 
   # and 2013 for b&wDown and uses these as the black & white 'PICT's
   #place Button2 relative to the current pen location, that is,
   # 50 pixels to the right, 100 pixels down
   <3D Button> 2010, 2012, Point(50,100), doButton2Action()
<End Panel>
#define doOpenDocmt as an event function that sends to 
# the app with signature 'WAVE' (SurfWriter) the 
# Open Documents event. Note that when doOpenDocmt is called
# it expects a parameter (the name of the file to open)
<Define Event> "doOpenDocmt", 'WAVE', 'aevt', 'odoc',,'----'

<Define Panel> "Example Panel 3"
   To accomplish this task, do this:

   #place Open button left-justified on panel
   <3D Button> "OpenButtonUpPict", "OpenButtonDownPict", LEFT, \xAC
               doOpenDocmt("HD:SurfWriter folder:SampleReport"),\xAC 
               "OpenButtonB&WUpPict", "OpenButtonB&WDownPict"
<End Panel>

SEE ALSO

For information on using formats when placing buttons, see "Formatting Text and Objects in a Panel" beginning on page 10-84. For information on the <Define Event> and <Define Event List> commands, see page 10-178 and page 10-181, respectively.