Swiftpack.co - Package - PureLayout/PureLayout
Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.

PureLayout

Build Status Version Platform License

The ultimate API for iOS & OS X Auto Layout — impressively simple, immensely powerful. PureLayout extends UIView/NSView, NSArray, and NSLayoutConstraint with a comprehensive Auto Layout API that is modeled after Apple's own frameworks. PureLayout is a cross-platform Objective-C library that works (and looks!) great in Swift. It is fully backwards-compatible with all versions of iOS and OS X that support Auto Layout.

Writing Auto Layout code from scratch isn't easy. PureLayout provides a fully capable and developer-friendly interface for Auto Layout. It is designed for clarity and simplicity, and takes inspiration from the AutoLayout UI options available in Interface Builder while delivering far more flexibility. The API is also highly efficient, as it adds only a thin layer of third party code and is engineered for maximum performance.

Table of Contents

  1. Setup
  2. API Cheat Sheet
  3. Usage
  1. PureLayout vs. the rest
  2. Problems, Suggestions, Pull Requests?

Setup

Compatibility

The current release of PureLayout supports all versions of iOS and OS X since the introduction of Auto Layout on each platform, in both Swift and Objective-C, with a single codebase!

  • Xcode
    • Language Support: Swift (any version), Objective-C
    • Fully Compatible With: Xcode 7.0
    • Minimum Supported Version: Xcode 5.0
  • iOS
    • Fully Compatible With: iOS 9.0
    • Minimum Deployment Target: iOS 6.0
  • OS X
    • Fully Compatible With: OS X 10.11
    • Minimum Deployment Target: OS X 10.7

Using CocoaPods

  1. Add the pod PureLayout to your Podfile.
pod 'PureLayout'
  1. Run pod install from Terminal, then open your app's .xcworkspace file to launch Xcode.
  2. Import the PureLayout.h umbrella header.
  • With use_frameworks! in your Podfile
    • Swift: import PureLayout
    • Objective-C: #import <PureLayout/PureLayout.h> (or with Modules enabled: @import PureLayout;)
  • Without use_frameworks! in your Podfile
    • Swift: Add #import "PureLayout.h" to your bridging header.
    • Objective-C: #import "PureLayout.h"

That's it - now go write some beautiful Auto Layout code!

Using Carthage

  1. Add the PureLayout/PureLayout project to your Cartfile.
github "PureLayout/PureLayout"
  1. Run carthage update, then follow the additional steps required to add the framework into your project.
  2. Import the PureLayout framework/module.
  • Swift: import PureLayout
  • Objective-C: #import <PureLayout/PureLayout.h> (or with Modules enabled: @import PureLayout;)

That's it - now go write some beautiful Auto Layout code!

Manually from GitHub

  1. Download the source files in the PureLayout subdirectory.
  2. Add the source files to your Xcode project.
  3. Import the PureLayout.h header.
  • Swift: Add #import "PureLayout.h" to your bridging header.
  • Objective-C: #import "PureLayout.h"

That's it - now go write some beautiful Auto Layout code!

App Extensions

To use PureLayout in an App Extension, you need to do a bit of extra configuration to prevent usage of unavailable APIs. Click here for more info.

Releases

Releases are tagged in the git commit history using semantic versioning. Check out the releases and release notes for each version.

API Cheat Sheet

This is just a handy overview of the core API methods. Explore the header files for the full API, and find the complete documentation above the implementation of each method in the corresponding .m file. A couple of notes:

  • All of the public API methods are namespaced with the prefix auto..., which also makes it easy for Xcode to autocomplete as you type.
  • Methods that create constraints also automatically install (activate) the constraint(s), then return the new constraint(s) for you to optionally store for later adjustment or removal.
  • Many methods below also have a variant which includes a relation: parameter to make the constraint an inequality.

Attributes

PureLayout defines view attributes that are used to create auto layout constraints. Here is an illustration of the most common attributes.

There are 5 specific attribute types, which are used throughout most of the API:

  • ALEdge
  • ALDimension
  • ALAxis
  • ALMargin available in iOS 8.0 and higher only
  • ALMarginAxis available in iOS 8.0 and higher only

Additionally, there is one generic attribute type, ALAttribute, which is effectively a union of all the specific types. You can think of this as the "supertype" of all of the specific attribute types, which means that it is always safe to cast a specific type to the generic ALAttribute type. (Note that the reverse is not true -- casting a generic ALAttribute to a specific attribute type is unsafe!)

UIView/NSView

