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

World of Tanks Generals guide - Tips and...
World of Tanks Generals is a brand new card game by the developer behind the World of Tanks shooter franchise. It plays like a cross between chess and your typical card game. You have to keep in consideration where you place your tanks on the board... | Read more »
TruckSimulation 16 guide: How to succeed...
Remember those strangely enjoyable truck missions in Grand Theft Auto V whereit was a disturbing amount of fun to deliver cargo? TruckSimulation 16 is reminiscent of that, and has you play the role of a truck driver who has to deliver various... | Read more »
The best GIF making apps
Animated GIFs have exploded in popularity recently which is likely thanks to a combination of Tumblr, our shorter attention spans, and the simple fact they’re a lot of fun. [Read more] | Read more »
The best remote desktop apps for iOS
We've been sifting through the App Store to find the best ways to do computer tasks on a tablet. That gave us a thought - what if we could just do computer tasks from our tablets? Here's a list of the best remote desktop apps to help you use your... | Read more »
Warhammer 40,000: Freeblade guide - How...
Warhammer 40,000: Freebladejust launched in the App Store and it lets you live your childhood dream of blowing up and slashing a bunch of enemies as a massive, hulking Space Marine. It's not easy being a Space Marine though - and particularly if... | Read more »
Gopogo guide - How to bounce like the be...
Nitrome just launched a new game and, as to be expected, it's a lot of addictive fun. It's called Gopogo, and it challenges you to hoparound a bunch of platforms, avoiding enemies and picking up shiny stuff. It's not easy though - just like the... | Read more »
Sago Mini Superhero (Education)
Sago Mini Superhero 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: KAPOW! Jack the rabbit bursts into the sky as the Sago Mini Superhero! Fly with Jack as he lifts impossible weights,... | Read more »
Star Wars: Galaxy of Heroes guide - How...
Star Wars: Galaxy of Heroes is all about collecting heroes, powering them up, and using them together to defeat your foes. It's pretty straightforward stuff for the most part, but increasing your characters' stats can be a bit confusing because it... | Read more »
The best cooking apps (just in time for...
It’s that time of year again, where you’ll be gathering around the dinner table with your family and a huge feast in front of you. [Read more] | Read more »
Square Rave guide - How to grab those te...
Square Rave is an awesome little music-oriented puzzle game that smacks of games like Lumines, but with its own unique sense of gameplay. To help wrap your head around the game, keep the following tips and tricks in mind. [Read more] | Read more »

Price Scanner via

Cyber Monday: Target offers 15% discount on A...
Target has discounted Apple Watches by 15% for Cyber Monday. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-store prices may vary: - Apple... Read more
Sunday roundup of Holiday weekend Mac sales:...
Take up to $500 off MSRP on the price of a new Mac at B&H Photo today as part of their Black Friday/Holiday weekend sale. Shipping is free, and B&H charges NY tax only. These prices are... Read more
Holiday weekend: Apple Watch on sale for $50-...
B&H Photo has the Apple Watch on sale today for $50-$100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - Apple Watch Sport: $50 off - Apple Watch: $50-$100 off Read more
Holiday weekend: iPad Air 2s on sale for up t...
B&H Photo has iPad Air 2s on sale for up to $80 off MSRP including free shipping plus NY sales tax only: - 16GB iPad Air 2 WiFi: $459 $40 off - 64GB iPad Air 2 WiFi: $569 $30 off - 128GB iPad Air... Read more
Holiday weekend Mac sales roundup: B&H Ph...
B&H Photo continues to have all new Macs on sale for up to $500 off MSRP as part of their Black Friday/Holiday weekend sale. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina... Read more
iMobie Releases its Ace iOS Cleaner PhoneClea...
iMobie Inc. has announced the new update of PhoneClean 4, its iOS cleaner designed to reclaim wasted space on iPhone/iPad for use and keep the device fast. Alongside, iMobie hosts a 3-day giveaway of... Read more
U.S. Cellular Offering iPad Pro
U.S. Cellular today announced that it is offering the new iPad Pro with Wi-Fi + Cellular, featuring a 12.9-inch Retina display with 5.6 million pixels — the most ever in an iOS device. U.S. Cellular... Read more
Newegg Canada Unveils Black Friday Deals for...
Newegg Canada is offering more than 1,000 deep discounts to Canadian customers this Black Friday, available now through Cyber Monday, with new deals posted throughout the week. “Black Friday is... Read more
Black Friday: Macs on sale for up to $500 off...
BLACK FRIDAY B&H Photo has all new Macs on sale for up to $500 off MSRP as part of their early Black Friday sale including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $... Read more
Black Friday: Up to $125 off iPad Air 2s at B...
BLACK FRIDAY Walmart has the 16GB iPad Air 2 WiFi on sale for $100 off MSRP on their online store. Choose free shipping or free local store pickup (if available): - 16GB iPad Air 2 WiFi: $399, save $... Read more

Jobs Board

Technical Program Manager, Strategic Merchant...
# Technical Program Manager, Strategic Merchants - Apple Pay Job Number: 44001177 Santa Clara Valley, Califo ia, United States Posted: Oct. 30, 2015 Weekly Hours: 40.00 Read more
Frameworks Engineer, *Apple* Watch - Apple...
# Frameworks Engineer, Apple Watch Job Number: 41403122 Santa Clara Valley, Califo ia, United States Posted: Jul. 1, 2015 Weekly Hours: 40.00 **Job Summary** Join the Read more
Software Engineer - *Apple* Pay - Apple (Un...
# Software Engineer - Apple Pay Job Number: 44003246 Santa Clara Valley, Califo ia, United States Posted: Nov. 16, 2015 Weekly Hours: 40.00 **Job Summary** Apple Pay Read more
Merchant Operations Manager: *Apple* Pay -...
# Merchant Operations Manager: Apple Pay Job Number: 43593822 Santa Clara Valley, Califo ia, United States Posted: Nov. 10, 2015 Weekly Hours: 40.00 **Job Summary** The Read more
Product Design Engineer - *Apple* Watch - A...
# Product Design Engineer - Apple Watch Job Number: 41727161 Santa Clara Valley, Califo ia, United States Posted: Jul. 22, 2015 Weekly Hours: 40.00 **Job Summary** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.