Changes in the Human Interface Toolbox

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.

Appearance Manager

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:

Application Manager

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 Event Manager

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.

Carbon Event Parameters

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.

Refcon Data, Byte Counts, and Byte Offsets

In the case of refcon data, byte counts, and byte offsets, these parameters use typeSInt32 or typeLongInteger as the event parameter type prior to OS X v10.5. Unfortunately, typeSInt32 and typeLongInteger specify a 32-bit value, and in 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 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 OS X system version on which your application will run.

When compiling your code using the 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 OS X v10.5 and earlier, and will allow your 64-bit application to run in 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

Graphics Devices

In the case of graphics devices, some event parameters used typeGDHandle prior to OS X v10.5. However, the GDHandle type is not available to 64-bit applications at runtime. In 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 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 Help Manager

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.

Control Manager

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.

Data Browser

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 Browser Programming Topics.

Dialog Manager

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.

Drag Manager

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.

Event Manager

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.

HIArchive

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.

HIGeometry

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.

HIObject

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.

HIShape

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.

HIToolbar

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.

HIView

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.

Interface Builder Services

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.

Keyboard Layout Services

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.

List Manager

Carbon: Lists.h

The List Manager is deprecated in 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 Browser Programming Topics.

Menu Manager

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

Multilingual Text Engine (MLTE)

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.

Navigation Services

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.

Notification Manager

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.

Scrap Manager

Carbon: Scrap.h

The Scrap Manager is deprecated in 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.

TextEdit Manager

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.

Text Services Manager

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 OS X v10.0. You should use the TSM Carbon events instead.

Window Manager

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.



Copyright © 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-04-23