62 PalmOSGlue Library

This chapter describes the API provided in the link library PalmOSGlue (PalmOSGlue.lib or libPalmOSGlue.a).

You use PalmOSGlue if you want to use the international and text manager features described in the chapter "Localized Applications" in the Palm OS Programmer's Companion and you want to maintain backward compatibility with earlier releases. If you link with PalmOSGlue, include the headers DateGlue.h, FntGlue.h, TxtGlue.h, TsmGlue.h, and WinGlue.h (in the International directory), and make calls as they are listed in this chapter, then your code will run regardless of whether the device's version of the operating system implements international support. The code in PalmOSGlue either uses the text manager or international manager on the ROM or, if the managers don't exist, executes a simple Latin equivalent of the function.

---

NOTE:  

PalmOSGlue is a link library, not a shared library. Linking with this library increases your application's code size. The amount by which your code size increases varies depending on the number of library functions you call. Use PalmOSGlue only on versions 2.0 and later of Palm OS^®.

---

In addition to covering the text and international manager API, PalmOSGlue adds some functions that are not included in any version of the Palm OS. This chapter describes the functions that are unique to PalmOSGlue and provides a mapping of PalmOSGlue calls to calls that exist in later versions of Palm OS.

PalmOSGlue Functions

The following table shows the mapping between the functions declared in the glue headers and the international functions and macros. To learn more about a glue function, click the link in the right column.

This table lists only those functions that map to a function that exists in newer versions of the OS. The functions that are exclusive to PalmOSGlue are not listed. They are described following this table.

Table 62.1 PalmOSGlue function mappings 

This PalmOSGlue function...	...is identical to...
DateGlueToAscii	DateToAscii
DateGlueToDOWDMFormat	DateToDOWDMFormat
TsmGlueGetFepMode	TsmGetFepMode
TsmGlueSetFepMode	TsmSetFepMode
TxtGlueByteAttr	TxtByteAttr
TxtGlueCaselessCompare	TxtCaselessCompare
TxtGlueCharAttr	TxtCharAttr
TxtGlueCharBounds	TxtCharBounds
TxtGlueCharEncoding	TxtCharEncoding
TxtGlueCharIsAlNum	TxtCharIsAlNum
TxtGlueCharIsAlpha	TxtCharIsAlpha
TxtGlueCharIsCntrl	TxtCharIsCntrl
TxtGlueCharIsDelim	TxtCharIsDelim
TxtGlueCharIsDigit	TxtCharIsDigit
TxtGlueCharIsGraph	TxtCharIsGraph
TxtGlueCharIsHex	TxtCharIsHex
TxtGlueCharIsLower	TxtCharIsLower
TxtGlueCharIsPrint	TxtCharIsPrint
TxtGlueCharIsPunct	TxtCharIsPunct
TxtGlueCharIsSpace	TxtCharIsSpace
TxtGlueCharIsUpper	TxtCharIsUpper
TxtGlueCharIsValid	TxtCharIsValid
TxtGlueCharSize	TxtCharSize
TxtGlueCharWidth	TxtCharWidth
TxtGlueCharXAttr	TxtCharXAttr
TxtGlueCompare	TxtCompare
TxtGlueEncodingName	TxtEncodingName
TxtGlueFindString	TxtFindString
TxtGlueGetChar	TxtGetChar
TxtGlueGetNextChar	TxtGetNextChar
TxtGlueGetPreviousChar	TxtGetPreviousChar
TxtGlueGetTruncation Offset	TxtGetTruncationOffset
TxtGlueMaxEncoding	TxtMaxEncoding
TxtGlueNextCharSize	TxtNextCharSize
TxtGlueParamString	TxtParamString
TxtGluePreviousCharSize	TxtPreviousCharSize
TxtGlueReplaceStr	TxtReplaceStr
TxtGlueSetNextChar	TxtSetNextChar
TxtGlueStrEncoding	TxtStrEncoding
TxtGlueTransliterate	TxtTransliterate
TxtGlueWordBounds	TxtWordBounds
WinGlueDrawChar	WinDrawChar
WinGlueDrawTruncChars	WinDrawTruncChars

FntGlueGetDefaultFontID

