ADC Home > Reference Library > Reference > Carbon > Text & Fonts > Script Manager Reference (Not Recommended) >

< Previous PageNext Page > Hide TOC

Legacy Documentclose button

Important: The Script Manager is deprecated as of Mac OS X v10.5. Instead, you should update your application to handle Unicode text using the facilities of the Cocoa system (see Text System Overview) or Core Text (see Core Text Programming Guide). See also Internationalization Programming Topics.

Deprecated Script Manager Reference (Not Recommended) Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

CharacterByteType

Identifies a byte in a text buffer as a single-byte character or as the first or second byte of a double-byte character. (Deprecated in Mac OS X v10.4. You should update your application to handle Unicode text. There is no replacement function because Unicode handles encoding in a different manner.)

short CharacterByteType (
   Ptr textBuf,
   short textOffset,
   ScriptCode script
);

Parameters
textBuf

A pointer to a text buffer containing the byte to be identified.

textOffset

The offset to the byte to be identified. The offset is measured in bytes; the first byte has an offset of 0.

script

A value that specifies the script system of the text in the buffer. Constants for all defined script codes are listed on “Meta Script Codes.” To specify the font script, pass smCurrentScript in this parameter.

Return Value

One of three identifications: a single-byte character, the first byte of a double-byte character, or the second byte of a double-byte character. The first byte of a double-byte character—the one at the lower offset in memory—is the high-order byte the second byte of a double-byte character—the one at the higher offset—is the low-order byte. This is the same order in which text is processed and numbers are represented.

Discussion

The script system associated with the character you wish to examine must be enabled in order for the function to provide useful information. For example, if only the Roman script system is available and you attempt to identify a byte in a run of double-byte characters, the CharacterByteType function returns 0, indicating that the byte is a single-byte character.

For single-byte script systems, the character-type tables reside in the string-manipulation ('itl2') resource and reflect region-specific or language-specific differences in uppercase conventions.

For double-byte script systems, the character-type tables reside in the encoding/rendering ('itl5') resource, not the string-manipulation resource. Whenever you call CharacterByteType, the necessary character-set encoding information is taken from the encoding/rendering resource. You cannot use the GetIntlResource function to access double-byte character-type tables directly.

From byte value alone, it is not possible to distinguish the second byte of a double-byte character from a single-byte character. CharacterByteType differentiates the second byte of a double-byte character from a single-byte character by assuming that the byte at offset 0 is the first byte of a character. With that assumption, it then sequentially identifies the size and starting position of each character in the buffer up to textOffset.

Special Considerations

If you specify smCurrentScript for the script parameter, the value returned by CharacterByteType can be affected by the state of the font force flag. It is unaffected by the state of the international resources selection flag.

Availability
Declared In
Script.h

CharacterType

Returns a variety of information about the character represented by a given byte, including its type, class, orientation, direction, case, and size (in bytes). (Deprecated in Mac OS X v10.4. You should update your application to handle Unicode text. There is no replacement function because Unicode handles encoding in a different manner.)

short CharacterType (
   Ptr textBuf,
   short textOffset,
   ScriptCode script
);

Parameters
textBuf

A pointer to a text buffer containing the character to be examined.

textOffset

The offset to the location of the character to be examined. (It can be an offset to either the first or the second byte of a double-byte character.) Offset is in bytes; the first byte of the first character has an offset of 0.

script

A value that specifies the script system the byte belongs to. Constants for all defined script codes are listed in “Meta Script Codes.” To specify the font script, pass smCurrentScript in this parameter.

Return Value

An integer bit field that provides information about the requested character.

Discussion

The CharacterType return value is an integer bit field that provides information about the requested character. The field has the following format:

The script system associated with the character you wish to examine must be enabled in order for any of these three functions to provide useful information.

For single-byte script systems, the character-type tables reside in the string-manipulation ('itl2') resource and reflect region-specific or language-specific differences in uppercase conventions. The CharacterType function gets the tables from the string-manipulation resource using the GetIntlResource function.

