< Home < Developers < Development Support < Documentation

## 51 Text Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 51 Text Manager Text Manager Data Structures CharEncodingType Text Manager Functions TxtByteAttr TxtCaselessCompare TxtCharAttr TxtCharBounds TxtCharEncoding TxtCharIsAlNum TxtCharIsAlpha TxtCharIsCntrl TxtCharIsDelim TxtCharIsDigit TxtCharIsGraph TxtCharIsHardKey TxtCharIsHex TxtCharIsLower TxtCharIsPrint TxtCharIsPunct TxtCharIsSpace TxtCharIsUpper TxtCharIsValid TxtCharSize TxtCharWidth TxtCharXAttr TxtCompare TxtConvertEncoding TxtEncodingName TxtFindString TxtGetChar TxtGetNextChar TxtGetPreviousChar TxtGetTruncationOffset TxtGetWordWrapOffset TxtMaxEncoding TxtNameToEncoding TxtNextCharSize TxtParamString TxtPreviousCharSize TxtReplaceStr TxtSetNextChar TxtStrEncoding TxtTransliterate TxtWordBounds |  |  |  | This chapter provides information about the text manager API declared in TextMgr.h by discussing these topics: Text Manager Data Structures Text Manager Functions For more information on the text manager, see the chapter "Localized Applications" in the Palm OS Programmer's Companion, vol. I. ## Text Manager Data Structures ## CharEncodingType The CharEncodingType enum specifies possible character encodings. The Character Encoding Constants define the possible values for CharEncodingType variables.
    UInt8 CharEncodingType;
