NSLayoutConstraint Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in iOS 6.0 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

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 iOS 6.0 and later.
Declared In
NSLayoutConstraint.h

firstAttribute

The attribute of the first object participating in the constraint.

@property (readonly) NSLayoutAttribute firstAttribute
Availability
  • Available in iOS 6.0 and later.
Declared In
NSLayoutConstraint.h

firstItem

The first object participating in the constraint.

@property (readonly, assign) id firstItem
Availability
  • Available in iOS 6.0 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 iOS 6.0 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 iOS 6.0 and later.
Declared In
NSLayoutConstraint.h

relation

The relation between the two attributes in the constraint.

@property (readonly) NSLayoutRelation relation
Availability
  • Available in iOS 6.0 and later.
Declared In
NSLayoutConstraint.h

secondAttribute

The attribute of the second object participating in the constraint.

@property (readonly) NSLayoutAttribute secondAttribute
Availability
  • Available in iOS 6.0 and later.
Declared In
NSLayoutConstraint.h

secondItem

The second object participating in the constraint.

@property (readonly, assign) id secondItem
Availability
  • Available in iOS 6.0 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 iOS 6.0 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 iOS 6.0 and later.
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 iOS 6.0 and later.
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 iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutRelationEqual

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

Available in iOS 6.0 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 iOS 6.0 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 iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeRight

The right side of the object’s alignment rectangle.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeTop

The top of the object’s alignment rectangle.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeBottom

The bottom of the object’s alignment rectangle.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeLeading

The leading edge of the object’s alignment rectangle.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeTrailing

The trailing edge of the object’s alignment rectangle.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeWidth

The width of the object’s alignment rectangle.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeHeight

The height of the object’s alignment rectangle.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeCenterX

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

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeCenterY

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

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutAttributeBaseline

The object’s baseline.

Available in iOS 6.0 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 iOS 6.0 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 iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllRight

Align all specified interface elements using NSLayoutAttributeRight on each.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllTop

Align all specified interface elements using NSLayoutAttributeTop on each.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllBottom

Align all specified interface elements using NSLayoutAttributeBottom on each.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllLeading

Align all specified interface elements using NSLayoutAttributeLeading on each.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllTrailing

Align all specified interface elements using NSLayoutAttributeTrailing on each.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllCenterX

Align all specified interface elements using NSLayoutAttributeCenterX on each.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllCenterY

Align all specified interface elements using NSLayoutAttributeCenterY on each.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatAlignAllBaseline

Align all specified interface elements using NSLayoutAttributeBaseline on each.

Available in iOS 6.0 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 iOS 6.0 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 iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatDirectionLeftToRight

Arrange objects in order from left to right.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

NSLayoutFormatDirectionRightToLeft

Arrange objects in order from right to left.

Available in iOS 6.0 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 iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

UILayoutPriority

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 {
   UILayoutPriorityRequired = 1000,
   UILayoutPriorityDefaultHigh = 750,
   UILayoutPriorityDefaultLow = 250,
   UILayoutPriorityFittingSizeLevel = 50,
};
typedef float UILayoutPriority;
Constants
UILayoutPriorityRequired

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

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

UILayoutPriorityDefaultHigh

This is the priority level with which a button resists compressing its content.

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

UILayoutPriorityDefaultLow

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

Available in iOS 6.0 and later.

Declared in NSLayoutConstraint.h.

UILayoutPriorityFittingSizeLevel

When you send a systemLayoutSizeFittingSize: message to a view, the size fitting most closely to the target size is computed. This is the priority level with which the view wants to conform to the target size 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 iOS 6.0 and later.

Declared in NSLayoutConstraint.h.