Carbon Compatibility Report

Report for: gene_kant	Report date: 5/14/2004
File Creator: ????	Data gathered by analyzer version: 1.3
File Type: APPL	Data gathered on: 5/14/2004

Summary

Test Number Analysis of Imports Supported API 299 Supported with Modifications 2 Supported But Not Recommended 50 Unsupported API 54 Analysis of Access to Low Memory Addresses Analysis of Resources Loaded into System Heap

Supported with Modifications

Common OS Services

Process Manager

Carbon supports most of the Process Manager. The exception is the LaunchDeskAccessory function, which is not supported.

Note that some Process Manager functions access a ProcessInfoRec data structure, which contains fields that are no longer applicable in a preemptively scheduled environment (for example, the processLocation, processFreeMem, and processActiveTime fields). Your application should avoid accessing such fields. Changes to the memory model may also affect certain fields.

GetProcessInformation

The processActiveTime field of the returned ProcessInfoRec structure is not used in Carbon on Max OS X. In Carbon on Mac OS 8 and 9, the accumulated amount of CPU time used by the process is returned in this field. In Carbon on Mac OS X, the value returned in this field is always 0. Other fields in the ProcessInfoRec structure may also no longer be applicable. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

Human Interface Toolbox

Menu Manager

Carbon supports the Menu Manager, with the following changes:

• Your application must use the functions defined by the Menu Manager whenever it creates and disposes of Menu Manager data structures. Some applications, for example, create menus by using the Resource Manager function GetResource (instead of the Menu Manager function GetMenu) and dispose of them by calling ReleaseResource instead of DisposeMenu. This practice is not supported in Carbon.

• The MenuInfo structure is opaque in Carbon. You must revise your application so that it accesses Menu Manager data structures only through accessor functions.

• There are several Menu Manager functions that deal with manipulating menu color information tables. Apple recommends that you stop using them. The Appearance Manager generally disregards these color tables and instead uses the colors defined for the current appearance.

• You are strongly encouraged to adopt the standard Mac OS 8 menu definition procedures (also known as MDEFs) in your application. Your menus will then inherit the systemwide appearance and, furthermore, take advantage of other Menu Manager enhancements planned for the future. Note, however, that if you must use custom menu definition procedures, you must compile them as PowerPC-native code.

GetMenu

In Carbon, the GetMenu function always returns a newly created MenuRef. Prior to Carbon, GetMenu would first check if the menu was already in memory. If so, GetMenu would return the in-memory copy. This behavior is no longer supported.

Carbon does not support custom menu definitions stored in 'MDEF' resources. If you want to specify a custom menu definition for GetMenu, you must compile your definition function directly in your application and then register the function by calling RegisterMenuDefinition. When GetMenu gets a resourceID value that doesn't recognize, it checks a special mapping table to find the pointer that's registered for the resourceID parameter. It then calls that function to implement your menu. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

Supported But Not Recommended

Human Interface Toolbox

Control Manager

Carbon supports most Control Manager functions, with the following changes:

• The C-style, lowercase versions of Control Manager function names are no longer supported. If your application uses any Control Manager lowercase function names, you must replace them with their uppercase equivalents.

• Custom control definition procedures (also known as CDEFs), must be compiled as PowerPC-native code, and can not be stored as resources. See the Carbon Porting Guide for more information.

• Your application must use the functions defined by the Control Manager to create and dispose of Control Manager data structures. For example, instead of directly creating and disposing of control records, applications must call the Control Manager functions GetNewControl and DisposeControl.

• With the availability of the Appearance Manager, you should not access the PopupPrivateData structure, but rather pass the kControlPopupButtonMenuHandleTag tag to GetControlData to obtain its contents.

• Your application must use Control Manager accessor functions to accesses Control Manager data structures.

• You are encouraged to adopt the standard Mac OS control definition procedures in your application. Applications that use the standard control definition procedures inherit the Mac OS human interface appearance. Applications that use custom control definition procedures will work correctly, but because custom definition procedures invoke their own drawing routines, Mac OS 8 and 9 can’t draw these applications with the current appearance.

