Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

80    PalmOSGlue Library

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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

PalmOSGlue Functions ^TOP^

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 80.1  PalmOSGlue function mappings

This PalmOSGlue function...

...is identical to...

BmpGlueGetBitDepth

BmpGetBitDepth()

BmpGlueGetDimensions

BmpGetDimensions()

BmpGlueGetNextBitmap

BmpGetNextBitmap()

DateGlueTemplateToAscii

DateTemplateToAscii()

DateGlueToDOWDMFormat

DateToDOWDMFormat()

FntGlueWCharWidth

FntWCharWidth()

FntGlueWidthToOffset

FntWidthToOffset()

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

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

BmpGlueGetBits Function ^TOP^

Purpose

Retrieve the bitmap's data. Unlike BmpGetBits(), this function can be used with all versions of Palm OS.

Declared In

BmpGlue.h

Prototype

void *BmpGlueGetBits (
   BitmapType*bitmapP
)

Parameters

bitmapP
Pointer to the bitmap's structure (a BitmapType).

Returns

Returns a pointer to the bitmap's data.

BmpGlueGetCompressionType Function ^TOP^

Purpose

Returns the compression type used for a specified bitmap.

Declared In

BmpGlue.h

Prototype

BitmapCompressionType BmpGlueGetCompressionType(
   constBitmapType*bitmapP
)

Parameters

bitmapP
Pointer to the bitmap.

Returns

Returns a BitmapCompressionType enum value. If the specified bitmap is not compressed, this function returns BitmapCompressionTypeNone. If the specified bitmap's encoding version is less than 2, this function returns BitmapCompressionTypeScanLine. If bitmapP is NULL, this function generates a fatal alert.

See Also

BmpCompress()

BmpGlueGetTransparentValue Function ^TOP^

Purpose

Indicates if a specified bitmap has transparency—if, when the bitmap is drawn, pixels of a certain value won't be drawn.

Declared In

BmpGlue.h

Prototype

Boolean BmpGlueGetTransparentValue(
   constBitmapType*bitmapP,
   UInt32*transparentValueP
)

Parameters

bitmapP
Pointer to the bitmap.
transparentValueP
The pixel value that isn't drawn, if the bitmap has transparency. If the value returned by BmpGlueGetTransparentValue is false, *transparentValueP is left unchanged.

Returns

Returns true if, when drawing the specified bitmap, Palm OS doesn't draw pixels that have a value equal to that returned in transparentValueP. Returns false if all pixels are drawn.

Comments

You can specify the transparent color when you create the bitmap using Constructor.

See Also

BmpGlueSetTransparentValue()

BmpGlueSetTransparentValue Function ^TOP^

Purpose

Causes pixels of a specified color not to be drawn when the bitmap is drawn.

Declared In

BmpGlue.h

Prototype

void BmpGlueSetTransparentValue(
   BitmapType*bitmapP,
   UInt32transparentValue
)

Parameters

bitmapP
Pointer to the bitmap. Note that this must not be a resource bitmap: resource bitmaps cannot be changed.
transparentValueP
The pixel value that isn't drawn.

Returns

Returns nothing.

Comments

Does nothing if bitmapP is NULL, if bitmapP is an off-screen bitmap, or if transparentValue is invalid given the bitmap's bit depth.

If the specified bitmap's encoding version is less than 2, this function updates it to 2.

See Also

BmpGlueGetTransparentValue()

CtlGlueGetControlStyle Function ^TOP^

Purpose

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

Declared In

CtlGlue.h

Prototype

ControlStyleType CtlGlueGetControlStyle(
   constControlType*ctlP
)

Parameters

ctlP
A pointer to a ControlType structure.

Returns

Returns one of the ControlStyleType constants.

Compatibility

Implemented only in the PalmOSGlue library.

CtlGlueGetFont Function ^TOP^

Purpose

Gets the font used when drawing a specified control's label.

Declared In

CtlGlue.h

Prototype

FontID CtlGlueGetFont (
   const ControlType*ctlP
)

Parameters

ctlP
Pointer to the control object.

Returns

Returns the ID of the font used to draw the control's label.

See Also

CtlGlueSetFont()

CtlGlueGetGraphics Function ^TOP^

Purpose

Gets the bitmaps displayed in place of a specified control's label.

Declared In

