Objective-C required us to wax philosophic about the nature of equality and identity. To the relief of any developer less inclined towards handwavy treatises, this is not as much the case for Swift.

In Swift, Equatable is a fundamental type, from which Comparable and Hashable are both derived. Together, these protocols form the central point of comparison throughout the language.

Equatable

Values of the Equatable type can be evaluated for equality and inequality. Declaring a type as equatable bestows several useful abilities, notably the ability values of that type to be found in a containing Array.

For a type to be Equatable, there must exist an implementation of the == operator function, which accepts a matching type:

func==(lhs:Self,rhs:Self)->Bool

For value types, equality is determined by evaluating the equality of each component property. As an example, consider a Complex type, which takes a generic type T, which conforms to SignedNumberType:

SignedNumberType is a convenient choice for a generic number type, as it inherits from both Comparable (and thus Equatable, as described in the section) and IntegerLiteralConvertible, which Int, Double, and Float all conform to.

structComplex<T:SignedNumberType>{letreal:Tletimaginary:T}

Since a complex number is comprised of a real and imaginary component, two complex numbers are equal if and only if their respective real and imaginary components are equal:

extensionComplex:Equatable{}// MARK: Equatablefunc==<T>(lhs:Complex<T>,rhs:Complex<T>)->Bool{returnlhs.real==rhs.real&&lhs.imaginary==rhs.imaginary}

The result:

leta=Complex<Double>(real:1.0,imaginary:2.0)letb=Complex<Double>(real:1.0,imaginary:2.0)a==b// truea!=b// false

As described in the article about Swift Default Protocol Implementations, an implementation of != is automatically derived from the provided == operator by the standard library.

For reference types, the equality becomes conflated with identity. It makes sense that two Name structs with the same values would be equal, but two Person objects can have the same name, but be different people.

For Objective-C-compatible object types, the == operator is already provided from the isEqual: method:

classObjCObject:NSObject{}ObjCObject()==ObjCObject()// false

For Swift reference types, equality can be evaluated as an identity check on an ObjectIdentifier constructed with an instance of that type:

classObject:Equatable{}// MARK: Equatablefunc==(lhs:Object,rhs:Object)->Bool{returnObjectIdentifier(lhs)==ObjectIdentifier(rhs)}Object()==Object()// false

Comparable

Building on Equatable, the Comparable protocol allows for more specific inequality, distinguishing cases where the left hand value is greater than or less than the right hand value.

Types conforming to the Comparable protocol provide the following operators:

func<=(lhs:Self,rhs:Self)->Boolfunc>(lhs:Self,rhs:Self)->Boolfunc>=(lhs:Self,rhs:Self)->Bool

What's interesting about this list, however, is not so much what is included, but rather what's missing.

The first and perhaps most noticeable omission is ==, since >= is a logical disjunction of > and == comparisons. As a way of reconciling this, Comparable inherits from Equatable, which provides ==.

The second omission is a bit more subtle, and is actually the key to understanding what's going on here: <. What happened to the "less than" operator? It's defined by the _Comparable protocol. Why is this significant? As described in the article about Swift Default Protocol Implementations, the Swift Standard Library provides a default implementation of the Comparable protocol based entirely on the existential type _Comparable. This is actually really clever. Since the implementations of all of the comparison functions can be derived from just < and ==, all of that functionality is made available automatically through type inference.

Contrast this with, for example, how Ruby derives equality and comparison operators from a single operator, <=> (a.k.a the "UFO operator"). Here's how this could be implemented in Swift.

As a more complex example, consider a CSSSelector struct, which implements cascade ordering of selectors:

