Legacy Document

Inside Macintosh: Text /

Appendix A - Built-in Script Support / WorldScript I

Replacing a Script Utility or QuickDraw Patch

Developers of 1-byte complex script systems should be able to specify most of their script system's behavior in tables in the script system's encoding/rendering ('itl5') resource. In cases where the WorldScript I routines are insufficient to handle the script's specific needs, the developers may create patches and install them as described here. The patches may be installed by an extensions file that is executed at system startup.

Application developers who need specific script-based behavior for their programs should not alter the tables in a 1-byte script's encoding/rendering ('itl5') resource. However, they can replace one or more 1-byte script utilities or QuickDraw patches for their target script system, as described here.

IMPORTANT

When you patch a script system's script utility or QuickDraw call, you alter that script's behavior for as long as it remains enabled. Therefore, be sure to restore the patches to their original state whenever your application quits or is switched out by the Process Manager.

The script-based dispatch table design gives you a simple, flexible way to replace individual routines without having to patch out all of the _ScriptUtil trap or any of the QuickDraw low-level routines in their entirety. Furthermore, in a multiscript environment each patch of this type applies only to its own script system. A developer might, for example, patch StdText for the Thai script system only, leaving all the other scripts unchanged.

In addition, you can choose the point at which your patched routine executes: either before (which also means in place of if your routine does not call the WorldScript I routine at all) or after the WorldScript I routine executes. For example, the WorldScript I version of StdText works by first performing contextual analysis and reordering of characters on the supplied text, and then calling the original version of StdText. Suppose you want to keep the WorldScript I contextual analysis and reordering of characters, but you want to do some additional processing before calling the original StdText. To do that, just patch out the WorldScript I routine's call to the original StdText, instead of patching out the entire WorldScript I routine. Then do your own processing and call StdText yourself.

Because you can patch at two points, and because you can perform your own processing either before or after a patch, your flexibility is great. To replace only the WorldScript I routine, replace its pointer in the dispatch table; to keep the WorldScript I routine while replacing or patching the original routine, replace the original-routine pointer in the dispatch table. The four Script Manager routines that allow you to make those patches are GetScriptUtilityAddress, SetScriptUtilityAddress, GetScriptQDPatchAddress, and SetScriptQDPatchAddress. Either pointer in the dispatch table may be NIL, meaning that WorldScript I either doesn't patch the original routine or doesn't call the original routine.

Patching Script Utilities

In terms of how to patch them, the script utilities can be divided into different groups, depending on whether or not WorldScript I performs contextual formatting and whether or not it subsequently calls the original Roman version of the utility. See Table A-13. For utilities that perform contextual formatting, keep in mind that if you replace them you will have to handle formatting yourself. For utilities that subsequently call their original Roman version, you can replace either the WorldScript I version of the call or the Roman version or both, depending on what your needs are.

Table A-13 Classification of 1-byte script utilities by function

No formatting, do not call original Roman routine	No formatting, do call original Roman routine	May do formatting, do not call original Roman routine
CharacterByteType	CharacterType	HiliteText
GetScriptVariable	TransliterateText	VisibleLength
SetScriptVariable	FindWordBreaks	PixelToChar
FillParseTable	FindScriptRun	CharToPixel
PortionLine		DrawJustified
		MeasureJustified

Note that those script utilities that do not call their equivalent Roman routine nevertheless call QuickDraw StdText or StdTxMeas if the grafProcs field in the graphics port has been changed. Thus, if you have changed (patched) either of those QuickDraw routines, your patch will still be called. Conversely, if the grafProcs field is NIL, The WorldScript I script utilities do not necessarily call StdText or StdTxMeas.

If you are replacing a script utility, remember that its interface is similar to that of its equivalent high-level call as described in Inside Macintosh. The utility takes the same parameters in the same order, except that it gets one additional last parameter on the stack: a pointer to the script record. For example, if you are replacing VisibleLength, whose high-level interface is

FUNCTION VisibleLength (textPtr: Ptr; 
                        textLen: LongInt): LongInt;

your patch to the equivalent script utility should expect to receive parameters as if the high-level interface were

FUNCTION VisibleLength (textPtr: Ptr; 
                        textLen: LongInt;
                        scriptRecord: Ptr): LongInt;

Also, if your replacement calls the original routine, don't forget to pass the extra parameter to it.

Patching QuickDraw Routines

WorldScript I patches the low-level QuickDraw text-handling routines StdText and StdTxMeas, the high-level QuickDraw routine MeasureText, and the Font Manager routine FontMetrics.

The QuickDraw patches lay out lines of text according to the context and line-direction rules for a script system. In each case (except for MeasureText) the patch calls the original QuickDraw routine after performing the contextual formatting. The contextual formatting routines are called only for contextual scripts.

Table A-14 lists the patches and what they do. For those patches that perform contextual formatting, if you replace them you will have to handle formatting for line layout yourself. For all of them, you can replace either the WorldScript I patch or the standard QuickDraw call or both, depending on your needs.

Table A-14 Classification of 1-byte QuickDraw patches by function

Call	Function
FontMetrics	Returns font measurements
MeasureText	Calls MeasureJustified (with slop = 0)
StdText	Does formatting, then calls original routine
StdTxMeas	Does formatting, then calls original routine

Issues in Designing a Script Utility or QuickDraw Patch

Keep the following points in mind if you plan to replace one or more script utilities or QuickDraw patches in WorldScript I:

• In script systems compatible with WorldScript I, text handling typically involves WorldScript I contextual analysis followed by a call to the original Roman version of the routine. You need to know whether it is the WorldScript I functionality or the original functionality that you want your routine to replace, and you need to be sure that your routine is called only at the correct points in the process. More detailed information on text layout is found in the chapter "QuickDraw Text" in this book.
• Script utilities process text in individual style runs, whose boundaries are defined by the application. If your application supports styled text, each script utility will need to handle only individual style runs. But if your application supports unstyled text only, there may be mixed Roman and non-Roman characters in a single font. Before performing text layout, your script utility will have to separate the Roman characters into their own style runs, and assign them to an associated font, if your script system uses associated fonts.
• If you provide your own script utility, you need to be sure that text is not formatted more than once. Because script utilities might be called reentrantly during printing, you may want to save the port for each contextual analysis. Check this port against the current port for each possible contextual analysis request, so you can prevent the text from being formatted twice.
• Printing adds another level of complexity to the WorldScript I QuickDraw
  patches and your ability to patch out those patches. The QuickDraw dispatch
  table has special entries to support developer patching of routines in printing as well as for display. See the descriptions of the routines GetScriptQDPatchAddress
  and SetScriptQDPatchAddress in the chapter "Script Manager" in this book
  for more information. See also Macintosh Technical Note #174 for additional information on printing.