(68K) Text Manager | Palm OS® Programmer's API Reference

This chapter provides information about the text manager API declared in TextMgr.h by discussing these topics:

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 ^TOP^

CharEncodingType Typedef ^TOP^

Purpose

The CharEncodingType enum specifies possible character encodings. The Character Encoding Constants define the possible values for CharEncodingType variables.

Prototype

UInt8 CharEncodingType;

Comments

A given handheld supports a single character encoding. The currently available handhelds support either the Palm^™ version of Windows code page 1252¹ (an extension of ISO Latin 1), the Palm version of Windows code page 932¹ (an extension of Shift JIS), or GB2312. In addition, Palm OS licensees and some third-party developers provide support for additional character encodings including Big-5, Hebrew, Arabic, Thai, Korean, and Cyrillic.

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.

TranslitOpType Typedef ^TOP^

Purpose

Specifies the transliteration operation to be performed by a given call to TxtTransliterate(). Each character encoding contains its own set of special transliteration operations, the values for which begin at translitOpCustomBase.

Prototype

typedef UInt16 TranslitOpType;

Comments

The following operations are always available, regardless of the character encoding used on the handheld:

Constant	Value	Description
`translitOpUpperCase`	0	Converts the character to uppercase letters.
`translitOpLowerCase`	1	Converts the characters to lowercase letters.
translitOpReserved2	2	Reserved
translitOpReserved3	3	Reserved
`translitOpPreprocess`	0x8000	A mask that , when OR'd to a transliteration operation value, indicates that `TxtTransliterate` should not perform the operation but should instead return (in `ioDstLength`) the amount of space required for the output text.

TxtConvertStateType Struct ^TOP^

Purpose

This structure is used to maintain state across calls to TxtConvertEncoding(). It is essentially opaque; simply declare a structure of this type and pass a pointer to your structure when making multiple calls to TxtConvertEncoding() for a single source text buffer.

Prototype

typedef struct {
  UInt8 ioSrcState[kTxtConvertStateSize];
  UInt8 ioDstState[kTxtConvertStateSize];
} TxtConvertStateType;

kTxtConvertStateSize is simply a constant that determines the size of the source and destination state buffers.

Text Manager Constants ^TOP^

Character Encoding Constant Modifiers ^TOP^

The following flag can be OR'd with the destination character encoding constant (one of those listed in "Character Encoding Constants") that is passed to TxtConvertEncoding().

Constant	Value	Description
`charEncodingDstBestFitFlag`	`0x80`	Causes `TxtConvertEncoding()` to make an extra effort to convert characters in the source encoding to similar (if not equal) characters in the destination encoding.

As an example, when converting from charEncodingUCS2 to charEncodingPalmGB, no mapping exists for 0x00A1 (INVERTED EXCLAMATION MARK), since this character doesn't exist within charEncodingPalmGB. In this instance, then TxtConvertEncoding() returns txtErrNoCharMapping for this mapping. If you OR the charEncodingDstBestFitFlag with the destination character encoding, however, TxtConvertEncoding() converts the character to chrExclamationMark (which is close). Generally, the operating system tries to support as many CP1252 characters as possible in the "best fit" table.

One situation when the best fit flag is commonly used is when you are trying to display text to the user (in which case the destination encoding is the device encoding). Because the best fit flag results in a lossy conversion, you typically don't want to use it on data which you will write back to storage. But for display, you almost always want to use best fit conversion because it maximizes the amount of meaningful information that may reach the user.

If charEncodingDstBestFitFlag is 1 and either the source or destination encoding is unknown, TxtConvertEncoding() copies anything that is 7-bit ASCII from the source to the destination. It then returns txtErrUnknownEncodingFallbackCopy. The rules for unknown characters apply during this 7-bit copy; if an inconvertible character is encountered the substitution string (if one has been specified) is used in its place and txtErrNoCharMapping is returned instead.

Compatibility

The charEncodingDstBestFitFlag is only supported in Palm OS versions that support Simplified Chinese. On Palm OS versions that don't support Simplified Chinese, use of this flag will prevent TxtConvertEncoding() from recognizing the destination encoding. To safely use the best fit flag on a variety of Palm OS releases, call TxtGlueConvertEncoding() instead of TxtConvertEncoding().

Character Encoding Feature Attributes ^TOP^