For double-byte script systems, the character-type tables reside in the encoding/rendering ('itl5') resource, not the string-manipulation resource. Whenever you call CharacterType, the necessary character-set encoding information is taken from the encoding/rendering resource. You cannot use the GetIntlResource function to access double-byte character-type tables directly.

The Script Manager defines the recognized character types, character classes, and character modifiers (bits 12–15), with constants to describe them. The CharacterType field masks are described in “Character Type Field Masks.”

The Script Manager also defines a set of masks with which you can isolate each of the fields in the CharacterType return value. If you perform an AND operation with the CharacterType result and the mask for a particular field, you select only the bits in that field. Once you’ve done that, you can test the result, using the constants that represent the possible results.

The function CharacterType calls CharacterByteType to determine whether the byte at textOffset is a single-byte character or the first byte or second byte of a double-byte character. The larger the text buffer, the longer CharacterByteType takes to execute. To be most efficient, place the pointer textBuf at the beginning of the character of interest before calling CharacterType. (If you want to be compatible with older versions of CharacterType, also set textOffset to 1, rather than 0, for double-byte characters.)

Special Considerations

The function CharacterType may move memory; your application should not call this function at interrupt time.

If you specify smCurrentScript for the script parameter, CharacterType always assumes that the text in the buffer belongs to the font script. It is unaffected by the state of the font force flag or the international resources selection flag.

For single-byte script systems, the character-type tables are in the string-manipulation ('itl2') resource. For double-byte script systems, they are in the encoding/rendering ('itl5') resource. If the appropriate resource does not include these tables, CharacterType exits without doing anything.

Some Roman fonts (for example, Symbol) substitute other characters for the standard characters in the Standard Roman character set. Since the Roman script system CharacterType function assumes the Standard Roman character set, it may return inappropriate results for nonstandard characters.

Version Notes

In versions of system software earlier than 7.0, the textOffset parameter to the CharacterType function must point to the second byte of a double-byte character.

Availability
Declared In
Script.h

ClearIntlResourceCache

Clears the application’s international resources cache, which contains the resource ID numbers of the string-manipulation ('itl2') and tokens ('itl4') resources for the current script. (Deprecated in Mac OS X v10.4. There is no replacement because this function is no longer needed in Mac OS X.)

Not recommended

void ClearIntlResourceCache (
   void
);

Discussion

At application launch, the script management system sets up an international resources cache for the application. The cache contains the resource ID numbers of the string-manipulation and tokens resources for all enabled scripts.

If you provide your own string manipulation or tokens resource to replace the default for a particular script, call ClearIntlResourceCache at launch to ensure that your supplied resource is used instead of the script system’s 'itl2' or 'itl4' resource.

The current default ID numbers for a script system’s 'itl2' and 'itl4' resources are stored in its script variables. You can read and modify these values with the GetScriptVariable and SetScriptVariable functions using the selectors smScriptSort (for the 'itl2' resource) and smScriptToken (for the 'itl4' resource). Before calling ClearIntlResourceCache, you should set the script’s default ID number to the ID of the resource that you are supplying.

If the international resources selection flag is TRUE, the ID numbers of your supplied resources must be in the system script range. Otherwise, the IDs must be in the range of the current script.

If you use the SetScriptVariable function to change the value of the 'itl2' or 'itl4' resource ID and then call ClearIntlResourceCache to flush the cache, be sure to restore the original resource ID before your application quits.

Special Considerations

The function ClearIntlResourceCache may move memory; your application should not call this function at interrupt time.

Availability
Declared In
Script.h

FillParseTable

Helps your application to quickly process a buffer of mixed single-byte and double-byte characters. (Deprecated in Mac OS X v10.4. You should update your application to handle Unicode text. There is no replacement function because Unicode handles encoding in a different manner.)

Boolean FillParseTable (
   CharByteTable table,
   ScriptCode script
);

Parameters
table

A 256-byte table to be filled in by FillParseTable.

script

A value that specifies the script system the parse table belongs to. Constants for all defined script codes are listed in “Meta Script Codes.” To specify the font script, pass smCurrentScript in this parameter.

