API Guide Home (Online version only) |

# HsExt.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2005 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  *
    00007  * @ingroup HSExt
    00008  *
    00009  */
    00010
    00011 /**
    00012  * @file    HsExt.h
    00013  * @brief   Header file that 68K programs include to access
    00014  *      Handspring Extensions functionality.
    00015  *
    00016  *
    00017  */
    00018
    00019
    00020
    00021 #ifndef   __HS_EXT_68K_H__
    00022 #define   __HS_EXT_68K_H__
    00023
    00024 // Most of the definitions for HsExtensions are now in HsExtCommon.h so that
    00025 // they can be shared by both 68K and ARM programs...
    00026 #include <HsExtCommon.h>
    00027 #include <Common/System/HsCreators.h>
    00028 #include <HsNavCommon.h>
    00029 #include <HsExtTraps.h>
    00030
    00031 #if (!(defined NO_HSEXT_TRAPS)) && (defined __GNUC__) && (EMULATION_LEVEL == EMULATION_NONE)
    00032   #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 95)
    00033
    00034     #ifndef _Str
    00035     #define _Str(X)  #X
    00036     #endif
    00037
    00038     #define _HS_OS_CALL_WITH_UNPOPPED_16BIT_SELECTOR(table, vector, selector)   \
    00039         __attribute__ ((__callseq__ (                                       \
    00040             "move.w #" _Str(selector) ",-(%%sp); "                          \
    00041             "trap #" _Str(table) "; dc.w " _Str(vector))))
    00042
    00043     #define SYS_SEL_TRAP(trapNum, selector) \
    00044         _HS_OS_CALL_WITH_UNPOPPED_16BIT_SELECTOR(sysDispatchTrapNum, trapNum, selector)
    00045
    00046
    00047   #else // GNUC < 2.95
    00048
    00049     #define SYS_SEL_TRAP(trapNum, selector) \
    00050         __attribute__ ((inline (0x3f3c, selector, m68kTrapInstr+sysDispatchTrapNum,trapNum)))
    00051
    00052   #endif // GNUC < 2.95
    00053
    00054 #elif (!(defined NO_HSEXT_TRAPS)) && (defined (__MWERKS__))
    00055
    00056     #define SYS_SEL_TRAP(trapNum, selector) \
    00057         = {0x3f3c, selector, m68kTrapInstr+sysDispatchTrapNum,trapNum}
    00058
    00059 #else
    00060     #define SYS_SEL_TRAP(trapNum, selector)
    00061
    00062 #endif
    00063
    00064 /**
    00065  *  @brief
    00066  *
    00067  *  @param appCardNo:   IN:
    00068  *  @param appDbId: IN:
    00069  *  @param copyrightYearStrP:   IN:
    00070  *  @param extraCreditsStrP:    IN:
    00071  *  @retval Error code.
    00072  **/
    00073 void
    00074 HsAboutHandspringApp (UInt16 appCardNo, LocalID appDbId,
    00075                       Char* copyrightYearStrP, Char* extraCreditsStrP)
    00076                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelAboutHandspringApp);
    00077
    00078 //ported from HsExt.h from the Visor-4.0 tree - VSB
    00079 // <chg 30-Jun-99 dia> Defined macros to make about box easier to call.
    00080 #define HsAboutHandspringAppWithYearId(yearId)                              \
    00081     do                                                                      \
    00082       {                                                                     \
    00083         UInt16  appCardNo;                                                  \
    00084         LocalID appDbId;                                                    \
    00085         MemHandle   yearStrH;                                               \
    00086         Char*   yearStrP;                                                   \
    00087                                                                             \
    00088         yearStrH = DmGetResource (strRsc, yearId);                          \
    00089         yearStrP = MemHandleLock (yearStrH);                                \
    00090         SysCurAppDatabase(&appCardNo, &appDbId);                            \
    00091         HsAboutHandspringApp (appCardNo, appDbId, yearStrP, NULL);          \
    00092         MemPtrUnlock (yearStrP);                                            \
    00093         DmReleaseResource (yearStrH);                                       \
    00094       }                                                                     \
    00095     while (0)
    00096
    00097 #define HsAboutHandspringAppWithYearCredId(yearId, creditsId)               \
    00098     do                                                                      \
    00099       {                                                                     \
    00100         UInt16  appCardNo;                                                  \
    00101         LocalID appDbId;                                                    \
    00102         MemHandle   yearStrH, extraStrH;                                    \
    00103         Char*   yearStrP;                                                   \
    00104         Char*   extraStrP;                                                  \
    00105                                                                             \
    00106         yearStrH = DmGetResource (strRsc, yearId);                          \
    00107         yearStrP = MemHandleLock (yearStrH);                                \
    00108         extraStrH = DmGetResource (strRsc, creditsId);                      \
    00109         extraStrP = MemHandleLock (extraStrH);                              \
    00110         SysCurAppDatabase(&appCardNo, &appDbId);                            \
    00111         HsAboutHandspringApp (appCardNo, appDbId, yearStrP, extraStrP);     \
    00112         MemPtrUnlock (extraStrP);                                           \
    00113         DmReleaseResource (extraStrH);                                      \
    00114         MemPtrUnlock (yearStrP);                                            \
    00115         DmReleaseResource (yearStrH);                                       \
    00116       }                                                                     \
    00117     while (0)
    00118
    00119 #ifdef __cplusplus
    00120 extern "C" {
    00121 #endif
    00122
    00123 /**
    00124  *  @brief Retrieve a null terminated version string.
    00125  *
    00126  *  @param selector:    IN:  Selects which version string to get
    00127  *  @param outStrP: IN:  Buffer to receive the NULL terminated version string. The buffer should be
    00128  *               large enough to hold hsVersionStringSize bytes
    00129  *  @param sizeP:   IN:  If not NULL, returns the number of bytes stored in *outStrP, including the
    00130  *               NULL terminator
    00131  *  @retval 0 if no error, hsErrNotSupported if error occurs
    00132  **/
    00133 Err
    00134 HsGetVersionString (UInt16 /*HsVerStrEnum*/selector, Char* outStrP,
    00135                     UInt16* sizeP)
    00136                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelGetVersionString);
    00137
    00138 /**
    00139  *  @brief Get any Handspring specific attributes that aren’t appropriate to be accessed
    00140  *         through a feature. (e.g., dynamic information about device state) @see HsAttrEnum
    00141  *
    00142  *  @param attr:    IN:  Which attribute is being retrieved. Most attributes are defined in
    00143  *               “HsExtCommon.h” in the HsAttrEnum enumeration.
    00144  *  @param param:   IN:  Meaning depends on ’attr’ (currently implemented attributes only take 0 for
    00145  *               this argument).
    00146  *  @param valueP:  IN:  Cast depending on attr (refer HsAttrEnum for data type this argument should
    00147  *                           point to).
    00148  *  @retval Err 0 if no error
    00149  **/
    00150 Err
    00151 HsAttrGet (UInt16 attr /*HsAttrEnum*/, UInt32 param, UInt32* valueP)
    00152                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelAttrGet);
    00153
    00154 /**
    00155  *  @brief Set Handspring specific attributes. @see HsAttrEnum
    00156  *
    00157  *  @param attr:    IN:  Which attribute is being set.
    00158  *  @param param:   IN:  Meaning depends on ’attr’ (currently implemented attributes only take 0 for
    00159  *                   this argument).
    00160  *  @param valueP:  IN:  Cast depending on attr (refer HsAttrEnum for data type this argument should
    00161  *               point to).
    00162  *  @retval Err 0 if no error hsErrNotSupported otherwise.
    00163  **/
    00164 Err
    00165 HsAttrSet (UInt16 attr /*HsAttrEnum*/, UInt32 param, UInt32* valueP)
    00166                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelAttrSet);
    00167
    00168 /**
    00169  *  @brief HsExtensions maintains and utilizes a set of preferences that are not a part of the
    00170  *     Palm OS system preferences. They can be retrieved using this function. @see HsPrefEnum
    00171  *
    00172  *  @param pref:    IN:  IN which preference to retrieve (refer HsPrefEnum)
    00173  *  @param bufP:    IN:  IN buffer to store preference (refer HsPrefEnum for the size of the buffer needed).
    00174  *  @param prefSizeP:   IN:  IN/OUT on entry, size of bufP on exit, size of stored pref. If larger than size of
    00175  *               bufP, then hsErrBufferTooSmall is returned.
    00176  *  @retval Err 0 if no err
    00177  *          hsErrInvalidParam if pref is invalid
    00178  *          hsErrBufferTooSmall if *prefSizeP was smaller than actual pref
    00179  **/
    00180 Err
    00181 HsPrefGet (UInt16 pref /*HsPrefEnum*/, void* bufP,
    00182                     UInt32* prefSizeP)
    00183                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelPrefGet);
    00184
    00185 /**
    00186  *  @brief HsExtensions maintains and utilizes a set of preferences that are not a part of the
    00187  *     Palm OS system preferences. They can be set using this function. @see HsPrefEnum
    00188  *
    00189  *  @param pref:    IN:  which pref to retrieve, a HsPrefEnum
    00190  *  @param bufP:    IN:  buffer to store pref
    00191  *  @param prefSize:    IN:  size of pref to store
    00192  *  @retval Err 0 if no err
    00193  *              hsErrInvalidParam if pref is invalid
    00194  **/
    00195 Err
    00196 HsPrefSet (UInt16 pref /*HsPrefEnum*/, void* bufP,
    00197                     UInt32 prefSize)
    00198                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelPrefSet);
    00199
    00200 /**
    00201  *  @brief Function that gets the reference number to the phone library. It decides whether it
    00202  *     should return the GSM or the CDMA library based on the type of device. If the
    00203  *     library is not loaded, it loads the library.
    00204  *
    00205  *  @param refNum:  IN:  Library reference number to be used in other function.
    00206  *  @retval Err 0 if no error.
    00207  **/
    00208 Err
    00209 HsGetPhoneLibrary (UInt16 * refNum)
    00210                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelGetPhoneLibrary);
    00211
    00212 /**
    00213  *  @brief Tell the system that a gadget on the form is a certain type of status gadget so that
    00214  *     the system can properly draw and update it.
    00215  *
    00216  *  Tell the system that a gadget on the form is a certain type of status gadget so that
    00217  *  the system can properly draw and update it.
    00218  *  A form can only have one gadget for each status type. If more than one gadget is
    00219  *  set to a certain type, only the last one set will be recorded. This function can also be
    00220  *  used to erase and release a gadget whose type has already been set. To do this, type
    00221  *  should be set to 0.
    00222  *
    00223  *  NOTE The gadget dimensions in the current implementation are hardcoded to
    00224  *  values of 10 X 12 pixels for the battery gadget and 16 X 12 pixels for signal gadget.
    00225  *  Scaling is not supported, so define your gadget resources accordingly.
    00226  *
    00227  *  @param frmP:    IN:  pointer to the form with the gadget (we will convert to an ID before saving but
    00228  *               want a ptr to be passed as a param to ensure that the caller is setting the gadget
    00229  *               for a loaded form)
    00230  *  @param gadgetID:    IN:  id of the gadget whose type is being specified
    00231  *  @param type:    IN:  type of the gadget (pass a member of HsStatusGadgetTypeEnum—defined in
    00232  *                   HsExt.h or 0 to erase and release a gadget)
    00233  *  @retval Err 0 if no error.
    00234  **/
    00235 Err
    00236 HsStatusSetGadgetType (void* frmP, UInt16 gadgetID,
    00237                                    UInt16 type /*HsStatusGadgetTypeEnum*/)
    00238                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelStatusSetGadgetType);
    00239
    00240 /**
    00241  *  @brief Explicitly update all status gadgets on the current form.
    00242  *
    00243  **/
    00244 void
    00245 HsStatusUpdateGadgets (void)
    00246                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelStatusUpdateGadgets);
    00247
    00248 /**
    00249  *  @brief Extended version of GrfSetState to allow setting an option and option lock state.
    00250  *
    00251  *  The original GrfSetState does not have an autoShift parameter because it always
    00252  *  assumed that anyone setting the shift state through the API call wanted an
    00253  *  automatic shift. We do not make this assumption.
    00254  *  The shift state can be set by calling either HsGrfSetStateExt() or GrfSetState().
    00255  *  Either way, we have to make sure that both the keyboard shift state and the Graffiti
    00256  *  engine’s shift state get set correctly.
    00257  *
    00258  *  @param capsLock:    IN:  Set to turn caps lock on
    00259  *  @param numLock: IN:  Set to true to turn num lock on
    00260  *  @param optLock: IN:  Set to true to turn option lock on
    00261  *  @param upperShift:  IN:  Set to true to put into upper shift
    00262  *  @param optShift:    IN:  Set to true to put into option shift
    00263  *  @param autoShift:   IN:  Valid only if upperShift is true. Set to true if the graffiti engine should consider
    00264  *               the upper shift an auto shift.
    00265  *  @retval Err Always returns 0.
    00266  **/
    00267 Err
    00268 HsGrfSetStateExt (Boolean capsLock, Boolean numLock, Boolean optLock,
    00269                   Boolean upperShift, Boolean optShift, Boolean autoShift)
    00270                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelGrfSetStateExt);
    00271
    00272 /**
    00273  *  @brief Extended version of GrfGetState to include detection of option and option lock state.
    00274  *
    00275  *  @param capsLockP:   IN:  returns true if caps lock on
    00276  *  @param numLockP:    IN:  returns true if num lock on
    00277  *  @param optLockP:    IN:  returns true if opt lock on
    00278  *  @param tempShiftP:  IN:  returns current temporary shift
    00279  *  @param autoShiftedP:    IN:  returns TRUE if shift not set by the user but by the system, for example, at the
    00280  *                   beginning of a line.
    00281  *  @retval Err Always returns 0.
    00282  **/
    00283 Err
    00284 HsGrfGetStateExt (Boolean* capsLockP, Boolean* numLockP, Boolean* optLockP,
    00285                   UInt16* tempShiftP, Boolean* autoShiftedP)
    00286                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelGrfGetStateExt);
    00287
    00288 /**
    00289  *  @brief Places a UI object to the right of the form title. This function is useful for adjusting
    00290  *     object positions for localized titles.
    00291  *
    00292  *  @param voidFrmP:    IN:  ptr to form containing the object
    00293  *  @param objID:   IN:  id of the object being positioned
    00294  *  @param titleOffset: IN:  number of pixels between title bar and status gadget
    00295  *  @retval Boolean True if the object was moved from it’s original position.
    00296  *          False otherwise
    00297  **/
    00298 Boolean HsPutObjectAfterTitle (void* voidFrmP, UInt16 objID, UInt8 titleOffset)
    00299                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelPutObjectAfterTitle);
    00300
    00301
    00302 //HsInfo, HsEvtMetaEvent and HsSpringboardNotSupported are nop functions that are
    00303 //included for backwards compatibility
    00304 /**
    00305  *  @brief This call will return info on a particular attribute of the Handspring extensions.
    00306  *
    00307  *  This call is designed to return info that won’t fit into a Palm OS feature call (a
    00308  *  UInt32).
    00309  *
    00310  *  @param item:    IN:  which info to return
    00311  *  @param paramSize:   IN:  size of paramP block passed in
    00312  *  @param paramP:  IN:  info is returned here
    00313  *  @retval UInt32 0 if no error
    00314  **/
    00315 UInt32
    00316 HsInfo (UInt16 item, UInt16 paramSize,  void* paramP)
    00317                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelInfo);
    00318
    00319 /**
    00320  *  @brief
    00321  *
    00322  *  @param eventP:  IN:
    00323  *  @retval UInt16 Error code.
    00324  **/
    00325 UInt16
    00326 HsEvtMetaEvent (EventPtr eventP)
    00327                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelEvtMetaEvent);
    00328
    00329 /**
    00330  *  @brief Used to determine if the device supports the Springboard expansion slot or not.
    00331  *
    00332  *  On springboard devices, this function is unimplemented. To determine whether
    00333  *  the device has a Springboard extension slot or not, use HsGetTrapAddress() to
    00334  *  obtain the trap addresses of this function and HsUnimplemented. If they are equal,
    00335  *  the device has the Springboard extension slot, otherwise it doesn’t.
    00336  *
    00337  *  @retval Err All of the Springboard functions return an error on the Treo 600.
    00338  **/
    00339 Err
    00340 HsSpringboardNotSupported (void)
    00341                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelSpringboardNotSupported);
    00342
    00343 /**
    00344  *  @brief Works like SysGetTrapAddress, but for Handspring trap numbers.
    00345  *
    00346  *  For every HsExt function implemented in ARM native, there exists a wrapper 68K
    00347  *  function that simply calls the HsExt function in question. This may seem
    00348  *  roundabout, but HsGetTrapAddress is retained for backward compatibility.
    00349  *
    00350  *  @param trapNum: IN:  the address of the trap handler for the given selector.
    00351  *  @retval void* If the selector is invalid, returns the address of HsUnimplemented().
    00352  **/
    00353 void*
    00354 HsGetTrapAddress (UInt16 trapNum)
    00355                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelHsGetTrapAddress);
    00356
    00357 // Disconnects all open NetLib connections.  ***IMPORTANT*** This function MUST
    00358 //  be called only from the context of the UI task!
    00359 /**
    00360  *  @brief This function will completely close the currently active TCP/IP network
    00361  *     connection. The open count will be 0 after this call is made.
    00362  *
    00363  *  @retval Err 0 if successful.
    00364  **/
    00365 Err
    00366 HsNetworkDropConnection (void)
    00367                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelNetworkDropConnection);
    00368
    00369
    00370 //will display a fatal error message since this trap number will not be handled by
    00371 //the trap dispatcher
    00372 /**
    00373  *  @brief
    00374  *
    00375  **/
    00376 void
    00377 HsUnimplemented (void)
    00378                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelUnimplemented);
    00379
    00380
    00381 // Returns the pointer to the ARM form. We need this because the 68K
    00382 // form might be deleted.
    00383 /**
    00384  *  @brief
    00385  *
    00386  **/
    00387 void*
    00388 HsGetARMActiveFormPtr (void)
    00389                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelGetARMActiveFormPtr);
    00390
    00391 /**
    00392  *  @brief Allows the user to select a small or a large font size.
    00393  *
    00394  *  This is just like the Palm OS routine FontSelect, except it gives the user a choice of
    00395  *  only a small and a large font. If the originalFont is not bold, then the two choices
    00396  *  are stdFont and largeFont. If the original choice is bold, then the two choices are
    00397  *  boldFont and largeBoldFont.
    00398  *
    00399  *  @param originalFont:    IN:  The original font ID (used to select the current font).
    00400  *  @retval FontID The new font ID.
    00401  **/
    00402 FontID
    00403 HsTwoFontSelect(FontID originalFont)
    00404                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelTwoFontSelect);
    00405
    00406 /**
    00407  *  @brief Opens a window with the number filled in the address text field.
    00408  *
    00409  *  This function can be used by any application that wants to dial a phone number,
    00410  *  but first give the user the option of editing the number. This functionality
    00411  *  originally existed in the STE, but was moved to the system.
    00412  *
    00413  *  @param numberP: IN:  A pointer to a string that contains the phone number to put into the number field.
    00414  *  @param nameP:   IN:  A pointer to a string that contains the name to put into the title of the dialog.
    00415  *  @param callerID:    IN:  If this is true, then we will attempt to match the phone number with an entry in
    00416  *                   the address book. If a match is found, then the title of the dialog will contain the name.
    00417  **/
    00418 void
    00419 HsOpenDialNumberDialog(char* numberP, char* nameP, Boolean callerID)
    00420                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelOpenDialNumberDialog);
    00421
    00422 /**
    00423  *  @brief Turn the radio (cell phone) on if it’s off.
    00424  *
    00425  *  @retval Err 0 if successful.
    00426  **/
    00427 Err
    00428 HsTurnRadioOn(void)
    00429                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelTurnRadioOn);
    00430
    00431 /**
    00432  *  @brief Launches the messaging application (SMS) to the new message form with some
    00433  *     fields optionally prefilled with the specified values.
    00434  *
    00435  *  This function can be used by any application that wants to launch the messaging
    00436  *  application and have some of the fields prefilled without using the helper APIs.
    00437  *
    00438  *  @param addressP:    IN:  A pointer to a string that contains the phone number to put into the To: field. (optional)
    00439  *  @param nameP:   IN:  A pointer to a string that contains the name to put above the To: field. (optional)
    00440  *  @param msgP:    IN:  A pointer to a string that contains the message text of the new message. (optional)
    00441  *  @retval Err 0 on success or the error that occurred.
    00442  **/
    00443 Err
    00444 HsCreateNewMessage(char* addressP, char* nameP, char* msgP)
    00445                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelCreateNewMessage);
    00446
    00447
    00448 /**
    00449  *  @brief Launches the email application to the new email form with some fields optionally
    00450  *     prefilled with the specified values.
    00451  *
    00452  *  This function can be used by any application that wants to launch the email
    00453  *  application and have some of the fields prefilled without using the helper APIs.
    00454  *
    00455  *  @param addressP:    IN:  A pointer to a string that contains the address to put in the To: field.
    00456  *  @param ccP:     IN:  A pointer to a string that contains the address to put in the cc: field. (optional)
    00457  *  @param subjectP:    IN:  A pointer to a string that contains the subject of the new email. (optional)
    00458  *  @param msgP:    IN:  A pointer to a string that contains the message text of the new email. (optional)
    00459  *  @retval Err 0 on success or the error that occurred.
    00460  **/
    00461 Err
    00462 HsCreateNewEmail(char* addressP, char* ccP, char* subjectP, char* msgP)
    00463                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelCreateNewEmail);
    00464
    00465 /**
    00466  *  @brief Launches the browser to the specified URL.
    00467  *
    00468  *  This function can be used by any application that wants to launch the web browser
    00469  *  to a specified URL without using the helper APIs.
    00470  *
    00471  *  @param urlP:    IN:  A pointer to a string that contains the phone number to put into the number field.
    00472  *  @retval Err 0 on success or the error that occurred.
    00473  **/
    00474 Err
    00475 HsBrowseUrl(char* urlP)
    00476                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelBrowseUrl);
    00477
    00478 /**
    00479  *  @brief If a form has a system drawn focus ring, gets info about the ring
    00480  *
    00481  *  @param formP:   IN:  Ptr to form whose ring info is to be obtained
    00482  *  @param objectIDP:   IN:  If not NULL, on exit will point to the object with the system-drawn focus ring
    00483  *  @param extraInfoP:  IN:  If not NULL, on exit will point to any extra info associated with the focus ring.
    00484  *               Extra info is any info that the caller wants to associate with a ring.
    00485  *               hsNavFocusRingNoExtraInfo (0xFFFF) is used to represent no extra info.
    00486  *  @param boundsInsideRingP:   IN:  If not NULL, on exit will point to the bounds inside the system-drawn focus ring
    00487  *  @param ringStyleP:  IN:  If not NULL, on exit will point to the style of the focus ring
    00488  *  @retval Err Error code.
    00489  **/
    00490 Err
    00491 HsNavGetFocusRingInfo (const FormType* formP, UInt16* objectIDP,
    00492                        Int16* extraInfoP, RectangleType* boundsInsideRingP,
    00493                        HsNavFocusRingStyleEnum* ringStyleP)
    00494                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelNavGetFocusRingInfo);
    00495 /**
    00496  *  @brief Tells the system to draw a focus ring for an object
    00497  *
    00498  *  @param formP:   IN:  Form containing object whose ring is being drawn
    00499  *  @param objectID:    IN:  ID of object getting the focus ring
    00500  *  @param extraInfo:   IN:  Any info that caller wants associated with the focus ring. For example, the
    00501  *               system uses this field to store the temporarily-selected item of a focused,
    00502  *               embedded list. Caller should pass hsNavFocusRingNoExtraInfo (0xFFFF) if there
    00503  *               is no associated info.
    00504  *  @param boundsInsideRingP:   IN:  Points to the bounds around which the ring should be drawn
    00505  *  @param ringStyle:   IN:  Enumeration value that represents the desired style for the ring.
    00506  *               hsNavFocusRingStyleObjectTypeDefault can be passed if caller just wants the
    00507  *               default ring style for the object’s type.
    00508  *  @param forceRestore:    IN:  If ring is already on the object, whether to force restoration of what’s behind the
    00509  *                   ring before redrawing the ring.
    00510  *  @retval Err Returns errNone if no error, error code otherwise.
    00511  **/
    00512 Err
    00513 HsNavDrawFocusRing (FormType* formP, UInt16 objectID, Int16 extraInfo,
    00514                     RectangleType* boundsInsideRingP,
    00515                     HsNavFocusRingStyleEnum ringStyle, Boolean forceRestore)
    00516                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelNavDrawFocusRing);
    00517
    00518 /**
    00519  *  @brief Removes system-drawn ring from around currently focused object
    00520  *
    00521  *  @param formP:   IN:  Ptr to form containing the object with the ring
    00522  *  @retval Err Returns errNone if no error, error code otherwise
    00523  **/
    00524 Err
    00525 HsNavRemoveFocusRing (FormType* formP)
    00526                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelNavRemoveFocusRing);
    00527
    00528 /**
    00529  *  @brief Sends a frmObjectFocusTake event for an object
    00530  *
    00531  *  @param formP:   IN:  Ptr to form that contains the object
    00532  *  @param objID:   IN:  ID of the object
    00533  **/
    00534 void
    00535 HsNavObjectTakeFocus (const FormType* formP, UInt16 objID)
    00536                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelNavObjectTakeFocus);
    00537
    00538 /**
    00539  *  @brief Obtains a focus color
    00540  *
    00541  *  @param color:   IN:  Enumeration value that specifies which focus color to get
    00542  *  @param rgbColorP:   IN:  On exit, points to the focus color
    00543  **/
    00544 void
    00545 HsNavGetFocusColor (HsNavFocusColorEnum color, RGBColorType* rgbColorP)
    00546                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelNavGetFocusColor);
    00547
    00548 /**
    00549  *  @brief Sets new focus color
    00550  *
    00551  *  @param color:   IN:  Enumeration value that specifies which focus color to set
    00552  *  @param rgbColorP:   IN:  Points to the new color
    00553  *  @param oldRgbColorP:    IN:  If not NULL, on exit it will point to the old focus color
    00554  **/
    00555 void
    00556 HsNavSetFocusColor (HsNavFocusColorEnum color, RGBColorType* rgbColorP,
    00557                     RGBColorType* oldRgbColorP)
    00558                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelNavSetFocusColor);
    00559
    00560 /**
    00561  *  @brief Set or get the state of the LED or Vibrator.
    00562  *
    00563  *  @param count:   IN:  Count of how many times to blink or pulse the indicator, or one of the
    00564  *               HsIndicatorCountEnum values to either run forever or get the current state.
    00565  *  @param indicatorType:   IN:  HsIndicatorTypeEnum (LED or vibrator)
    00566  *  @param stateP:  IN:  Pointer to HsIndicatorStateEnum If setting, points to state to set. If getting, as
    00567  *               IN param points to “none” state of the source to query (or kIndicatorStateNull
    00568  *               to query whatever source has priority). As OUT param, contains the result of
    00569  *               the query (kIndicatorStateNull if querying for the active source and there is none)
    00570  *  @retval Err 0 if no error
    00571  **/
    00572 Err
    00573 HsIndicatorState (UInt16 count, UInt16 indicatorType, UInt16* stateP)
    00574                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelIndicatorState);
    00575
    00576 /**
    00577  *  @brief Get or set the current mode.
    00578  *
    00579  *  @param set:     IN:  If true, we’ll switch to *modeP; if false we’ll put the current mode in *modeP
    00580  *  @param modeP:   IN:  If we’re setting, we’ll switch to this mode (refer HsLightModeEnum). If we’re
    00581  *               getting, we’ll put the current mode here.
    00582  *  @retval Err An error code; 0 if no error.
    00583  **/
    00584 Err
    00585 HsLightMode (Boolean set, UInt16* modeP)
    00586                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelLightMode);
    00587
    00588 /**
    00589  *  @brief Add/remove special lighting circumstances
    00590  *
    00591  *  This function does reference counting on added circumstances, so be sure to not
    00592  *  add a circumstance without eventually removing it (unless you intended that).
    00593  *  Note that some circumstances don’t take effect until some point in time later (in
    00594  *  SysHandleEvent). That’s because some circumstances only take effect when the
    00595  *  device is idle for some amount of time.
    00596  *
    00597  *  @param add:     IN:  If true, we’re adding a circumstance, If false, we’re removing it.
    00598  *  @param circumstance:    IN:  The circumstance we’re adding or taking away (refer
    00599  *                       HsLightCircumstanceEnum).
    00600  *  @retval Err An error code; 0 if no error
    00601  **/
    00602 Err
    00603 HsLightCircumstance (Boolean add, UInt16 circumstance)
    00604                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelLightCircumstance);
    00605
    00606 /**
    00607  *  @brief
    00608  *
    00609  **/
    00610 UInt16 HsCurrentLightCircumstance(void)
    00611                 SYS_SEL_TRAP (sysTrapHsSelector, hsGetCurrentLightCircumstance);
    00612
    00613 /**
    00614  *  @brief Converts HsKeysPressed() results into a bitfield.
    00615  *
    00616  *  This function provides compatibility with earlier Handspring SDKs. The preferred
    00617  *  method of querying key states is to call HsKeysPressed().
    00618  *
    00619  *  @param keys:    IN:  Array of three bitfields representing which keys are depressed.
    00620  **/
    00621 void
    00622 HsKeyCurrentStateExt (UInt32 keys[3])
    00623                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelKeyCurrentStateExt);
    00624
    00625 /**
    00626  *  @brief Glue to HsKeyEnabled() based on bitfields.
    00627  *
    00628  *  This function provides compatibility with earlier Handspring SDKs. The preferred
    00629  *  method of enabling keys is to call HsKeyEnableKey().
    00630  *
    00631  *  @param keyMaskNew:  IN:  new enabled mask
    00632  *  @param keyMaskOld:  IN:  previous enabled mask
    00633  **/
    00634 void
    00635 HsKeySetMaskExt (const UInt32 keyMaskNew[3], UInt32 keyMaskOld[3])
    00636                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelKeySetMaskExt);
    00637
    00638 /**
    00639  *  @brief Get the current state of specified keys.
    00640  *
    00641  *  This extends KeyCurrentState().
    00642  *
    00643  *  @param count:   IN:  number of elements in keyCodes[] and pressed[]
    00644  *  @param keyCodes[]:  IN:  Array of keyCodes to test
    00645  *  @param pressed[]:   IN:  Each element is set to true if the key specified by the corresponding element in
    00646  *               keyCodes[] is pressed, and set to false if it’s not pressed. It is acceptable to pass
    00647  *               NULL if only the return value is of interest.
    00648  *  @retval UInt16 Count of keys in keyCodes[] that are pressed
    00649  **/
    00650 UInt16
    00651 HsKeysPressed (UInt16 count, const UInt16 keyCodes[], Boolean pressed[])
    00652                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelKeysPressed);
    00653
    00654 /**
    00655  *  @brief Stop a key from sending any more autorepeat events until it is released.
    00656  *
    00657  *  @param keyCode: IN:  key to stop
    00658  *  @retval Err errNone if the keyCode is the last key pressed and it’s still held.
    00659  **/
    00660 Err
    00661 HsKeyStop (UInt16 keyCode)
    00662                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelKeyStop);
    00663
    00664 /**
    00665  *  @brief Enable/disable a key from generating key events.
    00666  *
    00667  *  @param keyCode: IN:  which key to enable/disable
    00668  *  @param enabled: IN:  true to enable, false to disable
    00669  *  @retval Boolean true if previously enabled.
    00670  **/
    00671 Boolean
    00672 HsKeyEnableKey (UInt16 keyCode, Boolean enabled)
    00673                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelKeyEnableKey);
    00674
    00675 /**
    00676  *  @brief Determine which key generates a certain character.
    00677  *
    00678  *  @param chrCode: IN:  the character to search for
    00679  *  @retval UInt16 The key code.
    00680  **/
    00681 UInt16
    00682 HsKeyChrCodeToKeyCode (UInt16 chrCode)
    00683                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelKeyChrCodeToKeyCode);
    00684
    00685 /**
    00686  *  @brief Translate a key code to the character generated by that key.
    00687  *
    00688  *  @param keyCode: IN:  The key to lookup
    00689  *  @param modifiersIn: IN:  Modifier mask indicating which character should be returned
    00690  *  @param chrP:    IN:  The character produced by the key
    00691  *  @param modifiersOutP:   IN:  The keyMask bits that must be set if a keyDown event is formed with the
    00692  *                   character. (Not including the bits set in modifiersIn)
    00693  **/
    00694 void
    00695 HsKeyKeyCodeToChrCode (UInt16 keyCode, UInt16 modifiersIn,
    00696                        UInt16* chrP, UInt16* modifiersOutP)
    00697                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelKeyKeyCodeToChrCode);
    00698
    00699 /**
    00700  *  @brief Determine if an event came from the physical keyboard.
    00701  *
    00702  *  @param eventP:  IN:  The event to check
    00703  *  @retval Boolean True if the event came from the keyboard
    00704  **/
    00705 Boolean
    00706 HsKeyEventIsFromKeyboard (EventPtr eventP)
    00707                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelKeyEventIsFromKeyboard);
    00708
    00709 /**
    00710  *  @brief Displays a dialog to the user allowing them to confirm the saving of data, and the
    00711  *     name that they wish to assign.
    00712  *
    00713  *  @param name:    IN:  Comes in as the default name and returns the name the user chose
    00714  *  @retval Boolean True if the user confirmed that the save should take place.
    00715  *      False otherwise.
    00716  **/
    00717 Boolean
    00718 HsExtDoSaveAsDialog (Char * name)
    00719                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelDoSaveAsDialog);
    00720
    00721 /**
    00722  *  @brief
    00723  *
    00724  *  @param inSrcP:  IN:
    00725  *  @param inSrcLen:    IN:
    00726  *  @param outDstP: IN:
    00727  *  @param inDstSize:   IN:
    00728  *  @retval UInt16
    00729  **/
    00730 UInt16
    00731 HsTxtPrepFindString(const Char* inSrcP, UInt16 inSrcLen,
    00732                         Char* outDstP, UInt16 inDstSize)
    00733                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelTxtPrepFindString);
    00734
    00735 // These are convenient multi-byte friendly text routines
    00736 /**
    00737  *  @brief
    00738  *
    00739  *  @param textP:   IN:
    00740  *  @retval UInt32
    00741  **/
    00742 UInt32
    00743 HsTxtNumChars(Char const* textP)
    00744                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelTxtNumChars);
    00745
    00746 /**
    00747  *  @brief
    00748  *
    00749  *  @param textP:   IN:
    00750  *  @param maxPixels:   IN:
    00751  *  @param keepLabel:   IN:
    00752  **/
    00753 void
    00754 HsTxtTruncateString(Char* textP, UInt16 maxPixels, Boolean keepLabel)
    00755                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelTxtTruncateString);
    00756
    00757 /**
    00758  *  @brief
    00759  *
    00760  *  @param textP:   IN:
    00761  *  @param textLen: IN:
    00762  *  @retval Boolean
    00763  **/
    00764 Boolean
    00765 HsTxtIsAscii(Char* textP, UInt16 textLen)
    00766                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelTxtIsAscii);
    00767
    00768 /**
    00769  *  @brief
    00770  *  @retval Boolean
    00771  **/
    00772 Boolean
    00773 HsIsHTTPLibraryLoaded (void)
    00774                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelIsHTTPLibraryLoaded);
    00775
    00776 /**
    00777  *  @brief Obtains the temporarily selected item of an embedded list
    00778  *
    00779  *  @param formP:   IN:  Pointer to the form containing the list whose temporary selection is to be obtained
    00780  *  @param listID:  IN:  ID of list whose temporary selection is to be obtained
    00781  *  @retval Int16 Returns the temporarily selected list item
    00782  **/
    00783 Int16
    00784 HsNavLstGetTempSelection (const FormType* formP, UInt16 listID)
    00785                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelNavLstGetTempSelection);
    00786
    00787 /**
    00788  *  @brief Sets the temporarily selected item for an embedded list
    00789  *
    00790  *  @param formP:   IN:  Pointer to the form containing the list whose temporary selection is to be set
    00791  *  @param listID:  IN:  ID of list whose temporary selection is to be set
    00792  *  @param itemNum: IN:  Number of the item that should be temporarily selected
    00793  **/
    00794 void
    00795 HsNavLstSetTempSelection (const FormType* formP, UInt16 listID, Int16 itemNum)
    00796                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelNavLstSetTempSelection);
    00797
    00798
    00799 /**
    00800  *  @brief Starts and stops memory tracing
    00801  *
    00802  *  @param tarce:   IN:  should tracing be started or stopped
    00803  *  if true tracing will be started.
    00804  *
    00805  *  called from the 68K controling (test) app.
    00806  **/
    00807 void
    00808 HsStartMemoryTracing(Boolean trace)
    00809                 SYS_SEL_TRAP (sysTrapHsSelector, hsSelStartMemoryTracing);
    00810
    00811
    00812 #ifdef __cplusplus
    00813 }
    00814 #endif
    00815
    00816 #endif    // __HS_EXT_68K_H__

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