NSLayoutConstraint Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.7 and later.
Companion guide
Declared in
NSLayoutConstraint.h
Related sample code

Overview

A constraint defines a relationship between two attributes of user interface objects that must be satisfied by the constraint-based layout system.

The relationship involves a first attribute, a relationship type, and a modified second value formed by multiplying an attribute by a constant factor and then adding another constant factor to it. In other words, constraints look very much like linear equations of the following form:

attribute1 == multiplier × attribute2 + constant

The right side of this equation can be considered a modified attribute, so this equation could be described in words as “attribute one must be equal to the modified attribute two.” Note that the constraint-based layout system is free to modify the attributes on either side of the equation as part of satisfying the system of constraints that apply to the objects being laid out.

Constraints are not limited to equality relationships. They can also use greater than or equal (>=) or less than or equal (<=) to describe the relationship between the two attributes. Constraints also have priorities, indicating to the layout system which constraint should take priority when two or more constraints are in conflict. The combination of a set of constraints, along with the set of priorities for applying those constraints, can uniquely describe the relationship between multiple user interface elements in all legal configurations for those elements, allowing the system to dynamically layout the user interface as the size and location of user interface elements change.

Tasks

Creating Constraints

Accessing Constraint Data

Identifying a Constraint

Controlling Constraint Archiving

Properties

constant

The constant added to the multiplied second attribute participating in the constraint.

@property CGFloat constant
Discussion

Unlike the other properties, the constant may be modified after constraint creation. Setting the constant on an existing constraint performs much better than removing the constraint and adding a new one that's just like the old but for having a new constant.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

firstAttribute

The attribute of the first object participating in the constraint.

@property (readonly) NSLayoutAttribute firstAttribute
Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

firstItem

The first object participating in the constraint.

@property (readonly, assign) id firstItem
Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

identifier

The name that identifies the constraint.

@property (copy) NSString *identifier
Discussion

A constraint’s identifier is available in its description. Identifiers that start with NS are reserved by the system.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSLayoutConstraint.h

multiplier

The multiplier applied to the second attribute participating in the constraint.

@property (readonly) CGFloat multiplier
Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

priority

The priority of the constraint.

@property NSLayoutPriority priority
Discussion

If a constraint's priority level is less than NSLayoutPriorityRequired in OS X or UILayoutPriorityRequired in iOS, then it is optional. Higher priority constraints are met before lower priority constraints.

Constraint satisfaction is not all or nothing. If a constraint 'a == b' is optional, the constraint-based layout system will attempt to minimize 'abs(a-b)'.

This property may only be modified as part of initial set up. An exception will be thrown if it is set after a constraint has been added to a view.

Priorities must be greater than 0 and less than or equal to NSLayoutPriorityRequired in OS X or UILayoutPriorityRequired in iOS.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

relation

The relation between the two attributes in the constraint.

@property (readonly) NSLayoutRelation relation
Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

secondAttribute

The attribute of the second object participating in the constraint.

@property (readonly) NSLayoutAttribute secondAttribute
Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

secondItem

The second object participating in the constraint.

@property (readonly, assign) id secondItem
Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

shouldBeArchived

Determines whether the constraint should be archived by its owning view.

@property BOOL shouldBeArchived
Discussion

When a view is archived, it archives some but not all constraints in its constraints array. The value of shouldBeArchived informs the view if a particular constraint should be archived by the view.

If a constraint is created at runtime in response to the state of the object, it isn't appropriate to archive the constraint—rather you archive the state that gives rise to the constraint. The default value for this property is NO.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

Class Methods

constraintsWithVisualFormat:options:metrics:views:

Create constraints described by an ASCII art-like visual format string.

+ (NSArray *)constraintsWithVisualFormat:(NSString *)format options:(NSLayoutFormatOptions)opts metrics:(NSDictionary *)metrics views:(NSDictionary *)views
Parameters
format

The format specification for the constraints.

opts

Options describing the attribute and the direction of layout for all objects in the visual format string.

metrics

A dictionary of constants that appear in the visual format string. The keys must be the string values used in the visual format string, and the values must be NSNumber objects.

views

A dictionary of views that appear in the visual format string. The keys must be the string values used in the visual format string, and the values must be the view objects.

Return Value

An array of constraints that, combined, express the constraints between the provided views and their parent view as described by the visual format string. The constraints are returned in the same order they were specified in the visual format string.

Discussion

The language used for the visual format string is described in “Visual Format Language” in Auto Layout Guide.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSLayoutConstraint.h

constraintWithItem:attribute:relatedBy:toItem:attribute:multiplier:constant:

Create a constraint of the form "view1.attr1 <relation> view2.attr2 * multiplier + constant".

