API Guide Home (Online version only) |

# HsExt.h File Reference

## Detailed Description

Header file that 68K programs include to access Handspring Extensions functionality.

Definition in file HsExt.h.

Include dependency graph for HsExt.h:

Go to the source code of this file.

## Defines

- #define SYS_SEL_TRAP(trapNum, selector)
- #define HsAboutHandspringAppWithYearId(yearId)
- #define HsAboutHandspringAppWithYearCredId(yearId, creditsId)

## Functions

- void HsAboutHandspringApp (UInt16 appCardNo, LocalID appDbId, Char *copyrightYearStrP, Char *extraCreditsStrP)
    Parameters:

      | appCardNo,: | IN:

- Err HsGetVersionString (UInt16 selector, Char *outStrP, UInt16 *sizeP)
    Retrieve a null terminated version string.
- Err HsAttrGet (UInt16 attr, UInt32 param, UInt32 *valueP)
    Get any Handspring specific attributes that aren’t appropriate to be accessed through a feature. (e.g., dynamic information about device state).
- Err HsAttrSet (UInt16 attr, UInt32 param, UInt32 *valueP)
    Set Handspring specific attributes.
- Err HsPrefGet (UInt16 pref, void *bufP, UInt32 *prefSizeP)
    HsExtensions maintains and utilizes a set of preferences that are not a part of the Palm OS system preferences. They can be retrieved using this function.
- Err HsPrefSet (UInt16 pref, void *bufP, UInt32 prefSize)
    HsExtensions maintains and utilizes a set of preferences that are not a part of the Palm OS system preferences. They can be set using this function.
- Err HsGetPhoneLibrary (UInt16 *refNum)
    Function that gets the reference number to the phone library. It decides whether it should return the GSM or the CDMA library based on the type of device. If the library is not loaded, it loads the library.
- Err HsStatusSetGadgetType (void *frmP, UInt16 gadgetID, UInt16 type)
    Tell the system that a gadget on the form is a certain type of status gadget so that the system can properly draw and update it.
- void HsStatusUpdateGadgets (void)
    Explicitly update all status gadgets on the current form.
- Err HsGrfSetStateExt (Boolean capsLock, Boolean numLock, Boolean optLock, Boolean upperShift, Boolean optShift, Boolean autoShift)
    Extended version of GrfSetState to allow setting an option and option lock state.
- Err HsGrfGetStateExt (Boolean *capsLockP, Boolean *numLockP, Boolean *optLockP, UInt16 *tempShiftP, Boolean *autoShiftedP)
    Extended version of GrfGetState to include detection of option and option lock state.
- Boolean HsPutObjectAfterTitle (void *voidFrmP, UInt16 objID, UInt8 titleOffset)
    Places a UI object to the right of the form title. This function is useful for adjusting object positions for localized titles.
- UInt32 HsInfo (UInt16 item, UInt16 paramSize, void *paramP)
    This call will return info on a particular attribute of the Handspring extensions.
- UInt16 HsEvtMetaEvent (EventPtr eventP)
    Parameters:

      | eventP,: | IN:

- Err HsSpringboardNotSupported (void)
    Used to determine if the device supports the Springboard expansion slot or not.
- void * HsGetTrapAddress (UInt16 trapNum)
    Works like SysGetTrapAddress, but for Handspring trap numbers.
- Err HsNetworkDropConnection (void)
    This function will completely close the currently active TCP/IP network connection. The open count will be 0 after this call is made.
- void HsUnimplemented (void)
- void * HsGetARMActiveFormPtr (void)
- FontID HsTwoFontSelect (FontID originalFont)
    Allows the user to select a small or a large font size.
- void HsOpenDialNumberDialog (char *numberP, char *nameP, Boolean callerID)
    Opens a window with the number filled in the address text field.
- Err HsTurnRadioOn (void)
    Turn the radio (cell phone) on if it’s off.
- Err HsCreateNewMessage (char *addressP, char *nameP, char *msgP)
    Launches the messaging application (SMS) to the new message form with some fields optionally prefilled with the specified values.
- Err HsCreateNewEmail (char *addressP, char *ccP, char *subjectP, char *msgP)
    Launches the email application to the new email form with some fields optionally prefilled with the specified values.
- Err HsBrowseUrl (char *urlP)
    Launches the browser to the specified URL.
