Text Manager
 

 < 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

-> inByteA 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

-> s1Pointer to the first text buffer to compare.
-> s1LenLength in bytes of the text pointed to by s1.
<- s1MatchLenPoints 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.
-> s2Pointer to the second text buffer to compare.
-> s2LenLength in bytes of the text pointed to by s2.
<- s2MatchLenPoints 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

-> inCharAny 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

-> inTextPointer to the text buffer to search.
-> inOffsetA valid offset into the buffer inText. This location may contain a byte in any position (start, middle, or end) of a multi-byte character.
<- outStartPoints to the starting offset of the character containing the byte at inOffset.
<- outEndPoints 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

-> inCharA 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

-> chA 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

-> chA 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

-> chA 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

-> chA 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

-> chA 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

-> chA 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

-> mThe modifier keys from the keyDownEvent.
-> chThe 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

-> chA 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

-> chA 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

-> chA 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

-> chA 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

-> chA 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

-> chA 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

-> inCharA 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

-> inCharA 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

-> inCharA 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

-> inCharA 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

-> s1Pointer to the first text buffer to compare.
-> s1LenThe length in bytes of the text pointed to by s1.
<- s1MatchLenPoints 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.
-> s2Pointer to the second text buffer to compare.
-> s2LenThe length in bytes of the text pointed to by s2.
<- s2MatchLenPoints 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

-> newConversiontrue if this function call is starting a new conversion, or false if this function call is a continuation of a previous conversion.
<-> ioStatePIf 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.
-> srcTextPA 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.
<-> ioSrcBytesA 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.
-> srcEncodingThe character encoding that srcTextP currently uses. This should be one of the Character Encoding Constants.
<- dstTextPA pointer to the destination text buffer or NULL. This should always point to the location where TxtConvertEncoding can begin writing.
<-> ioDstBytesA pointer to the length in bytes of dstTextP. Upon return, contains the number of bytes required to represent srcTextP in the new encoding.
-> dstEncodingThe character encoding to which to convert srcTextP. This should be one of the Character Encoding Constants.
-> substitutionStrA 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.
-> substitutionLenThe 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:

txtErrConvertOverflowThe destination buffer is not large enough to contain the converted text.
txtErrConvertUnderflowThe end of the source buffer contains a partial character.
txtErrNoCharMappingThe device does not contain a mapping between the source and destination encodings for at least one of the characters in srcTextP.
txtErrUnknownEncodingOne 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:

newConversionfalse.
ioStatePThe same data that was returned by the previous invocation.
srcTextPThe 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.
<-> ioSrcBytesThe number of bytes that this function call should convert.
dstTextPA 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.
ioDstBytesThe 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

-> inEncodingOne 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

-> inSourceStrPointer to the string to be searched.
-> inTargetStrPrepared 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.
<- outPosPointer to the offset of the match in inSourceStr.
<- outLengthPointer 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

-> inTextPointer to the text buffer to be searched.
-> inOffsetA 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

-> inTextPointer to the text buffer to be searched.
-> inOffsetA valid offset into the buffer inText. This offset must point to an inter-character boundary.
<- outCharThe 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

-> inTextPointer to the text buffer to be searched.
-> inOffsetA valid offset into the buffer inText. This offset must point to an inter-character boundary.
<- outCharThe 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

-> inTextPointer to a text buffer.
-> inOffsetAn 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

-> iTextPPointer to a text buffer.
-> iOffsetPointer 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

-> aA character encoding to compare.
-> bAnother 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

-> iEncodingNameOne 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

-> inTextPointer to the text buffer to be searched.
-> inOffsetA 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

-> inTemplateThe string containing the substrings to replace.
-> param0String to replace ^0 with or NULL.
-> param1String to replace ^1 with or NULL.
-> param2String to replace ^2 with or NULL.
-> param3String 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

-> inTextPointer to the text buffer.
-> inOffsetA 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

<-> ioStrThe string in which to perform the replacing.
-> inMaxLenThe maximum length in bytes that ioStr can become.
-> inParamStrThe string that ^inParamNum should be replaced with. If NULL, no changes are made.
-> inParamNumA 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

<-> ioTextPointer to a text buffer.
-> inOffsetA valid offset into the buffer inText. This offset must point to an inter-character boundary.
-> inCharThe 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

-> inStrA 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

-> inSrcTextPointer to a text buffer.
-> inSrcLengthThe length in bytes of inSrcText.
<- outDstTextThe output buffer containing the converted characters.
<->ioDstLengthUpon entry, the maximum length of outDstText. Upon return, the actual length of outDstText.
-> inOpA 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.
translitOpPreprocessDon'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:

errNoneSuccess
txtErrUknownTranslitOpinOp's value is not recognized
txtErrTranslitOverruninSrcText and outDstText point to the same memory location and the operation has caused the function to overwrite unprocessed data in the input buffer.
txtErrTranslitOverflowoutDstText is not large enough to contain the converted string.
txtErrTranslitUnderflowThe 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

-> inTextPointer to a text buffer.
-> inLengthThe length in bytes of the text pointed to by inText.
-> inOffsetA valid offset into the text buffer inText. This offset must point to the beginning of a character.
<- outStartThe starting offset of the text word.
<- outEndThe 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