< Home < Developers < Development Support < Documentation

## 76 PalmOSGlue Library

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part IV: Libraries 76 PalmOSGlue Library PalmOSGlue Functions CtlGlueGetControlStyle FldGlueGetLineInfo FntGlueGetDefaultFontID FrmGlueGetObjectUsable IntlGlueGetRoutineAddress SysGlueTrapExists TxtGlueCharIsVirtual TxtGlueGetHorizEllipsisChar TxtGlueGetNumericSpaceChar TxtGlueLowerChar TxtGlueLowerStr TxtGluePrepFindString TxtGlueStripSpaces TxtGlueTruncateString TxtGlueUpperChar TxtGlueUpperStr |  |  |  | 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, vol. I and you want to maintain backward compatibility with earlier releases of Palm OS®. If you link with PalmOSGlue, include the headers in the folder Incs\Libraries\PalmOSGlue, 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 76.1 PalmOSGlue function mappings
This PalmOSGlue function... | ...is identical to...
--- | ---
BmpGlueGetBitDepth | BmpGetBitDepth
BmpGlueGetDimensions | BmpGetDimensions
BmpGlueGetNextBitmap | BmpGetNextBitmap
DateGlueTemplateToAscii | DateTemplateToAscii
DateGlueToDOWDMFormat | DateToDOWDMFormat
FntGlueWCharWidth | FntWCharWidth
FntGlueWidthToOffset | FntWidthToOffset
FrmGlueGetActiveField |
LmGlueGetLocaleSetting | LmGetLocaleSetting
LmGlueGetNumLocales | LmGetNumLocales
LmGlueLocaleToIndex | LmLocaleToIndex
LstGlueGetTopItem | LstGetTopItem
OmGlueGetCurrentLocale | OmGetCurrentLocale
OmGlueGetSystemLocale | OmGetSystemLocale
ResGlueLoadConstant | ResLoadConstant
SysGlueGetTrapAddress | SysGetTrapAddress
TsmGlueGetFepMode | TsmGetFepMode
TsmGlueSetFepMode | TsmSetFepMode
TblGlueGetNumberOf Columns | TblGetNumberOfColumns
TblGlueGetTopRow | TblGetTopRow
TblGlueSetSelection | TblSetSelection
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 | FntWCharWidth
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
## New CtlGlueGetControlStyle #### Purpose Return the type of the control, such as button, slider, and so on. #### Prototype ControlStyleType CtlGlueGetControlStyle (const ControlType *ctlP) #### Parameters #####
-> ctlP | A pointer to a ControlType structure.
#### Result Returns one of the ControlStyleType constants. #### Compatibility Implemented only in the PalmOSGlue library. ## New FldGlueGetLineInfo #### Purpose Retrieve the word-wrapping information for a visible line within a field. #### Prototype Boolean FldGlueGetLineInfo (const FieldType *fldP, UInt16 lineNum, UInt16 *startP, UInt16 *lengthP) #### Parameters #####
-> fldP | A pointer to a FieldType structure.
#####
-> lineNum | The number of the visible line in the field about which you want to retrieve information. Lines are numbered starting at 0.
#####
<- startP | The byte offset into the FieldType's text field of the first character displayed by this line. If the line is blank, start is equal to the length of the field's text string.
#####
<- lengthP | The length in bytes of the portion of the string displayed on this line. If the line is blank, the length is 0.
#### Result Returns true if startP and endP contain valid values, or false if the field is a single-line field or does not contain a line numbered lineNum. #### Compatibility Implemented only in the PalmOSGlue library. ## 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 ## New FrmGlueGetObjectUsable #### Purpose Returns whether an object in a form has been hidden. #### Prototype Boolean FrmGlueGetObjectUsable (const FormType *formP, UInt16 objIndex) #### Parameters #####
-> formP | A pointer to a FormType structure.
#####
-> objIndex | The index of the object on the form.
#### Result Returns true if the object is usable, meaning that it is considered part of the user interface. Returns false if the object is not usable. Objects that are not usable never appear on the screen. The function FrmHideObject clears an object's usable bit to hide that the object. #### Comments Implemented only in the PalmOSGlue library. ## New IntlGlueGetRoutineAddress #### Purpose Return the address of a Text Manager function or of its PalmOSGlue equivalent. #### Prototype void *IntlGlueGetRoutineAddress (IntlSelector selector, const void *latinSymbol) #### Parameters #####
-> selector | One of the routine selectors defined in IntlMgr.h.
#####
-> latinSymbol | The corresponding TxtLatin func symbol defined in IntlGlue.h.
#### Result Returns the address of the native Palm OS function if it is defined. If the function is not defined, it returns the address of the corresponding PalmOSGlue function. #### Comments Use IntlGlueGetRoutineAddress for performance reasons. You can use the address that it returns to call the function at that address without having to go through the International Manager's trap dispatch table. IntlGlueGetRoutineAddress is mostly useful for optimizing the performance of Text Manager functions that are called in a tight loop. To call IntlGlueGetRoutineAddress, you must pass both the international trap for the function and the corresponding symbol. For example, to obtain the address of the TxtGetNextChar function or of its PalmOSGlue equivalent, you would make this call:
    myTxtGetNextChar =
      IntlGlueGetRoutineAddress(intlTxtGetNextChar,
        TxtLatinGetNextChar);
The returned address is only valid while your application stays locked in memory. For this reason, you should only use the returned address up to the point where your application terminates. When the application starts up again, you should call IntlGlueGetRoutineAddress again. #### Compatibility Implemented only in the PalmOSGlue library. #### See Also IntlGetRoutineAddress ## New SysGlueTrapExists #### Purpose Macro that indicates if a given trap exists on the current system. #### Prototype SysGlueTrapExists (trapNum) #### Parameters #####
-> trapNum | One of the system trap constants.
#### Result Returns true if the current operating system defines the system trap trapNum, or false if the trap does not exist on that version of the operating system. #### Compatibility Implemented only in the PalmOSGlue library. ## 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 #####
None.
#### Result Returns the character code for horizontal ellipsis. #### Comments Versions 3.1 and higher of the Palm OS use 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 #####
None.
#### Result Returns the character code for numeric space. #### Comments Versions 3.1 and higher of the Palm OS use 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 does not handle the case in which the lowercase version of a character is represented by two or more characters. If you need to handle this situation, call the TxtGlueLowerStr function instead of this one. #### 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 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. ## New TxtGlueTruncateString #### Purpose Determine if a string can be displayed in a given number of pixels. If not, truncate the string. #### Prototype Boolean TxtGlueTruncateString (Char *ioStringP, UInt16 inMaxWidth) #### Parameters #####
<-> ioStringP | A null-terminated string. Upon return, the string is truncated if necessary so that it can be displayed in inMaxWidth pixels.
#####
-> inMaxWidth | The maximum width in pixels.
#### Result Returns true if the string was truncated, or false if the string can fit without truncation. #### Comments This function determines whether ioStringP can be displayed in the specified width without being truncated. If it can, TxtGlueTruncateString returns false. If the string must be truncated, this function truncates the string to one less than the number of characters that can fit in inMaxWidth and then appends an ellipsis (...) character. (If the boundary characters are narrower than the ellipsis, more than one character may be dropped to make room). If inMaxWidth is narrower than the width of an ellipsis, the string is set to the empty string. #### Compatibility Implemented only in the PalmOSGlue library. #### See Also FntWidthToOffset, WinDrawTruncChars, TxtGetTruncationOffset ## 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 does not handle the case in which the uppercase version of a character is represented by two or more characters. If you need to handle this situation, call the TxtGlueUpperStr function instead of this one. #### 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 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 |