- Err HsNavGetFocusRingInfo (const FormType *formP, UInt16 *objectIDP, Int16 *extraInfoP, RectangleType *boundsInsideRingP, HsNavFocusRingStyleEnum *ringStyleP)
    If a form has a system drawn focus ring, gets info about the ring.
- Err HsNavDrawFocusRing (FormType *formP, UInt16 objectID, Int16 extraInfo, RectangleType *boundsInsideRingP, HsNavFocusRingStyleEnum ringStyle, Boolean forceRestore)
    Tells the system to draw a focus ring for an object.
- Err HsNavRemoveFocusRing (FormType *formP)
    Removes system-drawn ring from around currently focused object.
- void HsNavObjectTakeFocus (const FormType *formP, UInt16 objID)
    Sends a frmObjectFocusTake event for an object.
- void HsNavGetFocusColor (HsNavFocusColorEnum color, RGBColorType *rgbColorP)
    Obtains a focus color.
- void HsNavSetFocusColor (HsNavFocusColorEnum color, RGBColorType *rgbColorP, RGBColorType *oldRgbColorP)
    Sets new focus color.
- Err HsIndicatorState (UInt16 count, UInt16 indicatorType, UInt16 *stateP)
    Set or get the state of the LED or Vibrator.
- Err HsLightMode (Boolean set, UInt16 *modeP)
    Get or set the current mode.
- Err HsLightCircumstance (Boolean add, UInt16 circumstance)
    Add/remove special lighting circumstances.
- UInt16 HsCurrentLightCircumstance (void)
- void HsKeyCurrentStateExt (UInt32 keys[3])
    Converts HsKeysPressed() results into a bitfield.
- void HsKeySetMaskExt (const UInt32 keyMaskNew[3], UInt32 keyMaskOld[3])
    Glue to HsKeyEnabled() based on bitfields.
- UInt16 HsKeysPressed (UInt16 count, const UInt16 keyCodes[], Boolean pressed[])
    Get the current state of specified keys.
- Err HsKeyStop (UInt16 keyCode)
    Stop a key from sending any more autorepeat events until it is released.
- Boolean HsKeyEnableKey (UInt16 keyCode, Boolean enabled)
    Enable/disable a key from generating key events.
- UInt16 HsKeyChrCodeToKeyCode (UInt16 chrCode)
    Determine which key generates a certain character.
- void HsKeyKeyCodeToChrCode (UInt16 keyCode, UInt16 modifiersIn, UInt16 *chrP, UInt16 *modifiersOutP)
    Translate a key code to the character generated by that key.
- Boolean HsKeyEventIsFromKeyboard (EventPtr eventP)
    Determine if an event came from the physical keyboard.
- Boolean HsExtDoSaveAsDialog (Char *name)
    Displays a dialog to the user allowing them to confirm the saving of data, and the name that they wish to assign.
- UInt16 HsTxtPrepFindString (const Char *inSrcP, UInt16 inSrcLen, Char *outDstP, UInt16 inDstSize)
    Parameters:

      | inSrcP,: | IN:

- UInt32 HsTxtNumChars (Char const *textP)
    Parameters:

      | textP,: | IN:

- void HsTxtTruncateString (Char *textP, UInt16 maxPixels, Boolean keepLabel)
    Parameters:

      | textP,: | IN:

- Boolean HsTxtIsAscii (Char *textP, UInt16 textLen)
    Parameters:

      | textP,: | IN:

- Boolean HsIsHTTPLibraryLoaded (void)
    Return values:

      | Boolean |

- Int16 HsNavLstGetTempSelection (const FormType *formP, UInt16 listID)
    Obtains the temporarily selected item of an embedded list.
- void HsNavLstSetTempSelection (const FormType *formP, UInt16 listID, Int16 itemNum)
    Sets the temporarily selected item for an embedded list.
- void HsStartMemoryTracing (Boolean trace)
    Starts and stops memory tracing.

## Define Documentation

#define HsAboutHandspringAppWithYearCredId | ( | yearId,
|  | creditsId |  | ) |