Return Value

If you specify smCurrentScript for the script parameter, the value returned by FillParseTable can be affected by the state of the font force flag. It is unaffected by the international resources selection flag.

Discussion

Before calling FillParseTable, allocate space for a 256-byte table to pass to the function in the table parameter.

This function returns a 256-byte table that distinguishes the character codes of all possible single-byte characters from the first (high-order) byte values of all possible double-byte characters in the specified script system. The script system associated with the character you wish to examine must be enabled in order for any of these three functions to provide useful information.

For single-byte script systems, the character-type tables reside in the string-manipulation ('itl2') resource and reflect region-specific or language-specific differences in uppercase conventions.

For double-byte script systems, the character-type tables reside in the encoding/rendering ('itl5') resource, not the string-manipulation resource. Whenever you call FillParseTable, the necessary character-set encoding information is taken from the encoding/rendering resource. You cannot use the GetIntlResource function to access double-byte character-type tables directly.In every script system, double-byte characters have distinctive high-order (first) bytes that allow them to be distinguished from single-byte characters. FillParseTable fills a 256-byte table, conceptually equivalent to a single-byte character-set table, with values that indicate, byte-for-byte, whether the character-code value represented by that byte index is the first byte of a double-byte character. An entry in the CharByteTable is 0 for a single-byte character and 1 for the first byte of a double-byte character.

If your application is processing mixed characters, it can use the table to identify the locations of the double-byte characters as it makes a single pass through the text, rather than having to call CharacterByteType or CharacterType for each byte of the text buffer in turn. CharacterByteType and CharacterType start anew at the beginning of the text buffer each time they are called, tracking character positions up to the offset of the byte to be analyzed.

Special Considerations

FillParseTable may move memory; your application should not call this function at interrupt time.

The table defined by CharByteTable is not dynamic; it does not get updated when the current font changes. You need to call it separately for each script run in your text.

Availability
Declared In
Script.h

FontScript

Returns the script code for the current script (usually the font script). (Deprecated in Mac OS X v10.4. Use ATSFontFamilyGetEncoding instead.)

short FontScript (
   void
);

Parameters
Return Value

A script code. All recognized script codes and their defined constants are listed in “Meta Script Codes.” FontScript returns only explicit script codes (≥ 0). If the font of the active graphics port is Roman and the font force flag is TRUE, the script code returned is that of the system script and the script-forced result flag is set to TRUE. If the font of the active graphics port is non-Roman, the state of the font force flag is ignored. If the script system corresponding to the font of the active graphics port is not installed and enabled, the script code returned is that of the system script and the script-defaulted result flag is set to TRUE.

Discussion

The information about the script code is subject to two control flags—the font force flag and the international resources selection flag. You can test and set these flags with the GetScriptManagerVariable and SetScriptManagerVariable selectors smFontForce and smIntlForce.

The function starts by initializing two result flags, the script-forced result flag and the script-defaulted result flag, to FALSE. These flags are Script Manager variables, accessed through the GetScriptManagerVariable function selectors smForced and smDefault.

Special Considerations

FontScript may move memory; your application should not call this function at interrupt time.

Availability
Declared In
Script.h

FontToScript

Translates a font family ID number into its corresponding script code, if that script system is currently enabled. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyGetEncoding instead.)

short FontToScript (
   short fontNumber
);

Parameters
fontNumber

A font family ID number.

Return Value

A script code. All recognized script codes and their defined constants are listed in “Meta Script Codes.” FontToScript returns only explicit script codes (≥ 0). If fontNumber is in the Roman range and the font force flag is TRUE, the script code returned is that of the system script and the script-forced result flag is set to TRUE. If fontNumber is in the non-Roman range, the state of the font force flag is ignored. If the script system corresponding to fontNumber is not enabled, the script code returned is that of the system script and the script-defaulted result flag is set to TRUE.

Discussion

The information about the script code is subject to two control flags—the font force flag and the international resources selection flag. You can test and set these flags with the GetScriptManagerVariable and SetScriptManagerVariable selectors smFontForce and smIntlForce.

