Redesign and optimize the API

NOTE: This commit includes a number of breaking changes to the API. - Introduce the 'auto' prefix to all public methods, and a new 'al_' prefix to all private methods. This insures against namespace issues and potential conflicts that could arise. - Introduce a new category on NSArray which offers modified versions of the old methods on UIView that add constraints to arrays of views. These methods are also now more resilient, such as if the array includes other objects besides UIViews. - Re-organize some private internal methods.
smileyborg · Nov 15, 2013 · 001a503 · 001a503
1 parent a2839a5
commit 001a503
Show file tree

Hide file tree

Showing 4 changed files with 372 additions and 281 deletions.
diff --git a/Example/Example/ALViewController.m b/Example/Example/ALViewController.m
@@ -83,11 +83,11 @@ - (void)setupDemo1
     NSArray *subviews = @[self.blueView, self.redView, self.yellowView, self.greenView, self.orangeView];
 
     [self.blueView autoSetDimension:ALDimensionWidth toSize:80.0f];
-    [self.containerView autoMatchSubviews:subviews dimension:ALDimensionWidth];
+    [subviews autoMatchViewsDimension:ALDimensionWidth];
 
     [self.orangeView autoCenterInSuperviewAlongAxis:ALAxisVertical];
 
-    [self.containerView autoDistributeSubviews:subviews alongAxis:ALAxisVertical withFixedSize:30.0f alignment:NSLayoutFormatAlignAllCenterX];
+    [subviews autoDistributeViewsAlongAxis:ALAxisVertical withFixedSize:30.0f alignment:NSLayoutFormatAlignAllCenterX];
 }
 
 /**
@@ -101,11 +101,11 @@ - (void)setupDemo2
     NSArray *subviews = @[self.blueView, self.redView, self.yellowView, self.greenView, self.orangeView];
 
     [self.blueView autoMatchDimension:ALDimensionHeight toDimension:ALDimensionWidth ofView:self.blueView];
-    [self.containerView autoMatchSubviews:subviews dimension:ALDimensionHeight];
+    [subviews autoMatchViewsDimension:ALDimensionHeight];
 
     [self.orangeView autoCenterInSuperviewAlongAxis:ALAxisHorizontal];
 
-    [self.containerView autoDistributeSubviews:subviews alongAxis:ALAxisHorizontal withFixedSpacing:10.0f alignment:NSLayoutFormatAlignAllCenterY];
+    [subviews autoDistributeViewsAlongAxis:ALAxisHorizontal withFixedSpacing:10.0f alignment:NSLayoutFormatAlignAllCenterY];
 }
 
 /**
@@ -168,7 +168,7 @@ - (void)animateDemo3Constraints
                          self.demo3BlueBottomInset.constant = -10.0f;
                          self.demo3BlueRightInset.constant = -50.0f;
                          self.demo3RedSizeConstraint.constant = 10.0f;
-                         [self.demo3GreenPinConstraint remove];
+                         [self.demo3GreenPinConstraint autoRemove];
                          self.demo3GreenPinConstraint = [self.greenView autoPinEdge:ALEdgeRight toEdge:ALEdgeRight ofView:self.blueView];
                          [self.view layoutIfNeeded];
                      }
@@ -184,7 +184,7 @@ - (void)animateDemo3Constraints
                                               self.demo3BlueBottomInset.constant = -50.0f;
                                               self.demo3BlueRightInset.constant = -10.0f;
                                               self.demo3RedSizeConstraint.constant = -40.0f;
-                                              [self.demo3GreenPinConstraint remove];
+                                              [self.demo3GreenPinConstraint autoRemove];
                                               self.demo3GreenPinConstraint = [self.greenView autoPinEdge:ALEdgeRight toEdge:ALEdgeRight ofView:self.redView];
                                               [self.view layoutIfNeeded];
                                           }
@@ -241,7 +241,7 @@ - (void)setupDemo5
 
     NSArray *subviews = @[self.blueView, self.redView, self.yellowView, self.greenView, self.orangeView];
 
-    [self.containerView autoAlignSubviews:subviews toAxis:ALAxisVertical];
+    [subviews autoAlignViewsToAxis:ALAxisVertical];
 
     UIView *previousView = nil;
     for (UIView *view in subviews) {
@@ -301,7 +301,8 @@ - (void)setupConstraintsForCurrentDemo
         self.constraintDemo = ExampleConstraintDemo1;
     }
 
-    [self.containerView removeConstraintsAffectingViewAndSubviews];
+    // WARNING: Be sure to read the documentation on the below method - it can cause major performance issues!
+    [self.containerView autoRemoveConstraintsAffectingViewAndSubviews];
 
     [self.containerView autoPinToTopLayoutGuideOfViewController:self withInset:10.0f];
     [self.containerView autoPinToBottomLayoutGuideOfViewController:self withInset:10.0f];

diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 UIView+AutoLayout
 =================
 
-A carefully-crafted category on `UIView` (and a one-method category on `NSLayoutConstraint`) that provides a simpler interface for creating Auto Layout constraints.
+The ultimate API for creating Auto Layout constraints -- impressively simple, immensely powerful. Comprised of categories on `UIView`, `NSArray`, and `NSLayoutConstraint`.
 
-The goal is to provide a pleasant API for the vast majority of common Auto Layout use cases. It's designed for clarity and simplicity while simultaneously minimizing the amount of third party code. The API takes inspiration from the Auto Layout UI options available in Interface Builder.
+UIView+AutoLayout was designed to provide a developer-friendly interface for the vast majority of Auto Layout use cases. It's optimized for clarity and simplicity while simultaneously minimizing the amount of third party code. The API takes inspiration from the Auto Layout UI options available in Interface Builder, but delivers far more flexibility and capability.
 
 API Cheat Sheet
 ---------------
@@ -14,9 +14,9 @@ This is just a handy overview of the primary methods. Check out the [header file
 
 **UIView**
 
-*	\+ removeConstraint(s):
-*	\- removeConstraintsAffectingView
-*	\- removeConstraintsAffectingViewAndSubviews
+*	\+ autoRemoveConstraint(s):
+*	\- autoRemoveConstraintsAffectingView
+*	\- autoRemoveConstraintsAffectingViewAndSubviews
 *	\+ autoSetPriority:forConstraints:
 *	\- autoCenterInSuperview(AlongAxis:)
 *	\- autoPinCenterAxis:toPositionInSuperview:
@@ -30,18 +30,18 @@ This is just a handy overview of the primary methods. Check out the [header file
 *	\- autoPinToTopLayoutGuideOfViewController:withInset:
 *	\- autoPinToBottomLayoutGuideOfViewController:withInset:
 
-*Advanced methods that layout an array of subviews:*
+**NSArray**
 
-*	\- autoAlignSubviews:toEdge:
-*	\- autoAlignSubviews:toAxis:
-*	\- autoMatchSubviews:dimension:
-*	\- autoSetSubviews:dimension:toSize:
-*	\- autoDistributeSubviews:alongAxis:withFixedSpacing:alignment:
-*	\- autoDistributeSubviews:alongAxis:withFixedSize:alignment:
+*	\- autoAlignViewsToEdge:
+*	\- autoAlignViewsToAxis:
+*	\- autoMatchViewsDimension:
+*	\- autoSetViewsDimension:toSize:
+*	\- autoDistributeViewsAlongAxis:withFixedSpacing:alignment:
+*	\- autoDistributeViewsAlongAxis:withFixedSize:alignment:
 
 **NSLayoutConstraint**
 
-*	\- remove
+*	\- autoRemove
 
 Setup
 -----
@@ -116,4 +116,4 @@ I'm especially interested in hearing about any common use cases that this API do
 Credits
 -------
 
-Originally forked from Rich Turton's [jrturton/UIView-Autolayout](https://github.com/jrturton/UIView-Autolayout). Designed & maintained by Tyler Fox. Distributed with the MIT License.
+Originally forked from Rich Turton's [jrturton/UIView-Autolayout](https://github.com/jrturton/UIView-Autolayout). Designed & maintained by Tyler Fox. Distributed with the MIT license.
diff --git a/Source/UIView+AutoLayout.h b/Source/UIView+AutoLayout.h
@@ -32,7 +32,7 @@ typedef void(^ALConstraintsBlock)(void);    // a block of method calls to the UI
 #pragma mark - UIView+AutoLayout
 
 /**
- A category on UIView that provides a simpler interface for creating Auto Layout constraints.
+ A category on UIView that provides a simple yet powerful interface for creating Auto Layout constraints.
  */
 @interface UIView (AutoLayout)
 
