Mac OS X 10.3.9 Developer Release Notes:
High Level Toolbox and Navigation Services
Version Checking
If you need to check for a specific version of the HIToolbox framework, you can use either the kHIToolboxVersionNumber global variable (on 10.3 and later) or the CFBundleShortVersionString in the HIToolbox Info.plist dictionary. kHIToolboxVersionNumber contains the HIToolbox build number, which is incremented each time that HIToolbox is rebuilt during the course of a Mac OS X release; CFBundleShortVersionString contains a separate non-incrementing HIToolbox version for a given Mac OS X release. To test for the HIToolbox included in Mac OS X 10.3.9, check that kHIToolboxVersionNumber is at least 145.48, or that CFBundleShortVersionString is at least 1.3.6.
This sample code shows how to check the framework short version:
CFBundleRef bundle;
CFStringRef versionStr = NULL;
UInt32 version = 0;
bundle = CFBundleGetBundleWithIdentifier( CFSTR("com.apple.HIToolbox") );
if ( bundle != NULL )
versionStr = CFBundleGetValueForInfoDictionaryKey( bundle, CFSTR("CFBundleShortVersionString") );
if ( versionStr != NULL && CFGetTypeID( versionStr ) == CFStringGetTypeID() )
{
int major = 0, minor = 0, bugfix = 0;
char sz[20];
CFStringGetCString( versionStr, sz, sizeof( sz ), kCFStringEncodingUTF8 );
sscanf( sz, "%d.%d.%d", &major, &minor, &bugfix );
version = ( major << 8 ) + ( minor << 4 ) + bugfix;
}
if ( version >= 0x136 )
// we have an HIToolbox with these fixes
else
// we do not have an HIToolbox with these fixes
To check for the presence of bug fixes to the NavigationServices framework, you can use the CFBundleShortVersionString in the NavigationServices Info.plist dictionary. To test for the NavigationServices included in Mac OS X 10.3.9, check that CFBundleShortVersionString is at least 3.3.3.
HIToolbox Framework
Menu Manager
A crash could occur when the user clicked on a menu title, moved the mouse into an empty portion of the menubar, and then pressed a key (3681276).
NavigationServices Framework
In Mac OS X 10.3.5 and later, the NavDialogSetSaveFileExtensionHidden API could crash (3771170).
Mac OS X 10.3.5 Developer Release Notes:
High Level Toolbox and Navigation Services
Version Checking
If you need to check for a specific version of the HIToolbox framework, you can use either the kHIToolboxVersionNumber global variable (on 10.3 and later) or the CFBundleShortVersionString in the HIToolbox Info.plist dictionary. kHIToolboxVersionNumber contains the HIToolbox build number, which is incremented each time that HIToolbox is rebuilt during the course of a Mac OS X release; CFBundleShortVersionString contains a separate non-incrementing HIToolbox version for a given Mac OS X release. To test for the HIToolbox included in Mac OS X 10.3.5, check that kHIToolboxVersionNumber is at least 145.42, or that CFBundleShortVersionString is at least 1.3.4.
This sample code shows how to check the framework short version:
CFBundleRef bundle;
CFStringRef versionStr = NULL;
UInt32 version = 0;
bundle = CFBundleGetBundleWithIdentifier( CFSTR("com.apple.HIToolbox") );
if ( bundle != NULL )
versionStr = CFBundleGetValueForInfoDictionaryKey( bundle, CFSTR("CFBundleShortVersionString") );
if ( versionStr != NULL && CFGetTypeID( versionStr ) == CFStringGetTypeID() )
{
int major = 0, minor = 0, bugfix = 0;
char sz[20];
CFStringGetCString( versionStr, sz, sizeof( sz ), kCFStringEncodingUTF8 );
sscanf( sz, "%d.%d.%d", &major, &minor, &bugfix );
version = ( major << 8 ) + ( minor << 4 ) + bugfix;
}
if ( version >= 0x134 )
// we have an HIToolbox with these fixes
else
// we do not have an HIToolbox with these fixes
To check for the presence of bug fixes to the NavigationServices framework, you can use the CFBundleShortVersionString in the NavigationServices Info.plist dictionary. To test for the NavigationServices included in Mac OS X 10.3.5, check that CFBundleShortVersionString is at least 3.3.2.
HIToolbox Framework
Control Manager
The EditUnicodeText and HISearchField controls no longer clear their focus if asked to focus on the edit field part an even number of times (3636345).
The kEventTextAccepted event is now sent by Unicode-based edit controls in response to Return or Enter (3672631).
The HILayout implementation now removes its event handlers from other views when a view with layout data is disposed (3657566).
We introduced a regression in the Image well and Picture controls in Mac OS X 10.3.4 that caused these controls to draw outside of the clipping region for the GrafPort. This regression has been fixed (3673139).
Menu Manager
A crash could sometimes occur when a menu was inserted into the hierarchical portion of the menubar, removed, and then another menu with the same ID was inserted (3615228).
Command keys were sometimes ignored when using Carbon Events (kEventMenuEnableItems or kEventCommandUpdateStatus) to enable or disable menu items (3630620).
A crash could occur in CreateStandardFontMenu when certain fonts lacking font name info were installed (3663531).
MLTE
A crash could occur after a drag&drop operation near a text field (3599055).
NavigationServices Framework
In Mac OS X 10.3.5 we have focused on fixing as many as possible of the known problems with packaged document support in NavigationServices. If you encounter other problems with packaged documents, please file bugs as soon as possible and we will attempt to fix any remaining problems in Mac OS X Tiger.
The "Can't Replace Folder" dialog is no longer shown when saving over a folder if the folder is a package and kNavSupportPackages is set (3680431).
In a GetFileDialog with kNavSupportPackages turned on, double-clicking on a package folder now returns the folder to the application, exactly as if the user had pressed the Open button (3680424). This fixes a regression in Panther.
A GetFileDialog now allows descent into package folders, if kNavAllowOpenPackages and kNavSupportPackages are set, even if the caller has also specified a type list (3690187).
The NavDialogGetSaveFileExtensionHidden and NavDialogSetSaveFileExtensionHidden APIs were previously just stubs. They are now fully implemented and functional (3688239).
NavigationServices could crash if the Connect to Server dialog was canceled (3690191).
Compatibility issues with Macromedia Director MX (3459308), Eudora 6.0 and 6.0.1 (3690189), and Quicken (3690193) were fixed.
Mac OS X 10.3.4 Developer Release Notes:
High Level Toolbox and HIServices
Version Checking
If you need to check for a specific version of the HIToolbox framework, you can use either the kHIToolboxVersionNumber global variable (on 10.3 and later) or the CFBundleShortVersionString in the HIToolbox Info.plist dictionary. kHIToolboxVersionNumber contains the HIToolbox build number, which is incremented each time that HIToolbox is rebuilt during the course of a Mac OS X release; CFBundleShortVersionString contains a separate non-incrementing HIToolbox version for a given Mac OS X release. To test for the HIToolbox included in Mac OS X 10.3.4, check that kHIToolboxVersionNumber is at least 145.41, or that CFBundleShortVersionString is at least 1.3.3.
This sample code shows how to check the framework short version:
CFBundleRef bundle;
CFStringRef versionStr = NULL;
UInt32 version = 0;
bundle = CFBundleGetBundleWithIdentifier( CFSTR("com.apple.HIToolbox") );
if ( bundle != NULL )
versionStr = CFBundleGetValueForInfoDictionaryKey( bundle, CFSTR("CFBundleShortVersionString") );
if ( versionStr != NULL && CFGetTypeID( versionStr ) == CFStringGetTypeID() )
{
int major = 0, minor = 0, bugfix = 0;
char sz[20];
CFStringGetCString( versionStr, sz, sizeof( sz ), kCFStringEncodingUTF8 );
sscanf( sz, "%d.%d.%d", &major, &minor, &bugfix );
version = ( major << 8 ) + ( minor << 4 ) + bugfix;
}
if ( version >= 0x133 )
// we have an HIToolbox with these fixes
else
// we do not have an HIToolbox with these fixes
To check for the presence of bug fixes to the HIServices framework, you can use the CFBundleShortVersionString in the HIServices Info.plist dictionary. To test for the HIServices included in Mac OS X 10.3.4, check that CFBundleShortVersionString is at least 1.4.1.
HIToolbox Framework
Control Manager
The HIViewSuspendLayout API introduced in Mac OS X 10.3 would deactivate its children instead of suspending their layouts (3609950).
The DataBrowser sometimes crashed when double-clicking on a folder in a Navigation Services Save As dialog (3449349).
The DataBrowser did not correctly position help tags when the browser control was used in a compositing window (3608039).
The slider control did not highlight the thumb when clicked if the control was used in a compositing window (3451159).
The picture and image well controls did not clip their drawing properly, sometimes causing drawing to extend outside the bounds of the control (3609945).
Drag Manager
SetDragImage would crash when passed an imagePixMap of NULL and an imageRgn that was either NULL or had empty bounds (3578669).
Menu Manager
Menus sometimes didn't display scrolling arrows when they should have (3563215).
A crash occurred if the user clicked on a menu title to enter sticky menu tracking mode, moved the mouse to the right past the last menu title, and then pressed the right arrow key (3578673).
The Dock sometimes behaved as if a modifier key was pressed when the user selected an item from a Dock menu (3609941).
Text Services Manager
It was not possible to use Unicode keyboards with ThinkFree Office (3604740).
Window Manager
The opaque area of Cocoa windows was sometimes reset by the Carbon Window Manager (3399650).
HIServices Framework
Internet Config
ICSetPref was returning an error when passed a data size of zero, instead of deleting the preference (3610583). This was a regression in Mac OS X 10.3.
InternetConfig APIs would sometimes return errors incorrectly when used to modify IC preferences (3610587). This prevented users from modifying the contents of the Internet control panel in Classic.
Mac OS X 10.3.3 Developer Release Notes:
High Level Toolbox and Navigation Services
Version Checking
If you need to check for a specific version of the HIToolbox framework, you can use either the kHIToolboxVersionNumber global variable (on 10.3 and later) or the CFBundleShortVersionString in the HIToolbox Info.plist dictionary. kHIToolboxVersionNumber contains the HIToolbox build number, which is incremented each time that HIToolbox is rebuilt during the course of a Mac OS X release; CFBundleShortVersionString contains a separate non-incrementing HIToolbox version for a given Mac OS X release. To test for the HIToolbox included in Mac OS X 10.3.3, check that kHIToolboxVersionNumber is at least 145.38, or that CFBundleShortVersionString is at least 1.3.2.
This sample code shows how to check the framework short version:
CFBundleRef bundle;
CFStringRef versionStr = NULL;
UInt32 version = 0;
bundle = CFBundleGetBundleWithIdentifier( CFSTR("com.apple.HIToolbox") );
if ( bundle != NULL )
versionStr = CFBundleGetValueForInfoDictionaryKey( bundle, CFSTR("CFBundleShortVersionString") );
if ( versionStr != NULL && CFGetTypeID( versionStr ) == CFStringGetTypeID() )
{
int major = 0, minor = 0, bugfix = 0;
char sz[20];
CFStringGetCString( versionStr, sz, sizeof( sz ), kCFStringEncodingUTF8 );
sscanf( sz, "%d.%d.%d", &major, &minor, &bugfix );
version = ( major << 8 ) + ( minor << 4 ) + bugfix;
}
if ( version >= 0x132 )
// we have an HIToolbox with these fixes
else
// we do not have an HIToolbox with these fixes
To check for the presence of bug fixes to the Navigation Services framework, you must examine the Mac OS X version number. These bug fixes will be present in Mac OS X 10.3.3 and later.
HIToolbox Framework
Control Manager
The popup button now honors its title justification again [3461583]. This fixes a regression in 10.3.0.
It is now possible to transfer a Unicode edit-text control from a non-compositing to a compositing window [3277641]. This fixes several related problems:
- it is now possible to create a Unicode edit-text control in an HIToolbar while passing a non-NULL WindowRef to the CreateEditUnicodeTextControl API.
- it is now possible to add a Unicode edit-text control to a Navigation Services dialog custom control area (see Technical Q&A 1315 for information on working around this problem on earlier versions of Mac OS X 10.3).
The Unicode edit-text control now obeys its background color [3479279]. This fixes a regression in Mac OS X 10.3.
The checkbox control now restores the current port's font after drawing [3512218]. This fixes a regression in Mac OS X 10.3 that caused a checkbox's custom font to be incorrectly used for other controls.
Help Manager
The Help Manager now detects when a window that is about to display a help tag is destroyed [3503768]. This fixes a problem in Mac OS X 10.3 that caused the port origin of application windows to become corrupted.
The HMDisplayTag API now retains the help content that is passed to it, and releases the content after the tag has closed [3531781]. Previously, the content was not retained, and since there was no notification to the client application when the tag was closed, it was difficult for the client to know how long the content should remain allocated.
The Help Manager previously attempted to release the contents of HMHelpContentRec.content[1].tagCFString if content[0].contentType was kHMCFStringLocalizedContent, even if content[1].contentType was kHMNoContent [3508377]. This bug is fixed and the Help Manager now only releases content[1].tagCFString if content[1].contentType is kHMCFStringContent or kHMCFStringLocalizedContent.
Menu Manager
Menu item icons that are formed by compositing multiple IconRefs are now drawn correctly when the item is hilited [3403770]. This fixes a regression in Mac OS X 10.3.
The menu attribute kMenuAttrDoNotUseUserCommandKeys, introduced in Mac OS X 10.3, now works properly [3514638]. Previously, it did not actually prevent the menu from using user command keys.
The Menu Manager now correctly updates the command key cache when a menu item with a command key in a popup menu is deleted [3517196]. Previously, the Menu Manager could corrupt the command key cache in this case, which could cause a crash during the next search for a command key.
MLTE
The TXNSetData API no longer crashes when large numbers of graphic objects are inserted [3524763].
Window Manager
When an inactive process becomes active, the Window Manager activates the window that was previously active when the process became inactive. The Window Manager now detects when a different window is made visible in front of the previously active window while the process is inactive, and now activates the newly visible window instead of the previously active window when the process becomes active [3436471].
Composited windows now redraw the entire content when the display bit depth changes [3482751]. In Mac OS X 10.2 (all versions) and earlier versions of Mac OS X 10.3, only the window frame was redrawn, which caused the window content to be erased and never redrawn if the display depth changed from millions to thousands to 256 colors.
NavigationServices Framework
In column view, Navigation Services dialogs now display a button labeled "Connect..." for servers inside /Network requiring authorization [3538558].
Navigation Services no longer sets the current port to an invalid GrafPtr when closing a sheet [3507494].
The Navigation Services dialogs for choosing a file, folder, or other filesystem object now use the word "Choose" instead of "Open" for the default button [3459301]. This fixes a regression in Mac OS X 10.3.
Mac OS X 10.3.2 Developer Release Notes:
High Level Toolbox
Version Checking
If you need to check for a specific version of the HIToolbox framework, you can use either the kHIToolboxVersionNumber global variable (on 10.3 and later) or the CFBundleShortVersionString in the HIToolbox Info.plist dictionary. kHIToolboxVersionNumber contains the HIToolbox build number, which is incremented each time that HIToolbox is rebuilt during the course of a Mac OS X release; CFBundleShortVersionString contains a separate non-incrementing HIToolbox version for a given Mac OS X release. To test for the HIToolbox included in Mac OS X 10.3.2, check that kHIToolboxVersionNumber is at least 145.35, or that CFBundleShortVersionString is at least 1.3.1.
This sample code shows how to check the framework short version:
CFBundleRef bundle;
CFStringRef versionStr = NULL;
UInt32 version = 0;
bundle = CFBundleGetBundleWithIdentifier( CFSTR("com.apple.HIToolbox") );
if ( bundle != NULL )
versionStr = CFBundleGetValueForInfoDictionaryKey( bundle, CFSTR("CFBundleShortVersionString") );
if ( versionStr != NULL && CFGetTypeID( versionStr ) == CFStringGetTypeID() )
{
int major = 0, minor = 0, bugfix = 0;
char sz[20];
CFStringGetCString( versionStr, sz, sizeof( sz ), kCFStringEncodingUTF8 );
sscanf( sz, "%d.%d.%d", &major, &minor, &bugfix );
version = ( major << 8 ) + ( minor << 4 ) + bugfix;
}
if ( version >= 0x131 )
// we have an HIToolbox with these fixes
else
// we do not have an HIToolbox with these fixes
Appearance Manager
The theme drawing engine was incorrectly clipping out drawing at very large coordinates (less than -10,000 and greater than +20,000) [3486693].
Theme primitives were not reloaded when the appearance changed from blue to graphite or vice versa [3486728].
Control Manager
SetKeyboardFocus did not clear the focused control in a window when called with kControlNoPart on a control that was already unfocused [3486694]. This caused problems with keyboard navigation of clock controls in PowerPlant-based applications.
The popup button control was failing to acquire the popup menu when the menu was inserted after the control was created [3486698]. This prevented the control from showing the popup menu when clicked.
The push button control was not setting up the clipping region before erasing its background, potentially allowing it to erase too much or too little [3486703].
The HISegmentedView control did not send command events when a segment was clicked [3486711]. A workaround for this bug on 10.3.0 is to use a kEventControlHit handler to detect clicks on the control.
The HISegmentedView control did not draw or track properly when embedded in an HIToolbar [3486712].
The HISegmentedViewGetSegmentBehavior API was returning the segment's enable state rather than its behavior [3486713].
Event Manager
The Control Manager would enter its default mouse-tracking loop in response to a click in an HIView at a location where hit-testing the view returned a part code of zero [3486697]. Previously, the Control Manager only began mouse tracking if the hit test returned a non-zero part code.
When a classic Event Manager API returned a null EventRecord, the event.modifiers field contained the modifiers from the most recently dispatched kEventRawKeyModifiersChanged event, rather than the current hardware modifiers, which might have changed since the last event was dispatched [3486716].
Menu Manager
kEventMenuClosed was being sent after the menu's window had been hidden, but before the menu's WindowRef was marked invisible [3486690]. This caused windows shown by handlers for this event to be z-ordered improperly.
Menus displayed by NSStatusItems were invisible if the owning process was deactivated or hidden [3486706, 3486707].
MenuSelect was returning a non-zero value when the mouse was released over an item in a menu in which item zero (the menu title) had been disabled [3486723]. Disabling the menu title also disables all of the items in the menu, so no item can ever be selected and the proper return value is zero.
Command key matching was broken when the caps lock key was pressed [3486725].
When the SetSystemUIMode API was used to disable the Apple menu and disable the Force Quit dialog, it was still possible in Cocoa applications to use cmd-shift-option-Escape to quit the application [3497890].
Text Services Manager
A crash sometimes occurred during text input using the bottom-line input window [3475879, 3475953].
The Special Characters palette would continuously open after sleep or login for some users [3475984].
Unicode keyboards were unavailable if an application called UseInputWindow without setting kTSMDocumentUnicodeInputWindowPropertyTag for the TSMDocument [3477289].
MLTE
A crash could occur when using a graphic image in an MLTE field [3476016].
Pasting text that ended with a carriage return could corrupt the resulting text display [3476020].
Window Manager
Closing a sheet always enabled the close box of the parent window, even if the parent did not have kWindowCloseBoxAttribute [3486715].
A crash occurred when showing a sheet while the parent window was hidden [3486720].
Mac OS X 10.3 Developer Release Notes:
High Level Toolbox
Features and Enhancements
The major new features in the HIToolbox, HIServices, and NavigationServices frameworks for Mac OS X 10.3 are:
Redesigned Navigation Services dialogs
Updated Aqua user interface
HITheme API
HIView layout API
HIView-based menus
Compositing support in the DataBrowser
Translation Services Manager
Pasteboard Manager
HISearchField
HITextView
HISegmentedView
Miniature-sized controls
New MLTE API
Support for WebKit
Performance improvements in text, menu, window, and control drawing, especially in composited windows
Tips for Compatibility with Mac OS X 10.3
Control Manager
In a handler for kEventControlGetRegion, if you are asked for a region ID that you don't recognize, simply return eventNotHandledErr. Do not return noErr or some other error code; do not set the RgnHandle to an empty region. Proper handling of this event is critical to allow the toolbox to add new regions that are implemented by the default handlers installed for all controls. Notably, applications which do not follow this rule may find that clicks are ignored on their custom controls, because returning an empty region when the kControlClickableMetaPart region is requested (a new region for Panther) will cause the Control Manager to think that no mouse-down event falls in a clickable area.
In classic Mac OS, the popup button control's ControlRecord.contrlData field (accessible with the GetControlDataHandle API) was a handle to a PopupPrivateData structure containing the popup's menu and menu ID. In Carbon, this field is opaque, and the PopupPrivateData structure is not defined in Carbon header files; instead, applications should use GetControlData with the kControlPopupButtonMenuRefTag and kControlPopupButtonMenuIDTag constants to access this data. However, in previous versions of Mac OS X, the popup button control did actually still use the same format for its private data, and some applications were still dereferencing the popup private data anyways. In Mac OS X 10.3, the popup button control has been rewritten, and no longer supports the popup private data handle. For compatibility with current applications, the popup button control still provides a dummy handle with the same contents as before, but this may be removed in future versions of Mac OS X. If you are currently using the popup button control's data handle, you should switch to using GetControlData with kControlPopupButtonMenuRefTag or kControlPopupButtonMenuIDTag.
The popup button control no longer supports the variable-width option (that option is simply ignored). All popup button controls are now fixed-width. Your application can use the GetBestControlRect API to determine the best size for a popup button control, and size it explicitly, if you require a variable-width control.
Menu Manager
If you are installing an event loop source on kCFRunLoopDefaultMode and you want your source to be called during menu tracking, you should use kCFRunLoopCommonModes instead. See the Menu Manager release notes for more details.
Since menus are now implemented using WindowRefs, you may find menu windows in your window list that were not present in previous versions of Mac OS X. It is important to use the correct APIs to locate windows in the window list, so that your application doesn't get confused about which windows are yours and which belong to the toolbox. It is rarely correct to use FrontWindow or GetFrontWindowOfClass(kAllWindowClasses), for example; if you want the frontmost application window (even if your application doesn't use floating windows), you should use FrontNonFloatingWindow. If you want the active window, use ActiveNonFloatingWindow.
The Menu Manager now automatically provides cmd-comma as the command key equivalent for the Preferences menu item. Previously, the Preferences item did not have a standard command key. Your application is still free to set its own command key on the item if it wishes; the Menu Manager will automatically remove the standard command key if it detects that your application has added a submenu to the Preferences item. Because the Preferences item is now accessible via a command key, it is important that your application use a kEventCommandUpdateStatus handler to enable or disable the Preferences item appropriately according to your application state. Notably, it is not sufficient to wait to enable the item until your application receives a click in the menubar and calls MenuSelect, since the Preferences item is initially disabled and won't be enabled for command key matching unless your application also uses a kEventCommandUpdateStatus handler to enable it.
If your application uses the kEventMenuDrawItem or kEventMenuDrawItemContent Carbon events, we have several suggestions for compatibility with future releases of Mac OS X:
- There is currently no change in the port bounds, CGContext transform, or event parameters as compared to earlier versions of Mac OS X; all bounding rectangles are still expressed in global coordinates. However, for future compatibility, we recommend that you do not assume that menu and menu item bounds will always be in global coordinates; if you need to determine the global coordinates of a menu item inside a DrawItem/DrawItemContent handler, use LocalToGlobal to convert coordinates. Future releases of Mac OS X may change the port origin, CGContext transform, and event parameters such that the port origin begins at (0,0), and all other coordinates would be relative to that location.
- The CGContextRef that is passed to the event is only valid while the event handler is executing. After the event handler has returned, the CGContextRef is released. Do not cache the context or otherwise attempt to use it at any time other than during an event handler; if you need to draw outside of a kEventMenuDrawItem[Content] handler, you should create your own CGContextRef for the menu port.
In previous versions of Mac OS X, the SetMenuItemCommandKey API returned an error if passed a character code in the range 0x1A to 0x21; this is the range of command key meta-characters such as hMenuCmd. In Mac OS X 10.3, the Menu Manager now interprets character codes in this range as the actual ASCII character for that value, and displays the appropriate command key glyph; for example, calling SetMenuItemCommandKey with hMenuCmd, which previously would have returned an error, now sets the menu item's command key to be cmd-Escape, because 0x1B (the value of hMenuCmd) is the character code for the Escape character. Since the old behavior had no runtime effect, there was never any point in calling SetMenuItemCommandKey with any value from this range, but some applications did so anyways, and accidentally depended on an error being returned; make sure that your application does not pass a value to SetMenuItemCommandKey in this range unless it intends to have that value as its command key.
Window Manager
When a minimized document's Dock menu is displayed, the Window Manager now adds a Close menu item to the menu if there is a kEventWindowClose event handler on the document. Any window that uses the standard window event handler automatically has a kEventWindowClose handler installed on it that calls DisposeWindow on the window. Therefore, it is especially important that you use the kEventWindowClose event to check if your document has unsaved changes, and display a Save Changes sheet if necessary; otherwise, the user will be able to close unsaved documents from the Dock without any chance to save changes.
The toolbox now sends a kEventCommandProcess event containing the kHICommandSelectWindow command ID in more cases (see the Carbon Events Manager section of the release notes for details). Some applications do not handle this command ID, but return noErr from window or application-level kEventCommandProcess event handlers anyways; this prevents the windows of such applications from changing z-order in many cases. To avoid this problem, it is very important that a kEventCommandProcess handler return eventNotHandledErr for any command ID that it does not recognize.
The DragWindow API now obeys its boundsRect parameter; this parameter limits the area in which the window can be dragged. Since this parameter was ignored in Mac OS X 10.0 through 10.2, some applications have accidentally been passing invalid rectangles to DragWindow; on Mac OS X 10.3, this results in unexpected limitations to where a window of these applications can be dragged. Make sure that if you pass a non-NULL boundsRect parameter to DragWindow, that the rectangle has reasonable, useful values in it.
Previously, when asked to create a window with a zero width or height, the Window Manager would actually create the window with a width and height of 1. The Window Manager now obeys the rectangle that is provided by the application, and creates the window with the specified empty bounds. Some applications have accidentally come to depend on the Window Manager always creating their windows with non-empty bounds; make sure that your application can handle this change.
When resizing a window (with SizeWindow or SetWindowBounds), make sure that you haven't locked the window's port bits with LockPortBits. It has always been incorrect to hold a lock when changing the size of a window, but CoreGraphics has previously silently ignored this error; it will now block waiting for the lock to be unlocked, which will appear as a hang in your application.
Navigation Services
See the Navigation Services section of this document for a discussion of the rules to follow to safely customize Navigation Services dialogs.
QuickDraw
The format of a RgnHandle has changed. RgnHandles have always been opaque in Carbon, but some applications are still dereferencing RgnHandles; this will now fail. Use the accessor APIs provided by QuickDraw to retrieve the bounds or data of a RgnHandle.
Known Bugs
Custom HIViews that return a part code of zero in response to kEventControlHitTest will prevent kEventMouseDragged and kEventMouseUp events from being sent to the owning window (3423638).
Although the HISegmentedView control supports a command ID for each segment, and is documented to send a command event with that ID when a segment is clicked, it actually does not send the command event at all (3441632). A workaround for this problem is to install a kEventControlHit event handler on the control; the part code parameter of the event is the 1-based index of the segment that was clicked.
The HISegmentedView control currently does not work well in toolbars; it does not redraw when tracked, and does not handle kEventControlGetSizeConstraints (3441637).
The HISegmentedViewGetSegmentBehavior API actually returns the enable state of the segment, not the behavior (3467604).
There is a small memory leak in the Menu Manager after displaying a contextual menu (3361957).
There is currently no way to draw Panther-style tab controls using the Appearance Manager or HITheme APIs (3412964). Work is underway to support drawing Panther-style tabs in a near-term release of Mac OS X.
Menus cannot be displayed by hidden applications (3433293, 3474078). Normally a hidden application wouldn't display a menu anyways, but this case can occur when an application with an NSStatusItem is hidden.
Bug Reporting
We encourage all developers to file bugs found in Mac OS X 10.3 at <http://bugreport.apple.com>. Duplicate bugs are not a problem; please don't hesitate to file a bug with the thought that "surely someone else must have found this already."
Version Checking
On Mac OS X 10.3 and later, HIToolbox.framework exports a global variable, kHIToolboxVersionNumber, which contains the internal build number for the running version of HIToolbox. You can use this version number to check for bug fixes or feature changes in newer versions of HIToolbox. On Mac OS X 10.3, the build number was 145.0.
Feedback
For feedback and comments about HIToolbox, HIServices, and Navigation Services APIs and features, you can email toolbox@apple.com. The intent of this address is to provide developers with a direct channel to the engineering team responsible for these technologies. We will read your input, and will try to acknowledge it, but we might not always have time for replies. Please use this address for feedback and comments on the APIs and features (for instance "please add QuickTime wrapper classes to HIToolbox" or "I need API to do this and that"), but not for support type questions (for instance, "I can't install OS X" or "How does one create a new bundle in PB?") or comments in other areas (for instance, "why is the dock centered in Aqua?"). We also highly recommend that you file feature requests in Radar, where you can more easily track our progress on your request.
Accessibility
Header files (HIServices): AXConstants.h, AXError.h, AXUIElement.h, AXValue.h
Features and Enhancements
The Accessibility API has new APIs and attributes to support extended access to text (3158781), meant specifically to allow screen readers to access text. Two new APIs, AXUIElementCopyParameterizedAttributeNames and AXUIElementCopyParameterizedAttributeValue, have been added as part of this feature; the following attributes have been added for use with the new APIs:
kAXLineForIndexParameterizedAttribute
kAXRangeForLineParameterizedAttribute
kAXStringForRangeParameterizedAttribute
kAXRangeForPositionParameterizedAttribute
kAXRangeForIndexParameterizedAttribute
kAXBoundsForRangeParameterizedAttribute
kAXRTFForRangeParameterizedAttribute
kAXStyleRangeForIndexParameterizedAttribute
A new API, AXValueGetTypeID, returns the CoreFoundation type ID that is used for AXValueRef objects.
New accessible attributes:
kAXVisibleTextAttribute
kAXVisibleCharacterRangeAttribute
kAXNumberOfCharactersAttribute
kAXModalAttribute
kAXDefaultButtonAttribute(**)
kAXCancelButtonAttribute(**)
kAXIncrementorAttribute
kAXHourFieldAttribute
kAXMinuteFieldAttribute
kAXSecondFieldAttribute
kAXAMPMFieldAttribute
kAXDayFieldAttribute
kAXMonthFieldAttribute
kAXYearFieldAttribute
kAXURLAttribute
New accessible actions:
kAXRaiseAction(**)
New accessible roles:
kAXTimeFieldRole
kAXDateFieldRole
New accessible subroles:
kAXStandardWindowSubrole
kAXDialogSubrole
kAXSystemDialogSubrole
kAXFloatingWindowSubrole
kAXSystemFloatingWindowSubrole
kAXIncrementArrowSubrole(**)
kAXDecrementArrowSubrole(**)
kAXIncrementPageSubrole(**)
kAXDecrementPageSubrole(**)
New accessible notifications:
kAXDrawerCreatedNotification(**)
kAXSheetCreatedNotification(**)
All of the above have been implemented in Cocoa. Those that are implemented in Carbon are marked with (**).
A new kEventClassAccessibility Carbon event, kEventAccessibleGetAllParameterizedAttributeNames, has been added to allow retrieval of parameterized accessible attributes.
A new Carbon Event Manager error code, eventDeferAccessibilityEventErr, has been defined for use by event handlers for the kEventAccessiblePerformNamedAction event. This error should be returned by an event handler when the handler knows that responding to the event will take a significant amount of time; when this error is returned, the Carbon Accessibility implementation will immediately return noErr to the accessibility client, and then will post the Carbon event to the main event queue, where it will be dispatched when the application returns to its event loop. See the discussion of the kEventAccessiblePerformNamedAction event in CarbonEvents.h for more details.
Appearance Manager
Header files (HIToolbox): Appearance.h, HITheme.h
Features and Enhancements
The Appearance Manager now provides a new API for drawing appearance primitives (2816257). This API is located in the HITheme.h header file. It is similar to the old Appearance Manager API, but many parameters have been modified to use CoreGraphics types instead of QuickDraw types, and all drawing APIs take a CGContextRef to allow drawing directly into a context. The old Appearance Manager API is now implemented on top of the new API; using the new API can provide significant performance advantages. The following new APIs are provided:
HIThemeDrawChasingArrows
HIThemeGetTrackPartBounds
HIThemeDrawGroupBox
HIThemeDrawTrack
HIThemeDrawTitleBarWidget
HIThemeGetScrollBarTrackRect
HIThemeGetButtonContentBounds
HIThemeDrawMenuSeparator
HIThemeGetWindowRegionHit
HIThemeGetTrackThumbPositionFromOffset
HIThemeDrawPlacard
HIThemeDrawFrame
HIThemeDrawMenuBackground
HIThemeGetTabShape
HIThemeDrawTabPane
HIThemeDrawButton
HIThemeDrawTab
HIThemeDrawFocusRect
HIThemeApplyBackground
HIThemeGetTrackThumbPositionFromBounds
HIThemeGetTrackDragRect
HIThemeHitTestTrack
HIThemeGetButtonShape
HIThemeDrawPopupArrow
HIThemeDrawMenuTitle
HIThemeGetTabPaneDrawShape
HIThemeGetTabPaneContentShape
HIThemeDrawMenuBarBackground
HIThemeGetTrackBounds
HIThemeGetButtonBackgroundBounds
HIThemeDrawMenuItem
HIThemeGetMenuBackgroundShape
HIThemeGetTabDrawShape
HIThemeGetTextDimensions
HIThemeDrawTextBox
HIThemeDrawTrackTickMarks
HIThemeDrawTickMark
HIThemeGetTrackThumbShape
HIThemeGetTrackParts
HIThemeGetTrackLiveValue
HIThemeHitTestScrollBarArrows
HIThemeDrawScrollBarDelimiters
HIThemeDrawWindowFrame
HIThemeDrawGrowBox
HIThemeGetGrowBoxBounds
HIThemeGetWindowShape
HIThemeDrawGenericWell
HIThemeDrawPaneSplitter
HIThemeDrawGrabber
HIThemeDrawHeader
HIThemeDrawSeparator
HIThemeDrawBackground
The Appearance Manager now supports a miniature size which is even smaller than the small control size introduced in Mac OS X 10.2. Appearance primitives may be drawn in the minature size using either the old Appearance Manager or the new HITheme API. New Appearance primitive constants have been added to specify the miniature sizes of the primitives:
kThemeMiniSlider
kThemeComboBoxMini
kThemeMiniCheckBox
kThemeMiniRadioButton
kThemeIncDecButtonMini
kThemeArrowButtonMini
kThemePushButtonMini
kThemePopupButtonMini
The value returned by Gestalt for gestaltAppearanceVersion has been changed to 0x300. This indicates that the HITheme APIs have been implemented and that all legacy theme APIs are now wrapped around HITheme APIs.
A new theme font constant, kThemeMiniSystemFont, has been added for use with miniature controls (3211805).
Four new theme cursors have been added: three for ResizeUp, ResizeDown, and ResizeUpDown, and one (kThemePoofCursor) to indicate that a dragged item will be deleted if it is released at the current mouse position.
Many new theme metrics have been added to return information about combo boxes, round edit text fields, and mini controls (3211816):
kThemeMetricComboBoxLargeBottomShadowOffset
kThemeMetricComboBoxLargeRightShadowOffset
kThemeMetricComboBoxSmallBottomShadowOffset
kThemeMetricComboBoxSmallRightShadowOffset
kThemeMetricComboBoxLargeDisclosureWidth
kThemeMetricComboBoxSmallDisclosureWidth
kThemeMetricRoundTextFieldContentInsetLeft
kThemeMetricRoundTextFieldContentInsetRight
kThemeMetricRoundTextFieldContentInsetBottom
kThemeMetricRoundTextFieldContentInsetTop
kThemeMetricRoundTextFieldContentHeight
kThemeMetricComboBoxMiniBottomShadowOffset
kThemeMetricComboBoxMiniDisclosureWidth
kThemeMetricComboBoxMiniRightShadowOffset
kThemeMetricLittleArrowsMiniHeight
kThemeMetricLittleArrowsMiniWidth
kThemeMetricLittleArrowsSmallHeight
kThemeMetricLittleArrowsSmallWidth
kThemeMetricMiniCheckBoxHeight
kThemeMetricMiniCheckBoxWidth
kThemeMetricMiniDisclosureButtonHeight
kThemeMetricMiniDisclosureButtonWidth
kThemeMetricMiniHSliderHeight
kThemeMetricMiniHSliderMinThumbWidth
kThemeMetricMiniHSliderTickHeight
kThemeMetricMiniHSliderTickOffset
kThemeMetricMiniPopupButtonHeight
kThemeMetricMiniPullDownHeight
kThemeMetricMiniPushButtonHeight
kThemeMetricMiniRadioButtonHeight
kThemeMetricMiniRadioButtonWidth
kThemeMetricMiniTabCapsWidth
kThemeMetricMiniTabFrameOverlap
kThemeMetricMiniTabHeight
kThemeMetricMiniTabOverlap
kThemeMetricMiniVSliderMinThumbHeight
kThemeMetricMiniVSliderTickOffset
kThemeMetricMiniVSliderTickWidth
kThemeMetricMiniVSliderWidth
kThemeMetricRoundTextFieldContentInsetWithIconLeft
kThemeMetricRoundTextFieldContentInsetWithIconRight
kThemeMetricRoundTextFieldMiniContentHeight
kThemeMetricRoundTextFieldMiniContentInsetBottom
kThemeMetricRoundTextFieldMiniContentInsetLeft
kThemeMetricRoundTextFieldMiniContentInsetRight
kThemeMetricRoundTextFieldMiniContentInsetTop
kThemeMetricRoundTextFieldMiniContentInsetWithIconLeft
kThemeMetricRoundTextFieldMiniContentInsetWithIconRight
kThemeMetricRoundTextFieldSmallContentHeight
kThemeMetricRoundTextFieldSmallContentInsetBottom
kThemeMetricRoundTextFieldSmallContentInsetLeft
kThemeMetricRoundTextFieldSmallContentInsetRight
kThemeMetricRoundTextFieldSmallContentInsetTop
kThemeMetricRoundTextFieldSmallContentInsetWithIconLeft
kThemeMetricRoundTextFieldSmallContentInsetWithIconRight
kThemeMetricSmallTabFrameOverlap
kThemeMetricSmallTabOverlap
kThemeMetricSmallPaneSplitterHeight
New constants for control part codes (kAppearancePart* constants) and window region codes (kAppearanceRegion* constants) have been added to remove dependencies in Appearance.h on Controls.h and MacWindows.h. These constants are preferred for use with Appearance Manager APIs.
kThemeBrushAlternatePrimaryHighlightColor is now documented. This brush is actually available on Mac OS X 10.2 and later. It represents the highlight color that is used in some list views.
A new theme brush, kThemeBackgroundMetal, is defined for use with HIThemeApplyBackground. It can be used to draw the metal visual appearance in a specified area.
Implementation Changes
Various performance optimizations to the text-drawing path in the Appearance Manager, ATSUI, and CoreGraphics have increased text drawing speed by up to 60% compared to 10.2. Your application will get the most benefit from these improvements by adopting the HIThemeDrawTextBox API; because the HITheme API does not have to copy GrafPort state into a CoreGraphics context, it is faster than the older DrawThemeTextBox API.
Application Manager
Header file (HIToolbox): MacApplication.h
Features and Enhancements
A new SystemUIMode constant, kUIModeAllSuppressed, is available for use with the SetSystemUIMode API. In this mode, the menubar and Dock are hidden, but will automatically show themselves if the mouse moves into the area that each would normally occupy.
The Dock now supports kUIModeContentSuppressed and kUIModeContentHidden.
A new SystemUIOptions constant, kUIOptionDisableHide, is available for use with the SetSystemUIMode API. This option specifies that the Hide menu item should be disabled (3092973).
A new API, HIAboutBox, displays a standard about box, using information from the application's Info.plist. There is now a handler for all applications that responds to kEventCommandProcess (kHICommandAbout) by calling HIAboutBox.
The kHIToolboxVersionNumber global variable is now exported. It contains the build number of the HIToolbox framework, and can be used by applications to check for a specific version to determine whether a bug has been fixed, a feature added, etc.
Carbon Event Manager
Header files (HIToolbox): CarbonEvents.h, CarbonEventsCore.h
Features and Enhancements
The documentation for individual Carbon events in CarbonEvents.h has been reformatted and much more detail has been added about each event parameter. The new event documentation also indicates the Mac OS X version in which each event was first supported.
The Carbon Event Manager now provides the ability to monitor user input events that occur in other applications (2498953). User input events are events such as mouse-down, mouse-up, key-down, and so forth. This ability is provided via a new event target, called the event monitor target, which is returned by the new API GetEventMonitorTarget. When an event handler is installed on this target for a supported event type, the Carbon Event Manager requests that a copy of any event of that type be sent to the monitoring application. These events are queued into the application's main event queue, and during normal event dispatching are sent directly to the event handlers installed on the event monitor target. Monitored events are not sent through the normal event dispatching path; the event dispatcher sends them directly to the event monitor target. A new event attribute, kEventAttributeMonitored, indicates that an event originated from another process and should be dispatched to the event monitor target.
Note that both Carbon and Cocoa password edit text controls enable a secure input mode while the focus is on the control, which prevents keyboard events from being passed to other applications. This prevents the monitoring event target from being used to sniff password keystrokes. For additional security, the event monitor target does not allow monitoring of RawKeyDown, RawKeyUp, or RawKeyRepeat events unless the "Enable access for assistive devices" control is checked in the Universal Access preference pane (which requires administrative access); other event kinds can be freely monitored regardless of whether this control is checked. You can determine whether this control is checked using AXAPIEnabled API in AXUIElement.h.
Three new APIs are provided for use by applications that implement their own password input edit fields and do not use the standard password edit text control: EnableSecureEventInput, DisableSecureEventInput, and IsSecureEventInputEnabled. A custom password edit control may call EnableSecureEventInput when focus is moved to the edit field, and this will prevent keystrokes from being monitored by any other application. Be sure to call DisableSecureEventInput when the edit field loses focus; if your application keeps secure input mode enabled even when it has been deactivated, other applications will be affected in various ways, such as being unable to read the current keyboard modifiers or keyboard state with GetCurrentKeyModifiers or GetKeys.
A new API, CopyEventAs, may be used to create a copy of an EventRef while simultaneously setting the new event's class and kind (2855452).
A new API, HIMouseTrackingGetParameters, may be used to get information about how mouse tracking loops should behave (3094552). Currently, this API supports only returns one set of parameters, about the time and distance to determine sticky mouse tracking as used in sticky menu behavior.
A new API, AcquireFirstMatchingEventInQueue, may be used to search the event queue quickly for an event with minimal side effects (2874501). This API is similar to the old EventAvail API, and also to FindSpecificEventInQueue; all of these APIs allow your application to determine if an event is present in the event queue. EventAvail, however, will flush modified window buffers to the screen as a side effect, and FindSpecificEventInQueue is somewhat slowed by the need to pass each event in the queue to a comparator proc. AcquireFirstMatchingEventInQueue should be faster than either of these APIs because it does not flush window buffers and it searches the queue directly rather than calling back to a comparator proc.
A new API, CopySymbolicHotKeys, may be used to copy a list of the hotkeys that are shown in the Keyboards preference pane. This API also returns a few other hotkeys that are not currently editable in the preference pane.
A new HICommand constant, kHICommandShowCharacterPalette, has been defined (3181469). The Carbon Event Manager provides a default handler for all applications that handles this command ID; your application does not need to handle it. In response to this command, the default handler shows the Character Palette window. The Mac OS X human interface guidelines now recommend that all applications include a menu item labeled "Special Characters…" in the Edit menu, with kHICommandShowCharacterPalette as its command ID.
Carbon event queues in previous releases were limited to 200 events. Event queues are now unlimited in size as long as the application is processing events on a timely basis. If an application does not remove new events from the queue promptly (currently, within 10 seconds of the creation of the oldest event in the queue), then when the queue reaches 200 events, the Carbon Event Manager will remove the most recent event from the front of the queue to make room for each newly arrived event. Applications that only check for event availability with APIs such as EventAvail, FindSpecificEventInQueue, or AcquireFirstMatchingEventInQueue, and do not ever remove events from the queue with GetNextEvent, WaitNextEvent, or ReceiveNextEvent, will become subject to this limitation in the event queue length; new events will continue to be queued, but will only exist in the queue until the next event arrives. Such applications should make sure to either remove individual events or flush the entire event queue periodically (once the application has processed all events in the queue that it cares about).
The eventPassToNextTargetErr error code has been documented (2823357). This error code is supported on all versions of Mac OS X and CarbonLib. When an event handler returns this error code, the Carbon event dispatching system stops passing the event to handlers on the current event target, and immediately skips to the next event target in the target chain. For example, if handlers A and B are installed on a window, and handler C is installed on the application, then normally, if handler A returns eventNotHandledErr, an event will be sent to handler B, and then to handler C. If handler A returns eventPassToNextTargetErr, however, the event dispatcher will skip over handler B and send the event directly to handler C.
The kEventParamControlWouldAcceptDrop parameter to kEventControlDragEnter is now documented (3139458). It may be used in Mac OS X 10.2 and later.
Several of the kEventClassService Carbon events now include an event parameter containing a PasteboardRef (2858584). Handlers for these events may use either the PasteboardRef or ScrapRef included with the event; both references point to the same underlying data store. Since the Pasteboard Manager supports multiple items on a pasteboard, using the PasteboardRef allows the service handler to provide or act on multiple items; the previous ScrapRef event parameter only supported services that provided or acted on a single item.
kEventClassMouse events have a new WindowPartCode parameter, containing the part code that was hit by the mouse. This parameter can be used by applications instead of calling FindWindow.
kEventMouseMoved events now have WindowRef, WindowMouseLocation, and WindowPartCode parameters.
The following event parameter types are now retained when added to an event, and released when the event is destroyed (2931173):
typeEventRef
typeCFArrayRef
typeCFDictionaryRef:
typeCFMutableDictionaryRef
Previously, a kHICommandClose command would only result in a kEventWindowClose event if the window receiving the command used the standard handler. This translation is now supported for all windows, regardless of whether they use the standard handler.
When a window is selected from the standard window menu, the window is activated via a kEventCommandProcess event containing kHICommandSelectWindow. The toolbox now uses this same event to activate windows in other cases too: when selecting the front or clicked window on app activation; when selecting a document window when the sheet attached to it is clicked; when selecting a window from an application's Dock menu; in the standard window event handler for handling a click in a window; when setting the kAXMain accessibility attribute of a window; and when responding to interprocess and intraprocess window cycling. In these cases, the attributes field of the HICommand structure contains kHICommandFromWindow, and the source.window field contains the window that should be selected.
The toolbox provides a default handler for all windows that handles certain command events, such as kHICommandClose. For example, the default handler will map this command to a kEventWindowClose event. Previously, the default handler would determine the window to receive the kEventClassWindow event by calling ActiveNonFloatingWindow. Now, if the HICommand structure has the kHICommandFromWindow flag set, the default handler will use the window field of the HICommandExtended structure to determine the target of the kEventClassWindow event, instead of using ActiveNonFloatingWindow.
The default toolbox window event handler for all document, modal, and floating windows now disables any menu item with the kHICommandClose command ID if a sheet is open on the window.
The Carbon Event Manager now informs the CFNotificationCenter implementation when a Carbon application is deactivated, which allows CFNotificationCenter to properly implement the CFNotificationSuspensionBehavior options for Carbon applications. Previously, a Carbon application that installed a CFNotification observer would be called back with the specified notification while in the background, even if the application did not specify CFNotificationSuspensionBehaviorDeliverImmediately. In Panther, background applications will not receive CFNotification callbacks unless CFNotificationSuspensionBehaviorDeliverImmediately was specified when installing the observer. Note that this also affects the FNSubscribe API in the File Manager, which is based on CFNotifications internally; previously, an FNSubscriptionProcPtr would be called back even when the subscribing application was in the background, but this no longer occurs, and you must now specify the kFNNotifyInBackground option to FNSubscribe if you wish to be called while in the background.
kEventClassCommand events are now routed from drawers to their parent windows, if not handled by the drawer. Previously, command events were routed from a drawer to the application target (3115838).
RegisterEventHotKey now officially allows its modifiers parameter to be zero. Previously, it required this parameter to have at least one modifier bit set.
New and Improved Carbon Events
The following Carbon events are new for Mac OS X 10.3:
-- Accessibility events
kEventAccessibleGetAllParameterizedAttributeNames
Also, the kEventAccessibleGetNamedAttribute event (introduced in Mac OS X 10.2) has a new optional event parameter, kEventParamAccessibleAttributeParameter, which is used when your event handler is being asked for the value of a parameterized attribute.
-- Application events
kEventAppActiveWindowChanged (3040056). Sent when the active window has changed.
kEventAppAvailableWindowBoundsChanged (3154246). Sent when the available bounds for window positioning on a GDevice has changed (for example, when the Dock is shown or hidden, or when the device resolution changes).
-- Control events
kEventControlGetFrameMetrics. Sent to controls that are used as window frame views to determine the inset of the content region of the control.
kEventControlInvalidateForSizeChange. Sent when a control's size changes to allow the control to override its invalidation. If not handled, the Control Manager will automatically invalidate the entire control, but the control may choose to handle the event and invalidate less.
-- Ink events
These events allow applications to customize their handling of ink input.
kEventInkPoint
kEventInkGesture
kEventInkText
-- Menu events
kEventMenuBarHidden/Shown (3059179). Sent when the menubar is hidden or shown in any process.
kEventMenuCalculateSize. Sent to a menu to request that the menu recalculate its size.
kEventMenuCreateFrameView. Sent to a menu content view to request that the view create a frame view for the menu window.
kEventMenuGetFrameBounds. Sent to a menu content view to request the bounds of the menu window.
kEventMenuBecomeScrollable. Sent to a menu content view to request that the view install event handlers as necessary to support scrolling of the menu contents. If not handled, the Menu Manager automatically installs handlers to provide scrolling for HIView-based menus.
kEventMenuCeaseToBeScrollable. Sent to a menu content view to request that the view remove event handlers that were installed to support scrolling.
-- SearchField events
kEventSearchFieldCancelClicked. Sent when the cancel icon in a search field has been clicked.
-- System events
kEventSystemTimeDateChanged. Sent when the time or date has changed.
kEventSystemUserSessionActivated/Deactivated. Sent when the current user login session is activated or deactivated by Fast User Switching.
-- TextField events
kEventTextAccepted. Sent by Unicode-based edit controls when Return or Enter is pressed in a control.
-- Text Services events
These events are used to support interaction between an input method and a text editing view. They are automatically handled by MLTE.
kEventTSMDocumentAccessGetLength
kEventTSMDocumentAccessGetSelectedRange
kEventTSMDocumentAccessGetCharactersPtr
kEventTSMDocumentAccessGetCharactersPtrForLargestBuffer
kEventTSMDocumentAccessGetCharacters
kEventTSMDocumentAccessGetFont
kEventTSMDocumentAccessGetGlyphInfo
kEventTSMDocumentAccessLockDocument
kEventTSMDocumentAccessUnlockDocument
-- Toolbar events
kEventToolbarItemEnabledStateChanged. Sent when a toolbar item is enabled or disabled.
kEventToolbarItemViewConfigForMode. Sent to a custom toolbar item view when a toolbar's display mode has changed.
kEventToolbarItemViewConfigForSize. Sent to a custom toolbar item view when a toolbar's display size has changed.
kEventToolbarItemViewEnterConfigMode. Sent to a custom toolbar item view when a toolbar is about to show its configuration sheet.
kEventToolbarItemViewExitConfigMode. Sent to a custom toolbar item view when a toolbar's configuration sheet has been closed.
The following toolbar events were sent in Mac OS X 10.2 also, and have now been documented:
kEventToolbarItemAdded
kEventToolbarItemRemoved
kEventToolbarDisplayModeChanged
kEventToolbarDisplaySizeChanged
kEventToolbarLayoutChanged
kEventToolbarBeginMultiChange
kEventToolbarEndMultiChange
-- Window events
kEventWindowTransitionStarted. Sent when TransitionWindow has begun a transition.
kEventWindowTransitionCompleted. Sent when TransitionWindow has completed a transition.
Notable Bug Fixes
The standard window event handler in Mac OS X 10.2.3 and later, in response to kEventWindowGetClickActivation, returned kActivateAndIgnoreClick for compositing floating windows. This caused clicks in a non-frontmost floating window to activate the window, but the clicked control would not react to the click. The standard window handler now returns kActivateAndHandleClick for compositing windows that have kWindowActivationScopeIndepent, such as floating windows (3139977).
Control Manager
Header files (HIToolbox): Controls.h, ControlDefinitions.h, HIView.h
Features and Enhancements
A new HIView layout API is provided to automatically reposition controls in response to changes in the size of the containing window (3170190). This API allows a control to be positioned relative to another control in a variety of different ways; see HIView.h for details. The following new APIs are provided to support HIView layout:
HIViewGetLayoutInfo
HIViewSetLayoutInfo
HIViewResumeLayout
HIViewSuspendLayout
HIViewIsLayoutActive
HIViewApplyLayout
A new API, HIViewRegionChanged, allows a custom HIView to indicate when one of its regions has changed due to an external event (3188688). The Control Manager will send a kEventControlGetRegion event to the control in response to ask for the new region.
Two new APIs, HIViewGetFeatures and HIViewChangeFeatures, allow a control's feature flags to be retrieved and modified at runtime (3188540). New feature flag constants have been defined in HIView.h for use with HIViewGet/ChangeFeatures; note that you must use the kHIView feature flags, not the older Control Manager feature flags, with HIViewGet/ChangeFeatures.
A new API, HIViewRender, allows a control in a compositing window to be drawn immediately rather than waiting for the next call to the runloop (3018431).
The DataBrowser now fully supports compositing mode (2932742).
The EditUnicodeText control now fully supports compositing mode.
Many of the standard controls now support a miniature size which is even smaller than the small control size introduced in Mac OS X 10.2. The miniature control size may be requested for a control using SetControlData with kControlSizeTag and kControlSizeMini.
The kDataBrowserListViewTypeSelectColumn property flag can be used to mark the column that, in list view, should be the key column for type selection.
Two new ScrollView APIs, HIScrollViewCanNavigate and HIScrollViewNavigate, allow the application to, respectively, determine whether it is currently possible to scroll in a given direction in a scrollview, and direct the scrollview to scroll to home, end, page up, page down, or scroll by a line (3145456). Note that these APIs are not currently exported via CFM; to access them from a CFM application, you must use CFBundleGetFunctionPointerForName.
As of Mac OS X 10.2.3, Data Browser now supports proper type-selection. Support is completely free in Column View, but you need to do a bit of work in List View. You need to tell List View which columns contain type-selectable strings by setting the kDataBrowserListViewTypeSelectColumn property flag for the appropriate columns. See the documentation for kDataBrowserListViewTypeSelectColumn in ControlDefinitions.h for more details. In addition, Column View and any List View with a type-selectable column will gather keyboard input via a carbon event handler instead of relying on client calls to HandleControlKey. Clients will therefore not see such keyboard input come out of WaitNextEvent.
A new control region code, kControlOpaqueMetaPart, is now documented. This region is actually requested from controls on Mac OS X 10.2 and later. This region indicates the area of the control that is opaque; that is, the area which the control entirely fills with pixels that have an alpha channel value of 1.0. For example, if the control erases a portion of itself to a non-transparent color, that portion of the control is opaque; no other controls can be seen behind that portion of the control. If a request for this region is not handled, the Control Manager's default handler will return an empty region. A control may return a non-empty opaque region to improve drawing speed in composited windows; the Control Manager will not attempt to draw any views behind the control that are entirely obscured by the opaque region.
A new control region code, kControlClickableMetaPart, is now available (3065030). This region is the area of the control that can receive clicks (regardless of whether the control is active or inactive, enabled or disabled). This region is used to determine which parts of the containing window may invoke async window dragging when clicked. If a request for this region is not handled, the Control Manager's default hanlder will return a region covering the control's entire bounds. Note: If you have a custom control, or if you install a kEventControlGetRegion handler on a standard control, you must either return eventNotHandledErr from your handler when this region is requested, or return a non-empty region, in order for clicks on the control to be handled. If you return an empty region from your handler in response to a request for this region, clicks on the control will be ignored.
A new control meta-font, kControlFontMiniSystemFont, has been defined (3211805). This meta-font should be used to draw text associated with miniature-sized controls.
A new structure, HIViewFrameMetrics, has been defined for use with the kEventControlGetFrameMetrics event. This event and structure are primarily used by custom window root views.
HIObject class IDs have been established and documented in ControlDefinitions.h for nearly all standard controls. These class IDs may be passed to HIObjectCreate to create instances of the standard controls on Mac OS X 10.3 and later. These class IDs are not supported on Mac OS X 10.2.
A new control feature flag, kControlInvertsUpDownValueMeaning, has been defined. This feature flag indicates that the control, in typical usage, increments the value of an associated object when the up part of the control is pressed, and decrements the value of an associated object when the down part of the control is pressed. The LittleArrows control is currently the only client of this feature flag.
Live control tracking can now be canceled using Escape and Command-period (2546483).
New Controls
HITextView is a wrapper around an MLTE object (2264638). Unlike the EditUnicodeText control, HITextView supports embedding within a scroll view and makes available the underlying TXNObject.. Two new APIs are provided by HITextView: HITextViewCreate and HITextViewGetTXNObject.
HISearchField provides a control that is similar to those seen in Safari, Finder, iTunes, and other applications for entering a search string (3107105). It provides the following new APIs:
HISearchFieldCreate
HISearchFieldChangeAttributes
HISearchFieldSetSearchMenu
HISearchFieldGetSearchMenu
HISearchFieldGetAttributes
HISearchFieldSetDescriptiveText
HISearchFieldCopyDescriptiveText
HISegmentedView provides a control that displays multiple segments as parts of a single button-like control. These segments can display text, icons, or both. This control provides the following new APIs:
HISegmentedViewSetSegmentLabel
HISegmentedViewSetSegmentBehavior
HISegmentedViewIsSegmentEnabled
HISegmentedViewGetSegmentContentWidth
HISegmentedViewGetSegmentValue
HISegmentedViewChangeSegmentAttributes
HISegmentedViewCreate
HISegmentedViewSetSegmentCount
HISegmentedViewGetSegmentCount
HISegmentedViewGetSegmentBehavior
HISegmentedViewGetSegmentAttributes
HISegmentedViewSetSegmentValue
HISegmentedViewSetSegmentEnabled
HISegmentedViewSetSegmentCommand
HISegmentedViewGetSegmentCommand
HISegmentedViewCopySegmentLabel
HISegmentedViewSetSegmentContentWidth
HISegmentedViewSetSegmentImage
HISegmentedViewGetSegmentImageContentType
HISegmentedViewCopySegmentImage
Note that the HISegmentedView APIs are not currently exported via CFM; to access them from a CFM application, you must use CFBundleGetFunctionPointerForName.
New ControlData Tags
kControlBevelButtonIsMultiValueMenuTag
kControlLittleArrowsIncrementValueTag (2915076)
kControlGroupBoxFrameRectTag
kControlWindowHeaderIsListHeaderTag (2888639)
kControlStaticTextIsMultilineTag
kControlEditTextInsertTextBufferTag (3050612)
kControlEditTextInsertCFStringRefTag (3050612)
Use kControlEditTextInsertTextBufferTag when you want to insert WorldScript-encoded text or retrieve the currently selected text as a buffer of WorldScript-encoded text. Use kControlEditTextInsertCFStringRefTag when you want to insert a CFStringRef or retrieve the currently selected text as a CFStringRef. If the current selection is empty and you call GetControlData with one of these tags you get an actualSize of 0 back for kControlEditTextInsertTextBufferTag and an empty CFStringRef for kControlEditTextInsertCFStringRefTag.
Implementation Changes
All controls have been converted to use the new HITheme APIs rather than the older Appearance Manager APIs. Since the new HITheme APIs are faster than the old APIs, this change combined with other performance optimizations to the control and Appearance Manager drawing code increase control drawing speed by 10 to 50% compared to 10.2, depending on the control.
Various performance optimizations to the compositing drawing path increase compositing drawing speed by 25 to 35% compared to 10.2 (3181884).
Notable Bug Fixes
HIViewSetBoundsOrigin failed to invalidate the view's visible region (3126953). To work around this problem on earlier version of Mac OS X, hide and then show the view.
Previously, setting the keyboard focus to a control that already had the focus caused two kEventControlGetFocusPart events to be sent to that control. One of these events was unnecessary. Now only a single event is sent (3193998).
Previously, setting the keyboard focus to a control that already had the focus caused a kEventControlSetFocusPart event with a part code of zero to be sent to the control, followed by a second kEventControlSetFocusPart event with the actual control part code. The first event, with part code zero, is no longer sent (3194017).
In a DataBrowser control in list view mode with full-row hiliting and none of the columns marked as selectable, up/down arrow key navigation was not working (3181576).
The following control creation APIs can now take a NULL WindowRef parameter (previously they returned paramErr): CreateStaticTextControl, CreateRoundButtonControl, CreatePlacardControl, CreateIconControl, CreatePictureControl, and CreatePopupArrowControl (3077871).
Dialog Manager
Header file (HIToolbox): Dialogs.h
Features and Enhancements
The windows created by CreateStandardSheet now use compositing mode and are transparent once again (they were also transparent in Mac OS X 10.1, but were not transparent in 10.2).
The movable flag in the standard alert param block is now ignored. All standard alerts are now movable by default.
Dock Support
Header files (HIToolbox): MacApplication.h, MacWindows.h
Features and Enhancements
A Close menu item is now added to the Dock tile menu of a collapsed window, if the window has a close box, and the window event target has an event handler for kEventWindowClose (3017915). When this menu item is selected, a kEventCommandProcess event containing kHICommandClose is sent to the window, which in turn is converted into a kEventWindowClose event. Windows which use the standard window event handler will support this feature automatically, since the standard handler provides a kEventWindowClose handler; windows which do not use the standard window event handler should install a kEventWindowClose handler on the window, and respond appropriately. Note that your handler may now receive this event while the window is still collapsed; if you display a sheet on the window, the window will be automatically uncollapsed, but if you display a modal dialog, you may wish to uncollapse the window programmatically first before displaying the dialog. It is especially important that if you use the standard window event handler, that you use the kEventWindowClose event to check if your document has unsaved changes, and display a Save Changes sheet if necessary; otherwise, the user will be able to close unsaved documents from the Dock without any chance to save changes.
Drag Manager
Header file (HIToolbox): Drag.h
Features and Enhancements
The NewDragWithPasteboard and GetDragPasteboard APIs have been added to support interoperability between the Drag Manager and the Pasteboard Manager.
Help Manager
Header file (HIToolbox): MacHelp.h
User Interface Changes
Help tags are now shown over both active and inactive windows in the frontmost app. Previously, they were only shown over active (or hilited) windows. This matches a similar behavior change in Cocoa in Panther.
Notable Bug Fixes
The menu returned by HMGetHelpMenu now has the same title as the Help menu displayed in the menubar (3190366). In Mac OS X 10.2, the menu returned by HMGetHelpMenu had an empty title.
HIToolbar
Header file (HIToolbox): HIToolbar.h
Features and Enhancements
A new API, HIToolbarSetItemsWithIdentifiers, allows adding multiple items to a toolbar at once.
A new API, HIToolbarItemConfigDataChanged, informs the toolbar that the config data for a toolbar item has changed and should be written to the toolbar config prefs (3165849).
A new Carbon event, kEventToolbarItemEnabledStateChanged, is now sent when a toolbar item is enabled or disabled.
Two new Carbon events have been added to support dragging into toolbar items (3067304). kEventToolbarItemWouldAcceptDrop is sent when a drag passes over a toolbar item; a handler can respond to this event to indicate that the item would like to accept the drag. kEventToolbarItemAcceptDrop is sent when a drag is released over a toolbar item; it allows the handler to process the drop.
A new event class, kEventClassToolbarItemView, contains these new events, which are sent to custom toolbar item views:
- kEventToolbarItemViewConfigForMode is sent when a toolbar's display mode has changed.
- kEventToolbarItemViewConfigForSize is sent when a toolbar's display size has changed.
- kEventToolbarItemViewEnterConfigMode is sent when a toolbar is about to show its configuration sheet.
- kEventToolbarItemViewExitConfigMode is sent when a toolbar's configuration sheet has been closed.
A new toolbar item attribute, kHIToolbarItemLabelDisabled, causes clicks on the label of a custom toolbar item view to be ignored. For example, the view switcher control in a Finder toolbar (for switching between icon, list, and browse views) ignores clicks on the label, but the icon for the Applications directory on a Finder toolbar does not.
The HIToolbarItemSetMenu API now allows a NULL MenuRef parameter to remove the menu from a toolbar item (3214835).
For toolbar items that use a custom view, the item label text now responds to clicks (highlighting and tracking the click), if the item has a non-zero command ID (3087217).
The following toolbar events were sent in Mac OS X 10.2, and have now been documented (3082754):
kEventToolbarItemAdded
kEventToolbarItemRemoved
kEventToolbarDisplayModeChanged
kEventToolbarDisplaySizeChanged
kEventToolbarLayoutChanged
kEventToolbarBeginMultiChange
kEventToolbarEndMultiChange
IBCarbonRuntime
Header file (HIToolbox): IBCarbonRuntime.h
Features and Enhancements
The following controls can now be created from nibs:
HISearchField
HIImageView
HITextView
HIComboBox
HIScrollView
It is now possible to place custom subclasses of HIView in a nib (3273533). When placing a custom HIView subclass in a nib, it is now possible to specify initialization event parameters (3156268).
It is now possible to specify custom control properties in a nib.
Interface Builder and IBCarbonRuntime now allow the creation of miniature-sized controls (3156263).
It is now possible to specify a custom root view class ID for a window in a nib (3156269).
There is limited support for the HIView layout APIs (3345464).
The following menu attributes are now supported in a nib:
kMenuAttrUsePencilGlyph
kMenuAttrHidden
kMenuAttrCondenseSeparators
The following menu item attributes are now supported in a nib (3151902):
kMenuItemAttrSectionHeader
kMenuItemAttrAutoRepeat
kMenuItemAttrCustomDraw
kMenuItemAttrIncludeInCmdKeyMatching
kMenuItemAttrAutoDisable
kMenuItemAttrUpdateSingleItem
When creating a new menu item in Interface Builder, the kMenuItemAttrUpdateSingleItem attribute is now automatically turned on.
It is now possible to specify a menu item's indent in a nib (3363809). Note that support for specifying the indent has not yet been added to Interface Builder, but once it is, you'll be able to use a nib with an indent on Mac OS X 10.3 and later.
It is now possible to specify in Interface Builder that a menu item's command key does not require the command key modifier (3363821).
The following window attributes are now supported in a nib (3156272):
kWindowNoShadowAttribute
kWindowHideOnSuspendAttribute
kWindowHideOnFullScreenAttribute
kWindowIgnoreClicksAttribute
kWindowNoConstrainAttribute
kWindowAsyncDragAttribute
Extended help tags are now supported in nibs for menu items, controls, and windows (3156287).
Windows of class kSheetAlertWindowClass can now be created from nibs (3197449).
The font of a control can now be specified in a nib. The nib format supports both kControlFont constants and kThemeFont constants.
The SingleLine control property can now be specified in a nib for a Unicode edit text control (3156265).
Notable Bug Fixes
Previously, the enable state of a menu in a nib was ignored, and the resulting MenuRef was always enabled. IBCarbonRuntime now obeys the enable state of the menu itself (2788446).
IBCarbonRuntime now clears the mark on the selected menu item of menus attached to popup button, bevel button, and popup group box controls, so if you previously had code to clear the mark manually, you won't need that code on Mac OS X 10.3 and later (2874782).
Icon Services
Header file (HIServices): Icons.h
Features and Enhancements
A new API, GetIconRefFromTypeInfo, returns the appropriate IconRef for a file, given at least one of the file's creator code, file type, extension, or MIME type. This API is useful when determining an icon for a file that does not exist in a mounted filesystem; by using this API, it is no longer necessary to create temporary local file with the remote file's attributes.
A new API, GetIconRefFromIconFamilyPtr, creates an IconRef given a pointer to the IconFamily data. This is the data that is found in an 'icns' resource.
Two new IconServicesUsageFlags flags have been added: kIconServicesNoBadgeFlag and kIconServicesUpdateIfNeededFlag. NoBadge causes the icon to be drawn without a badge, even if it would normally have one; UpdateIfNeeded causes the cached icon image data to be updated if necessary, if the image data has changed at runtime.
Internet Config
Header file (HIServices): InternetConfig.h
Notable Bug Fixes
The value returned by ICSeed is now incremented when any process updates the IC preferences (3159683).
Keyboards
Header file (HIToolbox): Keyboards.h
Features and Enhancements
The Keyboard Input menu, previously added to each application's menubar, has been converted into a menu extra, and now appears on the right side of the menubar. The new menu also incorporates the contents of the current input method's menu. The Keyboard Input menu also now has a menu item to open KeyCaps (now called Keyboard Viewer) and Character Palette.
The KLGetIndexedKeyboardLayout API has been removed from HIToolbox. It was accidentally included in the Mac OS X 10.2 release, but was not meant to be public.
Menu Manager
Header file (HIToolbox): Menus.h
Features and Enhancements
The Menu Manager has been updated to support using an HIView to draw the content of a menu (2456194). All standard menus now use a new view, HIStandardMenuView, to draw their content. Developers may provide their own custom HIViews to draw custom menu content, or override the standard menu view. When an HIView is used to implement custom menu content, the Menu Manager automatically provides menu scrolling behavior (2456179) and automatically caches the menu content image to improve performance when the menu is next displayed (2827581). See "HIView Support in the Menu Manager" at the end of this document for more details.
Two new HIView subclasses, HIMenuView and HIStandardMenuView, are provided for use by application developers. HIMenuView is the base class from which most custom menu HIViews should inherit; HIStandardMenuView is the view that is used to draw standard menu content.
Two new APIs, HIMenuViewGetMenu and HIMenuGetContentView, are provided as part of the HIView-based menu implementation. HIMenuViewGetMenu returns the MenuRef that is associated with an instance of HIMenuView; HIMenuGetContentView returns the HIView that is being used to draw the content of a MenuRef.
The Menu Manager now supports the NSUserKeyEquivalents dictionary for customization of command keys (3066055). This is a dictionary stored in the user preferences that contains mappings from menu item names to command keys. In Mac OS X 10.3, the Application Keyboard Shortcuts feature of the Keyboard preference pane uses this feature to customize the command keys of Carbon applications. A menu item's command key will be customized according to the content of the dictionary at these times: before menu size calculation, before command key matching, and before the command key is returned by GetItemCmd or GetMenuItemCommandKey. An application must use either the MenuEvent or IsMenuKeyEvent APIs, or handle kEventCommandProcess events for its menu item commands, to be compatible with this feature. If your application does not currently use the Menu Manager's command key matching code, we highly recommend that you attempt to switch to it, and file bugs if there are features that you need in order to adopt the Menu Manager code; if you absolutely cannot use the Menu Manager's code, there is a new plist key, UIDisallowUserKeyboardShortcuts, of type Boolean, which you may add to your application to indicate that your application is incompatible with this feature. If this key is set, the Keyboard preference pane will not allow your application to be selected as the target for customizing command key shortcuts, and the Menu Manager will not substitute command keys in your application.
A new API, CancelMenuTracking, allows applications to cancel any menu tracking that is currently occuring in that application.
The Menu Manager now provides type-select support for selecting a menu item (2693284).
The Menu Manager now supports Home, End, PageUp, PageDown, and various arrow-key combinations for keyboard navigation of a menu (2713397).
Several new menu attributes are available: kMenuAttrCondenseSeparators, kMenuAttrDoNotCacheImage, and kMenuAttrDoNotUseUserCommandKeys.
- kMenuAttrCondenseSeparators causes extra separator items at the beginning or end of a menu, or contiguous separator items inside a menu, to be hidden.
- kMenuAttrDoNotCacheImage prevents the Menu Manager from caching the menu contents image. The menu content view will be called to redraw the menu each time that the menu is displayed.
- kMenuAttrDoNotUseUserCommandKeys prevents the Menu Manager from substituting user command keys from the NSUserKeyEquivalents dictionary.
Two new menu item attributes are available: kMenuItemAttrAutoDisable and kMenuItemAttrUpdateSingleItem.
- kMenuItemAttrAutoDisable causes a menu item to be automatically disabled if kEventCommandUpdateStatus events for that item are not handled (3145707).
- kMenuItemAttrUpdateSingleItem is provided to improve the performance of command key matching by avoiding excess kEventCommandUpdateStatus events. When the Menu Manager finds a menu item that matches a command key event, its default behavior is to send a kEventMenuEnableItems event to that menu, which in turn produces kEventCommandUpdateStatus events for each item in the menu, and then verify that the menu item is still enabled. If the item has kMenuItemAttrUpdateSingleItem, however, the Menu Manager now only sends a single kEventCommandUpdateStatus event for that specific item, and does not send kEventMenuEnableItems at all. This greatly reduces event traffic during command key matching. This change requires explicit adoption by your application because your application may actually require the EnableItems or CommandUpdateStatus events to be sent for all items in the menu; if that is the case, you should not use kMenuItemAttrUpdateSingleItem. However, if your menu item enabling code entirely uses kEventCommandUpdateStatus event handlers, then we highly recommend that you set this attribute for all menu items in your application. InterfacerBuilder now automatically sets this attribute for newly created menu items; this does not cause any backwards compatibility problems with older versions of Mac OS X, because older versions of IBCarbonRuntime simply ignore this attribute, and so the event behavior is unchanged.
The HIObjectPrintDebugInfo API now prints useful information when passed a MenuRef (3047535).
The AXSize accessible attribute is now available for unopened menus; previously it was only available if the menu was open. The AXPosition attribute is now available for unopened menus that are top-level menus in the menubar. It is not available for submenus or popup menus, unless the menu is open.
The Menu Manager's Accessibility implementation previously returned AXMenu objects when asked for children of the menubar. The Menu Manager now returns AXMenuBarItem objects; an AXMenuBarItem has an AXMenu as its child.
The Menu Manager now tracks the parent menu of submenus, and uses this to implement the AXParent accessible attribute of a submenu, even when the submenu is not open. Previously, the AXParent attribute was only implemented for open submenus.
SetMenuTitleIcon now supports CGImageRefs as a possible icon type.
SetMenuItemCommandKey now supports a broader range of character code values for the command key parameter (2615155). The following character codes are now handled. In each case, the input character code is mapped to a menu item glyph code, and this glyph code is installed for the menu item using SetMenuItemKeyGlyph:
- 0x03 (kEnterCharCode in Events.h) generates kMenuEnterGlyph
- 0xF729 (NSHomeFunctionKey in AppKit/NSEvent.h) generates kMenuNorthwestArrowGlyph. Note that 0x01 (kHomeCharCode) does not map to a function key glyph code; this was required for compatibility with some applications that pass 0x01 to SetMenuItemCommandKey and that expect the value to be used as a literal command character.
- 0x04 (kEndCharCode) and 0xF72B (NSEndFunctionKey) generate kMenuSoutheastArrowGlyph
- 0x05 (kHelpCharCode) and 0xF746 (NSHelpFunctionKey) generate kMenuHelpGlyph
- 0x08 (kBackspaceCharCode) generates kMenuDeleteLeftGlyph
- 0x09 (kTabCharCode) generates kMenuTabRightGlyph
- 0x0A (kLineFeedCharCode) and 0x0D (kReturnCharCode) generate kMenuReturnGlyph
- 0x0B (kPageUpCharCode) and 0xF72C (NSPageUpFunctionKey) generate kMenuPageUpGlyph
- 0x0C (kPageDownCharCode) and 0xF72D (NSPageDownFunctionKey) generate kMenuPageDownGlyph
- 0x19 (NSBackTabCharacter in AppKit/NSText.h) generates kMenuTabLeftGlyph
- 0x1B (kEscapeCharaCode) generates kMenuEscapeGlyph
- 0x1C (kLeftArrowCharCode) and 0xF702 (NSLeftArrowFunctionKey) generate kMenuLeftArrowGlyph
- 0x1D (kRightArrowCharCode) and 0xF703 (NSRightArrowFunctionKey) generate kMenuRightArrowGlyph
- 0x1E (kUpArrowCharCode) and 0xF700 (NSUpArrowFunctionKey) generate kMenuUpArrowGlyph
- 0x1F (kDownArrowCharCode) and 0xF701 (NSDownArrowFunctionKey) generate kMenuDownArrowGlyph
- 0x7F (kDeleteCharCode) generates kMenuDeleteRightGlyph
- 0xF704 through 0xF712 (NSF1FunctionKey through NSF15FunctionKey in AppKit/NSEvent.h) generate the F1 through F15 function key glyphs
- 0xF73A (NSClearDisplayFunctionKey) generates kMenuClearGlyph
User Interface Changes
The algorithm used by the Menu Manager to determine the bounds of a popup menu has changed. Previously, the Menu Manager would prescroll the menu content inside the menu so that the selected item was under the mouse, but this would often leave large amounts of blank white space in the menu. This no longer happens; instead, the Menu Manager now almost always positions the menu at the specified location, and as the menu scrolls, the menu window is resized to make room for the newly visible menu items. If the menu popup point is very close to the top or bottom of the screen, instead of positioning the menu at the popup point, the menu may be moved entirely above or below the popup point, if necessary to avoid popping up the menu with an item other than the selected item under the menu (1198655).
The Preferences item in the Application menu is now initially hidden until the application searches for it by calling GetIndMenuItemWithCommandID( NULL, kHICommandPreferences, 1, ... ). This allows apps that don't use the Preferences item to avoid having a disabled item always in their menu. Also, the Preferences item now has a default command key of cmd-, in accordance to the Aqua HIG. This command key is automatically removed if the application adds a submenu to the item or if cmd-, is used somewhere else in the application's menus.
The Apple menu now contains a menu item to open the Software Update preference pane.
The Apple menu now includes the user's name in the Log Out menu item, so you can be sure about which user will be logged out (2866361).
The Apple menu now hides the Recents menu item entirely, or the Applications or Documents sections of the menu, if the corresponding user preference for the maximum number of recent applications or documents is zero (2931548).
Menu content in standard menus is now drawn using an HIView in a composited window (2645529). The menu background is drawn separately (by the window's content view) from the menu item text; this has a beneficial effect that when the menu scrolls, the menu item text now scrolls but the menu background does not. In previous versions of Mac OS X, the menu background lines also scrolled, which caused a disturbing moire effect in the background.
Menus that use the standard appearance are now prevented from being wider than 3/5ths of the display on which they are being presented, to avoid drastically wide menus. Also, menu item text is now truncated with an ellipsis at the middle of the text, rather than at the end.
Implementation Changes
Since the Menu Manager now uses HIViews to draw menu content, and HIViews must be drawn inside Carbon WindowRefs, each menu now creates a WindowRef as well. These WindowRefs will be visible in the window list; your application must be prepared to see them. Menu windows are automatically disposed a short time after menu tracking completes, and are reallocated when a menu is next opened.
A behavior change has been implemented when loading a menu with an 'xmnu' resource: previously, if a both a 'MENU' and an 'xmnu' specified a submenu ID, the MenuRef would, after being loaded with GetMenu, contain both hMenuCmd and the menu ID in the item command/mark, and the menu ID from the 'xmnu' in a separate location. If the submenu IDs in the 'xmnu' and the 'MENU' are different, GetMenu will now clear the item command key/mark so that only the submenu ID from the 'xmnu' is recorded; this is the same behavior as you'd get if you had called SetMenuItemHierarchicalID, and is not considered a bug, but may cause problems for apps that have the menu ID specified in both locations and expect the item's command key to be hMenuCmd. In that case, the menu ID should be removed from the 'xmnu'.
The Menu Manager previously used the default CF runloop mode (kCFRunLoopDefaultMode) when running the event loop during menu tracking. It now uses NSEventTrackingRunLoopMode for mach-o applications that are linked on Mac OS X 10.3, and for all CFM applications (since CFM apps are all implicitly LaunchCFMApp applications, and LaunchCFMApp was linked on Mac OS X 10.3). If you happen to be installing an event loop source on the main thread's runloop and you want your source callbacks to be called during menu tracking, you should install your source on kCFRunLoopCommonModes instead of kCFRunLoopDefaultMode; the event-tracking mode is automatically made part of the common modes.
Command-key-matching behavior has changed in several ways to improve matching behavior for non-US keyboards and provide behavior requested by developers. The primary changes are:
- when determining if a keyboard event matches a menu item, the Menu Manager sometimes needs to re-run keyboard translation. Previously, the retranslation step would sometimes strip off the command key modifier. The Menu Manager now dynamically determines whether a given virtual key on the current keyboard layout should have the command key preserved for all key translation, and if so, keeps the command key modifier. This significantly improves the correctness of command-key matching on non-US keyboard layouts such as Russian, especially when modifiers other than the command key are required for a menu item (2755945).
- when determining if a keyboard event matches a menu item, if the menu item requires the command key modifier, and the keyboard event has more modifiers pressed than are required by the menu item, then the Menu Manager re-runs the keyboard event through key translation using only the modifiers that were specified in the menu item. If the same character is produced as was originally in the keyboard event, then the event is deemed to not match the menu item. For example: on a US keyboard with US layout, press cmd-control-=. This generates an event with the '=' character. This event should not match cmd-= in the menus; it should match cmd-control-= instead.
- when a keydown event is examined for matches against the available command keys, the Menu Manager now prefers a match to a command key specified by virtual keycode over a match to a command key specified by character code (2835164). For example, if menu item A has a command key specified by the virtual keycode 0x51, which is the '=' key on the numeric keypad, and menu item B has a command key specified by the character code for '=', then the Menu Manager will now always return menu item A when the '=' key on the numeric keypad is pressed. Previously, which menu item was returned was dependent on which item the Menu Manager found first.
The Menu Manager's use of the kEventMenuEnableItems event has changed in several ways to improve performance during command key matching:
- Previously, when searching for a menu item that matched a keyboard event, and the command key cache was not valid, the Menu Manager would first send kEventMenuPopulate to a menu, then send kEventMenuEnableItems, and then search the menu for a menu item containing a matching command key. If a matching item was enabled, then the Menu Manager returned that item. In Mac OS X 10.3, the Menu Manager still sends kEventMenuPopulate to a menu, but then searches the menu for a matching menu item without sending kEventMenuEnableItems. If a matching item is found, the Menu Manager sends kEventMenuEnableItems to the menu, and then verifies that the item is enabled; if no matching menu item is found, then kEventMenuEnableItems is never sent.
- Previously, when the command key cache was valid, the Menu Manager would locate items in the cache with the same command key as a keyboard event, send kEventMenuPopulate and kEventMenuEnableItems to each cached menu, and then check the cached item to determine if it matched the command key event. In Mac OS X 10.3, the Menu Manager still sends kEventMenuPopulate to a cached menu, but then