Purpose

Return the font ID of a default font.

Prototype

FontID FntGlueGetDefaultFontID ( FontDefaultType inFontType)

Parameters

-> inFontType

A FontDefaultType constant specifying one of the system default fonts. This value can be one of the following:

defaultSystemFont

The default font for the system.

defaultLargeFont

The default large font.

defaultSmallFont

The default small font.

defaultBoldFont

The default bold font.

Result

Returns the ID of inFontType.

Comments

Use this function whenever you need to obtain a font ID for one of the system default fonts. The default fonts (and thus, the IDs for the default fonts) vary depending on the system's locale. For example, Japanese systems have a different set of default fonts than systems using the Latin character encoding.

Use this function in place of the constants that specify the IDs of default fonts, as shown in the following table.

In place of this...	...use FntGlueGetDefaultFontID with this constant...
stdFont	defaultSystemFont (best for displaying text) or: defaultSmallFont (if you want a smaller font)
largeFont	defaultLargeFont
largeBoldFont	defaultLargeFont
boldFont	defaultBoldFont

Note that defaultSystemFont and defaultSmallFont might return the same font ID or different font IDs, depending on the system locale.

Compatibility

Implemented only in the PalmOSGlue library.

See Also

FontSelect, FntGetFont, FntSetFont

TxtGlueCharIsVirtual

Purpose

Return whether a character is a virtual character or not.

Prototype

Boolean TxtGlueCharIsVirtual(UInt16 inModifiers, WChar inChar)

Parameters

-> inModifiers

The value passed in the modifiers field of the keyDownEvent.

-> inChar

A character.

Result

Returns true if the character inChar is a virtual character, false otherwise.

Comments

Virtual characters are nondisplayable characters that trigger special events in the operating system, such as displaying low battery warnings or displaying the keyboard dialog. Virtual characters should never occur in any data and should never appear on the screen.

Starting in Palm OS 3.1, the command modifier bit is always set in the keyDownEvent for a virtual character because the range for virtual characters overlaps the range for "real" characters that should appear on the screen. Earlier releases of the operating system did not always set the command modifier for virtual characters.

You can use this function to test whether a character is virtual or not. Pass the chr and modifiers fields exactly as you received them in the keyDownEvent, and this function performs the appropriate check based on the operating system version.

Compatibility

Implemented only in the PalmOSGlue library.

TxtGlueGetHorizEllipsisChar

Purpose

Return the horizontal ellipsis character.

Prototype

WChar TxtGlueGetHorizEllipsisChar (void)

Parameters

Result

Returns the character code for horizontal ellipsis.

Comments

Version 3.1 of the Palm OS uses different character codes for the horizontal ellipsis character and the numeric space character than earlier versions did. Use TxtGlueGetHorizEllipsisChar to return the appropriate code for horizontal ellipsis regardless of which version of Palm OS your application is run on.

Compatibility

Implemented only in the PalmOSGlue library.

See Also

ChrHorizEllipsis, TxtGlueGetNumericSpaceChar

TxtGlueGetNumericSpaceChar

Purpose

Return the numeric space character.

Prototype

WChar TxtGlueGetNumericSpaceChar (void)

Parameters

Result

Returns the character code for numeric space.

Comments

Version 3.1 of the Palm OS uses different character codes for the horizontal ellipsis character and the numeric space character than earlier versions did. Use TxtGlueGetNumericSpaceChar to return the appropriate code for numeric space regardless of which version of Palm OS your application is run on.

Compatibility

Implemented only in the PalmOSGlue library.

See Also

ChrNumericSpace, TxtGlueGetHorizEllipsisChar

TxtGlueLowerChar

Purpose

Convert a character to lowercase.

Prototype

WChar TxtGlueLowerChar (WChar inChar)

Parameters

-> inChar

A character.

Result

Returns the character as a lowercase letter.

Comments

This function can only handle characters in the ISO Latin 1 character encoding unless the International Feature Set is present.

Compatibility

Implemented only in the PalmOSGlue library.

See Also

TxtGlueUpperChar, TxtGlueLowerStr, TxtGlueUpperStr, TxtGlueTransliterate, TxtTransliterate, StrToLower

