Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Text /
Chapter 5 - Text Utilities / Text Utilities Reference
Routines / Truncating Strings


TruncText

The TruncText function ensures that a text string fits into the specified pixel width, by truncating the string as necessary. This function makes use of the current script and font. The text string can be up to 32 KB long.

You can use the TruncText function to ensure that a string defined by a pointer and a byte length fits into the specified pixel width, by truncating the string in a manner dependent on the font script.

FUNCTION TruncText (width: Integer; textPtr: Ptr; 
                    VAR length: Integer; 
                    truncWhere: TruncCode): Integer;
width
The number of pixels in which the text string must be displayed in the current script and font.
textPtr
A pointer to the text string to be truncated.
length
On input, the number of bytes in the text string to be truncated. On output, this value is updated to reflect the length of the (possibly) truncated text.
truncWhere
A constant that indicates where the text string should be truncated.
You must set this parameter to one of the constants truncEnd
or truncMiddle.
DESCRIPTION
The TruncText function ensures that a text string fits into the pixel width specified by the width parameter by modifying the string, if necessary, through truncation. TruncText uses the font script to determine how to perform truncation. If truncation occurs, TruncText inserts a truncation indicator which is the ellipsis (...) in the Roman script system. You can specify which token to use for indicating truncation as the tokenEllipsis token type in the untoken table of a tokens resource.

The truncWhere parameter specifies where truncation is performed. If you supply the truncEnd value, characters are truncated off the end of the string. If you supply the truncMiddle value, characters are truncated from the middle of the string; this is useful when displaying pathnames.

The TruncText function returns a result code that indicates whether the string
was truncated.

SPECIAL CONSIDERATIONS
TruncText may move memory; your application should not call this function at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION
The trap macro and routine selector for the TruncText function are
Trap macroSelector
_ScriptUtil$820C FFDE

RESULT CODES
Truncated1Truncation performed
NotTruncated0No truncation necessary
TruncErr-1Truncation necessary, but cannot be performed within the specified width
resNotFound-192Cannot get the correct 'itl4' resource or resource is not in current format
SEE ALSO
To determine the width of a string in the current font and script, use the QuickDraw StringWidth function, which is described in the chapter "QuickDraw Text" in
this book.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
6 JUL 1996