TweetFollow Us on Twitter

MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
2001 K. J. Bricknell
Go to Contents Go to Program Listing



Notification From Applications in the Background

The Need for the Notification Manager

Applications running in the background sometimes need to communicate information to the user, and need to be certain that the user has actually received that information. The Notification Manager provides for this requirement.

Elements of a Notification

The Notification Manager creates notifications. A notification comprises one or more of five possible elements, which occur in the following sequence:

  • A diamond mark appears against the name of the target application in the Mac OS 8/9 Application menu.

    This mark is intended to prompt the user to switch the marked application to the foreground. The diamond mark only appears while the application posting the notification remains in the background. It is replaced by the familiar check mark when that application is brought to the foreground.

  • The Application menu title begins alternating between the target application's icon and the foreground application's icon, or the Apple menu title begins alternating between the target application's icon and the Apple icon.

    The location of the icon alternation in the menu bar is determined by the posting application's mark (if any). If the application posting the notification is marked by either a diamond mark or a check mark in the Mac OS 8/9 Application menu, the Application menu title alternates; otherwise the Mac OS 8/9 Apple menu title alternates.

    Note that several applications might post notifications, so there might be a series of alternating icons.

  • On Mac OS 8/9, the Sound Manager plays a sound.

    The application posting the notification can request that the system alert sound be used or it can specify its own sound by passing the Notification Manager a handle to a 'snd ' resource.

  • On Mac OS 8.6, a modal alert appears, and the user dismisses it (by clicking on the Cancel button). On Mac OS 9.x and Mac OS X, a floating window appears, allowing the user to continue working in any running application without first dismissing the notification window. On Mac OS X, a system movable modal alert, which remains in front of all other windows, appears.

    The application posting the notification specifies the text for the modal alert.

  • A response function, if specified, executes.

    A response function can be used to remove the notification request from the notification queue (see below) or to perform other processing. For example, it can be used to set a global variable to record that the notification was received.

Notifications in Action


The Notification Manager is automatically initialised at system startup.

To present the user with a notification, you create a notification request and install it into the notification queue, which is a standard Macintosh queue. The Notification Manager presents the notification to the user at the earliest possible time.

When appropriate (that is, in the response function or when your application returns to the foreground), you can remove the notification request from the notification queue.

Creating a Notification Request

The Notification Structure

When installing a request into the notification queue, your application must supply a pointer to a notification structure, a static and nonrelocatable structure of type NMRec which indicates the type of notification required. Each entry in the notification queue is, in fact, a notification structure. The notification structure is as follows:

     struct NMRec
       QElemPtr   qLink;       // Address of next element in queue. (Used internally.)
       short      qType;       // Type of data. (8 = nmType).
       short      nmFlags;     // (Reserved.)
       long       nmPrivate;   // (Reserved.)
       short      nmReserved;  // (Reserved.)
       short      nmMark;      // Application to identify with diamond mark.
       Handle     nmIcon;      // Handle to small icon.
       Handle     nmSound;     // Handle to sound structure.
       StringPtr  nmStr;       // Pointer to string to appear in the notification.
       NMUPP      nmResp;      // Pointer to response function.
       long       nmRefCon;    // Available for application use.
     typedef struct NMRec NMRec;
     typedef NMRec *NMRecPtr;

To set up a notification request, you need to fill in at least the first six of the following fields:


Indicates the type of operating system queue. Set to nmType (8).


Specifies whether to place a diamond mark next to the name of the application in the Mac OS 8/9 Application menu. 0 means no mark appears. 1 means the mark appears. Applications should ordinarily set this field to 1.


A handle to an icon family containing a small colour icon that is to alternate periodically in the menu bar. If this field is set to NULL, no icon appears. The handle must be non-purgeable.


A handle to a sound resource. If this field is set to NULL, no sound is played. If this field is set to -1, the system alert sound is played. The handle must be non-purgeable.


Pointer to a string that appears in the alert/floating window/system movable modal alert. If this field is set to NULL, no alert/ floating window appears/system movable modal alert. Your application should not dispose of this storage until it removes the notification request.


Universal procedure pointer to a response function. If this field is set to NULL, no response function executes when the notification is posted. If this field is set to -1, a pre-defined function removes the notification request when it has completed. However, on Mac OS 8/9, if either nmMark or nmIcon is non-zero, do not set nmResp to -1, because the Notification Manager will remove the diamond mark or the icon before the user sees it.

If you do not need to do any processing in response to the notification, you should set this field to NULL. If you supply a universal procedure pointer to your own response function, the Notification Manager passes your response function one parameter, namely, a universal procedure pointer to your notification structure. Accordingly, this is how you would declare a response function having the name theResponse:

     void  theResponse(NMUPP nmStructurePtr);

You can use response functions to remove notification requests from the notification queue, free any memory, or set a global variable in your application to record that the notification was posted.