The function starts by initializing two result flags, the script-forced result flag and the script-defaulted result flag, to FALSE. These flags are Script Manager variables, accessed through the GetScriptManagerVariable function selectors smForced and smDefault.

Do not use the function FontToScript to convert resource IDs to scripts codes.

Special Considerations

FontToScript may move memory; your application should not call this function at interrupt time.

Availability
Declared In
Script.h

GetIntlResourceTable

Obtains a specific word-selection, line-break, number-parts, untoken, or whitespace table from the appropriate international resource. (Deprecated in Mac OS X v10.4. There is no replacement because this function is no longer needed in Mac OS X.)

void GetIntlResourceTable (
   ScriptCode script,
   short tableCode,
   Handle *itlHandle,
   long *offset,
   long *length
);

Parameters
script

A script code, the value that specifies a particular script system. Constants for all defined script codes are listed in “Meta Script Codes.”

tableCode

A number that specifies which table is requested. The constants for tableCode are detailed in “Table Selectors.”

itlHandle

On return, a handle to the string-manipulation ('itl2') or tokens ('itl4') resource containing the table specified in the tableCode parameter. If the script system whose table is requested is not available, GetIntlResourceTable returns a NULL handle.

offset

On return, a pointer to the offset (in bytes) to the specified table from the beginning of the resource.

length

On return, a pointer to the size of the table (in bytes).

Discussion

When you provide a script code in the script parameter, and a table code in the tableCode parameter, GetIntlResourceTable returns a handle to the string-manipulation resource or tokens resource containing that table, the offset of the specified table from the beginning of the resource, and the length of the table.

If you wish to manipulate the contents of the table you have requested, use the size returned in the length parameter to allocate a buffer, and perform a block move of the table’s contents into that buffer.

Special Considerations

GetIntlResourceTable may move memory; your application should not call this function at interrupt time.

Availability
Declared In
Script.h

GetSysDirection

Returns the current value of SysDirection, the global variable that determines the system direction (primary line direction). (Deprecated in Mac OS X v10.4. This function does not return anything useful in Mac OS X.)

short GetSysDirection (
   void
);

Parameters
Return Value

The current value of SysDirection: 0 if the system direction is left-to-right; -1 ($FFFF) if the system direction is right-to-left.

Availability
Declared In
Script.h

IntlScript

Identifies the script system used by the Text Utilities date-formatting, time-formatting, and string-sorting functions. (Deprecated in Mac OS X v10.4. Use ATSFontFamilyGetEncoding instead.)

short IntlScript (
   void
);

Parameters
Return Value

A script code. All recognized script codes and their defined constants are listed in “Meta Script Codes.” IntlScript returns only explicit script codes (≥ 0). If the international resources selection flag is TRUE, the script code returned is that of the system script. If the identified script system is not enabled, the script code returned is that of the system script and the script-defaulted result flag is set to TRUE.

Discussion

Information about the script system is subject to two control flags—the font force flag and the international resources selection flag. You can test and set these flags with the GetScriptManagerVariable and SetScriptManagerVariable selectors smFontForce and smIntlForce.

The function starts by initializing two result flags, the script-forced result flag and the script-defaulted result flag, to FALSE. These flags are Script Manager variables, accessed through the GetScriptManagerVariable function selectors smForced and smDefault.

The function also identifies the script system whose resources are returned by the Script Manager function GetIntlResource. It is either the font script—the script system corresponding to the current font of the active graphics port—or the system script.

Special Considerations

IntlScript may move memory; your application should not call this function at interrupt time.

Availability
Declared In
Script.h

IntlTokenize

Allows your application to convert text into a sequence of language-independent tokens. (Deprecated in Mac OS X v10.4. There is no replacement because this function is no longer needed in Mac OS X.)

TokenResults IntlTokenize (
   TokenBlockPtr tokenParam
);

Parameters
tokenParam