GetControlMaximum

Use GetControl32BitMaximum instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

GetControlMinimum

Use GetControl32BitMinimum instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

GetControlValue

Use GetControl32BitValue instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

HiliteControl

If you are activating or deactivating a control, you should use ActivateControl or DeactivateControl instead. Otherwise okay to use. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

NewControl

Use the specific control creation function instead (for example, CreateCheckboxControl).

Carbon does not support custom control definitions stored in 'CDEF' resources. If you want to specify a custom control definition for NewControl, you must compile your definition function directly in your application and then register the function by calling RegisterControlDefinition. When NewControl gets a procID value that doesn't recognize, it checks a special mapping table to find the pointer that's registered for the resource ID embedded in the procID parameter. It then calls that function to implement your control. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

SetControlMaximum

Use SetControl32BitMaximum instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

SetControlValue

Use SetControl32BitValue instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TrackControl

Use HandleControlClick instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

Scrap Manager

Carbon supports only the LoadScrap and UnloadScrap functions from the original Scrap Manager. However, Carbon supplies new features, including support for "promises," to the Scrap Manager.

LoadScrap

Carbon applications may continue calling this function on Mac OS 8; however, on Mac OS X it does nothing and is no longer necessary. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

Window Manager

Carbon supports the Window Manager. Be aware, however, that if you use custom window definition procedures (also known as WDEFs), you must compile them as PowerPC-native code. In addition:

• Your application must use the functions defined by the Window Manager whenever it creates and disposes of Window Manager data structures. For example, instead of directly creating and disposing of window records, applications must call such Window Manager functions as GetNewCWindow and DisposeWindow.

• You must revise your application so that it accesses Window Manager data structures only through accessor functions.

• You are encouraged to adopt the standard Mac OS 8 window definition procedures in your application. Applications that use the standard Mac OS 8 window definition procedures inherit the Mac OS 8 human interface appearance. Applications that use custom window definition procedures work correctly, but because custom definition procedures invoke their own drawing routines, Mac OS 8 can’t draw these applications with the current appearance.

ClipAbove

If you are using this function to redraw your own floating windows, you should just use the standard floating window class instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

DragGrayRgn

Can’t be used for live dragging. If you are implementing your own window dragging, use DragWindow instead. If you need to override window positioning during a drag, register a Carbon event handler for kEventWindowBoundsChanging. Okay to use if you’re dragging objects within a window. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

GetGrayRgn

Use GetAvailableWindowPositioningBounds if you want to determine where you can position your windows. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

GetWTitle

Use CopyWindowTitleAsCFString instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

GetWVariant

Use GetWindowAttributes instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

GrowWindow

Use ResizeWindow instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

HiliteWindow

If available, use the ActivateWindow function instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

NewCWindow

You should use CreateNewWindow instead.

However, if you are still using the NewCWindow function in Carbon, note that you cannot pass your own storage in to the wStorage parameter.

Carbon does not support custom window definitions stored in 'WDEF' resources. If you want to specify a custom window definition for NewCWindow, you must compile your definition function directly in your application and then register the function by calling RegisterWindowDefinition. When NewCWindow gets a procID value that doesn't recognize, it checks a special mapping table to find the pointer that's registered for the resource ID embedded in the procID parameter. It then calls that function to implement your window. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

NewWindow

Use CreateNewWindow instead.

In Carbon, you cannot pass your own storage in to the wStorage parameter.

In Carbon, NewWindow is functionally equivalent to the NewCWindow, in that NewWindow returns a color window instead of a monochrome window.

Carbon does not support custom window definitions stored in 'WDEF' resources. If you want to specify a custom window definition for NewWindow, you must compile your definition function directly in your application and then register the function by calling RegisterWindowDefinition. When NewWindow gets a procID value that doesn't recognize, it checks a special mapping table to find the pointer that's registered for the resource ID embedded in the procID parameter. It then calls that function to implement your window. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

