Support hardware keyboards in your app

Hello and welcome to WWDC.

My name is James Magahern. I'm from the iOS Keyboards team, and I'm here to give you a brief primer on how to make your app a first-class app on devices with hardware keyboards.

iOS applications have always embraced user interfaces designed all around touch, which is a truly excellent way to interact with content. Discovering UI in your application is as easy as just showing something on the screen. iPad users with hardware keyboards attached, however, have become quite common. Embracing hardware-keyboard support in your application allows your users to become more productive and navigate your UI more quickly and ergonomically. They can leverage muscle memory to execute functions without even thinking about it. Also, by implementing standard system shortcuts, novice users can approach your application with a familiar, consistent interface armed with expectations brought from the Mac. To be a first-class app on a next-generation computing platform like the iPad, your application should excel at both touch and hardware-keyboard interactions.

Here's a quick setup for what we're gonna be talking about today. Let's jump right in and talk about keyboard shortcuts.

To go briefly over how keyboard shortcuts work on iOS, let's first talk about UIKeyCommand. UIKeyCommand is an object that represents a custom keyboard shortcut in your application. It has all the properties that you might expect, such as the discoverability title shown to the user, what keyboard input is required to invoke it, and optionally, a set of modifierFlags defining which modifier keys should be held.

This fits together with your UI by returning an array of key commands via an overridable property called keyCommands on UIResponder, where you return an array of all the commands for that particular responder. Most common UIKit widgets are subclasses of UIResponder already, so in most cases, extending your application to include these key commands should be as simple as just overriding this one property and returning whatever key commands are relevant for that particular part of your UI. The way this all fits together in your application is via the responder chain. The responder chain loosely follows the view hierarchy of your application, with the UIApplication instance at the very end and the responder the user is currently interacting with at the beginning. Your application's first responder is the UIResponder object in which all keyboard events first funnel into. If a responder in the chain isn't able to handle a particular event, the event goes further up the chain. UIViews, for example, have their designated next responder in the chain as the view's superview.

Key commands are then collected by the application from each responder via the keyCommands method that you override, starting with the application's first responder and ending up at the top-level UIApplication instance.

Once all of your key commands are collected by the system, users will be able to discover them via the discoverability heads-up display, which is accessible by holding the Command key anywhere in the system. This is great, not only for your users to be able to discover keyboard shortcuts, but it's also handy during development to be able to test and inspect all of them in one place.

Now let's take a look at how all this fits together in practice. Let's take the Music app as an example.

When the Music app is in the foreground, the user can press the space bar to easily toggle the playback of the currently playing song.

This works consistently across all apps that do media playback of any kind, such as when playing videos in the Photos app or for QuickTime videos in Safari.

Following the model-view-controller pattern, the ideal place to define this behavior is in your custom view controller subclass.

In this example, we have a player view controller subclass of UIViewController, which manages playback in our application and whose view contains things like the play button. Because all UIViewControllers are UIResponders, all I need to do is override a few methods here to allow this to start accepting keyboard shortcuts.

First, override canBecomeFirstResponder and return true.

Then, override viewDidAppear and call becomeFirstResponder to make sure this view controller is first responder when it first appears.

Lastly, override the keyCommands property to return our custom space-bar keyboard shortcut. Here you can see we provide a localized string to show in the discoverability HUD which action to perform when it's invoked in the form of a selector and which input is required. In this case, a string just containing space to indicate this is for the space bar.

You're getting really excited right about now, thinking about adding some commonly used keyboard shortcuts to your app that your users are expecting from other apps. For example, if you're working on a music library application, you'll want to add a few shortcuts that would make it faster to interact with songs and playlists, such as select all, copy, and paste.

Or if you're working on an illustration app, for example, you'll want to have things like Command-Plus for zooming in and Command-Minus for zooming out. Well, fortunately, for many of these commonly used keyboard shortcuts, you don't even need to create a single UIKeyCommand. All you need to do is override a couple of methods. Every UIResponder subclass conforms to a protocol called UIResponderStandardEditActions, which can respond to any method listed here. All you need to do is override the relevant method. You don't have to create a single UIKeyCommand. Here's a quick example. In your UIResponder subclass, our UITableViewController subclass here, we just need to override the same two methods that we did before to make sure it can become first responder. As always, this will be required if you decide to implement this inside of your view controller subclass. Then you can override any of the methods mentioned on the previous slide, such us select all, copy, paste, and a few others, all without creating a single UIKeyCommand. Check out the documentation on UIResponderStandardEditActions for more commands and for more information.

UIKeyCommand was designed with Catalyst in mind. Making all these new key commands work with the macOS Menu bar is extremely easy. For the UIResponderStandardEditActions I mentioned on the previous slide, you get those for free. But for custom UIKeyCommands, luckily, UIKeyCommand is a subclass of UICommand,