6. The Keyboard

Written by Andy Pereira

The physical keyboard is something that has always been part of the personal computer experience. But, when iOS was introduced, it almost seemed like the idea of a software keyboard would take over. Luckily, for those that like a real keyboard, Apple introduced support not only for physical keyboards on iOS but keyboard shortcuts.

While keyboards shortcuts might go overlooked on iOS apps, macOS users expect them. In this chapter, you’ll learn how to add shortcuts, what modifier keys are, and how to combine them with key combinations to quickly perform tasks in your app.

Getting started

Open the starter project for the chapter. It will be best if you can run this app on a physical iOS or iPadOS device, with a physical keyboard paired with the device. Using the simulator will work, but you may notice some performance issues.

First responders

Before you add the shortcuts, it will help to understand a little bit about the responder chain and the first responder. UIViewControllers, UIViews and UIApplication are all classes that can receive and handle events, otherwise known as responder objects. Since you can add keyboard shortcuts to any of these kinds of classes, you’ll need to tell the system which responder is the class in the responder chain that will receive the keyboard event first. This is referred to as the first responder.

To start, open RootSplitViewController.swift and add the following:

// MARK: - Keyboard Commands
override var canBecomeFirstResponder: Bool {
  return true
}

Now, when you perform a keyboard shortcut, RootSplitViewController will be able to receive and respond to it.

Adding the commands

Keyboard shortcuts can be performed by simply pressing a single key on the keyboard or multiple keys. They can also be used in conjunction with modifiers keys, like Command, Control and Option. You’re going to add three shortcuts that each use modifier keys.

Open RootSplitViewController.swift and add the following methods:

@objc private func addEntry(sender: UIKeyCommand) {
}

@objc private func goToPrevious(sender: UIKeyCommand) {
}

@objc private func goToNext(sender: UIKeyCommand) {
}

For now, these don’t do anything. You need them because keyboard shortcuts need actions to call. You’ll come back to this later in the chapter.

Now you can start adding key commands. Add the following in RootSplitViewController.swift:

