UIKeyCommand — Part 3: macOS Catalyst Menu Items

This is the final post in a series on adding UIKeyCommands (keyboard shortcuts) to an iOS app. In this post, we’ll cover how to add menu bar items to a macOS Catalyst app using UIKeyCommands.

This will not be a full tutorial on how to add menu items to macOS Catalyst apps. Instead, this post will demonstrate that you can use the same keyboard shortcuts created in part two and create menu items.

In macOS Catalyst apps, your UIApplicationDelegate class (usually AppDelegate) will configure the menu bar. This is handled in the func buildMenu(with builder: UIMenuBuilder)  method (documentation). In this method, you can add and remove menu items and sub menu items.

You can download the corresponding sample app here (the branch is part-3-catalyst). I slightly refactored the code that creates the UIKeyCommand to be a class level variable on the two view controllers. They can now be easily accessed like: TableViewController.showTableAlert.

Use the existing UIKeyCommand objects in a UIMenu initializer and then added to the builder object in the buildMenu method (from above) like this:

let menu = UIMenu(title: "Show",
				  identifier: .show,
                  options: .displayInline,
                  children: [TableViewController.showTableAlert,
                             DetailViewController.showDetailAlert])

builder.insertChild(menu, atStartOfMenu: .file)

This little block of code adds the “Show Table” and “Show Detail” menu items. When you run the app, it will look like this.

Resulting menu

That’s it. That’s really all there is to it to take existing keyboard shortcuts and add them to a macOS Catalyst app as menu items.

UIKeyCommand object are incredibly versatile in the situations we’ve gone over in this series. They can be added to both simple and more complex apps. They can also be used in macOS Catalyst apps to provide menu bar items.

Part 1 | Part 2

UIKeyCommand — Part 2: Split View Controller

In the first post in this UIKeyCommands series, we went over the basics of UIKeyCommands and adding keyboard shortcuts to an app. Adding keyboard shortcuts to a real app can be a little more complicated, but not much.

First, some background

My latest update of Beer Style Guidelines has these keyboard shortcuts reenabled. A long time ago, I had keyboard shortcuts enabled within the app. At that time, I didn’t have a clear understanding of how they worked. This lack of understanding meant that the keyboard shortcuts didn’t quite work the way I expected them to (or at all sometimes).

I became frustrated with my lack of understanding and I just disabled the keyboard shortcuts. I didn’t have a lot of time to investigate and figure out what was wrong. But I was determined to figure it out. Recently, I had purchased an iPad Air (4th Generation) and an Apple Magic Keyboard. This gave me the kick in the butt to get the keyboard shortcuts working again.

Getting the keyboard shortcuts working wasn’t a lot of work. I just lacked an understanding of how to put it all together. I hope to impart some of that wisdom in this post.

Beer Style Guidelines has a Split View Controller view architecture.

Split View Controller Wireframe

In my first iteration of keyboard shortcuts, I had two or three commands. They were all triggered from the Detail View Controller (the large part of the screen). I wanted to add more keyboard shortcuts, but I was paralyzed with not knowing how to proceed.

Ok. So, what was holding me up? I wasn’t sure which view controller in the app I needed to implement the keyboard command. Did I need to add them all to my Split View Controller class? Did I need to implement the commands in one view controller or the other, based on a user’s focus?

I started by adding the commands to the split view controller class. But it turns out that isn’t the correct answer. The correct answer is that you implement the keyboard commands wherever you need them, and let the Responder Chain take care of the rest.

Responder Chain? What?

In iOS, there is this thing called the responder chain. The responder chain is how iOS (and UIKit) determine how to handle events. This chain starts with the first responder and then traverses the rest of the chain looking to handle the event. In the case of UIKeyCommands, UIKit will traverse the responder chain and collect the UIKeyCommands for the current scenario.

This WWDC video (Support hardware keyboards in your app) does a fantastic job of explaining all of this. It’s also super short. I only discovered the video after I figured out how this works.

You may have noticed that the UIApplicationDelegate class (usually called AppDelegate) is a subclass of UIResponder. What you may not have noticed is that all UIViewControllers and even UIViews subclass UIResponder.

Back to UIKeyCommand

