Your guide to keyboard layout

♪ ♪ Hi. My name is Kasia Wawer. I'm an engineer on the Keyboards UI team, and today, I'll be your guide to the wonderful world of keyboard layout. I am incredibly excited to talk to you today about bringing the keyboard from a frame-based past into an auto-layout future. We'll start our tour by talking about the new guide. Then, we'll go over some of the new things you'll be able to do to more fully integrate the keyboard into your layout. And finally, we'll talk about what a keyboard really is-- philosophically speaking, types of keyboards to consider, and some of the cases you might not think about right away. So, let's get started with our tour. As with many things, this one begins in the ancient past. If you have worked with the keyboard in your app before, you know the way that it's been handled since time immemorial is by registering for notifications, deriving the appropriate offsets and animations from the information in the notification, doing some math, and finally, using that to adjust your layout. Now, notifications are sticking around. We are not deprecating them. You can learn more about them, if you're interested, in "The Keys to a Better Text Input Experience" from 2017. Let's look at a quick example of how notifications might be used with a custom guide. Now, don't copy any of this code because we're about to replace it. But here's how you handle the keyboard before iOS 15. You'd create your custom guide and anchors to respond to notifications. Then, you'd register for the appropriate notifications. Usually, at least willShow and willHide, but sometimes frame changes, etc. Then, you'd respond to said notifications by getting the frame information from the notification, making sure that you're adjusting for your own views and the safe area guide, if the keyboard is leaving the screen. And you'd get the animation info from the notification and, finally, change your guide to match. Now, it's not a ton, but it can get complicated quickly. Today, I am happy to announce a brand-new addition to the auto layout collection: UI keyboard layout guide. Now, try to constrain your excitement as we dive into this. Keyboard layout guide is brand-new in iOS 15. It's a layout guide. You can constrain the views and guides in your existing layout to it. If you're not familiar with layout guides, a layout guide is a way to represent space in a layout without using a view. It has all the same anchors as a view. The keyboard layout guide will represent the space that the keyboard occupies in your app so that your layout can account for it. And that's it! Mostly. Let's talk about updating that code we just saw to use this instead. Here's that notifications code. Don't copy it yet, wait for the green checkmark. So, now you can go ahead and remove that anchor you were tracking. And change from your layout guide to the view's keyboardLayoutGuide.

And we don't need to register for notifications anymore. And we don't need to respond to them either. And that's it. All that code boils down to this single line. Ready to see it in action? Here's what it looks like to bring up the keyboard when using the notifications code. And here's what it looks like to bring it up using the guide.

You may have noticed that, other than their localizations, those looked virtually identical, but that's kinda the point. You don't have to do nearly as much, and you get the same result. So, let's talk about updating to the guide. It's a property on UI view. And, for most cases, you'll just update to using the guide's topAnchor. The guide matches keyboard animations, like bring up and dismiss, and it follows height changes too. Because sometimes the keyboard is taller, and sometimes it's shorter. But the guide will adapt to fit whatever size appears. And, when the keyboard is undocked, by default, the guide will drop to the bottom of the screen and be the width of your window, and anything you've tied to the top anchor will follow. It accounts for safe-area insets, so you don't have to worry about that anymore, either. For basic uses, that's probably all you need to know. But now we get to talk about the fun stuff. Why did we choose to use a new class and not just a normal layout guide? Well, we wanted you to be able to do more than you've ever been able to do with the keyboard. Our next stop is full keyboard integration into your app. Why do I say "integration"? Well, I have often heard people talking about the keyboard as something they need to avoid, or as something fighting with their layout, but the keyboard is part of your app. One of the main motivations behind UI keyboard layout guide is to give you, the developer, the ability to respond to the many different ways we have for users to input text, and let you really, fully think of the keyboard as a part of your layout in a way that maybe you haven't been able to before. I am really excited to see how you take advantage of these new features. So, our next stop, what makes keyboard layout guide not just a layout guide? With UI keyboard layout guide, you have the ability to fully follow the keyboard in all its incarnations, if you so choose, by using a new property: followsUndockedKeyboard. It's false by default, but if you set it to true, the guide will follow the keyboard when it's undocked or floating, giving you a lot of control over how your layout responds to wherever the keyboard may be.

