Important: The information in this document is obsolete and should not be used for new development.
Creating a Notification Request
Information describing each notification request is contained in the notification queue, which is a standard operating-system queue (as described in the chapter "Queue Utilities" in Inside Macintosh: Operating System Utilities). Each entry in the notification queue is a notification record--a static and nonrelocatable record of typeNMRec
. When installing a request in the notification queue, your application must supply a pointer to a notification record that indicates the type of notification you desire. Here is theNMRec
data structure:
TYPE NMRec = RECORD qLink: QElemPtr; {next queue entry} qType: Integer; {queue type} nmFlags: Integer; {reserved} nmPrivate: LongInt; {reserved} nmReserved: Integer; {reserved} nmMark: Integer; {item to mark in menu} nmIcon: Handle; {handle to icon} nmSound: Handle; {handle to sound resource} nmStr: StringPtr; {string to appear in alert box} nmResp: ProcPtr; {pointer to response procedure} nmRefCon: LongInt; {for application's use} END;To set up a notification request, you need to fill in the fieldsqType
,nmMark
,nmIcon
,nmSound
,nmStr
,nmResp
, andnmRefCon
. The remaining fields of this record are used internally by the Notification Manager or are reserved for use by Apple Computer, Inc.
Listing 5-1 illustrates how to set up a notification record. In this listing,
Field Description
qLink
- Points to the next element in the queue. This field is used internally by the Notification Manager.
qType
- Indicates the type of queue. You should set this field to the value
ORD(nmType)
, which is 8.nmFlags
- Reserved for use by Apple Computer, Inc.
nmPrivate
- Reserved for use by Apple Computer, Inc.
nmReserved
- Reserved for use by Apple Computer, Inc.
nmMark
- Indicates whether to place a diamond-shaped mark next to the name of the application in the Application menu. If the value of
nmMark
is 0, no such mark appears. If the value ofnmMark
is 1, the mark appears next to the name of the calling application. If the value ofnmMark
is neither 0 nor 1, it is interpreted as the reference number of a desk accessory. An application should pass 1, a desk accessory should pass its own reference number, and a driver or a detached background task (such as a VBL task or Time Manager task) should pass 0.nmIcon
- Contains a handle to a small icon that is to blink periodically in the menu bar. If the value of
nmIcon
isNIL
, no icon appears in the menu bar. This handle must be valid at the time that the notification occurs; it does not need to be locked, but it must be nonpurgeable.nmSound
- Contains a handle to a sound resource to be played with
SndPlay
. If the value ofnmSound
isNIL
, no sound is produced. If the value ofnmSound
is -1, then the system alert sound plays. This handle does not need to be locked, but it must be nonpurgeable.nmStr
- Points to a string that appears in the alert box. If the value of
nmStr
isNIL
, no alert box appears. Because the Notification Manager does not make a copy of this string, your application should not release this memory until it removes the notification request.nmResp
- Points to a response procedure. If the value of
nmResp
isNIL
, no response procedure is executed when the notification is posted. If the value ofnmResp
is -1, then a predefined procedure removes the notification request immediately after it has completed.nmRefCon
- A long integer available for your application's own use.
gMyNotification
is a global variable of typeNMRec
andgText
is a global variable of typeStr255
.Listing 5-1 Setting up a notification record
VAR myResNum: Integer; {resource ID of small icon} myResHand: Handle; {handle to small icon resource} BEGIN myResNum := 1234; {resource ID in resource fork} myResHand := GetResource('SICN', myResNum); {get icon from resource fork} gText := 'Sample Alert Box'; {set message for alert box} WITH gMyNotification DO BEGIN qType := ORD(nmType); {set queue type} nmMark := 1; {put mark in Application menu} nmIcon := myResHand; {blinking icon} nmSound := Handle(-1); {play system alert sound} nmStr := @gText; {display alert box} nmResp := NIL; {no response procedure} nmRefCon := 0; {not needed here} END; END;This notification record requests all three types of notification--polite (blinking small icon), audible (system alert sound), and alert (alert box). In addition, the diamond appears in front of the application's name in the Application menu. In this case, the small icon has resource ID 1234 of type'SICN'
in the application's resource fork.