To obtain the attributes of the character encoding supported by the handheld's ROM, request the value of the sysFtrNumCharEncodingFlags feature. You do this by calling FtrGet() as follows:

err = FtrGet(sysFtrCreator, sysFtrNumEncodingFlags, &value);

Use the following bit masks to interpret value:

Constant	Value	Description
`charEncodingOnlySingleByte`	`0x00000001`	The character encoding consists only of single-byte characters.
`charEncodingHasDoubleByte`	`0x00000002`	The character encoding contains one or more double-byte characters.
`charEncodingHasLigatures`	`0x00000004`	The character encoding has ligatures.
`charEncodingRightToLeft`	`0x00000008`	The character encoding supports a writing system that primarily renders text right-to-left.

Character Attributes ^TOP^

The following constants define the flags that identify various character attributes. These replace the old flags defined in CharAttr.h, but are bit-compatible.

NOTE: TextMgr.h defines a set of functions and macros that can be used determine a character's attributes. These include TxtCharIsAlpha(), TxtCharIsCntrl(), and TxtCharIsValid().

Constant	Value	Description
`charAttr_XA`	`0x0200`	Extra alphabetic
`charAttr_XS`	`0x0100`	Extra space
`charAttr_BB`	`0x0080`	BEL, BS, etc.
`charAttr_CN`	`0x0040`	CR, FF, HT, NL, VT
`charAttr_DI`	`0x0020`	'0'-'9'
`charAttr_LO`	`0x0010`	'a'-'z' and lowercase extended characters
`charAttr_PU`	`0x0008`	Punctuation
`charAttr_SP`	`0x0004`	Space
`charAttr_UP`	`0x0002`	'A'-'Z' and uppercase extended characters
`charAttr_XD`	`0x0001`	'0'-'9', 'A'-'F', 'a'-'f'

These character attribute flags can be combined in various ways. TextMgr.h defines a number of standard combinations:

Constant	Value	Description
`charAttrPrint`	`(charAttr_DI\|charAttr_LO\|charAttr_PU\| charAttr_SP\|charAttr_UP\|charAttr_XA)`	Printable characters
`charAttrSpace`	`(charAttr_CN\|charAttr_SP\|charAttr_XS)`	Whitespace characters
`charAttrAlNum`	`(charAttr_DI\|charAttr_LO\|charAttr_UP\| charAttr_XA)`	Alphanumeric characters
`charAttrAlpha`	`(charAttr_LO\|charAttr_UP\|charAttr_XA)`	Alphabetic characters
`charAttrCntrl`	`(charAttr_BB\|charAttr_CN)`	Control characters
`charAttrGraph`	`(charAttr_DI\|charAttr_LO\|charAttr_PU\|charAttr_UP\|charAttr_XA)`	Printable, non-space characters
`charAttrDelim`	`(charAttr_SP\|charAttr_PU)`	Delimiters

Character Sizes ^TOP^

These constants can be useful when working with characters of varying sizes.

Constant	Value	Description
`sizeOf7BitChar`	`1`	The size, in bytes, of a 7-bit character. In C, characters are treated like integers: `sizeof(0x0D) == 2` (as is `sizeof('a')`, `sizeof('\0')`, and `sizeof(chrNull)`). Because of this, it's safest to use the `sizeOf7BitChar` macro to document buffer size and string length calculations. Note that this can only be used with low-ASCII characters, as anything else might be the high byte of a double-byte character.
`maxCharBytes`	`3`	Maximum size a single WChar character will occupy in a text string.

Text Manager Functions ^TOP^

TxtByteAttr Function ^TOP^

Purpose

Return the possible locations of a given byte within a multi-byte character.

Declared In

TextMgr.h

Prototype

UInt8 TxtByteAttr (
   UInt8 inByte
)

Parameters

→ inByte: A byte representing all or part of a valid character.

Returns

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. TextMgr.h defines two constants that represent double-byte encoding combinations:

byteAttrSingleLow	Either a single-byte character or the low-order byte of a double-byte character.
byteAttrHighLow	Either the first byte of a multi-byte character or the last byte of a multi-byte character.

Every byte in a stream of double-byte data must be either a single byte, a single/low byte (byteAttrSingleLow), or a high/low byte (byteAttrHighLow).

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 80, "PalmOSGlue Library."