Note that an nmResp value of -1 does not free the memory block containing the queue element; it merely removes that element from the notification queue.


For your application's own use.

Installing a Notification Request

NMInstall is used to add a notification request to the notification queue. The following is an example call:

     osError = NMInstall(¬ificationStructure);

Before calling NMInstall, you should make sure that your application is running in the background. If your application is in the foreground, you simply use standard alert methods, rather than the Notification Manager, to gain the user's attention.

Removing a Notification Request

NMRemove is used to remove a notification request from the notification queue. The following is an example call:

     osError = NMRemove(¬ificationStructure);

You can remove requests at any time, either before or after the notification actually occurs.

On Mac OS 9.x and Mac OS X the user does not have to dismiss the notification before being able to activate the application. For this reason, when your application is running on Mac OS 9.x or Mac OS X, may wish to have it explicitly cancel the notification using NMRemove when the application becomes active.

Progress Bars and Scanning for Command-Period Key-Down Events and Mouse-Down Events

Progress Bars

Operations within an application which tie up the machine for relatively brief periods of time should be accompanied by a cursor shape change to the watch cursor or perhaps to an animated cursor (Mac OS 8/9) or by an invocation of the wait cursor (Mac OS X). On the other hand, lengthy operations should be accompanied by the display of a progress indicator.

The progress indicator control was described at Chapter 14 - More On Controls. A progress indicator created using this control may be determinate or indeterminate. Determinate progress indicators show how much of the operation has been completed. Indeterminate progress indicators show that an operation is occurring but does not indicate its duration. Ordinarily, progress indicators should be displayed within a dialog.

As stated at Chapter 2 - Low and Operating System Events, your application should allow the user to cancel a lengthy operation using the Command-period key combination.

Scanning for Command-Period Key-Down Events

The function CheckEventQueueForUserCancel may be used to scan the event queue for Command-period key-down events, and will return true if a Command-period event is found. If true is returned, the lengthy operation should be terminated and the dialog displaying the progress indicator should be closed.

Soliciting a Colour Choice From the User - The Color Picker

The Color Picker Utilities provide your application with:

  • A standard dialog, called the Color Picker, for soliciting a colour choice from the user.

  • Functions for converting colour specifications from one colour model to another.

Preamble - Colour Models

In the world of colour, three main colour models are used to specify a particular colour. These are the RGB (red, green, blue) model, the CYMK (cyan, magenta, yellow, black) model, and the HLS or HSV (hue, lightness, saturation, or hue, saturation, value) models.

RGB Model

The RGB model is used where light-produced colours are involved, as in the case of a television set, computer monitor, or stage lighting. In this model, the three primary colours involved (red, green, and blue) are said to be additive because, the more of each colour you add, the closer the resulting colour is to white.

CYMK Model

The CYMK model is closely associated with printing, that is, putting colour on a white page. In this model, the three primary colours (cyan, yellow, and magenta) are said to be subtractive because, the more of each colour you add, the closer the resulting colour is to black. (The inclusion of black in the model accounts for the fact that the colours of printer's inks may vary slightly from true cyan, yellow, and magenta, meaning that a true black may not be achievable with just a CYM model.)

Cyan, magenta, and yellow are the complements of red, green, and blue.

HLS and HSV Models

The HLS and HSV models separate colour (that is, hue) from saturation and brightness. Saturation is a measure of the amount of white in a colour (the less white, the more saturated the colour). Lightness is the measure of the amount of black in a colour. (The less black, the lighter the colour). The amount of black is specified by the lightness (L) value in the HLS model and by the value (V) value in the HSV model.

The HSL/HLV model may be represented diagrammatically by the HSL/HLV colour cone shown at Fig 1. In this colour cone, hue is represented by an angle between 0 and 360.

The Color Picker

The Color Picker allows the user to specify a colour using either the RGB, CMYK, HLS, or HSV, models.

Using the Color Picker RGB Mode

Fig 2 shows the Color Picker in RGB mode. The desired red, green and blue values may be set using the three slider controls or may be entered directly into the edit text fields on the right of the sliders.

Using the Color Picker in HSV Mode

Fig 3 shows the Color Picker in HSV mode. Hue is specified by an angle, which may be entered at Hue Angle:. Saturation is specified by percentage, which may be entered at Saturation:. Value is also specified by a percentage, which may be entered at Value: Alternatively, hue and saturation may be selected simultaneously by clicking at the desired point within the coloured disc, and value may be set with the slider control.

To relate Fig 3 to Fig 1, the coloured disc at Fig 3 may be considered as the HSL/HSV cone as viewed from above. The value slider control can then be conceived of as moving the disc up or down the axis of the cone from the apex (black) to the base (white).

Invoking the Color Picker

The Color Picker is invoked using the GetColor function:

     Boolean GetColor(Point where,ConstStr255Param prompt,const RGBColor *inColor,
                      RGBColor *outColor);


Dialog's upper-left corner. (0,0) causes the dialog to positioned centrally on the main screen.


A prompt string, which is displayed in the upper left corner of the main pane in the dialog.


The starting colour, which the user may want for comparison, and which is displayed against Original: in the top right corner of the dialog.


Initially set to equal inColor. Assigned a new value when the user picks a colour. The colour stored in this parameter is displayed at the top right of the dialog against New:.)