CtlGlue.h

Prototype

void CtlGlueGetGraphics (
   constControlType*ctlP,
   DmResID*bitmapID,
   DmResID*selectedBitmapID
)

Parameters

ctlP
Pointer to the control.
bitmapID
Resource ID of the bitmap to display when the graphical control is not selected.
selectedBitmapID
Resource ID of the bitmap to display when the graphical control is selected, if, when selected, the graphical control should show a different bitmap.

Returns

Returns nothing.

Comments

If the specified control is not a graphical control—one that displays a bitmap in place of the text label—*bitmapID and *selectedBitmapID are set to zero.

This function works with any graphical control, including sliders.

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

CtlGlueGetFont(), CtlSetGraphics()

CtlGlueIsGraphical Function ^TOP^

Purpose

Return whether or not a control is a graphical control.

Declared In

CtlGlue.h

Prototype

Boolean CtlGlueIsGraphical (
   ControlType*controlP
)

Parameters

controlP
Pointer to the control

Returns

Returns true if the control indicated by controlP is a graphical control, a slider, or a feedback slider. Otherwise, it returns false.

CtlGlueNewSliderControl Function ^TOP^

Purpose

Create a new slider or feedback slider dynamically and install it in the specified form. The newly-created control is marked as a graphical control.

Declared In

CtlGlue.h

Prototype

SliderControlType *CtlGlueNewSliderControl(
   void**formPP,
   UInt16ID,
   ControlStyleTypestyle,
   DmResIDthumbID,
   DmResIDbackgroundID,
   Coordx,
   Coordy,
   Coordwidth,
   Coordheight,
   UInt16minValue,
   UInt16maxValue,
   UInt16pageSize,
   UInt16value
)

Parameters

formPP
Pointer to the pointer to the form in which the new control is installed. This value is not a handle; that is, the formPP value may change if the object moves in memory. In subsequent calls, always use the new formPP value returned by this function.
ID
Symbolic ID of the slider.
style
Either sliderCtl or feedbackSliderCtl. See ControlStyleType.
thumbID
Resource ID of the bitmap to display as the slider thumb. The slider thumb is the knob that the user can drag to change the slider's value. To use the default thumb bitmap, pass NULL for this parameter.
backgroundID
Resource ID of the bitmap to display as the slider background. To use the default background bitmap, pass NULL for this parameter.
x
Horizontal coordinate of the upper-left corner of the slider's boundaries, relative to the window in which it appears.
y
Vertical coordinate of the upper-left corner of the slider's boundaries, relative to the window in which it appears.
width
Width of the slider, expressed in pixels. Valid values are 1–160.
height
Height of the slider, expressed in pixels. Valid values are 1–160.
minValue
Value of the slider when its thumb is all the way to the left.
maxValue
Value of the slider when its thumb is all the way to the right.
pageSize
Amount by which to increase or decrease the slider's value when the user clicks to the right or left of the thumb.
value
The initial value to display in the slider.

Returns

Returns a pointer to the new slider control. See SliderControlType.

Compatibility

Implemented only if 3.5 New Feature Set is present.

See Also

CtlNewSliderControl(), CtlNewGraphicControl(), CtlNewControl(), CtlValidatePointer(), FrmRemoveObject()

CtlGlueSetFont Function ^TOP^

Purpose

Sets the font to use when drawing the control's label.

Declared In

CtlGlue.h

Prototype

void CtlGlueSetFont (
   ControlType*ctlP,
   FontIDfontID
)

Parameters

ctlP
Pointer to the control object.
fontID
The ID of the font to use when drawing the control's label.

Returns

Returns nothing.

See Also

CtlGlueGetFont()

CtlGlueSetFrameStyle Function ^TOP^

Purpose

Set the frame style for a button control.

Declared In

CtlGlue.h

Prototype

void CtlGlueSetFrameStyle (
   ControlType*controlP,
   ButtonFrameTypeframeStyle
)

Parameters

controlP
Pointer to a button control.
frameStyle
Frame style to be applied to the button. Supply one of these values (declared in the ButtonFrameType enum): noButtonFrame, standardButtonFrame, or boldButtonFrame. Don't use rectangleButtonFrame; rectangular button frames have been deprecated.

Returns

Returns nothing.

CtlGlueSetLeftAnchor Function ^TOP^