A given device supports a single character encoding. The currently available devices support either the PalmTM version of Windows code page 1252 (an extension of ISO Latin 1) or the Palm version of Windows code page 932 (an extension of Shift JIS). These encodings are identical to their Windows counterparts with some additional characters added in the control range. #### Compatibility Prior to version 4.0, CharEncodingType was an enum that defined only eight character encodings. The Palm OS® 4.0 definition of CharEncodingType is compatible with the previous definition. ## Text Manager Functions ## TxtByteAttr #### Purpose Return the possible locations of a given byte within a multi-byte character. #### Prototype UInt8 TxtByteAttr (UInt8 inByte) #### Parameters #####
-> inByte | A byte representing all or part of a valid character.
#### Result Returns a byte with one or more of the following bits set: #####
byteAttrFirst | First byte of multi-byte character.
byteAttrLast | Last byte of multi-byte character.
byteAttrMiddle | Middle byte of multi-byte character.
byteAttrSingle | Single-byte character.
#### Comments If inByte is valid in more than one location of a character, multiple return bits are set. For example, 0x40 in the Shift JIS character encoding is valid as a single-byte character and as the low-order byte of a double-byte character. Thus, the return value for TxtByteAttr(0x40) on a Shift JIS system has both the byteAttrSingle and byteAttrLast bits set. Text manager functions that need to determine the byte positioning of a character use TxtByteAttr to do so. You rarely need to use this function yourself. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueByteAttr. For more information, see Chapter 76, "PalmOSGlue Library." ## TxtCaselessCompare #### Purpose Perform a case-insensitive comparison of two text buffers. #### Prototype Int16 TxtCaselessCompare (const Char* s1, UInt16 s1Len, UInt16* s1MatchLen, const Char* s2, UInt16 s2Len, UInt16* s2MatchLen) #### Parameters #####
-> s1 | Pointer to the first text buffer to compare.
#####
-> s1Len | Length in bytes of the text pointed to by s1.
#####
<- s1MatchLen | Points to the offset of the first character in s1 that determines the sort order. Pass NULL for this parameter if you don't need to know this number.
#####
-> s2 | Pointer to the second text buffer to compare.
#####
-> s2Len | Length in bytes of the text pointed to by s2.
#####
<- s2MatchLen | Points to the offset of the first character in s2 that determines the sort order. Pass NULL for this parameter if you don't need to know this number.
#### Result Returns one of the following values: #####
< 0 | If s1 occurs before s2 in alphabetical order.
> 0 | If s1 occurs after s2 in alphabetical order.
0 | If the two substrings that were compared are equal.
#### Comments In certain character encodings (such as Shift JIS), one character may be accurately represented as either a single-byte character or a multi-byte character. TxtCaselessCompare accurately matches a single-byte character with its multi-byte equivalent. For this reason, the values returned in s1MatchLen and s2MatchLen are not always equal. You must make sure that the parameters s1 and s2 point to a the start of a valid character. That is, they must point to the first byte of a multi-byte character or they must point to a single-byte character; if they don't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCaselessCompare. For more information, see Chapter 76, "PalmOSGlue Library." In Palm OS 4.0, the TxtCaselessCompare function terminates when it finds a null byte in the string. In earlier releases, it terminated only when it reached the ending byte specified by the length parameters. #### See Also StrCaselessCompare, TxtCompare, StrCompare ## TxtCharAttr #### Purpose Return a character's attributes. #### Prototype UInt16 TxtCharAttr (WChar inChar) #### Parameters #####
-> inChar | Any valid character.
#### Result Returns a 16-bit unsigned value with any of the following bits set: #####
charAttrPrint | Printable
charAttrSpace | Blank space, tab, or newline
charAttrAlNum | Alphanumeric
charAttrAlpha | Alphabetic
charAttrCntrl | Control character
charAttrGraph | Character that appears on the screen; that is, is not whitespace, a control character, or a virtual character.
charAttrDelim | Word delimiter (whitespace or punctuation).
#### Comments The character passed to this function must be a valid character given the system encoding. This function is used in the text manager's character attribute macros (TxtCharIsAlNum, TxtCharIsCntrl, and so on). The macros perform operations analogous to the standard C functions isPunct, isPrintable, and so on. Usually, you'd use one of these macros instead of calling TxtCharAttr directly. To obtain attributes specific to a given character encoding, use TxtCharXAttr. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharAttr. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharIsValid ## TxtCharBounds #### Purpose Return the boundaries of a character containing the byte at a specified offset in a string. #### Prototype WChar TxtCharBounds (const Char* inText, UInt32 inOffset, UInt32* outStart, UInt32* outEnd) #### Parameters #####
-> inText | Pointer to the text buffer to search.
#####
-> inOffset | A valid offset into the buffer inText. This location may contain a byte in any position (start, middle, or end) of a multi-byte character.
#####
<- outStart | Points to the starting offset of the character containing the byte at inOffset.
#####
<- outEnd | Points to the ending offset of the character containing the byte at inOffset.
#### Result Returns the character located between the offsets outStart and outEnd. #### Comments Use this function to determine the boundaries of a character in a string or text buffer. If the byte at inOffset is valid in more than one location of a character, the function must search back toward the beginning of the text buffer until it finds an unambiguous byte to determine the appropriate boundaries. For this reason, TxtCharBounds is often slow and should be used only where needed. You must make sure that the parameter inText points to the beginning of the string. That is, if the string begins with a multi-byte character, inText must point to the first byte of that character; if it doesn't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharBounds. For more information, see Chapter 76, "PalmOSGlue Library." ## TxtCharEncoding #### Purpose Return the minimum encoding required to represent a character. #### Prototype CharEncodingType TxtCharEncoding (WChar inChar) #### Parameters #####
-> inChar | A valid character.
#### Result A CharEncodingType value that indicates the minimum encoding required to represent inChar. If the character isn't recognizable, charEncodingUnknown is returned. #### Comments The minimum encoding is the encoding that takes the lowest number of bytes to represent the character. For example, if the character is a blank or a tab character, the minimum encoding is charEncodingAscii because these characters can be represented in single-byte ASCII. If the character is a ü, the minimum encoding is charEncodingISO8859_1. Because Palm OS only supports a single character encoding at a time, the result of this function is always logically equal to or less than the encoding used on the current system. That is, you'll only receive a return value of charEncodingISO8859_1 if you're running on a US or European system and you pass a non-ASCII character. Use this function for informational purposes only. Your code should not assume that the character encoding returned by this function is the Palm OS system character encoding. (Instead use FtrGet as shown in the TxtCharXAttr function description.) Use TxtMaxEncoding to determine the order of encodings. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharEncoding. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtStrEncoding, TxtMaxEncoding ## TxtCharIsAlNum #### Purpose Macro that indicates if the character is alphanumeric. #### Prototype TxtCharIsAlNum (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is a letter in an alphabet or a numeric digit, false otherwise. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsAlNum. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharIsDigit, TxtCharIsAlpha ## TxtCharIsAlpha #### Purpose Macro that indicates if a character is a letter in an alphabet. #### Prototype TxtCharIsAlpha (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is a letter in an alphabet, false otherwise. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsAlpha. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharIsAlNum, TxtCharIsLower, TxtCharIsUpper ## TxtCharIsCntrl #### Purpose Macro that indicates if a character is a control character. #### Prototype TxtCharIsCntrl (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is a non-printable character, such as the bell character or a carriage return; false otherwise. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsCntrl. For more information, see Chapter 76, "PalmOSGlue Library." ## TxtCharIsDelim #### Purpose Macro that indicates if a character is a delimiter. #### Prototype TxtCharIsDelim (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is a word delimiter (whitespace or punctuation), false otherwise. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsDelim. For more information, see Chapter 76, "PalmOSGlue Library." ## TxtCharIsDigit #### Purpose Macro that indicates if the character is a decimal digit. #### Prototype TxtCharIsDigit (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is 0 through 9, false otherwise. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsDigit. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharIsAlNum, TxtCharIsHex ## TxtCharIsGraph #### Purpose Macro that indicates if a character is a graphic character. #### Prototype TxtCharIsGraph (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is a graphic character, false otherwise. #### Comments A graphic character is any character visible on the screen, in other words, letters, digits, and punctuation marks. A blank space is not a graphic character because it is not visible. This macro differs from TxtCharIsPrint in that it returns false if the character is whitespace. TxtCharIsPrint returns true if the character is whitespace. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsGraph. For more information, see Chapter 76, "PalmOSGlue Library." ## TxtCharIsHardKey #### Purpose Macro that returns true if the character is one of the hard keys on the device. #### Prototype TxtCharIsHardKey (m, ch) #### Parameters #####
-> m | The modifier keys from the keyDownEvent.
#####
-> ch | The character from the keyDownEvent.
#### Result true if the character is one of the built-in hard keys on the device, false otherwise. #### Compatibility Valid only if International Feature Set is present. #### See Also ChrIsHardKey ## TxtCharIsHex #### Purpose Macro that indicates if a character is a hexadecimal digit. #### Prototype TxtCharIsHex (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is a hexadecimal digit from 0 to F, false otherwise. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsHex. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharIsDigit ## TxtCharIsLower #### Purpose Macro that indicates if a character is a lowercase letter. #### Prototype TxtCharIsLower (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is a lowercase letter, false otherwise. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsLower. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharIsAlpha, TxtCharIsUpper ## TxtCharIsPrint #### Purpose Macro that indicates if a character is printable. #### Prototype TxtCharIsPrint (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is not a control character, false otherwise. #### Comments This macro differs from TxtCharIsGraph in that it returns true if the character is whitespace. TxtCharIsGraph returns false if the character is whitespace. If you are using a debug ROM and you pass a virtual character to this macro, a fatal alert is generated. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsPrint. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharIsValid ## TxtCharIsPunct #### Purpose Macro that indicates if a character is a punctuation mark. #### Prototype TxtCharIsPunct (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is a punctuation mark, false otherwise. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsPunct. For more information, see Chapter 76, "PalmOSGlue Library." ## TxtCharIsSpace #### Purpose Macro that indicates if a character is a whitespace character. #### Prototype TxtCharIsSpace (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is whitespace such as a blank space, tab, or newline; false otherwise. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsSpace. For more information, see Chapter 76, "PalmOSGlue Library." ## TxtCharIsUpper #### Purpose Macro that indicates if a character is an uppercase letter. #### Prototype TxtCharIsUpper (ch) #### Parameters #####
-> ch | A valid character.
#### Result Returns true if the character is an uppercase letter, false otherwise. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsUpper. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharIsAlpha, TxtCharIsLower ## TxtCharIsValid #### Purpose Determine whether a character is valid character given the Palm OS character encoding. #### Prototype Boolean TxtCharIsValid (WChar inChar) #### Parameters #####
-> inChar | A character.
#### Result Returns true if inChar is a valid character; false if inChar is not a valid character. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharIsValid. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharAttr, TxtCharIsPrint ## TxtCharSize #### Purpose Return the number of bytes required to store the character in a string. #### Prototype UInt16 TxtCharSize (WChar inChar) #### Parameters #####
-> inChar | A valid character.
#### Result The number of bytes required to store the character in a string. #### Comments Although character variables are always two-byte long WChar values, in some character encodings such as Shift-JIS, characters in strings are represented by a mix of one or more bytes per character. If the character can be represented by a single byte (its high-order byte is 0), it is stored in a string as a single-byte character. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharSize. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharBounds ## TxtCharWidth #### Purpose Return the width required to display the specified character in the current font. If the specified character does not exist within the current font, the missing character symbol is substituted. #### Prototype Int16 TxtCharWidth (WChar inChar) #### Parameters #####
-> inChar | A valid character.
#### Result Returns the width of the specified character (in pixels). #### Comments Use FntWCharWidth or FntGlueWCharWidth instead of this routine. #### Compatibility Implemented only if International Feature Set is present. ## TxtCharXAttr #### Purpose Return the extended attribute bits for a character. #### Prototype UInt16 TxtCharXAttr (WChar inChar) #### Parameters #####
-> inChar | A valid character.
#### Result Returns an unsigned 16-bit value with one or more extended attribute bits set. For specific return values, look in the header files that are specific to certain character encodings (CharLatin.h or CharShiftJIS.h). #### Comments To interpret the results, you must know the character encoding being used. Use FtrGet with sysFtrNumEncoding as the feature number to determine the character encoding. This returns one of the CharEncodingType values. For example:
    WChar ch;
    UInt16 attr;
    UInt32 encoding;
    ...
    attr = TxtCharXAttr(ch);
    if (FtrGet(sysFtrCreator, sysFtrNumEncoding,
      &encoding) != errNone)
      encoding = charEncodingPalmLatin;
    if (encoding == charEncodingUTF8) {
    }
#### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCharXAttr. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharAttr ## TxtCompare #### Purpose Performs a case-sensitive comparison of all or part of two text buffers. #### Prototype Int16 TxtCompare (const Char* s1, UInt16 s1Len, UInt16* s1MatchLen, const Char* s2, UInt16 s2Len, UInt16* s2MatchLen) #### Parameters #####
-> s1 | Pointer to the first text buffer to compare.
#####
-> s1Len | The length in bytes of the text pointed to by s1.
#####
<- s1MatchLen | Points to the offset of the first character in s1 that determines the sort order. Pass NULL for this parameter if you don't need to know this number.
#####
-> s2 | Pointer to the second text buffer to compare.
#####
-> s2Len | The length in bytes of the text pointed to by s2.
#####
<- s2MatchLen | Points to the offset of the first character in s2 that determines the sort order. Pass NULL for this parameter if you don't need to know this number.
#### Result Returns one of the following values: #####
< 0 | If s1 occurs before s2 in alphabetical order.
> 0 | If s1 occurs after s2 in alphabetical order.
0 | If the two substrings that were compared are equal.
#### Comments This function performs a case-sensitive comparison. If you want to perform a case-insensitive comparison, use TxtCaselessCompare. The s1MatchLen and s2MatchLen parameters are not as useful for the TxtCompare function as they are for the TxtCaselessCompare function because TxtCompare implements a multi-pass sort algorithm. (See the Compatibility section below for further details.) For example, comparing the string "celery" with the string "Cauliflower" returns a positive value to indicate that "celery" sorts after "Cauliflower," and it returns a match length of 1 to indicate that the second letter determines the sort order ("e" comes after "a"). However, because TxtCompare ultimately does a case-sensitive comparison, comparing the string "c" to the string "C" produces a negative result and a match length of 0. In certain character encodings (such as Shift JIS), one character may be accurately represented as either a single-byte character or a multi-byte character. TxtCompare accurately matches a single-byte character with its multi-byte equivalent. For this reason, the values returned in s1MatchLen and s2MatchLen are not always equal. You must make sure that the parameters s1 and s2 point to the start of a a valid character. That is, they must point to the first byte of a multi-byte character or they must point to a single-byte character; if they don't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueCompare. For more information, see Chapter 76, "PalmOSGlue Library." Prior to Palm OS 4.0, TxtCompare and StrCompare only performed one level of comparison and returned as soon as they found two unequal characters. For example, if you compared the string "celery" with the string "Cauliflower," both functions returned a value indicating that "celery" should appear before "Cauliflower" because they sorted "c" before "C." In Palm OS 4.0, StrCompare calls TxtCompare, and TxtCompare performs a comparison using up to six comparison tables for sorting with increasing precision. As a result, in Palm OS 4.0 and higher, TxtCompare sorts "Cauliflower" before "celery." The TxtGlueCompare function uses a two-pass sort on pre-4.0 devices, which will also sort "Cauliflower" before "celery." Palm OS 4.0 sorting of Shift-JIS characters attempts to duplicate the sorting algorithm described by the JIS standard. In Palm OS 4.0, the TxtCompare function terminates when it finds a null byte in the string. In earlier releases, it terminated only when it reached the ending byte specified by the length parameters. #### See Also StrCompare, TxtFindString ## New TxtConvertEncoding #### Purpose Convert a text buffer from one character encoding to another. #### Prototype Err TxtConvertEncoding (Boolean newConversion, TxtConvertStateType *ioStateP, const Char *srcTextP, UInt16 *ioSrcBytes, CharEncodingType srcEncoding, Char *dstTextP, UInt16 *ioDstBytes, CharEncodingType dstEncoding, const Char *substitutionStr, UInt16 substitutionLen) #### Parameters #####
-> newConversion | true if this function call is starting a new conversion, or false if this function call is a continuation of a previous conversion.
#####
<-> ioStateP | If newConversion is false, this parameter must point to the same data used for the previous invocation. If newConversion is true and no subsequent calls are planned, this parameter can be NULL.
#####
-> srcTextP | A pointer to a text buffer. If newConversion is true, this must point to the start of a text buffer. If newConversion is false, it may point to a location in the middle of a text buffer. In either case, it must point to an inter-character boundary.
#####
<-> ioSrcBytes | A pointer to the length in bytes of the text in srcTextP that needs to be converted. Upon return, contains the number of bytes successfully processed.
#####
-> srcEncoding | The character encoding that srcTextP currently uses. This should be one of the Character Encoding Constants.
#####
<- dstTextP | A pointer to the destination text buffer or NULL. This should always point to the location where TxtConvertEncoding can begin writing.
#####
<-> ioDstBytes | A pointer to the length in bytes of dstTextP. Upon return, contains the number of bytes required to represent srcTextP in the new encoding.
#####
-> dstEncoding | The character encoding to which to convert srcTextP. This should be one of the Character Encoding Constants.
#####
-> substitutionStr | A string that should be used to substitute any invalid or inconvertible characters that occur in srcTextP. This string must already be in the destination encoding. If NULL, the function immediately returns when an invalid character is encountered.
#####
-> substitutionLen | The number of bytes in substitutionStr, not including the terminating null byte.
#### Result Returns errNone upon success or one of the following if an error occurs: #####
txtErrConvertOverflow | The destination buffer is not large enough to contain the converted text.
#####
txtErrConvertUnderflow | The end of the source buffer contains a partial character.
#####
txtErrNoCharMapping | The device does not contain a mapping between the source and destination encodings for at least one of the characters in srcTextP.
#####
txtErrUnknownEncoding | One of the specified encodings is not valid. Currently, both the source and destination encodings must match either the device's encoding or one of the Unicode character encodings.
#### Comments This function converts ioSrcBytes of text in srcTextP from the srcEncoding to the dstEncoding character encoding and returns the result in dstTextP. Currently, the focus of TxtConvertEncoding is to convert between Unicode-encoded text and the device's character encoding. For this reason, TxtConvertEncoding can only handle conversions between the device's encoding and one of UTF-8, UCS-2, UTF-16LE, or UTF-16BE. If you specify any other character encoding for either the source or the destination buffer, the error code txtErrUnknownEncoding is returned. You can retrieve the device's encoding using the following function:
    FtrGet(sysFtrCreator, sysFtrNumEncoding,
      &encoding)