A Boolean value indicating whether the user clicked on the OK button or Cancel button.

If the user clicks the OK button in the Color Picker dialog, your application should adopt the outColor value as the colour chosen by the user. If the user clicks the Cancel button, your application should assume that the user has decided to make no colour change, that is, the colour should remain as that represented by the inColor parameter.

Coping With Multiple Monitors


In a multi-monitor system, the user may specify which of the attached monitors is to be the main screen (that is, the screen containing the menu bar) and to set the position of the other screen, or screens, relative to the main screen.

The maximum number of colours capable of being displayed by a given Macintosh at the one time is determined by the video capability of that particular Macintosh. The maximum number of colours capable of being displayed on a given screen at the one time depends on settings made by the user. In a multi-monitor environment, therefore, it is possible for each screen to be set to a different pixel depth.

In more technical terms, the user's settings set the pixel depth of a particular video device. A brief review of the subject of video devices is therefore appropriate at this point.

Video Devices Revisited

As stated at Chapter 11:

  • A graphics device is anything into which QuickDraw can draw, a video device (such as a plug-in video card or a built-in video interface) is a graphics device that controls screens, QuickDraw stores information about video devices in GDevice structures, the system creates and initialises a GDevice structure for each video device found during start-up, all structures are linked together in a list called the device list, and the global variable DeviceList holds a handle to the first structure in the list.

  • At any given time, one, and only one, graphics device is the current device, that is, the one in which the drawing is taking place. A handle to the current device's GDevice structure is placed in the global variable TheGDevice.

    The current device is sometimes referred to as the active device.

By default, the GDevice structure corresponding to the first video device found at start up is marked as the (initial) current device, and all other graphics devices in the list are initially marked as inactive. When the user moves a window to, or creates a window on, another screen, and your application draws into that window, QuickDraw automatically makes the video device for that screen the current device and stores that information in TheGDevice. As QuickDraw draws across a user's video devices, it keeps switching to the GDevice structure for the video device on which it is actively drawing.

Requirements of the Application

Image Optimisation

To draw a particular graphic, your application may have to call different drawing functions for that graphic depending on the characteristics of the video device intersecting your window's drawing region, the aim being to optimise the appearance of the image regardless of whether it is being displayed on, say, a grayscale device or a colour device. Recall from Chapter 11 that when QuickDraw displays a colour on a grayscale screen, it computes the luminance, or intensity of light, of the desired colour and uses that value to determine the appropriate gray value to draw. It is thus possible that, for example, two overlapping objects drawn in two quite different colours on a colour screen may appear in the same shade of gray on a grayscale screen. In order for the user to differentiate between these two objects on a grayscale screen, you would need to provide an alternative drawing function which draws the two objects in different shades of gray on grayscale screens.

The QuickDraw function DeviceLoop is central to the matter of optimising the appearance of your images. DeviceLoop searches for graphics devices which intersect your window's drawing region, informing your application of each graphics device it finds and providing your application with information about the current device's attributes. Armed with this information, your application can then invoke whichever of its drawing functions is optimised for those particular attributes.

DeviceLoop's second parameter is a pointer to an application-defined (callback) function. That function must be defined like this:

     void  myDrawingFunction(short depth,short deviceFlags,GDHandle targetDevice,
                 long userData)

DeviceLoop calls this function for each dissimilar video device it finds. If it encounters similar devices (that is, devices having the same pixel depth, colour table seeds, etc.) it will make only one call to myDrawingFunction, pointing to the first such device encountered.

Other Requirements - Classic Event Model Applications

Other requirements, for Classic event model applications only, are as follows:

  • Window Zooming. If the user drags a window currently zoomed to the user state so that it spans two screens, and then clicks the zoom box to zoom the window to the standard state, the window should be zoomed to the standard state on the screen which contained the largest area of the window before the zoom box was clicked. The function ZoomWindowIdeal, which was introduced with Mac OS 8.5, zooms windows in accordance with this requirement.
  • Window Dragging. In Carbon, if NULL is passed in DragWindow's boundsRect parameter, the bounding rectangle limiting the area in which the window can be dragged is set to the desktop region, which, in a multi-monitors environment, includes all screen real estate less the menu bar.
  • Window Sizing. In a multi-monitor environment, if you pass a constraining rectangle in ResizeWindow's sizeContraints parameter, that rectangle should be based on the bounding rectangle of the desktop region. You should call GetGrayRgn to get a handle to the desktop region and then call GetRegionBounds to get that region's bounding rectangle.