TxtCaselessCompare Function ^TOP^

Purpose

Perform a case-insensitive comparison of two text buffers.

Declared In

TextMgr.h

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.

Returns

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 80, "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.

TxtCharAttr Function ^TOP^

Purpose

Return a character's attributes.

Declared In

TextMgr.h

Prototype

UInt16 TxtCharAttr (
   WChar inChar
)

Parameters

→ inChar: Any valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharBounds Function ^TOP^

Purpose

Return the boundaries of a character containing the byte at a specified offset in a string.

Declared In

TextMgr.h

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.

Returns

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 80, "PalmOSGlue Library."

TxtCharEncoding Function ^TOP^

Purpose

Return the minimum encoding required to represent a character.

Declared In

TextMgr.h

Prototype

CharEncodingType TxtCharEncoding (
   WChar inChar
)

Parameters

→ inChar: A valid character.

Returns

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 represents the fewest number of characters while still containing the character specified in inChar. 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.

This function is used by TxtStrEncoding(), which is the function that most applications should use to determine the character encoding for tagging text (for instance, for email).

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 80, "PalmOSGlue Library."

Palm OS only supports a single character encoding at a time. Because of this, the result of TxtCharEncoding 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.

TxtCharIsAlNum Macro ^TOP^

Purpose

Indicates if the character is alphanumeric.

Declared In

TextMgr.h

Prototype

#define TxtCharIsAlNum (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsAlpha Macro ^TOP^

Purpose

Indicates if a character is a letter in an alphabet.

Declared In

TextMgr.h

Prototype

#define TxtCharIsAlpha (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsCntrl Macro ^TOP^

Purpose

Indicates if a character is a control character.

Declared In

TextMgr.h

Prototype

#define TxtCharIsCntrl (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsDelim Macro ^TOP^

Purpose

Indicates if a character is a delimiter.

Declared In

TextMgr.h

Prototype

#define TxtCharIsDelim (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsDigit Macro ^TOP^

Purpose

Indicates if the character is a decimal digit.

Declared In

TextMgr.h

Prototype

#define TxtCharIsDigit (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsGraph Macro ^TOP^

Purpose

Indicates if a character is a graphic character.

Declared In

TextMgr.h

Prototype

#define TxtCharIsGraph (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsHardKey Macro ^TOP^

Purpose

Returns true if the character is one of the hard keys on the device.

Declared In

TextMgr.h

Prototype

#define TxtCharIsHardKey (
   m,
   ch
)

Parameters

→ m: The modifier keys from the keyDownEvent.
→ ch: The character from the keyDownEvent.

Returns

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.

TxtCharIsHex Macro ^TOP^

Purpose

Indicates if a character is a hexadecimal digit.

Declared In

TextMgr.h

Prototype

#define TxtCharIsHex (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsLower Macro ^TOP^

Purpose

Indicates if a character is a lowercase letter.

Declared In

TextMgr.h

Prototype

#define TxtCharIsLower (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsPrint Macro ^TOP^

Purpose

Indicates if a character is printable.

Declared In

TextMgr.h

Prototype

#define TxtCharIsPrint (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsPunct Macro ^TOP^

Purpose

Indicates if a character is a punctuation mark.

Declared In

TextMgr.h

Prototype

#define TxtCharIsPunct (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsRockerKey Macro ^TOP^

Purpose

Determines whether or not a given character and event modifier combination indicate that the key is a 5-way rocker key.

Declared In

TextMgr.h

Prototype

#define TxtCharIsRockerKey (
   m,
   c
)

Parameters

→ m: The event modifier.
→ c: The character.

Returns

true if c is one of the a 5-way rocker keys. c is a rocker key if the event modifier m has the command bit set and c is in the proper range:

vchrRockerUp <= c <= vchrRockerCenter

TxtCharIsSpace Macro ^TOP^

Purpose

Indicates if a character is a whitespace character.

Declared In

TextMgr.h

Prototype

#define TxtCharIsSpace (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsUpper Macro ^TOP^

Purpose

Indicates if a character is an uppercase letter.

Declared In

TextMgr.h

Prototype

#define TxtCharIsUpper (
   ch
)

Parameters

→ ch: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharIsValid Function ^TOP^

Purpose

Determine whether a character is valid character given the Palm OS character encoding.

Declared In