A pointer to a token block structure. The structure specifies the text to be converted to tokens, the destination of the token list, a handle to the tokens ('itl4') resource, and a set of options. See the TokenBlockdata structure for information on what you need to pass in this structure and what you obtain on return.

Return Value

A TokenResults value that specifies whether the function executed with errors. See “Token Results” for a list of the values that can be returned.

Discussion

Before calling the IntlTokenize function, allocate memory for and set up the following data structures:

The function IntlTokenize creates tokens based on information in the tokens ( 'itl4') resource of the script system under which the source text was created. You must load the tokens resource and place its handle in the token block structure before calling the IntlTokenize function.

The token block structure contains both input and output values. At input, you must provide values for the fields that specify the source text location, the token list location, the size of the token list, the tokens ( 'itl4') resource to use, and several options that affect the operation. You must set reserved locations to 0 before calling IntlTokenize.

On output, the token block structure specifies how many tokens have been generated and the size of the string list (if you have selected the option to generate strings).

The results of the tokenizing operation are contained in the token list, an array of token structures (data type TokenRec ).

Pascal strings are generated if the doString parameter in the token block structure is set to TRUE. The string is a normalized version of the source text that generated the token; alternate digits are replaced with ASCII numerals, the decimal point is always an ASCII period, and double-byte Roman letters are replaced with low-ASCII equivalents.

To make a series of calls to IntlTokenize and append the results of each call to the results of previous calls, set doAppend to FALSE and initialize tokenCount and stringCount to 0 before making the first call to IntlTokenize. (You can ignore stringCount if you set doString to FALSE.) Upon completion of the call, tokenCount and stringCount will contain the number of tokens and the length in bytes of the string list, respectively, generated by the call. On subsequent calls, set doAppend to TRUE, reset the source and sourceLength parameters (and any other parameters as appropriate) for the new source text, but maintain the output values for tokenCount and stringCount from each call as input values to the next call. At the end of your sequence of calls, the token list and string list will contain, in order, all the tokens and strings generated from the calls to IntlTokenize.

If you are making tokens from text that was created under more than one script system, you must load the proper tokens resource and place its handle in the token block structure separately for each script run in the text, appending the results each time.

Delimiters for quoted literals are passed to IntlTokenize in a two-integer array.

The individual delimiters, as specified in the leftDelims and rightDelims parameters, are paired by position. The first (in storage order) opening delimiter in leftDelims is paired with the first closing delimiter in rightDelims.

Comment delimiters may be 1 or 2 tokens each and there may be two sets of opening and closing pairs. They are passed to IntlTokenize in a commentType array.

If only one token is needed for a delimiter, the second token must be specified to be delimPad. If only one delimiter of an opening-closing pair is needed, then both of the tokens allocated for the other symbol must be delimPad. The first token of a two-token sequence is at the higher position in the leftComment or rightComment array.

When IntlTokenize encounters an escape character within a quoted literal, it places the portion of the literal before the escape character into a single token (of type tokenLiteral), places the escape character into another token ( tokenEscape), places the character following the escape character into another token (whatever token type it corresponds to), and places the portion of the literal following the escape sequence into another token ( tokenLiteral). Outside of a quoted literal, the escape character has no special significance.

IntlTokenize considers the character specified in the decimalCode parameter to be a decimal character only when it is flanked by numeric or alternate numeric characters, or when it follows them.

Special Considerations

IntlTokenize may move memory; your application should not call this function at interrupt time.

Because each call to IntlTokenize must be for a single script run, there can be no change of script within a comment or quoted literal.

Comments and quoted literals must be complete within a single call to IntlTokenize in order to avoid syntax errors.

IntlTokenize always uses the tokens resource whose handle you pass it in the token block structure. Therefore, it is not directly affected by the state of the font force flag or the international resources selection flag. However, if you use the GetIntlResource function to get a handle to the tokens resource to pass to IntlTokenize, remember that GetIntlResource is affected by the state of the international resources selection flag.

Availability
Declared In
Script.h

SetSysDirection