Constraining a Window to One Screen

In a multi-monitors environment, a call to the function ConstrainWindowToScreen enables you to constrain a window's movement and resizing so that it is contained entirely on a single screen.

Help Tags

Help tags are the equivalent, on Mac OS X, of Help balloons on Mac OS 8/9, and appear when the cursor hovers over a user interface element. Carbon also supports Help tags on Mac OS 8/9; however, you may consider that, compared with Help balloons, their "look" is somewhat at odds with the Platinum appearance.

Human Interface Guidelines

Guidelines for Help tags are at

Creating Help Tags

You create a Help tag for, say, a control by filling in the fields of an HMHelpContentRec structure and its associated HMHelpContent structure and passing the control reference and the address of the HMHelpContentRec structure in a call to the function HMSetControlHelpContent.

Data Types

The an HMHelpContentRec and HMHelpContent structures are as follows:

     struct HMHelpContentRec
       SInt32           version;
       Rect             absHotRect;
       HMTagDisplaySide tagSide;
       HMHelpContent    content[2];
     typedef struct HMHelpContentRec HMHelpContentRec;
     typedef HMHelpContentRec *HMHelpContentPtr;

     struct HMHelpContent 
       HMContentType  contentType;
         CFStringRef     tagCFString;   // A CFStringRef reference.
         Str255          tagString;     // A Pascal string.
         HMStringResType tagStringRes;  // A 'STR#' resource ID and index.
         TEHandle        tagTEHandle;   // A TextEdit handle.  (Mac OS 8/9 only.)
         SInt16          tagTextRes;    // A 'TEXT'/'styl' resource ID. (Mac OS 8/9 only.)
         SInt16          tagStrRes;     // A 'STR ' resource ID
       }                 u;
     typedef struct HMHelpContent HMHelpContent;

The HMStringResType structure is used to specify the resource ID and index when Help tag content is sourced from a 'STR#' resource:

     struct HMStringResType 
       short hmmResID; // Resource ID of 'STR#' resource.
       short hmmIndex; // 'STR#' resource index.
     typedef struct HMStringResType HMStringResType;

Note that the content field of the HMHelpContentRec structure is a two-element array. The second element allows you to provide an expanded version of the Help tag message when the user presses the Command key.


Typical constants relevant to the tagSide field of the HMHelpContentRec structure are as follows:




kHMDefaultSide 0

System default location

kHMOutsideTopScriptAligned 1

Above, aligned with left or right depending on system script

kHMOutsideLeftCenterAligned 2

To the left, centered vertically

kHMOutsideRightCenterAligned 4

To the right, centered vertically

kHMOutsideTopLeftAligned 5

Above, aligned with left

kHMOutsideTopRightAligned 6

Above, aligned with right

kHMOutsideLeftTopAligned 7

To the left, aligned with top

kHMOutsideLeftBottomAligned 8

To the left, aligned with bottom

kHMOutsideBottomLeftAligned 9

To the right, aligned with top

kHMOutsideBottomRightAligned 10

To the right, aligned with bottom

Constants relevant to the content field of the HMHelpContentRec structure are as follows:




kHMMinimumContentIndex 0

First element of content array.

kHMMaximumContentIndex 1

Second element of content array.

Constants relevant to the contentType field of the HMHelpContent structure are as follows:




kHMNoContent 'none'

No content.

kHMCFStringContent 'cfst'

Content sourced from a CFStringRef reference.

kHMPascalStrContent 'pstr'

Content sourced from a Pascal string.

kHMStringResContent 'str#'

Content sourced from a 'STR#' resource.

kHMTEHandleContent 'txth'

Content sourced from a TexEdit handle. (Mac OS 8/9 only.)

kHMTextResContent 'text'

Content sourced from 'TEXT'/'styl' resources. (Mac OS 8/9 only.)

kHMStrResContent 'str '

Content sourced from a 'STR ' resource.

Help Tags for Windows

You create a Help tag for a window in the same way as you do for a control, except that:

  • You call the function HMSetWindowHelpContent instead of HMSetControlHelpContent.

  • You assign the window's port rectangle, converted to global coordinates, to the absHotRect field of the HMHelpContentRec structure.

  • You must call HMSetControlHelpContent again whenever the window size or position changes to ensure that the hot rectangle coordinates are updated.

Help Tags for Menus

You create Help tags for menu titles and items in the same way as you do for a control, except that you call the function HMSetMenuItemHelpContent instead of HMSetControlHelpContent.

At the time of writing, menu title and menu item Help tags were not supported by Carbon or CarbonLib. However, future support was planned.

Setting the Delay Before Tag Display

You can set the delay, in milliseconds, before a tag opens by calling the function HMSetTagDelay.

Enabling and Disabling Help Tags

You can enable and disable help tags using the function HMSetHelpTagsDisplayed, and you can determine whether Help tags are currently enabled using the function HMAreHelpTagsDisplayed.