TextMgr.h

Prototype

Boolean TxtCharIsValid (
   WChar inChar
)

Parameters

→ inChar: A character.

Returns

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 80, "PalmOSGlue Library."

TxtCharSize Function ^TOP^

Purpose

Return the number of bytes required to store the character in a string.

Declared In

TextMgr.h

Prototype

UInt16 TxtCharSize (
   WChar inChar
)

Parameters

→ inChar: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCharWidth Function ^TOP^

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.

Declared In

TextMgr.h

Prototype

Int16 TxtCharWidth (
   WChar inChar
)

Parameters

→ inChar: A valid character.

Returns

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 Function ^TOP^

Purpose

Return the extended attribute bits for a character.

Declared In

TextMgr.h

Prototype

UInt16 TxtCharXAttr (
   WChar inChar
)

Parameters

→ inChar: A valid character.

Returns

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 80, "PalmOSGlue Library."

TxtCompare Function ^TOP^

Purpose

Performs a case-sensitive comparison of all or part of two text buffers.

Declared In

TextMgr.h

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.

Returns

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 80, "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.

TxtConvertEncoding Function ^TOP^

Purpose

Convert a text buffer from one character encoding to another.

Declared In

TextMgr.h

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: Set to 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 a TxtConvertStateType structure containing the same data used for the previous invocation. If newConversion is true and no subsequent calls are planned, this parameter can be NULL.
→ srcTextP: Pointer to the source 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 starting at srcTextP that needs to be converted. Upon return, *ioSrcBytes contains the number of bytes successfully processed.
→ srcEncoding: The character encoding that the source text uses. This should be one of the Character Encoding Constants.
→ dstTextP: Pointer to the destination text buffer, or NULL if you only want to know how large the destination text buffer must be (the minimum size is returned in *ioDstBytes). If not NULL, dstTextP should point to a location where TxtConvertEncoding() can begin writing.
→ ioDstBytes: A pointer to the length, in bytes, of dstTextP. Upon return, *ioDstBytes contains the number of bytes required to represent the source text in the new encoding.
→ dstEncoding: The character encoding to which to convert srcTextP. This should be one of the constants documented in "Character Encoding Constants." Note that the encoding can be modified, giving you greater control over the conversion process: see "Character Encoding Constant Modifiers."
→ substitutionStr: A string to be substituted for any invalid or inconvertible characters that occur in the source text. This string must already be in the destination encoding. If NULL, TxtGlueConvertEncoding() immediately returns if it encounters an invalid character.
→ substitutionLen: The number of bytes in substitutionStr, not including the terminating null byte.

Returns

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.
txtErrMalformedText: An error in the source text encoding has been discovered.
txtErrNoCharMapping: The device does not contain a mapping between the source and destination encodings for at least one of the characters in srcTextP, and there is no substitution string.
txtErrUnknownEncoding: One of the specified encodings is unknown or can't be handled, or the function is being called on a handheld running a version of Palm OS prior to 3.5.
txtErrUnknownEncodingFallbackCopy: Either the source or destination encoding is unknown, and the best fit flag was set in the destination encoding. Before returning this error code, TxtConvertEncoding() copies anything that is 7-bit ASCII from the source text buffer to the destination text buffer.

Comments

This function converts ioSrcBytes of text in srcTextP from the srcEncoding to the dstEncoding character encoding and returns the result in dstTextP.

TxtConvertEncoding() can convert between the following "built-in" encodings and the device encoding:

UTF-8
UTF-16, UTF-16BE, UTF-16LE, UCS-2
UTF-32, UTF-32BE, UTF-32LE, UCS-4²

It can also support a variety of encodings that are locale dependent. The only locale for which TxtConvertEncoding() supports additional encodings is simplified Chinese in Palm OS versions that support simplified Chinese. The additional source encodings supported for the simplified Chinese locale are:

GB2312
GBK
ISO2022-CN
Big5
Big5+HKSCS
CP1252
ISO8859-1
US ASCII (ISO646)
GSM

The additional destination encodings supported for the simplified Chinese locale are:

GB2312
GBK
ISO2022-CN
GSM

