< Home < Developers < Development Support < Documentation

## 25 Attention Manager

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 25 Attention Manager Attention Manager Data Structures AttnCommandType AttnCommandArgsType AttnFlagsType AttnLaunchCodeArgsType AttnLevelType Attention Manager Constants Error Code Constants Attention Manager Drawing Constants Attention Manager Feature Constants Attention Manager Functions AttnDoSpecialEffects AttnForgetIt AttnGetAttention AttnGetCounts AttnIndicatorEnable AttnIndicatorEnabled AttnIterate AttnListOpen AttnUpdate Application-Defined Functions AttnCallbackProc |  |  |  | This chapter provides reference material for the Attention Manager, and is divided into the following sections: Attention Manager Data Structures Attention Manager Constants Attention Manager Functions Application-Defined Functions The Attention Manager API is declared in the header file AttentionMgr.h. For more information about the attention manager, see the section "Getting the User's Attention" in the Palm OS Programmer's Companion, vol. I. IMPORTANT: The Attention Manager was introduced in Palm OS® 4.0 and is not available in earlier versions of the operating system. ## Attention Manager Data Structures ## New AttnCommandType The AttnCommandType typedef specifies the set of possible commands that can be sent to the application requesting the user's attention, either as a parameter to the AttnCallbackProc callback function or as one of the arguments that accompanies a sysAppLaunchCmdAttention launch code.
    typedef UInt16 AttnCommandType;
The following table lists the values that AttnCommandType can assume. #####
Constant | Description
--- | ---
kAttnCommandDrawDetail | Indicates that the application needs to draw the detailed contents of the attention dialog. The command arguments parameter points to a structure of type drawDetail.
kAttnCommandDrawList | Indicates that the application needs to draw the appropriate list item in the attention dialog. The command arguments parameter points to a structure of type drawList.
kAttnCommandPlaySound | Indicates that the application needs to play a sound. The command arguments parameter is NULL.
kAttnCommandCustomEffect | Indicates that the application needs to perform any application-specific special effects. This command is only sent for attention items that set the kAttnFlagsCustomEffectBit when they call AttnGetAttention, which most applications won't do.
kAttnCommandGoThere | Tells the application to navigate to the item. The command arguments parameter is NULL. An application commonly calls SysAppLaunch upon receipt of this command to have itself launched.
kAttnCommandGotIt | Tells the application that the user is dismissing the item. The command arguments parameter points to a structure of type gotIt. The application may choose to clean up memory at this point.
kAttnCommandSnooze | Indicates to the application that the user is snoozing. The command arguments parameter is NULL. Most applications do nothing upon receipt of this command. This command is passed to the appropriate application for each and every item currently pending, insistent or subtle. Applications with more than one attention item pending are called more than once.
kAttnCommandIterate | This command is passed to the application during the enumeration of attention items. It is particularly useful after HotSync® operations, as it allows the application to examine each item, updating or removing those that are stale or invalid. The command arguments parameter points to a structure of type iterate.
## New AttnCommandArgsType The AttnCommandArgsType structure is a union of C structures. How you interpret the union's contents depends on which command it accompanies. Not all commands are accompanied by an AttnCommandArgsType structure, as listed in the following table: #####
AttnCommandType | Accompanied By
--- | ---
kAttnCommandDrawDetail | drawDetail
kAttnCommandDrawList | drawList
kAttnCommandPlaySound | None
kAttnCommandCustomEffect | None
kAttnCommandGoThere | None
kAttnCommandGotIt | gotIt
kAttnCommandSnooze | None
kAttnCommandIterate | iterate
The structures that make up the AttnCommandArgsType union are described in the following sections. #### drawDetail When kAttnCommandDrawDetail is passed to the application, either via the callback function or as a parameter accompanying the sysAppLaunchCmdAttention launch code, the application needs to draw the detailed contents of the attention dialog. The drawDetail structure accompanies the kAttnCommandDrawDetail command, and provides the information needed to draw the contents of that dialog.
    struct AttnCommandArgsDrawDetailTag {
      RectangleType bounds;
      Boolean firstTime;
      AttnFlagsType flags;
    } drawDetail;
