OS X Mountain Lion Release Notes
Cocoa Application Framework

Some of the major topics covered in this document:

• iCloud support for NSDocument
  
• Layer-backed drawing improvements
  
• Sharing sheet support
  
• New class NSPageController
  
• NSScrollView zooming and smart magnification
  
• NSImage improvements
  
• NSImage multi representation support for high resolution recap
  
• Full screen changes
  
• Use of NSSavePanel / NSOpenPanel when application sandboxed
  
• Auto layout changes
  
• Changes to Resume for applications
  
• New class NSTextAlternatives
  

Marking updated APIs in headers

 NS_AVAILABLE_MAC(10_8), NS_AVAILABLE(10_8, <iOS Release>), NS_CLASS_AVAILABLE(10_8, <iOS Release>), NS_ENUM_AVAILABLE(10_8)

 #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_8
 ...
 #endif

 NS_DEPRECATED_MAC(<Release when introduced>, 10_8)

Runtime Version Check

double NSAppKitVersionNumber;
#define NSAppKitVersionNumber10_0 577
...
#define NSAppKitVersionNumber10_6 1038
#define NSAppKitVersionNumber10_7 1138

if (floor(NSAppKitVersionNumber) <= NSAppKitVersionNumber10_6) {
  /* On a 10.6.x or earlier system */
} else if (floor(NSAppKitVersionNumber) <= NSAppKitVersionNumber10_7) {
  /* On a 10.7 - 10.7.x system */
} else {
  /* Mountain Lion or later system */
}

#define NSAppKitVersionWithSuchAndSuchBadBugFix 582.1

Backward Compatibility

NSDocument Support for iCloud

NSDocument Versions Preservation Optimization

Debugging -performActivityWithSynchronousWaiting:usingBlock:, -performSynchronousFileAccessUsingBlock:, and -performAsynchronousFileAccessUsingBlock:

po _NSDocumentSerializationInfo()

New and Updated NSDocument Operations

NSDocument Drafts

NSDocument Customizing Default Draft Names

CoreAnimation updates for NSView (i.e.: CALayer backed NSView)

CGContextRef ctx = NSGraphicsContext.currentContext.graphicsPort;
CGContextSetShouldSmoothFonts(ctx, true);
[@"Tandem Unicycle" drawInRect: ... ];

view.layerContentsRedrawPolicy = NSViewLayerContentsRedrawPolicyOnSetNeedsDisplay; // This should be set in init
NSRect frame = view.frame; // Starts out as 100, 100
frame.size = NSMakeSize(300, 300);
[view.animator setFrame:frame]; // Animates the view frame from 100,100 to 300,300
// However, reading back in the view.frame at this point will indicate it is already at 300,300

[NSAnimationContext runAnimationGroup:^(NSAnimationContext *context) {
     context.allowsImplicitAnimations = YES; // Enable implicit CoreAnimation animations
     // Any operations done in this block will be animated
} completionHandler:nil];

NSRect frame = view.frame; // Starts at 0,0 -- the view was already drawn on screen at this location
frame.origin = NSMakePoint(100, 100);
view.frame = frame; // The view should move to 100,100 -- however, it has not drawn yet
frame.origin = NSMakePoint(300, 300);
[[view animator] setFrame:frame]; // The view should animate from point 100,100 to point 300,300

[NSAnimationContext runAnimationGroup:^(NSAnimationContext *context) {
  context.duration = 0;
  NSRect frame = view.frame; // Starts at 0,0 -- the view was already drawn on screen at this location
  frame.origin = NSMakePoint(100, 100);
  view.frame = frame; // The view should move to 100,100 -- however, it has not drawn yet
} completionHandler:^ {
  NSRect frame = view.frame; // Now it has drawn at 100,100
  frame.origin = NSMakePoint(300, 300);
  [[view animator] setFrame:frame]; // This will correctly animate from 100,100 to 300, 300 using the default animation context duration
}];

NSTableView/NSOutlineView

NSOutlineView

NSButton / NSButtonCell

NSInterfaceStyle

Zooming ScrollView

/* Allow the user to magnify the scrollview. */
@property BOOL allowsMagnification;

/* This value determines how much the content is currently scaled. To animate the magnification, use the object's animator.
   The default value is 1.0.
*/
@property CGFloat magnification;

