Some Cocoa Touch improvements can make developing apps easier
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
COSEigen
COSLayout
COSObserver
LICENSE
README.md

README.md

Introduction

CocoaSugar is an Objective-C library that can make developing apps easier. It includes a collection of runtime and Cocoa Touch improvements to solve some practical problem.

Documentation

COSLayout

COSLayout is yet another layout library. It's neither a wrapper nor a replacement for Auto Layout. It dose not handle circular references of constraints and constraint priority. Besides that, COSLayout can solve all layout cases. What's more, COSLayout provides some additional benefits: smaller memory footprint, better performance and more intuitive expression.

COSLayout is an abstraction of layout of view. With COSLayout, you can specify view's layout relative to it's superview, sibling views and non-sibling views. Following example specifies a 10-points constraint from view's bottom to superview's bottom:

UIView *view = [[UIView alloc] init];

COSLayout *layout = [COSLayout layoutOfView:view];

[layout addRule:@"bb = 10"];

In the example above, a rule has been added into layout by method addRule:. A rule is expressed in Sample Layout Language or "SLL", which can specify constraints intuitively. The syntax of SLL is very simple, just comma-separated assignment expressions. Each assignment expression specifies a constraint, l-value is constraint name, r-value is constraint value.

COSLayout supports 18 constraints:

Constraint Direction Description
w Horizontal View's width
h Vertical View's height
tt Vertical Space from view's top to superview's top
tb Vertical Space from view's top to superview's bottom
ll Horizontal Space from view's left to superview's left
lr Horizontal Space from view's left to superview's right
bb Vertical Space from view's bottom to superview's bottom
bt Vertical Space from view's bottom to superview's top
rr Horizontal Space from view's right to superview's right
rl Horizontal Space from view's right to superview's left
ct Vertical Space from view's center to superview's top
cl Horizontal Space from view's center to superview's left
cb Vertical Space from view's center to superview's bottom
cr Horizontal Space from view's center to superview's right
minw Horizontal Minimal width of view
maxw Horizontal Maximal width of view
minh Vertical Minimal height of view
maxh Vertical Maximal height of view

COSLayout supports 5 constraint value types:

Constraint Value Type Example Description
CGFloat 5 -10 20.0 Fixed length on screen
Percentage 5% -10% 20.0% Percentage of superview's width or height
Format specifier %tt %w %f Constraint value given by additional argument
Constraint tt maxw Constraint value of current layout
Nil nil Used to reset a constraint

Note that the percentage has different means for different constraint directions. If current constraint direction is horizontal, the percentage represents the percentage of superview's width, otherwise, the percentage of superview's height. You can also specify direction of percentage by H: (horizontal) or V: (vertical) prefix. For example, H:50% means 50% width of superview, V:30% means 30% height of superview.

Format specifier represents a constraint value given by additional argument. For example, %tt is the space from other view's top to superview's top. Here, the other view is given by additional argument, and the superview is the superview of layout's view. It means that COSLayout can specify constraints between non-sibling views.

COSLayout support 20 format specifiers:

Format Type Description
%tt UIView * Space from view's top to superview's top
%tb UIView * Space from view's top to superview's bottom
%ll UIView * Space from view's left to superview's left
%lr UIView * Space from view's left to superview's right
%bb UIView * Space from view's bottom to superview's bottom
%bt UIView * Space from view's bottom to superview's top
%rr UIView * Space from view's right to superview's right
%rl UIView * Space from view's right to superview's left
%ct UIView * Space from view's center to superview's top
%cl UIView * Space from view's center to superview's left
%cb UIView * Space from view's center to superview's bottom
%cr UIView * Space from view's center to superview's right
%w UIView * Width of view
%h UIView * Height of view
%f CGFloat Fixed length on screen
%p CGFloat Percentage of superview's width or superview's height
%^f CGFloat(^)(UIView *) Space provided by a block
%^p CGFloat(^)(UIView *) Percentage provided by a block
%@f id<COSCGFloatProtocol> Space provided by an object
%@p id<COSCGFloatProtocol> Percentage provided by an object

Like percentage constraint value, you can also use H: and V: prefix to specify direction of percentage. For example, H:%p, H:%^p, H:%@p means percentage is horizontal, V:%p, V:%^p, V:%@p means percentage is vertical.

It is worth mentioning that, format specifier also create a dependency between two views: the layout view and the other view given by additional argument. In COSLayout, the dependencies is presented by DAG. So COSLayout do not support the circular dependencies. When superview needs layout, all layouts of subviews will solve it's constraints according to the dependencies.

Constraint value expression

You can apply arithmetic operator between constraint values. Like other languages, SLL supports 5 basic arithmetic operators:

Operator name Priority Associativity Code examples
= 1 right tt = 20 ct = 50%
+= 1 right tt += 20 ct += 50%
-= 1 right tt -= 20 ct -= 50%
*= 1 right tt *= 20 ct *= 50%
/= 1 right tt /= 20 ct /= 50%
+ 2 left 10 + 20 50% + 10 %w + 5
- 2 left 20 - 10 50% - 10 %h - 5
* 3 left 50 * 2 80% * 0.5 %h * 2
/ 3 left 100 / 2 100% / 2 %h / 2

You can also use () to group sub-expression to change the evaluation order of expression.

Examples

In the following example, COSLayout aligns view's top-right corner to superview's top-right corner with 5-points space.

UIView *view = [[UIView alloc] init];

COSLayout *layout = [COSLayout layoutOfView:view];

[layout addRule:@"tt = rr = 5"];

In the following example, COSLayout aligns view's left/bottom/right to superview's left/bottom/right with 10-points space, and make the view's top aligned to superview's center.

UIView *view = [[UIView alloc] init];

COSLayout *layout = [COSLayout layoutOfView:view];

[layout addRule:@"ll = bb = rr = 10, tt = 50%"];

COSObserver

COSObserver is an improvement of KVO. Using COSObserver, you can use block for KVO notification. It eliminates some inconvenience of KVO. After making an observation by COSObserver, there's no need to remove observer manually, COSObserver can remove observer for target automatically when either observer or target is dealloced.

In the following example, observer is the observer for label1. Then, label2 is added to observer as target. When the text of label2 changed, observer observes this change immediately and call the block, which makes text of label1 the same as text of label2.

UILabel *label1 = [[UILabel alloc] init];
UILabel *label2 = [[UILabel alloc] init];

COSObserver *observer = [COSObserver observerForObject:label1];

[observer
 addTarget:label2
 forKeyPath:@"text"
 options:NSKeyValueObservingOptionNew
 block:^(id object, id target, NSDictionary *change) {
     [target setText:change[NSKeyValueChangeNewKey]];
 }];