(Online version only)
|
API Guide Home (Online version only) |
|
Definition in file HsExt.h.
Include dependency graph for HsExt.h:
Go to the source code of this file.
| #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)
| #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)
| void HsAboutHandspringApp | ( | UInt16 | appCardNo, | |
| LocalID | appDbId, | |||
| Char * | copyrightYearStrP, | |||
| Char * | extraCreditsStrP | |||
| ) |
| appCardNo,: | IN: |
| appDbId,: | IN: | |
| copyrightYearStrP,: | IN: | |
| extraCreditsStrP,: | IN: |
| Error | code. |
Get any Handspring specific attributes that aren’t appropriate to be accessed through a feature. (e.g., dynamic information about device state).
| 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). |
| Err | 0 if no error |
Set Handspring specific attributes.
| 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). |
| 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.
| urlP,: | IN: A pointer to a string that contains the phone number to put into the number field. |
| 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.
| 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) |
| 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.
| 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) |
| Err | 0 on success or the error that occurred. |
| UInt16 HsCurrentLightCircumstance | ( | void | ) |
| UInt16 HsEvtMetaEvent | ( | EventPtr | eventP | ) |
| eventP,: | IN: |
| UInt16 | Error code. |
Displays a dialog to the user allowing them to confirm the saving of data, and the name that they wish to assign.
| name,: | IN: Comes in as the default name and returns the name the user chose |
| Boolean | True if the user confirmed that the save should take place. False otherwise. |
| void* HsGetARMActiveFormPtr | ( | void | ) |
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.
| refNum,: | IN: Library reference number to be used in other function. |
| 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.
| trapNum,: | IN: the address of the trap handler for the given selector. |
| void* | If the selector is invalid, returns the address of HsUnimplemented(). |
Retrieve a null terminated version string.
| 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 |
| 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.
| 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. |
| 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.
| 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. |
| Err | Always returns 0. |
Set or get the state of the LED or Vibrator.
| 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) |
| Err | 0 if no error |
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).
| item,: | IN: which info to return | |
| paramSize,: | IN: size of paramP block passed in | |
| paramP,: | IN: info is returned here |
| UInt32 | 0 if no error |
| Boolean HsIsHTTPLibraryLoaded | ( | void | ) |
| Boolean |
Determine which key generates a certain character.
| chrCode,: | IN: the character to search for |
| 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().
| keys,: | IN: Array of three bitfields representing which keys are depressed. |
Enable/disable a key from generating key events.
| keyCode,: | IN: which key to enable/disable | |
| enabled,: | IN: true to enable, false to disable |
| Boolean | true if previously enabled. |
| Boolean HsKeyEventIsFromKeyboard | ( | EventPtr | eventP | ) |
Determine if an event came from the physical keyboard.
| eventP,: | IN: The event to check |
| 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.
| 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) |
Glue to HsKeyEnabled() based on bitfields.
This function provides compatibility with earlier Handspring SDKs. The preferred method of enabling keys is to call HsKeyEnableKey().
| keyMaskNew,: | IN: new enabled mask | |
| keyMaskOld,: | IN: previous enabled mask |
Get the current state of specified keys.
This extends KeyCurrentState().
| 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. |
| UInt16 | Count of keys in keyCodes[] that are pressed |
Stop a key from sending any more autorepeat events until it is released.
| keyCode,: | IN: key to stop |
| Err | errNone if the keyCode is the last key pressed and it’s still held. |
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.
| 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). |
| Err | An error code; 0 if no error |
Get or set the current mode.
| 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. |
| 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.
| 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. |
| Err | Returns errNone if no error, error code otherwise. |
| void HsNavGetFocusColor | ( | HsNavFocusColorEnum | color, | |
| RGBColorType * | rgbColorP | |||
| ) |
Obtains a focus color.
| 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.
| 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 |
| Err | Error code. |
Obtains the temporarily selected item of an embedded list.
| 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 |
| Int16 | Returns the temporarily selected list item |
Sets the temporarily selected item for an embedded list.
| 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.
| 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.
| formP,: | IN: Ptr to form containing the object with the ring |
| Err | Returns errNone if no error, error code otherwise |
| void HsNavSetFocusColor | ( | HsNavFocusColorEnum | color, | |
| RGBColorType * | rgbColorP, | |||
| RGBColorType * | oldRgbColorP | |||
| ) |
Sets new focus color.
| 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.
| 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.
| 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. |
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.
| 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. |
| Err | 0 if no err hsErrInvalidParam if pref is invalid hsErrBufferTooSmall if *prefSizeP was smaller than actual pref |
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.
| pref,: | IN: which pref to retrieve, a HsPrefEnum | |
| bufP,: | IN: buffer to store pref | |
| prefSize,: | IN: size of pref to store |
| Err | 0 if no err hsErrInvalidParam if pref is invalid |
Places a UI object to the right of the form title. This function is useful for adjusting object positions for localized titles.
| 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 |
| 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.
| Err | All of the Springboard functions return an error on the Treo 600. |
| void HsStartMemoryTracing | ( | Boolean | trace | ) |
Starts and stops memory tracing.
| tarce,: | IN: should tracing be started or stopped if true tracing will be started. |
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.
| 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) |
| 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.
| 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.
| originalFont,: | IN: The original font ID (used to select the current font). |
| FontID | The new font ID. |
| textP,: | IN: |
| textLen,: | IN: |
| Boolean |
| UInt16 HsTxtPrepFindString | ( | const Char * | inSrcP, | |
| UInt16 | inSrcLen, | |||
| Char * | outDstP, | |||
| UInt16 | inDstSize | |||
| ) |
| inSrcP,: | IN: |
| inSrcLen,: | IN: | |
| outDstP,: | IN: | |
| inDstSize,: | IN: |
| UInt16 |
| textP,: | IN: |
| 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 |