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 determines if the cached item matches the command key event before sending kEventMenuEnableItems. If the item matches, then the Menu Manager sends kEventMenuEnableItems and then verifies that the item is enabled; if the item did not match (usually because its menu item modifiers did not match the modifiers in the keyboard event), then kEventMenuEnableItems is never sent.
- If the menu item that matches the keyboard event also has the kMenuItemAttrUpdateSingleItem attribute, then the kEventMenuEnableItems event is not sent at all; instead, only a single kEventCommandUpdateStatus event is sent, just for the matching item.
The effect of these changes is to greatly reduce the number of kEventMenuEnableItems and kEventCommandUpdateStatus events that are sent during command key matching. In applications that use the command key modifier for all of their menu items, and that generally keep the command key cache valid, the effect probably will not be noticable; but for applications that often invalidate the command key cache, that have menu items with command keys that don't use the command key modifier, or that handle the kEventMenuMatchKey event, these changes should provide a noticable performance improvement during normal typing.
Notable Bug Fixes
Very long menus (more than 2500 items or so) now draw and scroll correctly. Previously, the MDEF had a variety of 16-bit coordinate limitations that prevented drawing and scrolling from working properly. HIStandardMenuView does not have these limitations.
Menu items that are scrolled out of view may now be selected using the Accessibility API (3004492).
Navigation Services
Header File: Navigation.h
Features and Enhancements
The NavigationServices dialogs for opening and saving files have been redesigned to include the following new features:
- both list view and column view are now available, with the ability to switch back and forth at the user's choice
- a sidebar on the left side of the window that shows the mounted volumes and a user-editable selection of common filesystem locations
- the Favorites/Recents popup menu now presents a path hierarchy for the current directory
- when presented in sheet form, the dialogs are now transparent
Implementation Changes
The implementation of the Navigation Services dialogs has changed significantly in Mac OS X 10.3. The dialogs are now built from nibs instead of 'DITL' resources; the dialogs now use compositing windows; the dialogs now use Carbon event handlers for most user interaction, and HIView layout APIs to control most dialog layout as the dialogs change size. These changes have caused a variety of incompatibilities with various applications that customize their Navigation Services dialogs, which Apple has generally tried to work around to avoid problems with shipping applications. Nonetheless, the rules for compatibility with Navigation Services dialogs remain very simple, and are unchanged from previous releases. Following these rules will ensure that your Navigation Services custom areas work properly on all releases of Mac OS X.
- You must inform Navigation Services of every control or control hierarchy that you wish to add to the custom area. To do this, always use the NavCustomControl API with the kNavCtlAddControl or kNavCtlAddControlList selectors. Navigation Services will automatically position your controls in the appropriate location, and will automatically embed them inside a special non-compositing user pane. Optionally, you can embed a single user pane into the dialog (and call NavCustomControl with kNavCtlAddControl for the user pane), and then embed other controls inside the user pane, using the user pane's coordinates to determine the coordinates of the embedded controls. You do not need to call NavCustomControl for embedded subcontrols, but only for controls that are directly embedded in the dialog's content view.
- do not assume or hardcode the number or position of any dialog items in the default Navigation Services dialog. In Mac OS X 10.3, since Navigation Services no longer uses 'DITL' resources to create its dialogs, the dialogs actually have no dialog items in them. To find out how many items are in the dialog, use the NavCustomControl API with the kNavCtlGetFirstControlID selector; make this call after adding your custom items to the dialog.
- do not assume that the default button can be found by fetching dialog item one.
- do not reposition, change the title of, or otherwise modify any control that you do not own in the Navigation Services dialog. The standard controls
in Navigation Services dialogs may be changed or removed between releases of Mac OS X.
- do not rely on the existence or position of, or otherwise examine any control that you do not own in the Navigation Services dialog. The standard controls in Navigation Services dialogs may be changed or removed between releases of Mac OS X.
- do not use AutoEmbedControl to embed your custom controls into the Navigation Services dialog. Instead, either call the NavCustomControl API with the kNavCtlAddControl selector, or embed subcontrols into another control that has already been embedded using NavCustomControl and kNavCtlAddControl.
- when adding controls to a Navigation Services dialog, do so when the kNavCBStart message is sent to your NavEventProc (as documented in Navigation.h). Do not add custom controls during kNavCBCustomize.
- do not change the behavior of your custom area based on existence of kWindowCompositingAttribute in the Navigation Services window's attributes.
Any custom area content that you add using the Navigation Services APIs as of Mac OS X 10.3 will be drawn and managed in non-compositing mode even if
the window itself is in compositing mode.
- make sure to return an accurate height for your custom area when your NavEventProc is passed the kNavCBCustomize message.
- avoid erasing behind any standard controls (such as push buttons, popup buttons, check boxes, etc.) that you add to the custom area. Those controls and/or the Control Manager will erase automatically.
- when erasing, do not make assumptions about the color/pattern/brush to use for the custom area background. Make sure your custom control definitions call the SetUpControlBackground API appropriately before they erase; do not hardcode your control background to a particular theme brush or color. Any non-control erasing you do in response to an update or similar event must use the background color/pattern in the window's GrafPort at the time you are informed of the event; Navigation Services will set up the window's background color/pattern appropriately before giving you the event.
- avoid explicitly drawing the controls in your custom area. Navigation Services automatically draws all visible controls in the window, including any that you add to the custom area.
- do not cache the rectangle that is passed to your NavEventProc with the kNavCBAdjustRect message; this rectangle may change again by the time you are called to draw your custom controls. Instead, always consult the NavCBRec.customRect field to determine the bounds of your custom control area.
Pasteboard Manager
Header file (HIServices): Pasteboard.h
The Pasteboard Manager is a new API that provides common data-sharing behavior similar to the Scrap and Drag Managers. It is not necessary to adopt the Pasteboard Manager; you can continue to use the existing Scrap and Drag Managers. However, the Pasteboard Manager API has these advantages:
- A pasteboard may contain multiple items. The Scrap Manager API only supported a single item on the scrap.
- Using the Pasteboard Manager APIs, the same code may be used for copy/paste, drag-and-drop handling, and service handling. The Scrap Manager could not be used for drag-and-drop.
- Pasteboard flavors are described using Uniform Type Identifier strings rather than OSTypes. UTI strings allow compatiblity with Cocoa's NSPasteboard, more accurately describe the data being transported, provide a type inheritance mechanism, and allow namespacing with a reverse DNS scheme.
The Pasteboard Manager provides the following new APIs:
PasteboardClear
PasteboardCopyItemFlavorData
PasteboardCopyItemFlavors
PasteboardCopyPasteLocation
PasteboardCreate
PasteboardGetItemCount
PasteboardGetItemFlavorFlags
PasteboardGetItemIdentifier
PasteboardGetTypeID
PasteboardPutItemFlavor
PasteboardResolvePromises
PasteboardSetPasteLocation
PasteboardSetPromiseKeeper
PasteboardSynchronize
Process Manager
Header file (HIServices): Processes.h
Features and Enhancements
The KillProcess API has been added to Processes.h. This API was actually available in Mac OS X 10.2 and later.
A new API, TransformProcessType, may be used to convert a UIElement or BackgroundOnly application into a regular foregroundable application with a menubar and Dock icon (2848736).
Scrap Manager
Header file (HIToolbox): Scrap.h
The Scrap Manager has been reimplemented to be a thin layer on top of the Pasteboard Manager.
Notable Bug Fixes
When PutScrapFlavor is called to promise the same flavor type more than once, it now returns duplicateScrapFlavorErr, matching the behavior of CarbonLib, rather than noErr as in previous versions of Mac OS X.
Text Services Manager
Header file (HIToolbox): TextServices.h
Features and Enhancements
There are significant changes to the Input menu that is provided by the Text Services Manager on behalf of input methods. In previously versions of Mac OS X, the MenuRef returned by an input method was displayed in the frontmost application as part of the application's menubar. In Mac OS X 10.3, the contents of the input method's menu are now displayed in a new Input menu on the right side of the menubar, grouped with other system menus. Notably, the input method's menu is no longer displayed as a separate top-level menu; the menu contents are embedded inside the single Input menu.
This new user interface is implemented by the Text Services Manager by copying the menu items out of the menu returned by the input method, and sending those to a separate process (the SystemUIServer process), where the menu item contents are recreated as part of the Input menu. Before the input method menu contents are copied, the Text Services Manager sends kEventMenuPopulate, kEventMenuOpening, and kEventMenuEnableItems events, to allow the input method to populate and enable its menu items appropriately for the current application context.
Some notable compatibility implications of these change include:
- changes to the menu title of the input method menu are no longer visible anywhere in the user interface, because the input method menu is no longer inserted into the menubar.
- Carbon event handlers for kEventMenuTargetItem installed on the input method menu will not be called during tracking of the Input menu, because that menu is entirely separate from the input method menu.
- input method menus cannot use a custom MDEF or custom HIView to draw the menu contents.
The Text Services Manager supports a new Carbon-event-based protocol for communicating between text engines and input methods (3177045). This protocol is implemented by the kEventTSMDocumentAccess Carbon event class. MLTE automatically handles these events. The following Carbon events are new in Mac OS X 10.3 as part of this protocol:
kEventTSMDocumentAccessGetLength
kEventTSMDocumentAccessGetSelectedRange
kEventTSMDocumentAccessGetCharactersPtr
kEventTSMDocumentAccessGetCharactersPtrForLargestBuffer
kEventTSMDocumentAccessGetCharacters
kEventTSMDocumentAccessGetFont
kEventTSMDocumentAccessGetGlyphInfo
kEventTSMDocumentAccessLockDocument
kEventTSMDocumentAccessUnlockDocument
The following new APIs are provided:
CopyTextServiceInputModeList
IsTextServiceSelected
Added kTSMDocumentUnicodeInputWindowPropertyTag for Unicode support in bottom line Text Input window.
MLTE
Header file (HIToolbox): MacTextEditor.h
Features and Enhancements
A new set of APIs has been introduced for creating and manipulating MLTE objects that is easier to use in conjunction with the modern HIView system and data types. These APIs include:
TXNDrawObject
TXNCreateObject
TXNAttachObjectToWindowRef
TXNGetWindowRef
TXNSetDataFromCFURLRef
TXNFlattenObjectToCFDataRef
TXNSetHIRectBounds
TXNGetHIRect
TXNSetScrollbarState
TXNHIPointToOffset
TXNOffsetToHIPoint
MLTE now uses QuickTime to import graphics data, which automatically allows any QuickTime-supported graphics data format to be included in an MLTE object (2497939).
MLTE no longer requires the client to call TXNInitTextension. The first call to TXNNewObject will call it if the client hasn't already. NULL values will be used in that case.
MLTE supports the new TSMDocumentAccess Carbon events (3191151).
A new TXNFrameOptions bit, kTXNDoFontSubstitutionMask, allows the client to turn on font substitution before MLTE reads in any data with TXNNewObject.
Translation Manager
Header file (HIToolbox): Translation.h, TranslationExtensions.h
The Translation Manager is obsolete on Mac OS X. Its APIs have never been implemented. It is now replaced by the Translation Services Manager.
Translation Services Manager
Header file (HIServices): TranslationServices.h
The Translation Services Manager is a new API introduced to replace the obsolete Translation Manager API. The old Translation Manager API was not suitable for the Mac OS X environment; it did not support Unicode, FSRefs, or interoperability with Cocoa applications. The Translation Services Manager provides an extensible mechanism for translating data from one format to another.
Translation Services provides the following new APIs:
TransformProcessType
TranslationCopyDestinationType
TranslationCopySourceType
TranslationCreate
TranslationCreateWithSourceArray
TranslationGetTranslationFlags
TranslationGetTypeID
TranslationPerformForData
TranslationPerformForFile
TranslationPerformForURL
Window Manager
Header file (HIToolbox): MacWindows.h
Features and Enhancements
Floating windows now support kWindowMetalAttribute.
A new window attribute, kWindowAsyncDragAttribute, allows a window to be dragged by the WindowServer without the owning application being involved. This improves the user experience by allowing windows of applications that are temporarily not responding to events to still be dragged; however, note that the standard window-dragging Carbon events (kEventWindowBoundsChanging/BoundsChanged) will not be sent during an async window drag. If you require those events for your window in order to modify its position during dragging, you should not use this attribute. The Window Manager will still send the kEventWindowDragStarted and kEventWindowDragCompleted events, but the DragStarted event will typically not be sent until some time after the user has actually started dragging the window. Note that this attribute is ignored (async drag is not used, and your application must still call DragWindow) if your window is grouped with other windows in a window group that has the kWindowGroupAttrMoveTogether attribute.
A new window attribute, kWindowDoesNotCycleAttribute, indicates that a window does not participate in window cycling via the Rotate Windows hotkey (cmd-` on a US keyboard) or the Focus on Document hotkey (ctrl-F4).
Two new window transition effects, kWindowFadeTransitionEffect and kWindowGenieTransitionEffect, are now available (2823386, 2725363). These can be used to show and hide a window, respectively, by gradually changing its alpha value and by using the Dock's genie effect. A new API, TransitionWindowWithOptions, is available for use with all transition actions and effects; this API provides the ability to control the duration of the transition, and allows the transition to run either synchronously or asynchronously.
A new API, HIWindowChangeClass, allows some windows to change visual appearance into other types of windows (2600234, 3163684). Specifically, the following window classes may be changed from one to another: kDocumentWindowClass, kFloatingWindowClass, kUtilityWindowClass, and kMovableModalWindowClass.
A new API, HIWindowChangeFeatures, allows changes to the feature flags for an existing window. Previously, a window's feature flags were determined at creation time by the WDEF or window frame view, and could not be changed.
A new API, DetachSheetWindow, allows a sheet to be detached from its parent without using the sheet animation (3162886). This may be useful if you want to close the sheet window without animating; you can now use DetachSheetWindow and then HideWindow or DisposeWindow on the sheet.
A new API, HIWindowIsDocumentModalTarget, can be used to determine whether a window is currently the parent window of a sheet.
A new API, HIWindowFlush, is a convenience wrapper around QDFlushPortBuffer. However, for compositing windows, it does also cause a redraw of any invalid views in the window.
The Overlay, PlainDialog, Simple, and SimpleFrame window classes now support compositing mode.
kAXSheetCreated and kAXDrawerCreated notifications are now sent when sheets or drawers are shown, and kAXUIElementDestroyed notifications are sent when sheets or drawers are hidden.
RepositionWindow allows the parent window to be the same as the input window for the OnParentWindowScreen positioning methods, allowing a window to be easily positioned on its current screen (3204753).
Previously, ResizeWindow and GrowWindow would send kEventWindowGetMin/MaxSize events first, and then send kEventWindowResizeStarted. These APIs now send the ResizeStarted event first, followed by the GetMin/MaxSize events. This allows event handlers for the GetMin/MaxSize events to customize their behavior based on whether the sizes are needed for resizing, or for some other purpose.
Routing of command events sent to sheets has changed slightly. Previously, a command event that was not handled by the sheet window's event target would be routed directly to the application target. An unhandled command event is now routed to the sheet's parent window first, and then to the application.
IsWindowPathSelectEvent can now handle any type of event that has kEventParamMouseLocation and kEventParamKeyModifiers parameters. Previously it only handled kEventMouseDown events. It will still return false for kEventMouseUp events, even though these have the required parameters.
Dragging a window may now be canceled by pressing Escape or Command-period (2815588).
The DragWindow API now obeys its boundsRect parameter; this parameter limits the area in which the window can be dragged.
The window class constant kSimpleWindowClass has been added to MacWindows.h. This window class creates a simple frameless window, the same as creating a window by procID using kWindowSimpleProc. kSimpleWindowClass is actually available in Mac OS X 10.1 and later.
Implementation Changes
Improvements to the metal window rendering code and the compositing drawing path increase the speed of resizing an empty metal window by up to 75% compared to 10.2. In general, window resizing in both non-compositing and compositing windows is at least 10% faster than 10.2, and often as much as 30% faster.
Notable Bug Fixes
Previously, changing the bounds of a control in a window during live resizing could sometimes cause the window titlebar widgets to be drawn incorrectly. This is now fixed (3110971).
Destroying a sheet that is attached to a parent window will now detach the sheet from the parent before the sheet is destroyed (3162886).
When a composited window is resized using TransitionWindow, drawing by its views will now be flushed during the resize (3077987). Previously the flush would not occur until after the transition had finished. This means, for example, that a window that is being resized by TransitionWindow may now relayout its window contents and expect the drawing of the contents in their new positions to be visible as the window resizes.
kAXWindowCreated notifications are now sent when windows are shown, not when they are initially created; kAXUIElementDestroyed notifications are now sent when windows are hidden.
Sheets now return kAXSheetRole instead of kAXWindowRole.
HIView Support in the Menu Manager
Summary
The contents of a menu can now be drawn using an HIView instead of an MDEF. There is a standard HIView provided by the Menu Manager which is used to draw the contents of all menus that use the standard Aqua appearance, and this view may be re-used or subclassed by applications.
The view used to a draw a menu's content is called a "menu content view." Note that this is not the same as a window content view; in fact, the menu content view is embedded inside the window content view of the window that is displaying the menu.
Implementing a custom menu using an HIView instead of an MDEF has several advantages:
- The Carbon Event and HIView APIs are now the standard techniques for extending the user interface of a Carbon application. By supporting HIViews in menus, there is less to learn and understand when an application needs to customize its interface.
- The HIView event-handling and drawing model is much richer than the MDEF model. HIViews can easily use CoreGraphics to draw.
- The Menu Manager provides a base class, HIMenuView, which implements some of the common behaviors required of a menu content view. By subclassing HIMenuView, a new menu view needs to implement only a very small set of Carbon event handlers.
- HIViews can be used in both menus and windows, and in fact, in Mac OS X 10.3, a WindowRef is used to contain menus that are displayed from the menubar or as popups. We plan to provide tear-off menus in a future release of Mac OS X, and these will also use the same HIView drawing model.
- The Menu Manager provides automatic support for menu scrolling when the menu uses an HIView.
- To improve performance, the Menu Manager provides automatic support for caching a menu content view's image and drawing the menu's initial contents using the cached image.
Creating A Menu With A Custom Item View
The MenuDefSpec structure has been extended to contain a class ID and initialization EventRef. When creating a menu that uses a custom item view, a developer specifies the view's class ID, but does not provide an HIViewRef directly. The Menu Manager will create the menu content view lazily as necessary, when a view is needed to display a menu's contents. This approach is required because a given MenuRef's contents may be displayed in multiple windows; you can see the menu contents both as a pull-down from the menubar, and (in the future) as a tear-off menu. In this case, there will two instances of the custom view, one for the menubar window, and one for the tear-off window.
Converting MDEFs to HIViews
Writing a new HIView for use in a menu, or converting an existing MDEF to an HIView, requires implementing some of the standard Carbon events for HIViews. A menu content view must implement these events:
kEventScrollableGetInfo
kEventControlDraw
kEventControlHitTest
kEventControlGetPartRegion
kEventControlGetOptimalBounds
A menu content view may also optionally implement these events:
kEventMenuCreateFrameView
kEventMenuGetFrameBounds
kEventMenuBecomeScrollable
kEventMenuCeaseToBeScrollable
kEventScrollableScrollTo
kEventControlSetFocusPart
kEventControlSimulateHit
kEventControlGetPartBounds
When converting an existing MDEF to an HIView, the MDEF messages are converted to HIView events as follows:
kMenuInitMsg kEventControlInitialize
kMenuDisposeMsg kEventControlDispose
kMenuFindItemMsg kEventControlHitTest
kMenuHiliteItemMsg kEventControlSetFocusPart
kMenuDrawItemsMsg kEventControlDraw
kMenuDrawMsg kEventControlDraw
kMenuSizeMsg kEventControlGetOptimalBounds
kMenuPopUpMsg kEventMenuGetFrameBounds
kMenuCalcItemMsg kEventControlGetPartRegion
kMenuThemeSavvyMsg no replacement
The Menu Manager has a special interpretation of the part codes returned by a menu content view: a part code is exactly equivalent to a menu item index. For example, if the third menu item in the menu is selected, the menu content view should return a part code of 3 in response to kEventControlHitTest. Because Control Manager part codes are signed 16-bit integers, this limits the maximum number of menu items supported by a menu content view to 32767.
Although the Control Manager has traditionally interpreted the part codes with values 254 and 255 as indicating that the view is inactive or disabled, menu content views do not support this interpretation, and the Control Manager does not use this interpretation with menu content views.
Event Handling and Tracking
Event handling in a menu content view does not normally use the standard control tracking events, such as kEventControlClick or kEventControlTrack. Instead, the Menu Manager runs its own event loop that intercepts mouse events; in response to a mouse-moved or mouse-dragged event, the Menu Manager calls the view to hit-test the point, and if the view returns a non-zero part code, the Menu Manager calls the view to set its focused part to that menu item.
Before handling a mouse event, the Menu Manager sends it to the event dispatcher target to allow normal event dispatching to take place. This will result in kEventControlClick and kEventControlTrack events being sent to the view under the mouse. Normally, a menu content view will not respond to this events, or more specifically, it will return a non-zero error code immediately and not allow the Control Manager's default handling of these events to begin a control tracking loop. The HIMenuView base class provides this behavior automatically, but a menu content view that does not subclass HIMenuView should install a handler for kEventControlClick and return an error, such as paramErr, to prevent control tracking from occuring.
The exception to this rule is when a control is placed into a view that should be tracked using normal control tracking. For example, you might put a slider control into a view. The slider does not handle kEventControlClick or kEventControlTrack, so the Control Manager handles these events and initiates control tracking. The Control Manager will then track the user's mouse movements and the slider will respond appropriately; during this time, the Menu Manager is not handling events and no menu item tracking is occuring. When the user releases the mouse, the Menu Manager will regain control of menu tracking.
Scrolling
The Menu Manager provides automatic scrolling support for menus that use a menu content view. A view that subclasses HIMenuView gets scrolling support automatically, as long as it allows HIMenuView to handle the kEventScrollableScrollTo event.
A view that does not subclass HIMenuView should implement kEventScrollableScrollTo itself, use HIViewSetBoundsOrigin to change its bounds origin, and invalidate itself. Scrolling is then automatic.
The arrows at the top and bottom of a scrolling menu are drawn by the content view of the window containing the menu content view. There is a standard content view that is created and returned by the menu window frame view provided by HIMenuView; to get automatic scrolling arrows, a menu content view must currently subclass from HIMenuView.
Caching
The Menu Manager provides automatic menu image caching support for menus that use a menu content view. After the window contents have been drawn by the window's HIView hierarchy, the Menu Manager automatically caches the window image. When the menu is next opened, if nothing has changed to invalidate the menu contents, the cached image is used to redraw the menu window instead of calling the HIView hierarchy to draw.
Any call to InvalidateMenuSize or InvalidateMenuItems will invalidate the menu image cache.
The Menu Manager can be directed to not cache a menu's image by setting the kMenuAttrDoNotCacheImage attribute on the menu.
Standard Views
The Control Manager provides a built-in view, HIMenuView, that has useful default behavior and is designed to be subclassed by custom menu content views. Most menu content views should start by subclassing this view. HIMenuView does not draw, hit-test, or determine view size or part bounds, but it does provide this default behavior:
- marks the view as ignored by Carbon accessibility
- sets the kHIViewDoesNotUseSpecialParts and kHIViewAllowsSubviews feature flags
- implements kEventMenuCreateFrameView to return the standard menu window frame view
- implements kEventMenuGetFrameBounds to determine the bounds of pull-down, popup, and hierarchical menus
- implements kEventControlSetFocusPart to handle changing focus between menu items
- implements kEventControlSimulateHit to flash the selected item off and on
- implements kEventScrollableScrollTo to set the bounds origin and invalidate the view
- implements kEventControlClick by simply returning paramErr. This prevents clicks in the menu view from causing the Control Manager's default tracking behavior to be invoked; menu tracking must be handled by the Menu Manager, not the Control Manager.
- implementskEventControlHit by simply returning noErr for events that originate with the menu view control. This prevents clicks in the menu view from causing kEventControlHit events to be sent to the application, which might not be expecting them.
The Menu Manager provides a built-in view, HIStandardMenuView, that provides the standard menu item appearance. Your application may subclass this view to add its own custom behavior.
The class IDs for HIMenuView and HIStandardMenuView are defined in HIView.h:
#define kHIMenuViewClassID CFSTR("com.apple.HIMenuView")
#define kHIStandardMenuViewClassID CFSTR("com.apple.HIStandardMenuView")
Other
The width and height of a menu that uses a menu content view are always the total width and height of the menu, regardless of the actual height of the screen. MDEFs were expected to calculate a height that was limited by the size of the screen; menu content views always report their total height in response to kEventControlGetOptimalBounds. This affects the return values from GetMenuWidth and GetMenuHeight.
Menu Content View API Changes and Additions
CreateCustomMenu
The CreateCustomMenu API has been enhanced to allow specification of an HIView class and an initialization EventRef, using the MenuDefSpec structure:
enum { kMenuDefClassID = 1 };
struct MenuDefSpec
{
MenuDefType defType;
union
{
MenuDefUPP defProc;
struct
{
CFStringRef classID;
EventRef initEvent;
} view;
} u;
};
By setting the MenuDefSpec.defType field to kMenuDefClassID, and setting the MenuDefSpec.u.view.classID field to the name of a registered HIView subclass, your application can create a custom menu that uses the specified view to draw its menu items. When instances of the view are created, the event provided in the MenuDefSpec.u.view.initEvent field will be passed to HIObjectCreate.
HIMenuGetContentView
The HIMenuGetContentView API returns the HIViewRef used by a menu to draw its menu items for a certain type of menu, specified by a ThemeMenuType parameter:
extern OSStatus HIMenuGetContentView( MenuRef inMenu, ThemeMenuType inMenuType, HIViewRef* outView );
The Menu Manager will lazily create the view when it is first requested, and cache it internally. The view should not be released by the caller. Note that the Menu Manager may choose to return the same view or a different view based on the menu type, and that the behavior of the Menu Manager may change from release to release.
HIMenuViewGetMenu
The HIMenuViewGetMenu API returns the MenuRef that is associated with an HIView that is a subclass of HIMenuView. It should not be passed an HIView that is not a subclass of HIMenuView.
extern MenuRef HIMenuViewGetMenu( HIViewRef inView );
An HIMenuView subclass might use this API to determine the menu that it should draw.
Menu Attributes
The Menu Manager supports a new menu attribute, kMenuAttrDoNotCacheImage. This attribute indicates that a menu's image should not be automatically cached by the Menu Manager. Instead, the menu window's HIView hierarchy is called to draw the menu contents each time that the menu is displayed.
Menu Carbon Events
The following Carbon events are used by menus. All of these events are sent directly to the menu; all of them are sent only to the menu itself, and are not propagated past the menu event target.
kEventMenuCalculateSize
This event is sent by CalcMenuSize to the MenuRef to determine the size of the menu. The Menu Manager provides a default handler for all menus that calls the menu's MDEF or menu content view to determine the menu size. Applications will typically not need to handle this event; a custom menu definition or menu content view should use kMenuSizeMsg or kEventControlGetOptimalBounds to calculate its size.
Menu Content View Carbon Events
The following Carbon events are used by menu content views. All of these events are sent directly to the menu content view; all of them are sent only to the view itself, and are not propagated past the view event target.
kEventControlGetOptimalBounds
This event is sent in response to kEventMenuCalculateSize to determine the size of a menu content view.
All menu content views must implement this event. In response to this event, a menu content view should calculate its total size. A view will probably want to store the size internally in its instance data, so that it can be efficiently returned in response to kEventScrollableGetInfo in the ImageSize parameter. A view may also use this event to cache information about its size and item layout.
kEventMenuCreateFrameView
This event is sent by the Menu Manager before a menu is shown, to create the HIViewRef that draws the frame of the window containing the menu.
This event is handled automatically by HIMenuView. The default handler responds to this event by returning an instance of the standard menu window frame view.
If a menu content view chooses to respond to this event, it should return an HIViewRef that will be used to draw the window frame of the WindowRef containing the menu content view. This HIViewRef is also responsible for creating a content view embedded inside itself; the menu content view will be embedded in the content view.
Event parameters:
--> kEventParamEventRef typeEventRef the initialization event that should be passed to HIObjectCreate, if the
created view is a subclass of the standard menu window frame view.
--> kEventParamMenuType typeThemeMenuType the type of menu for which to create a frame view
<-- kEventParamMenuFrameView typeControlRef on exit, contains the HIViewRef of the window frame view
kEventMenuGetFrameBounds
This event is sent by the Menu Manager before a menu is shown, to determine the bounds of the menu window frame that should be used to display the menu.
This event is handled automatically by HIMenuView. The default handler responds to this event by calculating an appropriate bounding rect based on the bounds of the menu, the available screen space, and the frame metrics of the menu window content view.
If a menu content view chooses to respond to this event, it should calculate a bounding rect and return it in the event.
Event parameters:
--> kEventParamMenuType typeThemeMenuType the type of menu: pulldown, popup, or hierarchical
--> kEventParamMenuIsPopup typeBoolean whether this is a popup menu
--> kEventParamMenuFrameView typeControlRef the HIViewRef being used to draw the menu window frame
--> kEventParamMenuDirection typeMenuDirection the suggested direction for the menu relative to its parent: left or right
--> kEventParamMenuItemBounds typeHIRect the bounds of the menu title (for pulldown menus), or the parent item
(for hierarchical menus), or the popup location (for popup menus)
--> kEventParamGDevice typeGDHandle the GDevice on which the menu is being displayed
--> kEventParamAvailableBounds typeHIRect the available positioning bounds on the GDevice. The menu frame rect
should be constrained to these bounds.
parameters that are only available when kEventParamMenuType is kThemeMenuTypeHierarchical
--> kEventParamParentMenu typeMenuRef the parent menu
--> kEventParamParentMenuItem typeMenuItemIndex the parent menu item
parameters that are only available when kEventParamMenuType is kThemeMenuTypePopUp
--> kEventParamMenuPopupItem typeMenuItemIndex the item in the menu that should be positioned at the popup location,
or zero if the menu should be positioned such that no item should be
selected
return parameters
<-- kEventParamBounds typeHIRect on exit, contains the frame rect for the menu window
kEventMenuBecomeScrollable
This event is sent by the Menu Manager when a menu becomes the most recently opened menu in the menu hierarchy. It is an indication that this menu content view is now a candidate for scrolling.
This event is handled automatically by the Menu Manager. The default handler responds to this event by installing event handlers that provide automatic scrolling behavior for HIView-based menus.
If a menu content view chooses to respond to this event, it should install its own event handlers on the menu content view, content view, or frame view, as necessary to implement its own scrolling support.
This event has no parameters.
kEventMenuCeaseToBeScrollable
This event is sent by the Menu Manager when a menu ceases to be the most recently opened menu. This occurs when the menu is closed, or when a submenu of the most recently opened menu is opened. It is an indication that this menu content view is no longer a candidate for scrolling.
This event is handled automatically by the Menu Manager. The default handler responds to this event by removing event handlers that were installed to provide automatic scrolling behavior for HIView-based menus.
If a menu content view chooses to respond to this event, it should remove whatever event handlers it installed in response to kEventMenuBecomeScrollable.
This event has no parameters.
kEventScrollableGetInfo
This event is sent by the Menu Manager at various times during menu layout and menu scrolling.
All menu content views must implement this event. In response to this event, a menu content view should return information about its total size, its view size, its scrolling line size, and its origin. The total size should be the size that the view calculated in response to kEventMenuCalculateSize. The view size should be the view's current bounds, as returned by HIViewGetBounds. The scrolling line size should be determined by the view based on its item height. The origin should be the view's current origin; this can be determined by calling HIViewGetBounds and returning the bounds origin.
kEventScrollableScrollTo
This event is sent by the Menu Manager's automatic menu scrolling code.
This event is handled automatically by HIMenuView. The default handler changes the origin of the view bounds, and then invalidates the entire view.
A menu content view may choose to respond to this event if it needs to track the origin itself or wants to implement customized scrolling.
kEventControlDraw
This event is sent to request a menu content view to draw the items in the menu.
All menu content views must implement this event. In response to this event, a menu content view should draw itself into the provided CGContextRef. This event also includes an invalid region, which can be used by a view to determine which parts of the view need to be redrawn; since menu content views often require complex drawing operations, it is usually best to only redraw the portion of the view contained in the invalid region. All menu content views must implement this event.
kEventControlHitTest
This event is sent by the Menu Manager during menu tracking, to determine which item is underneath a specified point.
All menu content views must implement this event. In response to this event, a menu content view should determine which menu item contains the specified point, and return the index of that item as the output part code parameter. If no item contains the point, the view should return a part code of zero. All menu content views must implement this event.
This event is sent only to the view itself; it is not propagated past the view event target.
kEventControlGetPartRegion
This event is sent by the Menu Manager to determine the bounds of a menu item.
All menu content views must implement this event. In response to this event, a menu content view should update the region parameter to include the area covered by the specified menu item, as indicated by the part code parameter. All menu content views must implement this event.
kEventControlSetFocusPart
This event is sent by the Menu Manager during menu tracking, to set the selected menu item.
This event is handled automatically by HIMenuView. The default handler responds to this event by calling GetControlRegion to determine the region of the items that are gaining or losing focus, and calls HIViewSetNeedsDisplayInRegion with the total invalid region.
If a menu content view chooses to respond to this event, it should determine the invalid region that describes the area of the part losing or gaining focus. The view should then call HIViewSetNeedsDisplayInRegion with the invalid region, and the view will then receive a kEventControlDraw message with an invalid region parameter covering that area, which will be redrawn automatically. Most views won't have to implement this event and can just use the default behavior provided by HIMenuView.
This event is sent only to the view itself; it is not propagated past the view event target.
kEventControlSimulateHit
This event is sent by the Menu Manager after a menu item is selected.
This event is handled automatically by HIMenuView. The default handler responds to this event by flashing the specified item off and on.
If a menu content view chooses to respond to this event, it should display some sort of visual feedback to indicate that a menu item was selected.
Mac OS X 10.2.5 Developer Release Notes:
High Level Toolbox
Version Checking
If you need to check for a specific version of the HIToolbox framework, you can use the CFBundleShortVersionString in the HIToolbox Info.plist dictionary. The short version of HIToolbox in Mac OS X 10.2.5 is 1.2.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 >= 0x121 )
// we have an HIToolbox with these fixes
else
// we do not have an HIToolbox with these fixes
Drag Manager
An application's drag-tracking handlers were sometimes being called while the application was inside its drag-received handler. [3137949]
MLTE
The caret in a MLTE edit field would blink even if the field was read-only. [3163745]
Text Services Manager
Pressing the Control key while using the Hanin input method would crash. [3188231]
Window Manager
In Mac OS X 10.2.4, when an invisible window in a WindowGroup that had the kWindowGroupAttrMoveTogether attribute was moved, the rest of the windows in the group were not moved. This was a regression from earlier versions of Mac OS X and is now corrected; all the windows in the group move regardless of whether the initial window is visible or invisible. [3189987]
Mac OS X 10.2.4 Developer Release Notes:
High Level Toolbox
Version Checking
If you need to check for a specific version of the HIToolbox framework, you can use the CFBundleShortVersionString in the HIToolbox Info.plist dictionary. The short version of HIToolbox in Mac OS X 10.2.4 is 1.2.2.
Accessibility
Tab controls were reporting a role of AXUnknown. They now correctly report their accessible role. [3101728]
Windows now support the following accessible attributes: AXCloseButtonAttribute, AXZoomButtonAttribute, AXMinimizeButtonAttribute, AXToolbarButtonAttribute, AXTitleUIElementAttribute, AXGrowAreaAttribute, and AXDocumentAttribute. [3101745]
A crash could occur when using requesting accessibility information for a scrollbar control. [3142308]
Appearance Manager
SetThemeCursor(kThemeIBeamCursor) now uses a xor-based cursor, so that the i-beam will invert over a black background. [3105672]
In Mac OS X 10.2, the ThemeTabTitleDrawProcPtr passed to DrawThemeTab was being called with incorrect bounds rect data. [3105333]
When a popup menu was displayed from a Dock tile, sometimes the portion of the menu frame that pointed at the tile was not positioned correctly. [3131017]
Carbon Event Manager
RemoveEventLoopTimer was not correctly removing event loop idle timers (it did work correctly for non-idle timers). [3101754]
In Mac OS X 10.2, UnregisterToolboxObjectClass would crash; the crash was fixed in Mac OS X 10.2.3, but the class was not actually unregistered. UnregisterToolboxObjectClass now actually unregisters the specified class. [3137396]
Control Manager
In Mac OS X 10.2, the title text of some disabled controls was remaining black rather than drawing with a gray disabled appearance. [3117930]
In Mac OS X 10.2.3, the viewSize parameter to CreateScrollBarControl was ignored. [3101788]
In Mac OS X 10.2, the round button control returned errDataSizeMismatch when asked for its ControlButtonContentInfo with GetControlData. [3103006]
EmbedControl returned errNoRootControl when embedding a control into a composited window. [3115488]
DataBrowser
GetDataBrowserListViewHeaderDesc crashed because of a NULL dereference. [3101706]
The DataBrowser could crash while handling the kEventAccessibleGetChildAtPoint event, when the mouse was over the topmost item in a list. [3103927]
Shift-selection of multiple items using the arrow keys did not work once more than two items were selected. [3104201]
Drag Manager
In Mac OS X 10.2, in some cases, a kDragTrackingLeaveHandler message would not be sent to a drag tracking handler when the mouse left the tracking handler's window. [3072587]
Internet Config
Changes to data accessible via Internet Config (such as proxy servers) in the System Preferences application would not update the Internet Config change seed. [3101710]
When setting a helper application with ICSetPref, the creator type is now used as a primary search key, and the application name is only used if no app can be found using the creator. [3130718]
Menu Manager
In Mac OS X 10.2, calling ShowMenuBar from an inactive process left the Menu Manager in an invalid state, and when the process later became active, ShowMenuBar and HideMenuBar no longer worked. Note that since the introduction of ShowMenuBar and HideMenuBar in Mac OS 8.5, it has not been necessary to call ShowMenuBar when an application is deactivated, or HideMenuBar when activated; the Menu Manager automatically shows and hides the menubar according to the current state of the frontmost application. [3101732]
MLTE
Right-justified single-line MLTE objects were sometimes drawing their text outside of the view rect. [3093879]
Text Services Manager
In Mac OS X 10.2, when switching applications, the selected keyboard layout was sometimes lost and the US keyboard layout became active. [3134910]
Window Manager
Improved the use of the window group API by HIToolbox so that showing a sheet on a window that is already grouped with another window will not break the existing grouping. For this fix to work properly, applications that create their own window groups using the kWindowGroupAttrMoveTogether and kWindowGroupAttrLayerTogether attributes should also make sure to specify the kWindowGroupAttrHideOnCollapse and kWindowGroupAttrSharedActivation attributes. Also, we have reports that this fix may not yet work for Navigation Services sheets. [3101751]
Mac OS X 10.2.3 Developer Release Notes:
High Level Toolbox
Version Checking
If you need to check for a specific version of the HIToolbox framework, you can use the CFBundleShortVersionString in the HIToolbox Info.plist dictionary. The short version of HIToolbox in Mac OS X 10.2.3 is 1.2.1.
Accessibility
The AXUIElementGetAttributeValueCount API always returned a count of zero when targeted at a UIElement in a Carbon application. Carbon now supports this API and returns a valid attribute value count. [2955841]
Carbon now supports setting kAXMinimizedAttribute and kAXMainAttribute on a window. [3043011, 3043018]
Calling AXObserverRemoveNotification on a Carbon UIElement no longer causes the observed application to crash. [3011370]
Carbon Event Manager
On Mac OS X 10.2, installing event handlers for kEventAppLaunched, kEventAppTerminated, and kEventAppFrontSwitched would fail if no calls to the Process Manager had been made yet. [2998556]
The TrackMouseLocation API was, in some cases, returning the coordinates of a mouse event in the coordinate system of the wrong window. This could cause errors in control tracking when attempting to track a control in one window as a result of a mouse-down operation in a separate window. [3015647]
In Mac OS X 10.2, UnregisterToolboxObjectClass would crash. It no longer crashes, but due to an additional uncorrected problem, the class is not really unregistered and attempting to re-register a class with the same name will still fail. [3047579]
Flushing events from a secondary thread's event queue could cause user input events to be posted to that thread's event queue instead of the main event queue, where they belong. [3055925]
Controls in composited windows using the standard window event handler would respond to clicks even when the window was inactive. [3024871]
Control Manager
If keyboard focus was on the popup button control in the HIToolbar configuration sheet when the sheet was dismissed, the popup button control would crash. [3006009]
Slider and scrollbar controls that used traditional ghost indicator tracking (non-live tracking) would not draw properly during tracking in a composited window. [3012817]
Views in a composited window were not properly invalidated when an overlapping view higher in the z-order was resized. [3024592]
Prior to Mac OS X 10.2, non-tracking icon controls would still return a valid part code when clicked, and would send a command event. This was broken in Mac OS X 10.2. The prior behavior has now been restored. [3042897]
The popup group box control in Mac OS X 10.2 was improperly consuming space-bar keyboard events intended for controls embedded inside the group box, preventing these events from being handled by the focused control. [3044507]
HIScrollView, when updating its embedded scrollbars in response to a kEventScrollableInfoChanged event, was ignoring the origin values returned by the event. It now sets the scrollbar values to match the new origin values. [3062849]
Prior to Mac OS X 10.2, HandleControlClick and TrackControl allowed tracking of inactive controls. This behavior was changed in Mac OS X 10.2 to disallow tracking of inactive controls. The prior behavior has now been restored. [3064331]
In Mac OS X 10.2, the EditUnicodeText control would ignore Return, Enter, and Escape keys if the window had a default or cancel button. The scope of this change was too broad. The control now ignores Return and Enter only if the window has a default button, and ignore Escape only if the window has a Cancel button. [3048348]
DataBrowser
The DataBrowser now supports type-selection in column view. Notably, this provides type-selection in NavigationServices Open and Save dialogs. [2413929]
Several long-standing arrow key navigation problems in column view were fixed. [2674257]
HIObjects
Using HIObjectRegisterSubclass to register a subclass of a system-defined class would fail if no instance of the system-defined class had yet been created. For example, registering a subclass of HIView would fail if no window or control had yet been created. This is now fixed. [3020648].
HIToolbar
Space and flexible space toolbar items no longer add blank items to the toolbar overflow menu. [2936745]
A toolbar item that implemented the kEventToolbarItemPerformAction event would not receive that event when the menu item in the toolbar overflow menu for that toolbar item was selected; instead, a kEventCommandProcess event for the toolbar item's command ID would be sent. A toolbar item's command ID can now be set to the new constant kHIToolbarCommandPressAction:
kHIToolbarCommandPressAction = 'tbpr'
to indicate that the item implements the kEventToolbarItemPerformAction event and that when the toolbar item's menu item is selected, a kEventToolbarItemPerformAction event should be generated instead of a command event. [2998182]
The toolbar item view now ignores keyboard focusing Carbon events if there is a custom view, which corrects some problems with keyboard focusing. [3005983]
Menu Manager
The Menu Manager sometimes attempted to redraw the menubar from a secondary thread. Since menubar drawing is not thread-safe, this often caused a crash. This problem was especially frequent in Connectix Virtual PC and Microsoft Remote Desktop Connection Client. [2979514]
UpdateStandardFontMenu would fail to remove existing items in the font menu before adding new items if the application had already removed items from the menu. [3004330]
The Menu Manager could crash if menu tracking was cancelled while a submenu was being populated with items. [3004857]
Using keyboard navigation in the menubar would prevent keyboard navigation of controls from working until the mouse was clicked again. [3004924]
MLTE
TXNDrawCFStringTextBox was not honoring the GrafPort's clip region. [3050031]
A crash could occur when TXNSetData was used to clear the contents of an MLTE object containing a picture. [3077098]
Window Manager
The window widget appearance in Metal windows has been changed slightly, to make the widgets appear embedded into the metal. [3090855]
Metal windows did not redraw after a monitor depth change. [3008335]
A drawer with resize limits such that its size was fixed in the direction of drawer movement (for example, min width same as max width for a drawer that opened to the left) could be moved into the parent, but couldn't be moved back out. [3013695]
Opening multiple drawers on the same window, and then closing one of them, would cause the other drawer to become visually disconnected from its parent window when the parent was moved. [3014186]
In Mac OS X 10.2, drawing performed by a custom window content paint proc could be clipped incorrectly. [3045407]
In Mac OS X 10.2, a floating window with a title that is created using NewCWindow would have a global port rect that was four pixels lower than the original bounds rect passed to NewCWindow. [3052503]
When a drawer window was created and shown, and the window's size at creation time matched its size when displayed, then the drawer did not draw properly. [3065392]
Mac OS X 10.2 Developer Release Notes:
High Level Toolbox
The High Level Toolbox is a subsystem of the Carbon framework for Mac OS X. It is composed of two frameworks: HIToolbox and HIServices. This document discusses changes in these two frameworks for Mac OS X 10.2.
Features and Enhancements
The major new features in the HIToolbox and HIServices frameworks for Mac OS X 10.2 are:
Accessibility API and support
Full keyboard access to controls and windows
HIObjects
HIView
HIToolbar
HIShape
Drawers
Combo Box
Automatic URL detection and browser launch (MLTE)
Support for monostyled text and mouse scroll wheel (MLTE)
Functions to support scrolling with controls created by clients (MLTE)
Keyboard Layout functions to access keyboard layouts (Keyboards)
Other Changes
WindowRefs, ControlRefs, and MenuRefs are all HIObjectRefs in Mac OS X 10.2, and HIObjectRefs are themselves CoreFoundation types, so it is now possible to use CFRetain/Release on a window, control, or menu, and to add windows, controls, and menus to CoreFoundation collections using the standard kCFTypeCallbacks.
HIToolbox now supports the NSQuitAfterLaunch environment variable. Setting this variable to 1 and then launching your application from the same shell will cause your application to quit as soon as it makes its first call to the event system. This can be useful in profiling your launch time and launch activities.
Background applications are now permitted to change the cursor over kUtilityWindowClass windows.
Added a new header file, HITextUtils.h. This header file currently contains one API, GetTextAndEncodingFromCFString, which previously was located in Appearance.h.
In Mac OS X 10.1, if you specified the transparent sheet brush for a sheet, we would turn on our rudimentary compositing model to get real transparent sheets. This is no longer the case. We were forced to revert the sheet brush back to opaque and turn compositing off due to differences in the coordinate systems between the compositing and traditional drawing models. By turning the sheet transparent, controls embedded in other controls would have drawn in the completely wrong location. You can still have transparent sheets in Mac OS X 10.2, but only if you specify the new kWindowCompositingAttribute at window creation. Interface Builder supports this attribute directly as well.
Suggested or Required Application Changes for Mac OS X 10.2 Savvyness
The kMouseTrackingMouseMoved constant (previously obsoleted by the kMouseTrackingMouseDragged constant) has been given a new value and a new meaning. If your source code currently uses kMouseTrackingMouseMoved, you should convert to using kMouseTrackingMouseDragged before recompiling with the Mac OS X 10.2 version of CarbonEvents.h. See "Carbon Event Manager" for more details.
We recommend that all applications support the kEventClassWindow/kEventWindowClose Carbon event, even if the application does not use the standard window event handler or support other Carbon events. A future version of Mac OS X is likely to allow users to close specific windows without clicking in the close box. This will be implemented by sending a kEventWindowClose event to the window. The standard window event handler already responds to this event by disposing the window. Applications will generally want to display a Save Changes? dialog in response to this event, so your application will probably need a handler for this event regardless of whether it uses the standard event handler.
To fully support accessibility, applications should use kEventCommandProcess or kEventControlHit Carbon events to detect clicks on controls. These events are sent when an accessibility client application invokes the Press action on a standard Carbon control. The Control Manager does not post fake mouse-downs or otherwise attempt to manipulate the event stream in response to a Press action, so applications which rely on seeing a mouse-down and calling TrackControl or HandleControlClick themselves in order to respond to a control click will be less accessible than applications which use kEventCommandProcess or kEventControlHit for notification of a control click.
Bug Reporting
We encourage all developers to file bugs found in Mac OS X 10.2 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."
Appearance Manager
Features and Enhancements
Theme brush constants for the primary and secondary highlight colors have been added to Appearance.h: kThemeBrushPrimaryHighlightColor and kThemeBrushSecondaryHighlightColor. These theme brushes are actually available in Mac OS X 10.1 and later. Using the theme brush is preferable to getting the hilite color from QuickDraw, since it allows for a non-solid-color highlight.
Added a new ThemeWindowType, kThemeDrawerWindow.
Added a new theme cursor, kThemeNotAllowedCursor, which is typically used to indicate that a drag may not be dropped at a certain location.
For the GetThemeTextDimensions API, the ioBounds parameter may now be NULL if inWrapToWidth is false, and the outBaseline parameter may be NULL.
More improvements to text rendering speed in DrawThemeTextBox, approximately 40% faster than 10.1.4.
Application Manager
Features and Enhancements
The HIApplicationGetCurrent API has been added to MacApplication.h. This API returns an HIObjectRef representing the application. The existing GetApplicationEventTarget API returns the event target associated with this HIObjectRef.
Two new APIs, GetSystemUIMode and SetSystemUIMode, have been added to MacApplication.h. These APIs allow control over the visibility of the dock and the menubar, and over various system UI features for process switching, logout, and restart/shutdown. The API defines four system UI modes:
- Normal. This is the standard mode for general-purpose applications. Both the Dock and menubar are visible.
- ContentSuppressed. In this mode, system UI elements which cover the "content area" of the screen (the area other than the menubar) are hidden. However, these elements may automatically show themselves in response to mouse movements or other user activity; specifically, the Dock will still show itself automatically when the mouse moves into the Dock's auto-show region.
- ContentHidden. In this mode, system UI elements which cover the "content area" of the screen (the area other than the menubar) are hidden. Unlike ContentSuppressed, most UI elements will not automatically show themselves in this mode.
- AllSuppressed. In this mode, all system UI elements, including the menubar, are hidden. Most system UI elements will not automatically show themselves in this mode. This mode is effectively the same as calling HideMenuBar; however, the application may request that the menubar automatically show itself while in this mode by passing the kUIOptionAutoShowMenuBar flag to SetSystemUIMode. When the AutoShowMenuBar option is specified, the Menu Manager will track the position of the mouse and make the menubar visible when the mouse moves into the area that would be covered by the menubar.
The API also allows selective disabling of the Apple menu, the Process Switch hotkeys (cmd-Tab/cmd-shift-Tab), the Force Quit hotkey, the Power key, and Shut Down/Restart/Log Out commands in the Apple menu.
There is also a new Carbon event, kEventAppSystemUIModeChanged, that is sent when the frontmost application changes its UI mode, or when a new application is activated that has a different UI mode from the previously active application.
The Process Manager supports a new key in an application plist, LSUIPresentationMode. This key should be of type number and should have one of the values 0, 1, 2, or 3, matching the kUIMode constants. This key may be used by applications to specify the initial UI mode for the application when it is launched.
Known Limitations
There is limited support in Mac OS X 10.2 for the ContentSuppressed and ContentHidden modes. The Dock has not yet added support for these modes, so it does not yet hide when these modes are requested. Also, the Process Manager does not yet support the use of the ContentHidden mode in the LSUIPresentationMode key in an application plist. These problems will be addressed in a future release of Mac OS X.
Carbon Event Manager
Features and Enhancements
Mac OS X 10.2 includes a new API for writing Carbon Event-based objects, the HIObject API. This API is declared in HIObject.h. An HIObject is effectively an EventTargetRef, but extended with object-oriented semantics such as a class registry, subclassing, and inheritance of behavior (via Carbon event handlers) from an object's superclass.
The following HIToolbox objects are now implemented as HIObjects: windows, controls, and menus. These objects may be passed to any HIObject API.
Developers can create their own HIObjects by registering an HIObject class and then creating an instance of the class. Such an object can then receive Carbon events, and its EventTargetRef may be passed to any Carbon Event Manager API that requires an event target.
New API and Carbon events have been added to support Accessibility. See "Accessibility" in the release notes for the Carbon Event Manager, Window Manager, Menu Manager, and Control Manager.
New API has been added for accessing queue-synchronized event state: GetCurrentEvent, GetCurrentEventButtonState, and GetCurrentEventKeyModifiers. These APIs allow you to get the event currently being processed by the event dispatcher, and to get the mouse button state and keyboard modifier state according to the events that have been dispatched; they do not return the current hardware state. These APIs are recommended for use over the existing GetCurrentKeyModifiers API as they are significantly faster (they do not need to ask the WindowServer for the current hardware state). Also added GetCurrentButtonState to get the current hardware state of the mouse buttons; again, you should generally use GetCurrentEventButtonState rather than GetCurrentButtonState unless you absolutely need the hardware state.
The SendEventToEventTargetWithOptions API has been added. This API allows sending an event with additional options: sending only to the specified event target, and sending to all handlers. Normally, an event will be propagated to the next handler or next event target as long as the current handler returns eventNotHandledErr. Any other return value will prevent the event from being propagated. You can now override this behavior in two ways: by specifying the kEventTargetDontPropagate option, the event will only be sent to handlers on the specified target, and will not be propagated to any other targets. By specifying the kEventTargetSendToAllHandlers option, the event will be sent to all handlers on all targets regardless of the return value of the handlers.
The MouseTrackingRegion API is now exported; see CarbonEvents.h. This API is recommended in all cases for tracking mouse movement and handling cursor changes; it has significant advantages over using mouse-moved events for this purpose, including lower CPU overhead and the ability to receive tracking-region events in an inactive application.
kEventMouseMoved, kEventMouseWheelMoved, and kEventRawKeyModifiersChanged events are now sent to utility windows even when the owning application is not active.
Previously, the TrackMouseLocation, TrackMouseLocationWithOptions, and TrackMouseRegion APIs did not support mouse tracking when no mouse button was pressed. In this case, they would simply block until a mouse button was pressed; they would ignore any mouse movements. These APIs now support mouse tracking while the mouse is up. The obsolete constant kMouseTrackingMouseMoved (previously equivalent to kMouseTrackingMouseDragged) has been brought back to life and given a new value. Its value is now 9, not 5. kMouseTrackingMouseMoved is now returned by TrackMouseLocation[WithOptions] if the mouse is moved while no mouse button is pressed; TrackMouseRegion continues to return kMouseTrackingMouseEntered/Exited if it sees the mouse enter or exit the specified region, but now supports mouse movement that occurs when no button is pressed. This change does not affect binary compatibility, but will cause silent semantic changes to source code that is recompiled with the new constant value. All existing code that uses kMouseTrackingMouseMoved should convert to use the preferred name, kMouseTrackingMouseDragged.
The Carbon Event Manager now automatically handles the window rotation hotkey. This hotkey is cmd-` by default. Cmd-shift-` will rotate windows backwards. The Carbon Event Manager will check for any use of this command key sequence in the current menubar before interpreting it as the window rotation hotkey, to avoid overriding existing application command key equivalents. The basic window event handler now supports two new HICommands, kHICommandRotateWindowsForward and kHICommandRotateWindowsBackward; these are sent to the user focus chain when the window rotation hotkey is pressed. An application can override the behavior of this hotkey by installing a Carbon event handler for kEventCommandProcess on the application target that looks for these command IDs and handles them itself. Applications may also add their own menu items that use these command IDs, and the Carbon event manager will automatically handle selections of these items using the Window Manager's standard window rotation code.
The Carbon Event Manager now automatically handles the document window, floating window, and toolbar focus hotkeys as defined in the Full Keyboard Access section of the Keyboard preferences pane. New Carbon events in the application event class are sent during focusing, which applications may override if necessary. The kHICommandRotateFloatingWindowsForward/Backward command IDs are used to initiate rotation of the application's floating windows.
Previously, to implement redrawing during live resizing, a Carbon application needed to handle the BoundsChanged event and call BeginUpdate/draw/EndUpdate. The standard window event handler now does this automatically; when it receives a kEventWindowBoundsChanged event, and the event has the UserResize attribute, and the window has the LiveResize attribute, and the window requires updating, then the standard window event handler now sends an update event for the window to the event dispatcher target. This enables live resizing to redraw window content automatically in windows that use the standard window event handler.
Mouse wheel Carbon events are now sent to the control underneath the mouse, rather than the focused control.
The Carbon event manager now automatically increments the refcount of some event parameter data when the parameter is added to an event. The parameter data's refcount is decremented when the event is destroyed. Refcounting is currently performed for the following data types: typeCFStringRef, typeCFMutableStringRef, typeCFMutableArrayRef, typeCFTypeRef, and typeHIAccessibleObjectRef. Because the data types that are refcounted may change in the future, we recommend that if you need to know whether a particular data type is refcounted, you simply create an event, add an instance of the data type to the event, and check if the refcount of the data has changed. This technique will correctly indicate the presence or absence of refcounting on any release of Carbon.
Accessibility
The following new Carbon events are part of the kEventClassAccessibility class:
kEventAccessibleGetChildAtPoint
kEventAccessibleGetFocusedChild
kEventAccessibleGetAllAttributeNames
kEventAccessibleGetNamedAttribute
kEventAccessibleSetNamedAttribute
kEventAccessibleIsNamedAttributeSettable
kEventAccessibleGetAllActionNames
kEventAccessiblePerformNamedAction
kEventAccessibleGetNamedActionDescription
These events are sent by HIToolbox when it receives a request from an external accessibility client for information about the application's accessible objects. An accessible object is any UI element in the application that can be represented by an HIObjectRef. An accessible object supports attributes and actions; attributes are properties of the object that hold data, and actions are user-interface-level changes to the application. A typical attribute might be "Value", to get the value of a scrollbar or slider. Attributes can be both read and written. A typical action might be "Pick", to pick a menu item or choose a button. Actions are invoked by external accessibility clients.
An accessible object is represented by the AXUIElementRef type. In order for Carbon apps to be accessible, they need a way to generate AXUIElementRefs for various Carbon widgets. To that end, we offer an API, AXUIElementCreateWithHIObjectAndIdentifier, to create an AXUIElementRef from any kind of Carbon HIObjectRef. This implicitly includes ControlRefs, WindowRefs, MenuRefs, or any custom HIObjectRefs an application may devise.
In fact, any HIObjectRef can represent a huge number of accessible objects. When creating an AXUIElementRef, you provide an HIObjectRef as well as a 64-bit integer which uniquely identifies one of the many accessible objects that the HIObjectRef represents. A whole MenuRef can be represented as an accessible object by providing the MenuRef and the integer zero. That
MenuRef's third menu item can be represented by providing the MenuRef and the integer three. (We use a 64-bit integer so Data Browser has the space it needs to represent all of its cells.)
Once an app developer understands how to represent its accessible objects, they can install Carbon Event handlers on the HIObjectRefs that they intend to make accessible. The Accessibility carbon events are used to gather information about accessible objects, as well as invoke actions on accessible objects.
HIToolbox already handles the accessibility Carbon Events for the standard system windows, controls, and menus. Developers are expected to handle them for custom areas of their applications, and they may choose to override the default handling for the standard system widgets in the normal Carbon Event fashion.
New and Improved Carbon Events
The following Carbon events are new for Mac OS X 10.2:
kEventAccessibleGetChildAtPoint
kEventAccessibleGetFocusedChild
kEventAccessibleGetAllAttributeNames
kEventAccessibleGetNamedAttribute
kEventAccessibleSetNamedAttribute
kEventAccessibleIsNamedAttributeSettable
kEventAccessibleGetAllActionNames
kEventAccessiblePerformNamedAction
kEventAccessibleGetNamedActionDescription
kEventAppFocusMenuBar
kEventAppFocusNextDocumentWindow
kEventAppFocusNextFloatingWindow
kEventAppFocusToolbar
kEventAppHidden
kEventAppShown
kEventAppSystemUIModeChanged
kEventControlDragEnter
kEventControlDragLeave
kEventControlDragReceive
kEventControlDragWithin
kEventControlEnabledStateChanged
kEventControlGetAutoToggleValue
kEventControlGetClickActivation
kEventControlGetNextFocusCandidate
kEventControlGetSizeConstraints
kEventControlHiliteChanged
kEventControlInterceptSubviewClick
kEventControlTitleChanged
kEventMouseEntered
kEventMouseExited
kEventTextInputUnicodeText
kEventWindowCollapsing
kEventWindowExpanding
kEventWindowFocusContent
kEventWindowFocusToolbar
kEventWindowGetDockTileMenu
The kEventParamPostTarget event parameter has been added to CarbonEvents.h. This event parameter contains an EventTargetRef to which a posted event should be dispatched by the event dispatcher target; it is especially useful for private application-specific events that are otherwise unknown to the event dispatcher. Such an event may be directed to a specific event target (a window event target, for example) by adding that event target to the event using this parameter. This parameter is actually available in all versions of Mac OS X, not just 10.2. Note that in versions of Mac OS X prior to 10.1, the Carbon Event Manager performed no validation on the event target; if you posted an event containing an event target, and then destroyed the object that supplied the event target before the event was dispatched, you would crash when the event dispatcher attempted to send the event to the (now invalid) event target. Mac OS X 10.2 validates the event target before attempting to use it, so this case will return an error.
The kEventWindowConstrain event has been extended with several new parameters. None of these parameters is guaranteed to be present in all Constrain events; event handlers should always be prepared for these parameters to be missing.
- kEventParamWindowRegionCode: this parameter is the region code that will be passed to ConstrainWindowToScreen. Application event handlers may modify this parameter and then allow the basic window handler to finish handling the event by returning eventNotHandledErr or calling CallNextEventHandler.
- kEventParamRgnHandle: this parameter is present if the Constrain event is being sent in response to a screen configuration change. It contains the old GrayRgn before the screen configuration change. Event handlers may wish to compare the window's position against the old GrayRgn to determine how it should be positioned on the new screen configuration.
- kEventParamAttributes: this parameter contains the options that will be passed to ConstrainWindowToScreen. Application event handlers may modify this parameter and then allow the basic window handler to finish handling the event by returning eventNotHandledErr or calling CallNextEventHandler.
- kEventParamPreviousDockRect and kEventParamCurrentDockRect: these parameters are present if the Constrain event is being sent in response to a change in the Dock. They contain the old and new dock bounds, respectively.
kEventWindowCursorChange events, in Mac OS 10.0 and 10.1, are posted to the queue and dispatched when removed. These events are now sent directly to the window receiving the event, and are never posted to the event queue.
kEventWindowCollapsing and kEventWindowExpanding are now available to indicate when a window is being collapsed to or expanded from the Dock. These have actually been sent since 10.1.
kEventCommandProcess, when sent from a menu item selection, now has a MenuContext parameter indicating whether the event originated from a popup menu or a menu in the menubar, as well as whether the menu item was selected via menu tracking or via a command key.
Contextual Menu Manager
Features and Enhancements
The Contextual Menu Manager now supports two new AE keywords for CMM plugin commands, keyContextualMenuAttributes and keyContextualMenuModifiers. These keywords allow specification of the menu item attributes and menu item modifiers for a menu item in a contextual menu. Using the attribute and modifier parameters, a CMM plugin may now: prevent menu item command text that starts with a dash from being interpreted as a separator (by specifing the kMenuItemAttrIgnoreMeta menu item attribute); create dynamic menu items that change according to the modifier keys pressed by the user (by specifying appropriate modifier key combinations).
Support for the Attributes and Modifiers keys in CMM plugin AERecords is indicated by the gestaltContextualMenuHasAttributeAndModifierKeys bit in the gestaltContextualMenuAttr selector.
The Contextual Menu Manager now supports more data types for the keyAEName parameter in a CM plugin command. Previously, the CMM supported typeChar and typeIntlText. Now, the CMM also supports typeStyledText, typeAEText, typeUnicodeText, and typeCFStringRef. Support for these additional types is indicated by the presence of the gestaltContextualMenuHasUnicodeSupport bit in the gestaltContextualMenuAttr result.
Since Mac OS X 10.0, the Contextual Menu Manager has supported a new value, kCMHelpItemRemoveHelp, for the inHelpType parameter to ContextualMenuSelect. This value causes the Help item to be removed from the contextual menu entirely. The symbolic constant for this value is now included in Menus.h.
Added the keyContextualMenuCommandID and keyContextualMenuSubmenu constants from the Contextual Menu SDK to Menus.h.
Implementation Changes
In general, the Contextual Menu Manager implementation has been cleaned up and modernized; it now internally stores menu item text with CFStringRefs instead of Str255s, and uses modern Menu Manager APIs.
Control Manager
Features and Enhancements
The Control Manager in Mac OS X 10.2 provides an entirely new API, HIView, for creating and managing standard and custom controls. This API provides many new features, including support for Quartz-based drawing, overlapping controls, controls on top of non-opaque backgrounds, control z-order manipulation, and more efficient invalid-region-based updating. To enable use of the HIView API, you must create the window containing the controls using the kWindowCompositingAttribute window attribute.
All Control Manager controls have been modified to support use in a compositing window, with the exception of the original (non-Unicode) EditText control, the ListBox control, and the scrolling TextBox control.
The Control Manager provides several new controls: a Combo Box control (HIComboBox), a toolbar control (HIToolbar), a scrolling container control (HIScrollView), and an image display control (HIImageView). Starting with Mac OS X 10.2, all new controls (HIComboBox, HIScrollView, and HIImageView) are initially invisible when created. You will need to call ShowControl (or the new HIViewSetVisible) to see the controls rendered on screen. All other controls are initially visible when created, but not drawn, as they always have been.
Controls are now internally implemented as HIObjects (which are CFTypes). This means that you can use CFRetain/Release on a ControlRef. It is also possible to create a ControlRef using HIObjectCreate.
The Control Manager supports the Accessibility API for the standard controls. It also provides some default behavior for custom controls. For all controls (standard and custom), the Control Manager supports the following attributes:
Window
Position
Size
Enabled
For the standard controls, the Control Manager also supports these attributes when applicable:
Title
Value
MinValue
MaxValue
Custom controls will need to support the Title, Value, MinValue, and MaxValue attributes themselves.
For the standard controls, the Control Manager supports the Press action, when applicable. Custom controls will need to support this action themselves.
kEventCommandProcess events sent by the menu attached to a popup button or bevel button control are now first sent to the control and its containing window. Previously, they were sent to the user focus target chain, which typically did not include the control and might not have even included the control's window if the control was in a non-focused window (such as a floating window). If the event is not handled after being sent to the control and window, it is still resent to the user focus chain.
A new structure definition has been introduced to augment the existing HICommand structure. The HICommandExtended structure is similar to the HICommand structure (and is the same size in memory), but includes extra unioned fields to indicate the source of an event. The HICommandExtended structure can indicate the source of an event to be a ControlRef or WindowRef, in addition to a MenuRef. kEventCommandProcess events originating from controls now set the kHICommandFromControl attribute bit and include the ControlRef in the HICommandExtended structure. Since the HICommandExtended structure is the same size and uses the same binary layout as the HICommand structure, it is backwards compatible with earlier versions of Mac OS X and CarbonLib; you can retrieve an HICommandExtended structure from a command event with the same code that you would use for an HICommand structure:
HICommandExtended cmd;
GetEventParameter( event, kEventParamDirectObject, typeHICommand, NULL, sizeof( cmd ), NULL, &cmd );
and then test the cmd.attributes field to determine if the structure has an originating object in it:
HIObjectRef source;
if ( cmd.attributes & kHICommandFromMenu )
source = cmd.source.menu.menuRef;
else if ( cmd.attributes & kHICommandFromControl )
source = cmd.source.control;
else if ( cmd.attributes & kHICommandFromWindow )
source = cmd.source.window;
The List Box control now supports creating a List Manager list using the standard icon LDEF. To create such a list, put the icon LDEF's procID (19) into the procID field of the 'ldes' resource.
The List Box control now supports the scroll wheel and responds to scroll wheel events by scrolling the list.
The bevel button control now supports drawing its icon at Huge and Thumbnail sizes, if the control is large enough.
Notable Bug Fixes
The EditText and EditUnicodeText controls can now safely be moved between windows using EmbedControl. Previously, they would fail to update their internal data to point at the new containing GrafPort.
The following bug was actually fixed in Mac OS X 10.1.3, but is described here for completeness: the Control Manager API IsAutomaticControlDragTrackingEnabledForWindow previously had a bug that would cause it to return true when no preference for automatic control drag tracking had yet been established. The proper return value is false in this case, and the API now behaves correctly. A notable effect of this change is that if you are creating a DataBrowser control in a window, and you would like drag tracking to occur inside the DB control, you must now call SetAutomaticControlDragTrackingEnabledForWindow(true) to enable drag tracking. Previously, because of this bug, drag tracking occurred by default if no preference had been established.
Dialog Manager
The text of alerts may now be optionally spoken by the operating system. This feature is not exposed at the application level; it is under the control of the user through the Speech preference pane.
Known Problems
Because the windows created by CreateStandardSheet are not yet implemented using compositing mode internally, standard sheets are opaque in Mac OS X 10.2. We intend to restore transparency to standard sheets in a future release.
Drag Manager
Features and Enhancements
The SetDragImageWithCGImage API has been added to the Drag Manager. This API allows setting a drag image using a CGImageRef, which may contain an alpha channel. A notable difference in usage between this API and the older SetDragImage API is that SetDragImageWithCGImage takes an HIPoint that is an offset from the drag mouse position, rather than an offset from the top, left of the global coordinate system.
The GetStandardDropLocation and SetStandardDropLocation APIs have been added. The Finder uses SetStandardDropLocation to indicate when a drag has landed in the trash. GetStandardDropLocation may now be used to easily determine whether a drag landed in the trash.
It is now possible to cancel a drag with Escape or cmd-period.
Help Manager
Features and Enhancements
Help tag behavior is closer to the original HI spec now: after moving the mouse off a help-enabled object, the tag stays visible for a short time before disappearing, and tags now fade away instead of hiding immediately.
Help tag content callbacks for controls, windows, menu titles, and menu items may now set the absHotRect to an empty rect, and the Help Manager will substitute the global coordinates of the object. Previously, this support of an empty absHotRect was only provided for help content attached with the HMSetControl/Window/MenuItemHelpContent APIs.
Help content using kHMTextResContent (a 'TEXT' resource) and kHMTEHandleContent (a TextEdit handle) is now supported. The text is assumed to use the application's text encoding.
The Help Manager supports a new type of help content in the HMHelpContentRec, kHMCFStringLocalizedContent. When this content type is specified, the HMHelpContent.u.tagCFString field should contain the name of a string in the application's Localizable.strings file. The Help Manager will automatically use CFCopyLocalizedString with that string name to load the localized help content.
Help tags are now transparent to events; mouse clicks that fall on a help tag will actually pass through the help tag and land on the window underneath the tag.
Notable Bug Fixes
Help tags for menu titles set with HMSetMenuItemHelpContent are now displayed. Previously, they would never be displayed due to a bug in HMGetMenuItemHelpContent.
Fixed a long-standing bug that a content provider callback would only be called to dispose content if the content type was kHMTEHandleContent. The callback is now called to dispose content for TEHandle, CFString, and CFStringLocalized content.
HIShape
HIShape is an abstract shape object for use with some of the HIToolbox APIs. It is designed as a replacement for RgnHandles (though it is currently implemented in terms of them at the time of this writing). This abstraction will allow us to avoid using QD types in our APIs, particularly in HIView.
Unfortunately, in Mac OS X 10.2 we did not have time to use HIShapeRefs anywhere in our HIView APIs, so look at this header as a kind of sneak peek. You can use this APIs to start using HIShapeRefs in your own code if you wish. When the Toolbox starts to use this in future releases, you will be able to pass your HIShapeRefs directly into APIs as you'd expect.
Icon Services
IconServices has been moved from HIToolbox.framework to HIServices.framework. IconServices now uses a server-based icon data store, which removes the icon data from each process. Most IconServices APIs are now thread-safe (see Icons.h for specifics on thread-safety).
Internet Config
InternetConfig has been moved to the HIServices framework.
Keyboards
New Keyboard Layout functions (Keyboards.h) provide access to keyboard layouts. Keyboard layout resources (KCHR/itlk/uchr/kcs#/kcs4/kcs8) are no longer available through the Resource Manager.
List Manager
The standard text and icon LDEFs now draw text with DrawThemeTextBox instead of QuickDraw. Aquarific!
Menu Manager
Features and Enhancements
The Menu Manager supports the Accessibility API and Carbon events.
Menus are now internally implemented as HIObjects (which are CFTypes). This means that you can use CFRetain/Release on a MenuRef. It is also possible to create a MenuRef using HIObjectCreate.
The Menu Manager no longer limits hierarchical menus to five deep. As many menus may be displayed as you have memory to allocate the menu data structures. The gestaltMenuMgrAttr selector includes a new bit, gestaltMenuMgrMoreThanFiveMenusDeepBit, which indicates that the Menu Manager supports hierarchical menus more than five deep.
Added the menu item attribute kMenuItemAttrIncludeInCmdKeyMatching to allow hidden menu items to participate in command key matching. Without this attribute, hidden menu items are always ignored during command key matching, unless they also have the dynamic menu attribute.
The 'xmnu' resource has been extended to include a version one format which allows setting a menu item's virtual command key, indent, and attributes.
A new menu attribute, kMenuAttrHidden, may be used to indicate that a menu which is inserted into the menubar should not be drawn in the menubar. Effectively, the menu does not exist visually. However, the menu is still included in command key matching, so this attribute may be useful for introducing hidden command keys that don't correspond to a specific menu item.
Added a new glyph to the .Keyboard font, the eject glyph. This glyph may be drawn in a menu item using the SetMenuItemKeyGlyph API and the new kMenuEjectGlyph constant.
When a menu tracking session ends, the Menu Manager now sends kEventMenuEndTracking to every menu that was opened during the session, in addition to the root menu. This is done to allow menus with dynamic content to remove that content at the end of menu tracking; for example, a menu containing many IconRefs might wish to load the IconRefs dynamically in response to a kEventMenuPopulate, and remove them in response to kEventMenuEndTracking, to avoid the memory overhead of keeping the IconRef data in memory while the menu is not being displayed.
kEventMenuPopulate is now sent to a menu before the menu is searched for a command ID by the CountMenuItemsWithCommandID and GetIndMenuItemWithCommandID APIs. This use of kEventMenuPopulate can be distinguished by the kMenuContextCommandIDSearch flag, which is set in the kEventParamMenuContext parameter to the event. When kEventMenuPopulate is used in this context, the Menu Manager also adds a kEventParamMenuCommand parameter with an MenuCommand containing the command ID that is being searched for.
New definitions have been added to Menus.h showing the format of a MenuBarHandle structure.
Previously, GetMenuTrackingData would only fill in the itemRect field for the most recently displayed menu. It will now place valid information in the itemRect field for any open menu.
Accessibility
The Menu Manager supports three types of accessible objects: the root menu, ordinary menus, and menu items. The root menu is a child of the application accessible object; the children of menus are menu items, and a menu item has either no children or a single child, its submenu. The root menu's children are menu items, and the child of each menu item is a top-level menu in the menubar.
Root menus, ordinary menus, and menu items all support reading the following accessible attributes. (w) indicates that the attribute is writable as well as readable.
Title (w)
Enabled (w)
Position
Size
Width
Height
SelectedChildren
VisibleChildren
All menu items support the Help accessible attribute. The value of the Help attribute for a menu item in the root menu is the Help Tag text for the menu title of the corresponding top-level menu. The value of the Help attribute for a menu item in an ordinary menu is the Help Tag text for the menu item.
In addition, menu items that are not in the root menu support these accessible attributes:
MenuItemCmdChar
MenuItemCmdVirtualKey
MenuItemCmdGlyph
MenuItemCmdModifiers
MenuItemMarkChar
All accessible menu objects support the Cancel action. Invoking this action causes any current menu tracking session to be dismissed.
Menu items support the Pick and Press actions. Invoking this action when the menus are closed causes a fake mouse-down to be posted to the application's event queue, which should cause the application to enable its menu item state properly and call MenuSelect; the picked menu item is then returned back to the application. If the menu is open, invoking this action simulates a click on the menu item. If menus are not being tracked and a Pick or Press action is invoked on a menu item in the root menu, a fake mouse-down is posted to the application's event queue to cause the application to begin menu tracking and open the specified menu.
Root menus and ordinary menus send these notifications:
MenuOpened
MenuClosed
Menu items send these notifications:
FocusedUIElementChanged
MenuItemSelected
The FocusedUIElementChanged notification indicates that a new menu item has been selected with the mouse or keyboard.
The MenuItemSelected notification indicates that a menu item has been selected using a command key equivalent or during a menu tracking session.
User Interface Changes
The "Hide Others" menu item in the Application menu now has command-option-H as a standard keyboard equivalent. However, this keyboard equivalent is automatically removed if the application already uses it in its menus.
The contents of the Apple menu are now displayed in the localization of the current application, rather than the localization of the OS install.
Implementation Changes
The Menu Manager's data structures for storing menu item data have been completely reimplemented using a new CF-based design. This has no effect at the API level, however.
The menu items in the standard Apple, Application, and Window menus are now added lazily, when these menus are first opened, rather than at application launch. This should improve application launch time. The menu items are also automatically added before the menus are searched for command keys or command IDs, so existing code that uses GetIndMenuItemWithCommandID to search for well-known command IDs such as kHICommandQuit or kHICommandPreferences should continue to work as before.
Notable Bug Fixes
kMenuAttrAutoDisable previously required that all items in a menu, including separators, be disabled before it would disable the menu title. It now ignores separators, so the enable state of the separator item no longer matters.
When a menu item command key is specified using a virtual keycode, the Menu Manager now uses KeyTranslate to determine the character code corresponding to that virtual key using the current keyboard layout. Previously, it always used the English keyboard layout to determine the character. Note that this only affects display of the command key equivalent, not the actual command-key matching process. For example, a menu item with vkey=13 would always display 'W' as its command key, even if you had a French keyboard layout where that virtual key generated the 'Z' key; but pressing that physical key together with the command key has always, and continues to, correctly match against a menu item with that virtual key.
Notification Manager
Notifications may now be optionally spoken by the operating system. This feature is not exposed at the application level; it is under the control of the user through the Speech preference pane.
Process Manager
The Process Manager has moved from HIToolbox.framework to HIServices.framework.
Added the SetFrontProcessWithOptions API to allow making a process frontmost without moving all of its windows to the front.
Text Services Manager
Features and Enhancements
The Text Services Manager now supports multiple different classes of input methods. Previously, all input methods were assumed to be keyboard-based input methods. TSM now supports ink input methods also.
New APIs include:
GetDefaultInputMethodOfClass
SetDefaultInputMethodOfClass
SelectTextService
DeselectTextService
TSMSetDocumentProperty
TSMGetDocumentProperty
TSMRemoveDocumentProperty
Notable Bug Fixes
Improved reliability of show/hide palettes when switching among applications that use different keyboard layouts and input methods.
Textension
Features and Enhancements
MLTE now supports automatic URL detection and browser launch. The level of support is comparable to the one WASTE provides.
A new frame option, kTXNMonostyledTextMask, indicates that the text has a single style. MLTE will enforce monostyled text when data is added to the object, including paste and drag and drop. Note that you can still call the TXNSetTypeAttributes function to set or change the text style. In the case of monostyled text, the new style will be applied to all the text in the object.
MLTE now automatically installs a Carbon event handler for kEventMouseWheelMoved event, hence providing automatic support for the scroll wheel mouse.
MLTE provides new functions to support scrolling with controls created by clients. TXNRegisterScrollInfoUPP enables you to create and manage your own scroll controls by installing a callback function. In this case, MLTE will invoke the callback function every time a user action causes the text to scroll. TXNScroll scrolls the text in an MLTE object in pixel, lines or viewrect units.
TXNClearUndo clears the undo and redo stack.
Implementation Changes
MLTE now uses the ATSUI function ATSUBatchBreakLines to break text into lines for improved performance in all operations that require to re-layout the text.
MLTE now uses CoreGraphics for all rendering operations.
Notable Bug Fixes
Previously clients were required to set QuickDraw style attributes one by one with TXNSetTypeAttributes. The API has been fixed so that all styles can be passed in a single call.
Window Manager
Features and Enhancements
WindowRefs are now internally implemented as HIObjects (which are CFTypes). This means that you can use CFRetain/Release on a WindowRef. It is also possible to create a WindowRef using HIObjectCreate.
The Window Manager now provides support for drawers. The basic steps for using a drawer are: create a drawer window using kDrawerWindowClass and kWindowCompositingAttribute; set the drawer's parent window using SetDrawerParent; and open or close the drawer using ToggleDrawer. Other APIs are available to control the drawer's leading and trailing offsets, determine its current state, and open the drawer on a specific parent window edge. Drawer windows must be created using compositing drawing mode.
The Window Manager supports the Carbon Accessibility API. The Window Manager provides the following attributes for all windows. (w) indicates that the attribute is writable as well as readable.
Title
Size (w)
Position (w)
Focused (w)
Miniaturized (w)
The Window Manager does not support any accessible actions.
The Window Manager now supports the use of HIViews to draw window frames. The document, floating, utility, and movable-modal window frames are now always composed of HIViews rather than being implemented by window definition functions, regardless of whether the window uses compositing mode; this is generally irrelevant to applications, however. Custom windows may also take advantage of this feature.
The GetPreviousWindow API has been added. It returns the window before a specified window in the window list.
The GetWindowAlpha and SetWindowAlpha APIs have been added. These functions control the transparency of an entire window, including its window frame. These APIs were actually available starting in Mac OS X 10.0, but had not previously been documented.
The GetAvailableWindowPositioningRegion API has been added. This API complements the existing GetAvailableWindowPositioningBounds API. The Region API, unlike the Bounds API, returns a RgnHandle describing exactly which areas of a GDevice are not covered by the Dock and menubar. The Bounds API trims the returned bounds to exclude the entire border of the device that may potentially be occupied by the Dock.
The GetWindowResizeLimits and SetWindowResizeLimits APIs have been added. These APIs set the minimum and maximum size of a window. When the Window Manager sends the kEventWindowGetMin/MaxResizeLimits events, there is now a default handler for these events that returns the size limits specified by SetWindowResizeLimits.
The GetWindowToolbar and SetWindowToolbar APIs have been added. These APIs are used to specify the HIToolbar object associated with a window.
The ShowHideWindowToolbar and IsWindowToolbarVisible APIs have been added. These APIs are used to control and query the visibility of the toolbar associated with a window.
The following window attributes have been added:
- kWindowCompositingAttribute requests that the window contents be drawn using the compositing mode of the Control Manager. In this mode, all window content must be drawn by HIViews; application content that is not rendered using an HIView is not supported. This attribute must be specified at window creation time; it cannot be changed later with ChangeWindowAttributes.
- kWindowMetalAttribute requests a metal appearance for the window. This attribute can be used with with document, floating, and utility-class windows. Windows that use the metal appearance must also use compositing mode and specify kWindowCompositingAttribute.
- kWindowIgnoreClicksAttribute requests that clicks in the window be ignored and instead passed through to whatever lies beneath the window. If some other window is beneath the window with this attribute, that other window will receive the mouse event instead.
kWindowOpaqueForEventsAttribute is now available for all types of windows. Previously it was only available for overlay windows.
Sheets must now use compositing mode in order to be transparent. Specifying kThemeBrushSheetBackgroundTransparent is no longer allowed unless the sheet you are applying it to has compositing enabled. This is because the compositing mode uses a different coordinate system than the traditional mode. If the transparent brush is set on a non-composited window, the opaque sheet background brush is substituted instead.
RepositionWindow supports a new positioning constant, kWindowCascadeStartAtParentWindowScreen.
ResizeWindow and GrowWindow both now send kEventWindowGetMinimum/MaximumSize events if their inSizeConstraints parameter is NULL. Previously, these events were only sent if the standard window event handler was being used (it would send these events before calling ResizeWindow).
kEventWindowZoomed is now sent from within ZoomWindow and ZoomWindowIdeal rather than from the standard window event handler. Therefore, it will now be sent in all cases when a window is zoomed, regardless of whether the zoom is invoked by the application or the standard event handler.
Previously, non-live window resizing would send a stream of BoundsChanging events of which the last event had a previousBounds parameter containing the window's original position (rather than its last position). Now, the previousBounds parameter of the last BoundsChanging event will contain the window's final position (typically, this will be the same as the previousBounds parameter in the next-to-last BoundsChanging event).
Added a new option for ConstrainWindowToScreen, kWindowConstrainUseTransitionWindow. This option causes ConstrainWindowToScreen to use TransitionWindow to set the window's new bounds, rather than using SetWindowBounds.
Various changes and improvements to the standard window constraint support, which moves windows back oncreen when a screen device or the Dock changes size: in response to Dock size changes, the Window Manager now uses TransitionWindow to move windows back on screen to give a cool sliding effect. In response to Dock and screen device changes, windows that use the standard Carbon event handler will be resized if the window is too large to fit onscreen; applications that use the standard Carbon event handler should install kEventWindowBoundsChanging/ BoundsChanged event handlers to detect when the window is resized. In response to screen device changes, windows that were previously entirely offscreen will now remain offscreen, and will not be forced onscreen. In response to screen device changes, windows that are not draggable will be forced entirely onscreen, instead of being allowed to be partially offscreen, since there's no way for the user to move a non-draggable window onscreen. In response to Dock size changes, if the Dock is getting smaller, no window constraining will occur.
The Window Manager now uses a more conservative approach to repositioning windows when the Dock changes size. Previously, the entire window would be forced on-screen if the Dock obscured the titlebar; now, just enough of the titlebar to allow dragging is moved onscreen. Also, the window will not be moved at all if the user resizes the Dock manually.
Previously, when a window had been marked modified with the SetWindowModified API, the window's proxy icon would become undraggable because dragging a window's proxy file would result in a copy of the file that didn't include the in-memory modifications to the file. Some applications, however, do not store their data in a file, and their proxy icon represents a URL or some other abstract identifier. Such applications typically use SetWindowProxyIcon to set their window's proxy icon. In this case (where the proxy is provided as an icon rather than as a file or alias), the proxy icon is now draggable even when the window is dirty, since the drag will not result in the movement of an out-of-date file on disk.
Added a new option to the standard Window menu, kWindowMenuIncludeRotate. Specifying this option to CreateStandardWindowMenu causes the window menu to include a "Cycle Through Windows" menu item that rotates the window list. This menu item is not added automatically because it also includes the standard command key for window rotation, cmd-`, and this command key might already be in use by applications that use the standard window menu; adding it automatically would override the use of this menu item in existing applications. Therefore we require applications to adopt this menu item explicitly to avoid command key conflicts.
When the ZoomWindow and ZoomWindowIdeal APIs send BoundsChanging/Changed events, they now include a new WindowBoundsChange attribute flag, kWindowBoundsChangeZoom, so you tell that the bounds change is originating from a window zoom.
The Window Manager now reliably sets the kWindowStandardHandler window attribute on a window even when the standard handler is installed with InstallStandardEventHandler( windowTarget ). If you need to determine whether a window is using the standard handler, it's safe to just test this attribute.
Carbon currently supports customizing the dock tile menu for an application. Applications are now allowed to also customize the dock tile menu for a collapsed window. For this purpose, a new Carbon event, kEventWindowGetDockTileMenu, and two new APIs, GetWindowDockTileMenu and SetWindowDockTileMenu, have been introduced. These parallel the existing kEventAppGetDockTileMenu Carbon event and Set/GetApplicationDockTileMenu APIs in MacApplication.h. When the Dock gets a control-click/right-click on a window's dock tile, the owning process now sends a kEventWindowGetDockTileMenu event to the window. The toolbox provides a default handler for this event that calls GetWindowDockTileMenu and returns the result. An application may therefore customize its windows' dock tile menus in two ways: statically by using SetWindowDockTileMenu, or dynamically by installing a Carbon event handler for kEventWindowGetDockTileMenu. After a selection is made from the window menu, the toolbox sends a kEventCommandProcess Carbon event to the window from which the menu item was selected (note: _not_ the user focus target).
User Interface Changes
When resizing a window, the Window Manager now allows the growbox to move into the areas adjacent to the Dock (for a bottom-oriented Dock, on its left and right). The grow box is prevented from moving underneath the Dock.
When dragging a window, the Window Manager now prevents the titlebar from going entirely underneath the Dock, and now allows the titlebar to be positioned partly in the area to the left and right of a bottom-oriented Dock.
Implementation Changes
Window transitions invoked by TransitionWindow, TransitionWindowAndParent, ShowSheetWindow, and HideSheetWindow are now run on the main thread, rather than a separate MP thread. This should (in theory) have no visible effect on any client of these APIs, except that the Carbon events send during window resizing (kEventWindowBoundsChanging andkEventWindowBoundsChanged) will now be sent on the main thread, instead of the separate MP thread. Handlers of these events may now therefore depend on being able to access their thread-local storage, which they previously could not.
Previously, kEventWindowClosed and kEventWindowHidden were sent in that order by the Window Manager to a window being destroyed. This can be problematic if you have a Hidden handler which uses data that is destroyed by the Closed handler. The Window Manager now sends these events in the reverse order: kEventWindowHidden first, followed by kEventWindowClosed. The last event sent to a window remains kEventWindowDispose.
Notable Bug Fixes
When a window is first created, its ideal user state rect is initially (0,0,0,0). Previously, GetWindowIdealUserState would return this rect, so if you were saving the window's state to disk as part of a document you had to check for an empty rect and use the window's current position instead. Now, GetWindowIdealUserState checks whether the window has a non-zero ideal user state. If the window's ideal user state is a zero rect, it automatically substitutes the window's current global port bounds.
Mac OS X 10.1 Developer Release Notes:
High Level Toolbox
The High Level Toolbox is a subsystem of the Carbon framework for Mac OS X. It is composed of two frameworks: HIToolbox and HIServices. This document discusses changes in these two frameworks for Mac OS X 10.1.
Window Manager
New APIs:
IsValidWindowClass
GetAvailableWindowAttributes
GetWindowGroupRetainCount
IsWindowLatentVisible
GetWindowStructurePort
kEventWindowBoundsChanging is now sent by the Window Manager before all window bounds changes, even when the window is changing bounds due to an explicit API call and not just by user move or resize action. Check the kWindowBoundsChangeUserDrag/Resize attribute bits in the kEventParamAttributes parameter of the event to determine whether the window's bounds are being changed programmatically or by the user.
The zoom box and grow box of a sheet's parent window are now accessible while the sheet is open. Previously, clicks on the zoom box and grow box were ignored. Sheet windows will automatically center themselves over their parent as the parent window is resized.
ShowSheetWindow now sends a deactivate event to the parent window of a sheet, requesting that the parent deactivate its content while the sheet is open. The parent's window frame will remain hilited; the parent should not unhilite its window frame in response to the deactivate event. If the parent window needs to determine whether its content is active, it should use IsWindowActive, not IsWindowHilited; the former will return false, while the latter will return true. The parent will receive an activate event from HideSheetWindow when the sheet is dismissed.
Transparent Sheets are now enabled via CreateStandardSheet, or any other case where a client sets the window's theme brush to the transparent sheet background brush (kThemeBrushSheetBackgroundTransparent).
Made toolbar button (for the title bars of windows, ala Finder, Mail, etc.) public.
The standard window menu now marks dirty windows with a bullet, in accordance with the Aqua HIG.
Added kSheetAlertWindowClass and kAltPlainWindowClass.
WDEFs may now set a new feature bit, kWindowIsOpaque, to indicate that their entire structure is opaque. This allows the Window Manager to avoid allocating an alpha channel for the window, reducing memory usage. (2637150)
CollapseAllWindows no longer collapses windows that don't have a collapse box. (2635164)
It was possible for windows to disobey the rules of window layering such that, for example, a document window came above a floating window. The window list maintained by the Window Manager was correct, but the visible order of the windows was not. This is now fixed. (2637150)
CollapseWindow(false) would uncollapse the window and also select it. It should not have been selecting it. Now it doesn't. (2640747)
kEventWindowExpanded is now sent after the window finishes expanding, instead of being sent immediately while the animation was still happening. (2649736)
altDBoxProc and kWindowShadowDialogProc work again. Previously, they produced document windows. (2658180)
Dialog Manager
In Mac OS X 10.0.x, the Alert and StandardAlert APIs would force the alert window to the top of the window list. This is no longer done in 10.1 and later. Instead, applications should use AEInteractWithUser or call the Notification Manager directly to request the user's attention before displaying an alert, as has always been the case in classic Mac OS.
CreateStandardSheet supports some new option flags, kStdAlertDoNotAnimateOnDefault/Cancel/Other. Each of the three flags applies to one of the three buttons in a standard sheet dialog. Setting a flag causes the sheet to disappear immediately when that button is chosen, rather than disappearing with the sheet animation. The most likely place where this ability will be used is in an AskSaveChanges dialog; the "Don't Save" button in this dialog should cause both the sheet and the document window to hide immediately, without any animation.
Carbon Event Manager
New APIs:
GetCFRunLoopFromEventLoop
IsMouseCoalescingEnabled
SetMouseCoalescingEnabled
CreateTypeStringWithOSType
New Carbon Events:
kEventAppGetDockTileMenu
kEventAppearanceScrollBarVariantChanged
kEventMenuDrawItem
kEventMenuDrawItemContent
kEventMenuMeasureItemHeight
kEventMenuMeasureItemWidth
kEventMenuPopulate
kEventServiceCopy
kEventServiceGetTypes
kEventServicePaste
kEventServicePerform
kEventWindowClickStructureRgn
kEventWindowClickToolbarButtonRgn
kEventWindowToolbarSwitchMode
GetCFRunLoopFromEventLoop can be used by applications which need to hook CFRunLoop sources into the Carbon event loop. It is important to call GetCFRunLoopFromEventLoop instead of CFRunLoopGetCurrent, as the main event loop is shared by all cooperative threads in an application. Since cooperative threads are actually implemented using pthreads, CFRunLoopGetCurrent on a cooperative thread will give you the wrong run loop to hook a source into.
IsMouseCoalescingEnabled/SetMouseCoalescingEnabled can be used to allow every mouse event generated by the driver to be queued up. By default coalescing is enabled, so as not to create mouse lag when dragging windows, slider, etc. Some applications may need finer mouse events, however, and these APIs can be used to control this. Be careful, however, as the event queue is limited in size - if you do not process the events quickly enough, the queue can overflow and events can be lost.
CreateTypeStringWithOSType is used primarily for Services in this release, though it may likely be used for more in future Mac OS releases. It is used to create an appropriate CFStringRef for a given OSType. Never assume that such a string will be simplistic, i.e. 'TEXT' won't necessarily turn into "TEXT", but may turn into something more elaborate such as "com.apple.type.text" or such. This API is designed to help insulate you from the specifics.
TrackMouseLocation used to assume that if it saw a MouseMoved event (only sent when the mouse is up), then it must have missed a MouseUp somehow, and it would return immediately with a MouseUp tracking result. TrackMouseLocation no longer makes this assumption. If it sees a MouseMoved, it just keeps tracking. If you are calling TrackMouseLocation in a case where your code assumes that the mouse button is already down, you should use StillDown to verify that before calling TrackMouseLocation. You should not use TrackMouseLocation for button-up mouse tracking.
Documented a bunch more HICommands.
Documented the MenuContext flags. These flags are included in most menu-related Carbon events. They indicate the context of the event - whether it's being sent from menubar tracking, popup menu tracking, command key matching, or menu title enabling. An event handler may want to inspect these flags to determine whether a menu is actually about to be displayed; if a handler creates or updates menu items during a MenuPopulate event, for example, it will be more efficient to only do that before display of the menu and not during command key matching, when accurate item text doesn't matter.
The default event handler for kEventWindowConstrainToScreen now extracts the constraint rect from the event and passes it to ConstrainWindowToScreen. Developers can therefore modify the default behavior by installing a handler on their windows that modifies the rect in the event and then returns eventNotHandledErr. (2648092)
Tablet events have been redesigned. Tablet info is now included in mouse events rather than being sent in a separate tablet event. However, if two-handed tablet input is happening, you will get tablet class events for the secondary input device (and mouse events with tablet information for the primary device).
Menu Manager
New APIs:
EraseMenuBackground
ScrollMenuImage
Many changes to improve menu drawing speed. There should be a noticeable difference.
Keyboard access to the menubar is now enabled. Enable and customize keyboard access using the Keyboard panel of the System Preferences application, and use ctrl-F2 to begin keyboard navigation of the menus, and the arrow keys to move from one menu item to another. The kEventMenuChangeTrackingMode Carbon event is now implemented, and is sent when menu tracking switches from mouse-based to keyboard-based and vice versa.
Add new APIs EraseMenuBackground and ScrollMenuImage for use by custom MDEFs.
The Services menu is now supported for Carbon applications. See <http://developer.apple.com/techpubs/macosx/Carbon/HumanInterfaceToolbox/MenuManager/appservices/index.html> for details.
The Menu Manager now supports new Carbon events for drawing a custom menu item inside an otherwise standard system-drawn menu. Set the kMenuItemAttrCustomDraw attribute on an item that requires custom drawing, and the Menu Manager will send kMenuEventMeasureItemWidth/Height events to measure the custom item, and kMenuEventDrawItem/DrawItemContent events to draw the item. If these events aren't handled by the app, they'll be handled by default handlers provided by the Menu Manager and the item will be drawn normally.
The Menu Manager now detects when the application uses one of the system-defined menu command keys (cmd-H for Hide and cmd-option-D for Turn Hiding On/Off), and removes the system-defined command key.
The Menu Manager now sends a new event, kEventMenuPopulate, before searching a menu for a command key match in MenuKey, MenuEvent, and IsMenuKeyEvent, and before displaying a menu. This event was added so that an application would have a single consistent time to add items to dynamically constructed menus; previously, the recommended time to add menu items was in a kEventMenuOpening handler, but this event isn't sent before a menu is searched for command keys.
A new Contextual Menu plugin API is available. This API is based on CFPlugin. See Menus.h for further comments and documentation.
Added new data structures to Menus.h that define the data passed via the whichItem pointer to the Draw and FindItem MDEF messages. These new data structures contain a CGContextRef field with the CGContext that the MDEF should draw into. Also added a CGContext to the Hilite data structure. All of these structures are valid for Mac OS X 10.0; that version provided a CGContextRef, but was simply not documented until now.
The Menu Manager supports two new icon types for the SetMenuItemIconHandle API: kMenuSystemIconSelectorType and kMenuIconResourceType. These are specifically designed to be used with a custom app dock tile menu; using one of these selectors is the only way to get an icon displayed in an app dock tile menu. When SetMenuItemIconHandle is used with kMenuSystemIconSelectorType, the "icon" parameter to the API should actually be the OSType of a standard system icon provided by IconServices, as listed in Icons.h. The Menu Manager will load the icon with GetIconRef(kOnSystemDisk, kSystemIconsCreator, iconSelector). When kMenuIconResourceType is used, the "icon" parameter to SetMenuItemIconHandle should be a CFStringRef containing the name of a .icns file located in the application's bundled resources. The Menu Manager will locate the file and register an IconRef using the data in the file, and then display the icon with the menu item. The CFStringRef will be retained by the Menu Manager.
CountMenuItemsWithCommandID and GetIndMenuItemWithCommandID now search hierarchical menus inserted into the menubar (with InsertMenu(hierMenu)) as well as menus directly reachable from the top-level menus in the menubar. This may be useful if you want to use these APIs to manipulate menu items in popup or contextual menus.
Improved the Menu Manager's command key cache so that when menu items are inserted or deleted, we update the cache instead of invalidating it. CodeWarrior likes to insert and delete items after nearly every keystroke, which was constantly invalidating the command key cache and slowing down typing; now the cache stays valid, improving typing speed.
Dock Integration
New APIs:
GetApplicationDockTileMenu
SetApplicationDockTileMenu
Carbon now supports customization of the popup menu displayed by the dock for an application's tile. Applications can add their own custom items to this menu, and be notified when the items are selected via a Carbon command event. There are several means available for customizing this menu: (1) if the application is bundled, and it only needs to add static, unchanging menu items, then the easiest way is to add a key "AppleDockMenu" to the application's plist. This key should be the name of a nib file in the application's resources (without .nib extension). That nib file should contain a menu object named "DockMenu". Carbon will automatically load the nib, create the menu, and provide it to the dock. (2) if the application is not bundled, or if it needs to create the menu at runtime, then there are two new APIs in MacApplication.h, SetApplicationDockTileMenu and GetApplicationDockTileMenu. These may be used to set and retrieve the current customized menu contents. (3) Finally, if the app needs to dynamically create the dock tile menu just in time as the user clicks on the tile, then there is a new Carbon event, kEventClassApplication/kEventAppGetDockTileMenu, that is sent to retrieve the menu. The default handler for this event returns the menu provided by SetApplicationDockTileMenu or the menu located in the dock menu nib, if any. Applications may install a Carbon event handler for this event and provide their own menu by calling SetEventParameter with kEventParamMenuRef and the menu to be displayed. Carbon will release this menu after it has been sent to the dock, so be sure to retain it with RetainMenu if you want it to remain in memory. In all cases, the contents of the menu provided by the application are inserted into the dock's standard menu contents after the window title items and before the Dock's standard items (Keep in Dock/Show in Finder/Quit). Selections from the menu will be communicated back to the application via a Carbon command event (kEventCommandProcess) sent to the user focus target, so it's important that all menu items provided by the application have command IDs, or the application won't be notified about selections of those items.
IBCarbonRuntime
Added support for Custom Controls (Both Proc-Ptr and event based).
Added support for plain and AltPlain window types
Added support for window auto-positionning (non parent based only)
Added support for toolbar button.
Added support for Unicode Edit field control
No menu item was selected for bevel button with menu causing some assertions. Also check selected menu item range for popup button
Added support for standard window menu.
MLTE
New APIs:
TXNGetActionChangeCount
TXNClearActionChangeCount
TXNGetRectBounds
TXNSetRectBounds
TXNRecalcTextLayout
Add support for single-line objects (kTXNSingleLineOnlyMask)
Add two new Textension public APIs, TXNGetActionChangeCount & TXNClearActionChangeCount, to get and reset count information for user specified action(s).
Scrap Manager
New APIs:
ClearScrap
GetScrapByName
Added GetScrapByName() which yields access not only to the standard "current" clipboard scrap (kScrapClipboardScrap = com.apple.scrap.clipboard) but the Cocoa style find scrap (kScrapFindScrap = com.apple.scrap.find) and any private named scrap a developer might choose. Private named scraps can be used as a high level IPC mechanism for helper apps for instance. It is suggested for developers to use the Java style naming scheme com.joeco.scrap.private. GetScrapByName() also takes OptionBits (kScrapGetNamedScrap, kScrapClearNamedScrap) which allow it to act as both getter and clearer of the scrap replacing both GetCurrentScrap() and ClearCurrentScap(). An example exists in /Developer/Examples/Carbon/SimpleText.
Appearance Manager
New APIs:
CopyThemeIdentifier
DrawThemeTextBox and related theme-text APIs have been optimized to speed up text drawing. Part of this optimization involves caching the CFString passed to these APIs. If you pass a mutable string, the API makes a copy of the CFStringRef; if you pass an immutable string, the API simply increments the refcount. This means that you should take care when passing immutable CFStringRefs that were created with the NoCopy option to the ThemeText APIs; they are simply retained, and the buffer that you passed to the CFStringCreate call must remain valid until the string is released, which is often not the case for many applications.
Added the kThemeMenuItemNoBackground flag to Appearance.h. This flag can be combined with other ThemeMenuItem values when calling DrawThemeMenuItem. It specifies that the Appearance Manager should not draw the menu background before drawing the menu item. This is a performance optimization if you're calling DrawThemeMenuItem from a custom menu definition (in which case the background has already been drawn for you) and it is a necessary step if you are using the Appearance Manager menu-drawing APIs to draw an image of a menu in a regular document window, as otherwise whatever is underneath the menu will be nearly erased by the effects of drawing the menu background twice at 90% alpha. This flag is supported in Mac OS X 10.0 and later; it was undocumented but still implemented in the original Mac OS X release.
Added kThemeBrushToolbarBackground and kThemeBrushSheetBackgroundTransparent.
Added theme metrics for menu layout:
kThemeMetricMenuMarkColumnWidth
kThemeMetricMenuExcludedMarkColumnWidth
kThemeMetricMenuMarkIndent
kThemeMetricMenuTextLeadingEdgeMargin
kThemeMetricMenuTextTrailingEdgeMargin
kThemeMetricMenuIndentWidth
kThemeMetricMenuIconTrailingEdgeMargin
Added kThemeVariantBaseTintTag.
kThemeBrushBlack works again. (2655865)
Control Manager
A new control data tag, kClockAnimatingTag, may be used to control whether the clock control animates itself.
The scrolling textbox control now scrolls itself automatically using a timer. A new control data tag, kControlScrollTextBoxAnimatingTag, may be used to control whether the control actually animates itself.
Setting the text of an EditText control using a CFString would only place half of the CFString's text into the control if the CFString required a double-byte encoding. (2646722)
Added kControlTabImageContentTag.
Added kControlEditTextPasswordCFStringTag.
The NO_DATA_BROWSER_TWEAKS and related conditionals in ControlDefinitions.h
were removed. Only one of each conditionalized prototype, structure, or
constant could be kept. Any compile-time changes you need to make should be
fairly straightforward. When two different API prototypes or structure
definitions were available, we kept the one which allows you to compile code
to run on Mac OS X (the first release) and/or the earliest version of
CarbonLib in which that prototype or structure was introduced. The runtime
itself still supports both variants of any prototype or structure; old
binaries will still run as expected. Also check out the note in the header
on DataBrowserItemNotificationProcPtr.
DataBrowser drawing performance was increased significantly.
A large number of DataBrowser crashing bugs (mostly due to item addition and removal)
were fixed.
Help Manager
New APIs:
HMHideTag
Added HMHideTag API to hide the currently visible help tag.
Added "quick mode" so that when moving from one tag-presenting object to another, if a tag is already showing, the tag for the new object will be shown immediately instead of after a delay.
Icon Services
New APIs:
GetIconRefFromFileInfo
RegisterIconRefFromFSRef
PlotIconRefInContext
ReadIconFromFSRef
Icon Services now provides 128x128 icons for the stop, caution, and alert icons. Previously, only 32x32 icons were available, which looked chunky when scaled up.
Process Manager
New APIs:
ShowHideProcess
IsProcessVisible
In Mac OS X 10.0.x, GetProcessInfo is a quite expensive call when the processName or processAppSpec fields of the ProcessInfoRec are not NULL, because the API implementation needs to create a CFBundle to determine the values of these fields.
In 10.1, GetProcessInfo has been modified to use a more efficient implementation that doesn't require creating a CFBundle. GetProcessInfo is still, however, more expensive than it is on Mac OS 9. Some applications like to keep track of which processes are running by continuously iterating over the process list, calling GetProcessInfo on each process. This is very slow on 10.0.x and still not a good idea on 10.1. Instead, if you need to detect when processes are created and destroyed, you should install Carbon events handlers for the kEventClassApplication/kEventAppLaunched and kEventAppTerminated events. This will allow you to observe process lifetimes without polling.
Drag Manager
New APIs:
SetDragAllowableActions
GetDragAllowableActions
GetDragDropAction
SetDragDropAction
Drag actions are a high level description of what should be done or what was done with a drag in a given context. For instance, setting an allowable action of kDragActionDelete suggests the receiver of that drag should only allow the drag to be dropped in an area which indicates the contents will be deleted. The trash typically serves this purpose. Allowable drag actions can be set independently for both the local, sending application and remote, receiving applications. Setting the corresponding drop action indicates to the sender what happened to the drag when it was dropped. Note, setting kDragActionNothing, as a remote allowable action guarantees remote apps will not receive the drag at all. Allowable actions default to kDragActionAll whereas drop actions default to kDragActionGeneric when the API has not been adopted.
Copyright © 2001-2005 Apple Computer, Inc.