Adopting Auto Layout

Views that are aware of Auto Layout can coexist in a window with views that are not. That is, an existing project can incrementally adopt Auto Layout—you don’t have to make it work in your entire app all at once. Instead, you can transition your app to use Auto Layout one view at a time using the property translatesAutoresizingMaskIntoConstraints.

When this property is YES, which it is by default, the autoresizing mask of a view is translated into constraints. For example, if a view is configured like the one below, and translatesAutoresizingMaskIntoConstraints is YES, then the constraints |-20-[button]-20-| and V:|-20-[button(20)] are added to the view’s superview. The net effect is that unaware views behave as they did in versions of OS X prior to version 10.7.


If you move the button 15 points to the left (including by calling setFrame: at runtime), the new constraints would be |-5-[button]-35-| and V:|-20-[button(20)].

For views that are aware of Auto Layout, in most circumstances you want translatesAutoresizingMaskIntoConstraints to be NO. The reason is that the constraints generated by translating the autoresizing mask are already sufficient to completely specify the frame of a view given its superview’s frame, which is generally too much. For example, this translation would prevent a button from automatically assuming its optimal width when its title is changed.

The principal circumstance in which you should not call setTranslatesAutoresizingMaskIntoConstraints: is when you are not the person who specifies a view’s relation to its container. For example, an NSTableRowView instance is placed by NSTableView. It might do this by allowing the autoresizing mask to be translated into constraints, or it might not. This is a private implementation detail. Other views on which you should not call setTranslatesAutoresizingMaskIntoConstraints: include an NSTableCellView object, a subview of NSSplitView, a view of NSTabViewItem, or the content view of an NSPopover, NSWindow, or NSBox object. For those familiar with classic Cocoa layout: If you would not call setAutoresizingMask: on a view in classic style, you should not call setTranslatesAutoresizingMaskIntoConstraints: under Auto Layout.

If you have a view that does its own custom layout by calling setFrame:, your existing code should work. Just don’t call setTranslatesAutoresizingMaskIntoConstraints: with the argument NO on views that you place manually.