If you're converting text that was received from the Internet, the encoding's name is passed along with the text data. Use the TxtNameToEncoding function to convert the name to a CharEncodingType value. The dstTextP buffer must be large enough to hold the result of converting srcTextP to the specified encoding. You can pass NULL for the dstTextP parameter to determine the required length of the buffer before actually doing the conversion. (The required length is returned in ioDstBytes.) If the function encounters an inconvertible character in the source text, it puts substitutionStr in the destination buffer in that character's place and continues the conversion. When the conversion is complete, it returns txtErrNoCharMapping to indicate that an error occurred. If substitutionStr is NULL, the function stops the conversion and immediately returns txtErrNoCharMapping. ioSrcBytes is set to the offset of the inconvertible character, dstTextP contains the converted string up to that point, and ioDstBytes contains the size of the converted text. You can examine the character at ioSrcBytes and choose to move past it and continue the conversion. Follow the rules for making repeated calls to TxtConvertEncoding as described in the next paragraph. You can make repeated calls to TxtConvertEncoding in a loop if you only want to convert part of the input buffer at a time. When you make repeated calls to this function, the first call should use true for newConversion, and srcTextP should point to the start of the text buffer. All subsequent calls should use the following values: #####
newConversion | false.
#####
ioStateP | The same data that was returned by the previous invocation.
#####
srcTextP | The location where this call should begin converting. Typically, this would be the previous srcTextP plus the number of bytes returned in ioSrcBytes.
#####
| If you are skipping over an inconvertible character, srcTextP must point to the character after that location.
#####
<-> ioSrcBytes | The number of bytes that this function call should convert.
#####
dstTextP | A pointer to a location where this function can begin writing the converted string. You might choose to have each function call write to a different destination buffer. To have successive calls write to the same buffer, pass the previous dstTextP plus the number of bytes returned in ioDstBytes each time.
#####
ioDstBytes | The number of bytes available for output in the dstTextP buffer. In other words, the number of bytes remaining.
#### Compatibility Implemented only if 4.0 New Feature Set is present. ## TxtEncodingName #### Purpose Obtain a character encoding's name. #### Prototype const Char* TxtEncodingName (CharEncodingType inEncoding) #### Parameters #####
-> inEncoding | One of the values from CharEncodingType, indicating a character encoding.
#### Result A constant string containing the name of the encoding. The possible return values are defined in PalmLocale.h. They are: #####
encodingNameAscii | us ascii
encodingNameISO8859_1 | ISO-8859-1
encodingNameCP1252 | ISO-8859-1-Windows-3.1-Latin-1
encodingNameShiftJIS | Shift_JIS
encodingNameCP932 | Windows-31J
encodingNameUTF8 | UTF-8
"" | The encoding is not known
#### Comments Use this function to obtain the official name of the character encoding, suitable to pass to an Internet application or any other application that requires the character encoding's name to be passed along with the data. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueEncodingName. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtNameToEncoding ## TxtFindString #### Purpose Perform a case-insensitive search for a string in another string. #### Prototype Boolean TxtFindString (const Char* inSourceStr, const Char* inTargetStr, UInt32* outPos, UInt16* outLength) #### Parameters #####
-> inSourceStr | Pointer to the string to be searched.
#####
-> inTargetStr | Prepared version of the string to be found. This string should either be passed directly from the strToFind field in the sysAppLaunchCmdFind launch code's parameter block or it should be prepared using the PalmOSGlue function TxtGluePrepFindString.
#####
<- outPos | Pointer to the offset of the match in inSourceStr.
#####
<- outLength | Pointer to the length in bytes of the matching text.
#### Result Returns true if the function finds inTargetStr within inSourceStr; false otherwise. If found, the values pointed to by the outPos and outLength parameters are set to the starting offset and the length of the matching text. If not found, the values pointed to by outPos and outLength are set to 0. The search that TxtFindString performs is locale-dependent. On most ROMs with Latin-based encodings, TxtFindString returns true only if the string is at the beginning of a word. On Shift-JIS encoded ROMs, TxtFindString returns true if the string is located anywhere in the word. #### Comments Use this function instead of FindStrInStr to support the global system find facility. This function contains an extra parameter, outLength, to specify the length of the text that matched. Pass this value to FindSaveMatch in the appCustom parameter. Then when your application receives sysAppLaunchCmdGoTo, the matchCustom field contains the length of the matching text. You use the length of matching text to highlight the match within the selected record. You must make sure that the parameters inSourceStr and inTargetStr point to the start of a valid character. That is, they must point to the first byte of a multi-byte character, or they must point to a single-byte character; if they don't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueFindString. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCaselessCompare ## TxtGetChar #### Purpose Retrieve the character starting at the specified offset within a text buffer. #### Prototype WChar TxtGetChar (const Char* inText, UInt32 inOffset) #### Parameters #####
-> inText | Pointer to the text buffer to be searched.
#####
-> inOffset | A valid offset into the buffer inText. This offset must point to an inter-character boundary.
#### Result Returns the character at inOffset in inText. #### Comments You must make sure that the parameter inText points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueGetChar. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtGetNextChar, TxtSetNextChar ## TxtGetNextChar #### Purpose Retrieve the character starting at the specified offset within a text buffer. #### Prototype UInt16 TxtGetNextChar (const Char* inText, UInt32 inOffset, WChar* outChar) #### Parameters #####
-> inText | Pointer to the text buffer to be searched.
#####
-> inOffset | A valid offset into the buffer inText. This offset must point to an inter-character boundary.
#####
<- outChar | The character at inOffset in inText. Pass NULL for this parameter if you don't need the character returned.
#### Result Returns the size in bytes of the character at inOffset. If outChar is not NULL upon entry, it points to the character at inOffset upon return. #### Comments You can use this function to iterate through a text buffer character-by-character in this way:
    UInt16 i = 0;
    WChar ch;
    while (i < bufferLength) {
        i += TxtGetNextChar(buffer, i, &ch);
        //do something with ch.
    }