- autoSetContent(CompressionResistance|Hugging)PriorityForAxis:
- autoCenterInSuperview(Margins) // Margins variant iOS 8.0+ only
- autoAlignAxisToSuperview(Margin)Axis: // Margin variant iOS 8.0+ only
- autoPinEdgeToSuperview(Edge:|Margin:)(withInset:) // Margin variant iOS 8.0+ only
- autoPinEdgesToSuperview(Edges|Margins)(WithInsets:)(excludingEdge:) // Margins variant iOS 8.0+ only
- autoPinEdge:toEdge:ofView:(withOffset:)
- autoAlignAxis:toSameAxisOfView:(withOffset:|withMultiplier:)
- autoMatchDimension:toDimension:ofView:(withOffset:|withMultiplier:)
- autoSetDimension(s)ToSize:
- autoConstrainAttribute:toAttribute:ofView:(withOffset:|withMultiplier:)
- autoPinTo(Top|Bottom)LayoutGuideOfViewController:withInset: // iOS only
- autoPinEdgeToSuperviewSafeArea: // iOS 11.0+ only
- autoPinEdgeToSuperviewSafeArea:withInset: // iOS 11.0+ only

NSArray

// Arrays of Constraints
- autoInstallConstraints
- autoRemoveConstraints
- autoIdentifyConstraints: // iOS 7.0+, OS X 10.9+ only

// Arrays of Views
- autoAlignViewsToEdge:
- autoAlignViewsToAxis:
- autoMatchViewsDimension:
- autoSetViewsDimension:toSize:
- autoSetViewsDimensionsToSize:
- autoDistributeViewsAlongAxis:alignedTo:withFixedSpacing:(insetSpacing:)(matchedSizes:)
- autoDistributeViewsAlongAxis:alignedTo:withFixedSize:(insetSpacing:)

NSLayoutConstraint

+ autoCreateAndInstallConstraints:
+ autoCreateConstraintsWithoutInstalling:
+ autoSetPriority:forConstraints:
+ autoSetIdentifier:forConstraints: // iOS 7.0+, OS X 10.9+ only
- autoIdentify: // iOS 7.0+, OS X 10.9+ only
- autoInstall
- autoRemove

Usage

Sample Code (Swift)

PureLayout dramatically simplifies writing Auto Layout code. Let's take a quick look at some examples, using PureLayout from Swift.

Initialize the view using PureLayout initializer:

let view1 = UIView(forAutoLayout: ())

If you need to use a different initializer (e.g. in UIView subclass), you can also use configureForAutoLayout:

view1.configureForAutoLayout() // alternative to UIView.init(forAutoLayout: ())

Here's a constraint between two views created (and automatically activated) using PureLayout:

view1.autoPinEdge(.top, toEdge: .bottom, ofView: view2)

Without PureLayout, here's the equivalent code you'd have to write using Apple's Foundation API directly:

NSLayoutConstraint(item: view1, attribute: .top, relatedBy: .equal, toItem: view2, attribute: .bottom, multiplier: 1.0, constant: 0.0).active = true

Many APIs of PureLayout create multiple constraints for you under the hood, letting you write highly readable layout code:

// 2 constraints created & activated in one line!
logoImageView.autoCenterInSuperview()

// 4 constraints created & activated in one line!
textContentView.autoPinEdgesToSuperviewEdges(with insets: UIEdgeInsets(top: 20.0, left: 5.0, bottom: 10.0, right: 5.0))

PureLayout always returns the constraints it creates so you have full control:

let constraint = skinnyView.autoMatchDimension(.height, toDimension: .width, ofView: tallView)

PureLayout supports safearea with iOS 11.0+:

view2.autoPinEdge(toSuperviewSafeArea: .top)

PureLayout supports all Auto Layout features including inequalities, priorities, layout margins, identifiers, and much more. It's a comprehensive, developer-friendly way to use Auto Layout.

Check out the example apps below for many more demos of PureLayout in use.

Example Apps

Open the project included in the repository (requires Xcode 6 or higher). It contains iOS (Example-iOS scheme) and OS X (Example-Mac scheme) demos of the library being used in various scenarios. The demos in the iOS example app make a great introductory tutorial to PureLayout -- run each demo, review the code used to implement it, then practice by making some changes of your own to the demo code.