/* This value determines how large the content can be magnified. It must be greater than or equal to the minimum magnification.
   The default value is 4.0.
*/
@property CGFloat maxMagnification;

/* This value determines how small the content can be magnified. The default value is 0.25.
*/
@property CGFloat minMagnification;

/* Magnify content view proportionally such that the entire rect (in content view space) fits centered in the scroll view.
   The resulting magnification value is clipped to the minMagnification and maxMagnification values. To animate the magnification,
   use the object's animator.
*/
- (void)magnifyToFitRect:(NSRect)rect;

/* Scale the content view such that the passed in point (in content view space) remains at the same screen location once the scaling
   is completed. The resulting magnification value is clipped to the minMagnification and maxMagnification values. To animate the
   magnification, use the object's animator.
*/
- (void)setMagnification:(CGFloat)magnification centeredAtPoint:(NSPoint)point;

/* This notification is sent at the beginning of a magnify gesture. The notification object is the scroll view performing the magnification.
*/
NSString *NSScrollViewWillStartLiveMagnifyNotification;

/* This notification is sent at the end of magnify gesture. The notification object is the scroll view view performing the magnification.
*/
NSString *NSScrollViewDidEndLiveMagnifyNotification;

Smart Magnification

NSEventTypeSmartMagnify

- (void)smartMagnifyWithEvent:(NSEvent *)event;

/* Return the complete rect of the most appropriate content grouping at the specified location. For example, if your content
   is divided into three columns, return the entire rect of the column that contains the location. NSScrollView will attempt
   to magnify such that the smaller dimension fits inside the scroll view while remaining within the
   minMagnification, maxMagnification range.

   If your content layout is sub-divided further than one level deep (for example, two boxes that each contain multiple text
   boxes), then use the visibleRect parameter to determine when to provide the rect of a sub-grouping. Always return a rect
   for the appropriate grouping. If there is no deeper content grouping, return the rect for the deepest grouping. NSScrollView
   will determine when to pan, magnify in, and magnify out.

   Return NSZeroRect for the default behavior.
 */
- (NSRect)rectForSmartMagnificationAtPoint:(NSPoint)location inRect:(NSRect)visibleRect;

Quick Look Gesture

/* Perform a Quick Look on the content at location in the event. If there are no Quick Look items at the location, call super.
   Also, see quickLookPreviewItems: further below.
*/
- (void)quickLookWithEvent:(NSEvent *)event;

/* Perform a Quick Look on the text cursor position, selection, or whatever is appropriate for your view. If there are no Quick Look
   items, then call [[self nextResponder] tryToPerform:_cmd with:sender]; to pass the request up the responder chain. Eventually
   AppKit will attempt to perform a dictionary look up. Also see quickLookWithEvent: above.
*/
- (void)quickLookPreviewItems:(id)sender;

NSPageController

NSPageController History Mode aka Non View Controller Mode

- (void)pageControllerWillStartLiveTransition:(NSPageController *)pageController;

- (void)pageController:(NSPageController *)pageController didTransitionToObject:(id)object;

- (void)pageControllerDidEndLiveTransition:(NSPageController *)pageController;

NSPageController Custom Mode aka View Controller Mode

- (NSString *)pageController:(NSPageController *)pageController identifierForObject:(id)object;
- (NSViewController *)pageController:(NSPageController *)pageController viewControllerForIdentifier:(NSString *)identifier;

- (void)pageController:(NSPageController *)pageController prepareViewController:(NSViewController *)viewController withObject:(id)object;

- (void)pageControllerWillStartLiveTransition:(NSPageController *)pageController;

 - (void)pageController:(NSPageController *)pageController didTransitionToObject:(id)object;

- (void)pageControllerDidEndLiveTransition:(NSPageController *)pageController;

NSPageController Completing the Transition

  pageController.selectedIndex = newIndex;

  [NSAnimationContext runAnimationGroup:^(NSAnimationContext *context) {
    [[pageController animator] setSelectedIndex:newIndex];
  } completionHandler:^{
    [pageController completeTransition];
  }];

NSPageController Transition Styles

NSPageController Layer Backed Mode

NSPageController Notes

Smooth Scrolling

  [[NSUserDefaults standardUserDefaults] boolForKey:@"NSScrollAnimationEnabled"];