Value:

    do                                                                      \
          {                                                                     \
            UInt16  appCardNo;                                                  \
            LocalID appDbId;                                                    \
            MemHandle   yearStrH, extraStrH;                                    \
            Char*   yearStrP;                                                   \
            Char*   extraStrP;                                                  \
                                                                                \
            yearStrH = DmGetResource (strRsc, yearId);                          \
            yearStrP = MemHandleLock (yearStrH);                                \
            extraStrH = DmGetResource (strRsc, creditsId);                      \
            extraStrP = MemHandleLock (extraStrH);                              \
            SysCurAppDatabase(&appCardNo, &appDbId);                            \
            HsAboutHandspringApp (appCardNo, appDbId, yearStrP, extraStrP);     \
            MemPtrUnlock (extraStrP);                                           \
            DmReleaseResource (extraStrH);                                      \
            MemPtrUnlock (yearStrP);                                            \
            DmReleaseResource (yearStrH);                                       \
          }                                                                     \
        while (0)

Definition at line 97 of file HsExt.h.

#define HsAboutHandspringAppWithYearId | ( | yearId |  | ) |

Value:

    do                                                                      \
          {                                                                     \
            UInt16  appCardNo;                                                  \
            LocalID appDbId;                                                    \
            MemHandle   yearStrH;                                               \
            Char*   yearStrP;                                                   \
                                                                                \
            yearStrH = DmGetResource (strRsc, yearId);                          \
            yearStrP = MemHandleLock (yearStrH);                                \
            SysCurAppDatabase(&appCardNo, &appDbId);                            \
            HsAboutHandspringApp (appCardNo, appDbId, yearStrP, NULL);          \
            MemPtrUnlock (yearStrP);                                            \
            DmReleaseResource (yearStrH);                                       \
          }                                                                     \
        while (0)

Definition at line 80 of file HsExt.h.

#define SYS_SEL_TRAP | ( | trapNum,
|  | selector |  | ) |

Definition at line 60 of file HsExt.h.

## Function Documentation

void HsAboutHandspringApp | ( | UInt16 | appCardNo,
|  | LocalID | appDbId,
|  | Char * | copyrightYearStrP,
|  | Char * | extraCreditsStrP |
| ) |  |  |

Parameters:

  | appCardNo,: | IN:

Parameters:

  | appDbId,: | IN:
  | copyrightYearStrP,: | IN:
  | extraCreditsStrP,: | IN:

Return values:

  | Error | code.

Err HsAttrGet | ( | UInt16 | attr,
|  | UInt32 | param,
|  | UInt32 * | valueP |
| ) |  |  |

Get any Handspring specific attributes that aren’t appropriate to be accessed through a feature. (e.g., dynamic information about device state).

See also:
  HsAttrEnum

Parameters:

  | attr,: | IN: Which attribute is being retrieved. Most attributes are defined in “HsExtCommon.h” in the HsAttrEnum enumeration.
  | param,: | IN: Meaning depends on ’attr’ (currently implemented attributes only take 0 for this argument).
  | valueP,: | IN: Cast depending on attr (refer HsAttrEnum for data type this argument should point to).

Return values:

  | Err | 0 if no error

Err HsAttrSet | ( | UInt16 | attr,
|  | UInt32 | param,
|  | UInt32 * | valueP |
| ) |  |  |

Set Handspring specific attributes.

See also:
  HsAttrEnum

Parameters:

  | attr,: | IN: Which attribute is being set.
  | param,: | IN: Meaning depends on ’attr’ (currently implemented attributes only take 0 for this argument).
  | valueP,: | IN: Cast depending on attr (refer HsAttrEnum for data type this argument should point to).

Return values:

  | Err | 0 if no error hsErrNotSupported otherwise.

Err HsBrowseUrl | ( | char * | urlP | ) |

Launches the browser to the specified URL.

This function can be used by any application that wants to launch the web browser to a specified URL without using the helper APIs.

Parameters:

  | urlP,: | IN: A pointer to a string that contains the phone number to put into the number field.

Return values:

  | Err | 0 on success or the error that occurred.

Err HsCreateNewEmail | ( | char * | addressP,
|  | char * | ccP,
|  | char * | subjectP,
|  | char * | msgP |
| ) |  |  |

Launches the email application to the new email form with some fields optionally prefilled with the specified values.

This function can be used by any application that wants to launch the email application and have some of the fields prefilled without using the helper APIs.