No more automatic drop-to-bottom. No listening for hide keyboard notifications when undocking. The layout guide is where the keyboard is. The thing about having that information, though, is that it means you have to be a lot more conscious of how your layout is responding to different types of keyboards. So, UI keyboard layout guide is a subclass of another new layout guide: UI tracking layout guide.

We call it a tracking layout guide because it tracks the constraints you want to change when it moves around the screen. You can give it an array of constraints that activate when near a specific edge, and deactivate when leaving it, and/or an array that activates when specifically awayFrom an edge, and deactivates when near it. Let's look at an example of what you can do with this, and the code you need to achieve it. Here's a test app. I have a text field and some controls that can sit on the keyboard. But, when it gets close to the top of the screen, I want them to drop to the bottom to avoid going off-screen.

And when the keyboard moves side to side, I want the rest of the UI to shift a bit to give it a little more space. So, how is all this accomplished? We're gonna look at some code here. In the following slides, the editView is the view with the text field and controls, and the imageView is the image view. Okay, note that we should be using identifiers here, and you will see that in the sample code, but this fits better on a slide. Let's start with what's happening on the vertical axis. First, we define an array that ties the bottom of the editView to the keyboard layout guide's top.

Then, we set those to be active only when the guide is away from the top, so that they'll be deactivated when it's near it.

Then, we define a separate array of constraints that we want for when the keyboard gets close to the top of the view. So, instead of the top of the keyboard layout guide, we use the safe area's bottom. Here's a quick visual to help. Here's the guide and the editView. It's currently away from the top, so the awayFromTopConstraints are active. But, as you move the guide closer to the top, the awayFrom constraints are deactivated, and the nearTopConstraints are activated, dropping it down to the bottom of the view. When we're back away from the top, the reverse happens. Now, let's look at horizontal movement. When the keyboard is away from both the leading and trailing edges, I want the editView to be at the center of the keyboard. I want the imageView to be centered in the view, as well. So, I define those constraints and set them to be active when I'm away from both leading and trailing.

Now, let's set up what happens when we approach an edge.

I want the editView to move over to trailing when we're at the trailing edge, and leading to leading. So, first, let's take care of that. I want the imageView to move out of the way of the keyboard a little, so when we're near either edge, I move it from the center to the opposite side from the keyboard, leading to leading when the keyboard is on the trailing edge, and vice versa. Then, I just set these to be active when I'm near the proper edge. They'll be activated when the keyboard crosses into that region, and deactivated when it leaves. And that's it! Super advanced keyboard integration into your very own layout. Let's take a look at what that looks like one more time. There's my editView. It stays with the floating keyboard, and as we move towards the top, it drops to the bottom. And as we move side to side, the adjustments we just talked about happen. Pretty cool! Next, let's talk about what "near" and "awayFrom" mean for the keyboard. A docked keyboard is considered to be near the bottom and awayFrom the other edges.

Undocked and split keyboards can be awayFrom all edges, or they can get near the top edge. When it's the floating keyboard, it can be near or awayFrom any edge, and it can even be near two adjacent edges at the same time. This can lead to some potentially interesting conflicts that you should be aware of. Now, all of this only applies when you set followsUndockedKeyboard to true, and for the rest of the talk, that's the assumption we'll be making. Okay. Final stretch: considerations for full keyboard integration. A keyboard is a keyboard is a keyboard-- until it's not. When you choose to follow the undocked keyboard, you have some extra things to think about. So, what sorts of things should you be paying attention to when designing your layout? Always remember that the floating keyboard can be awayFrom everything. Do you have sufficient information to be laid out correctly if it's awayFrom all edges? Also, what should happen when the keyboard is awayFrom the bottom edge, or near the top edge? You want to be careful with what's tied to the topAnchor of the keyboard, as well. Because it can get way up there! So, be careful. The way to resolve that is to set constraints when the keyboard is awayFrom the bottom edge that move those views off of the topAnchor of the keyboard and down to the bottom of the safeAreaLayoutGuide.