You must make sure that the parameter inText points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueGetNextChar. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtGetChar, TxtGetPreviousChar, TxtSetNextChar ## TxtGetPreviousChar #### Purpose Retrieve the character before the specified offset within a text buffer. #### Prototype UInt16 TxtGetPreviousChar (const Char* inText, UInt32 inOffset, WChar* outChar) #### Parameters #####
-> inText | Pointer to the text buffer to be searched.
#####
-> inOffset | A valid offset into the buffer inText. This offset must point to an inter-character boundary.
#####
<- outChar | The character immediately preceding inOffset in inText. Pass NULL for this parameter if you don't need the character returned.
#### Result Returns the size in bytes of the character preceding inOffset in inText. If outChar is not NULL upon entry, then it points to the character preceding inOffset upon return. Returns 0 if inOffset is at the start of the buffer (that is, inOffset is 0). #### Comments You can use this function to iterate through a text buffer character-by-character in this way:
    WChar ch;
    /* Find the start of the character containing the last byte. */
    TxtCharBounds (buffer, bufferLength - 1, &start, &end);
    i = start;
    while (i > 0) {
        i -= TxtGetPreviousChar(buffer, i, &ch);
        //do something with ch.
    }
This function is often slower to use than TxtGetNextChar because it must determine the appropriate character boundaries if the byte immediately before the offset is valid in more than one location (start, middle, or end) of a multi-byte character. To do this, it must work backwards toward the beginning of the string until it finds an unambiguous byte. You must make sure that the parameter inText points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueGetPreviousChar. For more information, see Chapter 76, "PalmOSGlue Library." ## TxtGetTruncationOffset #### Purpose Return the appropriate byte position for truncating a text buffer such that it is at most a specified number of bytes long. #### Prototype UInt32 TxtGetTruncationOffset (const Char* inText, UInt32 inOffset) #### Parameters #####
-> inText | Pointer to a text buffer.
#####
-> inOffset | An offset into the buffer inText.
#### Result Returns the appropriate byte offset for truncating inText at a valid inter-character boundary. The return value may be less than or equal to inOffset. #### Comments You must make sure that the parameter inText points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueGetTruncationOffset. For more information, see Chapter 76, "PalmOSGlue Library." ## New TxtGetWordWrapOffset #### Purpose Locate an appropriate place for a line break in a text buffer. #### Prototype UInt32 TxtGetWordWrapOffset (const Char *iTextP, UInt32 iOffset) #### Parameters #####
-> iTextP | Pointer to a text buffer.
#####
-> iOffset | Pointer to the offset where the search should begin. The search is performed backward starting from this offset.
#### Result Returns the offset of a character that can begin on a new line (typically, the beginning of the word that contains iOffset or last word before iOffset). If an appropriate break could not be found, returns iOffset. #### Comments The FntWordWrap and FntWordWrapReverseNLines functions call TxtGetWordWrapOffset to locate an appropriate place to break the text. The returned offset points to the character that should begin the next line. This function starts at iOffset and works backward until it finds a character that typically occurs between words (for example, white space or punctuation). Then it moves forward until it locates the character that begins a word (typically, a letter or number). Note that this function may return an offset value that is greater than the one passed in if the offset passed in occurs immediately before white space or in the middle of white space. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also TxtWordBounds ## TxtMaxEncoding #### Purpose Return the higher of two encodings. #### Prototype CharEncodingType TxtMaxEncoding (CharEncodingType a, CharEncodingType b) #### Parameters #####
-> a | A character encoding to compare.
#####
-> b | Another character encoding to compare.
#### Result Returns the higher of a or b. One character encoding is higher than another if it is more specific. For example code page 1252 is "higher" than ISO 8859-1 because it represents more characters than ISO 8859-1. #### Comments This function is used by TxtStrEncoding to determine the encoding required for a string. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueMaxEncoding. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharEncoding, CharEncodingType ## New TxtNameToEncoding #### Purpose Return an encoding's constant given its name. #### Prototype CharEncodingType TxtNameToEncoding (const Char *iEncodingName) #### Parameters #####
-> iEncodingName | One of the string constants containing the official name of an encoding. See TxtEncodingName for a list.
#### Result Returns one of the Character Encoding Constants. Returns charEncodingUnknown if the specified encoding could not be found. #### Comments Use this function to convert a character encoding's name as received from an Internet application into the character encoding constant that some text manager functions require. This function properly converts aliases for a character encoding. For example, passing the strings "us-ascii", "ASCII", "cp367", and "IBM367" all return charEncodingAscii. The known character encodings are device-dependent. For example, a device with the Shift-JIS encoding will not know all of the aliases for Latin character encodings; however, it will know all of the aliases for Shift-JIS. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also TxtEncodingName ## TxtNextCharSize #### Purpose Macro that returns the size of the character starting at the specified offset within a text buffer. #### Prototype TxtNextCharSize (inText, inOffset) #### Parameters #####
-> inText | Pointer to the text buffer to be searched.
#####
-> inOffset | A valid offset into the buffer inText. This offset must point to an inter-character boundary.
#### Result Returns (as a UInt16) the size in bytes of the character at inOffset. #### Comments You must make sure that the parameter inText points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueNextCharSize. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtGetNextChar ## TxtParamString #### Purpose Replace substrings within a string with the specified values. #### Prototype Char* TxtParamString (const Char* inTemplate, const Char* param0, const Char* param1, const Char* param2, const Char* param3) #### Parameters #####
-> inTemplate | The string containing the substrings to replace.
#####
-> param0 | String to replace ^0 with or NULL.
#####
-> param1 | String to replace ^1 with or NULL.
#####
-> param2 | String to replace ^2 with or NULL.
#####
-> param3 | String to replace ^3 with or NULL.
#### Result Returns a pointer to a locked relocatable chunk in the dynamic heap that contains the appropriate substitutions. #### Comments This function searches inTemplate for occurrences of the sequences ^0, ^1, ^2, and ^3. When it finds these, it replaces them with the corresponding string passed to this function. Multiple instances of each sequence will be replaced. The replacement strings can also contain the substitution strings, provided they refer to a later parameter. That is, the param0 string contain have references to ^1, ^2, and ^3, the param1 string can have references to ^2 and ^3, and the param2 string can have references to ^3. Any other occurrences of the substitution strings in the replacement strings are ignored. For example, if param3 is the string "^0", any occurrences of ^3 in inTemplate are replaced with the string "^0". You must make sure that the parameter inTemplate points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. TxtParamString allocates space for the returned string in the dynamic heap through a call to MemHandleNew, and then returns the result of calling MemHandleLock with this handle. Your code is responsible for freeing this memory when it is no longer needed. #### Compatibility Implemented if 3.5 New Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueParamString. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtReplaceStr, FrmCustomAlert ## TxtPreviousCharSize #### Purpose Macro that returns the size of the character before the specified offset within a text buffer. #### Prototype TxtPreviousCharSize (inText, inOffset) #### Parameters #####
-> inText | Pointer to the text buffer.
#####
-> inOffset | A valid offset into the buffer inText. This offset must point to an inter-character boundary.
#### Result Returns (as a UInt16) the size in bytes of the character preceding inOffset in inText. Returns 0 if inOffset is at the start of the buffer (that is, inOffset is 0). #### Comments You must make sure that the parameter inText points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. This macro is often slower to use than TxtNextCharSize because it must determine the appropriate character boundaries if the byte immediately before the offset is valid in more than one location (start, middle, or end) of a multi-byte character. To do this, it must work backwards toward the beginning of the string until it finds an unambiguous byte. #### Compatibility Valid only if International Feature Set is present. To use this macro in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGluePreviousCharSize. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtGetPreviousChar ## TxtReplaceStr #### Purpose Replace a substring of a given format with another string. #### Prototype UInt16 TxtReplaceStr (Char* ioStr, UInt16 inMaxLen, const Char* inParamStr, UInt16 inParamNum) #### Parameters #####
<-> ioStr | The string in which to perform the replacing.
#####
-> inMaxLen | The maximum length in bytes that ioStr can become.
#####
-> inParamStr | The string that ^inParamNum should be replaced with. If NULL, no changes are made.
#####
-> inParamNum | A single-digit number (0 to 9).
#### Result Returns the number of occurrences found and replaced. Returns a fatal error message if inParamNum is greater than 9. #### Comments This function searches ioStr for occurrences of the string ^inParamNum, where inParamNum is any digit from 0 to 9. When it finds the string, it replaces it with inParamStr. Multiple instances will be replaced as long as the resulting string doesn't contain more than inMaxLen bytes, not counting the terminating null. You can set the inParamStr parameter to NULL to determine the required length of ioStr before actually doing the replacing. TxtReplaceStr returns the number of occurrences it finds of ^inParamNum. Multiply this value by the length of the inParamStr you intend to use to determine the appropriate length of ioStr. You must make sure that the parameter ioStr points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueReplaceStr. For more information, see Chapter 76, "PalmOSGlue Library." ## TxtSetNextChar #### Purpose Set a character within a text buffer. #### Prototype UInt16 TxtSetNextChar (Char* ioText, UInt32 inOffset, WChar inChar) #### Parameters #####
<-> ioText | Pointer to a text buffer.
#####
-> inOffset | A valid offset into the buffer inText. This offset must point to an inter-character boundary.
#####
-> inChar | The character to replace the character at inOffset with. Must not be a virtual character.
#### Result Returns the size of inChar. #### Comments This function replaces the character in ioText at the location inOffset with the character inChar. Note that there must be enough space at inOffset to write the character. You can use TxtCharSize to determine the size of inChar. You must make sure that the parameter ioText points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueSetNextChar. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtGetNextChar ## TxtStrEncoding #### Purpose Return the encoding required to represent a string. #### Prototype CharEncodingType TxtStrEncoding (const Char* inStr) #### Parameters #####
-> inStr | A string.
#### Result A CharEncodingType value that indicates the encoding required to represent inChar. If any character in the string isn't recognizable, then charEncodingUnknown is returned. #### Comments The encoding for the string is the maximum encoding of any character in that string. For example, if a two-character string contains a blank space and a ü, the appropriate encoding is charEncodingISO8859_1. The blank space's minimum encoding is ASCII. The minimum encoding for the ü is ISO 8859-1. The maximum of these two encodings is ISO 8859-1. Because Palm OS only supports a single character encoding at a time, the results of this function is always logically equal to or less than the encoding used on the current system. That is, you'll only receive a return value of charEncodingISO8859_1 if you're running on a Latin-based system. Use this function for informational purposes only. Your code should not assume that the character encoding returned by this function is the Palm OS system's character encoding. (Instead use FtrGet as shown in the TxtCharXAttr function description.) #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueStrEncoding. For more information, see Chapter 76, "PalmOSGlue Library." #### See Also TxtCharEncoding, TxtMaxEncoding ## TxtTransliterate #### Purpose Converts the specified number of bytes in a text buffer using the specified operation. #### Prototype Err TxtTransliterate (const Char* inSrcText, UInt16 inSrcLength, Char* outDstText, UInt16* ioDstLength, TranslitOpType inOp) #### Parameters #####
-> inSrcText | Pointer to a text buffer.
#####
-> inSrcLength | The length in bytes of inSrcText.
#####
<- outDstText | The output buffer containing the converted characters.
#####
<->ioDstLength | Upon entry, the maximum length of outDstText. Upon return, the actual length of outDstText.
#####
-> inOp | A 16-bit unsigned value that specifies which transliteration operation is to be performed. The values possible for this field are specific to the character encoding used on a particular device. These operations are universally available:
#####
translitOpUpperCase | Converts the character to uppercase letters.
#####
translitOpLowerCase | Converts the characters to lowercase letters.
#####
translitOpPreprocess | Don't actually perform the operation. Instead, return in ioDstLength the amount of space required for the output text.
#### Result Returns one of the following values: #####
errNone | Success
#####
txtErrUknownTranslitOp | inOp's value is not recognized
#####
txtErrTranslitOverrun | inSrcText and outDstText point to the same memory location and the operation has caused the function to overwrite unprocessed data in the input buffer.
#####
txtErrTranslitOverflow | outDstText is not large enough to contain the converted string.
#####
txtErrTranslitUnderflow | The end of the source buffer contains a partial character.
##### #### Comments inSrcText and outDstText may point to the same location if you want to perform the operation in place. However, you should be careful that the space required for outDstText is not larger than inSrcText so that you don't generate a txtErrTranslitOverrun error. For example, suppose on a Shift JIS encoded system, you want to convert a series of single-byte Japanese Katakana symbols to double-byte Katakana symbols. You cannot perform this operation in place because it replaces a single-byte character with a multi-byte character. When the first converted character is written to the buffer, it overwrites the second input character. Thus, a text overrun has occurred. You can ensure that you have enough space for the output by OR-ing your chosen operation with translitOpPreprocess. For example, to convert a string to uppercase letters, do the following:
    outSize = buf2Len;
    error = TxtTransliterate(buf1, buf1len, &buf2,
    &outSize,
    translitOpUpperCase|translitOpPreprocess);
    if (outSize > buf2len)
        /* allocate more memory for buf2 */
    error = TxtTransliterate(buf1, buf1Len, &buf2,
    &outSize, translitOpUpperCase);
