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.
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!
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.
There are 5 specific attribute types, which are used throughout most of the API:
ALEdge
ALDimension
ALAxis
ALMarginavailable in iOS 8.0 and higher only
ALMarginAxisavailable 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!)
+ 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:
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:
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
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.
The ultimate API for iOS & OS X Auto Layout — impressively simple, immensely powerful. PureLayout extends
UIView
/NSView
,NSArray
, andNSLayoutConstraint
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
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!
Using CocoaPods
PureLayout
to your Podfile.pod install
from Terminal, then open your app’s.xcworkspace
file to launch Xcode.PureLayout.h
umbrella header.use_frameworks!
in your Podfileimport PureLayout
#import <PureLayout/PureLayout.h>
(or with Modules enabled:@import PureLayout;
)use_frameworks!
in your Podfile#import "PureLayout.h"
to your bridging header.#import "PureLayout.h"
That’s it - now go write some beautiful Auto Layout code!
Using Carthage
PureLayout/PureLayout
project to your Cartfile.carthage update
, then follow the additional steps required to add the framework into your project.import PureLayout
#import <PureLayout/PureLayout.h>
(or with Modules enabled:@import PureLayout;
)That’s it - now go write some beautiful Auto Layout code!
Manually from GitHub
PureLayout.h
header.#import "PureLayout.h"
to your bridging header.#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:
auto...
, which also makes it easy for Xcode to autocomplete as you type.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 onlyALMarginAxis
available in iOS 8.0 and higher onlyAdditionally, 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 genericALAttribute
type. (Note that the reverse is not true – casting a generic ALAttribute to a specific attribute type is unsafe!)UIView
/NSView
NSArray
NSLayoutConstraint
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:
If you need to use a different initializer (e.g. in
UIView
subclass), you can also useconfigureForAutoLayout
:Here’s a constraint between two views created (and automatically activated) using PureLayout:
Without PureLayout, here’s the equivalent code you’d have to write using Apple’s Foundation API directly:
Many APIs of PureLayout create multiple constraints for you under the hood, letting you write highly readable layout code:
PureLayout always returns the constraints it creates so you have full control:
PureLayout supports safearea with iOS 11.0+:
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:
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.