Each demo in the iOS example app has a Swift and Objective-C version. To compile & run the Swift demos, you must use Xcode 7.0 or higher (Swift 2.0) and choose the Example-iOS-Xcode7 scheme. When you run the example app, you can easily switch between using the Swift and Objective-C versions of the demos. To see the constraints in action while running the iOS demos, try using different device simulators, rotating the device to different orientations, as well as toggling the taller in-call status bar in the iOS Simulator.

On OS X, while running the app, press any key to cycle through the demos. You can resize the window to see the constraints in action.

Tips and Tricks

Check out some Tips and Tricks to keep in mind when using the API.

PureLayout vs. the rest

There are quite a few different ways to implement Auto Layout. Here is a quick overview of the available options:

  • Apple NSLayoutConstraint SDK API
    • Pros: Raw power
    • Cons: Extremely verbose; tedious to write; difficult to read
  • Apple Visual Format Language
    • Pros: Concise; convenient
    • Cons: Doesn't support some use cases; lacks compile-time checking and safety; must learn syntax; hard to debug
  • Apple Interface Builder
    • Pros: Visual; interactive; provides compile-time layout checking
    • Cons: Difficult for complex layouts; cannot dynamically set constraints at runtime; encourages hardcoded magic numbers; not always WYSIWYG
  • Apple NSLayoutAnchor SDK API
    • Pros: Clean, readable, and type-safe API for creating individual constraints
    • Cons: Only available in iOS 9.0 and OS X 10.11 and higher; requires manually activating each constraint; no API for creating multiple constraints at once
  • PureLayout
    • Pros: Compatible with Objective-C and Swift codebases; consistent with Cocoa API style; cross-platform API and implementation shared across iOS and OS X; fully backwards-compatible to iOS 6 & OS X 10.7; easy to use; type-safe; efficient
    • Cons: Not the most concise expression of layout code
  • High-level Auto Layout Libraries/DSLs (Cartography, SnapKit, KeepLayout)
    • Pros: Very clean, concise, and convenient
    • Cons: Unique API style is foreign to Apple's APIs; mixed compatibility with Objective-C & Swift; greater dependency on third party code

PureLayout takes a balanced approach to Auto Layout that makes it well suited for any project.

Problems, Suggestions, Pull Requests?

Please open a new Issue here if you run into a problem specific to PureLayout, have a feature request, or want to share a comment. Note that general Auto Layout questions should be asked on Stack Overflow.

Pull requests are encouraged and greatly appreciated! Please try to maintain consistency with the existing code style. If you're considering taking on significant changes or additions to the project, please communicate in advance by opening a new Issue. This allows everyone to get onboard with upcoming changes, ensures that changes align with the project's design philosophy, and avoids duplicated work.

Meta

Originally designed & built by Tyler Fox (@smileyborg). Currently maintained by Mickey Reiss (@mickeyreiss). Distributed with the MIT license.

Github

link
Stars: 7441

Releases

Swift Package Manager Support - 2020-04-25T22:18:25

Title says it all.

PureLayout v3.1.5 - Auto create constraint for safe area and compiler warnings fixes - 2019-07-23T16:44:42

This release fixes a compiler warnings related to ALAttribute as well as fixing a bug related to the +[NSLayoutConstraint autoCreateConstraintsWithoutInstalling] used in a super view safe area inset method.

Accessibility apis - 2018-10-27T17:34:57

This release adds accessibility apis as part of #227 marking the safe area apis as iOS 9 and above.

PureLayout v3.1.2 - Properly release iPhone X support - 2018-08-28T03:43:57

Properly release changes that support the iPhone X and safe areas

PureLayout v3.1 - iPhone X support - 2018-08-25T03:03:55

This release has changes that support the iPhone X and safe areas.

This hasn't had a lot of testing, but wanted to push it out to get feedback and testing.

PureLayout v3.0.2 - Maintenance Release & tvOS Support - 2016-06-11T00:36:32

This is a relatively minor maintenance release.

Thanks to all the contributors!

Psst. Interested in taking PureLayout to the next level? Get in touch if you'd like to become a maintainer.

New Repository URL - 2015-08-31T03:49:13