Ensuring Compatibility with the Operating Environment

If your application is to run successfully in the software and hardware environments that may be present in a wide range of Macintosh models, it must be able to acquire information about a number of machine-dependent features and, where appropriate, act on that information.

Getting Operating Environment Information - The Gestalt Function

The Gestalt function may be used to acquire a wide range of information about the operating environment.

     OSErr  Gestalt(OSType selector,long *response);

     selector   Selector code.

     response   4-byte return result which provides the requested information.  When all
                four bytes are not needed, the result is expressed in the low-order byte.

     Returns:    Error code.  (0 = no error.)

The types of information capable of being retrieved by Gestalt are as follows:

  • The type of machine.

  • The version of the System file currently running.

  • The type of CPU.

  • The type of keyboard attached to the machine.

  • The type of floating-point unit (FPU) installed, if any.

  • The type of memory management unit (MMU).

  • The size of the available RAM.

  • The amount of available virtual memory.
  • The versions and features of various drivers and managers.

Gestalt Selectors

To use Gestalt, you pass it a selector, which specifies exactly what information your application is seeking. Of those selectors which are pre-defined by the Gestalt Manager, there are two sub-types:

  • Environmental Selectors. Environmental selectors are those which return information about the existence, or otherwise, of a feature. This information can be used by your application to guide its actions. Some examples of the many available environmental selectors, and the information returned in the response parameter, are as follows:


    Information Returned


    FPU type.


    Keyboard type.


    Logical RAM size.


    Physical RAM size.


    QuickDraw version.


    TextEdit version.

  • Informational Selectors. Informational selectors are those which provide information which should be used for the user's enlightenment only. This information should never be used as proof positive of some feature's existence, nor should it be used to guide your application's actions. gestaltMachineType is an example of an informational selector.

Gestalt Responses

In almost all cases, the last few characters in the selector's name form a suffix which indicates the type of value that will be returned in the response parameter. The following shows the meaningful suffixes:


Returned Value


A range of 32 bits, the meaning of which must be determined by comparison with a list of constants.


A number indicating how many of the indicated type of items exist.


A size, usually in bytes.


Base address of a table.


An index describing a particular type of feature.


A version number. Implied decimal points may separate digits of the returned value. For example, a value of 0x0910 returned in response to the gestaltSystemVersion selector means that system software version 9.1.0 is present.

Using Gestalt - Examples

The header file Gestalt.h defines and describes Gestalt Manager selectors, together with the many constants which may be used to test the response parameter.

Example 1

For example, when Gestalt is used to check whether Version 1.3 or later of Color QuickDraw is present, the value returned in the response parameter may be compared with gestalt32BitQD13 as follows:

     OSErr    osErr
     SInt32   response;
     Boolean  colorQuickDrawVers13Present = true;

     osErr = Gestalt(gestaltQuickdrawVersion,&response);
     if(osErr == noErr)
       if(response < gestalt32BitQD13)
         colorQuickDrawVers13Present = false;

Example 2

Many constants in Gestalt.h represent bit numbers. In this example, the value returned in the response parameter is tested to determine whether bit number 5 (gestaltHasSoundInputDevice) is set:

     OSErr    osErr;
     SInt32   response;
     Boolean  hasSoundInputDevice = false;

     osErr = Gestalt(gestaltSoundAttr,&response);
     if(osErr == noErr)
       gHasSoundInputDevice = BitTst(&response,31 - gestaltHasSoundInputDevice);

Note that the function BitTst is used to determine whether the specified bit is set. Bit numbering with BitTst is the opposite of the usual MC680x0 numbering scheme used by Gestalt. Thus the bit to be tested must be subtracted from 31. This is illustrated in the following:

  Bit numbering as used in BitTst
  ...  7  8  9  10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
  Bit as numbered in MC69000 CPU operations, and used by Gestalt
  ...  8  7  6  5  4  3  2  1  0  15 14 13 12 11 10 9  8  7  6  5  4  3  2  1  0

  gestaltHasSoundInputDevice = 5
  31 - 5 = 26

Carbon and Available APIs

CarbonLib and the Underlying Mac OS 8/9 System Software

CarbonLib (the implementation of the Carbon API for Mac OS 8/9) does not, in general, implement new APIs on old systems. It is basically a "pass-through" library that re-exports what is available on the underlying system software.

Thus, if your application calls a function introduced with, say, Mac OS 9.0, it will compile correctly because that function is, by definition, part of the Carbon API (all new function introduced from Mac OS 8.5 onwards are supported by Carbon); however, if the application is run on Mac OS 8.6, the call to that function will fail.

There are a few exceptions to this rule, for example, the menu, control, and window property APIs.

Interpreting Universal Headers Comments

When you run a CFM application on Mac OS X, CFM follows the same rules for runtime linkages as it does on Mac OS 8/9. Since the application links against a library named CarbonLib, there needs to be a CFM library named CarbonLib somewhere on Mac OS X.