If the charEncodingDstBestFitFlag is supported (see "Character Encoding Constant Modifiers") but is not set in the destination encoding passed to the function, and you specify an unsupported character encoding for either the source or the destination buffer, TxtConvertEncoding() returns txtErrUnknownEncoding.

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 (assuming that no other higher-priority error occurred during the conversion). If substitutionStr is NULL, the function stops the conversion and immediately returns txtErrNoCharMapping. ioSrcBytes is set to the offset of the inconvertible character, dstTextP contains the converted string up to that point, and ioDstBytes contains the size of the converted text. You can examine the character at ioSrcBytes and choose to move past it and continue the conversion. Follow the rules for making repeated calls to TxtConvertEncoding() as described in the next paragraph.

You can make repeated calls to TxtConvertEncoding() in a loop if you only want to convert part of the input buffer at a time. When you make repeated calls to this function, the first call should use true for newConversion, and srcTextP should point to the start of the text buffer. All subsequent calls should use the following values:

newConversion: false.
ioStateP: The same data that was returned by the previous invocation.
srcTextP: The location where this call should begin converting. Typically, this would be the previous srcTextP plus the number of bytes returned in ioSrcBytes.; If you are skipping over an inconvertible character, srcTextP must point to the character after that location.
↔ ioSrcBytes: The number of bytes that this function call should convert.
dstTextP: A pointer to a location where this function can begin writing the converted string. You might choose to have each function call write to a different destination buffer. To have successive calls write to the same buffer, pass the previous dstTextP plus the number of bytes returned in ioDstBytes each time.
ioDstBytes: The number of bytes available for output in the dstTextP buffer. In other words, the number of bytes remaining.

Encodings Supported by Various ROMs

The locale module is designed to provide support for Unicode, the device encoding, and a set of related or locale-important encodings. The following tables summarize the set of encodings supported in TxtConvertEncoding() by various ROMs.

The encoding returned by the Locale Manager in Palm OS Garnet version 5.3SC (or in an earlier release if you use TxtGlueConvertEncoding()) for lmChoiceInboundDefaultVObjectEncoding is supported as a source encoding, and the encodings returned for lmChoicePrimarySMSEncoding, lmChoiceSecondarySMSEncoding, lmChoicePrimaryEmailEncoding, lmChoiceSecondaryEmailEncoding, and lmChoiceOutboundVObjectEncoding are supported as destination encodings. The exception to this rule is charEncodingAscii, which gets returned by LmGlueGetLocaleSetting(lmChoicePrimaryEmailEncoding) on systems running a version of Palm OS prior to 5.3SC. This encoding—charEncodingAscii—isn't supported as a destination encoding on Palm OS prior to 5.3SC.

Table 55.1 Source encodings for Latin ROMs version 4.0, 4.1, 5.0, 5.1, 5.2

`charEncodingUCS2`	`charEncodingUTF8`
`charEncodingUTF16LE`	`charEncodingUTF16BE`
`charEncodingPalmLatin`

Table 55.2 Destination encodings for Latin ROMs version 4.0, 4.1, 5.0, 5.1, 5.2

`charEncodingUCS2`	`charEncodingUTF8`
`charEncodingUTF16LE`	`charEncodingUTF16BE`
`charEncodingPalmLatin`

Table 55.3 Source encodings for Shift-JIS ROMs version 4.0, 4.1, 5.0, 5.1, 5.2

`charEncodingUCS2`	`charEncodingUTF8`
`charEncodingUTF16LE`	`charEncodingUTF16BE`
`charEncodingPalmSJIS`

Table 55.4 Destination encodings for Shift-JIS ROMs version 4.0, 4.1, 5.0, 5.1, 5.2

`charEncodingUCS2`	`charEncodingUTF8`
`charEncodingUTF16LE`	`charEncodingUTF16BE`
`charEncodingPalmSJIS`

Table 55.5 Source encodings for GB ROMs version 5.3SC

`charEncodingUCS2`	`charEncodingUTF8`
`charEncodingUTF16`	`charEncodingUTF16LE`
`charEncodingUTF16BE`	`charEncodingUTF32`
`charEncodingUTF32BE`	`charEncodingUTF32LE`
`charEncodingUCS4`	`charEncodingPalmGB`
`charEncodingGB2312`	`charEncodingGBK`
`charEncodingISO2022CN`	`charEncodingBig5`
`charEncodingBig5_HKSCS`	`charEncodingAscii`
`charEncodingCP1252`	`charEncodingISO8859_1`
`charEncodingGSM`