Parameters:

  | addressP,: | IN: A pointer to a string that contains the address to put in the To: field.
  | ccP,: | IN: A pointer to a string that contains the address to put in the cc: field. (optional)
  | subjectP,: | IN: A pointer to a string that contains the subject of the new email. (optional)
  | msgP,: | IN: A pointer to a string that contains the message text of the new email. (optional)

Return values:

  | Err | 0 on success or the error that occurred.

Err HsCreateNewMessage | ( | char * | addressP,
|  | char * | nameP,
|  | char * | msgP |
| ) |  |  |

Launches the messaging application (SMS) to the new message form with some fields optionally prefilled with the specified values.

This function can be used by any application that wants to launch the messaging application and have some of the fields prefilled without using the helper APIs.

Parameters:

  | addressP,: | IN: A pointer to a string that contains the phone number to put into the To: field. (optional)
  | nameP,: | IN: A pointer to a string that contains the name to put above the To: field. (optional)
  | msgP,: | IN: A pointer to a string that contains the message text of the new message. (optional)

Return values:

  | Err | 0 on success or the error that occurred.

UInt16 HsCurrentLightCircumstance | ( | void |  | ) |

UInt16 HsEvtMetaEvent | ( | EventPtr | eventP | ) |

Parameters:

  | eventP,: | IN:

Return values:

  | UInt16 | Error code.

Boolean HsExtDoSaveAsDialog | ( | Char * | name | ) |

Displays a dialog to the user allowing them to confirm the saving of data, and the name that they wish to assign.

Parameters:

  | name,: | IN: Comes in as the default name and returns the name the user chose

Return values:

  | Boolean | True if the user confirmed that the save should take place. False otherwise.

void* HsGetARMActiveFormPtr | ( | void |  | ) |

Err HsGetPhoneLibrary | ( | UInt16 * | refNum | ) |

Function that gets the reference number to the phone library. It decides whether it should return the GSM or the CDMA library based on the type of device. If the library is not loaded, it loads the library.

Parameters:

  | refNum,: | IN: Library reference number to be used in other function.

Return values:

  | Err | 0 if no error.

void* HsGetTrapAddress | ( | UInt16 | trapNum | ) |

Works like SysGetTrapAddress, but for Handspring trap numbers.

For every HsExt function implemented in ARM native, there exists a wrapper 68K function that simply calls the HsExt function in question. This may seem roundabout, but HsGetTrapAddress is retained for backward compatibility.

Parameters:

  | trapNum,: | IN: the address of the trap handler for the given selector.

Return values:

  | void* | If the selector is invalid, returns the address of HsUnimplemented().

Err HsGetVersionString | ( | UInt16 | selector,
|  | Char * | outStrP,
|  | UInt16 * | sizeP |
| ) |  |  |

Retrieve a null terminated version string.

Parameters:

  | selector,: | IN: Selects which version string to get
  | outStrP,: | IN: Buffer to receive the NULL terminated version string. The buffer should be large enough to hold hsVersionStringSize bytes
  | sizeP,: | IN: If not NULL, returns the number of bytes stored in *outStrP, including the NULL terminator

Return values:

  | 0 | if no error, hsErrNotSupported if error occurs

Err HsGrfGetStateExt | ( | Boolean * | capsLockP,
|  | Boolean * | numLockP,
|  | Boolean * | optLockP,
|  | UInt16 * | tempShiftP,
|  | Boolean * | autoShiftedP |
| ) |  |  |

Extended version of GrfGetState to include detection of option and option lock state.

Parameters:

  | capsLockP,: | IN: returns true if caps lock on
  | numLockP,: | IN: returns true if num lock on
  | optLockP,: | IN: returns true if opt lock on
  | tempShiftP,: | IN: returns current temporary shift
  | autoShiftedP,: | IN: returns TRUE if shift not set by the user but by the system, for example, at the beginning of a line.

Return values:

  | Err | Always returns 0.

Err HsGrfSetStateExt | ( | Boolean | capsLock,
|  | Boolean | numLock,
|  | Boolean | optLock,
|  | Boolean | upperShift,
|  | Boolean | optShift,
|  | Boolean | autoShift |
| ) |  |  |

Extended version of GrfSetState to allow setting an option and option lock state.

The original GrfSetState does not have an autoShift parameter because it always assumed that anyone setting the shift state through the API call wanted an automatic shift. We do not make this assumption. The shift state can be set by calling either HsGrfSetStateExt() or GrfSetState(). Either way, we have to make sure that both the keyboard shift state and the Graffiti engine’s shift state get set correctly.

