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

/ Formatting Text and Objects in a Panel

<Define Format>
You can use the <Define Format> command to define a format for either immediate or later use to place text and objects in a panel.
<Define Format> formatName, columnCoords [, txFnt] [, txSize]
               [, txStyle] [, txColor] [, txAlign] [, alignPrompt]
formatName
A text string specifying the name of this format. Each format name must be unique from all other format names that you define.
columnCoords

A column specifier giving the top, left, and right coordinates that define the bounds for this format. All objects placed using a specific format are placed relative to the bounds of that format. For example, Column(50,75,275) defines a format whose bounds are defined by the column beginning with a top coordinate of 50 and a left coordinate of 75 that extends horizontally for 200 pixels. You don't need to specify the bottom coordinate, because Guide Maker automatically extends the bottom as you place objects on a panel. Any objects placed using this format are aligned within the defined bounds.
txFnt
A text string that specifies a font name (such as "Palatino" or "Geneva"). This parameter is optional; provide this parameter only when you want to override the text font specified by text attributes of your source files.
txSize
A short integer specifying the font size. This parameter is optional; provide this parameter only when you want to override the text size specified by text attributes of your source files.
txStyle
A constant specifying the text style. You can specify only one of these constants:
PLAIN BOLD ITALIC UNDERLINE OUTLINE SHADOW CONDENSE EXTEND

This parameter is optional; provide this parameter only when you want to override the text style specified by text attributes of your source files.
txColor
A constant or RGB specifier describing the text color. You can specify only one of these constants:
BLACK YELLOW MAGENTA RED CYAN GREEN BLUE WHITE

To specify the color using RGB values, use the form RGBColor(red, green, blue); for example: RGBColor(30000, 30000,30000).

This parameter is optional; provide this parameter only when you want to override the text color specified by text attributes of your source files.
txAlign
A constant that specifies the text alignment. You can specify only one of these constants:
LEFT CENTER RIGHT SYSTEM

This parameter is optional; provide this parameter only when you want to override the text alignment specified by the default format.
alignPrompt
A Boolean constant (TRUE or FALSE) that specifies whether the prompt should be aligned to this format. This parameter is optional; provide this parameter only when you want to override the alignment of the prompt as specified by the default format.

DESCRIPTION
The <Define Format> command creates a column with certain attributes, which you can use to simplify the layout of your panel objects. You can use formats to control the placement of most panel objects:

paragraphs of text
checkboxes and radio buttons
'PICT' graphics and QuickTime movies
labels for graphics

You can specify a format that you define with the <Define Format> command in a <Format> or <Default Format> command.
Panel text objects that follow a <Format> command are placed inline within the bounds specified by the format's column and according to the format's attributes. For example, a <PICT> command that uses LEFT as the picture's location is aligned at the left edge of the format's column, not at the left edge of the panel. Text placed after a <Format> command uses the text attributes defined by the specified format. Any text attributes specified in a <Define Format> command and then used by a <Format> command override Guide Maker's default formatting or any default formatting you previously described with the <Default Format> command.
If your source file is plain text and you don't specify a default format, or if you define a default format (using the <Default Format> command) that doesn't specify a particular text attribute, Guide Maker uses its own default for that text attribute unless you override the default using a <Define Format> command. If you omit any of the txFnt, txSize, txStyle, or txColor parameters in a <Define Format> command (and your source file is plain text), Guide Maker uses default text attributes of Espy Serif, 10-point, plain, and black, accordingly.
If your source file is styled text, by default Guide Maker uses the font, size, style, and color of the text as it appears in the source file. However, when you define a format you can override one or more of these text attributes. If a format specifies a text attribute, Guide Maker uses that text attribute rather than the one specified in your source files. For example, if a format specifies the font size as 10 and the style as bold, then all text that uses that format will appear with a size of 10 and in the bold style, regardless of the size and style of the text in the source file. That same text retains its font and color from the source file.
By default, Apple Guide aligns the prompt on a panel with the left edge of the text object that appears first in the panel definition. To align the prompt with another text object, specify TRUE in the alignPrompt parameter of the <Define Format> command for the format used by that text object. If more than one format on a panel has its alignPrompt parameter set to TRUE, Guide Maker reports an error. If a panel does not contain a text object, Apple Guide aligns the prompt to Guide Maker's default format (11 pixels in from the left edge of the panel).
Some Guide Script commands allow you to specifically place an object by specifying a coordinate location using the Point function. When you specifically place an object in this way, specify the object's location relative to the current pen location. 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. For example, to place a button 50 pixels to the right and 20 pixels down from the current pen location, specify Point(50,20) as a parameter to the <Standard Button> command. Guide Maker does not reset the current pen location after placing an object that specified coordinates. This feature allows you to place objects relative to a known location (the current pen location). Guide Maker does change the current pen location as it places objects that don't specify coordinates; however, note that the horizontal coordinate of the current pen location always refers to the left edge of the current format.
The file Standard Setup is provided with Guide Maker. This file defines four formats:

