![]() |
ATSUMatchFontsToText |
||||
Header: | ATSUnicode.h | Carbon status: | Supported | |
Suggests a substitute font when a font does not have all the glyphs for the characters it is trying to draw.
OSStatus ATSUMatchFontsToText ( ATSUTextLayout iTextLayout, UniCharArrayOffset iTextStart, UniCharCount iTextLength, ATSUFontID *oFont, UniCharArrayOffset *oChangedOffset, UniCharCount *oChangedLength );
A reference to an initialized text layout object whose optimal substitute fonts you wish to determine. You cannot pass NULL for this parameter.
The edge offset corresponding to the beginning of the range of text that you want ATSUMatchFontsToText to scan for characters that could not be drawn with the assigned font. To start at the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in
The length of the range of text that you want ATSUMatchFontsToText to scan for characters that could not be drawn with the assigned font. If you want the range of text to extend to the end of the text buffer, pass the constant kATSUToTextEnd, described in
On return, a pointer to the font ID of the substitute font recommended by ATSUMatchFontsToText.
On return, a pointer to the edge offset corresponding to the beginning of the range of text containing the characters that could not be drawn with the assigned font.
On return, a pointer to the length of the range of text containing the characters that could not be drawn with the assigned font.
A result code. The result code noErr indicates that all the characters can be rendered with their currently assigned fonts. The result code kATSUFontsMatched indicates that at least one character could not be rendered with its currently assigned font. ATSUMatchFontsToText passes back the best substitute font to use in drawing the characters in the text range. The result code kATSUFontsNotMatched indicates that at least one character could not be rendered either with its currently assigned font or with any currently active font. ATSUMatchFontsToText suggests the last resort font for the substitute font, and passes back kATSUInvalidFontID in the oFont parameter. If ATSUMatchFontsToText returns the result codes kATSUFontsMatched or kATSUFontsNotMatched, you should update the input range and call ATSUMatchFontsToText again to make sure that all the characters in the range could be drawn.
The ATSUMatchFontsToText function passes back an offset to the first character in a range of text whose font does not have all the glyphs necessary to draw it and recommends the first valid font that it finds when sequentially scanning the fonts in the users system. ATSUMatchFontsToText recommends substitute fonts, but does not perform the font substitution. If you want ATSUI to perform font substitution, you should call the function ATSUSetTransientFontMatching.
If the subrange of text for which you wanted to perform font substitution was the text abcde, and the characters ‘c and ‘d could not be drawn with the current font but could be drawn with font F, and the character ‘e could either be drawn with the current font or could not be drawn with font F, then ATSUMatchFontsToText will pass back the ID of font F in the oFont parameter and will set the oChangedOffset parameter to 2 and the oChangedLength parameter to 2.
ATSUMatchFontsToText may allocate memory in your application heap, unless you designate a different heap by calling the function ATSUCreateMemorySetting.
Available beginning with ATSUI 1.0.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.5 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)