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 80.1 PalmOSGlue function mappings
BmpGlueGetBits Function
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
Purpose
Returns the compression type used for a specified bitmap.
Declared In
BmpGlue.h Prototype
BitmapCompressionType BmpGlueGetCompressionType( const BitmapType *bitmapP )
Parameters
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
BmpGlueGetTransparentValue Function
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( const BitmapType *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
BmpGlueGetTransparentValueisfalse,*transparentValuePis 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 Function
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, UInt32 transparentValue )
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
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
CtlGlueGetControlStyle Function
Purpose
Return the type of the control, such as button, slider, and so on.
Declared In
CtlGlue.h Prototype
ControlStyleType CtlGlueGetControlStyle( const ControlType *ctlP )
Parameters
-
→ctlP - A pointer to a
ControlTypestructure.
Returns
Returns one of the ControlStyleType constants.
Compatibility
Implemented only in the PalmOSGlue library.
CtlGlueGetFont Function
Purpose
Gets the font used when drawing a specified control's label.
Declared In
CtlGlue.h Prototype
FontID CtlGlueGetFont ( const ControlType *ctlP )
Parameters
Returns
Returns the ID of the font used to draw the control's label.
See Also
CtlGlueGetGraphics Function
Purpose
Gets the bitmaps displayed in place of a specified control's label.
Declared In
CtlGlue.h Prototype
void CtlGlueGetGraphics ( const ControlType *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
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
Purpose
Return whether or not a control is a graphical control.
Declared In
CtlGlue.h Prototype
Boolean CtlGlueIsGraphical ( ControlType *controlP )
Parameters
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
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, UInt16 ID, ControlStyleType style, DmResID thumbID, DmResID backgroundID, Coord x, Coord y, Coord width, Coord height, UInt16 minValue, UInt16 maxValue, UInt16 pageSize, UInt16 value )
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
formPPvalue may change if the object moves in memory. In subsequent calls, always use the newformPPvalue returned by this function. -
→ ID - Symbolic ID of the slider.
-
→ style - Either
sliderCtlorfeedbackSliderCtl. SeeControlStyleType. -
→ 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
NULLfor this parameter. -
→ backgroundID - Resource ID of the bitmap to display as the slider background. To use the default background bitmap, pass
NULLfor 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
Purpose
Sets the font to use when drawing the control's label.
Declared In
CtlGlue.h Prototype
void CtlGlueSetFont ( ControlType *ctlP, FontID fontID )
Parameters
-
→ ctlP - Pointer to the control object.
-
→ fontID - The ID of the font to use when drawing the control's label.
Returns
See Also
CtlGlueSetFrameStyle Function
Purpose
Set the frame style for a button control.
Declared In
CtlGlue.h Prototype
void CtlGlueSetFrameStyle ( ControlType *controlP, ButtonFrameType frameStyle )
Parameters
-
→controlP - Pointer to a button control.
-
→frameStyle - Frame style to be applied to the button. Supply one of these values (declared in the
ButtonFrameTypeenum):noButtonFrame,standardButtonFrame, orboldButtonFrame. Don't userectangleButtonFrame; rectangular button frames have been deprecated.
Returns
CtlGlueSetLeftAnchor Function
Purpose
Causes a control's left bound to be fixed or to float.
Declared In
CtlGlue.h Prototype
void CtlGlueSetLeftAnchor ( ControlType *ctlP, Boolean leftAnchor )
Parameters
-
→ ctlP - Pointer to the control.
-
→ leftAnchor - A value of
truecauses the left bound of the control to be fixed.
Returns
Comments
Used by controls that expand and shrink their width when the label is changed.
FldGlueGetLineInfo Function
Purpose
Retrieve the word-wrapping information for a visible line within a field.
Declared In
FldGlue.h Prototype
Boolean FldGlueGetLineInfo ( const FieldType *fldP, UInt16 lineNum, UInt16 *startP, UInt16 *lengthP )
Parameters
-
→fldP - A pointer to a
FieldTypestructure. -
→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'stextfield of the first character displayed by this line. If the line is blank,*startPis 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
Purpose
Return the font ID of a default font.
Declared In
FntGlue.h Prototype
FontID FntGlueGetDefaultFontID ( FontDefaultType inFontType )
Parameters
-
→inFontType - A
FontDefaultTypeconstant specifying one of the system default fonts. This value can be one of the following:
Returns
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.
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
Purpose
Return the active field for a form.
Declared In
FrmGlue.h Prototype
extern FieldType *FrmGlueGetActiveField( const FormType *formP )
Parameters
Returns
Returns a pointer to the active field. Returns NULL if there is no active form or field.
FrmGlueGetDefaultButtonID Function
Purpose
Gets the resource ID of the object on the form defined as the default button.
Declared In
FrmGlue.h Prototype
UInt16 FrmGlueGetDefaultButtonID( const FormType *formP )
Parameters
Returns
Returns the resource ID of the object defined as the default button.
See Also
FrmDoDialog(), FrmGlueSetDefaultButtonID()
FrmGlueGetHelpID Function
Purpose
Gets the resource ID number of the form's help resource.
Declared In
FrmGlue.h Prototype
UInt16 FrmGlueGetHelpID ( const FormType *formP )
Parameters
Returns
Returns the resource ID number of the form's help resource. The help resource is a String resource (type 'tSTR').
See Also
FrmGlueGetLabelFont Function
Purpose
Gets the font used for a particular label that appears on a form.
Declared In
FrmGlue.h Prototype
FontID FrmGlueGetLabelFont ( const FormType *formP, UInt16 labelID )
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
Purpose
Gets the ID number of the form's menu bar.
Declared In
FrmGlue.h Prototype
UInt16 FrmGlueGetMenuBarID ( const FormType *formP )
Parameters
Returns
Returns the ID number of the form's menu bar, or zero if the form doesn't have a menu bar.
See Also
FrmGlueGetObjIDFromObjPtr Function
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, FormObjectKind objKind )
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
FormObjectKindenum.
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
Purpose
Returns whether an object in a form has been hidden.
Declared In
FrmGlue.h Prototype
Boolean
FrmGlueGetObjectUsable ( const FormType *formP, UInt16 objIndex )
Parameters
-
→formP - A pointer to a
FormTypestructure. -
→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
Purpose
Tells the system to draw a focus ring for an object.
Declared In
FrmGlue.h Prototype
Err FrmGlueNavDrawFocusRing ( 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
RectangleTypestructure defining the bounds around which the ring should be drawn. -
→ ringStyle - One of the
FrmNavFocusRingStyleEnumvalues that represents the desired style for the ring. PassfrmNavFocusRingStyleObjectTypeDefaultif 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 -
formPorboundsInsideRingPisNULL. -
uilibErrInvalidFocusObject -
objectIDspecifies 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
Purpose
If a form has a system-drawn focus ring, gets information about the ring.
Declared In
FrmGlue.h Prototype
Err FrmGlueNavGetFocusRingInfo ( const FormType*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
UInt16that, upon exit will contain the ID of the object with the system-drawn focus ring. PassNULLfor this parameter if you don't need this information. -
← extraInfoP - Supply a pointer to a
UInt16that, upon exit will contain to any extra information associated with the focus ring; passNULLif you don't need this information. "Extra information" is any information that was associated with the ring whenFrmGlueNavDrawFocusRing()was called. If there is no extra information associated with the focus ring,*extraInfoPis set to frmNavFocusRingNoExtraInfo. -
← boundsInsideRingP - Supply a pointer to a
RectangleTypestructure into which the bounds of the system-drawn focus ring will be written. PassNULLfor this parameter if you don't need this information. -
← ringStyleP - Supply a pointer to a
FrmNavFocusRingStyleEnumvariable into which the style of the focus ring will be written. PassNULLfor 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
Purpose
Determines whether or not the device suppots one-handed navigation.
Declared In
FrmGlue.h Prototype
Boolean FrmGlueNavIsSupported ( void )
Parameters
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
Purpose
Sends a frmObjectFocusTakeEvent event for an object.
Declared In
FrmGlue.h Prototype
void FrmGlueNavObjectTakeFocus ( FormType*formP, UInt16objID)
Parameters
Returns
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
FrmGlueNavRemoveFocusRing Function
Purpose
Removes the system-drawn ring from around the currently-focused object.
Declared In
FrmGlue.h Prototype
Err FrmGlueNavRemoveFocusRing (
FormType *formP
)
Parameters
Returns
errNone if the focus ring was drawn successfully, or an error code such as one of the following otherwise:
-
uilibErrInvalidParam -
formPisNULL. -
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
Purpose
Designates the object on the form that is to act as the default button.
Declared In
FrmGlue.h Prototype
void FrmGlueSetDefaultButtonID ( FormType *formP, UInt16 defaultButton )
Parameters
-
→ formP - Pointer to the form.
-
→ defaultButton - The resource ID of the object on the form that is to be the default button.
Returns
See Also
FrmDoDialog(), FrmGlueGetDefaultButtonID()
FrmGlueSetHelpID Function
Purpose
Designates the String resource that is to act as the form's help resource.
Declared In
FrmGlue.h Prototype
void FrmGlueSetHelpID ( FormType *formP, UInt16 helpRscID )
Parameters
-
→ formP - Pointer to the form.
-
→ helpRscID - The resource ID of the String resource that is to be the form's help resource.
Returns
See Also
FrmGlueSetLabelFont Function
Purpose
Sets the font used for a particular label that appears on a form.
Declared In
FrmGlue.h Prototype
void FrmGlueSetLabelFont ( FormType *formP, UInt16 labelID, FontID fontID )
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
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
Purpose
Return the address of a Text Manager function or of its PalmOSGlue equivalent.
Declared In
IntlGlue.h Prototype
void *IntlGlueGetRoutineAddress( IntlSelector selector, const void *latinSymbol )
Parameters
-
→selector - One of the routine selectors defined in
IntlMgr.h. -
→latinSymbol - The corresponding
TxtLatin...symbol defined inIntlGlue.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
LmGlueGetSystemLocale Function
Purpose
Return the system locale and system character encoding.
Declared In
LmGlue.h Prototype
CharEncodingType LmGlueGetSystemLocale ( LmLocaleType *oSystemLocale )
Parameters
-
←oSystemLocale - Points to an
LmLocaleTypestruct 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
LstGlueGetDrawFunction Function
Purpose
Return a pointer to a list's drawing callback function.
Declared In
LstGlue.h Prototype
void *LstGlueGetDrawFunction ( ListType *listP )
Parameters
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
LstGlueGetFont Function
Purpose
Get the font used to draw a list's text strings.
Declared In
LstGlue.h Prototype
FontID LstGlueGetFont ( const ListType *listP )
Parameters
Returns
Returns the ID of the font used to draw all list text strings.
See Also
LstGlueGetItemsText Function
Purpose
Get the text strings that represent the items in a list.
Declared In
LstGlue.h Prototype
Char **LstGlueGetItemsText ( const ListType *listP )
Parameters
Returns
Returns a pointer to an array of pointers to the text of the list choices.
See Also
LstGetSelectionText(), LstSetListChoices()
LstGlueSetFont Function
Purpose
Specify the font to be used to draw a list's text strings.
Declared In
LstGlue.h Prototype
void LstGlueSetFont ( ListType *listP, FontID fontID )
Parameters
Returns
See Also
LstGlueSetIncrementalSearch Function
Purpose
Enables or disables incremental search for a sorted popup list.
Declared In
LstGlue.h Prototype
void LstGlueSetIncrementalSearch ( ListType *listP, Boolean incrementalSearch )
Parameters
-
→ listP - Pointer to the list.
-
→ incrementalSearch - Set to
trueto enable incremental search,falseto disable it.
Returns
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
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 ( UInt32 size )
Parameters
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
Purpose
Indicates if a given trap exists on the current system.
Declared In
SysGlue.h Prototype
#define SysGlueTrapExists ( trapNum )
Parameters
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
Purpose
Determines whether a particular table column is masked.
Declared In
TblGlue.h Prototype
Boolean TblGlueGetColumnMasked( const TableType *tableP, Int16 column )
Parameters
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
TblGlueGetItemPtr Function
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 ( const TableType *tableP, Int16 row, Int16 column )
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
TxtGlueConvertEncoding Function
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 ( Boolean newConversion, TxtConvertStateType *ioStateP, const Char *srcTextP, UInt16 *ioSrcBytes, CharEncodingType srcEncoding, Char *dstTextP, UInt16 *ioDstBytes, CharEncodingType dstEncoding, const Char *substitutionStr, UInt16 substitutionLen )
Parameters
-
→newConversion - Set to
trueif this function call is starting a new conversion, orfalseif this function call is a continuation of a previous conversion. -
↔ioStateP - If
newConversionisfalse, this parameter must point to aTxtConvertStateTypestructure containing the same data used for the previous invocation. IfnewConversionistrueand no subsequent calls are planned, this parameter can beNULL. -
→srcTextP - Pointer to the source text buffer. If
newConversionistrue, this must point to the start of a text buffer. IfnewConversionisfalse, 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
srcTextPthat needs to be converted. Upon return,*ioSrcBytescontains 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
NULLif you only want to know how large the destination text buffer must be (the minimum size is returned in*ioDstBytes). If notNULL,dstTextPshould point to a location whereTxtGlueConvertEncodingcan begin writing. -
→ioDstBytes - A pointer to the length, in bytes, of
dstTextP. Upon return,*ioDstBytescontains 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,TxtGlueConvertEncodingimmediately 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,
TxtConvertEncodingcopies 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:
The additional destination encodings supported for the simplified Chinese locale are:
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
srcTextPplus the number of bytes returned inioSrcBytes. - If you are skipping over an inconvertible character,
srcTextPmust 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
dstTextPplus the number of bytes returned inioDstByteseach time. -
ioDstBytes - The number of bytes available for output in the
dstTextPbuffer. 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
Table 80.3 Destination encodings for Latin ROMs version 4.0, 4.1, 5.0, 5.1, 5.2
Table 80.4 Source encodings for Shift-JIS ROMs version 4.0, 4.1, 5.0, 5.1, 5.2
Table 80.5 Destination encodings for Shift-JIS ROMs version 4.0, 4.1, 5.0, 5.1, 5.2
Table 80.6 Source encodings for GB ROMs version 5.3SC
Table 80.7 Destination encodings for GB ROMs version 5.3SC
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
Purpose
Return whether a character is a virtual character or not.
Declared In
TxtGlue.h Prototype
Boolean TxtGlueCharIsVirtual( UInt16 inModifiers, WChar inChar )
Parameters
-
→inModifiers - The value passed in the
modifiersfield of thekeyDownEvent. -
→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
Purpose
Perform a case-insensitive search for a string in another string.
Declared In
TextMgr.h Prototype
Boolean TxtGlueFindString( const Char *inSourceStr, const Char *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
strToFindfield in thesysAppLaunchCmdFindlaunch code's parameter block or it should be prepared usingTxtGluePrepFindString(). -
←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
Purpose
Return the horizontal ellipsis character.
Declared In
TxtGlue.h Prototype
WChar TxtGlueGetHorizEllipsisChar ( void )
Parameters
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
Purpose
Return the numeric space character.
Declared In
TxtGlue.h Prototype
WChar TxtGlueGetNumericSpaceChar ( void )
Parameters
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
Purpose
Convert a character to lowercase.
Declared In
TxtGlue.h Prototype
WChar TxtGlueLowerChar ( WChar inChar )
Parameters
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
Purpose
Convert a string to all lowercase letters.
Declared In
TxtGlue.h 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.
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
Purpose
Set up for TxtFindString() or FindStrInStr().
Declared In
TxtGlue.h 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
inSourcebut converted to a suitable format for searching.outDestmust not be the same address asinSource. -
→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
Purpose
Strip trailing and/or leading spaces from a string.
Declared In
TxtGlue.h 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.
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
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, UInt16 inMaxWidth )
Parameters
-
↔ioStringP - A null-terminated string. Upon return, the string is truncated if necessary so that it can be displayed in
inMaxWidthpixels. -
→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
Purpose
Convert a character to uppercase.
Declared In
TxtGlue.h Prototype
WChar TxtGlueUpperChar ( WChar inChar )
Parameters
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
Purpose
Convert a string to all uppercase letters.
Declared In
TxtGlue.h 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.
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
Purpose
Get the number of entries in the UI color table.
Declared In
UIColorGlue.h Prototype
UInt16 UIColorGlueGetNumTableEntries ( void )
Parameters
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
Purpose
Gets the frame type for a specified window.
Declared In
WinGlue.h Prototype
FrameType WinGlueGetFrameType( const WinHandle winH )
Parameters
Returns
Returns a FrameType value indicating the window's frame style.
See Also
WinGlueSetFrameType Function
Purpose
Sets the type of frame to be used for a specified window.
Declared In
WinGlue.h Prototype
void WinGlueSetFrameType ( WinHandle winH, FrameType frame )
Parameters
Returns
See Also
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.