A user can also move the keyboard at any time, so you can't count on it being any where specific. You'll wanna keep that in mind, as well.

Here's a rare specimen: the split keyboard. Split and undocked keyboards are awayFrom all edges, until it gets too close to the top. As with a docked keyboard, it's always away from leading and trailing, as well. Let's talk about some new stuff. There's a new way to get text into your app this year, using the camera.

It's still a keyboard, so it will still be able to use the guide.

It's the same as a regular docked keyboard, but it's one of a few keyboards that can be pretty much full screen. To learn more about taking advantage of text input via camera this year, tune into "Use the camera for keyboard input in your app." Continuing with new things, what about when there's a hardware keyboard attached? Well, new this year, we have an adaptive shortcuts bar that is no longer always full-width. It changes width based on what language you're using and how many buttons are in the bar.

Previously, it was always the full width of the screen, but now, if you're following the undocked keyboard, you can actually use the real leading and trailing edges of the bar. So, what's the story here with edges? This is always near the bottom and, in its normal position, it's awayFrom the other three edges. But it's collapsable! If you collapse it, it can also be near the leading or trailing edge.

This is one of several reasons why you might wanna be careful about using the widthAnchor of the keyboard, by the way. It can be very small, or it can be the full width of the screen. Now, let's get into the most fun part of the tour: what about if you're not the only app onscreen, and you're following the undocked keyboard? First, remember that the keyboard can leave your app space. When that happens, we're going to treat it as though it's been dismissed. Second, when your app is at its narrowest, the top and bottom edges are in play, but leading and trailing will stay awayFrom, whether the keyboard is over your app or not. Also, the guide is sized for what part of the keyboard is over your app's window, if you're not the only thing onscreen. Let's take a look at some visuals to show you what I mean.

All of this only applies if you have followsUndockedKeyboard set to true. If you haven't, the guide is at the bottom of the screen, the full width of your window. When you're full screen and the keyboard is floating and in the middle, you're awayFrom everything. All of your awayFrom constraints have been activated, and all of your near constraints have been deactivated.

When another app is onscreen, if you're the wider app, you're still wide enough for the keyboard to be able to be awayFrom everything. But it needs to move less to be near a horizontal edge. This is similar to being in portrait, too. But, at half screen, the keyboard in the same spot is now near your leading edge, and the guide has gotten sized to match only the part of the keyboard that's over your app.

When you're the narrow app, the guide is always considered to be awayFrom the horizontal edges, the same as an iPhone or a docked keyboard, but you can still be near the top edge.

And notice that, again, the guide is sized to account for the portion over your app only. And when you dock the keyboard and it's full sized again, it's also away from leading, trailing, and top. And notice, again, that the layout guide is once again sized for what's over your app. If you're a slide-over app, it will resize for that, as well.

With the previous examples and our demo code, this should all be well-handled. You just have to keep in mind that you might be in any one of these scenarios. You should now be ready to bring your app to the next level of keyboard integration. So, use keyboard layout guide. If your app can, take advantage of the advanced features of UI tracking layout guide. And, most importantly, if you have been thinking about keyboard layout as fighting or avoiding the keyboard, start thinking about integrating it into your layout instead. And if you've already been thinking about it that way, now you have even more tools to realize your full vision.

That brings us to the end of our tour. Please make sure you have all your personal items before exiting, don't forget to visit the gift shop, and have a great WWDC. [ethereal percussion music]