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
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
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
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
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
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
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
-> 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
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
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
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
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
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
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
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. |
<- 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. |
-> 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:
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
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:
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
|