importFoundationstructCSSSelector{letselector:StringstructSpecificity{letid:Intlet`class`:Intletelement:Intinit(_components:[String]){var(id,`class`,element)=(0,0,0)fortokenincomponents{iftoken.hasPrefix("#"){id++}elseiftoken.hasPrefix("."){`class`++}else{element++}}self.id=idself.`class`=`class`self.element=element}}letspecificity:Specificityinit(_string:String){self.selector=string// Naïve tokenization, ignoring operators, pseudo-selectors, and `style=`.letcomponents:[String]=self.selector.componentsSeparatedByCharactersInSet(NSCharacterSet.whitespaceCharacterSet())self.specificity=Specificity(components)}}

Where as CSS selectors are evaluated by specificity rank and order, two selectors are only really equal if they resolve to the same elements:

extensionCSSSelector:Equatable{}// MARK: Equatablefunc==(lhs:CSSSelector,rhs:CSSSelector)->Bool{// Naïve equality that uses string comparison rather than resolving equivalent selectorsreturnlhs.selector==rhs.selector}

Instead, selectors are actually compared in terms of their specificity:

extensionCSSSelector.Specificity:Comparable{}// MARK: Comparablefunc<(lhs:CSSSelector.Specificity,rhs:CSSSelector.Specificity)->Bool{returnlhs.id<rhs.id||lhs.`class`<rhs.`class`||lhs.element<rhs.element}// MARK: Equatablefunc==(lhs:CSSSelector.Specificity,rhs:CSSSelector.Specificity)->Bool{returnlhs.id==rhs.id&&lhs.`class`==rhs.`class`&&lhs.element==rhs.element}

Bringing everything together:

For clarity, assume CSSSelectorconforms to StringLiteralConvertible.

leta:CSSSelector="#logo"letb:CSSSelector="html body #logo"letc:CSSSelector="body div #logo"letd:CSSSelector=".container #logo"b==c// falseb.specificity==c.specificity// truec.specificity<a.specificity// falsed.specificity>c.specificity// true

Hashable

Another important protocol derived from Equatable is Hashable.

Only Hashable types can be stored as the key of a Swift Dictionary:

structDictionary<Key:Hashable,Value>:CollectionType,DictionaryLiteralConvertible{...}

For a type to conform to Hashable,it must provide a getter for the hashValue property.

protocolHashable:Equatable{/// Returns the hash value.  The hash value is not guaranteed to be stable/// across different invocations of the same program.  Do not persist the hash/// value across program runs.////// The value of `hashValue` property must be consistent with the equality/// comparison: if two values compare equal, they must have equal hash/// values.varhashValue:Int{get}}

Determining the optimal hashing value is way outside the scope of this article. Fortunately, most values can derive an adequate hash value from an XOR of the hash values of its component properties.

The following built-in Swift types implement hashValue:

• Double
• Float, Float80
• Int, Int8, Int16, Int32, Int64
• UInt, UInt8, UInt16, UInt32, UInt64
• String
• UnicodeScalar
• ObjectIdentifier

Based on this, here's how a struct representing Binomial Nomenclature in Biological Taxonomy:

structBinomen{letgenus:Stringletspecies:String}// MARK: HashableextensionBinomen:Hashable{varhashValue:Int{returngenus.hashValue^species.hashValue}}// MARK: Equatablefunc==(lhs:Binomen,rhs:Binomen)->Bool{returnlhs.genus==rhs.genus&&rhs.species==rhs.species}

Being able to hash this type makes it possible to key common name to the "Latin name":

varcommonNames:[Binomen:String]=[:]commonNames[Binomen(genus:"Canis",species:"lupis")]="Grey Wolf"commonNames[Binomen(genus:"Canis",species:"rufus")]="Red Wolf"commonNames[Binomen(genus:"Canis",species:"latrans")]="Coyote"commonNames[Binomen(genus:"Canis",species:"aureus")]="Golden Jackal"

Did you know that UIAlertView and UIActionSheet (as well as their respective delegate protocols) are deprecated in iOS 8?

It's true. ⌘-click on UIAlertView or UIActionSheet in your code, and check out the top-level comment:

UIAlertView is deprecated. Use UIAlertController with a preferredStyle of UIAlertControllerStyleAlert instead.

Wondering why Xcode didn't alert you to this change? Just read down to the next line:

@availability(iOS,introduced=2.0)

Although these classes are technically deprecated, this is not communicated in the @availability attribute. This should be of little surprise, though; UIAlertView has always played it fast and loose.

From its very inception, UIAlertView has been laden with vulgar concessions, sacrificing formality and correctness for the whims of an eager developer audience. Its delegate protocol conformance was commented out of its initializer (delegate:(id /* <UIAlertViewDelegate */)delegate). And what protocol methods that could be implemented invoked the cringeworthy notion of having "clicked" rather than "tapped" a buttonAtIndex:. This, and trailing variable-length arguments for otherButtonTitles, awkward management of button indexes, a -show method with no regard for the view hierarchy... the list goes on.

UIActionSheet was nearly as bad, though developers can't be bothered to remember what the heck that control is called half the time, much less complain about its awkward parts.

As such, the introduction of UIAlertController should be met like an army liberating a city from occupation. Not only does it improve on the miserable APIs of its predecessors, but it carves a path forward to deal with the UIKit interface singularity brought on by the latest class of devices.

This week's article takes a look at UIAlertController, showing first how to port existing alert behavior, and then how this behavior can be extended.

UIAlertController replaces both UIAlertView and UIActionSheet, thereby unifying the concept of alerts across the system, whether presented modally or in a popover.

Unlike the classes it replaces, UIAlertController is a subclass of UIViewController. As such, alerts now benefit from the configurable functionality provided with view controller presentation.

UIAlertController is initialized with a title, message, and whether it prefers to be displayed as an alert or action sheet. Alert views are presented modally in the center of their presenting view controllers, whereas action sheets are anchored to the bottom. Alerts can have both buttons and text fields, while action sheets only support buttons.

Rather than specifying all of an alert's buttons in an initializer, instances of a new class, UIAlertAction, are added after the fact. Refactoring the API in this way allows for greater control over the number, type, and order of buttons. It also does away with the delegate pattern favored by UIAlertView& UIActionSheet in favor or much more convenient completion handlers.

Comparing the Old and New Ways to Alerts

A Standard Alert

The Old Way: UIAlertView

letalertView=UIAlertView(title:"Default Style",message:"A standard alert.",delegate:self,cancelButtonTitle:"Cancel",otherButtonTitles:"OK")alertView.alertViewStyle=.DefaultalertView.show()

// MARK: UIAlertViewDelegatefuncalertView(alertView:UIAlertView,clickedButtonAtIndexbuttonIndex:Int){switchbuttonIndex{// ...}}

The New Way: UIAlertController

letalertController=UIAlertController(title:"Default Style",message:"A standard alert.",preferredStyle:.Alert)letcancelAction=UIAlertAction(title:"Cancel",style:.Cancel){(action)in// ...}alertController.addAction(cancelAction)letdestroyAction=UIAlertAction(title:"Destroy",style:.Destructive){(action)inprintln(action)}alertController.addAction(destroyAction)letOKAction=UIAlertAction(title:"OK",style:.Default){(action)in// ...}alertController.addAction(OKAction)self.presentViewController(alertController,animated:true){// ...}

A Standard Action Sheet

UIActionSheet

letactionSheet=UIActionSheet(title:"Takes the appearance of the bottom bar if specified; otherwise, same as UIActionSheetStyleDefault.",delegate:self,cancelButtonTitle:"Cancel",destructiveButtonTitle:"Destroy",otherButtonTitles:"OK")actionSheet.actionSheetStyle=.DefaultactionSheet.showInView(self.view)

// MARK: UIActionSheetDelegatefuncactionSheet(actionSheet:UIActionSheet,clickedButtonAtIndexbuttonIndex:Int){switchbuttonIndex{...}}

UIAlertController

letalertController=UIAlertController(title:nil,message:"Takes the appearance of the bottom bar if specified; otherwise, same as UIActionSheetStyleDefault.",preferredStyle:.ActionSheet)letcancelAction=UIAlertAction(title:"Cancel",style:.Cancel){(action)in// ...}alertController.addAction(cancelAction)letOKAction=UIAlertAction(title:"OK",style:.Default){(action)in// ...}alertController.addAction(OKAction)self.presentViewController(alertController,animated:true){// ...}

New Functionality

UIAlertController is not just a cleanup of pre-existing APIs, it's a generalization of them. Previously, one was constrained to whatever presets were provided (swizzling in additional functionality at their own risk). With UIAlertController, it's possible to do a lot more out-of-the-box:

Alert with Destructive Button

The type of an action is specified UIAlertActionStyle has three values:

• .Default: Apply the default style to the action’s button.
• .Cancel: Apply a style that indicates the action cancels the operation and leaves things unchanged.
• .Destructive: Apply a style that indicates the action might change or delete data.

So, to add a destructive action to a modal alert, just add a UIAlertAction with style .Destructive:

letalertController=UIAlertController(title:"Title",message:"Message",preferredStyle:.Alert)letcancelAction=UIAlertAction(title:"Cancel",style:.Cancel){(action)inprintln(action)}alertController.addAction(cancelAction)letdestroyAction=UIAlertAction(title:"Destroy",style:.Destructive){(action)inprintln(action)}alertController.addAction(destroyAction)self.presentViewController(alertController,animated:true){// ...}

Alert with >2 Buttons

With one or two actions, buttons in an alert are stacked horizontally. Any more than that, though, and it takes on a display characteristic closer to an action sheet:

letoneAction=UIAlertAction(title:"One",style:.Default){(_)in}lettwoAction=UIAlertAction(title:"Two",style:.Default){(_)in}letthreeAction=UIAlertAction(title:"Three",style:.Default){(_)in}letcancelAction=UIAlertAction(title:"Cancel",style:.Cancel){(_)in}alertController.addAction(oneAction)alertController.addAction(twoAction)alertController.addAction(threeAction)alertController.addAction(cancelAction)

Creating a Login Form

iOS 5 added the alertViewStyle property to UIAlertView, which exposed much sought-after private APIs that allowed login and password fields to be displayed in an alert, as seen in several built-in system apps.

In iOS 8, UIAlertController can add text fields with the addTextFieldWithConfigurationHandler method:

letloginAction=UIAlertAction(title:"Login",style:.Default){(_)inletloginTextField=alertController.textFields![0]asUITextFieldletpasswordTextField=alertController.textFields![1]asUITextFieldlogin(loginTextField.text,passwordTextField.text)}loginAction.enabled=falseletforgotPasswordAction=UIAlertAction(title:"Forgot Password",style:.Destructive){(_)in}letcancelAction=UIAlertAction(title:"Cancel",style:.Cancel){(_)in}alertController.addTextFieldWithConfigurationHandler{(textField)intextField.placeholder="Login"NSNotificationCenter.defaultCenter().addObserverForName(UITextFieldTextDidChangeNotification,object:textField,queue:NSOperationQueue.mainQueue()){(notification)inloginAction.enabled=textField.text!=""}}alertController.addTextFieldWithConfigurationHandler{(textField)intextField.placeholder="Password"textField.secureTextEntry=true}alertController.addAction(loginAction)alertController.addAction(forgotPasswordAction)alertController.addAction(cancelAction)

Creating a Sign Up Form

UIAlertController goes even further to allow any number of text fields, each with the ability to be configured and customized as necessary. This makes it possible to create a fully-functional signup form in a single modal alert:

alertController.addTextFieldWithConfigurationHandler{(textField)intextField.placeholder="Email"textField.keyboardType=.EmailAddress}alertController.addTextFieldWithConfigurationHandler{(textField)intextField.placeholder="Password"textField.secureTextEntry=true}alertController.addTextFieldWithConfigurationHandler{(textField)intextField.placeholder="Password Confirmation"textField.secureTextEntry=true}

Though, it must be said, caveat implementor. Just because you can implement a signup form in an alert doesn't mean you should. Suck it up and use a view controller, like you're supposed to.

Caveats

Attempting to add a text field to an alert controller with style .ActionSheet will throw the following exception:

Terminating app due to uncaught exception NSInternalInconsistencyException, reason: 'Text fields can only be added to an alert controller of style UIAlertControllerStyleAlert'

Likewise, attempting to add more than one .Cancel action to either an alert or action sheet will raise:

Terminating app due to uncaught exception NSInternalInconsistencyException, reason: 'UIAlertController can only have one action with a style of UIAlertActionStyleCancel'

While it's not accurate to say that Swift is "Objective-C without the C", it's for lack of resemblance to Objective-C, not the absence of C. Swift is vehementlynot C.

Swift certainly draws inspiration from Haskell, Rust, Python, D, and other modern languages, but one can perhaps best understand the language as a rejection of everything that's broken in C:

• C is unsafe by default. Swift is safe by default (hence the unsafe naming of pointer manipulation functions).
• C has undefined behavior. Swift has well-defined behavior(or at least theoretically; the compiler tools still have some catching up to do).
• C uses preprocessor directives capable of unspeakable evil. Swift has a safe subset of preprocessor directives.

One could go as far to say that Swift's type system was specifically designed out of spite for C++.

In Objective-C, checking for the availability of an API was accomplished through a combination of C preprocessor directives, conditionals on class, respondsToSelector:, and instancesRespondToSelector::

#if defined(__IPHONE_OS_VERSION_MAX_ALLOWED) && __IPHONE_OS_VERSION_MAX_ALLOWED >= 70000if([NSURLSessionclass]&&[NSURLSessionConfigurationrespondsToSelector:@selector(backgroundSessionConfigurationWithIdentifier:)]){// ...}#endif

However, as noted previously, Swift's compiler directives are extremely constrained, allowing only for compiler flags and conditional compilation against specific operating systems and architectures:

#if DEBUGprintln("OTHER_SWIFT_FLAGS = -D DEBUG")#endif

#if os(iOS)varimage:UIImage?#elseif os(OSX)varimage:NSImage?#endif

Unfortunately, os() does not offer any insight into the specific version of OS X or iOS, which means that checks must be made at runtime. And with Swift's less-forgiving treatment of nil, checking for constants Objective-C-style results in a crash.

So how do you check the system version in Swift to determine API availability? Read on to find out.

NSProcessInfo

Anticipating the need for a Swift-friendly API for determining API version at runtime, iOS 8 introduces the operatingSystemVersion property and isOperatingSystemAtLeastVersion method on NSProcessInfo. Both APIs use a new NSOperatingSystemVersion value type, which contains the majorVersion, minorVersion, and patchVersion.

Apple software releases follow semantic versioning conventions.

isOperatingSystemAtLeastVersion

For a simple check, like "is this app running on iOS 8?", isOperatingSystemAtLeastVersion is the most straightforward approach.

ifNSProcessInfo().isOperatingSystemAtLeastVersion(NSOperatingSystemVersion(majorVersion:8,minorVersion:0,patchVersion:0)){println("iOS >= 8.0.0")}

operatingSystemVersion

For more involved version comparison, the operatingSystemVersion can be inspected directly. Combine this with Swift pattern matching and switch statements for syntactic concision:

letos=NSProcessInfo().operatingSystemVersionswitch(os.majorVersion,os.minorVersion,os.patchVersion){case(8,_,_):println("iOS >= 8.0.0")case(7,0,_):println("iOS >= 7.0.0, < 7.1.0")case(7,_,_):println("iOS >= 7.1.0, < 8.0.0")default:println("iOS < 7.0.0")}

UIDevice systemVersion

Ironically, the new NSProcessInfo APIs aren't especially useful at the time of writing, since they're unavailable for iOS 7.

As an alternative, one can use the systemVersion property UIDevice:

switchUIDevice.currentDevice().systemVersion.compare("8.0.0",options:NSStringCompareOptions.NumericSearch){case.OrderedSame,.OrderedDescending:println("iOS >= 8.0")case.OrderedAscending:println("iOS < 8.0")}

Use NSStringCompareOptions.NumericSearch when comparing version number strings to ensure that, for example, "2.5" < "2.10".

String comparison and NSComparisonResult aren't as sexy as a dedicated value type like NSOperatingSystemVersion, but it gets the job done all the same.

NSAppKitVersionNumber

Another approach to determining API availability is to check framework version numbers. Unfortunately, Foundation's NSFoundationVersionNumber and Core Foundation's kCFCoreFoundationVersionNumber have historically been out of date, missing constants for past OS releases.

This is a dead-end for iOS, but OS X can pretty reliably check against the version of AppKit, with NSAppKitVersionNumber:

ifrint(NSAppKitVersionNumber)>NSAppKitVersionNumber10_9{println("OS X >= 10.10")}

Apple uses rint in sample code to round off version numbers for NSAppKitVersionNumber comparison.

To summarize, here's what you need to know about checking the system version in Swift:

• Use #if os(iOS) preprocessor directives to distinguish between iOS (UIKit) and OS X (AppKit) targets.
• For minimum deployment targets of iOS 8.0 or above, use NSProcessInfooperatingSystemVersion or isOperatingSystemAtLeastVersion.
• For minimum deployment targets of iOS 7.1 or below, use compare with NSStringCompareOptions.NumericSearch on UIDevicesystemVersion.
• For OS X deployment targets, compare NSAppKitVersionNumber against available AppKit constants.

In many ways, the story of Apple has been about fusing together technologies through happy accidents of history to create something better than before: OS X as a hybrid of MacOS & NeXTSTEP. Objective-C as the combination of Smalltalk's OOP paradigm and C. iCloud as the byproduct of MobileMe and actual clouds (presumably).

While this is true for many aspects of Apple's technology stack, inter-process communication is a flagrant counter-example.

Rather than taking the best of what was available at each juncture, solutions just kinda piled up. As a result, a handful of overlapping, mutually-incompatible IPC technologies are scattered across various abstraction layers. footnote:[Whereas all of these are available on OS X, only Grand Central Dispatch and Pasteboard (albeit to a lesser extent) can be used on iOS.]

• Mach Ports
• Distributed Notifications
• Distributed Objects
• AppleEvents & AppleScript
• Pasteboard
• XPC

Ranging from low-level kernel abstractions to high-level, object-oriented APIs, they each have particular performance and security characteristics. But fundamentally, they're all mechanisms for transmitting and receiving data from beyond a context boundary.

Mach Ports

All inter-process communication ultimately relies on functionality provided by Mach kernel APIs.

Mach ports are light-weight and powerful, but poorly documented footnote:[How poorly documented? The most up-to-date authoritative resource was a Mach 3.0 PostScript file circa 1990 tucked away on a Carnegie Mellon University FTP server.] and inconvenient to use directly. footnote:[How inconvenient? Well, just look at the code samples.]

Sending a message over a given Mach port comes down to a single mach_msg_send call, but it takes a bit of configuration in order to build the message to be sent:

natural_tdata;mach_port_tport;struct{mach_msg_header_theader;mach_msg_body_tbody;mach_msg_type_descriptor_ttype;}message;message.header=(mach_msg_header_t){.msgh_remote_port=port,.msgh_local_port=MACH_PORT_NULL,.msgh_bits=MACH_MSGH_BITS(MACH_MSG_TYPE_COPY_SEND,0),.msgh_size=sizeof(message)};message.body=(mach_msg_body_t){.msgh_descriptor_count=1};message.type=(mach_msg_type_descriptor_t){.pad1=data,.pad2=sizeof(data)};mach_msg_return_terror=mach_msg_send(&message.header);if(error==MACH_MSG_SUCCESS){// ...}

Things are a little easier on the receiving end, since the message only needs to be declared, not initialized:

mach_port_tport;struct{mach_msg_header_theader;mach_msg_body_tbody;mach_msg_type_descriptor_ttype;mach_msg_trailer_ttrailer;}message;mach_msg_return_terror=mach_msg_receive(&message.header);if(error==MACH_MSG_SUCCESS){natural_tdata=message.type.pad1;// ...}

Fortunately, higher-level APIs for Mach ports are provided by Core Foundation and Foundation. CFMachPort / NSMachPort are wrappers on top of the kernel APIs that can be used as a runloop source, while CFMessagePort / NSMessagePort facilitate synchronous communication between two ports.

CFMessagePort is actually quite nice for simple one-to-one communication. In just a few lines of code, a local named port can be attached as a runloop source to have a callback run each time a message is received:

staticCFDataRefCallback(CFMessagePortRefport,SInt32messageID,CFDataRefdata,void*info){// ...}CFMessagePortReflocalPort=CFMessagePortCreateLocal(nil,CFSTR("com.example.app.port.server"),Callback,nil,nil);CFRunLoopSourceRefrunLoopSource=CFMessagePortCreateRunLoopSource(nil,localPort,0);CFRunLoopAddSource(CFRunLoopGetCurrent(),runLoopSource,kCFRunLoopCommonModes);

Sending data is straightforward as well. Just specify the remote port, the message payload, and timeouts for sending and receiving. CFMessagePortSendRequest takes care of the rest:

CFDataRefdata;SInt32messageID=0x1111;// ArbitraryCFTimeIntervaltimeout=10.0;CFMessagePortRefremotePort=CFMessagePortCreateRemote(nil,CFSTR("com.example.app.port.client"));SInt32status=CFMessagePortSendRequest(remotePort,messageID,data,timeout,timeout,NULL,NULL);if(status==kCFMessagePortSuccess){// ...}

Distributed Notifications

There are many ways for objects to communicate with one another in Cocoa:

There is, of course, sending a message directly. There are also the target-action, delegate, and callbacks, which are all loosely-coupled, one-to-one design patterns. KVO allows for multiple objects to subscribe to events, but it strongly couples those objects together. Notifications, on the other hand, allow messages to be broadcast globally, and intercepted by any object that knows what to listen for. footnote:[It's pretty astonishing just how many notifications are fired off during the lifecycle of an application. Try adding NSNotificationCenter -addObserverForName:object:queue:usingBlock with nil values for name and object just as an application launches, and see just how many times that block fires.]

Each application manages its own NSNotificationCenter instance for infra-application pub-sub. But there is also a lesser-known Core Foundation API, CFNotificationCenterGetDistributedCenter that allows notifications to be communicated system-wide as well.

To listen for notifications, add an observer to the distributed notification center by specifying the notification name to listen for, and a function pointer to execute each time a notification is received:

staticvoidCallback(CFNotificationCenterRefcenter,void*observer,CFStringRefname,constvoid*object,CFDictionaryRefuserInfo){// ...}CFNotificationCenterRefdistributedCenter=CFNotificationCenterGetDistributedCenter();CFNotificationSuspensionBehaviorbehavior=CFNotificationSuspensionBehaviorDeliverImmediately;CFNotificationCenterAddObserver(distributedCenter,NULL,Callback,CFSTR("notification.identifier"),NULL,behavior);

Sending a distributed notification is even simpler; just post the identifier, object, and user info:

void*object;CFDictionaryRefuserInfo;CFNotificationCenterRefdistributedCenter=CFNotificationCenterGetDistributedCenter();CFNotificationCenterPostNotification(distributedCenter,CFSTR("notification.identifier"),object,userInfo,true);

Of all of the ways to link up two applications, distributed notifications are by far the easiest. It wouldn't be a great idea to use them to send large payloads, but for simple tasks like synchronizing preferences or triggering a data fetch, distributed notifications are perfect.

Distributed Objects

Distributed Objects (DO) is a remote messaging feature of Cocoa that had its heyday back in the mid-90's with NeXT. And though its not widely used any more, the dream of totally frictionless IPC is still unrealized in our modern technology stack.

Vending an object with DO is just a matter of setting up an NSConnection and registering it with a particular name:

@protocolProtocol;

id<Protocol>vendedObject;NSConnection*connection=[[NSConnectionalloc]init];[connectionsetRootObject:vendedObject];[connectionregisterName:@"server"];

Another application would then create a connection registered for that same registered name, and immediately get an atomic proxy that functioned as if it were that original object:

idproxy=[NSConnectionrootProxyForConnectionWithRegisteredName:@"server"host:nil];[proxysetProtocolForProxy:@protocol(Protocol)];

Any time a distributed object proxy is messaged, a Remote Procedure Call (RPC) would be made over the NSConnection to evaluate the message against the vended object and return the result back to the proxy. footnote:[Behind the scenes, a shared NSPortNameServer instance managed by the operating system was responsible for hooking up named connections.]

Distributed Objects are simple, transparent, and robust. And they would have been a flagpole feature of Cocoa had any of it worked as advertised.

In reality, Distributed Objects can't be used like local objects, if only because any message sent to a proxy could result in an exception being thrown. Unlike other languages, Objective-C doesn't use exceptions for control flow. As a result, wrapping everything in a @try/@catch is a poor fit to the conventions of Cocoa.

DO is awkward for other reasons, too. The divide between objects and primitives is especially pronounced when attempting to marshal values across a connection. Also, connections are totally unencrypted, and the lack of extensibility for the underlying communication channels makes it a deal-breaker for most serious usage.

All that's really left are traces of the annotations used by Distributed Objects to specify the proxying behavior of properties and method parameters:

• in: Argument is used as input, but not referenced later
• out: Argument is used to return a value by reference
• inout: Argument is used as input and returned by reference
• const: Argument is constant
• oneway: Return without blocking for result
• bycopy: Return a copy of the object
• byref: Return a proxy of the object

AppleEvents & AppleScript

AppleEvents are the most enduring legacies of the classic Macintosh operating system. Introduced in System 7, AppleEvents allowed apps to be controlled locally using AppleScript, or remotely using a feature called Program Linking. To this day, AppleScript, using the Cocoa Scripting Bridge, remains the most direct way to programmatically interact with OS X applications. footnote:[Mac OS's Apple Event Manager provided the initial low-level transport mechanism for AppleEvents, but was reimplemented on top of Mach ports for OS X.]

That said, it's easily one of the weirdest technologies to work with.

AppleScript uses a natural language syntax, intended to be more accessible to non-programmers. And while it does succeed in communicating intent in a human-understandable way, it's a nightmare to write.

To get a better sense of the nature of the beast, here's how to tell Safari to open a URL in the active tab in the frontmost window:

tellapplication"Safari"settheURLofthefrontdocumentto"http://nshipster.com"endtell

In many ways, AppleScript's natural language syntax is more of a liability than an asset. English, much like any other spoken language, has a great deal of redundancy and ambiguity built into normal constructions. While this is perfectly acceptable for humans, computers have a tough time resolving all of this.

Even for a seasoned Objective-C developer, it's nearly impossible to write AppleScript without constantly referencing documentation or sample code.

Fortunately, the Scripting Bridge provides a proper programming interface for Cocoa applications.

Cocoa Scripting Bridge

In order to interact with an application through the Scripting Bridge, a programming interface must first be generated:

$ sdef /Applications/Safari.app | sdp -fh --basename Safari

sdef generates scripting definition files for an application. These files can then be piped into sdp to be converted into another format—in this case, a C header. The resulting .h file can then be added and #import-ed into a project to get a first-class object interface to that application.

Here's the same example as before, expressed using the Cocoa Scripting Bridge:

#import "Safari.h"SafariApplication*safari=[SBApplicationapplicationWithBundleIdentifier:@"com.apple.Safari"];for(SafariWindow*windowinsafari.windows){if(window.visible){window.currentTab.URL=[NSURLURLWithString:@"http://nshipster.com"];break;}}

It's a bit more verbose than AppleScript, but this is much easier to integrate into an existing codebase. It's also a lot clearer to understand how this same code could be adapted to slightly different behavior (though that could just be the effect of being more familiar with Objective-C).

Alas, AppleScript's star appears to be falling, as recent releases of OS X and iWork applications have greatly curtailed their scriptability. At this point, it's unlikely that adding support in your own applications will be worth it.

Pasteboard

Pasteboard is the most visible inter-process communication mechanism on OS X and iOS. Whenever a user copies or pastes a piece of text, an image, or a document between applications, an exchange of data from one process to another over mach ports is being mediated by the com.apple.pboard service.

On OS X there's NSPasteboard, and on iOS there's UIPasteboard. They're pretty much the same, although like most counterparts, iOS provides a cleaner, more modern set of APIs that are slightly less capable than what's found on OS X.

Programmatically writing to the Pasteboard is nearly as simple as invoking Edit > Copy in a GUI application:

NSImage*image;NSPasteboard*pasteboard=[NSPasteboardgeneralPasteboard];[pasteboardclearContents];[pasteboardwriteObjects:@[image]];

The reciprocal paste action is a bit more involved, requiring an iteration over the Pasteboard contents:

NSPasteboard*pasteboard=[NSPasteboardgeneralPasteboard];if([pasteboardcanReadObjectForClasses:@[[NSImageclass]]options:nil]){NSArray*contents=[pasteboardreadObjectsForClasses:@[[NSImageclass]]options:nil];NSImage*image=[contentsfirstObject];}

What makes Pasteboard especially compelling as a mechanism for transferring data is the notion of simultaneously providing multiple representations of content copied onto a pasteboard. For example, a selection of text may be copied as both rich text (RTF) and plain text (TXT), allowing, for example, a WYSIWYG editor to preserve style information by grabbing the rich text representation, and a code editor to use just the plain text representation.

These representations can even be provided on an on-demand basis by conforming to the NSPasteboardItemDataProvider protocol. This allows derivative representations, such as plain text from rich text, to be generated only as necessary.

Each representation is identified by a Unique Type Identifier (UTI), a concept discussed in greater detail in the next chapter.

XPC

XPC is the state-of-the-art for inter-process communication in the SDKs. Its architectural goals are to avoid long-running process, to adapt to the available resources, and to lazily initialize wherever possible. The motivation to incorporate XPC into an application is not to do things that are otherwise impossible, but to provide better privilege separation and fault isolation for inter-process communication.

It's a replacement for NSTask, and a whole lot more.

Introduced in 2011, XPC has provided the infrastructure for the App Sandbox on OS X, Remote View Controllers on iOS, and App Extensions on both. It is also widely used by system frameworks and first-party applications:

$ find /Applications -name \*.xpc

By surveying the inventory of XPC services in the wild, one can get a much better understanding of opportunities to use XPC in their own application. Common themes in applications emerge, like services for image and video conversion, system calls, webservice integration, and 3rd party authentication.

XPC takes responsibility for both inter-process communication and service lifecycle management. Everything from registering a service, getting it running, and communicating with other services is handled by launchd. An XPC service can be launched on demand, or restarted if they crash, or terminated if they idle. As such, services should be designed to be completely stateless, so as to allow for sudden termination at any point of execution.

As part of the new security model adopted by iOS and backported in OS X, XPC services are run with the most restricted environment possible by default: no file system access, no network access, and no root privilege escalation. Any capabilities must be whitelisted by a set of entitlements.

XPC can be accessed through either the libxpc C API, or the NSXPCConnection Objective-C API. footnote:[Though one should always try to use the highest-level API available to accomplish a particular task, this book does have the words "Low-Level" in the title, so the examples in this section will use libxpc.]

XPC services either reside within an application bundle or are advertised to run in the background using launchd.

Services call xpc_main with an event handler to receive new XPC connections:

staticvoidconnection_handler(xpc_connection_tpeer){xpc_connection_set_event_handler(peer,^(xpc_object_tevent){peer_event_handler(peer,event);});xpc_connection_resume(peer);}intmain(intargc,constchar*argv[]){xpc_main(connection_handler);exit(EXIT_FAILURE);}

Each XPC connection is one-to-one, meaning that the service operates on distinct connections, with each call to xpc_connection_create creating a new peer. footnote:[This is similar to accept in the BSD sockets API, in that the server listens on a single file descriptor that creates additional descriptors for each inbound connection.] :

xpc_connection_tc=xpc_connection_create("com.example.service",NULL);xpc_connection_set_event_handler(c,^(xpc_object_tevent){// ...});xpc_connection_resume(c);

When a message is sent over an XPC connection, it is automatically dispatched onto a queue managed by the runtime. As soon as the connection is opened on the remote end, messages are dequeued and sent.

Each message is a dictionary, with string keys and strongly-typed values:

xpc_dictionary_tmessage=xpc_dictionary_create(NULL,NULL,0);xpc_dictionary_set_uint64(message,"foo",1);xpc_connection_send_message(c,message);xpc_release(message)

XPC objects operate on the following primitive types:

• Data
• Boolean
• Double
• String
• Signed Integer
• Unsigned Integer
• Date
• UUID
• Array
• Dictionary
• Null

XPC offers a convenient way to convert from the dispatch_data_t data type, which simplifies the workflow from GCD to XPC:

void*buffer;size_tlength;dispatch_data_tddata=dispatch_data_create(buffer,length,DISPATCH_TARGET_QUEUE_DEFAULT,DISPATCH_DATA_DESTRUCTOR_MUNMAP);xpc_object_txdata=xpc_data_create_with_dispatch_data(ddata);

dispatch_queue_tqueue;xpc_connection_send_message_with_reply(c,message,queue,^(xpc_object_treply){if(xpc_get_type(event)==XPC_TYPE_DICTIONARY){// ...}});

Registering Services

XPC can also be registered as launchd jobs, configured to automatically start on matching IOKit events, BSD notifications or CFDistributedNotifications. These criteria are specified in a service's launchd.plist file:

.launchd.plist

<key>LaunchEvents</key><dict><key>com.apple.iokit.matching</key><dict><key>com.example.device-attach</key><dict><key>idProduct</key><integer>2794</integer><key>idVendor</key><integer>725</integer><key>IOProviderClass</key><string>IOUSBDevice</string><key>IOMatchLaunchStream</key><true/><key>ProcessType</key><string>Adaptive</string></dict></dict></dict>

A recent addition to launchd property lists is the ProcessType key, which describe at a high level the intended purpose of the launch agent. Based on the prescribed contention behavior, the operating system will automatically throttle CPU and I/O bandwidth accordingly.

Process Types and Contention Behavior

To register a service to run approximately every 5 minutes (allowing a grace period for system resources to become more available before scheduling at a more aggressive priority), a set of criteria is passed into xpc_activity_register:

xpc_object_tcriteria=xpc_dictionary_create(NULL,NULL,0);xpc_dictionary_set_int64(criteria,XPC_ACTIVITY_INTERVAL,5*60);xpc_dictionary_set_int64(criteria,XPC_ACTIVITY_GRACE_PERIOD,10*60);xpc_activity_register("com.example.app.activity",criteria,^(xpc_activity_tactivity){// Process Dataxpc_activity_set_state(activity,XPC_ACTIVITY_STATE_CONTINUE);dispatch_async(dispatch_get_main_queue(),^{// Update UIxpc_activity_set_state(activity,XPC_ACTIVITY_STATE_DONE);});});

Beneath the smooth glass of each shiny iPhone, nestled on a logic board between touch screen controllers and Apple-designed SoCs, the gyroscope and accelerometer sit largely neglected.

Need it be so? The Core Motion framework makes it surprisingly easy to harness these sensors, opening the door to user interactions above and beyond the tapping and swiping we do every day.

For devices that include the M7 or M8 motion processor, the Core Motion framework also provides access to stored motion activity, such as step counts, stairs climbed, and movement type (walking, cycling, etc.).

Core Motion allows a developer to observe and respond to the motion and orientation of an iOS device by inspecting the raw and processed data from a combination of built-in sensors, including the accelerometer, gyroscope, and magnetometer.

Both accelerometer and gyroscope data are presented in terms of three axes that run through the iOS device. For an iPhone held in portrait orientation, the X axis runs through the device from left (negative values) to right (positive values), the Y axis through the device from bottom (-) to top (+), and the Z axis runs perpendicularly through the screen from the back (-) to the front (+).

The composited device motion data are presented in a few different ways, each with their own uses, as we'll see below.

CoreMotionManager

The CoreMotionManager class provides access to all the motion data on an iOS device. Interestingly, Core Motion provides both "pull" and "push" access to motion data. To "pull" motion data, you can access the current status of any sensor or the composited data as read-only properties of CoreMotionManager. To receive "pushed" data, you start the collection of your desired data with a block or closure that receives updates at a specified interval.

To keep performance at the highest level, Apple recommends using a single shared CoreMotionManager instance throughout your app.

CoreMotionManager provides a consistent interface for each of the four motion data types: accelerometer, gyro, magnetometer, and deviceMotion. As an example, here are the ways you can interact with the gyroscope -- simply replace gyro with the motion data type you need:

Checking for Availability

letmanager=CoreMotionManager()ifmanager.gyroAvailable{// ...}

To make things simpler and equivalent between Swift and Objective-C, assume we've declared a manager instance as a view controller property for all the examples to come.

Setting the Update Interval

manager.gyroUpdateInterval=0.1

This is an NSTimeInterval, so specify your update time in seconds: lower for smoother responsiveness, higher for less CPU usage.

Starting Updates to "pull" Data

manager.startGyroUpdates()

After this call, manager.gyroData is accessible at any time with the device's current gyroscope data.

Starting Updates to "push" Data

letqueue=NSOperationQueue.mainQueuemanager.startGyroUpdatesToQueue(queue){(data,error)in// ...}

The handler closure will be called at the frequency given by the update interval.

Stopping Updates

manager.stopGyroUpdates()

Using the Accelerometer

Let's say we want to give the splash page of our app a fun effect, with the background image staying level no matter how the phone is tilted.

Consider the following code:

First, we check to make sure our device makes accelerometer data available, next we specify a very high update rate, and then we begin updates to a closure that will rotate a UIImageView property.

ifmanager.accelerometerAvailable{manager.accelerometerUpdateInterval=0.01manager.startAccelerometerUpdatesToQueue(NSOperationQueue.mainQueue()){[weakself](data:CMAccelerometerData!,error:NSError!)inletrotation=atan2(data.acceleration.x,data.acceleration.y)-M_PIself?.imageView.transform=CGAffineTransformMakeRotation(CGFloat(rotation))}}

RotationViewController*__weakweakSelf=self;if(manager.accelerometerAvailable){manager.accelerometerUpdateInterval=0.01f;[managerstartAccelerometerUpdatesToQueue:[NSOperationQueuemainQueue]withHandler:^(CMAccelerometerData*data,NSError*error){doublerotation=atan2(data.acceleration.x,data.acceleration.y)-M_PI;weakSelf.imageView.transform=CGAffineTransformMakeRotation(rotation);}];}

Each packet of CMAccelerometerData includes an x, y, and z value -- each of these shows the amount of acceleration in Gs (where G is one unit of gravity) for that axis. That is, if your device were stationary and straight up in portrait orientation, it would have acceleration (0, -1, 0); laying flat on its back on the table would be (0, 0, -1); and tilted forty-five degrees to the right would be something like (0.707, -0.707, 0).

We're calculating the rotation by computing the arctan2 of the x and y components from the accelerometer data, and then using that rotation in a CGAffineTransform. Our image should stay right-side up no matter how the phone is turned:

The results are not terribly satisfactory -- the image movement is jittery, and moving the device in space affects the accelerometer as much as or even more than rotating. These issues could be mitigated by sampling multiple readings and averaging them together, but instead let's look at what happens when we involve the gyroscope.

Adding the Gyroscope

Rather than use the raw gyroscope data that we would get with startGyroUpdates..., let's get composited gyroscope and accelerometer data from the deviceMotion data type. Using the gyroscope, Core Motion separates user movement from gravitational acceleration and presents each as its own property of the CMDeviceMotionData instance that we receive in our handler. The code is very similar to our first example:

ifmanager.deviceMotionAvailable{manager.deviceMotionUpdateInterval=0.01manager.startDeviceMotionUpdatesToQueue(NSOperationQueue.mainQueue()){[weakself](data:CMDeviceMotionData!,error:NSError!)inletrotation=atan2(data.gravity.x,data.gravity.y)-M_PIself?.imageView.transform=CGAffineTransformMakeRotation(CGFloat(rotation))}}

RotationViewController*__weakweakSelf=self;if(manager.deviceMotionAvailable){manager.deviceMotionUpdateInterval=0.01f;[managerstartDeviceMotionUpdatesToQueue:[NSOperationQueuemainQueue]withHandler:^(CMDeviceMotion*data,NSError*error){doublerotation=atan2(data.gravity.x,data.gravity.y)-M_PI;weakSelf.imageView.transform=CGAffineTransformMakeRotation(rotation);}];}

Much better!

UIClunkController

We can also use the other, non-gravity portion of this composited gyro/acceleration data to add new methods of interaction. In this case, let's use the userAcceleration property of CMDeviceMotionData to navigate backward whenever a user taps the left side of her device against her hand.

Remember that the X axis runs laterally through the device in our hand, with negative values to the left. If we sense a user acceleration to the left of more than 2.5 Gs, that will be the cue to pop our view controller from the stack. The implementation is only a couple lines different from our previous example:

ifmanager.deviceMotionAvailable{manager.deviceMotionUpdateInterval=0.02manager.startDeviceMotionUpdatesToQueue(NSOperationQueue.mainQueue()){[weakself](data:CMDeviceMotion!,error:NSError!)inifdata.userAcceleration.x<-2.5{self?.navigationController?.popViewControllerAnimated(true)}}}

ClunkViewController*__weakweakSelf=self;if(manager.deviceMotionAvailable){manager.deviceMotionUpdateInterval=0.01f;[managerstartDeviceMotionUpdatesToQueue:[NSOperationQueuemainQueue]withHandler:^(CMDeviceMotion*data,NSError*error){if(data.userAcceleration.x<-2.5f){[weakSelf.navigationControllerpopViewControllerAnimated:YES];}}];}

And it works like a charm:

Getting an Attitude

Better acceleration data isn't the only thing we gain by including gyroscope data - we now also know the device's true orientation in space. We find this data in the attitude property of CMDeviceMotionData, an instance of CMAttitude. CMAttitude contains three different representations of the device's orientation: Euler angles, a quaternion, and a rotation matrix. Each of these is in relation to a given reference frame.

Finding a Frame of Reference

You can think of a reference frame as the resting orientation of the device from which an attitude is calculated. All four possible reference frames describe the device laying flat on a table, with increasing specificity about the direction it's pointing.

• CMAttitudeReferenceFrameXArbitraryZVertical describes a device laying flat (vertical Z axis) with an "arbitrary" X axis. In practice the X axis is fixed to the orientation of the device when you first start device motion updates.
• CMAttitudeReferenceFrameXArbitraryCorrectedZVertical is essentially the same, but uses the magnetometer to correct possible variation in the gyroscope's measurement over time. Using the magnetometer adds a CPU (and therefore battery) cost.
• CMAttitudeReferenceFrameXMagneticNorthZVertical describes a device laying flat, with its X axis (i.e., the right side of the device) pointed toward magnetic north. This setting may require your user to perform that figure-eight motion with their device to calibrate the magnetometer.
• CMAttitudeReferenceFrameXTrueNorthZVertical is the same as the last, but adjusts for the magnetic/true north discrepancy, and therefore requires location data as well as the magnetometer.

For our purposes, the default "arbitrary" reference frame will be fine - you'll see why in a moment.

Euler Angles

Of the three attitude representations, Euler angles are the most readily understood, as they simply describe rotation around each of the axes we've already been working with. pitch is rotation around the X-axis, increasing as the device tilts toward you, decreasing as it tilts away; roll is rotation around the Y-axis, decreasing as the device rotates to the left, increasing to the right; and yaw is rotation around the (vertical) Z-axis, decreasing clockwise, increasing counter-clockwise.

Each of these values follows what's called the "right hand rule": make a cupped hand with your thumb pointing up and point your thumb in the direction of any of the three axes. Turns that move toward your fingertips are positive, turns away are negative.

Keep It To Yourself

Lastly, let's try using the device's attitude to enable a new interaction for a flash-card app, designed to be used by two study buddies. Instead of manually switching between the prompt and the answer, we'll automatically switch the view as the device turns around, so the quizzer sees the answer while the person being quizzed only sees the prompt.

Figuring out this switch from the reference frame would be tricky. We'd need to somehow take into account the starting orientation of the device and then determine which direction the device is pointing so we know which angles to monitor. Instead, we can save a CMAttitude instance and use it as the "zero point" for an adjusted set of Euler angles, using the multiplyByInverseOfAttitude() method to translate all future attitude updates.

When the quizzer taps the button to begin the quiz, we first configure the interaction - note the "pull" of the deviceMotion for initialAttitude:

// get magnitude of vector via Pythagorean theoremfuncmagnitudeFromAttitude(attitude:CMAttitude)->Double{returnsqrt(pow(attitude.roll,2)+pow(attitude.yaw,2)+pow(attitude.pitch,2))}// initial configurationvarinitialAttitude=manager.deviceMotion.attitudevarshowingPrompt=false// trigger values - a gap so there isn't a flicker zoneletshowPromptTrigger=1.0letshowAnswerTrigger=0.8

// --- class method to get magnitude of vector via Pythagorean theorem+(double)magnitudeFromAttitude:(CMAttitude*)attitude{returnsqrt(pow(attitude.roll,2.0f)+pow(attitude.yaw,2.0f)+pow(attitude.pitch,2.0f));}// --- In @IBAction handler// initial configurationCMAttitude*initialAttitude=manager.deviceMotion.attitude;__blockBOOLshowingPrompt=NO;// trigger values - a gap so there isn't a flicker zonedoubleshowPromptTrigger=1.0f;doubleshowAnswerTrigger=0.8f;

Then, in our now familiar call to startDeviceMotionUpdates, we calculate the magnitude of the vector described by the three Euler angles and use that as a trigger to show or hide the prompt view:

ifmanager.deviceMotionAvailable{manager.startDeviceMotionUpdatesToQueue(NSOperationQueue.mainQueue()){[weakself](data:CMDeviceMotion!,error:NSError!)in// translate the attitudedata.attitude.multiplyByInverseOfAttitude(initialAttitude)// calculate magnitude of the change from our initial attitudeletmagnitude=magnitudeFromAttitude(data.attitude)??0// show the promptif!showingPrompt&&magnitude>showPromptTrigger{ifletpromptViewController=self?.storyboard?.instantiateViewControllerWithIdentifier("PromptViewController")as?PromptViewController{showingPrompt=truepromptViewController.modalTransitionStyle=UIModalTransitionStyle.CrossDissolveself!.presentViewController(promptViewController,animated:true,completion:nil)}}// hide the promptifshowingPrompt&&magnitude<showAnswerTrigger{showingPrompt=falseself?.dismissViewControllerAnimated(true,completion:nil)}}}

FacingViewController*__weakweakSelf=self;if(manager.deviceMotionAvailable){[managerstartDeviceMotionUpdatesToQueue:[NSOperationQueuemainQueue]withHandler:^(CMDeviceMotion*data,NSError*error){// translate the attitude[data.attitudemultiplyByInverseOfAttitude:initialAttitude];// calculate magnitude of the change from our initial attitudedoublemagnitude=[FacingViewControllermagnitudeFromAttitude:data.attitude];// show the promptif(!showingPrompt&&(magnitude>showPromptTrigger)){showingPrompt=YES;PromptViewController*promptViewController=[weakSelf.storyboardinstantiateViewControllerWithIdentifier:@"PromptViewController"];promptViewController.modalTransitionStyle=UIModalTransitionStyleCrossDissolve;[weakSelfpresentViewController:promptViewControlleranimated:YEScompletion:nil];}// hide the promptif(showingPrompt&&(magnitude<showAnswerTrigger)){showingPrompt=NO;[weakSelfdismissViewControllerAnimated:YEScompletion:nil];}}];}

Having implemented all that, let's take a look at the interaction. As the device rotates, the display automatically switches views and the quizee never sees the answer:

Further Reading

I skimmed over the quaternion and rotation matrix components of CMAttitude earlier, but they are not without intrigue. The quaternion, in particular, has an interesting history, and will bake your noodle if you think about it long enough.

Queueing Up

To keep the code examples readable, we've been sending all our CoreMotionManager updates to the main queue. As a best practice, it would be better to have these updates on their own queue, so they can't get slow down user interaction, but then we'll need to get back on the main queue to update user interface elements. NSOperationQueue makes this easy, with its addOperationWithBlock method:

letqueue=NSOperationQueue()manager.startDeviceMotionUpdatesToQueue(queue){[weakself](data:CMDeviceMotion!,error:NSError!)in// motion processing hereNSOperationQueue.mainQueue().addOperationWithBlock{// update UI here}}

NSOperationQueue*queue=[[NSOperationQueuealloc]init];[managerstartDeviceMotionUpdatesToQueue:queuewithHandler:^(CMDeviceMotion*data,NSError*error){// motion processing here[[NSOperationQueuemainQueue]addOperationWithBlock:^{// update UI here}];}];

Clearly not all interactions made possible by Core Motion are good ones. Navigation through motion can be fun but also hard to discover or easy to accidentally trigger; purposeless animations can make it harder to focus on the task at hand. Prudent developers will skip over gimmicks that distract and find ways to use device motion that enrich their apps and delight their users.

The introduction of iPhone 6+ brought on a new importance for UISplitViewController. With just a few little tweaks, an app can now become Universal, with Apple handling most of the UI logic for all the different screen sizes.

Check out the UISplitViewController doing it's magic on iPhone 6+:

Note that the view does not split when the iPhone 6+ is in Zoomed Display mode! (You can change between Standard and Zoomed Display Mode by going to Settings.app → Display & Brightness → View)

Again, Apple handles the logic for figuring out exactly when to show the split views.

The Storyboard Layout

Here is an overview of what a storyboard layout looks like with a split view controller:

Let's get into more detail:

Master / Detail

The first step to using a UISplitViewController is dragging it onto the storyboard. Next, specify which view controller is the Master and which one is the Detail.

Do this by selecting the appropriate Relationship Segue:

The Master view controller is usually the navigation controller containing the list view (a UITableView in most cases). The Detail view controller is the Navigation Controller for the view corresponding to what shows up when the user taps on the list item.

Show Detail

There is one last part to making the split view controller work: specifying the "Show Detail" segue:

In the example below, when the user taps on a cell in the SelectColorTableViewController, they'll be shown a navigation controller with the ColorViewController at it's root.

Double Navigation Controllers‽

At this point, you might be wondering why both the Master and the Detail view controllers have to be navigation controllers—especially since there is a "Show Detail" segue from a table view (which is part of the navigation stack) to the Detail view controller. What if the Detail View Controller didn't start with a Navigation Controller?

By all accounts, the app would still work just fine. On an iPhone 6+, the only difference is the lack of a navigation toolbar when the phone is in landscape mode:

It's not a big deal, unless you do want your navigation bar to show a title. This ends up being a deal-breaker on an iPad.

Notice that when the iPad app is first opened up, there is no indication that this is a split view controller at all! To trigger the Master view controller, the user has to magically know to swipe left to right.

Even when the navigation controller is in place, the UI is not that much better at first glance (although seeing a title is definitely an improvement):

displayModeButtonItem

The simplest way to fix this issue would be to somehow indicate that there is more to the app than what's currently on-screen. Luckily, the UISplitViewController has a displayModeButtonItem, which can be added to the navigation bar:

overridefuncviewDidLoad(){super.viewDidLoad()// ...navigationItem.leftBarButtonItem=splitViewController?.displayModeButtonItem()navigationItem.leftItemsSupplementBackButton=true}

Build and Run on the iPad again, and now the user gets a nice indication of how to get at the rest of the app:

UISplitViewController's displayModeButtonItem adds a bit of extra-cool usability to the iPhone 6+ in Landscape mode, too:

By using the displayModeButtonItem, you're once again letting Apple figure out what's appropriate for which screen sizes / rotations. Instead of sweating the small (and big) stuff yourself, you can sit back and relax.

Collapse Detail View Controller

There is one more optimization we can do for the iPhone 6+ via UISplitViewControllerDelegate.

When the user first launches the app, we can make the Master view controller fully displayed until the user selects a list item:

importUIKitclassSelectColorTableViewController:UITableViewController,UISplitViewControllerDelegate{privatevarcollapseDetailViewController=true// MARK: UITableViewControlleroverridefuncviewDidLoad(){super.viewDidLoad()splitViewController?.delegate=self}// ...// MARK: UITableViewDelegateoverridefunctableView(tableView:UITableView,didSelectRowAtIndexPathindexPath:NSIndexPath){collapseDetailViewController=false}// MARK: - UISplitViewControllerDelegatefuncsplitViewController(splitViewController:UISplitViewController,collapseSecondaryViewControllersecondaryViewController:UIViewController!,ontoPrimaryViewControllerprimaryViewController:UIViewController!)->Bool{returncollapseDetailViewController}}

When the user first opens up the app on iPhone 6+ in portrait orientation, SelectColorViewController gets displayed as the primary view controller. Once the user selects a color or the app goes into the background, the SelectColorViewController gets collapsed again, and the ColorViewController is displayed:

Be sure to check out the UISplitViewControllerDelegate documentation to learn about all the other fancy things you can do with the UISplitViewController.

Given the new different device sizes we now have to work with as iOS developers, the UISplitViewController will soon have to become our new best friend!

You can get the complete source code for the project used in this post on Github.

For as long has the iPhone has existed, location services have been front and center. Maps.app was one of the killer features that launched with the original iPhone. The Core Location API has existed in public form since the first public iPhone OS SDK. With each release of iOS, Apple has steadily added new features to the framework, like background location services, geocoding, and iBeacons.

iOS 8 continues that inexorable march of progress. Like many other aspects of the latest update, Core Location has been shaken up, with changes designed both to enable developers to build new kinds of things they couldn't before and to help maintain user privacy. Specifically, iOS 8 brings three major sets of changes to the Core Location framework: more granular permissions, indoor positioning, and visit monitoring.

Permissions

There are a number of different reasons an app might request permission to access your location. A GPS app that provides turn-by-turn directions needs constant access to your location so it can tell you when to turn. A restaurant recommendation app might want to be able to access your location (even when it's not open) so it can send you a push notification when you're near a restaurant your friends like. A Twitter app might want your location when it posts, but shouldn't need to monitor your location when you're not using it.

Prior to iOS 8, location services permissions were binary: you either gave an app permission to use location services, or you didn't. Settings.app would show you which apps were accessing your location in the background, but you couldn't do anything about it short of blocking the app from using location services entirely.

iOS 8 fixes that by breaking up location services permissions into two different types of authorization.

• "When In Use" authorization only gives the app permission to receive your location when — you guessed it — the app is in use.

• "Always" authorization, gives the app traditional background permissions, just as has always existed in prior iOS versions.

This is a major boon for user privacy, but it does mean a bit more effort on the part of us developers.

Requesting Permission

In earlier versions of iOS, requesting permission to use location services was implicit. Given an instance of CLLocationManager, the following code would trigger the system prompting the user to authorize access to location services if they hadn't yet explicitly approved or denied the app:

importFoundationimportCoreLocationletmanager=CLLocationManager()ifCLLocationManager.locationServicesEnabled(){manager.startUpdatingLocation()}

To make things simpler, assume we've declared a manager instance as a property for all the examples to come, and that its delegate is set to its owner.

The very act of telling a CLLocationManager to get the latest location would cause it to prompt for location services permission if appropriate.

With iOS 8, requesting permission and beginning to use location services are now separate actions. Specifically, there are two different methods you can use to explicitly request permissions: requestWhenInUseAuthorization and requestAlwaysAuthorization. The former only gives you permission to access location data while the app is open; the latter gives you the traditional background location services that prior versions of iOS have had.

ifCLLocationManager.authorizationStatus()==.NotDetermined{manager.requestAlwaysAuthorization()}

or

ifCLLocationManager.authorizationStatus()==.NotDetermined{manager.requestWhenInUseAuthorization()}

Since this happens asynchronously, the app can't start using location services immediately. Instead, one must implement the locationManager:didChangeAuthorizationStatus delegate method, which fires any time the authorization status changes based on user input.

If the user has previously given permission to use location services, this delegate method will also be called after the location manager is initialized and has its delegate set with the appropriate authorization status. Which conveniently makes for a single code path for using location services.

funclocationManager(manager:CLLocationManager!,didChangeAuthorizationStatusstatus:CLAuthorizationStatus){ifstatus==.AuthorizedAlways||status==.AuthorizedWhenInUse{manager.startUpdatingLocation()// ...}}

Descriptive String

Another change is required to use location services in iOS 8. In the past, one could optionally include a 'NSLocationUsageDescription' key in Info.plist. This value was a plain-text string explaining to the user for what the app planning to use location services. This has since been split up into two separate keys (NSLocationWhenInUseUsageDescription and NSLocationAlwaysUsageDescription), and is now mandatory; if you call requestWhenInUseAuthorization or requestAlwaysAuthorization without the corresponding key, the prompt simply won't be shown to the user.

Requesting Multiple Permissions

Another detail worth noting is that the authorization pop-up will only ever be shown to a user once. After CLLocationManager.authorizationStatus() returns anything other than NotDetermined, calling either requestWhenInUseAuthorization() or requestAlwaysAuthorization() won't result in a UIAlertController being displayed to the user. After the user's initial choice, the only way to change authorization settings is to go to Settings.app and go to either the privacy settings or the settings page for that specific app.

While more of an inconvenience under the old permission system, this significantly complicates things if an app asks for both "when-in-use" and "always" authorization at different times in its lifecycle. To help mitigate this, Apple has introduced a string constant, UIApplicationOpenSettingsURLString, that represents a URL that will open the current app's settings screen in Settings.app.

Here's an example of how an app that prompts for both kinds of permissions might decide what to do when trying to prompt for Always permissions.

switchCLLocationManager.authorizationStatus(){case.Authorized:// ...case.NotDetermined:manager.requestWhenAlwaysAuthorization()case.AuthorizedWhenInUse,.Restricted,.Denied:letalertController=UIAlertController(title:"Background Location Access Disabled",message:"In order to be notified about adorable kittens near you, please open this app's settings and set location access to 'Always'.",preferredStyle:.Alert)letcancelAction=UIAlertAction(title:"Cancel",style:.Cancel,handler:nil)alertController.addAction(cancelAction)letopenAction=UIAlertAction(title:"Open Settings",style:.Default){(action)inifleturl=NSURL(string:UIApplicationOpenSettingsURLString){UIApplication.sharedApplication().openURL(url)}}alertController.addAction(openAction)self.presentViewController(alertController,animated:true,completion:nil)}

Backwards Compatibility

All of these new APIs require iOS 8. For apps still supporting iOS 7 or earlier, one must maintain two parallel code paths—one that explicitly asks for permission for iOS 8 and one that maintains the traditional method of just asking for location updates. A simple implementation might look something like this:

functriggerLocationServices(){ifCLLocationManager.locationServicesEnabled(){ifself.manager.respondsToSelector("requestWhenInUseAuthorization"){manager.requestWhenInUseAuthorization()}else{startUpdatingLocation()}}}funcstartUpdatingLocation(){manager.startUpdatingLocation()}// MARK: - CLLocationManagerDelegatefunclocationManager(manager:CLLocationManager!,didChangeAuthorizationStatusstatus:CLAuthorizationStatus){ifstatus==.AuthorizedWhenInUse||status==.Authorized{startUpdatingLocation()}}

Building User Trust

There is a common thread running throughout all of the changes in iOS 8: they all make it easier to earn the trust of your users.

Explicit calls to request authorization encourage apps to not ask for permission until the user attempts to do something that requires authorization. Including a usage description makes it easy to explain why you need location access and what the app will use it for. The distinction between "When In Use" and "Always" authorization makes users feel comfortable that you only have as much of their data as is needed.

Of course, there is little in these new APIs to stop one from doing things the same way as always. All one "needs" to do for iOS 8 support is to add in a call to useAlwaysAuthorization and add in a generic usage string. But with these new changes, Apple is sending the strong message that you should to respect your users. Once users get accustomed to apps that respect users' privacy in this way, it isn't hard to imagine that irresponsible use of location services could result in negative App Store ratings.

Indoor Positional Tracking

If one were to peruse the API diffs for CoreLocation.framework, among the most baffling discoveries would be the introduction of CLFloor, a new object with a quite simple interface:

classCLFloor:NSObject{varlevel:Int{get}}

@interfaceCLFLoor : NSObject@property(readonly,nonatomic)NSIntegerlevel@end

That's it. A single property, an integer that tells you what floor of a building the location represents.

Europeans will surely be glad to know that the ground floor of a building is represented by '0', not '1'.

A CLLocation object returned by a CLLocationManager may include a floor property, but if you were to write a sample app that used location services you'd notice that your CLLocation objects' floor property was always nil.

That's because this API change is the tip of the iceberg for a larger suite of features introduced in iOS 8 to facilitate indoor location tracking. For developers building applications in large spaces, like art museums or department stores, Apple now has tooling to support IPS using the built-in Core Location APIs and a combination of WiFi, GPS, cellular, and iBeacon data.

That said, information about this new functionality is surprisingly hard to come by. The program is currently limited to businesses who have applied for the program via Apple Maps Connect, with a pretty strict barrier to entry. Limited information about the program was outlined in this year's WWDC (Session 708: Taking Core Location Indoors), but for the most part, most logistical details are locked behind closed doors. For all but the most well-connected of us, we have no choice but to be content writing this off as an idle curiosity.

CLVisit

In many apps, the reason to use location monitoring is determining whether a user is in a given place. Conceptually, you're thinking in terms of nouns like "places" or "visits", rather than raw GPS coordinates.

However, unless you have the benefit of being able to use region monitoring (which is limited to a relatively small number of regions) or iBeacon ranging (which requires beacon hardware to be physically installed in a space) Core Location's background monitoring tools aren't a great fit. Building a check-in app or a more comprehensive journaling app along the lines of Moves has traditionally meant eating up a lot of battery life with location monitoring and spending a lot of time doing custom processing.

With iOS 8, Apple has tried to solve this by introducing CLVisit, a new type of background location monitoring. A single CLVisit represents a period of time a user has spent in a single location, including both a coordinate and start / end timestamps.

In theory, using visit monitoring is no more work than any other background location tracking. Simply calling manager.startMonitoringVisits() will enable background visit tracking, assuming the user has given Always authorization to your app. Once started, your app will be woken up periodically in the background when new updates come in. Unlike with basic location monitoring, if the system has a number of visit updates queued up (typically be enabling deferred updates), your delegate method will be called multiple times, with each call having a single visit, rather than the array of CLLocation objects that locationManager:didReceiveUpdates: is called with. Calling manager.stopMonitoringVisits() will stop tracking.

Handling Visits

Each CLVisit object contains a few basic properties: its average coordinate, a horizontal accuracy, and dates for arrival and departure times.

Every time a visit is tracked, the CLLocationManagerDelegate might be informed twice: once while the user has just arrived to a new place, and again when they leave it. You can figure out which is which by checking the departureDate property; a departure time of NSDate.distantFuture() means that the user is still there.

funclocationManager(manager:CLLocationManager!,didVisitvisit:CLVisit!){ifvisit.departureDate.isEqualToDate(NSDate.distantFuture()){// User has arrived, but not left, the location}else{// The visit is complete}}

Caveat Implementor

CLVisit is, as of iOS 8.1, not all that precise. While start and end times are generally accurate within a minute or two, lines get blurred at the edges of what is and is what not a visit. Ducking into a corner coffee shop for a minute might not trigger a visit, but waiting at a particularly long traffic light might. It's likely that Apple will improve the quality of visit detection in future OS upgrades, but for now you might want to hold off on relying on CLVisit in favor of your own visit detection for use cases where it's vital your data is as accurate can be.

With all the different means to comment, mark up, save, and share right at our fingertips, it's easy to overlook the value of a printed sheet of paper.

UIKit makes it easy to print straight from a user's device with custom designs that you can adapt to both your content and the paper size. This article will first walk through how to format your content for printing, then detail the different ways to present (or not!) the printing interface.

The "printed" images throughout this article are taken from Apple's Printer Simulator. (The yellow edges represent the non-printable margins of the paper)

As of Xcode 6, the printer simulator must be downloaded as part of the Hardware IO Tools for Xcode.

At the heart of the UIKit Printing APIs is UIPrintInteractionController. A shared instance of this class manages details of print jobs and configure any UI that will be presented to the user. It also provides three levels of control for the formatting of your content.

Printing is a Job

Before we look at formatting actual content for printing, let's go through the options for configuring the print job and the print options presented to the user.

UIPrintInfo

Print job details are set in a UIPrintInfo instance. You can use the following properties:

• jobNameString: A name for this print job. The name will be displayed in the Print Center on the device and, for some printers, on the LCD display.
• orientationUIPrintInfoOrientation: Either .Portrait (the default) or .Landscape—this is ignored if what you print has an intrinsic orientation, such as a PDF.
• duplexUIPrintInfoDuplex: .None, .ShortEdge, or .LongEdge. The short- and long-edge settings indicate how double-sided pages could be bound, while .None suppresses double-sided printing (though not the UI toggle for duplexing, perplexingly).
• outputTypeUIPrintInfoOutputType: Gives UIKit a hint about the type of content you're printing. Can be any of:
  • .General (default): For mixed text and graphics; allows duplexing.
  • .Grayscale: Can be better than .General if your content includes black text only.
  • .Photo: For color or black and white images; disables duplexing and favors photo media for the paper type.
  • .PhotoGrayscale: Can be better than .Photo for grayscale-only images, depending on the printer.
• printerIDString?: An ID for a particular printer—you can retrieve this only after the user has selected a printer through the UI and save it to use as a preset for a future print job.

In addition, UIPrintInfo provides a dictionaryRepresentation property, which can be saved and used to create a new UIPrintInfo instance later.

UIPrintInteractionController Settings

There are a handful of settings on the UIPrintInteractionController that you can configure before displaying the printing UI. These include:

• printInfoUIPrintInfo: The aforementioned print job configuration.
• printPaperUIPrintPaper: A simple type that describes the physical and printable size of a paper type; except for specialized applications, this will be handled for you by UIKit.
• showsNumberOfCopiesBool: When true, lets the user choose the number of copies.
• showsPageRangeBool: When true, lets the user choose a sub-range from the printed material. This only makes sense with multi-page content—it's turned off by default for images.
• showsPaperSelectionForLoadedPapersBool: When this is true and the selected printer has multiple paper options, the UI will let the user choose which paper to print on.

Formatting Your Content

Through four different properties of UIPrintInteractionController, you can select the level of control (and complexity) you want for your content.

1. printingItemAnyObject! or printingItems[AnyObject]!: At the most basic level, the controller simply takes content that is already printable (images and PDFs) and sends them to the printer.
2. printFormatterUIPrintFormatter: At the next level, you can use a UIPrintFormatter subclass to format content inside your application, then hand the formatter off to the UIPrintInteractionController. You have some control over the format, and the printing API largely takes care of the rest.
3. printPageRendererUIPrintPageRenderer: At the highest level, you can create a custom subclass of UIPrintPageRenderer, combining page formatters and your own drawing routines for headers, footers, and page content.

Since Thanksgiving (my favorite holiday) is around the corner, to illustrate these properties we'll add printing to different screens of a hypothetical app for Thanksgiving recipes.

Printing With printItem(s)

You can print pre-existing printable content by setting either the printItem or printItems property of UIPrintInteractionController. Images and PDFs can be given either as image data (in a NSData, UIImage, or ALAsset instance) or via any NSURL referencing something that can be loaded into an NSData object. To be printable, images must be in a format that UIImage supports.

Let's walk through a very simple case: showing the UI to print an image when the user taps a button. (We'll look at alternate ways of initiating printing below.) The process will be largely the same, no matter what you're printing—configure your print info, set up the print interaction controller, and provide your content before displaying the UI:

@IBActionfuncprint(sender:UIBarButtonItem){ifUIPrintInteractionController.canPrintURL(imageURL){letprintInfo=UIPrintInfo(dictionary:nil)printInfo.jobName=imageURL.lastPathComponentprintInfo.outputType=.PhotoletprintController=UIPrintInteractionController.sharedPrintController()!printController.printInfo=printInfoprintController.showsNumberOfCopies=falseprintController.printingItem=imageURLprintController.presentAnimated(true,completionHandler:nil)}}

-(IBAction)print:(id)sender{if([UIPrintInteractionControllercanPrintURL:self.imageURL]){UIPrintInfo*printInfo=[UIPrintInfoprintInfo];printInfo.jobName=self.imageURL.lastPathComponent;printInfo.outputType=UIPrintInfoOutputGeneral;UIPrintInteractionController*printController=[UIPrintInteractionControllersharedPrintController];printController.printInfo=printInfo;printController.printingItem=self.imageURL;[printControllerpresentAnimated:truecompletionHandler:nil];}}

Easy as pie! (Or, in this case, sautéed Swiss chard.)

The presentAnimated(:completionHandler:) method is for presenting the printing UI on the iPhone. If printing from the iPad, use one of the presentFromBarButtonItem(:animated:completionHandler:) or presentFromRect(:inView:animated:completionHandler:) methods instead.

UIPrintFormatter

The UIPrintFormatter class has two subclasses that can be used to format text (UISimpleTextPrintFormatter and UIMarkupTextPrintFormatter) plus another (UIViewPrintFormatter) that can format the content of three views: UITextView, UIWebView, and MKMapView. Print formatters have a few properties that allow you to define the printed area of the page in different ways; the final print area for the formatter will be the smallest rectangle that meets the following criteria:

• contentInsetsUIEdgeInsets: A set of insets from the edges of the page for the entire block of content. The left and right insets are applied on every page, but the top inset is only applied on the first page. The bottom inset is ignored.
• perPageContentInsetsUIEdgeInsets (iOS 8 only): A set of insets from the edges of the page for every page of formatted content.
• maximumContentWidth and maximumContentHeightCGFloat: If specified, these can further constrain the width and height of the content area.

Though not clearly documented by Apple, all of these values are based on 72 points per inch.

The two text-based print formatters are initialized with the text they will be formatting. UISimpleTextPrintFormatter can handle plain or attributed text, while UIMarkupTextPrintFormatter takes and renders HTML text in its markupText property. Let's try sending an HTML version of our Swiss chard recipe through the markup formatter:

letformatter=UIMarkupTextPrintFormatter(markupText:htmlString)formatter.contentInsets=UIEdgeInsets(top:72,left:72,bottom:72,right:72)// 1" marginsprintController.printFormatter=formatter

UIMarkupTextPrintFormatter*formatter=[[UIMarkupTextPrintFormatteralloc]initWithMarkupText:htmlString];formatter.contentInsets=UIEdgeInsetsMake(72,72,72,72);// 1" marginsprintController.printFormatter=formatter;

The result? A handsomely rendered HTML page:

On the other hand, to use a UIViewPrintFormatter, you retrieve one from the view you want to print via its viewPrintFormatter property. Here's a look at how the formatter does its job for each of the three supported views:

1) UITextView

2) UIWebView

3) MKMapView

UIPrintPageRenderer

The built-in formatters are fine, but for the most control over the printed page, you can implement a subclass of UIPrintPageRenderer. In your subclass you can combine the print formatters we saw above with your own custom drawing routines to create terrific layouts for your app's content. Let's look at one more way of printing a recipe, this time using a page renderer to add a header and to draw the images alongside the text of the recipe.

In the initializer, we save the data that we'll need to print, then set the headerHeight (the header and footer drawing methods won't even be called unless you set their respective heights) and create a markup text formatter for the text of the recipe.

Complete Objective-C and Swift source code for the following examples is available as a gist.

classRecipePrintPageRenderer:UIPrintPageRenderer{letauthorName:Stringletrecipe:Recipeinit(authorName:String,recipe:Recipe){self.authorName=authorNameself.recipe=recipesuper.init()self.headerHeight=0.5*POINTS_PER_INCHself.footerHeight=0.0// defaultletformatter=UIMarkupTextPrintFormatter(markupText:recipe.html)formatter.perPageContentInsets=UIEdgeInsets(top:POINTS_PER_INCH,left:POINTS_PER_INCH,bottom:POINTS_PER_INCH,right:POINTS_PER_INCH*3.5)addPrintFormatter(formatter,startingAtPageAtIndex:0)}// ...}

@interfaceRecipePrintPageRenderer : UIPrintPageRenderer@property(nonatomic,strong)NSString*authorName;@property(nonatomic,strong)Recipe*recipe;-(id)initWithAuthorName:(NSString*)authorNamerecipe:(Recipe*)recipe;@end@implementationRecipePrintPageRenderer-(id)initWithAuthorName:(NSString*)authorNamerecipe:(Recipe*)recipe{if(self=[superinit]){self.authorName=authorName;self.recipe=recipe;self.headerHeight=0.5;self.footerHeight=0.0;// defaultUIMarkupTextPrintFormatter*formatter=[[UIMarkupTextPrintFormatteralloc]initWithMarkupText:recipe.html];formatter.perPageContentInsets=UIEdgeInsetsMake(POINTS_PER_INCH,POINTS_PER_INCH,POINTS_PER_INCH,POINTS_PER_INCH*3.5);[selfaddPrintFormatter:formatterstartingAtPageAtIndex:0];}returnself;}// ...@end

When you use one or more print formatters as part of your custom renderer (as we're doing here), UIKit queries them for the number of pages to print. If you're doing truly custom page layout, implement the numberOfPages() method to provide the correct value.

Next, we override drawHeaderForPageAtIndex(:inRect:) to draw our custom header. Unfortunately, those handy per-page content insets on print formatters are gone here, so we first need to inset the headerRect parameter to match my margins, then simply draw into the current graphics context. There's a similar drawFooterForPageAtIndex(:inRect:) method for drawing the footer.

overridefuncdrawHeaderForPageAtIndex(pageIndex:Int,varinRectheaderRect:CGRect){varheaderInsets=UIEdgeInsets(top:CGRectGetMinY(headerRect),left:POINTS_PER_INCH,bottom:CGRectGetMaxY(paperRect)-CGRectGetMaxY(headerRect),right:POINTS_PER_INCH)headerRect=UIEdgeInsetsInsetRect(paperRect,headerInsets)// author name on leftauthorName.drawAtPointInRect(headerRect,withAttributes:nameAttributes,andAlignment:.LeftCenter)// page number on rightletpageNumberString:NSString="\(pageIndex + 1)"pageNumberString.drawAtPointInRect(headerRect,withAttributes:pageNumberAttributes,andAlignment:.RightCenter)}

-(void)drawHeaderForPageAtIndex:(NSInteger)indexinRect:(CGRect)headerRect{UIEdgeInsetsheaderInsets=UIEdgeInsetsMake(CGRectGetMinY(headerRect),POINTS_PER_INCH,CGRectGetMaxY(self.paperRect)-CGRectGetMaxY(headerRect),POINTS_PER_INCH);headerRect=UIEdgeInsetsInsetRect(self.paperRect,headerInsets);// author name on left[self.authorNamedrawAtPointInRect:headerRectwithAttributes:self.nameAttributesandAlignment:NCStringAlignmentLeftCenter];// page number on rightNSString*pageNumberString=[NSStringstringWithFormat:@"%ld",index+1];[pageNumberStringdrawAtPointInRect:headerRectwithAttributes:self.pageNumberAttributesandAlignment:NCStringAlignmentRightCenter];}

Lastly, let's provide an implementation of drawContentForPageAtIndex(:inRect:):

overridefuncdrawContentForPageAtIndex(pageIndex:Int,inRectcontentRect:CGRect){ifpageIndex==0{// only use rightmost two inches of contentRectletimagesRectWidth=POINTS_PER_INCH*2letimagesRectHeight=paperRect.height-POINTS_PER_INCH-(CGRectGetMaxY(paperRect)-CGRectGetMaxY(contentRect))letimagesRect=CGRect(x:CGRectGetMaxX(paperRect)-imagesRectWidth-POINTS_PER_INCH,y:paperRect.origin.y+POINTS_PER_INCH,width:imagesRectWidth,height:imagesRectHeight)drawImages(recipe.images,inRect:imagesRect)}}

-(void)drawContentForPageAtIndex:(NSInteger)pageIndexinRect:(CGRect)contentRect{if(pageIndex==0){// only use rightmost two inches of contentRectCGFloatimagesRectWidth=POINTS_PER_INCH*2;CGFloatimagesRectHeight=CGRectGetHeight(self.paperRect)-POINTS_PER_INCH-(CGRectGetMaxY(self.paperRect)-CGRectGetMaxY(contentRect));CGRectimagesRect=CGRectMake(CGRectGetMaxX(self.paperRect)-imagesRectWidth-POINTS_PER_INCH,CGRectGetMinY(self.paperRect)+POINTS_PER_INCH,imagesRectWidth,imagesRectHeight);[selfdrawImages:self.recipe.imagesinRect:imagesRect];}}

With the implementation of our custom page renderer complete, we can set an instance as the pageRenderer property on the print interaction controller and we're ready to print.

letrenderer=RecipePrintPageRenderer(authorName:"Nate Cook",recipe:selectedRecipe)printController.printPageRenderer=renderer

RecipePrintPageRenderer*renderer=[[RecipePrintPageRendereralloc]initWithAuthorName:@"Nate Cook"recipe:selectedRecipe];printController.printPageRenderer=renderer;

The final result is much nicer than any of the built-in formatters.

Note that the text of the recipe is being formatted by a UIMarkupTextPrintFormatter, while the header and images are drawn via custom code.

Printing via a Share Sheet

With the tools we've learned above, adding printing capability in a share sheet is simple. Instead of using UIPrintInteractionController to present the printing UI, we pass off our configured UIPrintInfo and printing item(s), formatter, or renderer to a UIActivityViewController. If the user selects the Print button in the share sheet, the printing UI will be displayed with all our configurations intact.

@IBActionfuncopenShareSheet(){letprintInfo=...letformatter=...letactivityItems=[printInfo,formatter,textView.attributedText]letactivityController=UIActivityViewController(activityItems:activityItems,applicationActivities:nil)presentViewController(activityController,animated:true,completion:nil)}

-(IBAction)openShareSheet:(id)sender{UIPrintInfo*printInfo=...UISimpleTextPrintFormatter*formatter=...NSArray*activityItems=@[printInfo,formatter,self.textView.attributedText];UIActivityViewController*activityController=[[UIActivityViewControlleralloc]initWithActivityItems:activityItemsapplicationActivities:nil];[selfpresentViewController:activityControlleranimated:YEScompletion:nil];}

While UIPrintInfo and subclasses of UIPrintFormatter and UIPrintPageRenderer can be passed to a UIActivityViewController as activities, none of them seem to conform to the UIActivityItemSource protocol, so you'll see a (harmless) warning in your console about "Unknown activity items."

Skipping the Printing UI

New in iOS 8 is a way to print without any presentation of the printing UI. Instead of presenting the UI each time the user presses a print button, you can provide a way for your users to select a printer somewhere in your app with the easy-to-use UIPrinterPickerController. It accepts an optional UIPrinter instance in its constructor for a pre-selection, uses the same presentation options as explained above, and has a completion handler for when the user has selected her printer:

letprinterPicker=UIPrinterPickerController(initiallySelectedPrinter:savedPrinter)printerPicker.presentAnimated(true){(printerPicker,userDidSelect,error)inifuserDidSelect{self.savedPrinter=printerPicker.selectedPrinter}}

UIPrinterPickerController*printPicker=[UIPrinterPickerControllerprinterPickerControllerWithInitiallySelectedPrinter:self.savedPrinter];[printPickerpresentAnimated:YEScompletionHandler:^(UIPrinterPickerController*printerPicker,BOOLuserDidSelect,NSError*error){if(userDidSelect){self.savedPrinter=printerPicker.selectedPrinter;}}];

Now you can tell your UIPrintInteractionController to print directly by calling printToPrinter(:completionHandler:) with the saved printer instead of using one of the present... methods.

As one final recommendation, consider the printed page as you would any other way of interacting with your content. In the same way you scrutinize font size and weight or the contrast between elements on screen, make sure to test your print layouts on paper—the contrast, size, and margins should all be appropriate to the medium.

Everyone is excited about ᴡᴀᴛᴄʜ. Developers especially.

What's the best way to get started? Look no further than Apple's WatchKit developer resources.

• Watch the "Getting Started" video—it's like being in Moscone.
• Read the Human Interface Guidelines—consider it a prerequisite for designing your application.
• Peruse the WatchKit Programming Guide and WKInterfaceCatalog for an introduction everything the framework provides.
• And when you're finally ready to add that App Extension target to your app, consult the Lister Sample App (in both Objective-C & Swift!) to see how everything fits together.

Apple's Developer Publications, Developer Evangelism, and WatchKit teams knocked it out of the park with the WatchKit launch. The official resources are superb.

That said, after taking a look at everything, there were a few things that jumped out as it relates to UIKit. They're the kind of subjective, opinionated things that don't make for good documentation, but might be interesting or useful to anyone else as they're getting started.

So this week, some initial impressions of WatchKit from the perspective of an iOS developer.

WatchKit harkens back to the earliest days of iOS development, when the platform limitations acted as liberating constraints for developers. Compared to OS X & AppKit, mired in decades of cruft and churn, iPhoneOS (as it was originally known) & UIKit were a breath of fresh air. Apps were small, simple, and humble.

After 7 years and as many major releases, iOS has grown to encompass myriad devices and configurations, from iPhones and iPads of all shapes and sizes, to the TV and CarPlay. It's still an amazing developer experience (for the most part), but it feels like some of the magic has been lost along the way.

Counterpoint: Nostalgia is bullshit. Remember, back in those days, there was no ARC, no GCD, no Interface Builder support for iOS and certainly no Swift. The indispensable open source libraries of the time were Three20 and asi-http-request. The state of the art for table view scroll performance was to manually composite text and images in a cell's content view drawRect:. Life was solitary, poor, nasty, brutish, and short.

Regardless of where you're personally coming from, the simplicity of WatchKit is something to be enjoyed and celebrated.

Comparison to UIKit

WatchKit bears a striking resemblance to UIKit, which is not entirely surprising, given their shared history and purpose. Watches are different from phones and tablets, which themselves are different from desktops. Some concepts are shared, but each have unique purposes and constraints that shape the topography of their software.

For sake of comparison, here is how one might understand WatchKit in terms of UIKit / Cocoa concepts:

As a namespace prefix, WKInterface sticks out like a sore thumb, but WK on its own was recently claimed by the new WebKit framework. Although the Watch platform is a long way from being able to embed web views, the decision to demarcate things as they are is sensible.

There's a lot of overlap, but there are important differences. Understanding those differences is both informative to making great WatchKit apps as well as enlightening in terms of how Apple's thinking about API and best practices continues to evolve.

WKInterfaceController

WKInterfaceController manages the elements in a scene, whereas UIViewController manages a view and its subviews. Interface objects are not views, but they act in similar ways.

The designated initializer for WKInterfaceController is initWithContext:, which accepts an optional context object:

overrideinit(context:AnyObject?){super.init(context:context)// ...}

What's a context? It's anything you want it to be: a date, a string, a model object, or nothing at all.

The open-endedness of context may be disorienting at first, but it's actually a remarkably clever solution to a long-standing problem of UIKit—namely, the difficulty passing information between view controllers. Without a standard convention for configuring UIViewControllers as they are pushed, popped, and presented, developers are regularly faced with a miserable choice between custom designated initializers (incompatible with Storyboards), property configuration (prone to creating controllers with incomplete state), custom delegates (overly ceremonious when done correctly), or notifications (just... no). It's for this reason that so many applications backed by Core Data fall into the pattern of referencing a shared managedObjectContext in the App Delegate.

But I digress.

Overall, WKInterfaceController's API has a tiny footprint, and there's no better illustration than its lifecycle methods:

// MARK: - WKInterfaceControlleroverridefuncwillActivate(){// ...}overridefuncdidDeactivate(){// ...}

That's it: 2 methods. No loading / unloading, no will / did appear / disappear, no animated:YES. Watch apps are simple by necessity. Communication between the iOS device driving the application and the watch is both time-consuming and battery-consuming, so all of the setup for the interface controller's scene is to be done in the initializer and willActivate. Both during and after didDeactivate, the Watch will ignore attempts to update the state of interface elements.

Watch applications are either Hierarchical or Page-Based. This is similar to Xcode's project templates for "Master-Detail Application", "Page-Based Application", and "Tabbed Application", except that the design choices are mutually exclusive.

Hierarchical applications have an implicit navigational stack, which WKInterfaceController can manage with -pushControllerWithName:context:& -popController. One thing to note here is how -pushControllerWithName:context: takes a string—the name of the controller as specified in the Storyboard—rather than an instance of the controller itself.

Page-Based applications, on the other hand, act like a horizontal or vertical paged UIScrollView, with a pre-determined number of scenes each managed by a controller. It will be interesting to see which use cases are best served by Page-Based and Hierarchical interfaces. Without trying out stock applications on a real device, there's not much context to understand the trade-offs of each intuitively.

As a final aside, there is an interesting pattern in Apple's Swift sample code, to use inner structs as namespaces for Storyboard constants:

classWatchListsInterfaceController:WKInterfaceController,ListsControllerDelegate{structWatchStoryboard{staticletinterfaceControllerName="WatchListsInterfaceController"structRowTypes{staticletlist="WatchListsInterfaceControllerListRowType"staticletnoLists="WatchListsInterfaceControllerNoListsRowType"}structSegues{staticletlistSelection="WatchListsInterfaceControllerListSelectionSegue"}}// ...}

WKInterfaceObject

WKInterfaceObject resembles a streamlined rendition of UIView, with properties for alpha, hidden, horizontal& vertical alignment, and width& height.

The most striking difference is the lack of a frame. Instead of manually specifying coordinate points or setting up Auto Layout constraints, WatchKit interface objects are laid out in a grid according to their margins and respective ordering, which is reminiscent to working with a CSS framework like Bootstrap (or for you Rubyists out there, remember Shoes?).

Another departure from Cocoa Touch is that Target-Action methods use a fixed-format specific for each type of control, rather than passing a dynamic sender and UIEvent.

For the small, closed set of controls, this approach is really appealing—much better than typing UIControlEventTouchUpInside.

WKInterfaceButton

WKInterfaceButton is an interface object that can be tapped to trigger an action. Its contents can be either a single text label or a group.

That latter part—being able to contain a group—is huge. This avoids one of the biggest gripes folks have with UIButton, the difficulty of adding subviews and having things position and interact correctly, which would otherwise drive people to give up and use UITapGestureRecognizer.

WKInterfaceTable

Of all of the concepts carried over from iOS, tables are perhaps the most-changed.

UITableView is the backbone of iPhone applications. As such, they've evolved significant complexity to handle the demands of applications with a lot of data that needs to be displayed in many different ways. WKInterfaceTable, by comparison, seems marginal by comparison.

WatchKit tables do not have sections or headers, or footers, or editing, or searching, or data sources, or delegates. Rows are pre-populated at WKInterfaceController -willActivate, with each row specifying its own row controller (an NSObject subclass with IBOutlets). WKInterfaceController can respond to table interactions either with the table:didSelectrowAtIndex: delegate method, or using the aforementioned Target-Action method.

It may not seem like much, but this approach is well-suited for the watch, and is a lot more straightforward than on iOS.

WKInterfaceLabel

By contrast, WKInterface is perhaps the least-changed thing carried over from iOS. With support for NSAttributedString, custom fonts, and font scaling, it's pretty much everything you could ask for.

WKInterfaceDate & WKInterfaceTimer

Let us not forget that time is a pretty important concept for watch. As such, WatchKit introduces two new interface objects that are unprecedented in Cocoa or Cocoa Touch: WKInterfaceDate& WKInterfaceTimer.

WKInterfaceDate is a special kind of label that displays the current date or time. WKInterfaceTimer is similar, except that it displays a countdown until a specified date.

Including these two classes does as much to ensure app quality as much as anything else in WatchKit. Given how these essential these tasks are for a watch, and how notoriously bad programmers are at using NSDateFormatter and NSTimer, one can only imagine where we'd be without these.

WKInterfaceSlider & WKInterfaceSwitch

Sliders and Switches are due for a comeback on the watch. Without the benefit of touch gestures, interfaces are resigned to go back to basics. Tap, Tap, On / Off. Tap, Tap, + / -.

WKInterfaceSlider& WKInterfaceSwitch both appear to be well-crafted and rather customizable.

This is, of course, but a superficial reflection into the capabilities of WatchKit. Like I said at the beginning of the article, Apple's official resources for WatchKit have everything you could ever need.

There's a unique brand of modern angst that manifests the moment you decide to buy something online. While there's no English word for it, it translates roughly to "Where is my credit card? What is its number? How badly do I actually want this thing, anyway?".

When you're on an iOS device, this ennui intensifies: there's a good chance you don't have your card with you, and holding your credit card and typing on your phone simultaneously is a feat best left to gymnasts and astronauts. (I'm sort of joking, but also willing to bet Apple has measured this in a lab somewhere.)

And if you're a developer accepting credit card payments in your app, this unfortunate phenomenon is directly correlated to lost revenue.

Apple Pay changes all this. Though a lot of the attention around its launch has focused on physical payments in stores (where customers can use their iPhone to pay at NFC-enabled payment terminals), there's an equally large opportunity for iOS developers to improve the checkout experience in their apps.

Just a reminder: if you're selling digital goods or virtual currencies in your app, you should use In-App Purchases—not Apple Pay—to sell your content (See section 11.2 of the App Store Review Guidelines). You can use Apple Pay for selling physical goods and services.

Obtaining an Apple Merchant ID

You'll have to register an Apple Merchant ID before testing anything out. Before doing this, you should choose a payment provider to actually handle your credit card processing. Apple provides a list of recommended ones at their Apple Pay Developer Page (disclosure: I work for Stripe, one of the recommended companies, but the code in this article doesn't depend on you choosing any specific provider). While your provider should have a specific guide for how to get set up using Apple Pay with their platform, the process looks like this:

• Head to the Certificates, Identifiers, and Profiles section of the Apple Developer center and create a new merchant ID.
• Next, head to the Certificates section and create a new Apple Pay Certificate. This involves uploading a Certificate Signing Request (CSR) to Apple. When you're signing up for a payment processor, they'll typically give you a CSR to use. You can use a CSR that you generate yourself to follow along with this guide, but your payment processor won't be able to decrypt payments made with it and you'll need to redo it later.
• In Xcode, go to the "Capabilities" section of your project settings and turn "Apple Pay" to on. You may have to select the merchant ID you created earlier from the list provided.

Making Your First Charge

Apple Pay will only work on an iOS device capable of using Apple Pay (e.g. iPhone 6/6+, iPad Mini 3, iPad Air 2). In addition, you have to have successfully added the Apple Pay entitlement (described in "Obtaining an Apple Merchant ID") in order to test it in your app. If you'd like to approximate its behavior on the simulator, you can find a testing library that mimics its functionality (with test credit card details) at https://github.com/stripe/ApplePayStubs.

Once you're up and running with a merchant account, getting started with Apple Pay is really straightforward. When it's time to check out, you'll first need to see if Apple Pay is supported on the device you're running and your customer has added any cards to Passbook:

letpaymentNetworks=[PKPaymentNetworkAmex,PKPaymentNetworkMasterCard,PKPaymentNetworkVisa]ifPKPaymentAuthorizationViewController.canMakePaymentsUsingNetworks(paymentNetworks){// Pay is available!}else{// Show your own credit card form.}

Assuming Apple Pay is available, the next step is to assemble a PKPaymentRequest. This object describes the charge you're requesting from your customer. If you're requesting payment in the U.S. (reasonable, as Apple Pay is currently US-only), here's some default options you'll need to set that'll likely stay constant:

letrequest=PKPaymentRequest()request.supportedNetworks=[PKPaymentNetworkAmex,PKPaymentNetworkMasterCard,PKPaymentNetworkVisa]request.countryCode="US"request.currencyCode="USD"request.merchantIdentifier="<#Replace me with your Apple Merchant ID#>"request.merchantCapabilities=.Capability3DS

Next, describe the things the customer is actually buying with the paymentSummaryItems property. This takes an array of PKPaymentSummaryItems, which have a label and amount. They're analogous to line items on a receipt (which we'll see momentarily).

letwax=PKPaymentSummaryItem(label:"Mustache Wax",amount:NSDecimalNumber(string:"10.00"))letdiscount=PKPaymentSummaryItem(label:"Discount",amount:NSDecimalNumber(string:"-1.00"))lettotalAmount=wax.amount.decimalNumberByAdding(discount.amount).decimalNumberByAdding(shipping.amount)lettotal=PKPaymentSummaryItem(label:"NSHipster",amount:totalAmount)request.paymentSummaryItems=[wax,discount,shipping,total]

Note that you can specify zero or negative amounts here to apply coupons or communicate other information. However, the total amount requested must be greater than zero. You'll note we use a PKShippingMethod (inherits from PKPaymentSummaryItem) to describe our shipping item. More on this later.

Next, to display the actual payment sheet to the customer, we create an instance of PKPaymentAuthorizationViewController with our PKPaymentRequest and present it. (Assume for this example that all this code is inside a UIViewController that will sit behind the payment screen).

letviewController=PKPaymentAuthorizationViewController(paymentRequest:request)viewController.delegate=selfpresentViewController(viewController,animated:true,completion:nil)

A few style nits to be aware of:

• The view controller doesn't fully obscure the screen (in this case the blue background is part of our application). You can update the background view controller while the PKPaymentAuthorizationViewController is visible if you want.
• All text is automatically capitalized.
• The final line item is separated from the rest, and is intended to display the total amount you're charging. The label will be prepended with the word "PAY", so it usually makes sense to put your company name for the payment summary item's label.
• The entire UI is presented via a Remote View Controller. This means that outside the PKPaymentRequest you give it, it's impossible to otherwise style or modify the contents of this view.

PKPaymentAuthorizationViewControllerDelegate

In order to actually handle the payment information returned by the PKPaymentAuthorizationViewController, you need to implement the PKPaymentAuthorizationViewControllerDelegate protocol. This has 2 required methods, -(void)paymentAuthorizationViewController:didAuthorizePayment:completion: and -(void)paymentAuthorizationViewControllerDidFinish:.

To understand how each of these components work, let's check out a timeline of how an Apple Pay purchase works:

• You present a PKPaymentAuthorizationViewController as described above.
• The customer approves the purchase using Touch ID (or, if that fails 3 times, by entering their passcode).
• The thumbprint icon turns into a spinner, with the label "Processing"
• Your delegate receives the paymentAuthorizationViewController:didAuthorizePayment:completion: callback.
• Your application communicates asynchronously with your payment processor and website backend to actually make a charge with those payment details. Once this complete, you invoke the completion handler that you're given as a parameter with either PKPaymentAuthorizationStatus.Success or PKPaymentAuthorizationStatus.Failure depending on the result.
• The PKPaymentAuthorizationViewController spinner animates into a success or failure icon. If successful, a notification will arrive from PassBook indicating a charge on the customer's credit card.
• Your delegate receives the paymentAuthorizationViewControllerDidFinish: callback. It is then responsible for calling dismissViewControllerAnimated:completion to dismiss the payment screen.

Concretely, this comes out looking like this:

// MARK: - PKPaymentAuthorizationViewControllerDelegatefuncpaymentAuthorizationViewController(controller:PKPaymentAuthorizationViewController!,didAuthorizePaymentpayment:PKPayment!,completion:((PKPaymentAuthorizationStatus)->Void)!){// Use your payment processor's SDK to finish charging your customer.// When this is done, call completion(PKPaymentAuthorizationStatus.Success)}funcpaymentAuthorizationViewControllerDidFinish(controller:PKPaymentAuthorizationViewController!){dismissViewControllerAnimated(true,completion:nil)}

Here, the processPayment:payment completion: method is your own code, and would leverage your payment processor's SDK to finish the charge.

Dynamic Shipping Methods and Pricing

If you're using Apple Pay to let your customer buy physical goods, you might want to offer them different shipping options. You can do this by setting the shippingMethods property on PKPaymentRequest. Then, you can respond to your customer's selection by implementing the optional PKPaymentAuthorizationViewControllerDelegate method, paymentAuthorizationViewController:didSelectShippingMethod:completion:. This method follows a similar pattern to the didAuthorizePayment method described above, where you're allowed to do asynchronous work and then call a callback with an updated array of PKPaymentSummaryItems that includes the customer's desired shipping method. (Remember from earlier that PKShippingMethod inherits from PKPaymentSummaryItem? This is really helpful here!)

Here's a modified version of our earlier example, implemented as a computed property on the view controller and helper function:

varpaymentRequest:PKPaymentRequest{letrequest=...// initialize as beforeletfreeShipping=PKShippingMethod(label:"Free Shipping",amount:NSDecimalNumber(string:"0"))freeShipping.identifier="freeshipping"freeShipping.detail="Arrives in 6-8 weeks"letexpressShipping=PKShippingMethod(label:"Express Shipping",amount:NSDecimalNumber(string:"10.00"))expressShipping.identifier="expressshipping"expressShipping.detail="Arrives in 2-3 days"request.shippingMethods=[freeShipping,expressShipping]request.paymentSummaryItems=paymentSummaryItemsForShippingMethod(freeShipping)returnrequest}funcpaymentSummaryItemsForShippingMethod(shipping:PKShippingMethod)->([PKPaymentSummaryItem]){letwax=PKPaymentSummaryItem(label:"Mustache Wax",amount:NSDecimalNumber(string:"10.00"))letdiscount=PKPaymentSummaryItem(label:"Discount",amount:NSDecimalNumber(string:"-1.00"))lettotalAmount=wax.amount.decimalNumberByAdding(discount.amount).decimalNumberByAdding(shipping.amount)lettotal=PKPaymentSummaryItem(label:"NSHipster",amount:totalAmount)return[wax,discount,shipping,total]}// MARK: - PKPaymentAuthorizationViewControllerDelegatefuncpaymentAuthorizationViewController(controller:PKPaymentAuthorizationViewController!,didSelectShippingMethodshippingMethod:PKShippingMethod!,completion:((PKPaymentAuthorizationStatus,[AnyObject]!)->Void)!){completion(PKPaymentAuthorizationStatus.Success,paymentSummaryItemsForShippingMethod(shippingMethod))}

In this example, the customer will get the option to choose either free or express shipping—and the price they're quoted will adjust accordingly as they change their selection.

But wait, there's more!

Instead of having to provide a bunch of flat-rate shipping options, you can let your customer choose their shipping address and then calculate shipping rates dynamically based on that. To do that, you'll first need to set the requiredShippingAddressFields property on your PKPaymentRequest. This can represent any combination of PKAddressField.Email , .PhoneNumber, and .PostalAddress.

Alternatively, if you don't need the user's full mailing address but need to collect some contact information (like an email address to send receipts to), this is a good way to do it.

When this field is set, a new "Shipping Address" row appears in the payment UI that allows the customer to choose one of their saved addresses. Every time they choose one, the (aptly named) paymentAuthorizationViewController:didSelectShippingAddress:completion: message will be sent to your PKPaymentAuthorizationViewControllerDelegate.

Here, you should calculate the shipping rates for the selected address and then call the completion callback with 3 arguments:

1. The result of the call
   • PKPaymentAuthorizationStatus.Success if successful
   • `PKPaymentAuthorizationStatus.Failure` if a connection error occurs
   • .InvalidShippingPostalAddress if the API returns an empty array (i.e. shipping to that address is impossible).
2. An array of PKShippingMethods representing the customer's available shipping options
3. A new array of PKPaymentSummaryItems that contains one of the shipping methods

I've set up a really simple web backend that queries the EasyPost API for shipping rates to a given address. The source is available at https://github.com/jflinter/example-shipping-api.

Here's a function to query it, using Alamofire:

importAddressBookimportPassKitimportAlamofirefuncaddressesForRecord(record:ABRecord)->[[String:String]]{varaddresses:[[String:String]]=[]letvalues:ABMultiValue=ABRecordCopyValue(record,kABPersonAddressProperty).takeRetainedValue()forindexin0..<ABMultiValueGetCount(values){ifletaddress=ABMultiValueCopyValueAtIndex(values,index).takeRetainedValue()as?[String:String]{addresses.append(address)}}returnaddresses}funcfetchShippingMethodsForAddress(address:[String:String],completion:([PKShippingMethod]?)->Void){letparameters=["street":address[kABPersonAddressStreetKey]??"","city":address[kABPersonAddressCityKey]??"","state":address[kABPersonAddressStateKey]??"","zip":address[kABPersonAddressZIPKey]??"","country":address[kABPersonAddressCountryKey]??""]Alamofire.request(.GET,"http://example.com",parameters:parameters).responseJSON{(_,_,JSON,_)inifletrates=JSONas?[[String:String]]{letshippingMethods=map(rates){(rate)->PKShippingMethodinletidentifier=rate["id"]letcarrier=rate["carrier"]??"Unknown Carrier"letservice=rate["service"]??"Unknown Service"letamount=NSDecimalNumber(string:rate["amount"])letarrival=rate["formatted_arrival_date"]??"Unknown Arrival"letshippingMethod=PKShippingMethod(label:"\(carrier) \(service)",amount:amount)shippingMethod.identifier=identifiershippingMethod.detail=arrivalreturnshippingMethod}}}}