Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 10 - Scripting Components / Scripting Components Reference

Required Scripting Component Routines / Executing and Disposing of Scripts

OSADisplay

You can use the OSADisplay function to convert a script value to text. Your application can then use its own routines to display this text to the user.

FUNCTION OSADisplay(scriptingComponent: ComponentInstance;
                    scriptValueID: OSAID; 
                    desiredType: DescType;
                    modeFlags: LongInt;
                    VAR resultingText: AEDesc): OSAError;

scriptingComponent

A component instance created by a prior call to the Component Manager function OpenDefaultComponent or OpenComponent (see page 10-4).

scriptValueID

The script ID for the script value to coerce.

desiredType

The desired text descriptor type, such as typeChar, for the resulting descriptor record.

modeFlags

Information used by individual scripting components. To avoid setting any mode flags, specify kOSAModeNull. To make the resulting text readable by humans only, so that it can't be recompiled, specify kOSAModeDisplayForHumans.

resultingText

The resulting descriptor record.

DESCRIPTION

The OSADisplay function coerces the script value identified by scriptValueID to a descriptor record of the text type specified by the desiredType parameter, if possible. Valid types include all the standard text descriptor types defined in the Apple Event Registry: Standard Suites, plus any special types supported by the scripting component.

Unlike OSAGetSource, OSADisplay can coerce only script values and always produces a descriptor record of a text descriptor type. In addition, if you specify the mode flag kOSAModeDisplayForHumans, the resulting text cannot be recompiled.

SPECIAL CONSIDERATIONS

If you want to get a script value in a form that you can display for humans to read, use OSADisplay. If you want the descriptor type of the descriptor record returned in the resultingText parameter to be the same as the descriptor type returned by a scripting component, use OSACoerceToDesc and specify typeWildCard as the desired type.

RESULT CODES

noErr	0	No error
errOSACantCoerce	-1700	Desired type not supported by scripting component
errOSASystemError	-1750	General scripting system error
errOSAInvalidID	-1751	Invalid script ID
badComponentInstance	$80008001	Invalid component instance

SEE ALSO

For descriptions of the OSAGetSource and OSACoerceToDesc functions, see page 10-51 and page 10-54, respectively.

For an example of the use of OSADisplay, see Listing 10-2 on page 10-9.