Sets the value of SysDirection, the global variable that determines the system direction (primary line direction). (Deprecated in Mac OS X v10.4. There is no replacement because this function is no longer needed in Mac OS X.)

void SetSysDirection (
   short value
);

Parameters
value

The desired value for SysDirection:0 if you wish the system direction to be left-to-right and -1 ($FFFF) if you wish the system direction to be right-to-left.

Return Value
Discussion

The value of SysDirection is initialized from the system’s international configuration resource, and may be controlled by the user. Your application can use the SetSysDirection function to change SysDirection while drawing, but should restore it when appropriate (such as when your application becomes inactive).

Availability
Declared In
Script.h

TransliterateText

Converts characters from one subscript to the closest possible approximation in a different subscript within the same double-byte script system. (Deprecated in Mac OS X v10.4. Use CFStringUppercase instead.)

OSErr TransliterateText (
   Handle srcHandle,
   Handle dstHandle,
   short target,
   long srcMask,
   ScriptCode script
);

Parameters
srcHandle

A handle to the source text to be transliterated. The TransliterateText function converts all of the text that you pass it in this parameter. It determines the length of the source text (in bytes) from the handle size.

dstHandle

A handle to a buffer that, upon completion of the call, contains the transliterated text.

Before calling TransliterateText, allocate a handle (of any size) to pass in the dstHandle parameter. The length of the transliterated text may be different (as when converting between single-byte and double-byte characters), and TransliterateText sets the size of the destination handle as required. It is your responsibility to dispose of the destination handle when you no longer need it.

target

A value that specifies what kind of text the source text is to be transliterated into.

The low byte of the target is the format to convert to (the target format). It determines what form the text should be transliterated to. In all script systems, there are two currently supported values for target format: smTransAscii and smTransNative. In double-byte script systems, additional values are recognized.

The high byte is the target modifier; it contains modifiers, whose meanings depend on the script code, providing additional formatting instructions. In all script systems, there are two values for target modifier: smTransLower and smTransUpper.

srcMask

A bit array that specifies which parts of the source text are to be transliterated. A bit is set for each script system or subscript that should be converted to the target format. In all script systems, the srcMask parameter may have the following values: smMaskAscii, smMaskNative, and smMaskAll. In double-byte script systems, additional values are recognized.

script

A value that specifies the script system of the text to be transliterated. Constants for all defined script codes are listed in “Meta Script Codes.” To specify the font script, pass smCurrentScript in this parameter.

Return Value

A result code. See “Script Manager Result Codes.”

Discussion

Transliteration is the conversion of text from one form or subscript to another within a single script system. In the Roman script system, transliteration means case conversion. In double-byte script systems, it is the automatic conversion of characters from one subscript to another. One common use for transliteration is as an initial stage of text conversion for an input method.

TransliterateText also performs uppercasing and lowercasing, with consideration for regional variants, in the Roman script system and on Roman text within double-byte script systems.

Because the low-ASCII character set (character codes $20–$7F) is present in all script systems, you could theoretically use the TransliterateText function to convert characters from one script system into another completely different script system. You could transliterate from a native subscript into ASCII under one script system, and then transliterate from that ASCII into a native subscript under a different script system. Such a function is not recommended, however, because of the imperfect nature of phonetic translation. Furthermore, many script systems do not support transliteration from native subscripts to ASCII.

Special Considerations

TransliterateText may move memory; your application should not call this function at interrupt time.

If you pass smCurrentScript in the script parameter, the conversion performed by TransliterateText can be affected by the state of the font force flag. It is unaffected by the international resources selection flag.

Transliteration of a block of text does not work across script-run boundaries. Because the TransliterateText function requires transliteration tables that are in a script system’s international resources, you need to call it anew for each script run in your text.

Currently, the Roman version of TransliterateText checks the source mask only to ensure that at least one of the bits corresponding to the smMaskAscii and smMaskNative constants is set.

The Arabic and Hebrew versions of TransliterateText perform case conversion only. They allow the target values smTransAscii and smTransNative only; otherwise, they behave like the Roman version.

