PalmOSGlue Library
 

 < 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
BmpGlueGetDimensions
BmpGlueGetNextBitmap
DateGlueTemplateToAscii
DateGlueToDOWDMFormat
FntGlueWCharWidth
FntGlueWidthToOffset
FrmGlueGetActiveField
LmGlueGetLocaleSetting
LmGlueGetNumLocales
LmGlueLocaleToIndex
LstGlueGetTopItem
OmGlueGetCurrentLocale
OmGlueGetSystemLocale
ResGlueLoadConstant
SysGlueGetTrapAddress
TsmGlueGetFepMode
TsmGetFepMode
TsmGlueSetFepMode
TsmSetFepMode
TblGlueGetNumberOf
Columns
TblGlueGetTopRow
TblGlueSetSelection
TxtGlueByteAttr
TxtGlueCaselessCompare
TxtGlueCharAttr
TxtGlueCharBounds
TxtGlueCharEncoding
TxtGlueCharIsAlNum
TxtGlueCharIsAlpha
TxtGlueCharIsCntrl
TxtGlueCharIsDelim
TxtGlueCharIsDigit
TxtGlueCharIsGraph
TxtGlueCharIsHex
TxtGlueCharIsLower
TxtGlueCharIsPrint
TxtGlueCharIsPunct
TxtGlueCharIsSpace
TxtGlueCharIsUpper
TxtGlueCharIsValid
TxtGlueCharSize
TxtGlueCharWidth
TxtGlueCharXAttr
TxtGlueCompare
TxtGlueEncodingName
TxtGlueFindString
TxtGlueGetChar
TxtGlueGetNextChar
TxtGlueGetPreviousChar
TxtGlueGetTruncation
Offset
TxtGlueMaxEncoding
TxtGlueNextCharSize
TxtGlueParamString
TxtGluePreviousCharSize
TxtGlueReplaceStr
TxtGlueSetNextChar
TxtGlueStrEncoding
TxtGlueTransliterate
TxtGlueWordBounds
WinGlueDrawChar
WinGlueDrawTruncChars

New CtlGlueGetControlStyle

Purpose

Return the type of the control, such as button, slider, and so on.

Prototype

ControlStyleType CtlGlueGetControlStyle (const ControlType *ctlP)

Parameters

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

-> fldPA pointer to a FieldType structure.
-> lineNumThe number of the visible line in the field about which you want to retrieve information. Lines are numbered starting at 0.
<- startPThe 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.
<- lengthPThe 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

-> inFontTypeA FontDefaultType constant specifying one of the system default fonts. This value can be one of the following:
defaultSystemFontThe default font for the system.
defaultLargeFontThe default large font.
defaultSmallFontThe default small font.
defaultBoldFontThe 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

-> formPA pointer to a FormType structure.
-> objIndexThe 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

-> selectorOne of the routine selectors defined in IntlMgr.h.
-> latinSymbolThe corresponding TxtLatinfunc 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

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

-> inModifiersThe value passed in the modifiers field of the keyDownEvent.
-> inCharA 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

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

<-> ioStringThe string to be converted.
-> inMaxLengthThe 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

-> inSourcePointer to the text to be searched for. Must not be NULL.
<- outDestThe same text as in inSource but converted to a suitable format for searching. outDest must not be the same address as inSource.
-> inDstSizeThe 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

<-> ioStrAny string.
-> leadingIf true, strip the leading spaces from the string.
-> trailingIf 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

<-> ioStringPA null-terminated string. Upon return, the string is truncated if necessary so that it can be displayed in inMaxWidth pixels.
-> inMaxWidthThe 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

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

<-> ioStringThe string to be converted.
-> inMaxLengthThe 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