#### Field Descriptions #####
bounds | Contains the window-relative bounding box for the area to draw. The clipping region is also set to the dimensions of this box to prevent accidental drawing outside.
--- | ---
firstTime | Set to true if the user has not yet seen this item. The value of this field could be used to display attentions that the user hasn't seen before in some special way. firstTime also indicates to your application whether or not the area in which your application is to draw has been erased. If firstTime is false, the area is not guaranteed to be blank; your application will need to erase it.
flags | The global user preferences for this attention attempt combined with the custom flags passed in by the developer. Only the lower 16 bits of this field have meaning; use kAttnFlagsSoundBit, kAttnFlagsLEDBit, kCustomFlagsVibrateBit, and kAttnFlagsCustomEffectBit (described under "AttnFlagsType") to interpret the contents of this field.
#### drawList When kAttnCommandDrawList is passed to the application, either via the callback function or as a parameter accompanying the sysAppLaunchCmdAttention launch code, the application needs to draw the appropriate list item in the attention dialog. The drawList structure accompanies the kAttnCommandDrawList command, and provides the information needed to draw the contents of that dialog.
    struct AttnCommandArgsDrawListTag {
      RectangleType bounds;
      Boolean firstTime;
      AttnFlagsType flags;
      Boolean selected;
    } drawList;
#### Field Descriptions #####
bounds | Contains the window-relative bounding box for the area to draw. The clipping region is also set to the dimensions of this box to prevent accidental drawing outside.
firstTime | Set to true if the user has not yet seen this item. The value of this field could be used, for example, to trigger a custom sound the first time this attention item is presented to the user.
flags | The global user preferences for this attention attempt combined with the custom flags passed in by the developer. Only the lower 16 bits of this field have meaning; use kAttnFlagsSoundBit, kAttnFlagsLEDBit, kCustomFlagsVibrateBit, and kAttnFlagsCustomEffectBit (described under "AttnFlagsType") to interpret the contents of this field.
selected | Set to true if the item has been selected. It is up to your code to draw the item appropriately (typically by changing the UI colors) based upon the value of this flag.
#### gotIt When kAttnCommandGotIt is passed to the application, either via the callback function or as a parameter accompanying the sysAppLaunchCmdAttention launch code, it is accompanied by an gotIt structure. This structure indicates whether the kAttnCommandGotIt command was generated because the user dismissed the attention, or whether the system is simply informing your application that AttnForgetIt was called. Your application normally ignores the latter case if your application made the call to AttnForgetIt.
    struct AttnCommandArgsGotItTag {
      Boolean dismissedByUser;
    } gotIt;
#### Field Descriptions #####
dismissedByUser | true indicates that the user dismissed the attention. false indicates that the kAttnCommandGotIt command was generated by a call to AttnForgetIt.
#### iterate When kAttnCommandIterate is passed to the application, either via the callback function or as a parameter accompanying the sysAppLaunchCmdAttention launch code, it is accompanied by an iterate structure. This structure contains any necessary data that the application may need in order to process the callback or launch code.
    struct AttnCommandArgsIterateTag {
      UInt32 iterationData;
    } iterate;
#### Field Descriptions #####
iterationData | Any necessary data that the application may need in order to process the callback or launch code. The value of this field is that which was originally passed to AttnIterate.
## New AttnFlagsType Pass a value of this type to AttnGetAttention and AttnUpdate to specify what means the device should or should not use to get the user's attention. A value of this type is also passed back to your code either as a parameter to the callback function or, if no callback was specified, as part of the structure passed with the sysAppLaunchCmdAttention launch code.
    typedef UInt32 AttnFlagsType;