The TransliterateText tables for single-byte script systems reside in the script’s string-manipulation ('itl2') resource, so they can reflect region-specific or language-specific differences in uppercase conventions. If the string-manipulation resource does not include these tables, TransliterateText exits without doing anything.

The TransliterateText tables for double-byte script systems reside in the script’s transliteration ('trsl') resource. If the 'trsl' resource does not include these tables, TransliterateText exits without doing anything.

The Japanese, Traditional Chinese, and Simplified Chinese versions of TransliterateText have two modes of operation. If either smMaskAscii or smMaskNative is specified in the source mask, and if the target is smTransAscii, and if either of the target modifiers is specified, TransliterateText performs the specified case conversion on both single-byte and double-byte Roman letters. Otherwise, TransliterateText performs conversions according to the target format values. Any combination of source masks and target format is permitted.

Availability
Declared In
Script.h

Deprecated in Mac OS X v10.5

GetIntlResource

Returns a handle to one of the international resources. (Deprecated in Mac OS X v10.5. The replacement for this function depends on the purpose for which it is used, as described in the Special Considerations section.)

Handle GetIntlResource (
   short theID
);

Parameters
theID

Contains an integer (0, 1, 2, 4, or 5 respectively for the 'itl0', 'itl1', 'itl2', 'itl4', and 'itl5'resources) to identify the type of the desired international resource.

Return Value

A handle to the correct resource of the requested type. The resource returned is that of the current script, which is either the font script or the system script. The resource is of one of the following types: numeric-format ('itl0'), long-date-format ('itl1'), string-manipulation ('itl2'), tokens ('itl4'), or encoding/rendering ('itl5'). If GetIntlResource cannot return the requested resource, it returns a NULL handle and sets the global variable resErr to the appropriate error code.

Special Considerations

Depending on the information that this function was called to obtain, it can be replaced by the use of CFLocaleCopyCurrent to get an appropriate CFLocaleRef followed by one of the following:

GetIntlResource may move memory; your application should not call this function at interrupt time.

Carbon Porting Notes

While the return type of this function remains a Handle, in Mac OS X it returns an ordinary memory handle instead of a resource handle.

Availability
Declared In
Script.h

GetScriptManagerVariable

Retrieves the value of the specified Script Manager variable. (Deprecated in Mac OS X v10.5. The replacement for this function depends on the selector used with it, as described in the Special Considerations section.)

long GetScriptManagerVariable (
   short selector
);

Parameters
selector

A value that specifies a particular Script Manager variable. To specify the Script Manager variable whose value you need, use one of the selector constants listed in “Script Manager Selectors.”

Return Value

The current value of the specified Script Manager variable or 0 if the selector is invalid. For some valid selectors, 0 may also be a valid return value. For example, when you call GetScriptManagerVariable with a selector value of smRegionCode on a version of Macintosh system software that has been localized for the United States, it returns 0. Although GetScriptManagerVariable always returns a long integer, the actual value may be a long integer, standard integer, or signed byte. If the value is not a long integer, it is stored in the low-order word or byte of the long integer returned by GetScriptManagerVariable; the remaining bytes are set to 0.

Discussion

The Script Manager maintains a set of variables that control general settings of the text environment, including the identity of the system script and the keyboard script, and the settings of the font force flag and the international resources selection flag.

You may want access to the Script Manager variables in order to understand the current environment or to modify it.

Special Considerations

The replacement for this function depends on the selector used with it. Many of the selectors refer to information that is not meaningful on a Unicode system or refer to details of the Script Manager itself; in general there are no replacements for these. Selectors that have meaningful replacements are shown in the following list. These are not direct replacements; they provide analogous but more modern functionality.

Selectors that have no meaningful replacement on a Unicode system include smEnabled, smBidirect, and smDoubleByte. Selectors that pertain to internal operation of the Script Manager itself and thus have no meaningful replacement include smVersion, smMunged, smPrint, and smSysRef.

Availability
Declared In
Script.h

GetScriptVariable

