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 Context Check>
You can use the <Define Context Check> command to define a context check that you can use in later commands to dynamically adjust the display of panels.
<Define Context Check> contextCheckName, codeResSpec [, targetApp]
                     [, additionalParam] [, additionalParam] 
                     [, ... ]
contextCheckName
A text string specifying the name of this context check. The name must be a single-word string (no spaces) and should be as descriptive as possible.
codeResSpec
A four-character sequence specifying the resource name of an external code module that contains the code that performs the context check. (An external module must have a four-character resource name, a resource type of 'extm', and a resource ID greater than 2000.)
targetApp
A four-character sequence specifying the signature of the target application or the constant FRONT. This parameter is optional. If it is omitted, Apple Guide uses FRONT as the default.
additionalParam
One or more additional parameters, of the form

data type [:default value]

where data type is a constant with an optional default value. To specify the data type, use one of these constants:
SHORT LONG PSTRING LPSTRING OSTYPE

To specify a default value, include a colon followed by the value after the data type. By default, if you specify a value as SHORT or LONG, the value is treated as a decimal number. To specify a hexadecimal number, precede the number by 0x. If you provide a default value for a parameter, then the caller does not specify this parameter when the context check is used in another command.

For strings, you should specify LPSTRING if you intend for the string to be localized. Guide Maker's Localize utility extracts from the <Define Context Check> command strings that are specified by LPSTRING but not strings specified by PSTRING.

Avoid providing a default value if you specify LPSTRING or PSTRING as the data type of the additional parameter. Instead, require that the caller of the context check provide this information.

DESCRIPTION
The <Define Context Check> command defines a context check. You typically use a context check to dynamically adjust the display of panels based on conditions that Apple Guide or your context check can detect. For example, Guide Maker provides two built-in context checks, checkBoxState and radioButtonState, that return the state of a checkbox or radio button.
After defining a context check, you can reference the context check in <If>, <Skip If>, <Make Sure>, and <Start Making Sure> commands.
Apple Guide passes parameters specified in additionalParam and following parameters to the context check. The context check should take the appropriate action and then return a value of TRUE or FALSE.
The file Standard Resources is provided with Guide Maker. This file contains external code modules, defined as resources of type 'extm'. The Standard Setup file contains <Define Context Check> commands that reference each external module. The context checks defined by these commands can be used to specify a condition in <If>, <Skip If>, <Make Sure>, and <Start Making Sure> commands.

EXAMPLES
#define a context check called "isSomethingActive"
# (with resource name 'MyEM') 
# that has 3 parameters: the first (short) and 
# third (long) are specified by the context check to have 
# default values of 10 and 30
# the second parameter is of type LPSTRING and the caller
# is required to provide this value
<Define Context Check> "isSomethingActive", 'MyEM', 'WAVE', 
                     SHORT:10, LPSTRING, LONG:30
<Define Sequence> "using the ruler"
   <If> isSomethingActive("Object1")
      <Panel> "Panel to display if context check is true"
   <Else>
      <Panel> "Panel to display if context check is false"
   <End If>
<End Sequence> 
SEE ALSO
For information on the <If>, <Skip If>, <Make Sure>, and <Start Making Sure> commands, see page 10-153, page 10-160, page 10-162, and page 10-168, respectively.