Getting back to where to implement the keyboard shortcuts. I ended up implementing the keyboard shortcuts for the list view (search, change guide, etc), in the list view controller. The keyboard shortcuts used in the detail view controller (like toggle favorite, next/previous section, etc) were implemented there.

Like in part one, I’ve created a sample app to put this into practice. This sample app uses a Split View Controller and implements keyboard shortcuts where it makes sense. The sample app only has a few keyboard shortcuts.

The list view controller has two keyboard shortcuts and so does the detail view controller.

You may notice something strange about these keyboard shortcuts. Both have the “Show Info” keyboard shortcut. I did this as a test more than anything. I wanted to see what would happen if there are duplicate keyboard shortcuts. Likewise, I also wanted to see where this was called from when triggered. I discovered that found that the keyboard shortcut in the detail view controller usually wins. I think that’s because it’s the first responder in the chain that responds to this command.

This may feel a bit overwhelming. But it’s not very difficult. The sample app should give you a better idea of how easy it is to implement keyboard shortcuts in a split view controller.

There’s one more post in this series. Next time, we’ll stray away from iOS slightly to use UIKeyCommands to add menu items to a macOS Catalyst app.

Part 1 | Part 3

UIKeyCommand — Part 1: The Basics

This post is the first in a series of three on UIKeyCommands on iOS. In this first post, we’ll go over UIKeyCommand at a high level.

What are UIKeyCommands?

UIKeyCommands represent a key press (or combination of key presses) on a hardware keyboard that will trigger an action. In short, you can think of these as keyboard shortcuts. The system already has a few built-in keyboard shortcuts. Some of these are keyboard shortcuts are Cut (⌘ + x), Copy (⌘ + c), and Paste (⌘ + v).

Beginning in iOS 7, Apple started allowing developers to implement keyboard shortcuts. The system already handles Cut, Copy and Paste and developers won’t need to implement these.

These keyboard shortcuts have been around for a few years. So, it’s easy to see how other developers have implemented these. A great way to discover what keyboard shortcuts apps have is to launch the app, and then hold down the command (⌘) key. Here’s an example from my app Beer Style Guidelines.

iPad Keyboard Shortcut Discovery

How do I implement my own UIKeyCommand?

There are two parts to implement UIKeyCommands in your app. First, is the UIKeyCommand object itself. Then these UIKeyCommands need to be integrated into the app.

The initializer for UIKeyCommand has a lot going on. You don’t need to use every parameter. Here are the minimum parameters to create a UIKeyCommand object. Those parameters are:

  • title: This is the display title of the keyboard shortcut.
  • action: This parameter points to the method that gets called from this shortcut.
  • input: This is the keyboard key (a string) that is part of the keyboard shortcut. For example, the “c” in the Copy shortcut (⌘ + c)
  • modifierFlags: This is the modifying key that is the other part of the keyboard shortcut. For example, the “⌘” in the Copy shortcut (⌘ + c)

Putting all of this together, you can create a keyboard shortcut like this:

let infoCommand = UIKeyCommand(title: "Show Info",
                               action: #selector(showInfo),
                               input: "i",
                               modifierFlags: .command)

In this example, the user will trigger a keyboard shortcut to show info when they use ⌘ + i. This will show them an iOS alert with a simple message in it.

I’ve created a sample app that pulls all the various pieces together. The sample app, is simple. It has a single keyboard shortcut. You can discover this just like keyboard shortcuts in other iOS apps.

Download and run the sample app. Once launched, hold down on the Command key (⌘) until you see the prompt showing the single keyboard shortcut within the app.

Testing in the simulator.

If nothing shows up, and you’re testing this in the simulator, you may need to enable “Send Keyboard Input to Device” in the simulator. This can be done through the menu system by selecting I/O → Input → Send Keyboard Input to Device. Or, you can click on this button in the toolbar (below) of the simulator. Without doing this, sometimes the keyboard shortcuts can be lost, and it will seem like the keyboard shortcuts are not working.

Send Keyboard Input to Device

That’s it. Keyboard shortcuts are straightforward to set up and get working in your apps. Next time we’ll get a little more in-depth on UIKeyCommand.

Part 2 | Part 3

General Update: March 2021

It’s been a busy month. I’m not even sure where the month went. I figured I’d post a general update on what I’ve been up to.

Development Updates