You must make sure that the parameter inSrcText points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueTransliterate. For more information, see Chapter 76, "PalmOSGlue Library." In Palm OS 4.0, the TxtTransliterate function terminates when it finds a null byte in the source string. In earlier releases, it terminated only when it reached the ending byte specified by the length parameter. ## TxtWordBounds #### Purpose Find the boundaries of a word of text that contains the character starting at the specified offset. #### Prototype Boolean TxtWordBounds (const Char* inText, UInt32 inLength, UInt32 inOffset, UInt32* outStart, UInt32* outEnd) #### Parameters #####
-> inText | Pointer to a text buffer.
#####
-> inLength | The length in bytes of the text pointed to by inText.
#####
-> inOffset | A valid offset into the text buffer inText. This offset must point to the beginning of a character.
#####
<- outStart | The starting offset of the text word.
#####
<- outEnd | The ending offset of the text word.
#### Result Returns true if a word is found. Returns false if the word doesn't exist or is punctuation or whitespace. #### Comments Assuming the ASCII encoding, if the text buffer contains the string "Hi! How are you?" and you pass 5 as the offset, TxtWordBounds returns the start and end of the word containing the character at offset 5, which is the character "o". Thus, outStart and outEnd would point to the start and end of the word "How". You must make sure that the parameter inText points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable. #### Compatibility Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueWordBounds. For more information, see Chapter 76, "PalmOSGlue Library." In Palm OS 4.0, the TxtWordBounds function terminates when it finds a null byte in the string. In earlier releases, it terminated only when it reached the ending byte specified by the length parameter. #### See Also TxtCharBounds, TxtCharIsDelim, TxtGetWordWrapOffset |