Parameters:

  | capsLock,: | IN: Set to turn caps lock on
  | numLock,: | IN: Set to true to turn num lock on
  | optLock,: | IN: Set to true to turn option lock on
  | upperShift,: | IN: Set to true to put into upper shift
  | optShift,: | IN: Set to true to put into option shift
  | autoShift,: | IN: Valid only if upperShift is true. Set to true if the graffiti engine should consider the upper shift an auto shift.

Return values:

  | Err | Always returns 0.

Err HsIndicatorState | ( | UInt16 | count,
|  | UInt16 | indicatorType,
|  | UInt16 * | stateP |
| ) |  |  |

Set or get the state of the LED or Vibrator.

Parameters:

  | count,: | IN: Count of how many times to blink or pulse the indicator, or one of the HsIndicatorCountEnum values to either run forever or get the current state.
  | indicatorType,: | IN: HsIndicatorTypeEnum (LED or vibrator)
  | stateP,: | IN: Pointer to HsIndicatorStateEnum If setting, points to state to set. If getting, as IN param points to “none” state of the source to query (or kIndicatorStateNull to query whatever source has priority). As OUT param, contains the result of the query (kIndicatorStateNull if querying for the active source and there is none)

Return values:

  | Err | 0 if no error

UInt32 HsInfo | ( | UInt16 | item,
|  | UInt16 | paramSize,
|  | void * | paramP |
| ) |  |  |

This call will return info on a particular attribute of the Handspring extensions.

This call is designed to return info that won’t fit into a Palm OS feature call (a UInt32).

Parameters:

  | item,: | IN: which info to return
  | paramSize,: | IN: size of paramP block passed in
  | paramP,: | IN: info is returned here

Return values:

  | UInt32 | 0 if no error

Boolean HsIsHTTPLibraryLoaded | ( | void |  | ) |

Return values:

  | Boolean |

UInt16 HsKeyChrCodeToKeyCode | ( | UInt16 | chrCode | ) |

Determine which key generates a certain character.

Parameters:

  | chrCode,: | IN: the character to search for

Return values:

  | UInt16 | The key code.

void HsKeyCurrentStateExt | ( | UInt32 | keys[3] | ) |

Converts HsKeysPressed() results into a bitfield.

This function provides compatibility with earlier Handspring SDKs. The preferred method of querying key states is to call HsKeysPressed().

Parameters:

  | keys,: | IN: Array of three bitfields representing which keys are depressed.

Boolean HsKeyEnableKey | ( | UInt16 | keyCode,
|  | Boolean | enabled |
| ) |  |  |

Enable/disable a key from generating key events.

Parameters:

  | keyCode,: | IN: which key to enable/disable
  | enabled,: | IN: true to enable, false to disable

Return values:

  | Boolean | true if previously enabled.

Boolean HsKeyEventIsFromKeyboard | ( | EventPtr | eventP | ) |

Determine if an event came from the physical keyboard.

Parameters:

  | eventP,: | IN: The event to check

Return values:

  | Boolean | True if the event came from the keyboard

void HsKeyKeyCodeToChrCode | ( | UInt16 | keyCode,
|  | UInt16 | modifiersIn,
|  | UInt16 * | chrP,
|  | UInt16 * | modifiersOutP |
| ) |  |  |

Translate a key code to the character generated by that key.

Parameters:

  | keyCode,: | IN: The key to lookup
  | modifiersIn,: | IN: Modifier mask indicating which character should be returned
  | chrP,: | IN: The character produced by the key
  | modifiersOutP,: | IN: The keyMask bits that must be set if a keyDown event is formed with the character. (Not including the bits set in modifiersIn)

void HsKeySetMaskExt | ( | const UInt32 | keyMaskNew[3],
|  | UInt32 | keyMaskOld[3] |
| ) |  |  |

Glue to HsKeyEnabled() based on bitfields.

This function provides compatibility with earlier Handspring SDKs. The preferred method of enabling keys is to call HsKeyEnableKey().

Parameters:

  | keyMaskNew,: | IN: new enabled mask
  | keyMaskOld,: | IN: previous enabled mask

UInt16 HsKeysPressed | ( | UInt16 | count,
|  | const UInt16 | keyCodes[],
|  | Boolean | pressed[] |
| ) |  |  |