Table 55.6 Destination encodings for GB ROMs version 5.3SC

`charEncodingUCS2`	`charEncodingUTF8`
`charEncodingUTF16`	`charEncodingUTF16LE`
`charEncodingUTF16BE`	`charEncodingUTF32`
`charEncodingUTF32BE`	`charEncodingUTF32LE`
`charEncodingUCS4`	`charEncodingPalmGB`
`charEncodingGB2312`	`charEncodingGBK`
`charEncodingISO2022CN`	`charEncodingAscii`
`charEncodingISO8859_1`	`charEncodingGSM`

Compatibility

Implemented only if 4.0 New Feature Set is present. To use this function in code intended to be run on Palm OS 3.5, link with the PalmOSGlue library and call TxtGlueConvertEncoding(). For more information, see Chapter 80, "PalmOSGlue Library."

In Palm OS versions that do not support simplified Chinese, 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.

Prior to Palm OS Garnet version 5.3SC, due to a bug in the implementation of this function the destination buffer must be larger than what is needed in order to accommodate the destination text. If the destination buffer is exactly the right size, an error is returned. Accordingly, if you call TxtConvertEncoding() and pass NULL for dstTextP in order to determine the needed buffer size, add one to the returned buffer size when you allocate the buffer.

TxtEncodingName Function ^TOP^

Purpose

Obtain a character encoding's name.

Declared In

TextMgr.h

Prototype

const Char *TxtEncodingName(
   CharEncodingType inEncoding
)

Parameters

→ inEncoding: One of the values from CharEncodingType, indicating a character encoding.

Returns

A constant string containing the name of the encoding. The possible return values are defined in PalmLocale.h.

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 80, "PalmOSGlue Library."

TxtFindString Function ^TOP^

Purpose

Perform a case-insensitive search for a string in another string.

Declared In

TextMgr.h

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.

Returns

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 80, "PalmOSGlue Library."

TxtGetChar Function ^TOP^

Purpose

Retrieve the character starting at the specified offset within a text buffer.

Declared In

TextMgr.h

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.

Returns

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 80, "PalmOSGlue Library."

TxtGetNextChar Function ^TOP^

Purpose

Retrieve the character starting at the specified offset within a text buffer.

Declared In

TextMgr.h

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.

Returns

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

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 80, "PalmOSGlue Library."

TxtGetPreviousChar Function ^TOP^

Purpose

Retrieve the character before the specified offset within a text buffer.

Declared In

TextMgr.h

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.

Returns

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.

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 80, "PalmOSGlue Library."

TxtGetTruncationOffset Function ^TOP^

Purpose

Return the appropriate byte position for truncating a text buffer such that it is at most a specified number of bytes long.

Declared In

TextMgr.h

Prototype

UInt32 TxtGetTruncationOffset (
   const Char *inText,
   UInt32 inOffset
)

Parameters

→ inText: Pointer to a text buffer.
→ inOffset: An offset into the buffer inText.

Returns

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

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 80, "PalmOSGlue Library."

TxtGetWordWrapOffset Function ^TOP^

Purpose

Locate an appropriate place for a line break in a text buffer.

Declared In

TextMgr.h

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.

Returns

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.

TxtMaxEncoding Function ^TOP^

Purpose

Return the higher of two encodings.

Declared In

TextMgr.h

Prototype

CharEncodingType TxtMaxEncoding(
   CharEncodingType a,
   CharEncodingType b
)

Parameters

→ a: A character encoding to compare.
→ b: Another character encoding to compare.

Returns

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 80, "PalmOSGlue Library."

TxtNameToEncoding Function ^TOP^

Purpose

Return an encoding's constant given its name.

Declared In

TextMgr.h

Prototype

CharEncodingType TxtNameToEncoding(
   const Char *iEncodingName
)

Parameters

→ iEncodingName: One of the string constants containing the official name of an encoding. See PalmLocale.h for the complete set of string constants.

Returns

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.

TxtNextCharSize Macro ^TOP^

Purpose

Returns the size of the character starting at the specified offset within a text buffer.

Declared In

TextMgr.h

Prototype

#define 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.

Returns

Returns (as a UInt16) the size in bytes of the character at inOffset.

Comments

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 80, "PalmOSGlue Library."

TxtParamString Function ^TOP^