That library is /System/Library/CFM Support/CarbonLib. It exports all of the APIs as does CarbonLib on Mac OS 8/9, plus some APIs that are only implemented on Mac OS X. (Those exports, incidentally, are not the real implementations but simply glue which transfers control from the CFM library to the Mach-O frameworks, where the APIs are really implemented. (Frameworks are like Mac OS 8/9 shared libraries.))

In the Universal Headers, a comment like:

     CarbonLib:  in CarbonLib 1.1 and later

means that the API is implemented in CarbonLib for Mac OS 8/9 and exported from the CarbonLib library on Mac OS X. This comment:

     CarbonLib:  in CarbonLib on Mac OS X

means that the API is not implemented in CarbonLib for Mac OS 8/9 but is still exported from the CarbonLib library on Mac OS X. The real determinant of whether an API is available in Carbon.framework is this comment:

     Mac OS X:   in version 10.0 or later

If the comment in CarbonLib on Mac OS X applies to a function called in your application, you must add the stub library CarbonFrameworkLib to the CodeWarrior project.

T-Vector Tests

In Carbon, the recommended method for checking the availability of a routine is to check its T-Vector (transition vector) directly, as in the following example

     if((UInt32) CreateStandardSheet == (UInt32) kUnresolvedCFragSymbolAddress)
       // CreateStandardSheet is not available.  Do this.
       // Do this.

Main Notification Manager Data Types and Functions

Data Types

Notification Structure

struct NMRec
  QElemPtr   qLink;       // Next queue entry. 
  short      qType;       // Queue type. 
  short      nmFlags;     // (Reserved.) 
  long       nmPrivate;   // (Reserved.) 
  short      nmReserved;  // (Reserved.) 
  short      nmMark;      // Item to mark in Apple menu. 
  Handle     nmIcon;      // Handle to small icon. 
  Handle     nmSound;     // Handle to sound structure. 
  StringPtr  nmStr;       // String to appear in the notification. 
  NMUPP      nmResp;      // Pointer to response function. 
  long       nmRefCon;    // For application use. 
typedef struct NMRec NMRec;
typedef NMRec *NMRecPtr;


Add Notification Request to the Notification Queue

OSErr  NMInstall(NMRecPtr nmReqPtr);

Remove Notification Request from the Notification Queue

OSErr  NMRemove(NMRecPtr nmReqPtr);

Relevant Process Manager Data Types and Functions

Data Types

Process Serial Number

struct ProcessSerialNumber
  unsigned long  highLongOfPSN;
  unsigned long  lowLongOfPSN;


Getting Process Serial Numbers

OSErr  GetCurrentProcess(ProcessSerialNumber *PSN);
OSErr  GetFrontProcess(ProcessSerialNumber *PSN);

Comparing Two Process Serial Numbers

OSErr  SameProcess(const ProcessSerialNumber *PSN1,const ProcessSerialNumber *PSN2,
       Boolean *result);

Relevant Event Manager Function

Check For Command-Period

Boolean  CheckEventQueueForUserCancel(void);

Relevant Color Picker Utilities Function

Boolean  GetColor(Point where,ConstStr255Param prompt,const RGBColor *inColor,
         RGBColor *outColor);

Relevant QuickDraw Function

Drawing Across Multiple Video Devices

void  DeviceLoop(RgnHandle drawingRgn,DeviceLoopDrawingUP drawingProc,long userData,
      DeviceLoopFlags flags);

Relevant Window Manager Function

OSStatus  ConstrainWindowToScreen(WindowRef inWindowRef,WindowRegionCode inRegionCode,
                                  WindowConstrainOptions inOptions,const Rect *inScreenRect,
                                  Rect *outStructure);

Main Help Package Constants, Data Types, and Functions


Content Type

kHMNoContent                  = FOUR_CHAR_CODE('none')
kHMCFStringContent            = FOUR_CHAR_CODE('cfst')
kHMPascalStrContent           = FOUR_CHAR_CODE('pstr')
kHMStringResContent           = FOUR_CHAR_CODE('str#')
kHMTEHandleContent            = FOUR_CHAR_CODE('txth')
kHMTextResContent             = FOUR_CHAR_CODE('text')
kHMStrResContent              = FOUR_CHAR_CODE('str ')

Tag Display Side

