Swiftpack.co - Package - Rightpoint/Anchorage

Anchorage

Swift 4.2 + 5.0 CircleCI Version Platform Carthage compatible

A lightweight collection of intuitive operators and utilities that simplify Auto Layout code. Anchorage is built directly on top of the NSLayoutAnchor API.

Each expression acts on one or more NSLayoutAnchors, and returns active NSLayoutConstraints. If you want inactive constraints, here's how to do that.

Usage

Alignment

// Pin the button to 12 pt from the leading edge of its container
button.leadingAnchor == container.leadingAnchor + 12

// Pin the button to at least 12 pt from the trailing edge of its container
button.trailingAnchor <= container.trailingAnchor - 12

// Center one or both axes of a view
button.centerXAnchor == container.centerXAnchor
button.centerAnchors == container.centerAnchors

Relative Alignment

// Position a view to be centered at 2/3 of its container's width
view.centerXAnchor == 2 * container.trailingAnchor / 3

// Pin the top of a view at 25% of container's height
view.topAnchor == container.bottomAnchor / 4

Sizing

// Constrain a view's width to be at most 100 pt
view.widthAnchor <= 100

// Constraint a view to a fixed size
imageView.sizeAnchors == CGSize(width: 100, height: 200)

// Constrain two views to be the same size
imageView.sizeAnchors == view.sizeAnchors

// Constrain view to 4:3 aspect ratio
view.widthAnchor == 4 * view.heightAnchor / 3

Composite Anchors

Constrain multiple edges at a time with this syntax:

// Constrain the leading, trailing, top and bottom edges to be equal
imageView.edgeAnchors == container.edgeAnchors

// Inset the edges of a view from another view
let insets = UIEdgeInsets(top: 5, left: 10, bottom: 15, right: 20)
imageView.edgeAnchors == container.edgeAnchors + insets

// Inset the leading and trailing anchors by 10
imageView.horizontalAnchors >= container.horizontalAnchors + 10

// Inset the top and bottom anchors by 10
imageView.verticalAnchors >= container.verticalAnchors + 10

Use leading and trailing

Using leftAnchor and rightAnchor is rarely the right choice. To encourage this, horizontalAnchors and edgeAnchors use the leadingAnchor and trailingAnchor layout anchors.

Inset instead of Shift

When constraining leading/trailing or top/bottom, it is far more common to work in terms of an inset from the edges instead of shifting both edges in the same direction. When building the expression, Anchorage will flip the relationship and invert the constant in the constraint on the far side of the axis. This makes the expressions much more natural to work with.

Priority

The ~ is used to specify priority of the constraint resulting from any Anchorage expression:

// Align view 20 points from the center of its superview, with system-defined low priority
view.centerXAnchor == view.superview.centerXAnchor + 20 ~ .low

// Align view 20 points from the center of its superview, with (required - 1) priority
view.centerXAnchor == view.superview.centerXAnchor + 20 ~ .required - 1

// Align view 20 points from the center of its superview, with custom priority
view.centerXAnchor == view.superview.centerXAnchor + 20 ~ 752

The layout priority is an enum with the following values:

  • .required - UILayoutPriorityRequired (default)
  • .high - UILayoutPriorityDefaultHigh
  • .low - UILayoutPriorityDefaultLow
  • .fittingSize - UILayoutPriorityFittingSizeLevel

Storing Constraints

To store constraints created by Anchorage, simply assign the expression to a variable:

// A single (active) NSLayoutConstraint
let topConstraint = (imageView.topAnchor == container.topAnchor)

// EdgeConstraints represents a collection of constraints
// You can retrieve the NSLayoutConstraints individually,
// or get an [NSLayoutConstraint] via .all, .horizontal, or .vertical
let edgeConstraints = (button.edgeAnchors == container.edgeAnchors).all

Batching Constraints

By default, Anchorage returns active layout constraints. If you'd rather return inactive constraints for use with the NSLayoutConstraint.activate(_:) method for performance reasons, you can do it like this:

let constraints = Anchorage.batch(active: false) {
    view1.widthAnchor == view2.widthAnchor
    view1.heightAnchor == view2.heightAnchor / 2 ~ .low
    // ... as many constraints as you want
}

// Later:
NSLayoutConstraint.activate(constraints)

You can also pass active: true if you want the constraints in the array to be automatically activated in a batch.

Autoresizing Mask

Anchorage sets the translatesAutoresizingMaskIntoConstraints property to false on the left hand side of the expression, so you should never need to set this property manually. This is important to be aware of in case the container view relies on translatesAutoresizingMaskIntoConstraints being set to true. We tend to keep child views on the left hand side of the expression to avoid this problem, especially when constraining to a system-supplied view.

