This chapter discusses 64-bit changes in the Carbon Human Interface Toolbox, which includes APIs in the HIToolbox, HIServices, and Navigation Services frameworks. The APIs are listed in alphabetical order.
Note: To find out if a specific function is not available to 64-bit applications, you can check the API reference documentation in the ADC Reference Library, use the Xcode 3.0 Research Assistant, or consult the relevant header file.
Carbon: Appearance.h
Most Appearance Manager functions are not available to 64-bit applications. The Appearance Manager is largely based on QuickDraw, while the newer HITheme API is based on Quartz 2D. You should use HITheme to draw appearance primitives. Refer to Appearance Manager Reference for detailed information about function availability.
The function GetThemeMetric
is available so that 64-bit applications can determine:
How large various theme-capable objects should be
The size of the bounding rectangle to pass to HITheme functions to get the right appearance
Carbon: MacApplication.h
A number of functions in the Application Manager are not available to 64-bit applications. Refer to Application Manager Reference for detailed information about function availability.
Because there are no Cocoa equivalents, the following functions are still available:
Carbon: CarbonEvents.h, CarbonEventsCore.h
Some Carbon Event Manager functions and events are not available to 64-bit applications. Refer to Carbon Event Manager Reference for detailed information about function availability. To learn about handling events in Cocoa, see Cocoa Event-Handling Guide.
With the introduction of 64-bit support in the Carbon Event Manager, four kinds of event parameters require changes to their underlying data types. The parameters that have changed are used to pass user-specified data, byte counts, byte offsets, and graphics devices.
In the case of refcon data, byte counts, and byte offsets, these parameters use typeSInt32
or typeLongInteger
as the event parameter type prior to Mac OS X v10.5. Unfortunately, typeSInt32
and typeLongInteger
specify a 32-bit value, and in Mac OS X v10.5, these parameters must be 64 bits wide when compiling for the 64-bit API so that 64-bit pointers, byte counts, and byte offsets may be passed without truncation.
The Carbon Event Manager defines three new event parameter types to provide source compatibility between 32-bit and 64-bit applications: typeRefCon
, typeByteCount
, and typeByteOffset
. Use of these new types by 32-bit applications is optional. The toolbox provides automatic coercion between the old and new types so existing applications will continue to run. You may recompile your 32-bit application in Mac OS X v10.5 without modification, but in a 64-bit application you must modify your source to use the new types.
The actual value of these constants depends on whether you are compiling for a 32-bit or 64-bit target and on the value of the preprocessor macro MAC_OS_X_VERSION_MIN_REQUIRED
, which specifies the minimum Mac OS X system version on which your application will run.
When compiling your code using the Mac OS X v10.5 header files, if you want your code to run cleanly in both 32-bit and 64-bit targets, you should modify your calls to GetEventParameter
to use typeRefCon
, typeByteCount
, or typeByteOffset
instead of typeSInt32
or typeLongInteger
. Using these preferred types will allow your 32-bit application to run in Mac OS X v10.5 and earlier, and will allow your 64-bit application to run in Mac OS X v10.5 and later.
Note that when you extract data from an event parameter of type typeRefCon
, the data type of the variable to which the parameter data is written should always be pointer sized; in other words, use SRefCon
, URefCon
, or PRefCon
, not SInt32
. Using a 32-bit variable will fail on 64-bit targets. Similarly, when extracting data from an event parameter of type typeByteCount
or typeByteOffset
, always use the corresponding standard type (ByteCount
or ByteOffset
), and use sizeof(ByteCount)
or sizeof(ByteOffset)
, not sizeof(SInt32)
or sizeof(UInt32)
, to specify the amount of data that you need.
The following Carbon events use typeRefCon
:
kEventTSMDocumentAccessGetLength |
kEventTSMDocumentAccessGetSelectedRange |
kEventTSMDocumentAccessGetCharactersPtr |
kEventTSMDocumentAccessGetCharactersPtrForLargestBuffer |
kEventTSMDocumentAccessGetCharacters |
kEventTSMDocumentAccessGetFont |
kEventTSMDocumentAccessGetGlyphInfo |
kEventTSMDocumentAccessLockDocument |
kEventTSMDocumentAccessUnlockDocument |
kEventTextInputUpdateActiveInputArea |
kEventTextInputUnicodeForKeyEvent |
kEventTextInputOffsetToPos |
kEventTextInputPosToOffset |
kEventTextInputShowHideBottomWindow |
kEventTextInputGetSelectedText |
kEventTextInputFilterText |
kEventAppLaunchNotification |
kEventControlArbitraryMessage |
The following Carbon events use typeByteCount
:
kEventTextInputUpdateActiveInputArea |
kEventControlSetData |
kEventControlGetData |
The following Carbon events use typeByteOffset
:
kEventTextInputOffsetToPos |
kEventTextInputPosToOffset |
In the case of graphics devices, some event parameters used typeGDHandle
prior to Mac OS X v10.5. However, the GDHandle
type is not available to 64-bit applications at runtime. In Mac OS X v10.5 and later, these parameters contain values of type CGDirectDisplayID
instead.
The Carbon Event Manager defines a new event parameter type, typeCGDisplayID
, to indicate that the data type of a graphics device event parameter is CGDirectDisplayID
instead of GDHandle
. You need to explicitly choose in your code the type of graphics device identifier you need. Use of typeCGDisplayID
by 32-bit applications is optional. The toolbox provides automatic coercion between typeCGDisplayID
and typeGDHandle
, so existing applications will continue to run. You may recompile a 32-bit application in Mac OS X v10.5 without modification, but in a 64-bit application you must use typeCGDisplayID
to retrieve the graphics device identifier.
The following 32-bit Carbon events use typeCGDisplayID
:
kEventAppAvailableWindowBoundsChanged |
kEventWindowConstrain |
kEventMenuGetFrameBounds |
Carbon: MacHelp.h
The Carbon Help Manager is used to display help tags for elements in an application’s user interface. You typically define help tags in Interface Builder, where they are called tool tips.
The Carbon Help Manager is not available to 64-bit applications. To learn about displaying help tags for Cocoa views, see Online Help.
Carbon: Controls.h and related headers
The Control Manager is not available to 64-bit applications. In a Cocoa user interface, you must use Cocoa controls. See Control and Cell Programming Topics for Cocoa.
Carbon: HIDataBrowser.h
The Data Browser is not available to 64-bit applications. The recommended replacements are the Cocoa classes NSBrowser
, NSTableView
, and NSOutlineView
. For additional information about Cocoa browsers, see Browsers.
Carbon: Dialogs.h
The Dialog Manager is not available to 64-bit applications. Cocoa provides both sheet and application-model dialogs. For information about using dialogs or panels in Cocoa, see Window Programming Guide and Sheet Programming Topics.
Carbon: Drag.h
The Drag Manager is not available to 64-bit applications. For information about drag-and-drop capabilities in Cocoa windows and views, see Drag and Drop Programming Topics for Cocoa.
Carbon: Events.h
Most Event Manager functions are not available to 64-bit applications. Refer to Event Manager Reference for detailed information about function availability. To learn about handling events in Cocoa, see Cocoa Event-Handling Guide.
The GetMouse
function returns a point in local coordinates in the current graphics port. Since there is no QuickDraw graphics port in 64-bit applications, this function is not available. You should use the Carbon Event Manager function HIGetMousePosition
instead. See Carbon/HIToolbox/CarbonEventsCore.h
.
The KeyTranslate
function is not available. You should use UCKeyTranslate
in Unicode Utilities instead.
Carbon: HIArchive.h
HIArchive is not available to 64-bit applications. Cocoa provides archiving capabilities for both data and objects. For more information, see Archives and Serializations Programming Guide.
Carbon: HIGeometry.h
The HIGetScaleFactor
function returns the scale factor of an application’s user interface. This function is not available to 64-bit applications, which must use Cocoa to implement their user interfaces. The Cocoa classes NSScreen
and NSWindow
have methods that return the same information.
Carbon: HIObject.h
Some HIObject functions are not available to 64-bit applications. Refer to HIObject Reference for detailed information about function availability. In Cocoa, most objects are subclasses of the NSObject
class. For more information about NSObject
, see Cocoa Fundamentals Guide.
ApplicationServices: HIShape.h
The HIShapeSetQDClip
function sets the current clip in a graphics port to a shape. Since there is no QuickDraw graphics port in 64-bit applications, this function has been removed. You should use HIShapeReplacePathInCGContext
followed by CGContextClip
instead.
Carbon: HIToolbar.h
HIToolbar is not available to 64-bit applications. Window toolbars are an integral feature in Cocoa. For more information, see Toolbar Programming Topics for Cocoa.
Carbon: HIView.h and related headers
HIView is not available to 64-bit applications. The NSView
class in Cocoa defines the basic drawing, event-handling, and printing architecture of an application. For more information, see Cocoa Fundamentals Guide and View Programming Guide.
Carbon: IBCarbonRuntime.h
Interface Builder Services includes functions such as CreateNibReference
that are used to instantiate user interface objects from Carbon nib files.
Interface Builder Services is not available to 64-bit applications. If you’re developing a 64-bit application, you should design a nib-based Cocoa user interface and use Cocoa to instantiate the user interface at runtime. To learn more about Cocoa nib files, see Resource Programming Guide.
Carbon: Keyboards.h
All functions in Keyboard Layout Services except KBGetLayoutType
have been deprecated and are not available to 64-bit applications. The replacement functions are in the new Text Input Source Services API. For more information, see Text Input Source Services Reference.
Carbon: Lists.h
The List Manager is deprecated in Mac OS X v10.5 and is not available to 64-bit applications. The recommended replacements are the Cocoa classes NSBrowser
, NSTableView
, and NSOutlineView
. For additional information about Cocoa browsers, see Browsers.
Carbon: Menus.h
Most Menu Manager functions are not available to 64-bit applications. Refer to Menu Manager Reference for detailed information about function availability. The Cocoa classes NSMenu
and NSMenuItem
are the basis for all types of menus in a Cocoa user interface. See Application Menu and Pop-up List Programming Topics.
The contextual menu plug-in functionality is not available to 64-bit applications. CM plug-ins are ignored by 64-bit applications and never given a chance to add menu items to a contextual menu before it is displayed. In Mac OS X v10.6 and later, the recommended replacement is Cocoa services. Cocoa adds menu items provided by services to the contextual menus displayed by Cocoa applications. For more information, see Services Implementation Guide.
Carbon: MacTextEditor.h, HITextViews.h
MLTE is not available to 64-bit applications. You should use the Cocoa text system instead. For information about the Cocoa text system, see Text System Overview.
Carbon: Navigation.h
Navigation Services is not available to 64-bit applications. Navigation Services dialogs are now implemented using the Cocoa classes NSOpenPanel
and NSSavePanel
. In 64-bit applications, you must use these classes directly.
Carbon: Notification.h
The Notification Manager is not available to 64-bit applications. The recommended replacement is CFUserNotification, which is designed for use in applications that do not otherwise have user interfaces but may need occasional interaction with the user. For more information, see CFUserNotification Reference.
For information about notifications in Cocoa, see Notification Programming Topics. For general guidelines about user notifications from background processes and applications, see Apple Human Interface Guidelines.
Carbon: Scrap.h
The Scrap Manager is deprecated in Mac OS X v10.5 and is not available to 64-bit applications. The recommended replacements are the Pasteboard Manager or the Cocoa class NSPasteboard
. For more information, see Pasteboard Manager Programming Guide or Pasteboard Programming Topics for Cocoa.
Carbon: TextEdit.h, TSMTE.h
The TextEdit Manager and Text Services Manager for Text Edit (TSMTE) are not available to 64-bit applications. You should use Cocoa text views instead. For more information, see Text Editing Programming Guide.
Carbon: TextServices.h
Almost all Text Services Manager (TSM) functions are not available to 64-bit applications. The replacement for most of these functions is the new Text Input Source Services API. For more information, see Text Input Source Services Reference.
The TSMSetInlineInputRegion
function, which depends on QuickDraw regions, is not available. A new Carbon event, kEventTextInputIsMouseEventInInlineInputArea
, replaces this function.
The Text Services Manager Apple events are not sent or handled in 64-bit applications. These events were deprecated in Mac OS X v10.0. You should use the TSM Carbon events instead.
Carbon: MacWindows.h
The Window Manager is not available to 64-bit applications. For information about using windows in a Cocoa user interface, see Window Programming Guide.
Last updated: 2009-04-27