@@ -54,30 +54,30 @@ typedef void(^ALConstraintsBlock)(void);    // a block of method calls to the UI
 
 
 /** Removes the given constraint from the view it has been added to. */
-+ (void)removeConstraint:(NSLayoutConstraint *)constraint;
++ (void)autoRemoveConstraint:(NSLayoutConstraint *)constraint;
 
 /** Removes the given constraints from the views they have been added to. */
-+ (void)removeConstraints:(NSArray *)constraints;
++ (void)autoRemoveConstraints:(NSArray *)constraints;
 
 /** Removes all explicit constraints that affect the view.
     WARNING: Apple's constraint solver is not optimized for large-scale constraint changes; you may encounter major performance issues after using this method.
     NOTE: This method preserves implicit constraints, such as intrinsic content size constraints, which you usually do not want to remove. */
-- (void)removeConstraintsAffectingView;
+- (void)autoRemoveConstraintsAffectingView;
 
 /** Removes all constraints that affect the view, optionally including implicit constraints.
     WARNING: Apple's constraint solver is not optimized for large-scale constraint changes; you may encounter major performance issues after using this method.
     NOTE: Implicit constraints are auto-generated lower priority constraints, and you usually do not want to remove these. */
-- (void)removeConstraintsAffectingViewIncludingImplicitConstraints:(BOOL)shouldRemoveImplicitConstraints;
+- (void)autoRemoveConstraintsAffectingViewIncludingImplicitConstraints:(BOOL)shouldRemoveImplicitConstraints;
 
 /** Recursively removes all explicit constraints that affect the view and its subviews.
     WARNING: Apple's constraint solver is not optimized for large-scale constraint changes; you may encounter major performance issues after using this method.
     NOTE: This method preserves implicit constraints, such as intrinsic content size constraints, which you usually do not want to remove. */