SetWTitle

Use SetWindowTitleWithCFString instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

ShowHide

Use ShowWindow or HideWindow instead. Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

Text and Other International Services

TextEdit

Carbon supports most TextEdit functions, but TextEdit functionality has been replaced by Multilingual Text Engine (MLTE). Although there is not a one-to-one correspondence between APIs in these two technologies, you are encouraged to use MLTE in place of TextEdit.

The Carbon version of TextEdit replaces the low memory accessors for TextEdit structures as follows:

TEGet/SetScrapLength replaces LMGet/SetTEScrpLength

TEGet/SetScrapHandle replaces LMGet/SetTEScrpHandle

TEGet/SetDoTextHook replaces LMGet/SetTEDoText

TEGet/SetRecalcHook replaces LMGet/SetTERecal

The Carbon version also has a new accessor for the FindWord hook: TEGet/SetFindWordHook.

TESetWordBreak is not available in Carbon, and you should not override wordBreak in order to customize wordBreak behavior. Instead, override the FindWord hook using the TEGet/SetFindWordHook accessors. Previously, the wordBreak hook was used on Roman-only systems, a distinction that no longer exists in Carbon. TERec's wordBreak field is ignored in Carbon.

TEActivate

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEAutoView

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TECalText

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEClick

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TECopy

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TECut

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEDeactivate

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEDelete

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEDispose

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEFromScrap

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEGetHeight

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEGetHiliteRgn

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEGetOffset

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEGetPoint

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEIdle

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEInsert

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEKey

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TENew

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEPaste

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEPinScroll

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEScroll

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TESelView

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TESetClickLoop

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TESetSelect

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TESetStyle

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TESetText

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEStyleNew

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEToScrap

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEUpdate

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

TEUseStyleScrap

Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later. Available in Mac OS X 10.0 and later.

Unsupported API

Carbon Core

File Manager

While Carbon supports most of the File Manager interface, there are a number of significant changes. The default volume format for Carbon is the Mac OS Extended format; in most cases you will not need to modify your application to gain this volume support, although Apple recommends that you adopt the new HFS Plus API introduced with Mac OS 9.0 to take full advantage of the capabilities of the Mac OS Extended format.

You should not access File Manager structures directly if accessor functions for the structure exist. For example, you should call PBGetFCBInfo rather than calling LMGetFCBSPtr and walking the FCB table.

Similarly, you should create file system specification (FSSpec) records using the functions PBMakeFSSpec or FSMakeFSSpec instead of filling in your own structures. File system specification records must contain a volume reference number, a parent directory, and a name. Substituting a working directory for the volume reference number or a full or partial pathname for the name is not supported.

File Manager functions that support MFS (the Macintosh file system) are not supported in Carbon. These include

• functions, such as OpenWD and GetWDInfo, that manipulate working directories

• functions that identify a file or folder using a volume reference number and pathname but not a parent directory ID. You should use the HFS version of these calls (which use a parent directory ID) instead.

Functions that cannot be called by PowerPC applications (such as PBGetAltAccessSync and PBGetAltAccessAsync) are not supported.

You should use only documented File Manager interfaces in your application. For example, you should use a documented API call to get low memory information rather than access undocumented low memory global variables or vectors directly.

Note that in current releases of Mac OS X (versions 10.0-10.1.x) File Manager file access permissions and byte range locking are not enforced across processes; it is possible for more than one process to open a file for writing simultaneously. If your application may have multiple clients accessing the same file simultaneously, you must synchronize the file accesses between these clients yourself. This only affects local volumes; file locking on AppleShare servers is still supported.

OpenRF

This function is not supported in Carbon. Use the function FSpOpenRF instead. To open a resource fork larger than 2 GB on an HFS Plus volume, use the FSOpenFork function. Not available in CarbonLib. Not available in Mac OS X.

PBGetFInfoSync

