Legacy Document

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

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

/ Specifying Pictures and Movies

<PICT>

You can use the <PICT> command to specify a picture in a panel.

<PICT> pictGraphic, location [, b&wPict]

pictGraphic

A resource ID, resource name, or filename that identifies the picture to place on the panel. If you specify the picture by 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.

location

A constant specifying the general location of the picture or a specific point describing the coordinates of the picture relative to the current pen location.

To specify a specific point (relative to the current pen location), use the Point function. The current pen location's horizontal coordinate is the left edge of the current format; its vertical coordinate corresponds to the bottom edge of the last object not specifically placed using coordinates.

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

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

b&wPict

A filename that, if provided, Apple Guide uses in place of the 'PICT' graphic described by the pictGraphic parameter only if the bit depth of the user's monitor is set to 4 bits or less. If you provide a black-and-white picture, be sure that it does not contain any color information. This parameter is optional and can be used only if you also specified a filename for the pictGraphic parameter. However, if you specify a resource ID or resource name in the pictGraphic 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 <PICT> command places a picture on a panel. The picture's appearance is determined by the pictGraphic and location parameters. In addition, you can specify a replacement picture using the b&wPict parameter, which Apple Guide uses according to the bit depth of the user's monitor. All pictures describing the graphic's appearance should have the exact same size. Note that if Apple Guide displays a black-and-white picture, it uses the frame created for the color picture. In general, you should always provide both a color and black-and-white version of the picture.

The picture appears inline with the surrounding text. To specify the picture's general location use the constants LEFT, CENTER, or RIGHT. If you do this, Guide Maker justifies the picture according to the current format. You can also specify the picture's location relative to the current pen position by specifying a specific point. For example, if you specify the picture location as Point(50, 100), Guide Maker positions the picture 50 pixels to the right and 100 pixels down from the current pen location.

Note that Guide Maker does not change the current pen position if you place an object using a point specifier. For example, if the current pen location is at (25, 25) (indicating the left edge of the current format and the bottom edge of the last object that was not specifically placed), and you specify the picture's location as Point(50, 100), Guide Maker places the picture as just described. If you then place text, the text appears starting at location (25, 25); after placing the text, Guide Maker updates the pen location to account for the placed text.

Guide Maker searches for the resource specified by the pictGraphic parameter in this manner. If the pictGraphic parameter contains a number, Guide Maker searches for a resource with the specified resource ID. If the parameter contains a name, Guide Maker looks first for a resource using the specified string as the resource name. If it fails to find such a resource, it then looks for a file using the specified string as the filename.

If the resource is contained in a file, Guide Maker imports the 'PICT' resource from the file referenced by the parameter pictGraphic and assigns it a resource ID. If provided, Guide Maker also imports the 'PICT' resource from the file referenced by the parameter b&wPict and assigns it a sequential resource ID. Note that the files containing the graphics should be located in the same folder as your help sources.

If you specify a color 'PICT' by resource ID or resource name, use a resource editor to assign it a resource ID greater than 2000 and also mark the resource as purgeable, then import it using the <Resource> command. Apple Guide reserves the use of 'PICT' resources with resource IDs less than 2000.

SPECIAL CONSIDERATIONS

Resource IDs 501 and 502 are reserved (for the application's color logo and black-and-white logo, respectively).

In general, in addition to a color picture you should always explicitly specify a black-and-white picture (by filename or by importing a 'PICT' graphic whose resource ID is one greater than the color 'PICT' graphic). If you do not explicitly specify a black-and-white picture and the guide file happens to contain a 'PICT' graphic whose resource ID is one greater than the color 'PICT' graphic, Apple Guide uses this 'PICT' graphic as the black-and-white picture.

EXAMPLES

#import resources used in this panel
<Resource> "MyResources", 'PICT'
<Resource> "MyResources2", 'PICT', 2528
<Define Panel> "Example Panel"
   To accomplish this task, do this:
   #very informative instructions here
   #place a picture on the panel (specified by filename)
   # and also include B&WPICT filename
   <PICT> "ColorPic1 File", CENTER, "B&WPic1 File"

   #place another picture on the panel (specified by res name)
   <PICT> "ColorPic2Resource", CENTER
   #place a picture on the panel (specified by resource ID)
   <PICT> 2528, CENTER
   #place a picture on the panel (specified by resource ID), and
   # specify its placement relative to the current pen location
   # as 75 pixels to the right, 30 pixels down
   <PICT> 2530, Point(75, 30)
<End Panel>

SEE ALSO

For information on the <Resource> command, see page 10-101.