Retrieves the value of the specified script variable from the specified script system. (Deprecated in Mac OS X v10.5. The replacement for this function depends on the selector used with it, as described in the Special Considerations section.)

long GetScriptVariable (
   short script,
   short selector
);

Parameters
script

A value that specifies the script system whose variable you are accessing. Use one of the script-code constants listed in “Meta Script Codes.”

selector

A value that specifies a particular script variable. Use one of the selector constants listed in “Script Variable Selectors.” Valid selector values are defined by each script system.

Return Value

0 if the selector value is invalid or if the specified script system is not installed. For some valid selectors, 0 may also be a valid return value. For example, calling GetScriptVariable with a selector of smScriptLang on a version of Macintosh system software that has been localized for the United States returns 0. Although GetScriptVariable always returns a long integer, the actual value may be a long integer, standard integer, or signed byte. If the value is not a long integer, it is stored in the low-order word or byte of the long integer returned by GetScriptVariable; the remaining bytes are set to 0.

Discussion

Each enabled script system maintains a set of variables that control the current settings of that script system, including the ID numbers of its international resources, its preferred fonts and font sizes, and its primary line direction.

Special Considerations

The replacement for this function depends on the selector used with it. Many of the selectors refer to information that is not meaningful on a Unicode system or refer to details of the Script Manager itself; in general there are no replacements for these. Selectors that have meaningful replacements are shown in the following list. These are not direct replacements; they provide analogous but more modern functionality.

Availability
Declared In
Script.h

SetScriptManagerVariable

Sets the specified Script Manager variable to the value of the input parameter. (Deprecated in Mac OS X v10.5. This is mainly used to set the value of variables that control the internal operation of the Script Manager (selectors smIntlForce and smGenFlags), and therefore there is no modern replacement.)

OSErr SetScriptManagerVariable (
   short selector,
   long param
);

Parameters
selector

A value that specifies a particular Script Manager variable. To specify the Script Manager variable whose value you wish to change, use one of the selector constants listed in “Script Manager Selectors.”

param

The new value for the specified Script Manager variable.

The actual values to be assigned may be long integers, standard integers, or signed bytes. If the value is other than a long integer, you must store it in the low-order word or byte of the param parameter and set the unused bytes to 0.

Return Value

A result code. See “Script Manager Result Codes.” The value smBadVerb if the selector is not valid. Otherwise, the function returns 0 (noErr).

Discussion

The Script Manager maintains a set of variables that control general settings of the text environment, including the identity of the system script and the keyboard script, and the settings of the font force flag and the international resources selection flag.

You may want access to the Script Manager variables in order to understand the current environment or to modify it.

Availability
Declared In
Script.h

SetScriptVariable

Sets the specified script variable for the specified script system to the value of the input parameter. (Deprecated in Mac OS X v10.5. The replacement for this function depends on the purpose for which it is used, as described in the Special Considerations section.)

OSErr SetScriptVariable (
   short script,
   short selector,
   long param
);

Parameters
script

A value that specifies the script system whose variable you are setting. Use one of the script-code constants listed in “Meta Script Codes.”

selector

A value that specifies a particular script variable. Use one of the selector constants listed in “Script Variable Selectors.”

param

The new value for the specified script variable. The actual value to be assigned may be a long integer, standard integer, or signed byte. If the value is not a long integer, you must store it in the low-order word or byte of the param parameter and set the unused bytes to 0.

Return Value

A result code. See “Script Manager Result Codes.” The value smBadVerb if the selector is not valid, and smBadScript if the script is invalid. Otherwise, 0 (noErr).

Discussion

Each enabled script system maintains a set of variables that control the current settings of that script system, including the ID numbers of its international resources, its preferred fonts and font sizes, and its primary line direction.

Special Considerations

The replacement for this function depends on whether the goal is to set the keyboard layout globally or for a specific TSM document. To set it globally, use TISSelectInputSource. To set it for a specific document, use the TSM document property kTSMDocumentInputSourceOverridePropertyTag.

Availability
Declared In
Script.h

< Previous PageNext Page > Hide TOC

© 2003, 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-12-11)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.