Tag. A format that provides a left column that you can use to format tags, that is, text such as "Do This" or "Oops".
Body. A format that provides a right column and that is designed for use with the Tag format. Use the Body format to provide the information that goes in the right column of a panel that also has a tag in it.
Full. A format that provides a full column. Use this format if your panel text requires a full-column width.
ResetPen. A format that resets the format to a default format.

If you include the Standard Setup file in your build file, you can automatically use these formats as needed in your source files.

EXAMPLES
#specifies a format with column coordinates of 
# top = 6, left = 0, and right = 54
# and text attributes of Espy Sans Bold, 10 point, Plain,
# default text color, and right aligned.
# And does not override the default alignment of the prompt.
# (the "Tag" format is defined in the Standard Setup file)
<Define Format> "Tag", Column(6, 0, 54), "Espy Sans Bold", 10, \xAC
                  PLAIN, , RIGHT, FALSE

#specifies a format with column coordinates of 
# top = 6, left = 65, and right = 330
# and text attributes of Espy Serif, 10 point, Plain,
# default text color, and left aligned.
# And the prompt should be aligned to leftmost edge of this format.
# (the "Body" format is defined in the Standard Setup file)
<Define Format> "Body", Column(6, 65, 330), "Espy Serif", 10, \xAC
                  PLAIN, , LEFT, TRUE
#use the "Tag" and "Body" formats in a panel
<Define Panel> "Some Panel"
   <Format> "Tag"
   Do This
   <Format> "Body"
   Give instruction here.
<End Panel>
#specifies a format with column coordinates of 
# top = 0, left = 0, and right = 250
# and default text attributes (Espy Serif, 10 point, Plain, Black)
# and default alignments
<Define Format> "Reset", Column(0, 0, 250)
#specifies a format with 
# text attributes of Palatino, 12 point, Bold, Red text color,
# and left aligned. The prompt should be aligned to the
# leftmost edge of this format (aligned to pixel 50).
<Define Format> "Left", Column(50, 50, 125), "Palatino", 12,\xAC
                  BOLD, RED, LEFT, TRUE

#specifies a format with 
# text attributes of Palatino, 12 point, Bold, default text color,
# and right aligned. 
<Define Format> "Right", Column(50, 150, 330), "Palatino", 12, \xAC
                  BOLD, , RIGHT, FALSE

#specifies a format with 
# text attributes of Palatino, 12 point, Bold, RGB values
# for the text color, and right aligned. 
<Define Format> "Right2", Column(50, 150, 330), "Palatino",12, \xAC
                  BOLD, RGBColor(30000,30000,30000), RIGHT, FALSE
<Define Panel> "An example panel with buttons"
   <Format> "Tag"
   Do This
   <Format> "Body"
   Give instruction here.
   #the current pen location at this point is 
   # for the x coordinate the left edge of the "Body" format
   # and for the y coordinate the bottom of the last placed text
   # this button is placed 50 pixels to the right and 20 pixels
   # down of the current pen location
   <Standard Button> "Some button", Point(50,20), doAction()
   #the current pen location is not reset
   # the next button is placed 50 pixels to the right and 80 pixels
   # down of the current pen location
   <Standard Button> "Another button", Point(50,80), doAction2()
   #the current pen location is not reset
   Here's some more instruction for the panel. 
   This text appears starting from the current pen location,
   so it could potentially overlap "Some button"
   #now the vertical pen location has changed to account for
   # the just placed text
   #the last button is placed using Guide Maker's formatting,
   # requesting the button be placed on the right in the 
   # current format
   <Standard Button> "Last button", RIGHT, doAction3()
<End Panel>
SEE ALSO
For information on the <Default Format> command, see page 10-30. For information on the <Format> command, see page 10-93.

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