TxtGlueLowerStr

Purpose

Convert a string to all lowercase letters.

Prototype

void TxtGlueLowerStr (Char* ioString, UInt16 inMaxLength)

Parameters

<-> ioString

The string to be converted.

-> inMaxLength

The size of the buffer that contains the string, excluding the terminating NULL character.

Result

Returns in ioString the input string with its letters converted to lowercase.

Comments

On systems that use multi-byte character encodings, converting a string from uppercase to lowercase letters or vice versa may change the size of the string. For this reason, you should always check the size of the ioString after this call returns.

You must make sure that the parameter ioString points to the start of a 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 function can only handle characters in the ISO Latin 1 character encoding unless the International Feature Set is present.

Compatibility

Implemented only in the PalmOSGlue library.

See Also

TxtGlueUpperStr, TxtGlueLowerChar, TxtGlueUpperChar, StrToLower TxtGlueTransliterate, TxtTransliterate

TxtGluePrepFindString

Purpose

Set up for TxtFindString or FindStrInStr.

Prototype

void TxtGluePrepFindString (const Char* inSource, CharPtr outDest, UInt16 inDstSize)

Parameters

-> inSource

Pointer to the text to be searched for. Must not be NULL.

<- outDest

The same text as in inSource but converted to a suitable format for searching. outDest must not be the same address as inSource.

-> inDstSize

The length in bytes of the area pointed to by outDest.

Result

Returns in outDest an appropriately converted string.

Comments

Use this function to normalize the string to search for before using TxtGlueFindString, TxtFindString, or FindStrInStr to perform a search that is internal to your application. If you use any of these three search routines in response to the sysAppLaunchCmdFind launch code, the string that the launch code passes in is already properly normalized for the search.

This function normalizes the string to be searched for. The method by which a search string is normalized varies depending on the version of Palm OS and the character encoding supported by the device.

Only inDstSize bytes of inSource are written to outDest. If necessary to prevent overflow of the destination buffer, not all of inSource is converted.

You must make sure that the parameter inSource 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 in the PalmOSGlue library.

TxtGlueStripSpaces

Purpose

Strip trailing and/or leading spaces from a string.

Prototype

Char* TxtGlueStripSpaces (Char* ioStr, Boolean leading, Boolean trailing)

Parameters

<-> ioStr

Any string.

-> leading

If true, strip the leading spaces from the string.

-> trailing

If true, strip the trailing spaces from the string.

Result

Returns ioStr with the specified spaces stripped from it. Note that this function both changes the ioStr buffer parameter and returns a pointer to it.

Comments

You must make sure that the parameter ioStr points to the start of a 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 in the PalmOSGlue library.

TxtGlueUpperChar

Purpose

Convert a character to uppercase.

Prototype

WChar TxtGlueUpperChar (WChar inChar)

Parameters

-> inChar

Any character.

Result

Returns the character as an uppercase letter.

Comments

This function can only handle characters in the ISO Latin 1 character encoding unless the International Feature Set is present.

Compatibility

Implemented only in the PalmOSGlue library.

See Also

TxtGlueLowerChar, TxtGlueUpperStr TxtGlueLowerStr, TxtGlueTransliterate, TxtTransliterate StrToLower

TxtGlueUpperStr

Purpose

Convert a string to all uppercase letters.

Prototype

void TxtGlueUpperStr (Char* ioString, UInt16 inMaxLength)

Parameters

<-> ioString

The string to be converted.

-> inMaxLength

The size of the buffer that contains the string, excluding the terminating NULL character.

Result

Returns in ioString the input string with its letters converted to uppercase.

Comments

On systems that use multi-byte character encodings, converting a string from uppercase to lowercase letters or vice versa may change the size of the string. For this reason, you should always check the size of the ioString after this call returns.

You must make sure that the parameter ioString 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 function can only handle characters in the ISO Latin 1 character encoding unless the International Feature Set is present.

Compatibility

Implemented only in the PalmOSGlue library.

See Also

TxtGlueLowerStr, TxtGlueUpperChar, TxtGlueLowerChar, TxtGlueTransliterate, TxtTransliterate StrToLower