Purpose

Replace substrings within a string with the specified values.

Declared In

TextMgr.h

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.

Returns

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 80, "PalmOSGlue Library."

TxtPreviousCharSize Macro ^TOP^

Purpose

Returns the size of the character before the specified offset within a text buffer.

Declared In

TextMgr.h

Prototype

#define 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.

Returns

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

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 80, "PalmOSGlue Library."

TxtReplaceStr Function ^TOP^

Purpose

Replace a substring of a given format with another string.

Declared In

TextMgr.h

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

Returns

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 80, "PalmOSGlue Library."

TxtSetNextChar Function ^TOP^

Purpose

Set a character within a text buffer.

Declared In

TextMgr.h

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.

Returns

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 80, "PalmOSGlue Library."

TxtStrEncoding Function ^TOP^

Purpose

Return the encoding required to represent a string.

Declared In

TextMgr.h

Prototype

CharEncodingType TxtStrEncoding(
   const Char *inStr
)

Parameters

→ inStr: A string.

Returns

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.

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 80, "PalmOSGlue Library."

Palm OS only supports a single character encoding at a time. Because of this, the value returned from 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.

TxtTransliterate Function ^TOP^

Purpose

Converts the specified number of bytes in a text buffer using the specified operation.

Declared In

TextMgr.h

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. See TranslitOpType for the possible values for this field.

Returns one of the following values:

errNone: Success
txtErrUknownTranslitOp: inOp's value is not recognized
txtErrTranslitOverrun: inSrcText and outDstText point to the same memory location and the operation has caused the function to overwrite unprocessed data in the input buffer.
txtErrTranslitOverflow: outDstText is not large enough to contain the converted string.
txtErrTranslitUnderflow: The end of the source buffer contains a partial character.

Comments

inSrcText and outDstText may point to the same location if you want to perform the operation in place. However, you should be careful that the space required for outDstText is not larger than inSrcText so that you don't generate a txtErrTranslitOverrun error.

For example, suppose on a Shift JIS encoded system, you want to convert a series of single-byte Japanese Katakana symbols to double-byte Katakana symbols. You cannot perform this operation in place because it replaces a single-byte character with a multi-byte character. When the first converted character is written to the buffer, it overwrites the second input character. Thus, a text overrun has occurred.

You can ensure that you have enough space for the output by OR-ing your chosen operation with translitOpPreprocess. For example, to convert a string to uppercase letters, do the following:

outSize = buf2Len;
error = TxtTransliterate(buf1, buf1len, &buf2,
&outSize,
translitOpUpperCase|translitOpPreprocess); 
if (outSize > buf2len) 
    /* allocate more memory for buf2 */ 
error = TxtTransliterate(buf1, buf1Len, &buf2,
&outSize, translitOpUpperCase);

You must make sure that the parameter inSrcText points to the start of a valid character. That is, it must point to the first byte of a multi-byte character or it must point to a single-byte character; if it doesn't, results are unpredictable.

Compatibility

Implemented only if International Feature Set is present. To use this function in code intended to be run on earlier versions of Palm OS, link with the PalmOSGlue library and call TxtGlueTransliterate. For more information, see Chapter 80, "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 Function ^TOP^

Purpose

Find the boundaries of a word of text that contains the character starting at the specified offset.

Declared In

TextMgr.h

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.

Returns

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

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 80, "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.

55 Text Manager

Text Manager Data Structures ^TOP^

CharEncodingType Typedef ^TOP^

Purpose

Prototype

Comments

Compatibility

TranslitOpType Typedef ^TOP^

Purpose

Prototype

Comments

TxtConvertStateType Struct ^TOP^

Purpose

Prototype

Text Manager Constants ^TOP^

Character Encoding Constant Modifiers ^TOP^

Compatibility

Character Encoding Feature Attributes ^TOP^

Character Attributes ^TOP^

Character Sizes ^TOP^

Text Manager Functions ^TOP^

TxtByteAttr Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

TxtCaselessCompare Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

TxtCharAttr Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

TxtCharBounds Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

TxtCharEncoding Function ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Comments

Compatibility

See Also

TxtCharIsAlNum Macro ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Compatibility

See Also

TxtCharIsAlpha Macro ^TOP^

Purpose

Declared In

Prototype

Parameters

Returns

Compatibility

See Also