kHMDefaultSide                = 0
kHMOutsideTopScriptAligned    = 1
kHMOutsideLeftCenterAligned   = 2
kHMOutsideBottomScriptAligned = 3
kHMOutsideRightCenterAligned  = 4
kHMOutsideTopLeftAligned      = 5
kHMOutsideTopRightAligned     = 6
kHMOutsideLeftTopAligned      = 7
kHMOutsideLeftBottomAligned   = 8
kHMOutsideBottomLeftAligned   = 9
kHMOutsideBottomRightAligned  = 10
kHMOutsideRightTopAligned     = 11
kHMOutsideRightBottomAligned  = 12
kHMOutsideTopCenterAligned    = 13
kHMOutsideBottomCenterAligned = 14
kHMInsideRightCenterAligned   = 15
kHMInsideLeftCenterAligned    = 16
kHMInsideBottomCenterAligned  = 17
kHMInsideTopCenterAligned     = 18
kHMInsideTopLeftCorner        = 19
kHMInsideTopRightCorner       = 20
kHMInsideBottomLeftCorner     = 21
kHMInsideBottomRightCorner    = 22
kHMAbsoluteCenterAligned      = 23

For HMHelpContentRec.content

kHMMinimumContentIndex        = 0
kHMMaximumContentIndex        = 1

Data Types

typedef UInt32 HMContentType;
typedef SInt16 HMTagDisplaySide;


struct HMHelpContent 
  HMContentType  contentType;
    CFStringRef     tagCFString;
    Str255          tagString;
    HMStringResType tagStringRes;
    TEHandle        tagTEHandle;
    SInt16          tagTextRes;
    SInt16          tagStrRes;
  }                 u;
typedef struct HMHelpContent  HMHelpContent;


struct HMHelpContentRec
  SInt32           version;
  Rect             absHotRect;
  HMTagDisplaySide tagSide;
  HMHelpContent    content[2];
typedef struct HMHelpContentRec HMHelpContentRec;
typedef HMHelpContentRec *HMHelpContentPtr;


struct HMStringResType 
  short hmmResID;
  short hmmIndex;
typedef struct HMStringResType HMStringResType;


Installing and Retrieving Content

OSStatus  HMSetControlHelpContent(ControlRef inControl,const HMHelpContentRec *inContent);
OSStatus  HMGetControlHelpContent(ControlRef inControl,HMHelpContentRec *outContent);
OSStatus  HMSetWindowHelpContent(WindowRef inWindow,const HMHelpContentRec *inContent);
OSStatus  HMGetWindowHelpContent(WindowRef inWindow,HMHelpContentRec *outContent);
OSStatus  HMSetMenuItemHelpContent(MenuRef inMenu,MenuItemIndex inItem,
          const HMHelpContentRec *inContent);
OSStatus  HMGetMenuItemHelpContent(MenuRef inMenu,MenuItemIndex inItem,
          HMHelpContentRec *outContent);

Enabling and Disabling Help Tags

Boolean   HMAreHelpTagsDisplayed(void);
OSStatus  HMSetHelpTagsDisplayed(Boolean inDisplayTags);

Setting and Getting Tag Delay

OSStatus  HMSetTagDelay(Duration inDelay);
OSStatus  HMGetTagDelay(Duration *outDelay);

Displaying Tags

OSStatus  HMDisplayTag(const HMHelpContentRec *inContent);

Relevant Gestalt Manager Function

OSErr  Gestalt(OSType selector,long *response);


Community Search:
MacTech Search:

Software Updates via MacUpdate