+ (id)constraintWithItem:(id)view1 attribute:(NSLayoutAttribute)attr1 relatedBy:(NSLayoutRelation)relation toItem:(id)view2 attribute:(NSLayoutAttribute)attr2 multiplier:(CGFloat)multiplier constant:(CGFloat)c
Parameters
view1

The view for the left-hand side of the constraint.

attr1

The attribute of the view for the left-hand side of the constraint.

relation

The relationship between the left-hand side of the constraint and the right-hand side of the constraint.

view2

The view for the right-hand side of the constraint.

attr2

The attribute of the view for the right-hand side of the constraint.

multiplier

The constant multiplied with the attribute on the right-hand side of the constraint as part of getting the modified attribute.

c

The constant added to the multiplied attribute value on the right-hand side of the constraint to yield the final modified attribute.

Return Value

A constraint object relating the two provided views with the specified relation, attributes, multiplier, and constant.

Discussion

Constraints are of the form "view1.attr1 <relation> view2.attr2 * multiplier + constant". If the constraint you wish to express does not have a second view and attribute, use nil and NSLayoutAttributeNotAnAttribute.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSLayoutConstraint.h

Constants

NSLayoutRelation

Describes the relation between the first attribute and the modified second attribute in a constraint.

enum {
   NSLayoutRelationLessThanOrEqual = -1,
   NSLayoutRelationEqual = 0,
   NSLayoutRelationGreaterThanOrEqual = 1,
};
typedef NSInteger NSLayoutRelation;
Constants
NSLayoutRelationLessThanOrEqual

The constraint requires that the first attribute be less than or equal to the modified second attribute.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutRelationEqual

The constraint requires that the first attribute be exactly equal to the modified second attribute.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutRelationGreaterThanOrEqual

The constraint requires that the first attribute by greater than or equal to the modified second attribute.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttribute

Layout attributes are used to specify the part of the object’s visual representation that should be used to get the value for the constraint.

enum {
   NSLayoutAttributeLeft = 1,
   NSLayoutAttributeRight,
   NSLayoutAttributeTop,
   NSLayoutAttributeBottom,
   NSLayoutAttributeLeading,
   NSLayoutAttributeTrailing,
   NSLayoutAttributeWidth,
   NSLayoutAttributeHeight,
   NSLayoutAttributeCenterX,
   NSLayoutAttributeCenterY,
   NSLayoutAttributeBaseline,
   
   NSLayoutAttributeNotAnAttribute = 0
};
typedef NSInteger NSLayoutAttribute;
Constants
NSLayoutAttributeLeft

The left side of the object’s alignment rectangle.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeRight

The right side of the object’s alignment rectangle.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeTop

The top of the object’s alignment rectangle.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeBottom

The bottom of the object’s alignment rectangle.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeLeading

The leading edge of the object’s alignment rectangle.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeTrailing

The trailing edge of the object’s alignment rectangle.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeWidth

The width of the object’s alignment rectangle.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeHeight

The height of the object’s alignment rectangle.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeCenterX

The center along the x-axis of the object’s alignment rectangle.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeCenterY

The center along the y-axis of the object’s alignment rectangle.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeBaseline

The object’s baseline.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeNotAnAttribute

The requested attribute does not exist. This result would be returned if you asked a constraint with no second object for the attribute of its second object.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatOptions

A bit mask that specifies both a part of an interface element to align and a direction for the alignment between two interface elements.

enum {
   /* choose only one of these */
   NSLayoutFormatAlignAllLeft = NSLayoutAttributeLeft,
   NSLayoutFormatAlignAllRight = NSLayoutAttributeRight,
   NSLayoutFormatAlignAllTop = NSLayoutAttributeTop,
   NSLayoutFormatAlignAllBottom = NSLayoutAttributeBottom,
   NSLayoutFormatAlignAllLeading = NSLayoutAttributeLeading,
   NSLayoutFormatAlignAllTrailing = NSLayoutAttributeTrailing,
   NSLayoutFormatAlignAllCenterX = NSLayoutAttributeCenterX,
   NSLayoutFormatAlignAllCenterY = NSLayoutAttributeCenterY,
   NSLayoutFormatAlignAllBaseline = NSLayoutAttributeBaseline,
   
   NSLayoutFormatAlignmentMask = 0xFF,
   
   /* choose only one of these three */
   NSLayoutFormatDirectionLeadingToTrailing = 0 << 8, // default
   NSLayoutFormatDirectionLeftToRight = 1 << 8,
   NSLayoutFormatDirectionRightToLeft = 2 << 8,
   
   NSLayoutFormatDirectionMask = 0x3 << 8,
};
typedef NSUInteger NSLayoutFormatOptions;
Constants
NSLayoutFormatAlignAllLeft