This function is not supported in Carbon. Use the function PBHGetFInfoSync instead.

To get information about files and directories on HFS Plus volumes, use the PBGetCatalogInfoSync function. Not available in CarbonLib. Not available in Mac OS X.

Low Memory Accessors

Carbon supports many of the accessor functions for low-memory variables. However, you should always avoid using low-memory accessors if there are direct Mac OS Toolbox calls to obtain the same information. For example:

• Use the function TickCount instead of the low-memory accessor function LMGetTicks.

• Use the function FrontWindow instead of the low-memory accessor function LMGetWindowList, when possible.

• Use the function PBGetFCBInfo instead of walking the FCB table with the low-memory accessor function LMGetFCBSPtr.

In general, don’t think of the values returned by low-memory accessor routines as residing in low memory—think of them as information, possibly associated with a specific Toolbox manager, that is returned by the Mac OS. In the future, Apple may supply new functions, distributed among the Mac OS Toolbox managers, for retrieving this information.

Some low-memory accessor functions are obsolete in Mac OS X. The following Resource Manager-related functions are not supported:

• LMGetTopMapHndl and LMSetTopMapHndl

• LMGetSysMapHndl and LMSetSysMapHndl

• LMGetCurMapHndl and LMSetCurMapHndl

LMGetCaretTime

You should instead use GetCaretTime. Not available in CarbonLib. Not available in Mac OS X.

LMGetMBarHeight

Use GetMBarHeight instead. If you are using this function to hide the menu bar, use Hide/ShowMenuBar instead. Not available in CarbonLib. Not available in Mac OS X.

LMGetTopMapHndl

Functions that access the resource map will not be supported. Not available in CarbonLib. Not available in Mac OS X.

LMGetWindowList

You should instead use GetWindowList. Not available in CarbonLib. Not available in Mac OS X.

LMSetMBarHeight

Do not hide and show the menu bar by adjusting the menu bar height. Use the HideMenuBar and ShowMenuBar functions instead. Not available in CarbonLib. Not available in Mac OS X.

LMSetWindowList

The window list is read-only in Carbon. You should instead use the high-level functions provided by the Window Manager. Not available in CarbonLib. Not available in Mac OS X.

Memory Management Utilities

While Carbon supports most of the Memory Management Utilities, there are changes to functions that assume a 68K runtime environment.

• Functions that flush caches on 68K processors (such as FlushInstructionCache, FlushDataCache, and FlushCodeCacheRange) are no longer supported.

• Functions such as SetA5 or SetCurrentA5 do nothing when running in Mac OS X. However, these functions should work normally when running in Mac OS 8 or 9.

• The functions GetMMUMode and SwapMMUMode are not supported because all PowerPC applications use 32-bit addressing, even if they are not Carbon-compliant.

• The SysEnvirons function is no longer supported since the Gestalt Manager can provide the same information. You should call the functions FindFolder and Gestalt instead.

SysEnvirons

Uses working directories. Use FindFolder and Gestalt instead. Not available in CarbonLib. Not available in Mac OS X.

Memory Manager

Carbon supports the majority of the Memory Manager programming interface. Changes primarily affect applications that use zones, system memory, or temporary memory. For example, temporary memory allocations in Mac OS X are allocated in the application’s address space. As a result, calling TempNewHandle is effectively the same as calling NewHandle.

Carbon does not support functions for accessing the system heap, as the system heap in unavailable in Mac OS X.

By adhering to the following guidelines, you can increase your application’s compliance with Mac OS X memory management:

• Try to use memory only within your own application heap. Review the places where you allocate memory in the system heap.

• Do not pass pointers to data among applications through Apple events, Gestalt routines, or other means. For example, don’t share Toolbox data structures between applications, because in Mac OS X, each application will run in its own protected address space.

• Do not use inline, hard-coded addresses.

• Do not modify the zone header by calling the MoreMasters function. You should instead call the function MoreMasterPointers. Note, however, that master pointer blocks do not need to be preallocated or optimized in the Mac OS X environment, so MoreMasterPointers will only benefit Carbon applications running on Mac OS 8 or 9.