Installation

CocoaPods

To integrate Anchorage into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'Anchorage'

Carthage

To integrate Anchorage into your Xcode project using Carthage, specify it in your Cartfile:

github "Rightpoint/Anchorage"

Run carthage update to build the framework and drag the built Anchorage.framework into your Xcode project.

License

This code and tool is under the MIT License. See LICENSE file in this repository.

Any ideas and contributions welcome!

Github

link
Stars: 548

Dependencies

Used By

Total: 0

Releases

4.4.0 - 2020-02-03 19:47:03

New Features

  • Swift Package Manager support #86 (thanks @ZevEisenberg!)
  • Runs tests using Xcode 11 for Swift 4.2 and 5.0

Deprecations

  • Drops official support for Xcode 10.x and Swift 4.0, although they should still continue to work.

See all commits since 4.3.1.

- 2019-05-31 00:57:22

New Features

  • Full support for Xcode 10.2 and Swift 5.0

Deprecations

  • Drops official support for Xcode 9.x

See all commits since 4.3.

- 2018-09-22 20:11:24

New Features

  • Full support for Xcode 10 and Swift 4.2 (#62, @heyltsjay)

- 2018-06-25 20:32:53

See all commits since 4.2.3.

Bug Fixes

  • Allow construction of an AnchorPair outside of Anchorage. (#59, @ZevEisenberg)
    • Note: this change is non-breaking, but to realize its benefits, you may need to delete code like this if you had added it to your project:

      extension AnchorPair {
          init(first: T, second: U) {
              self.first = first
              self.second = second
          }
      }
      

- 2018-06-20 14:22:59

See all commits since 4.2.2.

Bug Fixes

  • Added support for building with Swift 4.2 in Xcode 10. (#60, @kabiroberai)

- 2018-04-18 19:06:52

See all commits since 4.2.1.

Bug Fixes

  • Updated to Swift 4.1 and Xcode 9 (#56, @irace)
  • Started building on CircleCI 2.0 (#57, @ZevEisenberg)

4.2.1 - 2017-12-19 20:48:03

  • Added support for nested batches, thanks to @sanekgusev (#52)

4.2 - 2017-11-29 15:52:23

  • Add support for multiplier constraints derived from axis, thanks to @sanekgusev

4.1 - 2017-09-25 21:00:35

Anchorage 4.1 adds support for Xcode 9, iOS 11, tvOS 11, and macOS 10.13.

This version also drops support for Float80. If you were previously using this floating-point type in UI code, you may want to... reconsider.

4.0 - 2017-05-10 17:39:33

Anchorage 4 adds a new batching API for creating multiple constraints, with the ability to return inactive constraints if you need them. It also improves the API in many places, restructures the code to be more maintainable, and drops Swift 2.3 support. See the ReadMe for a full rundown of the current feature set.

New Features

  • Batching: any constraints created in the batch will not be activated until the whole batch returns. Optionally, you can write batch(active: false) { ... } to get back inactive constraints with Auto Layout's batch-activation mechanism.
  • Added sizeAnchors: you can now pin a view's size to a literal CGSize or another view's size anchors in a single line of code.
  • Added support for using (UI/NS)EdgeInsets when constraining edge anchors; useful for margins when not using layoutMarginsGuide.

Improvements

  • Expanded and improved the use of layout priority shorthand enum from #33. This is now the preferred way to adjust priority in Anchorage.
  • Added tests

Breaking Changes

  • dropped Swift 2.3 support
  • minor changes that may make some priority-related code fail to compile. This code should be converted to the much more concise new shorthand syntax; see the ReadMe for details.
  • the following have been renamed:
    • AxisGroupConstraintPair
    • EdgeGroupConstraintGroup
    • LayoutPriorityPriority

Bug fixes

  • Fixed copy/paste errors that resulted in incorrect constraints being created (https://github.com/Raizlabs/Anchorage/pull/37/commits/9891570de90226eb3bd2c09c48c30b4ffc0e19d9)

3.2.0 - 2017-03-30 18:57:27

  • Added new enums for working with common layout priorities.

3.1.0 - 2017-02-22 15:05:46

  • Priority operator precedence adjusted so that parens aren't required for most expressions
  • Anchorage now supports OS X thanks to @mattprowse !

Swift 3 Compatibility - 2017-02-17 14:43:15

Anchorage now supports both Swift 2.3 and Swift 3

2.0.1 - 2016-07-18 13:57:52

  • Carthage compatibility thanks to @jwatson

Initial Release - 2016-04-16 13:08:14