Legacy Document

Inside Macintosh: Processes

Chapter 5 - Notification Manager / Using the Notification Manager

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 type NMRec. 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 the NMRec 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 fields qType, nmMark, nmIcon, nmSound, nmStr, nmResp, and nmRefCon. The remaining fields of this record are used internally by the Notification Manager or are reserved for use by Apple Computer, Inc.

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 of nmMark is 1, the mark appears next to the name of the calling application. If the value of nmMark 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 is NIL, 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 of nmSound is NIL, no sound is produced. If the value of nmSound 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 is NIL, 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 is NIL, no response procedure is executed when the notification is posted. If the value of nmResp 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.

Listing 5-1 illustrates how to set up a notification record. In this listing, gMyNotification is a global variable of type NMRec and gText is a global variable of type Str255.

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.