Accelerated Scrolling

Changes in Loading Nib Files

Auto Layout View Priorities

Auto Layout NSSplitView improvements

- (NSLayoutPriority)holdingPriorityForSubviewAtIndex:(NSInteger)subviewIndex;
- (void)setHoldingPriority:(NSLayoutPriority)priority forSubviewAtIndex:(NSInteger)subviewIndex;

splitView:constrainMinCoordinate:ofSubviewAt:
splitView:constrainMaxCoordinate:ofSubviewAt:
splitView:resizeSubviewsWithOldSize:
splitView:shouldAdjustSizeOfSubview:

Auto Layout NSTextField wrapping improvements

- (void)setPreferredMaxLayoutWidth:(CGFloat)width;
- (CGFloat)preferredMaxLayoutWidth;

[[textField window] layoutIfNeeded];
[textField setPreferredMaxLayoutWidth:[textField alignmentRectForFrame:[textField frame]].width];

Auto Layout NSControl alignment rects

  NSRect alignmentFrame = (NSRect){NSZeroPoint, [control intrinsicContentSize]};

Auto Layout and Non-Finite Frames

NSSharingService

Sharing service integration for NSTextView

ARC Weak References

NSApplication

- (void)applicationDidFinishLaunching:(NSNotification *)notification {
    NSUserNotification *launchNotification = [[notification userInfo]
                                  objectForKey:NSApplicationLaunchUserNotificationKey];
    if (launchNotification) {
        // application was launched by a user selection from Notification Center
    }
}

Full Screen

Using NSSavePanel / NSOpenPanel API in an App Sandbox

NSOpenPanel : NSSavePanel : NSPanel : NSWindow : NSResponder : NSObject

NSOpenPanel : NSSavePanel : NSObject

Titlebar Renaming

Changes to Resume for Applications

Adopt Automatic Termination

NSTextAlternatives

Additional API for Spellchecking

- (NSString *)languageForWordRange:(NSRange)range
                          inString:(NSString *)string
                       orthography:(NSOrthography *)orthography;

NSImage

+[NSImage imageWithSize:flipped:drawingHandler:]
-[NSCustomImageRep initWithSize:flipped:drawingHandler:]
-[NSCustomImageRep drawingHandler]

static void updateLayerWithImageInWindow(NSImage *image, CALayer *layer, NSWindow *window)
{
    CGFloat baseScaleFactor = [window backingScaleFactor]; // This is the scale factor of the screen we are displayed on.

    NSSize imageSize = [image size];
    CGRect layerSize = [layer bounds].size;

    CGFloat additionalLayerScaleFactor = fmax(layerSize.width / imageSize.width, layerSize.height / imageSize.height);

    CGFloat desiredScaleFactor = baseScaleFactor * additionalLayerScaleFactor; // this scale factor is appropriate
                                                                               // for the actual pixel bounds of the layer.

    CGFloat actualScaleFactor = [image recommendedLayerContentsScale: desiredScaleFactor]; // Don't use a higher scale
                                          // factor if the image can't provide it. If the image is resolution independent
                                          // the return value will be the same as the input.

    id layerContents = [image layerContentsForContentsScale:actualScaleFactor]; // Now we have an appropriately
                                          // sized object to use as the contents of a layer.

    [layer setContents:layerContents];
    [layer setContentsScale:actualScaleFactor];
}

NSWindow

NSString *NSWindowDidChangeBackingPropertiesNotification;
@protocol NSWindowDelegate <NSObject>
@optional
...
- (void)windowDidChangeBackingProperties:(NSNotification *)notification;
...
@end

NSString *NSBackingPropertyOldScaleFactorKey;
NSString *NSBackingPropertyOldColorSpaceKey;

NSView

- (BOOL)layer:(CALayer *)layer shouldInheritContentsScale:(CGFloat)newScale fromWindow:(NSWindow *)window;

Managing NSImages with multiple representations

Managing application and document icons

NSOpenGL

NSColor

+ (NSColor *)underPageBackgroundColor;

+ (NSColor *)colorWithCGColor:(CGColorRef)cgColor;
- (CGColorRef)CGColor;

NSProgressIndicator

NSRulerView

New gestures for NSTextView

NSFont