Suitcase Fusion 6 17.3.0 - Font manageme...
Suitcase Fusion 6 is the creative professional's font manager. Every professional font manager should deliver the basics: spectacular previews, powerful search tools, and efficient font organization... Read more
Nisus Writer Pro 2.1.2 - Multilingual wo...
Nisus Writer Pro is a powerful multilingual word processor, similar to its entry level products, but brings new features such as table of contents, indexing, bookmarks, widow and orphan control,... Read more
calibre 2.40.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Vivaldi - An advanced browser...
Vivaldi is a browser for our friends. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind... Read more
OmniPlan 3.0 - Robust project management...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Yummy FTP 1.11 - FTP/SFTP/FTPS client fo...
Yummy FTP is an FTP + SFTP + FTPS file transfer client which focuses on speed, reliability and productivity. Whether you need to transfer a few files or a few thousand, schedule automatic backups, or... Read more
Tweetbot 2.1 - Popular Twitter client. (...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
MacPilot 8.0 - Enable over 1,200 hidden...
MacPilot gives you the power of UNIX and the simplicity of Macintosh, which means a phenomenal amount of untapped power in your hands! Use MacPilot to unlock over 1,200 features, and access them all... Read more
Typinator 6.7 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
Adobe Lightroom 6.2 - Import, develop, a...
Adobe Lightroom is available as part of Adobe Creative Cloud for as little as $9.99/month bundled with Photoshop CC as part of the photography package. Lightroom 6 is also available for purchase as a... Read more

Balloony Land offers a fresh twist on th...
Balloony Land by Palringo offers a fresh twist on the match three genre and is out now on iOS and Android. First-off, you'll be popping balloons instead of crushing candy and the balloons will float up and fill the empty spaces instead of dropping... | Read more »
Sago Mini Babies (Education)
Sago Mini Babies 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: Introducing the Sago Mini babies. Boys and girls love caring for these adorable characters. Feed Robin her favorite mush... | Read more »
PAUSE - Relaxation at your fingertip (H...
PAUSE - Relaxation at your fingertip 1.1 Device: iOS iPhone Category: Healthcare & Fitness Price: $1.99, Version: 1.1 (iTunes) Description: | Read more »
Super Sharp (Games)
Super Sharp 1.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.1 (iTunes) Description: Your finger has never been so sharp! Cut with skill to complete the 120 ingenious physics levels of Super Sharp and become a cut... | Read more »
Assembly - Graphic design for everyone...
Assembly - Graphic design for everyone 1.0 Device: iOS Universal Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Assembly is the easiest most powerful design tool on the App Store. Create anything you can... | Read more »
Dub Dash (Games)
Dub Dash 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: ARE YOU READY FOR THE ULTIMATE CHALLENGE? UNIQUE SYMBIOSIS OF MUSIC AND GRAPHICS | Read more »
Leave Me Alone (Games)
Leave Me Alone 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: 33% off launch sale!!! Somewhere between the 1980s and 1990s there exists a world that never was. A world of skatepunks,... | Read more »
YAMGUN (Games)
YAMGUN 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: The invasion has begun! Protect the walls of the citadel against waves of enemies! But watch out, you will soon run out of ammo...... | Read more »
Chesh (Games)
Chesh 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: It’s like chess, only not at all. ***40% off for a limited time to celebrate our launch!*** Chesh is a game of skill, strategy, luck,... | Read more »
Dust: An Elysian Tail (Games)
Dust: An Elysian Tail 1.051 Device: iOS Universal Category: Games Price: $5.99, Version: 1.051 (iTunes) Description: *Dust: An Elysian Tail is a visually rich experience and thus requires devices with 1GB RAM**Please note that... | Read more »

Price Scanner via

TP-LINK Next-Gen Routers Support a Large Numb...
TP-LINK, specialists in consumer and business networking products, have announced the availability of Archer C2600, the company’s next-generation router featuring wireless AC, multi-user MIMO, and 4-... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and... Read more
Save up to $350 with Apple refurbished iMacs
Apple has Certified Refurbished iMacs available for up to $350 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $1949 $350 off MSRP - 27... Read more
Mac Pros on sale for up to $300 off MSRP
B&H Photo has Mac Pros on sale for up to $300 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2818.99, $181 off MSRP - 3.5GHz 6-core Mac Pro: $3699... Read more
5K iMacs on sale for up to $150 off MSRP, fre...
B&H Photo has the 27″ 3.3GHz 5K iMac on sale for $1899.99 including free shipping plus NY tax only. Their price is $100 off MSRP. They have the 27″ 3.5GHz 5K iMac on sale for $2149, $150 off MSRP... Read more
Twelve South Redesigns BookArc For Today’s Sm...
Twelve South has announced a redesigned version of their very first product, BookArc for MacBook. Tailored specifically for the newest generation of MacBooks, BookArc holds the new, smaller Apple... Read more
Phone 6s Tips & Tricks – Tips Book For iP...
Poole, United Kingdom based Tap Guides Ltd. has announced the release and immediate availability of iPhone 6s Tips & Tricks, an in-depth eBook available in the iBookstore that’s priced just $2.99... Read more
Apple refurbished 2014 13-inch Retina MacBook...
Apple has Certified Refurbished 2014 13″ Retina MacBook Pros available for up to $400 off original MSRP, starting at $979. An Apple one-year warranty is included with each model, and shipping is free... Read more
13-inch 2.5GHz MacBook Pro on sale for $994,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $994.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $105 off MSRP. Price valid... Read more
Is The iPad Pro Really A Serious Laptop Repla...
Probably not, at least for productive professionals and other power users. Steve Jobs declared that we’d entered the “post-PC Era” with the advent of the original iPad in 2010, a phrase we don’t hear... Read more

Jobs Board

*Apple* Desktop Analyst - KDS Staffing (Unit...
…work with some of the brightest engineers. Job Description Title: Apple Desktop AnalystPosition Type: Full-time PermanentLocation: White Plains, NYHot Points:Depth of Read more
*Apple* Retail Online, Customer Experience R...
**Job Summary** Apple Retail's Online Store sells Apple products to customers around the world. In addition to selling Apple products with unique services such Read more
Frameworks Engineer, *Apple* Watch - Apple...
**Job Summary** Join the team that is shaping the future of software development for Apple Watch! As a software engineer on the Apple Watch Frameworks team you will Read more
Senior Manager, Global Direct Marketing *App...
**Job Summary** Apple Retail is looking for an experienced Direct Marketing Leader to join its Marketing team. This position will take a leadership role in creating Read more
*Apple* Online Store Expansion - Apple (Unit...
**Job Summary** The Online Apple Store is seeking a person to lead its expansion into new countries. Based in Cupertino, CA, this person will develop and maintain an Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.