override var keyCommands: [UIKeyCommand]? {
  let newKeyCommand
    = UIKeyCommand(input: "N",
                   modifierFlags: .control,
                   action: #selector(addEntry(sender:)))
  newKeyCommand.discoverabilityTitle = "Add Entry"
  return [newKeyCommand]
}

Here, you’ve added a key command for adding a new entry. It’s important to know what is happening:

• input: This is the actual key that will trigger the action to be called.
• modifierFlags: In this example, you’ve added .control, which means your shortcut will be performed by pressing Control-N.
• action: This is the method called when the shortcut is performed.
• discoverabilityTitle: When you have a physical keyboard attached to your iOS device, holding Command down will show the Discoverability window or layer. It lists all the keyboard shortcuts available in the current application. Adding the discoverabilityTitle is required to list the shortcut in the Discoverability window.

Overriding keyCommands is how you inform the responder chain what key commands the current responder supports. It is important to note that the system reserves certain key commands for itself, which you cannot override. For example, Cut, Copy and Paste’s key combinations cannot be changed for yourself. Because Command-N is reserved for opening a new window, you use the modifier to make Control-N create the entry.

Build and run, and hold down Command to make the Discoverability window appear.

To get the application to add an entry when using the key combination, add this line to addEntry:

DataService.shared.addEntry(Entry())

Build and run, and then press Control-N. You should now see a new entry show up in the list.

To get the remaining key commands set up, replace keyCommands with the following:

override var keyCommands: [UIKeyCommand]? {
  let newKeyCommand
    = UIKeyCommand(input: "N",
                   modifierFlags: .control,
                   action: #selector(addEntry(sender:)))
  newKeyCommand.discoverabilityTitle = "Add Entry"
  let upKeyCommand
    = UIKeyCommand(input: "[",
                   modifierFlags: [.command, .shift],
                   action: #selector(goToPrevious(sender:)))
  upKeyCommand.discoverabilityTitle = "Previous Entry"
  let downKeyCommand
    = UIKeyCommand(input: "]",
                   modifierFlags: [.command, .shift],
                   action: #selector(goToNext(sender:)))
  downKeyCommand.discoverabilityTitle = "Next Entry"
  return [newKeyCommand, upKeyCommand, downKeyCommand]
}

The final two key commands will allow the user to select the previous or next entry in the entry list. While almost the same as newKeyCommand, these take multiple modifier keys to perform. It requires Command-Shift-[ to be pressed to go back in the list, and Command-Shift-] to move forward.

While you can decide which modifiers are used, remember to keep the combinations simple enough for your user to remember.

Build and run, and hold down Command to show the Discoverability window. You should now see all three of your keyboard shortcuts:

Now, your last step is to actually do something when the keys are pressed. Open RootSplitViewController.swift and add this code to goToPrevious:

guard let navigationController =
  viewControllers.first as? UINavigationController,
  let mainTableViewController =
  navigationController.topViewController
    as? MainTableViewController else { return }
mainTableViewController.goToPrevious()

And add this code to goToNext:

guard let navigationController =
  viewControllers.first as? UINavigationController,
  let mainTableViewController =
  navigationController.topViewController
    as? MainTableViewController else { return }
mainTableViewController.goToNext()

Now, open MainTableViewController.swift, and add the following methods:

func goToPrevious() {
  guard let index = indexOfCurrentEntry(),
    index > 0 else { return }
  let previousIndex = index - 1
  let indexPath = IndexPath(row: previousIndex,
                            section: 0)
  tableView.selectRow(at: indexPath,
                      animated: false,
                      scrollPosition: .middle)
  performSegue(withIdentifier: "ShowEntrySegue",
               sender: tableView.cellForRow(at: indexPath))
}

func goToNext() {
  guard let index = indexOfCurrentEntry(),
    index < DataService.shared.allEntries.count - 1 else { return }
  let nextIndex = index + 1
  let indexPath = IndexPath(row: nextIndex,
                            section: 0)
  tableView.selectRow(at: indexPath,
                      animated: false,
                      scrollPosition: .middle)
  performSegue(withIdentifier: "ShowEntrySegue",
               sender: tableView.cellForRow(at: indexPath))
}

When performing the “Previous Entry” and “Next Entry” shortcuts, these methods will handle going to the previous and next entries.

Build and run, and try using the keyboard shortcuts. Press Control-N to add a few entries, and Command-Shift-[ and Command-Shift-] to move through the list.

Last, add the final keyboard shortcut to delete an entry. In RootSplitViewController.swift, add the following to the end of keyCommands replacing the existing return line:

let deleteKeyCommand
  = UIKeyCommand(input: "\u{8}",
                 modifierFlags: [],
                 action: #selector(removeEntry(sender:)))
deleteKeyCommand.discoverabilityTitle = "Delete Entry"

return [newKeyCommand, upKeyCommand, 
  downKeyCommand, deleteKeyCommand]

This will add the shortcut to delete an entry when pressing the Delete key. To display the macOS system symbol for Delete, and respond to it being pressed, you use the Unicode symbol for BACKSPACE, which is 8.

Then, add the following method in the same file:

@objc private func removeEntry(sender: UIKeyCommand) {
  guard let navigationController = viewControllers.first
    as? UINavigationController,
    let mainTableViewController 
      = navigationController.topViewController
      as? MainTableViewController else { return }
  mainTableViewController.deleteCurentEntry()
}

Finally, add the following method to MainTableViewController.swift:

func deleteCurentEntry() {
  guard let index = indexOfCurrentEntry() else { return }
  DataService.shared.removeEntry(atIndex: index)
}

The last thing you’ve added here supports responding to the keyboard shortcut and deleting the entry that is selected in the table view.

The examples in this chapter used an input that directly relates to what you see on the keyboard or its Unicode symbol. However, there are constants defined for a few keys which you’ll need to use if you want to respond to Escape or any of the directional arrows:

• UIKeyCommand.inputUpArrow
• UIKeyCommand.inputDownArrow
• UIKeyCommand.inputLeftArrow
• UIKeyCommand.inputRightArrow
• UIKeyCommand.inputEscape

Where to go from here?

Your app is now set to handle shortcuts. While Catalyst will automatically handle these keyboard shortcuts, you’ll learn later on how to make sure these shortcuts are shown in the Menu bar.

You can learn more about UIKeyCommand on Apple’s website: https://developer.apple.com/documentation/uikit/uikeycommand

There’s more you can learn about the responder chain, as well, from Apple’s website: https://developer.apple.com/documentation/appkit/nsresponder