Get the current state of specified keys.

This extends KeyCurrentState().

Parameters:

  | count,: | IN: number of elements in keyCodes[] and pressed[]
  | keyCodes[],: | IN: Array of keyCodes to test
  | pressed[],: | IN: Each element is set to true if the key specified by the corresponding element in keyCodes[] is pressed, and set to false if it’s not pressed. It is acceptable to pass NULL if only the return value is of interest.

Return values:

  | UInt16 | Count of keys in keyCodes[] that are pressed

Err HsKeyStop | ( | UInt16 | keyCode | ) |

Stop a key from sending any more autorepeat events until it is released.

Parameters:

  | keyCode,: | IN: key to stop

Return values:

  | Err | errNone if the keyCode is the last key pressed and it’s still held.

Err HsLightCircumstance | ( | Boolean | add,
|  | UInt16 | circumstance |
| ) |  |  |

Add/remove special lighting circumstances.

This function does reference counting on added circumstances, so be sure to not add a circumstance without eventually removing it (unless you intended that). Note that some circumstances don’t take effect until some point in time later (in SysHandleEvent). That’s because some circumstances only take effect when the device is idle for some amount of time.

Parameters:

  | add,: | IN: If true, we’re adding a circumstance, If false, we’re removing it.
  | circumstance,: | IN: The circumstance we’re adding or taking away (refer HsLightCircumstanceEnum).

Return values:

  | Err | An error code; 0 if no error

Err HsLightMode | ( | Boolean | set,
|  | UInt16 * | modeP |
| ) |  |  |

Get or set the current mode.

Parameters:

  | set,: | IN: If true, we’ll switch to *modeP; if false we’ll put the current mode in *modeP
  | modeP,: | IN: If we’re setting, we’ll switch to this mode (refer HsLightModeEnum). If we’re getting, we’ll put the current mode here.

Return values:

  | Err | An error code; 0 if no error.

Err HsNavDrawFocusRing | ( | FormType * | formP,
|  | UInt16 | objectID,
|  | Int16 | extraInfo,
|  | RectangleType * | boundsInsideRingP,
|  | HsNavFocusRingStyleEnum | ringStyle,
|  | Boolean | forceRestore |
| ) |  |  |

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

Parameters:

  | formP,: | IN: Form containing object whose ring is being drawn
  | objectID,: | IN: ID of object getting the focus ring
  | extraInfo,: | IN: Any info that caller wants associated with the focus ring. For example, the system uses this field to store the temporarily-selected item of a focused, embedded list. Caller should pass hsNavFocusRingNoExtraInfo (0xFFFF) if there is no associated info.
  | boundsInsideRingP,: | IN: Points to the bounds around which the ring should be drawn
  | ringStyle,: | IN: Enumeration value that represents the desired style for the ring. hsNavFocusRingStyleObjectTypeDefault can be passed if caller just wants the default ring style for the object’s type.
  | forceRestore,: | IN: If ring is already on the object, whether to force restoration of what’s behind the ring before redrawing the ring.

Return values:

  | Err | Returns errNone if no error, error code otherwise.

void HsNavGetFocusColor | ( | HsNavFocusColorEnum | color,
|  | RGBColorType * | rgbColorP |
| ) |  |  |

Obtains a focus color.

Parameters:

  | color,: | IN: Enumeration value that specifies which focus color to get
  | rgbColorP,: | IN: On exit, points to the focus color

Err HsNavGetFocusRingInfo | ( | const FormType * | formP,
|  | UInt16 * | objectIDP,
|  | Int16 * | extraInfoP,
|  | RectangleType * | boundsInsideRingP,
|  | HsNavFocusRingStyleEnum * | ringStyleP |
| ) |  |  |

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

Parameters:

  | formP,: | IN: Ptr to form whose ring info is to be obtained
  | objectIDP,: | IN: If not NULL, on exit will point to the object with the system-drawn focus ring
  | extraInfoP,: | IN: If not NULL, on exit will point to any extra info associated with the focus ring. Extra info is any info that the caller wants to associate with a ring. hsNavFocusRingNoExtraInfo (0xFFFF) is used to represent no extra info.
  | boundsInsideRingP,: | IN: If not NULL, on exit will point to the bounds inside the system-drawn focus ring
  | ringStyleP,: | IN: If not NULL, on exit will point to the style of the focus ring