This release contains no actual changes from v3.0.0 (release notes) – it exists solely to update the repository URL to the new location in the PureLayout organization (https://github.com/PureLayout/PureLayout).

Note: the previous repository URL (https://github.com/smileyborg/PureLayout) will continue to work, as it seamlessly redirects to the new URL.

PureLayout v3.0.0 - 2015-08-17T05:24:58

PureLayout v3.0.0 is a major release, with new APIs, enhancements, and other changes. The v3.0.0 release remains fully backwards compatible with Xcode 5, iOS 6, and OS X 10.7.

Upgrading from PureLayout v2.x? Check out the migration guide.

Breaking Changes from v2.x

  • The following class methods on UIView/NSView have been moved to NSLayoutConstraint. 1583f7b3dbbc519c327aec4c54d36fc77e085017
    • +[autoCreateConstraintsWithoutInstalling:]
    • +[autoSetPriority:forConstraints:]
    • +[autoSetIdentifier:forConstraints:]
  • The methods deprecated in PureLayout v2.0.0 have been removed entirely. 6d204083bc867b208c2ddc5d475b70a65caf9310

Additions

  • New API to batch create, activate, and return all constraints within a block. c2bcb1f976f5b7acf52ef8fce41d0d9115d32ef9
    • +[NSLayoutConstraint autoCreateAndInstallConstraints:]
  • New API to configure an initialized view for use with auto layout (thanks @vivianforzj). e2e75ab9bcdf5b75ddeb8ac85f9f5093b980f46c
    • -[ALView configureForAutoLayout]
  • New API to align a view's axis to another view's axis with a multiplier (thanks @s0mmer). c5a4dc28a33fb2c54ad4d2e54c849e634b80acf9
    • -[ALView autoAlignAxis:toSameAxisOfView:withMultiplier:]
  • New API to pin a view's edges to its superview's edges with zero insets (thanks @pfleiner). c97a5776269d0a649a309c36cbf249ccb22b06c5
    • -[ALView autoPinEdgesToSuperviewEdges]

Enhancements

  • Generics have been added throughout the entire codebase. b030f4f3289271a688d1f67a0fc8b43b675f6d2b bcd91bfa567a331882d712454e96a6f7940a576b 571de949d6926fac748a41a7434212e68a34d024
  • Nullability annotations have been added for all headers. b030f4f3289271a688d1f67a0fc8b43b675f6d2b
  • The methods to distribute views now support distributing an array containing a single view (thanks @pnc). a66c6205b9f43249431b0d1134a346bce9f58f58

Fixes

  • Fixed a warning when compiling using -Wconversion. f58e4b240af1aa1f17cb5c474746a675bb23d896

Fix OS X Legacy Compatibility - 2015-04-25T23:24:04

  • Fix a compilation issue when targeting OS X 10.7

- 2015-02-02T06:21:45

Enhancements & Fixes - 2014-12-09T03:45:24

  • Enhance the autoCreateConstraintsWithoutInstalling: API to return an array of created constraints
  • Add a new API to set the size of an array of views
  • Fix a constraint exception when distributing views

App Extension Support - 2014-11-17T17:25:51

  • Add support for using PureLayout in App Extensions. See this page for more details.

Internal enhancements - 2014-11-10T23:57:15

  • Use a new method to determine the UI layout direction (thanks @vytis)
  • Make activating and deactivating constraints more efficient in some cases

Bug Fixes - 2014-10-18T23:24:31

  • Make the constraint identifier APIs available on Mac OS X, as long as the SDK is at least 10.10 (will work with deployment target of 10.9 or higher)
  • Fix issues with nesting constraint blocks (nested calls to autoSetPriority:, autoSetIdentifier:, etc)
  • Don't set the priority of constraints when installing them unless inside a constraints block

PureLayout v2.0.0 - 2014-10-16T03:16:07

PureLayout v2.0.0 is a major release, with many new features, APIs, and enhancements. The v2.0.0 release is fully backwards compatible with Xcode 5 and iOS 6 and 7 deployment targets (OS X deployment target remains at 10.7 as well).

Upgrading from PureLayout v1.x? Check out the migration guide.

Looking to take it for a test drive? Check out the brand new demos in the example project! (Download as .zip here)

Changes include:

  • Full support for new features in iOS 8 SDK (first baseline and all layout margin attributes, active & identifier properties on NSLayoutConstraint)
  • New API to constrain views to the iOS 8 layout margin attributes
  • New API to prevent automatic installation of constraints
  • Improved Swift compatibility using a new combined enum type ALAttribute
  • Modified existing APIs to distribute views for naming & type consistency
  • Deprecation of the constraint removal API on UIView
  • Internal enhancements and optimizations

More options distributing views - 2014-09-07T21:13:53

  • Add a new API to allow distributing views with fixed spacing but without matching all their sizes (relying on each view's intrinsic content size instead)

Swift Compatibility - 2014-06-24T17:50:19

  • Add a Foundation import which enables Swift compatibility using a bridging header

Initial Release - 2014-06-23T00:30:18