TweetFollow Us on Twitter

MACINTOSH C CARBON
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

CHAPTER 25

MISCELLANY

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

Overview

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:

qType

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

nmMark

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.

nmIcon

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.

nmSound

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.

nmStr

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.

nmResp

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.

nmRefCon

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);

where

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

prompt

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

inColor

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

outColor

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:.)

Returns:

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

Overview

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 http://developer.apple.com/techpubs/macosx/Carbon/pdf/UsingHelpTags.pdf.

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;
       union 
       {
         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.

Constants

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

Constant

Value

Description

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:

Constant

Value

Description

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:

Constant

Value

Description

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:

    Selector

    Information Returned

    gestaltFPUType

    FPU type.

    gestaltKeyboardType

    Keyboard type.

    gestaltLogicalRAMSize

    Logical RAM size.

    gestaltPhysicalRAMSize

    Physical RAM size.

    gestaltQuickdrawVersion

    QuickDraw version.

    gestaltTextEditVersion

    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:

Suffix

Returned Value

Attr

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

Count

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

Size

A size, usually in bytes.

Table

Base address of a table.

Type

An index describing a particular type of feature.

Version

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.
     else
       // 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;

Functions

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;
};

Functions

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

Constants

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;

HelpContent

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

HMHelpContentRec

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

HMStringResType

struct HMStringResType 
{
  short hmmResID;
  short hmmIndex;
};
typedef struct HMStringResType HMStringResType;

Functions

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);

 
AAPL
$102.47
Apple Inc.
+2.71
MSFT
$44.88
Microsoft Corpora
+0.80
GOOG
$526.54
Google Inc.
+5.70

MacTech Search:
Community Search:

Software Updates via MacUpdate

RapidWeaver 6.0 - Create template-based...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
NTFS 12.0.39 - Provides full read and wr...
Paragon NTFS breaks down the barriers between Windows and OS X. Paragon NTFS effectively solves the communication problems between the Mac system and NTFS, providing full read and write access to... Read more
RestoreMeNot 2.0.3 - Disable window rest...
RestoreMeNot provides a simple way to disable the window restoration for individual applications so that you can fine-tune this behavior to suit your needs. Please note that RestoreMeNot is designed... Read more
Macgo Blu-ray Player 2.10.9.1750 - Blu-r...
Macgo Mac Blu-ray Player can bring you the most unforgettable Blu-ray experience on your Mac. Overview Macgo Mac Blu-ray Player can satisfy just about every need you could possibly have in a Blu-ray... Read more
Apple iOS 8.1 - The latest version of Ap...
The latest version of iOS can be downloaded through iTunes. Apple iOS 8 comes with big updates to apps you use every day, like Messages and Photos. A whole new way to share content with your family.... Read more
TechTool Pro 7.0.5 - Hard drive and syst...
TechTool Pro is now 7, and this is the most advanced version of the acclaimed Macintosh troubleshooting utility created in its 20-year history. Micromat has redeveloped TechTool Pro 7 to be fully 64... Read more
PDFKey Pro 4.0.2 - Edit and print passwo...
PDFKey Pro can unlock PDF documents protected for printing and copying when you've forgotten your password. It can now also protect your PDF files with a password to prevent unauthorized access and/... Read more
Yasu 2.9.1 - System maintenance app; per...
Yasu was originally created with System Administrators who service large groups of workstations in mind, Yasu (Yet Another System Utility) was made to do a specific group of maintenance tasks... Read more
Hazel 3.3 - Create rules for organizing...
Hazel is your personal housekeeper, organizing and cleaning folders based on rules you define. Hazel can also manage your trash and uninstall your applications. Organize your files using a... Read more
Autopano Giga 3.7 - Stitch multiple imag...
Autopano Giga allows you to stitch 2, 20, or 2,000 images. Version 3.0 integrates impressive new features that will definitely make you adopt Autopano Pro or Autopano Giga: Choose between 9... Read more

Latest Forum Discussions

See All