-- (void)removeConstraintsAffectingViewAndSubviews;
+- (void)autoRemoveConstraintsAffectingViewAndSubviews;
 
 /** Recursively removes all constraints from the view and its subviews, optionally including implicit constraints.
     WARNING: Apple's constraint solver is not optimized for large-scale constraint changes; you may encounter major performance issues after using this method.
     NOTE: Implicit constraints are auto-generated lower priority constraints, and you usually do not want to remove these. */
-- (void)removeConstraintsAffectingViewAndSubviewsIncludingImplicitConstraints:(BOOL)shouldRemoveImplicitConstraints;
+- (void)autoRemoveConstraintsAffectingViewAndSubviewsIncludingImplicitConstraints:(BOOL)shouldRemoveImplicitConstraints;
 
 
 /** Centers the view in its superview. */
@@ -153,27 +153,34 @@ typedef void(^ALConstraintsBlock)(void);    // a block of method calls to the UI
 /** Pins the bottom edge of the view to the bottom layout guide of the given view controller with an inset. */
 - (NSLayoutConstraint *)autoPinToBottomLayoutGuideOfViewController:(UIViewController *)viewController withInset:(CGFloat)inset;
 
+@end
+
+
+#pragma mark - NSArray+AutoLayout
 
-#pragma mark Advanced Auto Layout Methods
+/**
+ A category on NSArray that provides a simple yet powerful interface for applying constraints to groups of views.
+ */
+@interface NSArray (AutoLayout)
 
-/** Aligns subviews to one another along a given edge. */
-- (NSArray *)autoAlignSubviews:(NSArray *)views toEdge:(ALEdge)edge;
+/** Aligns views in this array to one another along a given edge. */
+- (NSArray *)autoAlignViewsToEdge:(ALEdge)edge;
 
-/** Aligns subviews to one another along a given axis. */
-- (NSArray *)autoAlignSubviews:(NSArray *)views toAxis:(ALAxis)axis;
+/** Aligns views in this array to one another along a given axis. */
+- (NSArray *)autoAlignViewsToAxis:(ALAxis)axis;
 
-/** Matches a given dimension of all the subviews. */
-- (NSArray *)autoMatchSubviews:(NSArray *)views dimension:(ALDimension)dimension;
+/** Matches a given dimension of all the views in this array. */
+- (NSArray *)autoMatchViewsDimension:(ALDimension)dimension;
 
-/** Sets the given dimension of all the subviews to a given size. */
-- (NSArray *)autoSetSubviews:(NSArray *)views dimension:(ALDimension)dimension toSize:(CGFloat)size;
+/** Sets the given dimension of all the views in this array to a given size. */
+- (NSArray *)autoSetViewsDimension:(ALDimension)dimension toSize:(CGFloat)size;
 
 
-/** Distributes the subviews equally along the selected axis. Views will be the same size (variable) in the dimension along the axis and will have spacing (fixed) between them. */
-- (NSArray *)autoDistributeSubviews:(NSArray *)views alongAxis:(ALAxis)axis withFixedSpacing:(CGFloat)spacing alignment:(NSLayoutFormatOptions)alignment;
+/** Distributes the views in this array equally along the selected axis. Views will be the same size (variable) in the dimension along the axis and will have spacing (fixed) between them. */
+- (NSArray *)autoDistributeViewsAlongAxis:(ALAxis)axis withFixedSpacing:(CGFloat)spacing alignment:(NSLayoutFormatOptions)alignment;
 
-/** Distributes the subviews equally along the selected axis. Views will be the same size (fixed) in the dimension along the axis and will have spacing (variable) between them. */
-- (NSArray *)autoDistributeSubviews:(NSArray *)views alongAxis:(ALAxis)axis withFixedSize:(CGFloat)size alignment:(NSLayoutFormatOptions)alignment;
+/** Distributes the views in this array equally along the selected axis. Views will be the same size (fixed) in the dimension along the axis and will have spacing (variable) between them. */
+- (NSArray *)autoDistributeViewsAlongAxis:(ALAxis)axis withFixedSize:(CGFloat)size alignment:(NSLayoutFormatOptions)alignment;
 
 @end
 
@@ -186,6 +193,6 @@ typedef void(^ALConstraintsBlock)(void);    // a block of method calls to the UI
 @interface NSLayoutConstraint (AutoLayout)
 
 /** Removes the constraint from the view it has been added to. */
-- (void)remove;
+- (void)autoRemove;
 
 @end