Return values:

  | Err | Error code.

Int16 HsNavLstGetTempSelection | ( | const FormType * | formP,
|  | UInt16 | listID |
| ) |  |  |

Obtains the temporarily selected item of an embedded list.

Parameters:

  | formP,: | IN: Pointer to the form containing the list whose temporary selection is to be obtained
  | listID,: | IN: ID of list whose temporary selection is to be obtained

Return values:

  | Int16 | Returns the temporarily selected list item

void HsNavLstSetTempSelection | ( | const FormType * | formP,
|  | UInt16 | listID,
|  | Int16 | itemNum |
| ) |  |  |

Sets the temporarily selected item for an embedded list.

Parameters:

  | formP,: | IN: Pointer to the form containing the list whose temporary selection is to be set
  | listID,: | IN: ID of list whose temporary selection is to be set
  | itemNum,: | IN: Number of the item that should be temporarily selected

void HsNavObjectTakeFocus | ( | const FormType * | formP,
|  | UInt16 | objID |
| ) |  |  |

Sends a frmObjectFocusTake event for an object.

Parameters:

  | formP,: | IN: Ptr to form that contains the object
  | objID,: | IN: ID of the object

Err HsNavRemoveFocusRing | ( | FormType * | formP | ) |

Removes system-drawn ring from around currently focused object.

Parameters:

  | formP,: | IN: Ptr to form containing the object with the ring

Return values:

  | Err | Returns errNone if no error, error code otherwise

void HsNavSetFocusColor | ( | HsNavFocusColorEnum | color,
|  | RGBColorType * | rgbColorP,
|  | RGBColorType * | oldRgbColorP |
| ) |  |  |

Sets new focus color.

Parameters:

  | color,: | IN: Enumeration value that specifies which focus color to set
  | rgbColorP,: | IN: Points to the new color
  | oldRgbColorP,: | IN: If not NULL, on exit it will point to the old focus color

Err HsNetworkDropConnection | ( | void |  | ) |

This function will completely close the currently active TCP/IP network connection. The open count will be 0 after this call is made.

Return values:

  | Err | 0 if successful.

void HsOpenDialNumberDialog | ( | char * | numberP,
|  | char * | nameP,
|  | Boolean | callerID |
| ) |  |  |

Opens a window with the number filled in the address text field.

This function can be used by any application that wants to dial a phone number, but first give the user the option of editing the number. This functionality originally existed in the STE, but was moved to the system.

Parameters:

  | numberP,: | IN: A pointer to a string that contains the phone number to put into the number field.
  | nameP,: | IN: A pointer to a string that contains the name to put into the title of the dialog.
  | callerID,: | IN: If this is true, then we will attempt to match the phone number with an entry in the address book. If a match is found, then the title of the dialog will contain the name.

Err HsPrefGet | ( | UInt16 | pref,
|  | void * | bufP,
|  | UInt32 * | prefSizeP |
| ) |  |  |

HsExtensions maintains and utilizes a set of preferences that are not a part of the Palm OS system preferences. They can be retrieved using this function.

See also:
  HsPrefEnum

Parameters:

  | pref,: | IN: IN which preference to retrieve (refer HsPrefEnum)
  | bufP,: | IN: IN buffer to store preference (refer HsPrefEnum for the size of the buffer needed).
  | prefSizeP,: | IN: IN/OUT on entry, size of bufP on exit, size of stored pref. If larger than size of bufP, then hsErrBufferTooSmall is returned.

Return values:

  | Err | 0 if no err hsErrInvalidParam if pref is invalid hsErrBufferTooSmall if *prefSizeP was smaller than actual pref

Err HsPrefSet | ( | UInt16 | pref,
|  | void * | bufP,
|  | UInt32 | prefSize |
| ) |  |  |

HsExtensions maintains and utilizes a set of preferences that are not a part of the Palm OS system preferences. They can be set using this function.

See also:
  HsPrefEnum

Parameters:

  | pref,: | IN: which pref to retrieve, a HsPrefEnum
  | bufP,: | IN: buffer to store pref
  | prefSize,: | IN: size of pref to store

Return values:

  | Err | 0 if no err hsErrInvalidParam if pref is invalid