Ghost Blade (Games)
Ghost Blade 1.1 Device: iOS Universal Category: Games Price: $4.99, Version: 1.1 (iTunes) Description: Get the most outstanding 3D Action Game from App Store NOW! For those who dare pursue dreams. Masterpiece of Yu Shi Game ---China... | Read more »
Fiete – A Day on a Farm Review
Fiete – A Day on a Farm Review By Amy Solomon on October 21st, 2014 Our Rating: :: A MEMORABLE EXPERIENCEUniversal App - Designed for iPhone and iPad Fiete – A day on a farm in an interactive app for young children full of... | Read more »
Tilt to Live: Gauntlet’s Revenge is Almo...
Tilt to Live: Gauntlet’s Revenge is Almost Here Posted by Jessica Fisher on October 21st, 2014 [ permalink ] One Man Left has announced the official release date of Tilt to Live: Gauntlet’s Re | Read more »
Sago Mini Monsters Celebrates Halloween...
Sago Mini Monsters Celebrates Halloween with Fun Costumes and Special Treats. Posted by Jessica Fisher on October 21st, 2014 [ permal | Read more »
Inferno 2 Review
Inferno 2 Review By Andrew Fisher on October 21st, 2014 Our Rating: :: TWIN STICK GOODNESSUniversal App - Designed for iPhone and iPad With tight controls and awesome, stark visuals, Inferno 2 is loads of fun.   | Read more »
Clips Review
Clips Review By Jennifer Allen on October 21st, 2014 Our Rating: :: CONVENIENT PASTINGUniversal App - Designed for iPhone and iPad Making copying and pasting more powerful than usual, Clips is a great way to move stuff around.   | Read more »
MonSense Review
MonSense Review By Jennifer Allen on October 21st, 2014 Our Rating: :: ORGANIZED FINANCESiPhone App - Designed for the iPhone, compatible with the iPad Organize your finances with the quick and easy to use, MonSense.   | Read more »
This Week at 148Apps: October 13-17, 201...
Expert App Reviewers   So little time and so very many apps. What’s a poor iPhone/iPad lover to do? Fortunately, 148Apps is here to give you the rundown on the latest and greatest releases. And we even have a tremendous back catalog of reviews; just... | Read more »
Angry Birds Transformers Review
Angry Birds Transformers Review By Jennifer Allen on October 20th, 2014 Our Rating: :: TRANSFORMED BIRDSUniversal App - Designed for iPhone and iPad Transformed in a way you wouldn’t expect, Angry Birds Transformers is a quite... | Read more »
GAMEVIL Announces the Upcoming Launch of...
GAMEVIL Announces the Upcoming Launch of Mark of the Dragon Posted by Jessica Fisher on October 20th, 2014 [ permalink ] Mark of the Dragon, by GAMEVIL, put | Read more »

Price Scanner via MacPrices.net

Select MacBook Airs $100 off MSRP, free shipp...
B&H Photo has 2014 a couple of MacBook Airs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only. They also include free copies of Parallels Desktop and LoJack for... Read more
13-inch 2.5GHz MacBook Pro on sale for $100 o...
B&H Photo has the 13″ 2.5GHz MacBook Pro on sale for $999.99 including free shipping plus NY sales tax only. Their price is $100 off MSRP. Read more
Strong iPhone, Mac And App Store Sales Drive...
Apple on Monday announced financial results for its fiscal 2014 fourth quarter ended September 27, 2014. The Company posted quarterly revenue of $42.1 billion and quarterly net profit of $8.5 billion... Read more
Apple Posts How-To For OS X Recovery
OS X 10.7 Lion and later include OS X Recovery. This feature includes all of the tools you need to reinstall OS X, repair your disk, and even restore from a Time Machine backup. OS X Recovery... Read more
Mac OS X Versions (Builds) Supported By Vario...
Apple Support has posted a handy resource explaining which Mac OS X versions (builds) originally shipped with or are available for your computer via retail discs, downloads, or Software Update. Apple... Read more
Deals on 2011 13-inch MacBook Airs, from $649
Daily Steals has the Mid-2011 13″ 1.7GHz i5 MacBook Air (4GB/128GB) available for $699 with a 90 day warranty. The Mid-2011 13″ 1.7GHz i5 MacBook Air (4GB/128GB SSD) is available for $649 at Other... Read more
2013 15-inch 2.0GHz Retina MacBook Pro availa...
B&H Photo has leftover previous-generation 15″ 2.0GHz Retina MacBook Pros now available for $1599 including free shipping plus NY sales tax only. Their price is $400 off original MSRP. B&H... Read more
Updated iPad Prices
We’ve updated our iPad Air Price Tracker and our iPad mini Price Tracker with the latest information on prices and availability from Apple and other resellers, including the new iPad Air 2 and the... Read more
Apple Pay Available to Millions of Visa Cardh...
Visa Inc. brings secure, convenient payments to iPad Air 2 and iPad mini 3as well as iPhone 6 and 6 Plus. Starting October 20th, eligible Visa cardholders in the U.S. will be able to use Apple Pay,... Read more
Textkraft Pocket – the missing TextEdit for i...
infovole GmbH has announced the release and immediate availability of Textkraft Pocket 1.0, a professional text editor and note taking app for Apple’s iPhone. In March 2014 rumors were all about... Read more

Jobs Board

Senior Event Manager, *Apple* Retail Market...
…This senior level position is responsible for leading and imagining the Apple Retail Team's global event strategy. Delivering an overarching brand story; in-store, Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
Project Manager / Business Analyst, WW *Appl...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.