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

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

iMazing 2.1.8 - Complete iOS device mana...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more
Civilization VI 1.0.2 - Next iteration o...
Sid Meier’s Civilization VI is the next entry in the popular Civilization franchise. Originally created by legendary game designer Sid Meier, Civilization is a strategy game in which you attempt to... Read more
TurboTax 2016 - Manage your 2016 U.S. ta...
TurboTax guides you through your tax return step by step, does all the calculations, and checks your return for errors and overlooked deductions. It lets you file your return electronically to get... Read more
Microsoft Office 2016 15.30 - Popular pr...
Microsoft Office 2016 - Unmistakably Office, designed for Mac. The new versions of Word, Excel, PowerPoint, Outlook and OneNote provide the best of both worlds for Mac users - the familiar Office... Read more
FotoMagico 5.3 - Powerful slideshow crea...
FotoMagico lets you create professional slideshows from your photos and music with just a few, simple mouse clicks. It sports a very clean and intuitive yet powerful user interface. High image... Read more
Acorn 5.6.1 - Bitmap image editor.
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
Dash 3.4.3 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
Microsoft Remote Desktop 8.0.37 - Connec...
With Microsoft Remote Desktop, you can connect to a remote PC and your work resources from almost anywhere. Experience the power of Windows with RemoteFX in a Remote Desktop client designed to help... Read more
Macs Fan Control 1.4.7.0 - Monitor and c...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
MacFamilyTree 8.1.3 - Create and explore...
MacFamilyTree gives genealogy a facelift: modern, interactive, convenient and fast. Explore your family tree and your family history in a way generations of chroniclers before you would have loved.... Read more

Stickman Surfer rides in with the tide t...
Stickson is back and this time he's taken up yet another extreme sport - surfing. Stickman Surfer is out this Thursday on both iOS and Android, so if you've been following the other Stickman adventures, you might be interested in picking this one... | Read more »
Z-Exemplar (Games)
Z-Exemplar 1.4 Device: iOS Universal Category: Games Price: $3.99, Version: 1.4 (iTunes) Description: | Read more »
5 dastardly difficult roguelikes like th...
Edmund McMillen's popular roguelike creation The Binding of Isaac: Rebirth has finally crawled onto mobile devices. It's a grotesque dual-stick shooter that tosses you into an endless, procedurally generated basement as you, the pitiable Isaac,... | Read more »
Last week on PocketGamer
Welcome to a weekly feature looking back on the past seven days of coverage on our sister website, PocketGamer. It’s taken a while for 2017 to really get going, at least when it comes to the world of portable gaming. Thank goodness, then, for... | Read more »
ROME: Total War - Barbarian Invasion set...
To the delight of mobile strategy fans, Feral Interactive released ROME: Total War just a few months ago. Now the game's expansion, Barbarian Invasion is marching onto iPads as a standalone release. [Read more] | Read more »
Yuri (Games)
Yuri 1.0 Device: iOS iPhone Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: It's night. Yuri opens his eyes. He wakes up in a strange forest.The small, courageous explorer rides on his bed on casters in this... | Read more »
Space schmup Xenoraid launches on the Ap...
10Tons Xenoraid is out today on the App Store, bringing some high-speed space action to your mobile gadgets just in time for the weekend. The company's last premium title, another sci-fi game titled Neon Chrome, did quite well for itself, so... | Read more »
Star Wars: Force Arena Beginner's G...
Star Wars: Force Arena joined the populous ranks of Star Wars games on mobile today. It's a two-lane MOBA starring many familiar faces from George Lucas's famed sci-fi franchise. As with most games of this nature, Force Arena can be a little obtuse... | Read more »
Mysterium: The Board Game (Games)
Mysterium: The Board Game 1.0 Device: iOS Universal Category: Games Price: $6.99, Version: 1.0 (iTunes) Description: The official adaptation of the famous board game Mysterium! | Read more »
Sonny (Games)
Sonny 1.0.4 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.4 (iTunes) Description: Reimagined for iOS, cult-hit RPG Sonny brings challenging turn-based combat that requires strategy and mastery of each new skill to... | Read more »

Price Scanner via MacPrices.net

Laptop Market – Flight To Quality? – The ‘Boo...
Preliminary quarterly PC shipments data released by Gartner Inc. last week reveal an interesting disparity between sales performance of major name PC vendors as opposed to that of less well-known... Read more
IBM and Bell Transform Canadian Enterprise Mo...
IBM and Bell Canada have announced they are joining forces to offer IBM MobileFirst for iOS market-ready enterprise applications for iPad, iPhone or Apple Watch. Bell, Canada’s largest communications... Read more
Otter Products is Closing… For a Day of Givin...
On Thursday, Feb. 9, Otter Products is closing doors to open hearts. In partnership with the OtterCares Foundation, the company is pausing operations for a day so all employees can volunteer with... Read more
15-inch 2.2GHz Retina MacBook Pro on sale for...
Amazon has 2015 15″ 2.2GHz Retina MacBook Pros (MJLQ2LL/A) available for $1799.99 including free shipping. Apple charges $1999 for this model, so Amazon’s price is represents a $200 savings. Read more
Back in stock: Apple refurbished 13-inch Reti...
Apple has Certified Refurbished 2015 13″ Retina MacBook Pros available for up to $360 off original MSRP, starting at $1099. An Apple one-year warranty is included with each model, and shipping is... Read more
CalcTape for macOS 1.2 Adding Machine App for...
schoettler Software has announced CalcTape 1.2, an update to their desktop calculator for macOS. When it comes to adding long columns of numbers, doing complex calculations or playing around with... Read more
New MacBooks And MacBook Pros WIth Kaby Lake...
Digitimes’ Joseph Tsai cites a Chinese-language Economic Daily News (EDN) report that unnamed market watchers are predicting Apple MacBook shipments to grow 10 percent in 2017, and projecting 15... Read more
New 2016 13-inch MacBook Pros on sale for up...
B&H Photo has the new 2016 13″ MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.9GHz/512GB Touch Bar MacBook Pro... Read more
New 15-inch Touch Bar MacBook Pros in stock a...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
Opera Announces Neon Concept Browser For Mac
Opera is inviting users to get a glimpse of what Opera for computers could become with its Opera Neon browser concept. Each Opera Neon feature is described as “an alternate reality” for the Opera... Read more

Jobs Board

*Apple* Retail - Multiple Positions (Multi-L...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* & PC Desktop Support Technician...
Apple & PC Desktop Support Technician job in Stamford, CT We have immediate job openings for several Desktop Support Technicians with one of our most well-known Read more
*Apple* macOS Systems Integration Administra...
…most exceptional support available in the industry. SCI is seeking an Junior Apple macOS systems integration administrator that will be responsible for providing Read more
*Apple* Premier Retailer - Service Technicia...
DescriptionSimply Mac is the largest premier retailer for Apple products and solutions. At Simply Mac we are all Apple , all the time. Same products. Same prices. Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.