Mac Developer Library Developer
Search
Document Generated: 2014-08-06 20:56:55 -0700
OS X Release Notes Copyright © 2014 Apple Inc. All Rights Reserved.


OS X 10.10 Yosemite Release Notes
Cocoa Application Framework



The Cocoa Application Framework (also referred to as the Application Kit, or AppKit) is one of the core Cocoa frameworks. It provides functionality and associated APIs for applications, including objects for graphical user interfaces (GUIs), event-handling mechanisms, application services, and drawing and image composition facilities.

Some of the major topics covered in this document:


These notes apply to seed 5 of OS X Yosemite, released early August. Sections updated since the WWDC seed are marked. These notes do not yet cover all of the changes in the Application Kit in OS X 10.10.

Please also refer to the Foundation release notes for notes on other important changes in 10.10.

Release notes for AppKit from 10.9 and earlier releases can be found here.

Marking updated APIs in headers

New APIs in headers are marked with decorations that include references to "10_10”:
 NS_AVAILABLE_MAC(10_10), NS_AVAILABLE(10_10, <iOS Release>), NS_CLASS_AVAILABLE(10_10, <iOS Release>), NS_ENUM_AVAILABLE(10_10)
or sometimes the construct:
 #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_10
...
#endif
Deprecated APIs are marked with:
 NS_DEPRECATED_MAC(<Release when introduced>, 10_10) or  NS_DEPRECATED_MAC(<Release when introduced>, 10_10, "Suggested alternative”)
In 10.10, the deprecated attribute has been added to many previously soft-deprecated methods. Please be aware of deprecation warnings and modify your code to use supported alternatives. Searching AppKit headers for NS_DEPRECATED_MAC and filtering for 10_10 will yield a list of affected symbols.

Runtime Version Check

There are several ways to check for new features provided by the Cocoa frameworks at runtime. One is to look for a given new class or method dynamically, and not use it if not there. Another is to use the global variable NSAppKitVersionNumber (or, in Foundation, NSFoundationVersionNumber):
double NSAppKitVersionNumber;
#define NSAppKitVersionNumber10_0 577
#define NSAppKitVersionNumber10_1 620
#define NSAppKitVersionNumber10_2 663
#define NSAppKitVersionNumber10_3 743
#define NSAppKitVersionNumber10_4 824
#define NSAppKitVersionNumber10_5 949
#define NSAppKitVersionNumber10_6 1038
#define NSAppKitVersionNumber10_7 1138
#define NSAppKitVersionNumber10_8 1187
#define NSAppKitVersionNumber10_9 1265
One typical use of this is to floor() the value, and check against the values provided in NSApplication.h. For instance:
if (floor(NSAppKitVersionNumber) <= NSAppKitVersionNumber10_8) {
/* On a 10.8.x or earlier system */
} else if (floor(NSAppKitVersionNumber) <= NSAppKitVersionNumber10_9) {
/* On a 10.9 - 10.9.x system */
} else {
/* 10.10 or later system */
}
Special cases or situations for version checking are also discussed in the release notes as appropriate. For instance some individual headers may also declare the versions numbers for NSAppKitVersionNumber where some bug fix or functionality is available in a given update, for example:
#define NSAppKitVersionWithSuchAndSuchBadBugFix 1138.42

Backward Compatibility

One backward compatibility mechanism that is occasionally used in the frameworks is to check for the version of the system an application was built against, and if an older system, modify the behavior to be more compatible. This is done in cases where bad incompatibility problems are predicted or discovered; and most of these are listed below in these notes.

Typically we detect where an application was built by looking at the version of the System, Cocoa, AppKit, or Foundation frameworks the application was linked against. Thus, as a result of relinking your application against the latest SDK, you might notice different behaviors, some of which might cause incompatibilities. In these cases because the application is being rebuilt, we expect you to address these issues at the same time as well. For this reason, if you are doing a small incremental update of your application to address a few bugs, it's usually best to continue building on the same build environment and libraries used originally.

In some cases, we provide defaults (preferences) settings which can be used to get the old or new behavior, independent of what system an application was built against. Often these preferences are provided for debugging purposes only; in some cases the preferences can be used to globally modify the behavior of an application by registering the values (do it somewhere very early, with -[NSUserDefaults registerDefaults:]).




Storyboards

AppKit has new API to support the Storyboarding feature being introduced in OS X 10.10.

The NSStoryboard class (declared in NSStoryboard.h) provides the means to access your app’s storyboards and instantiate controllers by name. (You can also specify an NSMainStoryboardFile in your app’s Info.plist, which causes the named storyboard to be automatically loaded, and its initial controller instantiated and presented, at app launch time.) Both NSViewController and NSWindowController have a new, readonly “storyboard” property, that returns the NSStoryboard (if any) that the controller belongs to.

The NSStoryboardSegue class (declared in NSStoryboardSegue.h) encapsulates a named connection from a sourceController to a destinationController, while the NSSeguePerforming protocol, to which both NSViewController and NSWindowController now conform, provides the means to hook into the mechanics of these transitions. When your app performs a segue, the segue’s destinationController is presented. The presented destinationController remains shown until it is dismissed (usually in response to a user action).

To dismiss a ViewController or WindowController, you send it (or have it send itself) the new -dismissController: message. -dismissController: is declared as an IBAction, so you can wire it up as the destination of a target-action connection if you wish.

NSWindowController (Section updated since WWDC seed)

NSWindowController has a new “contentViewController” property, that mirrors the “contentViewController” property of the associated window. An NSWindowController that’s part of a storyboard is required to have a contentViewController — a requirement that Xcode’s storyboard editor assists you in fulfilling when you drag an NSWindowController into the storyboard canvas.

Prior to OS X 10.10, an NSWindowController only received -windowWillLoad, -loadWindow, and -windowDidLoad messages when the NSWindowController itself performed the nib loading — that is, when the NSWindowController was instantiated in code and given the name of a nib file to load on demand when its -window was first requested.  This meant -windowWillLoad, -loadWindow, and -windowDidLoad would not be sent to an NSWindowController that was loaded as one of a nib file’s constituent objects.

AppKit now sends -windowWillLoad, -loadWindow, and -windowDidLoad to an NSWindowController that’s unarchived from a nib, if the NSWindowController is wired up to an associated window.  An override of -windowDidLoad can count on all connections described in the nib having been established.  The documented behavior of -isWindowLoaded has changed slightly to match: For an NSWindowController unarchived from a nib, -isWindowLoaded reports NO at first, then YES at the time -windowDidLoad is invoked and thereafter.  To prevent binary incompatibility problems due to these changes in long-standing NSWindowController behavior, the changes described in this paragraph only take effect for apps linked on or after OS X 10.10, when running on OS X 10.10 or later.



NSViewController (Section updated since WWDC seed)

NSViewController now has a suite of methods for presentation hooks: -viewWillAppear, -viewDidAppear, -viewWillDisappear, and -viewDidDisappear. See the header comments in NSViewController.h for more details.

NSViewController now has a -viewDidLoad method that can be overridden for instances that want to know when the view has been loaded, and can do additional setup work as needed. To maintain compatibility for apps that may invoke their own, identically named “-viewDidLoad” methods, AppKit invokes -viewDidLoad only for apps linked on or after OS X 10.10.

NSWindow now has a contentViewController property. This property makes it easy to assign the contentView of a window using a view controller. There is also a convenience method for creating a titled window: [NSWindow windowWithContentViewController:]. See the NSWindow.h header comments for more details.

NSViewController now has the following new features, all commented in great detail in NSViewController.h:
• Parent/child container view controller methods
• View controller presentation options
• View controller transition options

NSViewController now conforms to the NSUserInterfaceItemIdentification protocol. This allows it to participate in the Transparent Application Lifecycle management. Any NSViewController can now use the suite of methods declared on NSResponder for state restoration: encodeRestorableStateWithCoder:, restoreStateWithCoder:, invalidateRestorableState, and restorableStateKeyPaths.

NSViewController now has a suite of methods to control layout for its associated view: updateViewConstraints, viewWillLayout and viewDidLayout. See the NSViewController.h header for more information.

The following changes take effect for applications linked on 10.10 and higher:

• NSViewController automatically adds itself into the responder chain. When a view is assigned, the view's current nextResponder is saved off. The view's nextResponder is then set to be the viewController, and viewController's nextResponder is set to be the previously saved nextResponder. When the view has a call to setNextResponder: made, the method will be forwarded to the view’s view controller. If you currently are already doing your own responder chain management, take particular care as the view.nextResponder may already be the NSViewController. This can cause an issue for apps that manually set the viewController.nextResponder = view.nextResponder, without checking to see if the view.nextResponder != viewController; otherwise, an infinite loop may be created, causing an application to hang. To debug these hangs, run the application with “-NSResponderDebugResponderLoops YES”. This option will check the responder chain for loops anytime setNextResponder is called (note that this option will slow down program execution).

Put another way, the responder chain with view controllers looks like this:

ChildView -> ParentView -> ParentView’s ViewController -> ParentView’s ParentView -> Window -> Window’s WindowController.

• loadView: would previously not have well defined behavior if there was a "nil" nibName. On 10.10 and later, if nibName is nil NSViewController will automatically try to load a nib with the same name as the classname. This allows a convenience of doing [[MyViewController alloc] init] (which has a nil nibName) and having it automatically load a nib with the name "MyViewController".


Auto Layout (Section updated since WWDC seed)

For apps linked against 10.10 and later, recalculating a window’s key view loop will layout any dirty subtrees in the window. Previously, the key loop would be calculated using the dirty layout frames, potentially leading to an incorrect key view loop. This affected layouts created with constraints as well as with NSStackView.

Constraints that span over parent views (e.g. a button within a container view constrained to a sibling of the container view) that are created in IB are no longer removed at runtime. Apps running on systems earlier than 10.10 will still have this issue — a workaround for apps deployed on earlier systems is to create the affected constraints programmatically.

Constraints from a Leading or Trailing edge of one layout item to the Center X of another no longer behave unexpectedly (such as causing unsatisfiable constraints) in RTL environments. Apps running on systems earlier than 10.10 will still have this issue — a workaround for apps deployed on earlier systems is to use explicit Left or Right attributes in RTL environments.

NSPopover

The responder chain no longer ends at the NSPopover window. That window now has a nextResponder of its parentWindow, i.e. the window of the positioningView.

The contents of popovers shown from borderless windows and status bar items are now focusable. In these cases, the popover window will become the key window. Transient popovers shown from these contexts will also properly close.

If the popover’s contentView returns NO from -acceptsFirstResponder, the popover will no longer make it the first responder. This can be utilized to show help text popovers without making the source lose first responder or key status.

Calling the -close method on a popover will now cause child popovers to be forced closed as well (in accordance with past documentation). Calling -performClose: will still fail if the popover has a nested popover.

-popoverWillClose: is now called on the delegate before the popover queries its animates property to determine if it should animate. This allows the pattern of always having animates = NO, and turning it on in willClose: and willShow: to animate showing and closing the popover.

In OS X 10.10, NSPopover now positions its content flush to the edges of the popover. Previously it was inset (2, 2, 2, 2).

Detachable Popover Improvements

NSPopoverDelegate’s new -popoverShouldDetach:. This is called when the user begins dragging the popover to determine if it should be allowed to detach. If the delegate does not implement this method, the default behavior will be NO.

An app wanting to use a custom detached window vended from -detachableWindowFromPopover: will need to implement this method to return YES if linked against 10.10 or higher. Apps linked before this will continue to work as expected without the method implementation.

Automatically created detachable windows. If the delegate returns YES from -popoverShouldDetach:, but does not implement or returns nil from -detachableWindowForPopover:, a detached window will be automatically created to detach to. This will reuse the contentViewController’s view as its contentView, and maintain a popover-like appearance with a seamless transition during the detach. During the detach with an automatic window, -PopoverShould/Will/DidClose notifications will not be sent. Instead, when the automatic window is going to be closed, -popoverShouldClose: will give the delegate a chance to prevent the closing of the window, and PopoverWill/DidClose notifications will be sent if it does close. If -showRelativeToRect:ofView:preferredEdge: is called on the popover while an automatically created detached window is shown, the popover will not appear, but the detached window will be made key and ordered front. Once the detached window is closed, calling -showRelativeToRect:ofView:preferredEdge: will return to showing the popover.

-detachableWindowForPopover: will only be called once the popover is going to be fully detached, not when the user begins the drag. This means that the popover appearance during the drag will be based on the popover itself, rather than the final detached window. -popoverShouldDetach: should be used to indicate that the popover should be allowed to be dragged and detached.

-popoverShouldClose: is no longer called on the delegate or popover when the window is detaching to a separate window.

Popover Appearance Changes

In order to allow for appearance customization through NSAppearance, NSPopover’s appearance property is transitioning from type NSPopoverAppearance to NSAppearance. If you plan to deploy to 10.10 or above, the former is considered deprecated, and you should no longer set or read the appearance property with NSPopoverAppearanceMinimal or NSPopoverAppearanceHUD. If you are deploying to 10.10 as a minimum, the appearance property is declared as taking an NSAppearance. If no appearance is specified, the effective appearance defaults to NSAppearanceNameVibrantLight. This corresponds to the appearance created by NSPopoverAppearanceMinimal. NSPopoverAppearanceHUD has no parallel style in NSAppearance.

NSSplitView

In 10.10, SplitViews using auto layout will now correctly hide the first and last dividers when the delegate returns such from -splitView:shouldHideDividerAtIndex:. In 10.9 and earlier, these dividers would fail to hide.

In 10.10, SplitViews using auto layout will respect when its userInterfaceLayoutDirection is NSUserInterfaceLayoutDirectionRightToLeft. Its subviews and dividers will be ordered from Right to Left; i.e. subview 0 is the right-most view and divider 0 is the right-most divider. SplitViews not using auto layout will continue to not order views right-to-left.


NSSplitViewController

NSSplitViewController is a new container view controller class in 10.10. It manages an NSSplitView to layout its child view controller’s views. The use of NSSplitViewItem objects expose the SplitViewController specific properties of a child view controller in the NSSplitViewController.

One benefit of NSSplitViewController is the lazy loading of childViewControllers’ views. In general the performance benefits of this may not be as significant as NSTabViewController’s lazy loading, but does come into play in a couple situations: (1) when setting up the SplitViewController and adding SplitViewItems, the children’s views will not be loaded until the SplitViewController’s is loaded, and (2) when adding a collapsed SplitViewItem to a SplitViewController; the item’s view will only be loaded once the view is uncollapsed (programmatically or by the user). If it is never uncollapsed, it is never loaded by SplitViewController.

The use of auto layout with NSSplitViewController allows an app to customize whether the collapse of a split view item causes, for instance, the window to stay the same size or shrink without exposing any additional API or requiring the developer to do additional work. If the constraints used to create the layout of a child view controller’s view hierarchy are not enough to describe the behavior during collapse/uncollapse, NSSplitViewItem’s holdingPriority property can be set to specify this behavior.

The collapsed property of NSSplitViewItems are KVC/KVO compliant. This allows developers to do things like bind a PushOnOff button to the collapsed state of the item. As the button is toggled, so is the split view item. And vice versa: if the SplitViewItem is collapsible and the user collapses the the item (with a drag or double click), the button’s state is updated:
[toggleButton bind:NSValueBinding
toObject:sidebarSplitViewItem
withKeyPath:@"collapsed"
options:@{NSValueTransformerNameBindingOption : NSNegateBooleanTransformerName}];
Since the collapsed property is also animatable with the SplitViewItem's animator proxy, the binding could be instead written against the animator property. This gives all the same benefits as the previous example, but now when the button is toggled, the split view item’s view controller will be animated in or out:
[toggleButton bind:NSValueBinding
toObject:[sidebarSplitViewItem animator]
withKeyPath:@"collapsed"
options:@{NSValueTransformerNameBindingOption : NSNegateBooleanTransformerName}];

NSStackView

For layer-backed StackViews, views are no longer clipped to any private container bounds. This change only affects apps linked against 10.10. NSStackView now overrides +requiresConstraintBasedLayout to return YES, allowing StackViews to properly function in windows that do not have any other constraints.


Dark Menus (Section added since WWDC seed)

Dark menu support is enabled by users via the General preferences pane. It’s a system-wide setting, not per application, and it is intended to apply to a small number of system elements — menu bar, menus, dock, and cmd-tab application switcher. It does not apply to application windows.

NSStatusItem appearance and Dark Menu support (Section added since WWDC seed)

There are a number of stylistic changes added and supported by NSStatusItem, including appearance changes for Dark Menus. Template images should always be used to ensure correct styling based on the various states the status item can be in (light menu, dark menu, inactive light, inactive dark, selected, disabled, etc). NSStatusBarButton’s appearsDisabled property can be used to give the image a disabled or “off” look without having the item be functionally disabled. The -button property has been added to give access to the NSStatusBarButton that is internally created and displayed in the status item. Existing properties that had previously been forwarded to this button are softly deprecated and should be accessed directly through the button. The button property also allows screen position measurement (such as for use with popovers) without setting a custom view.

Creating a standard status item with proper styling can be done in a just few lines:
NSStatusItem *myStatusItem = [[NSStatusBar systemStatusBar] statusItemWithLength:NSSquareStatusItemLength];
gearImage.template = YES;
myStatusItem.button.image = gearImage;
myStatusItem.button.accessibilityTitle = @"My Status Item";
myStatusItem.button.appearsDisabled = networkIsDisabled;
myStatusItem.menu = myStatusItemMenu;

The view property of NSStatusItem is softly deprecated as well as API meant to support its use. The custom view property alone is not enough for AppKit to provide standard styling for the different status item states and enables items to look and feel out of place in the menu bar. Please file enhancement requests if NSStatusItem & NSStatusBarButton’s API does not allow for a behavior that should be standardized and allowed.


NSTabViewController

NSTabViewController is a new container view controller class in 10.10. It provides:
• Lazy loading of non-visible view controllers
• Easy design time construction with Storyboarding
• A target for bindings
• Easy/abstract hookup for displaying large content switches
• A way of providing standard tab-style UI with external controls

NSTabViewController represent an abstract target for providing content switching. tabViewItems and selectedTabViewItemIndex are KVC/KVO compliant. This allows one to bind an NSSegmentedControl (or other bindable objects) directly to them:
[segmentedControl bind:NSContentBinding toObject:tabViewController withKeyPath:@"tabViewItems" options:nil];
[segmentedControl bind:NSSelectedIndexBinding toObject:tabViewController withKeyPath:@"selectedTabViewItemIndex" options:nil];

Right to Left UI

• NSComboBox will now correctly flip when its userInterfaceLayoutDirection is NSUserInterfaceLayoutDirectionRightToLeft.
• NSDatePicker will now correctly flip when its userInterfaceLayoutDirection is NSUserInterfaceLayoutDirectionRightToLeft.
• NSPopupButton will now correctly flip when its userInterfaceLayoutDirection is NSUserInterfaceLayoutDirectionRightToLeft.
• NSSearchField will now correctly flip when its userInterfaceLayoutDirection is NSUserInterfaceLayoutDirectionRightToLeft.
• NSSplitView will layout its subviews from right to left when its userInterfaceLayoutDirection is NSUserInterfaceLayoutDirectionRightToLeft and is using auto layout.


NSDatePicker changes (Section added since WWDC seed)

On applications that build against the 10.10 SDK, when running on 10.10 or later, NSDatePicker and NSDatePickerCell’s setLocale: and setTimeZone: methods will copy the given locale/time zone instead of simply retaining it.

NSDatePicker now supports the Chinese lunar calendar when the calendar property is set to an NSCalendar created with the NSCalendarIdentifierChinese identifier.

NSDatePicker’s NSClockAndCalendarDatePickerStyle now supports RTL according to its locale.

NSTokenField property behavior changes

On applications that build against the 10.10 SDK, when running on 10.10 or later, NSTokenField and NSTokenFieldCell’s setTokenizingCharacterSet: methods will copy the given character set instead of simply retaining it.

NSSpeechRecognizer property behavior changes

On applications that build against the 10.10 SDK, when running on 10.10 or later, NSSpeechRecognizer’s setCommands: method will copy the given array instead of simply retaining it.

NSWorkspace methods for passing configuration and options when opening a URL (Section added since WWDC seed)

NSWorkspace now has a pair of methods for opening URLs with specific configuration options. See openURL:options:configuration:error: and openURLs:withApplicationAtURL:configuration:error: in AppKit/NSWorkspace.h.

NSScreen behavior changes (Section added since WWDC seed)

NSScreen instances are now immutable — their properties will not change. To get updated information as displays are reconfigured, listen for the NSApplicationDidChangeScreenParametersNotification and, when it arrives, get new NSScreen instances, which will have the updated information.

NSScreen isEqual will now return YES for the same display even if the NSScreen instances are not identical.

On applications that build against the 10.10 SDK, when running on 10.10 or later, [NSScreen screens] will return an empty array if no displays are attached instead of nil.


Handoff support in AppKit (Section added since WWDC seed)

NSUserActivity is a new class in Foundation which encapsulates the state of a user activity in an application on a particular device, in a way that allows the same activity to be continued on another device in a corresponding application from the same developer. Examples of user user activities include editing a document, viewing a web page, or watching a video.

There are new API on the NSApplication delegate to support continuing an activity from an NSUserActivity. There is also a userActivity property on NSResponder and NSDocument that lets AppKit manage calling -becomeCurrent and -invalidate, along with -updateUserActivityState: and -restoreUserActivityState: methods that can be overridden to save/restore your own state in the NSUserActivity.

Additionally, document based apps can put NSUbiquitousDocumentUserActivityType in each CFBundleDocumentTypes entry in the Info.plist and AppKit will automatically create NSUserActivities for documents in iCloud (that are accessible from the userActivity property). Activity types specified in this way do not need to appear in the Info.plist NSUserActivityTypes array, which is used to declare the activities supported by the application.

NSUserActivities that have the NSUserActivityDocumentURLKey set in their userInfo can be automatically continued using NSDocumentController’s openDocumentWithContentsOfURL:display:completionHandler:. NSDocument will put its fileURL in the userInfo with NSUserActivityDocumentURLKey in its implementation of updateUserActivityState:.

For more information, see Foundation/NSUserActivity.h and AppKit/NSUserActivity.h.


NSAppearance

An accessor has been added to get the name of an appearance instance.

NSAppearanceNameLightContent has been deprecated. Uses of this appearance will be redirected to the default Aqua appearance.

Vibrant appearances, NSAppearanceNameVibrantDark and NSAppearanceNameVibrantLight, have been added, for use with NSVisualEffectView.

NSTextView

The default insertion point color is now [NSColor controlTextColor]. In the Aqua appearance this color is black and therefore should result in no change in behavior, but in other appearances (e.g. Vibrant Dark) it may be different.



Gesture Recognizers (Section updated since WWDC seed)

Gesture recognizers are now available in AppKit. The API is nearly identical to the UIKit version. See NSGestureRecognizer.h. There is a NSGestureRecognizer (NSSubclassUse) category that is explicitly meant for subclassers to override and call. Non-subclassers should never directly access these category methods and properties.

The following are considered physical gestures:
• A mouse button press, drag, or release. Note: each button is an independent gesture stream.
• A gesture which always goes through NSEventPhaseBegan and NSEventPhaseEnded / NSEventPhaseCancelled (aka Rotate and Magnify)
Note: while ScrollWheel events have a phase value, the phase is not required, and thus ScrollWheel events are not capture-able by NSGestureRecognizers.

Gesture recognition begins at the moment any of the above physical gestures begin. At this point, the set of possible gesture recognizers is gathered much like UIKit. That is, the set of all gesture recognizers attached to the hit tested view and its ancestor views. (Or start with the first view found following the responder chain starting with the first responder in the case of key down events). From there, all mouse, keyboard, and gesture events are routed to the set of gesture recognizers even if such events are the start of a different physical gesture. This continues until the complete set of gesture recognizers end (or fail) or all physical gestures that have begun since the first one, have completed.

Gesture Recognizers do not see events that are pulled by event tracking loops. For this reason, it is advised that your gesture recognizer subclass delay events of the type you are processing.

The event passes from NSApplication’s -sendEvent: to any event monitors, then to NSWindow’s -sendEvent: method then to Gesture Recognizers and finally out to the responder chain. Warning: consuming events that mark the end of a gesture before Gesture Recognizers handle them can cause the gesture recognizers to get confused.

The set of AppKit provided gesture recognizers (and their UIKit analogs) are:
• NSPanGestureRecognizer [UIPanGestureRecognizer] - tracks a mouse drag
• NSClickGestureRecognizer [UITapGestureRecognizer] - tracks a specified number of clicks
• NSPressGestureRecognizer [UILongPressGestureRecognizer] - tracks a click and hold
• NSMagnificationGestureRecognizer [UIMagnificationGestureRecognizer] - tracks a magnification gesture event sequence
• NSRotationGestureRecognizer [UIRotationGestureRecognizer] - tracks a rotation gesture event sequence

Note: Any 32 bit subclass of NSPanGestureRecognizer will need to be rebuilt since the WWDC seed.

The delegate method -gestureRecognizer:shouldReceiveEvent: has been removed since the WWDC seed.

Block Based Event Tracking

There is a new block based event tracking method on NSWindow. It will continuously track events using the supplied tracking handler block until the tracking handler block explicitly terminates tracking.
- (void)trackEventsMatchingMask:(NSEventMask)mask
timeout:(NSTimeInterval)timeout
mode:(NSString *)mode
handler:(void(^)(NSEvent *event, BOOL *stop))trackingHandler;
If a matching event does not exist in the event queue, then the main thread blocks in the specified runloop mode until an event of the requested type is received or the timeout expires. If the timeout expires, the tracking handler is called with a nil event. A negative timeout is interpreted as 0. Use NSEventDurationForever to never timeout. Tracking continues until *stop is set to YES in the tracking handler. This method returns once tracking is terminated.

Calls to -nextEventMatchingMask:… are allowed inside the trackingHandler block. This is often useful to quickly drain the event queue for coalescing purposes.



NSScrollView (Section added since WWDC seed)

NSScrollView now has a contentInsets property similar to that of UIScrollView in iOS. Typically this is used with NSFullSizeContentViewWindowMask when the scroll view intersects the title / tool bar.

“Automatically” sets the scroll view's contentInsets property to account for any overlapping title / tool bar. In order to overlap with the title / tool bar the window style mask must include NSFullSizeContentViewWindowMask and the titlebar must not appear transparent. Normally this is NSEdgeInsetsZero. Defaults to YES.
@property BOOL automaticallyAdjustsContentInsets;
NSScrollView manages a number of subviews (contentView, scrollers, find bar, rulers, etc..). This property controls the distance that the subviews are inset from the enclosing scroll view during tiling. When contentInset equal to NSEdgeInsetsZero, traditional tiling is performed. That is, the rulers, headers, etc... are tiled with the contentView frame filling the remaining space. When contentInset is not equal to NSEdgeInsetsZero, the rulers, header, etc... are inset as specified. The contentView is is placed underneath these sibling views and is only inset by scroll view border and non-overlay scrollers. Note: if automaticallyAdjustsContentInsets == YES then any value set here will get overridden during tiling.
@property NSEdgeInsets contentInsets;
The distance the scrollers are inset from the edge of the scroll view:
@property NSEdgeInsets scrollerInsets;

NSClipView (Section added since WWDC seed)

Since NSClipView is the view that actually contains the scrollable content (documentView), NSClipView also gains the concept of contentInsets.

When YES, and used as the contentView of an NSScrollView, the scroll view will automatically set the appropriate clipView contentInsets considering the scrollView’s contentInsets, boarder and layout of other subviews such as rulers and headers. Defaults to YES.
@property BOOL automaticallyAdjustsContentInsets;
The distance that the content view is inset from the enclosing scroll view. Animate with [self animator]. If automaticallyAdjustsContentInsets == YES then any value set here will get overridden during tiling.
@property NSEdgeInsets contentInsets;
Generally, the default automatic behavior will do the right thing when using a full content view style window. To achieve a hidden pull down or pull to refresh style UI, set automaticallyAdjustsContentInsets to NO and manually set the contentInsets. Add the hidden content as subViews of the clipView and place arrange them above your documentView’s frame.



NSPrintSaveJob and File Coordination

In Mac OS X 10.9, when printing operations resulted in PDF or PostScript files, NSPrintOperation would use NSFileCoordinator to properly cooperate with other applications that might be presenting or accessing the same file. However, this new behavior caused deadlocks in some applications doing their file coordination, since coordinated writing on the same file from two separate subsystems is not reentrant

The scenario where these would occur always involved an app correctly doing a coordinated write, then inside that write running an NSPrintOperation with NSPrintSaveJob set with an explicit value for NSPrintJobSavingURL (the URL provided by the coordinated write). In order to break this deadlock NSPrintOperation on Mac OS X 10.9.2 or later will not perform a coordinated write if and only if both NSPrintSaveJob and NSPrintJobSavingURL are set.

If NSPrintSaveJob is set but NSPrintJobSavingURL is not, then NSPrintOperation will still perform a coordinated write. The same goes for when a print operation starts off with NSPrintSpoolJob, the print panel is displayed, and the user chooses to Save to PDF instead of sending the job to the printer.

Non-main thread invocations of -[NSDocumentController typeForContentsOfURL:error:]

Prior to Mac OS X 10.10, it was possible for -[NSDocumentController typeForContentsOfURL:error:] to be invoked on a non-main thread. This is no longer the case. However, if your application targets Mac OS X 10.9 or earlier and overrides this method, you should make sure the method is safe to be invoked on a non-main thread.



Gradual deprecation of NSCell

Mac OS X 10.10 takes another step towards the eventual deprecation of cells. Direct access to the cell of a control is discouraged, and methods which allow it will be formally deprecated in a subsequent release. A variety of cell-level APIs have been promoted to various Control subclasses in order to provide cell-free access to important functionality. NSLevelIndicator, NSTextField, NSSearchField, NSSlider, and NSPathControl all have new properties for this purpose. Cell-based NSTableViews are now deprecated, and view-based NSTableViews should be used instead. Matrix-based NSBrowsers are also deprecated in favor of the item-based interface.


NSPathControl

In order to discourage direct access to cells, Mac OS X 10.10 adds a new item-based API to NSPathControl. This eliminates the need to use NSPathComponentCell to manage the components of the path. Additionally, a variety of properties have been added to NSPathControl which provide access to important functionality previously only available through NSPathControlCell.


NSForm

Use of NSForm is now deprecated. Use NSTextField directly, and consider using NSStackView if layout assistance is desired.


NSMatrix

Use of NSMatrix is informally deprecated. We expect to add the formal deprecation macros in a subsequent release, but its use is discouraged in the mean time. The primary use of NSMatrix is for radio button groups, so recall that for applications linked on 10.8 or later, radio buttons that share the same parent view and action will operate as a group.


Weak targets for NSControl & NSCell

The target properties of control and cell subclasses have been modified to provide proper automatic-zeroing weak reference behavior for applications linked on Mac OS X 10.10 and higher. The implementation attempts to accommodate targets which cannot be safely referenced weakly, but the result is that messages are now sent to targets at the time they are set. If a target is being set to an invalid object reference or an object in the process of deallocation, this can cause crashes in cases that were previously innocuous. One consequence of this change is that NSControl now has a concrete implementation of the target & action properties. This is something to be aware of if you plan to rely on it in 10.10, but also deploy your application to previous releases.


New Auto Layout Constraint Management API

Under Mac OS X 10.10, it is now possible to directly activate and deactivate NSLayoutConstraint objects, without having to worry about adding them to an appropriate ancestor view. This is accomplished by manipulating NSLayoutConstraint's new boolean property 'active'. Class methods are available for operating on multiple constraints simultaneously, which can be much faster. The legacy API on NSView for adding & removing constraints is now deprecated.


Image positioning in Buttons

NSButtonCell now uses -imageRectForBounds: to position images displayed in buttons, for applications linked against Mac OS X 10.10 or later.



NSTableView/NSOutlineView General Updates

NSTableRowView now has properties to determine if the previous and/or next row is selected. This is useful for drawing selection differently based on this state.
@property(getter=isPreviousRowSelected) BOOL previousRowSelected;
@property(getter=isNextRowSelected) BOOL nextRowSelected;
NSTableView now supports the ability to statically design the contents of a table at design time in Xcode. At runtime, it is unarchived and identical to what you designed.

One can also dynamically create a static table view with a new property: usesStaticContents.

Normally, a table view will only keep around a subset of the total number of rows potentially available (in general, this is limited to the visible region, plus some overdrawn allowance for responsive scrolling). A static table view keeps all views added to the table around when usesStaticContents=YES. Views can dynamically be removed by calling removeRowsAtIndexes:withAnimation:. The datasource does not need to implement numberOfRowsInTableView: when usesStaticContents=YES. Static views are encoded and decoded with the table view. Views can also dynamically be inserted into the table view by using insertRowIndexes:withAnimation:, however, this requires an implementation of tableView:viewForTableColumn:row: to provide the newly inserted view, which is then kept around statically.

NSOutlineView also supports the ability be statically designed, and works similarly to NSTableView. However, to dynamically change the outline view you must use the methods: insertItemsAtIndexes:inParent:withAnimation:, removeItemsAtIndexes:inParent:withAnimation:, and moveItemAtIndex:inParent:toIndex:inParent:. Provide newly inserted items by implementing the datasource method outlineView:child:ofItem:, and indicate they are expandable by implementing outlineView:isItemExpandable:. It is not necessary to implement outlineView:numberOfChildrenOfItem when using a static outline view. Note that all items provided must be encodable (i.e.: implement the NSCoding protocol), and unique (in order to uniquely identify the row for a given item).

Since 10.5, NSTableViews/NSOutlineViews are configured as sidebars (source lists) by setting the selectionHighlightStyle to NSTableViewSelectionHighlightStyleSourceList. This has always had side effects. Specifically, it will control some layout metrics for NSOutlineView and NSTableView. Upon setting the style, it will also set the backgroundColor of the tableView to a special internal color. Prior to 10.10 this color was a light blue gradient. After 10.10, an NSVisualEffectView is internally used to create a blurred background. After setting the style, one could always change the color away from the internal default; doing this will cause the blur background to not be shown (which may be desired). On 10.10, setting the selectionHighlightStyle to NSTableViewSelectionHighlightStyleSourceList will now also set the appearance to NSAppearanceNameVibrantLight. On 10.10, for source lists using the rowSizeStyle of NSTableViewRowSizeStyleDefault, the intercellSpacing.height is now automatically controlled. In general, it may vary based on the user's set row size style in System Preferences, and it is important to test each size when creating a “source list” application.

Animations

Most animations on the system can be slowed down by setting the default NSAnimationSlowMotionOnShift to YES and holding down the shift key. NSTableView previously had use a default named NSTableViewSlowMotion; it is no longer used.


NSWindow (Section updated since WWDC seed)

NSWindow has some API to control the new look of windows in OS X.

The first new API is titlebarAppearsTransparent; when set to YES, the titlebar does not draw its background, allowing all content underneath it to “show through.” It is only applicable to use this option when turning on the new NSFullSizeContentViewWindowMask option for the window styleMask. NSFullSizeContentViewWindowMask can be combined with titled windows (using NSTitledWindowMask) to allow a contentView’s frame to be the full size of the window and take up space under the toolbar/titlebar. Doing this may still require certain UI pieces to not appear under the titlebar/toolbar; to find that area, utilize the contentLayoutRect and contentLayoutGuide. Please also refer to the notes about the contentInsets property and related new features in NSScrollView to see how to use NSFullSizeContentViewWindowMask in advanced situations.

Another new property is called titleVisibility and the enum options are:
typedef NS_ENUM(NSInteger, NSWindowTitleVisibility) {
/* The default mode has a normal window title and titlebar buttons. */
NSWindowTitleVisible = 0,
/* The always hidden mode hides the title and moves the toolbar up into the area previously occupied by the title. */
NSWindowTitleHidden = 1,
};
The option NSWindowTitleHiddenWhenActive has been removed since the WWDC seed.

In the WWDC seed, NSScrollView would incorrectly attempt to "mirror" its contents if it appeared under the titlebar, and titlebarAppearsTransparent =YES. This has been fixed, and will no longer happen.

The method canStoreColor is now deprecated; it has not been used in some time.

New since WWDC seed: NSWindow has never supported clients adding subviews to anything other than the contentView. Some applications would add subviews to the contentView.superview (also known as the border view of the window). NSWindow will now log when it detects this scenario: "NSWindow warning: adding an unknown subview:". Applications doing this will need to fix this problem, as it prevents new features on 10.10 from working properly. See titlebarAccessoryViewControllers for official API.

NSWindow now has the ability to add officially known subviews to the titlebar/toolbar area. The views are to be wrapped with a new NSViewController subclass called NSTitlebarAccessoryViewController and added to the window with the "titlebarAccessoryViewControllers" API. There are a set of methods to add and insert the titlebarAccessoryViewControllers, such as addTitlebarAccessoryViewController: and removeTitlebarAccessoryViewControllerAtIndex:. However, one can also utilize "removeFromParentViewController" to easily remove a given child view controller. NSTitlebarAccessoryViewController has a property to tell NSWindow where to place the view (layoutAttribute) and a property to determine how it behaves in full screen (fullScreenMinHeight). The NSToolbar fullScreenAccessoryView API is now deprecated, and clients should utilize this new API.

HUD style windows (utilizing the NSHUDWindowMask) now automatically utilize NSVisualEffectView to create a blurred background. Applications should set the NSAppearance with the name NSAppearanceNameVibrantDark on the window to get vibrant and dark controls.

NSView

shouldDrawColor is now deprecated. It has not meant anything meaningful in quite some time, and should not be used.

The "gState" class of functions in NSView (and some auxiliary classes) are now deprecated. In many cases, they did not do anything, and their use was not well defined.

NSSegmentedControl

NSSegmentedControl (and the underlying cell) properly respect the isBordered flag for applications linked on 10.10 and higher. The value is saved with the normal encoding routines. By default, the cell will have setBordered:YES done in init.


Yosemite's Translucent Backgrounds and Vibrancy / NSVisualEffectView (Section updated since WWDC seed)

Translucent backgrounds and associated "vibrancy" in Yosemite are supported by a new view class, NSVisualEffectView. “Vibrancy” describes a compositing mode that does special blending such as “Plus Darker”, “Plus Lighter”, “Color Dodge”, and “Color Burn.” It is automatically used by the system in many places, including pop-overs, “source list” and sidebar table views, and sheets. Some dynamically use vibrancy based on their contents; for example, NSTextField does when certain special colors are used, such as the new colors: [NSColor labelColor] and [NSColor secondaryLabelColor].

If you need to support vibrancy in one of your own views, the following conditions must be met:
• The view must be contained inside an NSVisualEffectView.
• The view must return YES from allowsVibrancy.
• The view’s effectiveAppearance must return YES from allowsVibrancy (this means it must be either the NSAppearanceNameVibrantLight or NSAppearanceNameVibrantDark appearance). (Typically you set the appearance on the window, or on the NSVisualEffectView, and the subviews will inherit the appearance.)

NSVisualEffectView’s internal implementation of blurring and vibrancy depends on the blendingMode. If the blendingMode is set to NSVisualEffectBlendingModeBehindWindow, then blurring is achieved by describing a rectangle to the window server that should be blurred. Areas that should be vibrant are also described in a similar way. Once a particular region is described to be vibrant, ANYTHING drawn in that region will be drawn vibrant, even things drawn drawn before the vibrant subview. Therefore, once a view returns YES from allowsVibrancy, both it and all of its subviews will always be vibrant—a subview can not turn off vibrancy by returning NO from allowsVibrancy. For example: consider a large square NSView that returns NO from allowsVibrancy which fills its contents with [NSColor blueColor]. Consider an NSTextField that is on top of this blue view, and the NSTextField returns YES from allowsVibrancy. The square bounding frame for the NSTextField will become vibrant, including the blue color beneath, which will look wrong (the blue rectangle under the text will be a darker blue). The solutions to this problem: The blue view should also be vibrant, and return YES from allowsVibrancy. Or, the NSTextField needs to opt-out of vibrancy. Opt-ing out of vibrancy can be done by one of the following: setting the appearance back to NSAppearanceNameAqua OR using controlTextColor OR overriding allowsVibrancy and returning NO. It is possible to opt-out rectangular 100% opaque views by adding another NSVisualEffectView, and subviews to it that return NO from allowsVibrancy. These overlapping siblings will not be vibrant, but ONLY works for the blending mode NSVisualEffectBlendingModeBehindWindow. Not that this will only respect the rectangular shape.

If the blendingMode is set to NSVisualEffectBlendingModeWithinWindow, then the use of Core Animation layers is required. It is best to call view.wantsLayer = YES on the parent view that contains the NSVisualEffectView, as blurring will occur with it and the children of the NSVisualEffectView. Blurring for NSVisualEffectView is achieved by using special Core Animation filters. Vibrancy for a particular subview that returns YES from allowsVibrancy is achieved by setting the layer.compositingFilter. Applications that have vibrant views should not change the layer.compositingFilter for a view. A layer’s compositingFilter applies to how the layer and all of its children are composited to the parent layer, and it is not possible to have a child view to NOT be vibrant. However, you can add sibling views over the vibrant view; the overlapping sibling views will correctly not be vibrant. Note this ONLY works for the blending mode NSVisualEffectBlendingModeWithinWindow.

It is not recommended to subclass NSVisualEffectView and override -drawRect: or -updateLayer.



NSImage changes to named image lifetime

Beginning in Mac OS X 10.10 named images are retained. Previously, named images had been weakly referenced (and occasionally cached.) This allows applications to register a named image using the -[NSImage setName:] API, and retrieve it later using the +[NSImage imageNamed:] API. To achieve the same pattern on prior releases, it was necessary to hold an extra reference to the image. Applications wishing to ensure named images are deallocated must call -[NSImage setName:] with nil, before releasing their reference to the image. Note that changing the name of system artwork, or bundle artwork loaded through +[NSImage imageNamed:] is not supported.

NSImage support for sliced images

The resizingMode property of an image defines how that image is drawn into a rectangle larger or smaller than that image's natural size. When drawn into a larger rectangle NSImageResizingModeTile will replicate the image like a pattern. When drawn into a smaller rectangle the image will be clipped. NSImageResizingModeStretch will resize the image to fit precisely into the specified rectangle. Both modes have no effect when the image is drawn into a rectangle of its native size. NSImageResizingModeStretch is the default, and matches the behavior of previous releases.

The capInsets property allows the image to have specific regions that are stretched or tiled independently, based on resizingMode. In both modes the corners defined by the capInsets property are drawn without scaling or tiling. When the resizingMode is NSImageResizingModeTile, the horizontal edges will be replicated vertically, the vertical edges will be replicated horizontally, and the center of the image will be replicated on both axes. When the resizingMode is NSImageResizingModeStretch, the horizontal edges will be stretched vertically, the vertical edges will be stretched horizontally, and the center of the image will be stretched on both axes.

Note that drawing an image into a rectangle smaller than its natural size will cause the edges and corners to be stretched to fit into that rectangle.

NSBitmapImageRep support for image data byte-swapping

In Mac OS X 10.10 NSBitmapImageRep now supports explicitly specifying the endianness of image data. This can be accomplished by using the new NS16BitLittleEndianBitmapFormat, NS32BitLittleEndianBitmapFormat, NS16BitBigEndianBitmapFormat, and NS32BitBigEndianBitmapFormat enumerations. These behave equivalently to the CGBitmapByteOrder enumerations. Setting no byte order option produces behavior identical to MacOSX 10.9. Setting more than one byte order option is illegal.

Importantly 8-bit BGRA image data can be expressed by passing bitsPerSample=8, samplesPerPixel=4, bitmapFormat=NSAlphaFirstBitmapFormat|NS32BitLittleEndianBitmapFormat, and bitsPerPixel=32 to -[NSBitmapImageRep initWithBitmapDataPlanes:pixelsWide:pixelsHigh:bitsPerSample:samplesPerPixel:hasAlpha:isPlanar:colorSpace:bitmapFormat:bytesPerRow:bitsPerPixel:].

NSOpenGLContext conformance to NSLocking

NSOpenGLContext now conforms to the NSLocking protocol. -[NSOpenGLContext lock] and -[NSOpenGLContext unlock] should be considered equivalent to CGLLockContext([NSOpenGLContext CGLContextObj]) and CGLUnlockContext([NSOpenGLContext CGLContextObj]).

NSOpenGLContext getter for associated pixel format

It is now possible to access the pixel format associated of an OpenGLContext using the -[NSOpenGLContext pixelFormat] method.

Changes to -[NSView noteFocusRingMaskChanged] (Section added since WWDC seed)

-[NSView setNeedsDisplay:] and -[NSView setNeedsDisplayInRect:] used to call -[NSView noteFocusRingMaskChanged]. In Mac OS X 10.10 this is no longer the case. Views must manually make the call -[NSView noteFocusRingMaskChanged]. This enables views to redraw portions of themselves without needlessly redrawing their focus rings, which can be expensive.

New NSGraphicsContext CGContext methods (Section added since WWDC seed)

In MacOSX 10.10 NSGraphicsContext offers two new methods, +graphicsContextWithCGContext:flipped: and -CGContext. These methods are exactly the same as the existing +graphicsContextWithGraphicsPort:flipped: and -graphicsPort methods, excepting that they are typed to accept and return CGContextRef respectively. The old methods will be deprecated in a future release.


NSColor (Section updated since WWDC seed)

NSColor exposes new system colors in 10.10 for static text and related elements: labelColor, secondaryLabelColor, tertiaryLabelColor, and quaternaryLabelColor. The first two are for primary and secondary static text elements. These colors are applied to new labels dragged out in Interface Builder. The tertiaryLabelColor is for disabled static text elements, and quaternaryLabelColor is for large disabled static text elements. These colors can also be applied to other related UI elements where related and appropriate; for instance, quaternaryLabelColor is recommended for separator lines as well as large glyphs or icons.

These new colors as well as some of the existing system colors now paint differently depending on the current appearance. Please be sure to set colors while the appropriate appearance is in effect and do not cache their individual color component values.


Hyphenation

Hyphenation is now enabled by default for all text rendering and measurement. The hyphenation factor is 0.4.

In addition, the handling of the soft hyphen character (U+00AD) has been changed. In prior versions of OS X, we handled the character just as a line break opportunity when the hyphenation is disabled. Now, we always show the hyphen glyph whenever wrapping at the character.