• Don’t make assumptions about the layout of memory, such as the relative position of data stored in heaps, stacks, and other memory areas.

• Don’t use the DisposePtr or DisposeHandle functions on pointers or handles allocated by Toolbox managers. For example, don’t call the function DisposeHandle on a control allocated by the NewControl function; use DisposeControl instead.

• Because Mac OS X applications run in a large, protected memory space, memory sizing routines such as MaxMem and FreeMem work differently than before and just return a large fixed value.

MaxApplZone

This routine is not needed by PowerPC-based applications because they can specify a stack size in the cfrg resource. Not available in CarbonLib. Not available in Mac OS X.

Mixed Mode Manager

Mac OS X will not run 68K code. Although Carbon supports universal procedure pointers (UPPs), applications should use ProcPtrs for their own code and plug-ins and use the new system-supplied UPP creation functions for Toolbox callback UPPs. You still need to dispose of those UPPs (using the corresponding disposal function), so that any allocated memory can be cleaned up when your application is running on Mac OS 8 or 9.

CallUniversalProc

Not available in CarbonLib. Not available in Mac OS X.

DisposeRoutineDescriptor

Use a specific UPP disposal routine; e.g., use Dispose ControlDefinitionProc instead of the more general function DisposeRoutineDescriptor. Not available in CarbonLib. Not available in Mac OS X.

NewRoutineDescriptor

Applications should use ProcPtrs for their own code and plug-ins, and use the system-supplied UPP creation functions (such as NewModalFilterProc) for Toolbox callback UPPs. You still need to dispose of those UPPs using the appropriate system-supplied disposal function so that any allocated memory can be cleaned up when your application is running on Mac OS 8 or 9. Not available in CarbonLib. Not available in Mac OS X.

Patch Manager

Carbon does not support the Patch Manager and there currently is no direct replacement. However, you can programmatically extend the system in various ways, such as by loading plug-ins or shared libraries, or by writing I/O Kit drivers or other kernel extensions.

NGetTrapAddress

Not available in CarbonLib. Not available in Mac OS X.

Common OS Services

Disk Initialization Manager

Carbon does not support the Disk Initialization Manager. Disk initialization is supported by the system. Mac OS X applications that need to initialize disks can do so using new APIs in the IOKit.

Note that Carbon does not support the diskEvt event. If your application needs to identify disk events, you will need to handle volume events which will be available in the Carbon Event Manager.

DIBadMount

Not available in CarbonLib. Not available in Mac OS X.

DILoad

Not available in CarbonLib. Not available in Mac OS X.

DIUnload

Not available in CarbonLib. Not available in Mac OS X.

Graphics Services

Printing Manager

The original Printing Manager defined in Printing.h is not supported in Carbon. Carbon applications must use the Carbon Printing Manager.

PrClose

Replace PrClose with PMRelease. Not available in CarbonLib. Not available in Mac OS X.

PrCloseDoc

Replace PrCloseDoc with PMSessionEndDocument. Not available in CarbonLib. Not available in Mac OS X.

PrClosePage

Replace PrClosePage with PMSessionEndPage. Not available in CarbonLib. Not available in Mac OS X.

PrError

Replace PrError with PMSessionError. Not available in CarbonLib. Not available in Mac OS X.

PrJobDialog

Replace PrJobDialog with PMSessionPrintDialog. Not available in CarbonLib. Not available in Mac OS X.

PrOpen

Replace PrOpen with PMCreateSession. Not available in CarbonLib. Not available in Mac OS X.

PrOpenDoc

Replace PrOpenDoc with PMSessionBeginDocument. Not available in CarbonLib. Not available in Mac OS X.

PrOpenPage

Replace PrOpenPage with PMSessionBeginPage. Not available in CarbonLib. Not available in Mac OS X.

PrPicFile