Note that more bits may be defined if necessary to accommodate additional hardware. #####
Constant | Value | Description
--- | --- | ---
kAttnFlagsSoundBit | 0x0001 | Plays a sound.
kAttnFlagsLEDBit | 0x0002 | Blinks an LED, if the device is so equipped.
kAttnFlagsVibrateBit | 0x0004 | Triggers vibration, if the device is so equipped.
kAttnFlagsCustomEffectBit | 0x0008 | Triggers an application-specific custom effect.
kAttnFlagsAllBits | 0xFFFF | Uses all available means to get the user's attention.
kAttnFlagsUseUserSettings | 0x0000 | System-wide preferences determine what means are used to get the user's attention.
The following constant values can be used to override the user's settings and force or prevent specific behaviors: #####
Constant | Value | Description
--- | --- | ---
kAttnFlagsAlwaysSound | kAttnFlagsSoundBit | Play a sound, regardless of the user's settings.
kAttnFlagsAlwaysLED | kAttnFlagsLEDBit | Blink an LED, if the device is so equipped, regardless of the user's settings.
kAttnFlagsAlwaysVibrate | kAttnFlagsVibrateBit | Vibrate, if the device is so equipped, regardless of the user's settings.
kAttnFlagsAlwaysCustomEffect | kAttnFlagsCustomEffectBit | Trigger an application-specific custom effect.
kAttnFlagsEverything | kAttnFlagsAllBits | Use every available means to get the user's attention, regardless of the user's settings.
kAttnFlagsNoSound | kAttnFlagsSoundBit << 16 | Prevent a sound from being played, regardless of the user's settings.
kAttnFlagsNoLED | kAttnFlagsLEDBit << 16 | Prevent the LED from flashing, regardless of the user's settings.
kAttnFlagsNoVibrate | kAttnFlagsVibrateBit << 16 | Prevent vibration, regardless of the user's settings.
kAttnFlagsNoCustomEffect | kAttnFlagsCustomEffectBit << 16 | Prevent triggering of the application-specific custom effect.
kAttnFlagsNothing | kAttnFlagsAllBits << 16 | Disable all attention-getting mechanisms, regardless of the user's settings.
These constants can be used in combination. For example, to disable both sound and the LED, use kAttnFlagsNoSound | kAttnFlagsNoLED. If neither kAttnFlagsAlwaysSound nor kAttnFlagsNoSound is set for a given attention item, a sound plays if and only if the user's preference is to play a sound and the user's preference for alarm volume is non-zero. ## New AttnLaunchCodeArgsType If a callback function is not specified in a call to AttnGetAttention and the Attention Manager needs your code to draw the details of your attention in the attention dialog or perform another attention-specific function, it sends a sysAppLaunchCmdAttention launch code to your application. Along with the launch code, it passes a pointer to the following structure, which indicates both what your code is expected to do and identifies the attention that triggered the launch code:
    typedef struct {
      AttnCommandType command;
      UInt32 userData;
      AttnCommandArgsType *commandArgsP;
    } AttnLaunchCodeArgsType;
#### Field Descriptions #####
command | Indicates what your code is being requested to do. The complete list of possible commands are described in the definition of AttnCommandType.
userData | Identifier that distinguishes the particular attention item from others made by this application. This identifier was specified when the attention item was created.
commandArgsP | Pointer to command-specific arguments. See the description of each command for a discussion of that command's arguments.
When processing the launch code be aware that your application doesn't have application globals available to it; it is important that anything necessary to draw or otherwise display be available through commandArgsP. ## New AttnLevelType Attention attempts can either be insistent or subtle. Insistent attention attempts make a serious effort to get the user's attention, by both displaying a dialog and possibly by triggering one or more special effects, such as blinking a light, vibrating, or playing a sound. Other alerts are of a less serious nature and shouldn't disrupt the user. Consequently, subtle attention attempts typically make the attention indicator blink and may trigger one or more special effects, but don't display the Attention Manager dialog. The user can then work until a suitable time, at which point they can tap on the indicator to see what needs their attention. Subtle attention attempts might be used for telling the user that they have new e-mail, or perhaps that a holiday or birthday is coming up.
    typedef UInt16 AttnLevelType;