Align all specified interface elements using NSLayoutAttributeLeft on each.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllRight

Align all specified interface elements using NSLayoutAttributeRight on each.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllTop

Align all specified interface elements using NSLayoutAttributeTop on each.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllBottom

Align all specified interface elements using NSLayoutAttributeBottom on each.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllLeading

Align all specified interface elements using NSLayoutAttributeLeading on each.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllTrailing

Align all specified interface elements using NSLayoutAttributeTrailing on each.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllCenterX

Align all specified interface elements using NSLayoutAttributeCenterX on each.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllCenterY

Align all specified interface elements using NSLayoutAttributeCenterY on each.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllBaseline

Align all specified interface elements using NSLayoutAttributeBaseline on each.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignmentMask

Bit mask that can be combined with a NSLayoutFormatOptions variable to yield only the alignment portion of the format options.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatDirectionLeadingToTrailing

Arrange objects in order based on the normal text flow for the current user interface language. In English this results in the first object being placed farthest to the left, the next one to its right, and so on. In right to left languages this ordering is reversed.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatDirectionLeftToRight

Arrange objects in order from left to right.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatDirectionRightToLeft

Arrange objects in order from right to left.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatDirectionMask

Bit mask that can be combined with a NSLayoutFormatOptions variable to yield only the direction portion of the format options.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutConstraintOrientation

The layout constraint orientation describes whether the constraint is used to enforce layout between objects horizontally or vertically.

enum {
   NSLayoutConstraintOrientationHorizontal = 0,
   NSLayoutConstraintOrientationVertical = 1
};
typedef NSInteger NSLayoutConstraintOrientation;
Constants
NSLayoutConstraintOrientationHorizontal

The constraint is applied when laying out the horizontal relationship between objects.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutConstraintOrientationVertical

The constraint is applied when laying out the vertical relationship between objects.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSEdgeInsets

Edge insets describe the distance between the edges of one rectangle to a related rectangle that can be described by measuring a constant but edge-specific distance from each edge.

typedef struct {
   CGFloat top;
   CGFloat left;
   CGFloat bottom;
   CGFloat right;
} NSEdgeInsets;
Fields
top

The distance from the top of the source rectangle to the top of the result rectangle.

left

The distance from the left side of the source rectangle to the left side of the result rectangle.

bottom

The distance from the bottom of the source rectangle to the bottom of the result rectangle.

right

The distance from the right side of the source rectangle to the right side of the result rectangle.

Discussion

A common use for this structure is to describe the relationship between a view’s frame and its alignment rectangle.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSLayoutConstraint.h

NSLayoutPriority

The layout priority is used to indicate to the constraint-based layout system which constraints are more important, allowing the system to make appropriate tradeoffs when satisfying the constraints of the system as a whole.

enum {
   NSLayoutPriorityRequired = 1000,
   NSLayoutPriorityDefaultHigh = 750,
   NSLayoutPriorityDragThatCanResizeWindow = 510,
   NSLayoutPriorityWindowSizeStayPut = 500,
   NSLayoutPriorityDragThatCannotResizeWindow = 490,
   NSLayoutPriorityDefaultLow = 250,
   NSLayoutPriorityFittingSizeCompression = 50,
};
typedef float NSLayoutPriority;
Constants
NSLayoutPriorityRequired

A required constraint. Do not specify a layout constraint that exceeds this number.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutPriorityDefaultHigh

This is the priority level with which a button resists compressing its content. Note that it is higher than NSLayoutPriorityWindowSizeStayPut. This means dragging to resize a window will not make buttons clip. Rather the window frame is constrained.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutPriorityDragThatCanResizeWindow

This is the appropriate priority level for a drag that may end up resizing the window. This needn't be a drag whose explicit purpose is to resize the window. The user might be dragging around window contents, and it might be desirable that the window get bigger to accommodate those contents.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutPriorityWindowSizeStayPut

This is the priority level at which the window prefers to stay the same size. It's generally not appropriate to make a constraint at exactly this priority. You want to be higher or lower.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutPriorityDragThatCannotResizeWindow

This is the priority level at which a split view divider, say, is dragged. It won't resize the window.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutPriorityDefaultLow

This is the priority level at which a button hugs its contents horizontally.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.

NSLayoutPriorityFittingSizeCompression

When you send a fittingSize message to a view, the smallest size that is large enough for the view's contents is computed. This is the priority level with which the view wants to be as small as possible in that computation. It's quite low. It is generally not appropriate to make a constraint at exactly this priority. You want to be higher or lower.

Available in OS X v10.7 and later.

Declared in NSLayoutConstraint.h.