This function is obsolete. Printer drivers must perform their own spooling. Not available in CarbonLib. Not available in Mac OS X.

PrStlDialog

Replace PrStlDialog with PMSessionPageSetUpDialog. Not available in CarbonLib. Not available in Mac OS X.

PrintDefault

Replace PrintDefault with calls to PMSessionDefaultPageFormat and PMSessionDefaultPrintSettings. Not available in CarbonLib. Not available in Mac OS X.

QuickDraw Manager

Carbon supports most of the QuickDraw programming interface.

Carbon applications should use CreateNewPort and DisposePort to open and close graphics ports, rather than OpenPort, OpenCPort, ClosePort, and CloseCPort.

Carbon adds functions to get and set port data without accessing port data structures directly. For example, you can use such functions as GetPixBounds, GetPortFillPixPat, SetPortBounds, and SetPortPenSize.

In the past, parts of QuickDraw have been documented in Inside Macintosh as the Color Manager and Cursor Utilities. Note, however, that Inside Macintosh: Imaging with QuickDraw describes animated cursor functions, such as SpinCursor, that are available in the MPW programming environment and possibly in other environments, but not in system software. These animated cursor functions, which are defined in the MPW interface file CursorCtl.h, are not supported by Carbon.

ClosePort

Carbon applications should use CreateNewPort and DisposePort to open and close graphics ports. Not available in CarbonLib. Not available in Mac OS X.

InitGraf

In Carbon, the Mac OS automatically initializes Quickdraw for every application. When the Mac OS initializes QuickDraw, the Mac OS also automatically calls InitGraf.

Not available in CarbonLib. Not available in Mac OS X.

OpenPort

Carbon applications should use the functions NewGWorld and CreateNewPort to open graphics ports.

Note that while OpenPort creates a GrafPort structure with an associated BitMap structure, OpenPort's Carbon replacements—NewGWorld and CreateNewPort—create a CGrafPort structure with an associated PixMap structure.

Which of the two replacement functions should you use? That depends on the task, but NewGWorld is often more suitable than CreateNewPort, because NewGWorld gives the caller more control over the characteristics of the new port.

Here's an example of a task for which NewGWorld is the better choice. Some QuickDraw functions, such as CalcCMask and SeedCFill, require you to supply an output buffer (specified in the dstBits argument) with a 1-bit pixel depth. Prior to Carbon, OpenPort was used to create a BitMap for this purpose. OpenPort's Carbon replacement functions both create PixMaps.

BitMaps and PixMaps differ in a number of ways. One important difference is that a BitMap has a 1-bit pixel depth, while a PixMap can have a pixel depth of 1, 2, 4, 8, 16 or 32. NewGWorld allows you to specify the pixel depth of the new PixMap, whereas CreateNewPort always uses the depth of the main screen device.

Before calling the functions CalcCMask and SeedCFill, you can use NewGWorld to create an offscreen GWorld with a 1-bit pixel depth. Pass the address of this GWorld to the function GetPortBitMapForCopyBits, which returns a pointer to a BitMap. Use this pointer as the dstBits parameter for CalcCMask and SeedCFill (and CopyBits, of course).

Not available in CarbonLib. Not available in Mac OS X.

Hardware Interfaces

Device Manager

Carbon does not support the Device Manager as an interface for installing or interacting with device drivers. Carbon supports only the Device Manager APIs that allow applications to read and write to open files.

Other software products (such as desk accessories) that have relied on the Device Manager interface in the past should be converted into Carbon applications.

In Mac OS X, applications can access serial devices through the device file system. An application uses the I/O Kit to obtain a path to a device file in the /dev directory. It can then use traditional UNIX serial port access through the POSIX termios API. For more detail, see Inside Mac OS X: Accessing Hardware From Applications.

CloseDeskAcc

Not available in CarbonLib. Not available in Mac OS X.

OpenDeskAcc

Desk accessories are not supported in Carbon. Not available in CarbonLib. Not available in Mac OS X.

Human Interface Toolbox