Purpose

Causes a control's left bound to be fixed or to float.

Declared In

CtlGlue.h

Prototype

void CtlGlueSetLeftAnchor (
   ControlType*ctlP,
   BooleanleftAnchor
)

Parameters

ctlP
Pointer to the control.
leftAnchor
A value of true causes the left bound of the control to be fixed.

Returns

Returns nothing.

Comments

Used by controls that expand and shrink their width when the label is changed.

FldGlueGetLineInfo Function ^TOP^

Purpose

Retrieve the word-wrapping information for a visible line within a field.

Declared In

FldGlue.h

Prototype

Boolean FldGlueGetLineInfo (
   constFieldType*fldP,
   UInt16lineNum,
   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, *startP 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.

Returns

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

Purpose

Return the font ID of a default font.

Declared In

FntGlue.h

Prototype

FontID FntGlueGetDefaultFontID (
    FontDefaultTypeinFontType
)

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.

Returns

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

FrmGlueGetActiveField Function ^TOP^

Purpose

Return the active field for a form.

Declared In

FrmGlue.h

Prototype

extern FieldType *FrmGlueGetActiveField(
   constFormType*formP
)

Parameters

formP
Pointer to the form, or NULL to use the active form.

Returns

Returns a pointer to the active field. Returns NULL if there is no active form or field.

FrmGlueGetDefaultButtonID Function ^TOP^

Purpose

Gets the resource ID of the object on the form defined as the default button.

Declared In

FrmGlue.h

Prototype

UInt16 FrmGlueGetDefaultButtonID(
   constFormType*formP
)

Parameters

formP
Pointer to the form.

Returns

Returns the resource ID of the object defined as the default button.

See Also

FrmDoDialog(), FrmGlueSetDefaultButtonID()

FrmGlueGetHelpID Function ^TOP^

Purpose

Gets the resource ID number of the form's help resource.

Declared In

FrmGlue.h

Prototype

UInt16 FrmGlueGetHelpID (
   constFormType*formP
)

Parameters

formP
Pointer to the form.

Returns

Returns the resource ID number of the form's help resource. The help resource is a String resource (type 'tSTR').

See Also

FrmGlueSetHelpID()

FrmGlueGetLabelFont Function ^TOP^

Purpose

Gets the font used for a particular label that appears on a form.

Declared In

FrmGlue.h

Prototype

FontID FrmGlueGetLabelFont (
   constFormType*formP,
   UInt16labelID
)

Parameters

formP
Pointer to the form.
labelID
ID of a label object in the form (the object's type must be frmLabelObj).

Returns

Returns a FontID value of 0 if either labelID is invalid or if the object indicated by labelID has a type other than frmLabelObj. Otherwise, this function returns the ID of the font used for the label.

See Also

FrmGetObjectType(), FrmGlueSetLabelFont()

FrmGlueGetMenuBarID Function ^TOP^

Purpose

Gets the ID number of the form's menu bar.

Declared In

FrmGlue.h

Prototype

UInt16 FrmGlueGetMenuBarID (
   constFormType*formP
)

Parameters

formP
Pointer to the form.

Returns

Returns the ID number of the form's menu bar, or zero if the form doesn't have a menu bar.

See Also

FrmSetMenu()

FrmGlueGetObjIDFromObjPtr Function ^TOP^

Purpose

Return the ID of a form object given only a pointer to the form object and an indication of the object's type—a pointer to the form isn't required.

Declared In

FrmGlue.h

Prototype

UInt16 FrmGlueGetObjIDFromObjPtr (
   void*formObjP,
   FormObjectKindobjKind
)

Parameters

formObjP
Pointer to a user interface object appearing on a form.
objKind
The form object's type. Supply one of the values declared in the FormObjectKind enum.

Returns

Returns the form object's ID, or frmInvalidObjectID if objKind is not a valid form object type.

See Also

FrmGetObjectId(), FrmGetObjectPtr(), FrmGetObjectType()

FrmGlueGetObjectUsable Function ^TOP^

Purpose

Returns whether an object in a form has been hidden.

Declared In

FrmGlue.h

Prototype

Boolean
FrmGlueGetObjectUsable (
   constFormType*formP,
   UInt16objIndex
)

Parameters

formP
A pointer to a FormType structure.
objIndex
The index of the object on the form.

Returns

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.

FrmGlueNavDrawFocusRing Function ^TOP^

Purpose

Tells the system to draw a focus ring for an object.

Declared In

FrmGlue.h

Prototype

ErrFrmGlueNavDrawFocusRing (
   FormType*formP,
   UInt16objectID,
   Int16extraInfo,
   RectangleType*boundsInsideRingP,
   FrmNavFocusRingStyleEnumringStyle,
   BooleanforceRestore
)

Parameters

formP
Pointer to the form containing the object whose ring is to be drawn.
objectID
ID of object getting the focus ring.
extraInfo
Any information that you want associated with the focus ring. For example, the system uses this field to store the temporarily-selected item of a focused, embedded list. Pass frmNavFocusRingNoExtraInfo if you have no information to associate with the ring.
boundsInsideRingP
Pointer to a RectangleType structure defining the bounds around which the ring should be drawn.
ringStyle
One of the FrmNavFocusRingStyleEnum values that represents the desired style for the ring. Pass frmNavFocusRingStyleObjectTypeDefault if you want the default ring style for the object's type.
forceRestore
Specifies whether, if the ring is already on the object, what is behind the ring should be restored prior to redrawing the ring.

Returns

errNone if the focus ring was drawn successfully, or an error code such as one of the following otherwise:

uilibErrInvalidParam
formP or boundsInsideRingP is NULL.
uilibErrInvalidFocusObject
objectID specifies a control that is not marked as usable.
uilibErrFormDoesNotHaveFocus
The specified form doesn't currently have the focus.
uilibErrObjectFocusModeOff
The specified form is not in object focus mode, or the device does not support one-handed navigation.

Comments

Note that if one-handed navigation is not supported, this function returns uilibErrObjectFocusModeOff. You'll probably want to call FrmGlueNavIsSupported() early on in your application, and then only call the other one-handed navigation functions if FrmGlueNavIsSupported() returned true.

See Also

FrmGlueNavGetFocusRingInfo(), FrmGlueNavObjectTakeFocus(), FrmGlueNavRemoveFocusRing(), FrmNavDrawFocusRing()

FrmGlueNavGetFocusRingInfo Function ^TOP^

Purpose

If a form has a system-drawn focus ring, gets information about the ring.

Declared In

FrmGlue.h

Prototype

ErrFrmGlueNavGetFocusRingInfo (
   constFormType*formP,
   UInt16*objectIDP,
   Int16*extraInfoP,
   RectangleType*boundsInsideRingP,
   FrmNavFocusRingStyleEnum*ringStyleP
)

Parameters

formP
Pointer to the form whose ring information is to be obtained.
objectIDP
Supply a pointer to a UInt16 that, upon exit will contain the ID of the object with the system-drawn focus ring. Pass NULL for this parameter if you don't need this information.
extraInfoP
Supply a pointer to a UInt16 that, upon exit will contain to any extra information associated with the focus ring; pass NULL if you don't need this information. "Extra information" is any information that was associated with the ring when FrmGlueNavDrawFocusRing() was called. If there is no extra information associated with the focus ring, *extraInfoP is set to frmNavFocusRingNoExtraInfo.
boundsInsideRingP
Supply a pointer to a RectangleType structure into which the bounds of the system-drawn focus ring will be written. Pass NULL for this parameter if you don't need this information.
ringStyleP
Supply a pointer to a FrmNavFocusRingStyleEnum variable into which the style of the focus ring will be written. Pass NULL for this parameter if you don't need this information.

Returns

errNone if the focus ring was drawn successfully, or an error code such as one of the following otherwise:

uilibErrFormDoesNotHaveFocus
The specified form doesn't currently have the focus.
uilibErrObjectFocusModeOff
The specified form is not in object focus mode, or the device does not support one-handed navigation.
uilibErrObjectNotFound
There is no object with a system-drawn focus ring.

Comments

For embedded lists in interaction mode, the system stores the temporarily selected item in the extra info field.

Note that if one-handed navigation is not supported, this function returns uilibErrObjectFocusModeOff. You'll probably want to call FrmGlueNavIsSupported() early on in your application, and then only call the other one-handed navigation functions if FrmGlueNavIsSupported() returned true.

See Also

FrmGlueNavDrawFocusRing(), FrmGlueNavRemoveFocusRing(), FrmNavGetFocusRingInfo()

FrmGlueNavIsSupported Function ^TOP^

Purpose

Determines whether or not the device suppots one-handed navigation.

Declared In

FrmGlue.h

Prototype

BooleanFrmGlueNavIsSupported (
   void
)

Parameters

None.

Returns

true if one-handed navigation is supported, false otherwise.

Comments

This function checks for the presence of either the one-handed functionality defined by PalmSource, or the 5-way navigation functionality defined by Handspring (palmOne). If this function returns true, the FrmGlueNav... functions will work on devices of either type.

See Also

FrmGlueNavDrawFocusRing(), FrmGlueNavGetFocusRingInfo(), FrmGlueNavObjectTakeFocus(), FrmGlueNavRemoveFocusRing()

FrmGlueNavObjectTakeFocus Function ^TOP^

Purpose

Sends a frmObjectFocusTakeEvent event for an object.

Declared In

FrmGlue.h

Prototype

voidFrmGlueNavObjectTakeFocus (
   FormType*formP,
   UInt16objID
)

Parameters

formP
Pointer to the form that contains the object.
objID
ID of the object.

Returns

Nothing.

Comments

If one-handed navigation is not supported on the device this function calls FrmSetFocus() for field and table objects and does nothing for all other objects.

Note that if one-handed navigation is not supported, this function returns uilibErrObjectFocusModeOff. You'll probably want to call FrmGlueNavIsSupported() early on in your application, and then only call the other one-handed navigation functions if FrmGlueNavIsSupported() returned true.

See Also

FrmNavObjectTakeFocus()

FrmGlueNavRemoveFocusRing Function ^TOP^

Purpose

Removes the system-drawn ring from around the currently-focused object.

Declared In

FrmGlue.h

Prototype

ErrFrmGlueNavRemoveFocusRing (
   FormType*formP
)

Parameters

formP
Pointer to the form containing the object with the focus ring.

Returns

errNone if the focus ring was drawn successfully, or an error code such as one of the following otherwise:

uilibErrInvalidParam
formP is NULL.
uilibErrFormDoesNotHaveFocus
The specified form doesn't currently have the focus.
uilibErrObjectFocusModeOff
The specified form is not in object focus mode, or the device does not support one-handed navigation.

Comments

Note that if one-handed navigation is not supported, this function returns uilibErrObjectFocusModeOff. You'll probably want to call FrmGlueNavIsSupported() early on in your application, and then only call the other one-handed navigation functions if FrmGlueNavIsSupported() returned true.

See Also

FrmGlueNavDrawFocusRing(), FrmGlueNavGetFocusRingInfo(), FrmNavRemoveFocusRing()

FrmGlueSetDefaultButtonID Function ^TOP^

Purpose

Designates the object on the form that is to act as the default button.

Declared In

FrmGlue.h

Prototype

void FrmGlueSetDefaultButtonID (
   FormType*formP,
   UInt16defaultButton
)

Parameters

formP
Pointer to the form.
defaultButton
The resource ID of the object on the form that is to be the default button.

Returns

Returns nothing.

See Also

FrmDoDialog(), FrmGlueGetDefaultButtonID()

FrmGlueSetHelpID Function ^TOP^

Purpose

Designates the String resource that is to act as the form's help resource.

Declared In

FrmGlue.h

Prototype

void FrmGlueSetHelpID (
   FormType*formP,
   UInt16helpRscID
)

Parameters

formP
Pointer to the form.
helpRscID
The resource ID of the String resource that is to be the form's help resource.

Returns

Returns nothing.

See Also

FrmGlueGetHelpID()

FrmGlueSetLabelFont Function ^TOP^

Purpose

Sets the font used for a particular label that appears on a form.

Declared In

FrmGlue.h

Prototype

void FrmGlueSetLabelFont (
   FormType*formP,
   UInt16labelID,
   FontIDfontID
)

Parameters

formP
Pointer to the form.
labelID
ID of a label object in the form (the object's type must be frmLabelObj).
fontID
ID of the font to be used for the label.

Returns

Returns nothing.

Comments

This function does nothing if either labelID is invalid or if the object indicated by labelID has a type other than frmLabelObj.

See Also

FrmGetObjectType(), FrmGlueGetLabelFont()

IntlGlueGetRoutineAddress Function ^TOP^

Purpose

Return the address of a Text Manager function or of its PalmOSGlue equivalent.

Declared In

IntlGlue.h

Prototype

void *IntlGlueGetRoutineAddress(
   IntlSelectorselector,
   constvoid*latinSymbol
)

Parameters

selector
One of the routine selectors defined in IntlMgr.h.
latinSymbol
The corresponding TxtLatin... symbol defined in IntlGlue.h.

Returns

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

LmGlueGetSystemLocale Function ^TOP^

Purpose

Return the system locale and system character encoding.

Declared In

LmGlue.h

Prototype

CharEncodingType LmGlueGetSystemLocale (
   LmLocaleType*oSystemLocale
)

Parameters

oSystemLocale
Points to an LmLocaleType struct that identifies the system locale.

Returns

Returns the system character encoding, unless oSystemLocale is null. For details on CharEncodingType, see "Character Encoding Constants."

Compatibility

Implemented only if 5.3SC New Feature Set is present.

See Also

OmGetSystemLocale()

LstGlueGetDrawFunction Function ^TOP^

Purpose

Return a pointer to a list's drawing callback function.

Declared In

LstGlue.h

Prototype

void *LstGlueGetDrawFunction (
   ListType*listP
)

Parameters

listP
Pointer to a list object.

Returns

Returns a pointer to the callback function that draws the list's items. If a callback function hasn't been set for the specified list, this function returns NULL.

See Also

LstSetDrawFunction()

LstGlueGetFont Function ^TOP^

Purpose

Get the font used to draw a list's text strings.

Declared In

LstGlue.h

Prototype

FontID LstGlueGetFont (
   constListType*listP
)

Parameters

listP
Pointer to the list.

Returns

Returns the ID of the font used to draw all list text strings.

See Also

LstGlueSetFont()

LstGlueGetItemsText Function ^TOP^

Purpose

Get the text strings that represent the items in a list.

Declared In

LstGlue.h

Prototype

Char **LstGlueGetItemsText (
   constListType*listP
)

Parameters

listP
Pointer to the list.

Returns

Returns a pointer to an array of pointers to the text of the list choices.

See Also

LstGetSelectionText(), LstSetListChoices()

LstGlueSetFont Function ^TOP^

Purpose

Specify the font to be used to draw a list's text strings.

Declared In

LstGlue.h

Prototype

void LstGlueSetFont (
   ListType*listP,
   FontIDfontID
)

Parameters

listP
Pointer to the list.
fontID
ID of the font to be used to draw all list text strings.

Returns

Returns nothing.

See Also

LstGlueGetFont()

LstGlueSetIncrementalSearch Function ^TOP^

Purpose

Enables or disables incremental search for a sorted popup list.

Declared In

LstGlue.h

Prototype

void LstGlueSetIncrementalSearch (
   ListType*listP,
   BooleanincrementalSearch
)

Parameters

listP
Pointer to the list.
incrementalSearch
Set to true to enable incremental search, false to disable it.

Returns

Returns nothing.

Comments

If incremental search is enabled, when the list is displayed the user can navigate the list by entering up to five characters. The list will scroll to present the first list item that matches the entered characters. This feature only works for popup lists, and only works if the list is sorted and the list items are available to the List Manager (that is, you don't pass NULL to LstSetListChoices).

MemGluePtrNew Function ^TOP^

Purpose

Allocate a new nonmovable chunk in the dynamic heap. Unlike MemPtrNew(), this function lets you request chunks larger than 64KB.

Declared In

MemGlue.h

Prototype

MemPtr MemGluePtrNew (
   UInt32size
)

Parameters

size
The desired size of the chunk.

Returns

Returns a pointer to the new chunk, or NULL if unsuccessful.

Comments

On versions of Palm OS prior to 3.5, this function acts exactly like MemPtrNew() and won't allocate chunks larger than 64K.

SysGlueTrapExists Macro ^TOP^

Purpose

Indicates if a given trap exists on the current system.

Declared In

SysGlue.h

Prototype

#define SysGlueTrapExists (
   trapNum
)

Parameters

trapNum
One of the system trap constants.

Returns

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.

TblGlueGetColumnMasked Function ^TOP^

Purpose

Determines whether a particular table column is masked.

Declared In

TblGlue.h

Prototype

Boolean TblGlueGetColumnMasked(
   constTableType*tableP,
   Int16column
)

Parameters

tableP
Pointer to the table.
column
Column number (zero-based).

Returns

Returns true if the column is masked, false otherwise.

Comments

If a table cell's column is masked and the cell's row is also masked, the table cell is drawn on the screen but is shaded to obscure the information that it contains.

See Also

TblSetColumnMasked()

TblGlueGetItemPtr Function ^TOP^

Purpose

Return the pointer value stored in a table item. Unlike TblGetItemPtr(), this function can be used with all versions of Palm OS.

Declared In

TblGlue.h

Prototype

void *TblGlueGetItemPtr (
   constTableType*tableP,
   Int16row,
   Int16column
)

Parameters

tableP
Pointer to a table object.
row
Row number of the item (zero-based).
column
Column number of the item (zero-based).

Returns

Returns the item's pointer value or NULL if the item does not have a pointer value.

Comments

Certain types of table items display the value pointed to by the ptr field, while other types display the value stored in the intValue field (see the TableItemType description for details). An application may set the value of the ptr field even for items that use the intValue field. This function always returns the value of the ptr field.

See Also

TblSetItemPtr()

TxtGlueConvertEncoding Function ^TOP^

Purpose

Convert a text buffer from one character encoding to another. Unlike TxtConvertEncoding(), this function will operate on many handhelds running Palm OS 3.5.

Declared In

TxtGlue.h

Prototype

Err TxtGlueConvertEncoding (
   BooleannewConversion,
   TxtConvertStateType*ioStateP,
   constChar*srcTextP,
   UInt16*ioSrcBytes,
   CharEncodingTypesrcEncoding,
   Char*dstTextP,
   UInt16*ioDstBytes,
   CharEncodingTypedstEncoding,
   const Char*substitutionStr,
   UInt16substitutionLen
)

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

TxtGlueConvertEncoding 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-41

It can also support a variety of encodings that are locale dependent. The only locale for which TxtGlueConvertEncoding supports additional encodings is simplified Chinese in those versions of Palm OS 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:

  • 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, TxtGlueConvertEncoding 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 TxtGlueConvertEncoding as described in the next paragraph.

You can make repeated calls to TxtGlueConvertEncoding 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 TxtGlueConvertEncoding() by various ROMs.

The encoding returned by the Locale Manager 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 80.2  Source encodings for Latin ROMs version 4.0, 4.1, 5.0, 5.1, 5.2

charEncodingUCS2

charEncodingUTF8

charEncodingUTF16LE

charEncodingUTF16BE

charEncodingPalmLatin

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

charEncodingUCS2

charEncodingUTF8

charEncodingUTF16LE

charEncodingUTF16BE

charEncodingPalmLatin

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

charEncodingUCS2

charEncodingUTF8

charEncodingUTF16LE

charEncodingUTF16BE

charEncodingPalmSJIS

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

charEncodingUCS2

charEncodingUTF8

charEncodingUTF16LE

charEncodingUTF16BE

charEncodingPalmSJIS

Table 80.6  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 80.7  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

This function works only on Palm OS 3.5 and later.

In versions of Palm OS that do not support simplified Chinese, the focus of TxtGlueConvertEncoding is to convert between Unicode-encoded text and the device's character encoding. For this reason, TxtGlueConvertEncoding 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 the underlying 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 TxtGlueConvertEncoding() 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.

TxtGlueCharIsVirtual Function ^TOP^

Purpose

Return whether a character is a virtual character or not.

Declared In

TxtGlue.h

Prototype

Boolean TxtGlueCharIsVirtual(
   UInt16inModifiers,
   WCharinChar
)

Parameters

inModifiers
The value passed in the modifiers field of the keyDownEvent.
inChar
A character.

Returns

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.

TxtGlueFindString Function ^TOP^

Purpose

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

Declared In

TextMgr.h

Prototype

Boolean TxtGlueFindString(
   constChar*inSourceStr,
   constChar*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 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. Unlike TxtFindString(), if the target string is not found, the values pointed to by outPos and outLength are not necessarily set to 0.

The search that TxtGlueFindString performs is locale-dependent. On most ROMs with Latin-based encodings, TxtGlueFindString returns true only if the string is at the beginning of a word. On Shift-JIS encoded ROMs, TxtGlueFindString 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 in the PalmOSGlue library.

See Also

TxtFindString(), TxtCaselessCompare()

TxtGlueGetHorizEllipsisChar Function ^TOP^

Purpose

Return the horizontal ellipsis character.

Declared In

TxtGlue.h

Prototype

WChar TxtGlueGetHorizEllipsisChar (
   void
)

Parameters

None.

Returns

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

Purpose

Return the numeric space character.

Declared In

TxtGlue.h

Prototype

WChar TxtGlueGetNumericSpaceChar (
   void
)

Parameters

None.

Returns

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

Purpose

Convert a character to lowercase.

Declared In

TxtGlue.h

Prototype

WChar TxtGlueLowerChar (
   WCharinChar
)

Parameters

inChar
A character.

Returns

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

Purpose

Convert a string to all lowercase letters.

Declared In

TxtGlue.h

Prototype

void TxtGlueLowerStr (
   Char*ioString,
   UInt16inMaxLength
)

Parameters

ioString
The string to be converted.
inMaxLength
The size of the buffer that contains the string, excluding the terminating null character.

Returns

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

Purpose

Set up for TxtFindString() or FindStrInStr().

Declared In

TxtGlue.h

Prototype

void TxtGluePrepFindString (
   constChar*inSource,
   CharPtroutDest,
   UInt16inDstSize
)

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.

Returns

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

Purpose

Strip trailing and/or leading spaces from a string.

Declared In

TxtGlue.h

Prototype

Char *TxtGlueStripSpaces (
   Char*ioStr,
   Booleanleading,
   Booleantrailing
)

Parameters

ioStr
Any string.
leading
If true, strip the leading spaces from the string.
trailing
If true, strip the trailing spaces from the string.

Returns

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.

TxtGlueTruncateString Function ^TOP^

Purpose

Determine if a string can be displayed in a given number of pixels. If not, truncate the string.

Declared In

TxtGlue.h

Prototype

Boolean TxtGlueTruncateString (
   Char*ioStringP,
   UInt16inMaxWidth
)

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.

Returns

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.


NOTE: Because this function attempts to null-terminate the supplied string, it should not be used with resources in the storage heap.

Compatibility

Implemented only in the PalmOSGlue library.

See Also

FntWidthToOffset(), WinDrawTruncChars(), TxtGetTruncationOffset()

TxtGlueUpperChar Function ^TOP^

Purpose

Convert a character to uppercase.

Declared In

TxtGlue.h

Prototype

WChar TxtGlueUpperChar (
   WCharinChar
)

Parameters

inChar
Any character.

Returns

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

Purpose

Convert a string to all uppercase letters.

Declared In

TxtGlue.h

Prototype

void TxtGlueUpperStr (
   Char*ioString,
   UInt16inMaxLength
)

Parameters

ioString
The string to be converted.
inMaxLength
The size of the buffer that contains the string, excluding the terminating null character.

Returns

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

UIColorGlueGetNumTableEntries Function ^TOP^

Purpose

Get the number of entries in the UI color table.

Declared In

UIColorGlue.h

Prototype

UInt16 UIColorGlueGetNumTableEntries (
   void
)

Parameters

None.

Returns

Returns the number of color table entries. Note that this is one greater than the maximum value that can be passed to UIColorGetTableEntryIndex(), UIColorGetTableEntryRGB(), and UIColorSetTableEntry().

WinGlueGetFrameType Function ^TOP^

Purpose

Gets the frame type for a specified window.

Declared In

WinGlue.h

Prototype

FrameType WinGlueGetFrameType(
   constWinHandlewinH
)

Parameters

winH
The window's handle.

Returns

Returns a FrameType value indicating the window's frame style.

See Also

WinGlueSetFrameType()

WinGlueSetFrameType Function ^TOP^

Purpose

Sets the type of frame to be used for a specified window.

Declared In

WinGlue.h

Prototype

void WinGlueSetFrameType (
   WinHandlewinH,
   FrameTypeframe
)

Parameters

winH
The window's handle.
frame
The style of frame to be used.

Returns

Returns nothing.

See Also

WinGlueGetFrameType()


1. UTF-32, UTF-32BE, UTF-32LE, and UCS-4 are only built into handhelds running a version of Palm OS that supports simplified Chinese.