Boolean HsPutObjectAfterTitle | ( | void * | voidFrmP,
|  | UInt16 | objID,
|  | UInt8 | titleOffset |
| ) |  |  |

Places a UI object to the right of the form title. This function is useful for adjusting object positions for localized titles.

Parameters:

  | voidFrmP,: | IN: ptr to form containing the object
  | objID,: | IN: id of the object being positioned
  | titleOffset,: | IN: number of pixels between title bar and status gadget

Return values:

  | Boolean | True if the object was moved from it’s original position. False otherwise

Err HsSpringboardNotSupported | ( | void |  | ) |

Used to determine if the device supports the Springboard expansion slot or not.

On springboard devices, this function is unimplemented. To determine whether the device has a Springboard extension slot or not, use HsGetTrapAddress() to obtain the trap addresses of this function and HsUnimplemented. If they are equal, the device has the Springboard extension slot, otherwise it doesn’t.

Return values:

  | Err | All of the Springboard functions return an error on the Treo 600.

void HsStartMemoryTracing | ( | Boolean | trace | ) |

Starts and stops memory tracing.

Parameters:

  | tarce,: | IN: should tracing be started or stopped if true tracing will be started.

called from the 68K controling (test) app.

Err HsStatusSetGadgetType | ( | void * | frmP,
|  | UInt16 | gadgetID,
|  | UInt16 | type |
| ) |  |  |

Tell the system that a gadget on the form is a certain type of status gadget so that the system can properly draw and update it.

Tell the system that a gadget on the form is a certain type of status gadget so that the system can properly draw and update it. A form can only have one gadget for each status type. If more than one gadget is set to a certain type, only the last one set will be recorded. This function can also be used to erase and release a gadget whose type has already been set. To do this, type should be set to 0.

NOTE The gadget dimensions in the current implementation are hardcoded to values of 10 X 12 pixels for the battery gadget and 16 X 12 pixels for signal gadget. Scaling is not supported, so define your gadget resources accordingly.

Parameters:

  | frmP,: | IN: pointer to the form with the gadget (we will convert to an ID before saving but want a ptr to be passed as a param to ensure that the caller is setting the gadget for a loaded form)
  | gadgetID,: | IN: id of the gadget whose type is being specified
  | type,: | IN: type of the gadget (pass a member of HsStatusGadgetTypeEnum—defined in HsExt.h or 0 to erase and release a gadget)

Return values:

  | Err | 0 if no error.

void HsStatusUpdateGadgets | ( | void |  | ) |

Explicitly update all status gadgets on the current form.

Err HsTurnRadioOn | ( | void |  | ) |

Turn the radio (cell phone) on if it’s off.

Return values:

  | Err | 0 if successful.

FontID HsTwoFontSelect | ( | FontID | originalFont | ) |

Allows the user to select a small or a large font size.

This is just like the Palm OS routine FontSelect, except it gives the user a choice of only a small and a large font. If the originalFont is not bold, then the two choices are stdFont and largeFont. If the original choice is bold, then the two choices are boldFont and largeBoldFont.

Parameters:

  | originalFont,: | IN: The original font ID (used to select the current font).

Return values:

  | FontID | The new font ID.

Boolean HsTxtIsAscii | ( | Char * | textP,
|  | UInt16 | textLen |
| ) |  |  |

Parameters:

  | textP,: | IN:

Parameters:

  | textLen,: | IN:

Return values:

  | Boolean |

UInt32 HsTxtNumChars | ( | Char const * | textP | ) |

Parameters:

  | textP,: | IN:

Return values:

  | UInt32 |

UInt16 HsTxtPrepFindString | ( | const Char * | inSrcP,
|  | UInt16 | inSrcLen,
|  | Char * | outDstP,
|  | UInt16 | inDstSize |
| ) |  |  |

Parameters:

  | inSrcP,: | IN:

Parameters:

  | inSrcLen,: | IN:
  | outDstP,: | IN:
  | inDstSize,: | IN:

Return values:

  | UInt16 |

void HsTxtTruncateString | ( | Char * | textP,
|  | UInt16 | maxPixels,
|  | Boolean | keepLabel |
| ) |  |  |

Parameters:

  | textP,: | IN:

Parameters:

  | maxPixels,: | IN:
  | keepLabel,: | IN:

void HsUnimplemented | ( | void |  | ) |

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:07:03 2008 for Palm API Guide