This chapter provides reference documentation for the Attention Manager. It is divided into the following sections:
Attention Manager Structures and Types
Attention Manager Constants
Attention Manager Launch Codes
Attention Manager Functions and Macros
The header file AttentionMgr.h
declares the API that this chapter describes.
For more information about the attention manager, see Chapter 1, "Attentions and Alarms."
Attention Manager Structures and Types
AttnCommandArgsDrawDetailTag Struct
Purpose
When kAttnCommandDrawDetail
is passed to the application as a parameter accompanying the sysAppLaunchCmdAttention
launch code, the application needs to draw the detailed contents of the attention slip. The AttnCommandArgsDrawDetailTag
structure accompanies the kAttnCommandDrawDetail
command, and provides the information needed to draw the contents of that slip.
Declared In
AttentionMgr.h
Prototype
struct AttnCommandArgsDrawDetailTag { RectangleType bounds; Boolean firstTime; uint8_t padding1; uint16_t padding2; AttnFlagsType flags; } drawDetail;
Fields
-
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
- Not used in Palm OS Cobalt.
-
padding1
- Padding bytes.
-
padding2
- Padding bytes.
-
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
, andkAttnFlagsCustomEffectBit
(described under "AttnFlagsType") to interpret the contents of this field.
AttnCommandArgsDrawListTag Struct
Purpose
When kAttnCommandDrawList
is passed to the application as a parameter accompanying the sysAppLaunchCmdAttention
launch code, the application needs to draw the appropriate list item in the attention slip. The AttnCommandArgsDrawListTag
structure accompanies the kAttnCommandDrawList
command, and provides the information needed to draw the contents of that slip.
Declared In
AttentionMgr.h
Prototype
struct AttnCommandArgsDrawListTag { RectangleType bounds; Boolean firstTime; uint8_t padding1; uint16_t padding2; AttnFlagsType flags; Boolean selected; uint8_t padding3; uint16_t padding4; } drawList;
Fields
-
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
- Not used in Palm OS Cobalt.
-
padding1
- Padding bytes.
-
padding2
- Padding bytes.
-
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
, andkAttnFlagsCustomEffectBit
(described under "AttnFlagsType") to interpret the contents of this field. -
selected
- Not used in Palm OS Cobalt.
-
padding3
- Padding bytes.
-
padding4
- Padding bytes.
AttnCommandArgsGotItTag Struct
Purpose
When kAttnCommandGotIt
is passed to the application as a parameter accompanying the sysAppLaunchCmdAttention
launch code, it is accompanied by an AttnCommandArgsGotItTag
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()
.
Declared In
AttentionMgr.h
Prototype
struct AttnCommandArgsGotItTag { Boolean dismissedByUser; } gotIt;
Fields
-
dismissedByUser
-
true
indicates that the user dismissed the attention.false
indicates that thekAttnCommandGotIt
command was generated by a call toAttnForgetIt()
.
AttnCommandArgsIterateTag Struct
Purpose
- When
kAttnCommandIterate
is passed to the application as a parameter accompanying thesysAppLaunchCmdAttention
launch code, it is accompanied by anAttnCommandArgsIterateTag
structure. This structure contains any necessary data that the application may need in order to process the launch code.
Declared In
AttentionMgr.h
Prototype
struct AttnCommandArgsIterateTag { uint32_t iterationData; } iterate;
Fields
-
iterationData
- Any necessary data that the application may need in order to process the launch code. The value of this field is that which was originally passed to
AttnIterate()
.
AttnCommandArgsType Struct
Purpose
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:
Declared In
AttentionMgr.h
Prototype
typedef union AttnCommandArgsTag { struct AttnCommandArgsDrawDetailTag { ... } drawDetail; struct AttnCommandArgsDrawListTag { ... } drawList; struct AttnCommandArgsGotItTag { ... } gotIt; struct AttnCommandArgsIterateTag { ... } iterate; } AttnCommandArgsType
Fields
-
drawDetail
- When
kAttnCommandDrawDetail
is passed to the application as a parameter accompanying thesysAppLaunchCmdAttention
launch code, the application needs to draw the detailed contents of the attention slip. TheAttnCommandArgsDrawDetailTag
structure accompanies thekAttnCommandDrawDetail
command, and provides the information needed to draw the contents of that slip. -
drawList
- When
kAttnCommandDrawList
is passed to the application as a parameter accompanying thesysAppLaunchCmdAttention
launch code, the application needs to draw the appropriate list item in the attention slip. TheAttnCommandArgsDrawListTag
structure accompanies thekAttnCommandDrawList
command, and provides the information needed to draw the contents of that slip. -
gotIt
- When
kAttnCommandGotIt
is passed to the application as a parameter accompanying thesysAppLaunchCmdAttention
launch code, it is accompanied by anAttnCommandArgsGotItTag
structure. This structure indicates whether thekAttnCommandGotIt
command was generated because the user dismissed the attention, or whether the system is simply informing your application thatAttnForgetIt()
was called. Your application normally ignores the latter case if your application made the call toAttnForgetIt()
. -
iterate
- When
kAttnCommandIterate
is passed to the application as a parameter accompanying thesysAppLaunchCmdAttention
launch code, it is accompanied by anAttnCommandArgsIterateTag
structure. This structure contains any necessary data that the application may need in order to process the launch code.
AttnCommandType Typedef
Purpose
The AttnCommandType
typedef specifies the set of possible commands that can be sent to the application requesting the user's attention, as one of the arguments that accompanies a sysAppLaunchCmdAttention
launch code.
Declared In
AttentionMgr.h
Prototype
typedef uint16_t AttnCommandType
Comments
See "Commands" for the set of values that AttnCommandType
can assume.
AttnFlagsType Typedef
Purpose
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 as part of the structure passed with the sysAppLaunchCmdAttention
launch code.
Declared In
AttentionMgr.h
Prototype
typedef uint32_t AttnFlagsType
Comments
See "Attention Flags" and "Attention Override Flags" for the set of values that this type can assume. Note that more bits may be defined if necessary to accommodate additional hardware.
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.
AttnLaunchCodeArgsType Struct
Purpose
If the Attention Manager needs your code to draw the details of your attention in the attention slip 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:
Declared In
AttentionMgr.h
Prototype
typedef struct { AttnCommandType command; uint16_t padding; uint32_t userData; AttnCommandArgsType *commandArgsP; } AttnLaunchCodeArgsType
Fields
-
command
- Indicates what your code is being requested to do. The complete list of possible commands are described in the definition of
AttnCommandType
. -
padding
- Padding bytes.
-
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.
Comments
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
.
AttnLevelType Typedef
Purpose
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 slip 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 present the attention indicator and may trigger one or more special effects, but don't display the Attention Manager slip. 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.
Declared In
AttentionMgr.h
Prototype
typedef uint16_t AttnLevelType
Comments
"Attention Levels" defines the set of values that this type can assume.
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.
AttnNotifyDetailsType Struct
Purpose
Structure that accompanied an obsolete Attention Manager notification. Not used in Palm OS Cobalt.
Declared In
AttentionMgr.h
Prototype
typedef struct { AttnFlagsType flags; } AttnNotifyDetailsType
Attention Manager Constants
Attention Manager Error Codes
Purpose
Error codes returned by the various Attention Manager functions.
Declared In
AttentionMgr.h
Constants
-
#define attnErrMemory (attnErrorClass | 1)
- Returned by
AttnGetAttention()
when there is insufficient memory to perform the requested operation. -
#define attnErrItemNotFound (attnErrorClass | 2)
- The specified attention item is not one of the items being handled by the Attention Manager. It may have been deleted.
Drawing Constants
Purpose
Define the on-screen boundaries of the attention indicator that is displayed when the status bar is not visible and the Attention Manager needs to get the user's attention, and specify how an application should format the list view.
Declared In
AttentionMgr.h
Constants
-
#define kAttnIndicatorHeight 15
- The height of the attention indicator.
-
#define kAttnIndicatorLeft 0
- The left-hand edge of the attention indicator.
-
#define kAttnIndicatorTop 0
- The top-most edge of the attention indicator.
-
#define kAttnIndicatorWidth 16
- The width of the attention indicator.
-
#define kAttnListMaxIconWidth 15
- Maximum width of the application's icon. If the icon is narrower than this, it should be drawn centered within this width.
-
#define kAttnListTextOffset 17
- Offset, from the left-hand edge of the drawing bounds, of the textual description of the attention.
Comments
The kAttnList...
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.
Feature Constants
Purpose
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.
Declared In
AtentionMgr.h
Constants
-
#define kAttnFtrCapabilities 0
- Attention Manager feature number.
-
#define kAttnFtrCreator 'attn'
- Attention Manager feature creator.
See Also
Feature Masks
Purpose
When working with the value obtained with FtrGet
, use these constants to separate those bits that contain the user settings from those bits that identify the device's capabilities.
Declared In
AttentionMgr.h
Constants
-
#define kAttnFlagsCapabilitiesMask (kAttnFlagsAllBits<<16)
- Mask to isolate those bits that contain the device capabilities.
-
#define kAttnFlagsUserSettingsMask (kAttnFlagsAllBits)
- Mask to isolate those bits that contain the user settings.
See Also
Feature Constants, Feature Flags
Feature Flags
Purpose
These constants can be used to interpret the device capabilities (kAttnFlagsHas...
) and the user settings (kAttnFlagsUserWants...
), obtained from FtrGet (see "Feature Constants"
Declared In
AttentionMgr.h
Constants
-
#define kAttnFlagsHasCustomEffect (kAttnFlagsCustomEffectBit<<16)
- Not used.
-
#define kAttnFlagsHasLED (kAttnFlagsLEDBit<<16)
- The device has an LED that can be illuminated to indicate an alert.
-
#define kAttnFlagsHasSound (kAttnFlagsSoundBit<<16)
- The device is capable of playing a sound to indicate an alert.
-
#define kAttnFlagsHasVibrate (kAttnFlagsVibrateBit<<16)
- The device is capable of vibrating to indicate an alert.
-
#define kAttnFlagsUserWantsCustomEffect (kAttnFlagsCustomEffectBit)
- Not used.
-
#define kAttnFlagsUserWantsLED (kAttnFlagsLEDBit)
- The user wants the LED illuminated to signal an alert.
-
#define kAttnFlagsUserWantsSound (kAttnFlagsSoundBit)
- The user wants a sound played to signal an alert.
-
#define kAttnFlagsUserWantsVibrate (kAttnFlagsVibrateBit)
- The user wants the device to vibrate to signal an alert.
See Also
Feature Constants, Feature Masks
Attention Flags
Purpose
Specify what means the device should or should not use to get the user's attention
Declared In
AttentionMgr.h
Constants
-
#define kAttnFlagsAllBits ((AttnFlagsType)0xFFFF)
- Uses all available means to get the user's attention.
-
#define kAttnFlagsCustomEffectBit ((AttnFlagsType)0x0008)
- Triggers an application-specific custom effect.
-
#define kAttnFlagsLEDBit ((AttnFlagsType)0x0002)
- Blinks an LED, if the device is so equipped.
-
#define kAttnFlagsSoundBit ((AttnFlagsType)0x0001)
- Plays a sound.
-
#define kAttnFlagsVibrateBit ((AttnFlagsType)0x0004)
- Triggers vibration, if the device is so equipped.
-
#define kAttnFlagsUseUserSettings ((AttnFlagsType)0x00000000)
- System-wide preferences determine what means are used to get the user's attention.
See Also
Attention Override Flags
Purpose
Override the user's settings and force or prevent specific behaviors.
Declared In
AttentionMgr.h
Constants
-
#define kAttnFlagsAlwaysCustomEffect (kAttnFlagsCustomEffectBit)
- Trigger an application-specific custom effect, regardless of the user's settings.
-
#define kAttnFlagsAlwaysLED (kAttnFlagsLEDBit)
- Blink an LED, if the device is so equipped, regardless of the user's settings.
-
#define kAttnFlagsAlwaysSound (kAttnFlagsSoundBit)
- Play a sound, regardless of the user's settings.
-
#define kAttnFlagsAlwaysVibrate (kAttnFlagsVibrateBit)
- Vibrate, if the device is so equipped, regardless of the user's settings.
-
#define kAttnFlagsEverything (kAttnFlagsAllBits)
- Use every available means to get the user's attention, regardless of the user's settings.
-
#define kAttnFlagsNoCustomEffect (kAttnFlagsCustomEffectBit<<16)
- Prevent triggering of the application-specific custom effect, regardless of the user's settings.
-
#define kAttnFlagsNoLED (kAttnFlagsLEDBit<<16)
- Prevent the LED from flashing, regardless of the user's settings.
-
#define kAttnFlagsNoSound (kAttnFlagsSoundBit<<16)
- Prevent a sound from being played, regardless of the user's settings.
-
#define kAttnFlagsNothing (kAttnFlagsAllBits<<16)
- Disable all attention-getting mechanisms, regardless of the user's settings.
-
#define kAttnFlagsNoVibrate (kAttnFlagsVibrateBit<<16)
- Prevent vibration, regardless of the user's settings.
Comments
These constants can be used in combination. For example, to disable both sound and the LED, use kAttnFlagsNoSound | kAttnFlagsNoLED
.
See Also
Commands
Purpose
The set of possible commands that can be sent to the application requesting the user's attention, as one of the arguments that accompanies a sysAppLaunchCmdAttention
launch code.
Declared In
AttentionMgr.h
Constants
-
#define kAttnCommandCustomEffect ((AttnCommandType)4)
- 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 callAttnGetAttention
, which most applications won't do. -
#define kAttnCommandDrawDetail ((AttnCommandType)1)
- ndicates that the application needs to draw the detailed contents of the attention slip. The command arguments parameter points to a structure of type
AttnCommandArgsDrawDetailTag
. -
#define kAttnCommandDrawList ((AttnCommandType)2)
- Indicates that the application needs to draw the appropriate list item in the attention slip. The command arguments parameter points to a structure of type
AttnCommandArgsDrawListTag
. -
#define kAttnCommandGoThere ((AttnCommandType)5)
- Tells the application to navigate to the item. The command arguments parameter is
NULL
. An application commonly callsSysAppLaunch()
upon receipt of this command to have itself launched. -
#define kAttnCommandGotIt ((AttnCommandType)6)
- Tells the application that the user is dismissing the item. The command arguments parameter points to a structure of type
AttnCommandArgsGotItTag
. The application may choose to clean up memory at this point. -
#define kAttnCommandIterate ((AttnCommandType)8)
- 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
AttnCommandArgsIterateTag
. -
#define kAttnCommandPlaySound ((AttnCommandType)3)
- Indicates that the application needs to play a sound. The command arguments parameter is
NULL
. -
#define kAttnCommandSnooze ((AttnCommandType)7)
- 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.
See Also
Attention Levels
Purpose
The lengths to which the Attention Manager should go in order to get the user's attention.
Declared In
AttentionMgr.h
Constants
-
#define kAttnLevelInsistent ((AttnLevelType)0)
- An insistent attention attempt. Make a serious effort to get the user's attention by displaying a slip and optionally triggering one or more special effects.
-
#define kAttnLevelSubtle ((AttnLevelType)1)
- A subtle attention attempt. Notify the user using special effects, but don't disrupt the user with the slip if the device is in use.
See Also
Attention Manager Launch Codes
sysAppLaunchCmdAttention
Purpose
Sent when the Attention Manager needs your application to draw the details of your attention in the attention slip or perform some other application-specific function.
Declared In
CmnLaunchCodes.h
Prototype
#define sysAppLaunchCmdAttention 60
Parameters
The launch code's parameter block pointer references a AttnLaunchCodeArgsType
structure.
Attention Manager Functions and Macros
AttnDoSpecialEffects Function
Purpose
Triggers an Attention Manager special effect set.
Declared In
AttentionMgr.h
Prototype
status_t 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. SupplykAttnFlagsUseUserSettings
to have this attention request follow the user's pre-set preferences.
Returns
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.
AttnForgetIt Function
Purpose
Provides a way for applications to tell the Attention Manager to forget about an attention item.
Declared In
AttentionMgr.h
Prototype
Boolean AttnForgetIt ( DatabaseIDdbID
, uint32_tuserData
)
Parameters
-
→ 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.
Returns
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 slip 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.
AttnForgetItV40 Function
Purpose
Provides a way for applications to tell the Attention Manager to forget about an attention item.
NOTE: This function is provided for compatibility purposes only; applications should use
AttnForgetIt()
instead.
Declared In
AttentionMgr.h
Prototype
Boolean AttnForgetItV40 ( uint16_tcardNo
, LocalIDdbID
, uint32_tuserData
)
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.
Returns
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. AttnForgetItV40()
allows the application to do this.
Note that this call can be made when the Attention Manager slip 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.
Compatibility
This function is provided for compatibility purposes only; applications should use AttnForgetIt()
—which omits the obsolete cardNo
parameter—instead.
AttnGetAttention Function
Purpose
Requests the user's attention.
Declared In
AttentionMgr.h
Prototype
status_t AttnGetAttention ( DatabaseIDdbID
, uint32_tuserData
, AttnLevelTypelevel
, AttnFlagsTypeflags
, uint16_tnagRateInSeconds
, uint16_tnagRepeatLimit
)
Parameters
-
→ dbID
- Database ID of the application making the request.
-
→ userData
- Application-specific data that 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. -
→ 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. SupplykAttnFlagsUseUserSettings
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.
Returns
Returns errNone
if no problems were encountered. Returns attnErrMemory
if there wasn't enough memory to accommodate the attention request.
Comments
The combination of 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 slip 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 slip 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.
- Subtle attention request:
The Attention Manager adds the item to its list for later display and presents the attention indicator, unless the slip is currently being displayed. In this event, the new subtle attention item simply appears in the list (switching to list mode if necessary).
See Also
AttnGetAttentionV40 Function
Purpose
Requests the user's attention.
NOTE: This function is provided for compatibility purposes only; applications should use
AttnGetAttention()
instead.
Declared In
AttentionMgr.h
Prototype
status_t AttnGetAttentionV40 ( uint16_tcardNo
, LocalIDdbID
, uint32_tuserData
, AttnLevelTypelevel
, AttnFlagsTypeflags
, uint16_tnagRateInSeconds
, uint16_tnagRepeatLimit
)
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 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. -
→ 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. SupplykAttnFlagsUseUserSettings
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.
Returns
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 slip 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 slip 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.
- Subtle attention request:
The Attention Manager presents the attention indicator, and adds the item to its list for later display, unless the slip is currently being displayed in list mode. In this event, the new subtle attention item simply appears in the list.
Compatibility
This function is provided for compatibility purposes only; applications should use AttnGetAttention()
—which omits the obsolete cardNo
parameter—instead.
See Also
AttnGetCounts Function
Purpose
Returns the number of attention items that are currently pending.
Declared In
AttentionMgr.h
Prototype
uint16_t AttnGetCounts ( DatabaseIDdbID
, uint16_t*insistentCountP
, uint16_t*subtleCountP
)
Parameters
-
→ 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.
Returns
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.
AttnGetCountsV40 Function
Purpose
Returns the number of attention items that are currently pending.
NOTE: This function is provided for compatibility purposes only; applications should use
AttnGetCounts()
instead.
Declared In
AttentionMgr.h
Prototype
uint16_t AttnGetCountsV40 ( uint16_tcardNo
, LocalIDdbID
, uint16_t*insistentCountP
, uint16_t*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.
Returns
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
This function is provided for compatibility purposes only; applications should use AttnGetCounts()
—which omits the obsolete cardNo
parameter—instead.
AttnIndicatorEnable Function
Purpose
Enables and disables the on-screen attention indicator displayed when the status bar is not visible.
Declared In
AttentionMgr.h
Prototype
void AttnIndicatorEnable (
Boolean enableIt
)
Parameters
Returns
Comments
This function is used by applications to enable or disable the on-screen attention indicator that appears in the upper left corner of the screen when the status bar is not visible. The indicator appears here only when all of the following are true:
- The status bar is not visible.
- The indicator is enabled.
- The Attention Manager needs to get the user's attention.
- 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
.
This function has no effect on the attention indicator that is displayed in the status bar.
See Also
AttnIndicatorEnabled Function
Purpose
Returns whether the on-screen attention indicator displayed when the status bar is not visible is currently enabled.
Declared In
AttentionMgr.h
Prototype
Boolean AttnIndicatorEnabled ( void )
Parameters
Returns
Returns true
if the on-screen attention indicator (displayed in the upper left hand corner of the screen when the status bar is not visible) is currently enabled, false
otherwise.
See Also
AttnIterate Function
Purpose
Instructs the Attention Manager to check each attention item currently pending and, for those that match the specified database ID, send the sysAppLaunchCmdAttention
launch code to the application that made the attention request.
Declared In
AttentionMgr.h
Prototype
void AttnIterate ( DatabaseIDdbID
, uint32_titerationData
)
Parameters
-
→ dbID
- Database ID of the application that made the request.
-
→ iterationData
- Any necessary data that the application may need in order to process the launch code.
Returns
Comments
This function iterates through all of the attention requests made by this application and uses the 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.
AttnIterateV40 Function
Purpose
Instructs the Attention Manager to check each attention item currently pending and, for those that match the specified card number and database ID, send the sysAppLaunchCmdAttention
launch code to the application that made the attention request.
NOTE: This function is provided for compatibility purposes only; applications should use
AttnIterate()
instead.
Declared In
AttentionMgr.h
Prototype
void AttnIterateV40 ( uint16_tcardNo
, LocalIDdbID
, uint32_titerationData
)
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 launch code.
Returns
Comments
This function iterates through all of the attention requests made by this application and uses the 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
This function is provided for compatibility purposes only; applications should use AttnIterate()
—which omits the obsolete cardNo
parameter—instead.
AttnListOpen Function
Purpose
Displays the attention slip in list mode and, after the user has dismissed it, acts accordingly based on how it was dismissed.
Declared In
AttentionMgr.h
Prototype
void AttnListOpen ( void )
Parameters
Returns
Comments
This function allows applications that do not provide the on screen attention indicator (the one that is displayed when the status bar is not visible) to open the list, if necessary.
AttnUpdate Function
Purpose
Updates one or more aspects of a specified attention item.
Declared In
AttentionMgr.h
Prototype
Boolean AttnUpdate ( DatabaseIDdbID
, uint32_tuserData
, AttnFlagsType*flagsP
, uint16_t*nagRateInSecondsP
, uint16_t*nagRepeatLimitP
)
Parameters
-
→ dbID
- Database ID of the application that made the request.
-
→ userData
- Application-specific data that 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 theuserData
parameter is also used to distinguish a given attention attempt from others made by the same application. -
→ 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. PassNULL
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.
Returns
Returns true
if the update was successful, false
if no matching attention item was found.
Comments
This call may result in the sending of the sysAppLaunchCmdAttention
launch code to your application. It may also result in this launch code being sent 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 slip. 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 rerun the special effects (if any) that occurred when that attention item was added. If you want to trigger Attention Manager effects for a particular item, call AttnForgetIt()
followed by AttnGetAttention()
.
See Also
AttnUpdateV40 Function
Purpose
Updates one or more aspects of a specified attention item.
NOTE: This function is provided for compatibility purposes only; applications should use
AttnUpdate()
instead.
Declared In
AttentionMgr.h
Prototype
Boolean AttnUpdateV40 ( uint16_tcardNo
, LocalIDdbID
, uint32_tuserData
, AttnFlagsType*flagsP
, uint16_t*nagRateInSecondsP
, uint16_t*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 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 theuserData
parameter is also used to distinguish a given attention attempt from others made by the same application. -
→ 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. PassNULL
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.
Returns
Returns true
if the update was successful, false
if no matching attention item was found.
Comments
This call may result in the sending of the sysAppLaunchCmdAttention
launch code to your application. It may also result in this launch code being sent 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 slip. 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 rerun the special effects (if any) that occurred when that attention item was added. If you want to trigger Attention Manager effects for a particular item, call AttnForgetIt()
followed by AttnGetAttention()
.
Compatibility
This function is provided for compatibility purposes only; applications should use AttnUpdate()
—which omits the obsolete cardNo
parameter—instead.