UpgradeScriptInfoToTextEncoding

Converts any combination of a Mac OS script code, a language code, a region code, and a font name to a text encoding.

pascal OSStatus UpgradeScriptInfoToTextEncoding (
                     ScriptCode iTextScriptID,
                     LangCode iTextLanguageID,
                     RegionCode iRegionID,
                     ConstStr255Param iTextFontname,
                     TextEncoding *oEncoding);

iTextScriptID

A valid Script Manager script code. The Mac OS Script Manager defines constants for script codes using this format: sm Xxx . To designate the system script, specify the meta-value of smSystemScript. To designate the current script based on the font specified in the graphics port (grafPort), specify the metavalue of smCurrentScript. To indicate that you do not want to provide a script code for this parameter, specify the constant kTextScriptDontCare. See Inside Macintosh: Text for more information on the Script Manager's script codes, language codes, and region codes.

iTextLanguageID

A valid Script Manager language code. The Mac OS Script Manager defines constants for language codes using this format: lang Xxx . To indicate that you do not want to provide a language code for this parameter, specify the constant kTextLanguageDontCare.

iRegionID

A valid Script Manager region code. The Mac OS Script Manager defines constants for region codes using this format: ver Xxx . To indicate that you do not want to provide a region code for this parameter, specify the constant kTextRegionDontCare.

iTextFontname

The name of a font associated with a particular text encoding specification, such as Symbol or Zapf Dingbats, or the name of any font that is currently installed on the system. To indicate that you do not want to provide a font name, specify a value of NULL.

oEncoding

A pointer to a value of type TextEncoding. On output, this value holds the text encoding specification that the function created from the other values you provided.

function result

A result code. This function returns paramErr if two or more of the input parameter values conflict in some way--for example, the Mac OS language code does not belong to the script whose script code you specified, or if the input parameter values are invalid. The function returns a kTECTableFormatErr result code if the internal mapping tables used for translation are invalid. For a list of other possible result codes, see Text Encoding Conversion Manager Result Codes .

DISCUSSION

The UpgradeScriptInfoToTextEncoding function allows you to derive a text encoding specification from script codes, language codes, region codes, and font names. A one-to-one correspondence exists between many of the Script Manager's script codes and a particular Mac OS text encoding base value. However, because text encodings are a superset of script codes, some combinations of script code, language code, region code, and font name might result in a different text encoding base value than would be the case if the translation were based on the script code alone.

When you call the UpgradeScriptInfoToTextEncoding function, you can specify any combination of its parameters, but you must specify at least one.

If you don't specify an explicit value for a script, language, or region code parameter, you must pass the don't-care constant appropriate to that parameter. If you don't specify an explicit value for iTextFontName, you must pass NULL. UpgradeScriptInfoToTextEncoding uses as much information as you supply to determine the equivalent text encoding or the closest approximation. If you provide more than one parameter, all parameters are checked against one another to ensure that they are valid in combination.

A font name, such as 'Symbol' or 'Zapf Dingbats', can indicate a particular text encoding base. Other font names can indicate particular variants associated with a particular text encoding base. Otherwise, the font name is used to obtain a script code, and this script code will be checked against any script code you supply (in this case, the font must be installed; if it is not, the function returns a paramErr result code). If you do not supply either a language code or a region code and the script code you supply or the one that is derived matches the system script, then the system's localization is used to determine the appropriate region and language code. This is used for deriving text encoding base values that depend on region and language, such as kTextEncodingMacTurkish.

Legacy Document

UpgradeScriptInfoToTextEncoding

DISCUSSION

SEE ALSO