I’ve been super busy at work, working on a new (to us) property. I’m not sure if I can announce what that property is yet, so I won’t. Once it launches, I’ll probably post an update here with more info.

As far as personal projects go, I’ve shipped a large update to Beer Style Guidelines. This update includes the Brewers Association 2021 Beer Style Guidelines. The release notes are here. I love updating the app with new guides as they come out, but I always forget how much work it is. I do a fair bit of testing the guide out before I release it, but I just know that I’m going go missing something.

This last few weeks, I’ve been really busy working on a few server components to another update to Beer Style Guidelines. It’s not ready yet and users shouldn’t notice any difference in how the app works. But this new set of server components it building towards some future features.

Gaming Updates

I haven’t been playing many video games this month. I’ve been so busy with the development updates above, it doesn’t leave a lot of time for playing video games at night.

I’ve dabbled in a few new games, but nothing has really hooked me. I think if a game hooked me, I’d find a way to play the game more.

Some of the games I’ve started:

I probably spent the most time playing LEGO Harry Potter Collection. I love LEGO games, they aren’t usually hard, and I can let my mind wander a bit while playing through them.

I stared Gears of War, but didn’t make it too far in. I’ve played through this game a few times, years ago. I have a lot of fond memories playing through these with my brother. But I just couldn’t really get into it again.

I finished the Pikmin 3 demo, but not sure I’m ready for the full game yet. I love the early game of Pikmin games, but I always get to a point where I get frustrated with the games. It’s probably because I’m bad at video games. I’m still debating whether I want to get this game or not.

I tried Hollow Knight. I’ve heard so many good things about it. It made me realize (even more) that I’m bad at video games. I couldn’t even get past the first boss (False Knight) before getting frustrated and giving up. I feel like I should keep at it, but I am just so bad at this game.

Book Update

I’ve read a handful of books this month. Looking back at the list, it was more than I expected. I listen to most of my books. It makes it much easier to enjoy books while I go for walks, runs, or while driving in the car.

In March, I finished these books:

Bossypants was a fun, quick read. I like Tina Fey and the work she’s done. This book was written during her time working on 30 Rock (which was a great show). Tina is also an Eagles fan, so that helps immensely.

I am a big fan of the new Star Wars: The High Republic content that’s been coming out this year. It’s an entirely new era being discovered in Star Wars. I’ve been keeping up with the novels and comic books in this ear and have really been enjoying them. I listened to about half of this book in a single day during a long road trip.

I really enjoyed the art style in Star Wars: The Rise of Skywalker Graphic Novel Adaptation. The graphic novel adaptation gets the bulk of the story across from the movie and the (non-graphic) novel adaptation. I still enjoying reading comics on my iPad. Although, I only really list the graphic novels or omnibuses on my list of books I’ve read.

The Lead Developer book was an impulse read of mine. I saw it promoted by some iOS developers I follow on Twitter, so I decided to buy it. The book is a good first version. There were a handful of typos throughout the book, but I could easily see past those. But the book does give a good overview of what a lead developer’s responsibilities are and some practical tips on how to survive as one. This is a relatively short book that I read in 3 or 4 sittings.

Wrapping up

This has been quite a busy month. I didn’t even cover the movies and TV shows that we’ve been watching. Maybe I’ll cover that in a different post, maybe not.

I hope to provide more frequent updates on the site. But I’m not always great with that.

Super Mario Odyssey

Super Mario Odyssey Screenshot

This past weekend, I finished playing through Super Mario Odyssey on the Nintendo Switch. The game flew by for me. I hadn’t even realized I was near the end of the story, and there I was. 

There isn’t a lot to the plot. If you’ve played any other Super Mario games, this one has a very similar plot. Princess Peach was kidnapped by Bowser and it’s up to you to rescue her. It’s not very imaginative. But playing the game is a lot of fun.

Once you’ve finished the game, you can go back to all of the worlds and attempt to collect Power Moons. I did not collect every Power Moon in the game. I’m not sure if I’ll even go back and play through more. I had just enough fun playing through the main storyline. It was the perfect amount for me.

It was a very fun game. It also wasn’t too difficult to get through the main storyline. I’d recommend this for anyone who enjoys 3D Super Mario games. 

I also have Super Mario Galaxy on the Nintendo Switch. I never played through this when it was out on the Wii. I’m not sure if I want to play through that or look for something else to play.