|
|
|
|
47
Text ManagerTextMgr.h declares the API that this chapter describes. For more information on the text manager, see the chapter "Localized Applications" in the Palm OS Programmer's Companion.
CharEncodingType enum specifies possible character encodings. A given device supports a single character encoding. The currently available devices support either Windows code page 1252 (an extension of ISO Latin 1) or Windows code page 932 (an extension of Shift JIS).
typedef enum { charEncodingUnknown = 0, charEncodingAscii, charEncodingISO8859_1, charEncodingPalmLatin, charEncodingShiftJIS, charEncodingPalmSJIS, charEncodingUTF8, charEncodingCP1252, charEncodingCP932} CharEncodingType;
UInt8 TxtByteAttr (UInt8 inByte)
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.
TxtByteAttr to do so. You rarely need to use this function yourself.
Int16 TxtCaselessCompare (const Char* s1, UInt16 s1Len, UInt16* s1MatchLen, const Char* s2, UInt16 s2Len, UInt16* s2MatchLen)
|
Pointer to the first text buffer to compare. Must not be NULL. |
|
Length in bytes of the text pointed to by s1. |
|
Points to the length in bytes of the text in s1 that matched text in s2. Pass NULL for this parameter if you don't need to know this number. |
|
Pointer to the second text buffer to compare. Must not be NULL. |
|
Length in bytes of the text pointed to by s2. |
|
Points to the length in bytes of the text in s2 that matched text in s1. Pass NULL for this parameter if you don't need to know this number. |
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.
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.
UInt16 TxtCharAttr (WChar inChar)
isPunct, isPrintable, and so on. Usually, you'd use one of these macros instead of calling TxtCharAttr directly.
.
WChar TxtCharBounds (const Char* inText, UInt32 inOffset, UInt32* outStart, UInt32* outEnd)
|
Pointer to the text buffer to search. Must not be NULL. |
|
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. |
|
Points to the starting offset of the character containing the byte at inOffset. |
|
Points to the ending offset of the character containing the byte at inOffset. |
outStart and outEnd.
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.
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.
CharEncodingType TxtCharEncoding (WChar inChar)
inChar. If the character isn't recognizable, charEncodingUnknown is returned.
charEncodingAscii because these characters can be represented in single-byte ASCII. If the character is a ü, the minimum encoding is charEncodingISO8859_1.
charEncodingISO8859_1 if you're running on a US or European system and you pass a non-ASCII character.
FtrGet as shown in the TxtCharIsAlNum (ch)
true if the character is a letter in an alphabet or a numeric digit, false otherwise.
TxtCharIsAlpha (ch)
true if the character is a letter in an alphabet, false otherwise.
TxtCharIsCntrl (ch)
true if the character is a non-printable character, such as the bell character or a carriage return; false otherwise.
TxtCharIsDelim (ch)
true if the character is a word delimiter (whitespace or punctuation), false otherwise.
TxtCharIsDigit (ch)
true if the character is 0 through 9, false otherwise.
TxtCharIsGraph (ch)
true if the character is a graphic character, false otherwise.
TxtCharIsHardKey (m, ch)
true if the character is one of the four built-in hard keys on the device, false otherwise.
TxtCharIsHex (ch)
true if the character is a hexadecimal digit from 0 to F, false otherwise.
TxtCharIsLower (ch)
true if the character is a lowercase letter, false otherwise.
TxtCharIsPrint (ch)
true if the character is not a control or virtual character, false otherwise.
true if the character is whitespace. TxtCharIsGraph returns false if the character is whitespace.
TxtCharIsPunct (ch)
true if the character is a punctuation mark, false otherwise.
TxtCharIsSpace (ch)
true if the character is whitespace such as a blank space, tab, or newline; false otherwise.
TxtCharIsUpper (ch)
true if the character is an uppercase letter, false otherwise.
Boolean TxtCharIsValid (WChar inChar)
true if inChar is a valid character; false if inChar is not a valid character.
UInt16 TxtCharSize (WChar inChar)
WChar values; however, strings may store characters as a single-byte value. 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.
Int16 TxtCharWidth (WChar inChar)
UInt16 TxtCharXAttr (WChar inChar)
CharLatin.h or CharShiftJIS.h).
sysFtrNumEncoding as the feature number to determine the character encoding. This returns one of the WChar ch;
UInt16 encoding, attr;
...
attr = TxtCharXAttr(ch);
if (FtrGet(sysFtrCreator, sysFtrNumEncoding,
&encoding) != 0)
encoding = charEncodingCP1252;;
if (encoding == charEncodingUTF8) {
}Int16 TxtCompare (const Char* s1, UInt16 s1Len, UInt16* s1MatchLen, const Char* s2, UInt16 s2Len, UInt16* s2MatchLen)
|
Pointer to the first text buffer to compare. Must not be NULL. |
|
The length in bytes of the text pointed to by s1. |
|
Points to the length in bytes of the text in s1 that matched text in s2. Pass NULL for this parameter if you don't need to know this number. |
|
Pointer to the second text buffer to compare. Must not be NULL. |
|
The length in bytes of the text pointed to by s2. |
|
Points to the length in bytes of the text in s2 that matched text in s1. Pass NULL for this parameter if you don't need to know this number. |
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.
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.
const Char* TxtEncodingName (CharEncodingType inEncoding)
Boolean TxtFindString (const Char* inSourceStr, const Char* inTargetStr, UInt32* outPos, UInt16* outLength)
|
Pointer to the string to be searched. Must not be NULL. |
|
Prepared version of the string to be found. |
|
Pointer to the offset of the match in inSourceStr. |
|
Pointer to the length in bytes of the matching text. |
true if the function finds inTargetStr within inSourceStr; false otherwise.
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.
outLength, to specify the length of the text that matched. Pass this value to 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.
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.
WChar TxtGetChar (const Char* inText, UInt32 inOffset)
|
Pointer to the text buffer to be searched. Must not be NULL. |
|
A valid offset into the buffer inText. This offset must point to an inter-character boundary. |
inOffset in inText.
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.
UInt16 TxtGetNextChar (const Char* inText, UInt32 inOffset, WChar* outChar)
|
Pointer to the text buffer to be searched. Must not be NULL. |
|
A valid offset into the buffer inText. This offset must point to an inter-character boundary. |
|
The character at inOffset in inText. Pass NULL for this parameter if you don't need the character returned. |
inOffset. If outChar is not NULL upon entry, it points to the character at inOffset upon return.
UInt16 i = 0;
while (i < bufferLength) {
i += TxtGetNextChar(buffer, i, &ch);
//do something with ch.
}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.
UInt16 TxtGetPreviousChar (const Char* inText, UInt32 inOffset, WChar* outChar)
|
Pointer to the text buffer to be searched. Must not be NULL. |
|
A valid offset into the buffer inText. This offset must point to an inter-character boundary. |
|
The character immediately preceding inOffset in inText. Pass NULL for this parameter if you don't need the character returned. |
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).
/* 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.}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.
UInt32 TxtGetTruncationOffset (const Char* inText, UInt32 inOffset)
|
Pointer to a text buffer. Must not be NULL. |
|
A valid offset into the buffer inText. |
inText at a valid inter-character boundary. The return value may be less than or equal to inOffset.
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.
CharEncodingType TxtMaxEncoding (CharEncodingType a, CharEncodingType b)
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.
TxtNextCharSize (inText, inOffset)
|
Pointer to the text buffer to be searched. Must not be NULL. |
|
A valid offset into the buffer inText. This offset must point to an inter-character boundary. |
UInt16) the size in bytes of the character at inOffset.
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.
Char* TxtParamString (const Char* inTemplate, const Char* param0, const Char* param1, const Char* param2, const Char* param3)
-> |
The string containing the substrings to replace. |
-> |
String to replace ^0 with or NULL. |
-> |
String to replace ^1 with or NULL. |
-> |
String to replace ^2 with or NULL. |
-> |
String to replace ^3 with or NULL. |
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.
TxtParamString allocates space for the returned string in the dynamic heap. Your code is responsible for freeing this memory when it is no longer needed.
TxtPreviousCharSize (inText, inOffset)
|
Pointer to the text buffer. Must not be NULL. |
|
A valid offset into the buffer inText. This offset must point to an inter-character boundary. |
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).
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.
UInt16 TxtReplaceStr (Char* ioStr, UInt16 inMaxLen, const Char* inParamStr, UInt16 inParamNum)
|
The string in which to perform the replacing. Must not be NULL. |
|
The maximum length in bytes that ioStr can become. |
|
The string that ^inParamNum should be replaced with. If NULL, no changes are made. |
|
A single-digit number (0 to 9). |
inParamNum is greater than 9.
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.
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.
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.
UInt16 TxtSetNextChar (Char* ioText, UInt32 inOffset, WChar inChar)
|
Pointer to a text buffer. Must not be NULL. |
|
A valid offset into the buffer inText. This offset must point to an inter-character boundary. |
|
The character to replace the character at inOffset with. Must not be a virtual character. |
inChar.
ioText at the location inOffset with the character inChar. Note that there must be enough space at inOffset to write the character.
inChar.
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.
CharEncodingType TxtStrEncoding (const Char* inStr)
inChar. If any character in the string isn't recognizable, then charEncodingUnknown is returned.
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.
charEncodingISO8859_1 if you're running on a USA or European system.
FtrGet as shown in the Err TxtTransliterate (const Char* inSrcText, UInt16 inSrcLength, Char* outDstText, UInt16* ioDstLength, TranslitOpType inOp)
|
Pointer to a text buffer. Must not be NULL. |
|
The length in bytes of inSrcText. |
|
The output buffer containing the converted characters. |
|
Upon entry, the maximum length of outDstText. Upon return, the actual length of outDstText. |
|
Converts the character to uppercase letters. |
|
Converts the characters to lowercase letters. |
|
Don't actually perform the operation. Instead, return in ioDstLength the amount of space required for the output text. |
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.
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);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.
Boolean TxtWordBounds (const Char* inText, UInt32 inLength, UInt32 inOffset, UInt32* outStart, UInt32* outEnd)
|
Pointer to a text buffer. Must not be NULL. |
|
The length in bytes of the text pointed to by inText. |
|
A valid offset into the text buffer inText. This offset must point to the beginning of a character. |
|
The starting offset of the text word. |
|
The ending offset of the text word. |
true if a word is found. Returns false if the word doesn't exist or is punctuation or whitespace.
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".
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.
|
|
|
|