Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Dialog Manager Routines / Handling Text in Alert and Dialog Boxes

ParamText

To substitute text strings in the static text items of your alert or dialog boxes while your application is running, use the ParamText procedure.

PROCEDURE ParamText (param0: Str255; param1: Str255; 
                     param2: Str255; param3: Str255);

param0

A text string to substitute for the special string ^0 in the static text items of all subsequently created alert and dialog boxes.

param1

A text string to substitute for the special string ^1 in the static text items of all subsequently created alert and dialog boxes.

param2

A text string to substitute for the special string ^2 in the static text items of all subsequently created alert and dialog boxes.

param3

A text string to substitute for the special string ^3 in the static text items of all subsequently created alert and dialog boxes.

DESCRIPTION

The ParamText procedure replaces the special strings ^0 through ^3 in the static text items of all subsequently created alert and dialog boxes with the text strings you pass as parameters. Pass empty strings (not NIL) for parameters not used.

SPECIAL CONSIDERATIONS

The strings used in ParamText are stored in the low-memory global variable DAStrings, which specifies a set of string handles used by the Dialog Manager.
If the user launches a desk accessory in your application's partition and the desk accessory calls ParamText, it may change the text in your application's dialog box.

You should be very careful about using ParamText in modeless dialog boxes. If a modeless dialog box using ParamText is onscreen and you display another dialog box or alert box that also uses ParamText, both boxes will be affected by the latest call
to ParamText.

The strings you pass in the parameters to ParamText cannot contain the special strings ^0 through ^3, or else the procedure will enter an endless loop of substitutions in versions of system software earlier than 7.1.

Note that you should try to store text strings in resource files to facilitate translation into other languages; therefore, ParamText is best used for supplying text strings, such as document names, that the user specifies. To avoid problems with grammar and sentence structure when you localize your application, you should use ParamText to supply only one text string per screen message.

SEE ALSO

Listing 6-9 on page 6-47 and Listing 6-10 on page 6-48 show an example of how you can use ParamText to supply the title of the user's current document to your alert and dialog boxes. If you need to supply a default text string to an editable text item while your application is running, use SetDialogItemText. The SetDialogItemText procedure also allows you to set or change the entire text string for a static text item.