The following table lists the two defined values for AttnLevelType: #####
Constant | Description
--- | ---
kAttnLevelInsistent | An insistent attention attempt. Make a serious effort to get the user's attention by displaying a dialog and optionally triggering one or more special effects.
kAttnLevelSubtle | A subtle attention attempt. Notify the user using special effects, but don't disrupt the user with the dialog if the device is in use.
Note that user preferences for the various special effects can't be set separately for subtle and insistent attention attempts. If your application needs to vary the effects based upon the AttnLevelType, pass a suitable value for the flags parameter in your AttnGetAttention call. ## Attention Manager Constants In addition to the constant values defined specifically for use with AttnCommandType, AttnFlagsType, and AttnLevelType, the Attention Manager defines the following constant types: Error Code Constants Attention Manager Drawing Constants Attention Manager Feature Constants ## Error Code Constants The Attention Manager returns the following error code under the circumstances described below. #####
Constant | Description
--- | ---
attnErrMemory | Returned by AttnGetAttention when there is insufficient memory to perform the requested operation.
## Attention Manager Drawing Constants The following four constants define the on-screen boundaries of the attention indicator: #####
Constant | Value | Description
--- | --- | ---
kAttnIndicatorLeft | 0 | The left-hand edge of the attention indicator.
kAttnIndicatorTop | 0 | The top-most edge of the attention indicator.
kAttnIndicatorWidth | 16 | The width of the attention indicator.
kAttnIndicatorHeight | 16 | The height of the attention indicator.
The following two constants are used when drawing the list view. Applications should use these constants to format the display of information in the Attention Manager's list view. Draw the application's small icon centered within the first kAttnListMaxIconWidth pixels of the drawing bounds. Then draw two lines of text describing the attention, left-justified, starting at kAttnListTextOffset from the left edge of the drawing bounds. #####
Constant | Value | Description
--- | --- | ---
kAttnListMaxIconWidth | 15 | Maximum width of the application's icon. If the icon is narrower than this, it should be drawn centered within this width.
kAttnListTextOffset | 17 | Offset, from the left-hand edge of the drawing bounds, of the textual description of the attention.
## Attention Manager Feature Constants The Attention Manager defines a read-only feature ('attn', 0) that indicates the current user settings and capabilities of the hardware. The upper 16 bits of the feature indicate whether or not the hardware has the capability to perform that sort of alert. The lower 16 bits indicate whether the user has currently enabled that sort of alert. #####
Constant | Value | Description
--- | --- | ---
kAttnFtrCreator | 'attn' | Attention Manager feature creator.
kAttnFtrCapabilities | 0 | Attention Manager feature number.
When working with the value obtained with FtrGet, use the following two constants to separate those bits that contain the user settings from those bits that identify the device's capabilities: #####
Constant | Value | Description
--- | --- | ---
kAttnFlagsUserSettingsMask | kAttnFlagsAllBits | Mask to isolate those bits that contain the user settings.
kAttnFlagsCapabilitiesMask | kAttnFlagsAllBits << 16 | Mask to isolate those bits that contain the device capabilities.
These constants can be used to interpret the device capabilities (kAttnFlagsHas...) and the user settings (kAttnFlagsUserWants...): #####
Constant | Value | Description
--- | --- | ---
kAttnFlagsHasLED | kAttnFlagsLEDBit << 16 | The device has an LED that can be illuminated to indicate an alert.
kAttnFlagsHasSound | kAttnFlagsSoundBit << 16 | The device is capable of playing a sound to indicate an alert.
kAttnFlagsHasVibrate | kAttnFlagsVibrateBit << 16 | The device is capable of vibrating to indicate an alert.
kAttnFlagsHasCustomEffect | kAttnFlagsCustomEffectBit << 16 | Not used.
kAttnFlagsUserWantsLED | kAttnFlagsLEDBit | The user wants the LED illuminated to signal an alert.
kAttnFlagsUserWantsSound | kAttnFlagsSoundBit | The user wants a sound played to signal an alert.
kAttnFlagsUserWantsVibrate | kAttnFlagsVibrateBit | The user wants the device to vibrate to signal an alert.
kAttnFlagsUserWantsCustomEffect | kAttnFlagsCustomEffectBit | Not used.
## Attention Manager Functions ## New AttnDoSpecialEffects #### Purpose Triggers an Attention Manager special effect set. #### Prototype Err AttnDoSpecialEffects (AttnFlagsType flags) #### Parameters #####
-> flags | Specifies the behavior to be exhibited by this special effects request. See AttnFlagsType for the various bits that make up this flag. Note that the behavior is undefined if you set incompatible flags. Supply kAttnFlagsUseUserSettings to have this attention request follow the user's pre-set preferences.
#### Result Returns errNone if no problems were encountered. Returns attnErrMemory if there wasn't enough memory to accommodate the attention request. #### Comments This routine is provided as a convenience for applications that need to trigger special effects. It does the equivalent of one "nag" of an Attention Manager special effect set. #### Compatibility Implemented only if 4.0 New Feature Set is present. ## New AttnForgetIt #### Purpose Provides a way for applications to tell the Attention Manager to forget about an attention item. #### Prototype Boolean AttnForgetIt (UInt16 cardNo, LocalID dbID, UInt32 userData) #### Parameters #####
-> cardNo | Card number on which the application making the request resides.
#####
-> dbID | Database ID of the application making the request.
#####
-> userData | Identifier that distinguishes the attention attempt from others made by the same application. This identifier can be an integer, a pointer, or any other 32-bit value.
#### Result Returns true if the item was removed, false if a matching item was not found. #### Comments You typically call this function after your application has handled a "Go There" event and the user has read about the item. For example, if there is a subtle attention pending that says "you have three e-mail messages waiting" and you go to the e-mail application on your own and read your e-mail, the subtle notification must disappear. AttnForgetIt allows the application to do this. Note that this call can be made when the Attention Manager dialog is on-screen (though presumably that is rare, since the application is probably not doing much at this point). If this call removes a list item, then the Attention Manager may call back into other items to redraw the list. If this call removes the last item when any indicator is present, the indicator disappears. If this call removes the last unread item, but read items remain, the indicator switches from blinking to steady state. #### Compatibility Implemented only if 4.0 New Feature Set is present. ## New AttnGetAttention #### Purpose Requests the user's attention. #### Prototype Err AttnGetAttention (UInt16 cardNo, LocalID dbID, UInt32 userData, AttnCallbackProc *callbackFnP, AttnLevelType level, AttnFlagsType flags, UInt16 nagRateInSeconds, UInt16 nagRepeatLimit) #### Parameters #####
-> cardNo | Card number on which the application making the request resides.
#####
-> dbID | Database ID of the application making the request.
#####
-> userData | Application-specific data that is later passed back to your code through the callback function. If no callback function is specified in the callbackFnP parameter, this data is included in what is passed along with a sysAppLaunchCmdAttention launch code. userData can be an integer, a pointer, or any other 32-bit value as needed by your application. Most applications pass the unique ID or other key for the record which caused the attention request. userData is also used to distinguish a given attention attempt from others made by the same application.
#####
-> callbackFnP | Pointer to the function registered by the application to be called by the Attention Manager when the attention is displayed or removed. See AttnCallbackProc, below, for the callback function's parameters. Supply NULL to instead have a sysAppLaunchCmdAttention launch code sent to the application that made the attention request whenever the attention is displayed or removed.
#####
-> level | Indicates the annoyance level. Pass one of the values defined for AttnLevelType.
#####
-> flags | Behavior override, if necessary, for this attention request. This override allows, for instance, silent alarms or noisy alarms. See AttnFlagsType for the various bits that make up this flag. Note that the behavior is undefined if you set incompatible flags. Supply kAttnFlagsUseUserSettings to have this attention request follow the user's pre-set preferences.
#####
-> nagRateInSeconds | How long to wait before nagging.
#####
-> nagRepeatLimit | How many times to nag, excluding the first attempt.
#### Result Returns errNone if no problems were encountered. Returns attnErrMemory if there wasn't enough memory to accommodate the attention request. #### Comments The combination of cardNo, dbID and userData uniquely identify an attention-getting attempt. If another call is made to AttnGetAttention with identical values for these arguments, an error is reported. To update or delete an existing attention item, pass these same values to AttnUpdate or AttnForgetIt, respectively. In response to AttnGetAttention, the behavior of the operating system or application depends on whether there already are other demands and on the annoyance level passed in the AttnGetAttention call. No other demands, insistent attention request: The Attention Manager puts up a dialog that details the current attempt to get the user's attention. Other demands exist, insistent attention request: The Attention Manager adds a summary of the current attempt to get the user's attention to a list of things that need attention. If the dialog is currently in detail form-which is the case if just one other demand exists-the view is refreshed, changing from detail to list form. In this case, the pen and key event queues are also flushed so that any user events that are happening while the display is changing are explicitly ignored. Two exceptions to this behavior exist: if all existing attentions are subtle, or if all existing insistent attentions were snoozed, the new insistent attention brings up the dialog in detail mode, rather than list mode. Subtle attention request: The Attention Manager starts the attention indicator blinking, and adds the item to its list for later display, unless the dialog is currently being displayed in list mode. In this event, the new subtle attention item simply appears in the list; the indicator does not blink to announce it. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also AttnUpdate ## New AttnGetCounts #### Purpose Returns the number of attention items that are currently pending. #### Prototype UInt16 AttnGetCounts (UInt16 cardNo, LocalID dbID, UInt16 *insistentCountP, UInt16 *subtleCountP) #### Parameters #####
-> cardNo | If this value is zero, counts pending attention items from applications on all cards. Otherwise, counts only pending attention items from applications on the specified card.
#####
-> dbID | If this value is zero, counts pending attention items from all applications. Otherwise, counts only pending attention items from applications with the specified database ID.
#####
<- insistentCountP | Pointer to a 16-bit unsigned value that is filled in with the number of insistent items pending. Pass NULL for this parameter if you don't need to know the number of insistent items that are pending.
#####
<- subtleCountP | Pointer to a 16-bit unsigned value that is filled in with the number of subtle items pending. Pass NULL for this parameter if you don't need to know the number of subtle items that are pending.
#### Result Returns the total number of items, both insistent and subtle, that are currently pending. #### Comments Call this function if you need to exhibit different behavior if attention items are already pending. #### Compatibility Implemented only if 4.0 New Feature Set is present. ## New AttnIndicatorEnable #### Purpose Enables and disables the on-screen attention indicator. #### Prototype void AttnIndicatorEnable (Boolean enableIt) #### Parameters #####
-> enableIt | true to enable the attention indicator, false to disable it.
#### Result Returns nothing. #### Comments This function is used by applications to enable or disable the on-screen attention indicator. The indicator only blinks when all of the following are true: The indicator is enabled. The indicator is being asked to blink by the attention manager. The operating system isn't using the display in such a way as to prevent the attention indicator from showing, such as when the menu bar is being displayed or when a modal dialog is on top of the form. The attention indicator is enabled by default. If your application controls the upper portion of the screen and needs to prevent the attention indicator from being displayed, call AttnIndicatorEnable and pass it a value of false. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also AttnIndicatorEnabled ## New AttnIndicatorEnabled #### Purpose Returns whether the on-screen attention indicator is currently enabled. #### Prototype Boolean AttnIndicatorEnabled (void) #### Parameters #####
None.
#### Result Returns true if the on-screen attention indicator is currently enabled, false otherwise. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also AttnIndicatorEnable ## New AttnIterate #### Purpose Instructs the Attention Manager to check each attention item currently pending and, for those that match the specified card number and database ID, invoke the item's callback routine. If a callback routine was not specified in the request, the sysAppLaunchCmdAttention launch code is sent to the application that made the attention request. #### Prototype void AttnIterate (UInt16 cardNo, LocalID dbID, UInt32 iterationData) #### Parameters #####
-> cardNo | Card number on which the application that made the request resides.
#####
-> dbID | Database ID of the application that made the request.
#####
-> iterationData | Any necessary data that the application may need in order to process the callback or launch code. See the description of the AttnCallbackProc function for more information on this parameter.
#### Result Returns nothing. #### Comments This function iterates through all of the attention requests made by this application and uses the callback or launch code for each to inform the application about the attention request. When an application receives a sysAppLaunchCmdSyncNotify launch code, signifying that a HotSync occurred that affected that application's databases, the application typically calls AttnIterate so it can remove attention requests for records that may have been removed during the HotSync. Applications can also call AttnGetAttention after a HotSync, if necessary. Note that you can call AttnForgetIt inside the iteration since it only marks the record for deletion and thus doesn't confuse the iteration. #### Compatibility Implemented only if 4.0 New Feature Set is present. ## New AttnListOpen #### Purpose Displays the attention dialog in list mode and, after the user has dismissed it, acts accordingly based on how it was dismissed. #### Prototype void AttnListOpen (void) #### Parameters #####
None.
#### Result Returns nothing. #### Comments This function allows applications that do not provide the blinking attention indicator to open the list, if necessary. #### Compatibility Implemented only if 4.0 New Feature Set is present. ## New AttnUpdate #### Purpose Updates one or more aspects of a specified attention item. #### Prototype Boolean AttnUpdate (UInt16 cardNo, LocalID dbID, UInt32 userData, AttnCallbackProc *callbackFnP, AttnFlagsType *flagsP, UInt16 *nagRateInSecondsP, UInt16 *nagRepeatLimitP) #### Parameters #####
-> cardNo | Card number on which the application that made the request resides.
#####
-> dbID | Database ID of the application that made the request.
#####
-> userData | Application-specific data that is passed back to your code through the callback function. If no callback function is specified in the callbackFnP parameter, this data is included in what is passed along with a sysAppLaunchCmdAttention launch code. userData can be an integer, a pointer, or any other 32-bit value. Most applications pass the unique ID or other key for the record which caused the attention request. The value of the userData parameter is also used to distinguish a given attention attempt from others made by the same application.
#####
-> callbackFnP | Registers a new function to be called by the Attention Manager when the attention is displayed or removed. The function to which this parameter points should conform to AttnCallbackProc. Supply NULL to instead have a sysAppLaunchCmdAttention launch code sent to the application that made the attention request whenever the attention is displayed or removed.
IMPORTANT: Because NULL indicates that a launch code should be sent whenever the callback would otherwise be invoked, it isn't used in this instance to leave the original setting for the callbackFnP parameter intact. The value supplied for this parameter always overwrites the value supplied in the original attention request. #####
-> flagsP | Pointer to a set of flags that can be used to override user-specified attention behavior; for instance, to force silent or noisy alarms. See AttnFlagsType for the various bits that make up this flag, and note that the behavior is undefined if you set incompatible flags. Pass NULL to leave the current flag settings unchanged.
#####
-> nagRateInSecondsP | Pointer to the length of time to wait before nagging. Pass NULL to leave the "nag rate" unchanged.
#####
-> nagRepeatLimitP | Pointer to the maximum number of times the user should be nagged. Pass NULL to leave the nag repeat limit unchanged.
#### Result Returns true if the update was successful, false if no matching attention item was found. #### Comments This call may result in the callback function being called to re-display the item. If no callback function is specified, the sysAppLaunchCmdAttention launch code is instead sent to your application. It may also result in callbacks to other pending attention requests. You call AttnUpdate to tell the Attention Manager to update, forcing it to call into all of its clients to redraw. This provides a way for an application to update the text of an attention item without tearing down and re-opening the Attention Manager dialog. For example, AttnUpdate could be used to update an existing email notification to say "You have three new email messages" when additional messages are received. Although AttnUpdate may cause a given attention item to redraw, it does not cause that item's sound to play, and the item is not moved to the top of the list. If you want this to happen, call AttnForgetIt followed by AttnGetAttention. #### Compatibility Implemented only if 4.0 New Feature Set is present. #### See Also AttnGetAttention ## Application-Defined Functions ## New AttnCallbackProc #### Purpose Provides a function prototype to be used by callback functions supplied to AttnGetAttention and AttnUpdate. The supplied function is invoked by the Attention Manager whenever the attention is displayed or removed. #### Prototype typedef Err AttnCallbackProc (AttnCommandType command, UInt32 userData, AttnCommandArgsType *commandArgsP) #### Parameters #####
-> command | Indicates what the callback function is being requested to do. The complete list of possible commands are described in the definition of AttnCommandType.
#####
-> userData | Identifier that distinguishes the particular attention item from others made by this application. This identifier was specified when the attention item was created.
#####
-> commandArgsP | Pointer to command-specific arguments. See the description of each command for a discussion of that command's arguments.
#### Result The callback function should return errNone if it correctly handled the command, or an appropriate error code otherwise. If the callback function returns an error code other than errNone, the attention is removed from the list of active attention items. #### Comments For a given attention item, the Attention Manager calls back to the code resource that created that item whenever the Attention Manager needs the resource to draw the attention dialog contents or whenever it needs to inform the code resource of activity relating to the attention item. The Attention Manager calls back using one of two mechanisms: If a callback routine has been specified for a given attention item, the Attention Manager invokes the specified routine. This callback routine doesn't have application globals available to it, so it is important that anything necessary to draw or otherwise display be available through commandArgsP. A callback routine is typically used by libraries and system extensions. If a callback routine has not been specified for a given attention item, the Attention Manager instead sends a sysAppLaunchCmdAttention launch code to the application that registered the attention item. Accompanying that launch code is an AttnLaunchCodeArgsType structure containing the three parameters documented above. Applications typically use the launch-code mechanism due to the restrictions that are placed on callback routines. IMPORTANT: It is your responsibility to ensure that the callback procedure is still in the same place when it gets called, dealing with the possibility that the code resource might be unlocked and moved in memory, and with the possibility that the database containing the code resource might be deleted. For the most part, these problems don't exist when using launch codes. #### Compatibility Invoked only if 4.0 New Feature Set is present. |