Dialog Manager

Carbon supports the majority of the Dialog Manager. However, your application must access Dialog Manager data structures only through the supplied accessor functions. Furthermore, your application must use the functions provided for creating and disposing of Dialog Manager data structures.

InitDialogs

InitDialogs is not supported in Carbon. There is no need to initialize the Dialog Manager because the shared library is loaded as needed. Not available in CarbonLib. Not available in Mac OS X.

Event Manager

Carbon supports the majority of the Event Manager.

High-level events APIs (as contained in EPPC.h) are not supported. You should use Apple events instead.

Carbon does not support the diskEvt event. Support for volume mount and unmount events will be available in the Carbon Event Manager.

Carbon does not set the convertClipboardFlag in the EventRecord to indicate that the scrap has changed while the application was suspended. You should call the Scrap Manager function GetCurrentScrap instead.

Low-level event queue functions, such as GetEvQHdr and PPostEvent, are no longer supported.

Application-defined function-key procedures are not supported in Carbon.

Note that Carbon introduces a new event model to the Mac OS, with a new set of APIs. Developers are strongly encouraged to use the Carbon Event Manager APIs in place of the Event Manager APIs. The Carbon Event Manager offers a simple yet flexible approach to event handling that greatly reduces the amount of code needed to write a basic application. Morevover, the Carbon Event Manager's streamlined event handling enhances system performance on Mac OS X through more efficient allocation of processing time. Applications that use the Carbon Event Manager not only run better on Mac OS X, they help improve overall performance and responsiveness, creating a better experience for our customers.

GetEvQHdr

Returns a global system data structure, so it will not be supported in the future. Not available in CarbonLib. Not available in Mac OS X.

SystemClick

Desk accessories are not supported in Carbon. Not available in CarbonLib. Not available in Mac OS X.

Menu Manager

Carbon supports the Menu Manager, with the following changes:

• Your application must use the functions defined by the Menu Manager whenever it creates and disposes of Menu Manager data structures. Some applications, for example, create menus by using the Resource Manager function GetResource (instead of the Menu Manager function GetMenu) and dispose of them by calling ReleaseResource instead of DisposeMenu. This practice is not supported in Carbon.

• The MenuInfo structure is opaque in Carbon. You must revise your application so that it accesses Menu Manager data structures only through accessor functions.

• There are several Menu Manager functions that deal with manipulating menu color information tables. Apple recommends that you stop using them. The Appearance Manager generally disregards these color tables and instead uses the colors defined for the current appearance.

• You are strongly encouraged to adopt the standard Mac OS 8 menu definition procedures (also known as MDEFs) in your application. Your menus will then inherit the systemwide appearance and, furthermore, take advantage of other Menu Manager enhancements planned for the future. Note, however, that if you must use custom menu definition procedures, you must compile them as PowerPC-native code.

CheckItem

CheckItem has been renamed to CheckMenuItem in Carbon. Not available in CarbonLib. Not available in Mac OS X.

CountMItems

CountMItems has been renamed to CountMenuItems in Carbon. Not available in CarbonLib. Not available in Mac OS X.

DisableItem

Replaced by DisableMenuItem. Not available in CarbonLib. Not available in Mac OS X.

EnableItem

Replaced by EnableMenuItem. Not available in CarbonLib. Not available in Mac OS X.

InitMenus

InitMenus is not supported in Carbon. There is no need to initialize the Menu Manager because the shared library is loaded as needed. Not available in CarbonLib. Not available in Mac OS X.

SystemEdit

Carbon does not support desk accessories. Not available in CarbonLib. Not available in Mac OS X.

Scrap Manager

Carbon supports only the LoadScrap and UnloadScrap functions from the original Scrap Manager. However, Carbon supplies new features, including support for "promises," to the Scrap Manager.

GetScrap

You should instead use the functions GetScrapFlavorSize and GetScrapFlavorData. Not available in CarbonLib. Not available in Mac OS X.

PutScrap

