Mac Developer Library

Developer

AppKit Framework Reference NSLayoutConstraint Class Reference

Options
Deployment Target:

On This Page
Language:

NSLayoutConstraint

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.

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.7 and later.
  • Create constraints described by an ASCII art-like visual format string.

    Declaration

    Swift

    class func constraintsWithVisualFormat(_ format: String, options opts: NSLayoutFormatOptions, metrics metrics: [NSObject : AnyObject]?, views views: [NSObject : AnyObject]) -> [AnyObject]

    Objective-C

    + (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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    convenience init(item view1: AnyObject, attribute attr1: NSLayoutAttribute, relatedBy relation: NSLayoutRelation, toItem view2: AnyObject?, attribute attr2: NSLayoutAttribute, multiplier multiplier: CGFloat, constant c: CGFloat)

    Objective-C

    + (instancetype)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • active active Property

    The active state of the constraint.

    Declaration

    Swift

    var active: Bool

    Objective-C

    @property(getter=isActive) BOOL active

    Discussion

    You can activate or deactivate a constraint by changing this property. Note that only active constraints affect the calculated layout. If you try to activate a constraint whose items have no common ancestor, an exception is thrown. For newly created constraints, the active property is NOfalse by default.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • Activates each constraint in the specified array.

    Declaration

    Objective-C

    + (void)activateConstraints:(NSArray *)constraints

    Parameters

    constraints

    An array of constraints to activate.

    Discussion

    This is a convenience method that provides an easy way to activate a set of constraints with one call. The effect of this method is the same as setting the active property of each constraint to YEStrue (typically, using this method is more efficient than activating each constraint individually).

  • Deactivates each constraint in the specified array.

    Declaration

    Objective-C

    + (void)deactivateConstraints:(NSArray *)constraints

    Parameters

    constraints

    An array of constraints to deactivate.

    Discussion

    This is a convenience method that provides an easy way to deactivate a set of constraints with one call. The effect of this method is the same as setting the active property of each constraint to NOfalse (typically, using this method is more efficient than deactivating each constraint individually).

  • priority priority Property

    The priority of the constraint.

    Declaration

    Swift

    var priority: NSLayoutPriority

    Objective-C

    @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)'.

    Priorities may not change from non-required to required or visa versa. An exception will be thrown if a priority of NSLayoutPriorityRequired in OS X or UILayoutPriorityRequired in iOS is changed to a lower priority, or if a lower priority is changed to a required priority after the constraints is added to a view. Changing between an optional priority to a different value is allowed even when the constraint is installed on a view.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • firstItem firstItem Property

    The first object participating in the constraint.

    Declaration

    Swift

    unowned(unsafe) var firstItem: AnyObject { get }

    Objective-C

    @property(readonly, assign) id firstItem

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The attribute of the first object participating in the constraint.

    Declaration

    Swift

    var firstAttribute: NSLayoutAttribute { get }

    Objective-C

    @property(readonly) NSLayoutAttribute firstAttribute

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • relation relation Property

    The relation between the two attributes in the constraint.

    Declaration

    Swift

    var relation: NSLayoutRelation { get }

    Objective-C

    @property(readonly) NSLayoutRelation relation

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The second object participating in the constraint.

    Declaration

    Swift

    unowned(unsafe) var secondItem: AnyObject? { get }

    Objective-C

    @property(readonly, assign) id secondItem

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The attribute of the second object participating in the constraint.

    Declaration

    Swift

    var secondAttribute: NSLayoutAttribute { get }

    Objective-C

    @property(readonly) NSLayoutAttribute secondAttribute

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    var multiplier: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat multiplier

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • constant constant Property

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

    Declaration

    Swift

    var constant: CGFloat

    Objective-C

    @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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The name that identifies the constraint.

    Declaration

    Swift

    var identifier: String?

    Objective-C

    @property(copy) NSString *identifier

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

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

    Declaration

    Swift

    var shouldBeArchived: Bool

    Objective-C

    @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 NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    enum NSLayoutRelation : Int { case LessThanOrEqual case Equal case GreaterThanOrEqual }

    Objective-C

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

    Constants

    • LessThanOrEqual

      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.

    • Equal

      NSLayoutRelationEqual

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

      Available in OS X v10.7 and later.

    • GreaterThanOrEqual

      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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • 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.

    Declaration

    Swift

    enum NSLayoutAttribute : Int { case Left case Right case Top case Bottom case Leading case Trailing case Width case Height case CenterX case CenterY case Baseline case NotAnAttribute }

    Objective-C

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

    Constants

    • Left

      NSLayoutAttributeLeft

      The left side of the object’s alignment rectangle.

      Available in OS X v10.7 and later.

    • Right

      NSLayoutAttributeRight

      The right side of the object’s alignment rectangle.

      Available in OS X v10.7 and later.

    • Top

      NSLayoutAttributeTop

      The top of the object’s alignment rectangle.

      Available in OS X v10.7 and later.

    • Bottom

      NSLayoutAttributeBottom

      The bottom of the object’s alignment rectangle.

      Available in OS X v10.7 and later.

    • Leading

      NSLayoutAttributeLeading

      The leading edge of the object’s alignment rectangle.

      Available in OS X v10.7 and later.

    • Trailing

      NSLayoutAttributeTrailing

      The trailing edge of the object’s alignment rectangle.

      Available in OS X v10.7 and later.

    • Width

      NSLayoutAttributeWidth

      The width of the object’s alignment rectangle.

      Available in OS X v10.7 and later.

    • Height

      NSLayoutAttributeHeight

      The height of the object’s alignment rectangle.

      Available in OS X v10.7 and later.

    • CenterX

      NSLayoutAttributeCenterX

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

      Available in OS X v10.7 and later.

    • CenterY

      NSLayoutAttributeCenterY

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

      Available in OS X v10.7 and later.

    • Baseline

      NSLayoutAttributeBaseline

      The object’s baseline.

      Available in OS X v10.7 and later.

    • NotAnAttribute

      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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    struct NSLayoutFormatOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var AlignAllLeft: NSLayoutFormatOptions { get } static var AlignAllRight: NSLayoutFormatOptions { get } static var AlignAllTop: NSLayoutFormatOptions { get } static var AlignAllBottom: NSLayoutFormatOptions { get } static var AlignAllLeading: NSLayoutFormatOptions { get } static var AlignAllTrailing: NSLayoutFormatOptions { get } static var AlignAllCenterX: NSLayoutFormatOptions { get } static var AlignAllCenterY: NSLayoutFormatOptions { get } static var AlignAllBaseline: NSLayoutFormatOptions { get } static var AlignmentMask: NSLayoutFormatOptions { get } static var DirectionLeadingToTrailing: NSLayoutFormatOptions { get } static var DirectionLeftToRight: NSLayoutFormatOptions { get } static var DirectionRightToLeft: NSLayoutFormatOptions { get } static var DirectionMask: NSLayoutFormatOptions { get } }

    Objective-C

    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

    • AlignAllLeft

      NSLayoutFormatAlignAllLeft

      Align all specified interface elements using NSLayoutAttributeLeft on each.

      Available in OS X v10.7 and later.

    • AlignAllRight

      NSLayoutFormatAlignAllRight

      Align all specified interface elements using NSLayoutAttributeRight on each.

      Available in OS X v10.7 and later.

    • AlignAllTop

      NSLayoutFormatAlignAllTop

      Align all specified interface elements using NSLayoutAttributeTop on each.

      Available in OS X v10.7 and later.

    • AlignAllBottom

      NSLayoutFormatAlignAllBottom

      Align all specified interface elements using NSLayoutAttributeBottom on each.

      Available in OS X v10.7 and later.

    • AlignAllLeading

      NSLayoutFormatAlignAllLeading

      Align all specified interface elements using NSLayoutAttributeLeading on each.

      Available in OS X v10.7 and later.

    • AlignAllTrailing

      NSLayoutFormatAlignAllTrailing

      Align all specified interface elements using NSLayoutAttributeTrailing on each.

      Available in OS X v10.7 and later.

    • AlignAllCenterX

      NSLayoutFormatAlignAllCenterX

      Align all specified interface elements using NSLayoutAttributeCenterX on each.

      Available in OS X v10.7 and later.

    • AlignAllCenterY

      NSLayoutFormatAlignAllCenterY

      Align all specified interface elements using NSLayoutAttributeCenterY on each.

      Available in OS X v10.7 and later.

    • AlignAllBaseline

      NSLayoutFormatAlignAllBaseline

      Align all specified interface elements using NSLayoutAttributeBaseline on each.

      Available in OS X v10.7 and later.

    • AlignmentMask

      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.

    • DirectionLeadingToTrailing

      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.

    • DirectionLeftToRight

      NSLayoutFormatDirectionLeftToRight

      Arrange objects in order from left to right.

      Available in OS X v10.7 and later.

    • DirectionRightToLeft

      NSLayoutFormatDirectionRightToLeft

      Arrange objects in order from right to left.

      Available in OS X v10.7 and later.

    • DirectionMask

      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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    enum NSLayoutConstraintOrientation : Int { case Horizontal case Vertical }

    Objective-C

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

    Constants

    • Horizontal

      NSLayoutConstraintOrientationHorizontal

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

      Available in OS X v10.7 and later.

    • Vertical

      NSLayoutConstraintOrientationVertical

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

      Available in OS X v10.7 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • 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.

    Declaration

    Swift

    typealias NSLayoutPriority = Float

    Objective-C

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

    Constants

    • NSLayoutPriorityRequired

      NSLayoutPriorityRequired

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

      Available in OS X v10.7 through OS X v10.9.

    • NSLayoutPriorityDefaultHigh

      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 through OS X v10.9.

    • NSLayoutPriorityDragThatCanResizeWindow

      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 through OS X v10.9.

    • NSLayoutPriorityWindowSizeStayPut

      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 through OS X v10.9.

    • NSLayoutPriorityDragThatCannotResizeWindow

      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 through OS X v10.9.

    • NSLayoutPriorityDefaultLow

      NSLayoutPriorityDefaultLow

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

      Available in OS X v10.7 through OS X v10.9.

    • NSLayoutPriorityFittingSizeCompression

      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 through OS X v10.9.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.