You should instead use the function PutScrapFlavor. Not available in CarbonLib. Not available in Mac OS X.

ZeroScrap

You should instead use the function ClearCurrentScrap. Not available in CarbonLib. Not available in Mac OS X.

Standard File Package

Carbon does not support the Standard File Package. You must use Navigation Services instead.

StandardGetFile

Not available in CarbonLib. Not available in Mac OS X.

StandardPutFile

Not available in CarbonLib. Not available in Mac OS X.

Window Manager

Carbon supports the Window Manager. Be aware, however, that if you use custom window definition procedures (also known as WDEFs), you must compile them as PowerPC-native code. In addition:

• Your application must use the functions defined by the Window Manager whenever it creates and disposes of Window Manager data structures. For example, instead of directly creating and disposing of window records, applications must call such Window Manager functions as GetNewCWindow and DisposeWindow.

• You must revise your application so that it accesses Window Manager data structures only through accessor functions.

• You are encouraged to adopt the standard Mac OS 8 window definition procedures in your application. Applications that use the standard Mac OS 8 window definition procedures inherit the Mac OS 8 human interface appearance. Applications that use custom window definition procedures work correctly, but because custom definition procedures invoke their own drawing routines, Mac OS 8 can’t draw these applications with the current appearance.

CloseWindow

The CloseWindow function is not supported because developers do not allocate their own memory for windows in Carbon. Use the DisposeWindow function to remove a window instead. Not available in CarbonLib. Not available in Mac OS X.

GetWMgrPort

Carbon does not support accessing the Window Manager port. You should draw into your own graphics port instead. Not available in CarbonLib. Not available in Mac OS X.

InitWindows

InitWindows is not supported in Carbon. There is no need to initialize the Window Manager because the shared library is loaded as needed. Not available in CarbonLib. Not available in Mac OS X.

InvalRect

Calls InvalWindowRect, which takes a window pointer as an additional parameter.

Invalidation works on windows, not ports, and because windows are not ports in Carbon, this change is necessary. Not available in CarbonLib. Not available in Mac OS X.

ValidRect

Calls ValidWindowRect, which takes a window pointer as an additional parameter. Validation works on windows, not ports, and because windows are not ports in Carbon, this change is necessary. Not available in CarbonLib. Not available in Mac OS X.

Text and Other International Services

Font Manager

Carbon supports most Font Manager functions. However, you no longer have direct access to Font Manager data structures, and you are not able to access the list of fonts (or the data in those fonts) using the Resource Manager. You should modify your application to use the new accessor functions.

InitFonts

There is no need to initialize the Font Manager because the shared library is loaded as needed. Not available in CarbonLib. Not available in Mac OS X.

TextEdit

Carbon supports most TextEdit functions, but TextEdit functionality has been replaced by Multilingual Text Engine (MLTE). Although there is not a one-to-one correspondence between APIs in these two technologies, you are encouraged to use MLTE in place of TextEdit.

The Carbon version of TextEdit replaces the low memory accessors for TextEdit structures as follows:

TEGet/SetScrapLength replaces LMGet/SetTEScrpLength

TEGet/SetScrapHandle replaces LMGet/SetTEScrpHandle

TEGet/SetDoTextHook replaces LMGet/SetTEDoText

TEGet/SetRecalcHook replaces LMGet/SetTERecal

The Carbon version also has a new accessor for the FindWord hook: TEGet/SetFindWordHook.

TESetWordBreak is not available in Carbon, and you should not override wordBreak in order to customize wordBreak behavior. Instead, override the FindWord hook using the TEGet/SetFindWordHook accessors. Previously, the wordBreak hook was used on Roman-only systems, a distinction that no longer exists in Carbon. TERec's wordBreak field is ignored in Carbon.

TEInit

There is no need to initialize TextEdit because the shared library is loaded as needed. Not available in CarbonLib. Not available in Mac OS X.

Address

Access Type

Located in Function

Comments

No Invalid Access Detected

No resources loaded into system heap.