On iOS, users normally interact with your apps via the device’s touch screen. On tvOS, however, user interaction is handled by moving the current focus between views on the screen.
Luckily, the tvOS implementations of the UIKit APIs handle the changing of focus between views automatically. While this built-in system works very well, for specific view layouts and/or purposes, it may be necessary to sometimes manually control the focus engine.
In this tutorial, we take an in-depth look at the tvOS focus engine. You learn how it works and how to control it however you want to.
This tutorial requires that you are running Xcode 7.3 or higher with the latest tvOS 9.2 SDK. If you want to follow along, you also need to download the starter project from GitHub.
1. Focus Engine Overview
The purpose of the focus engine of tvOS is to help developers concentrate on their own app’s unique content rather than reimplementing basic navigation behaviors. This means that, while many users will use Apple TV’s Siri Remote, the focus engine automatically supports all current and future Apple TV input devices.
This means that, as a developer, you don’t have to worry about how a user is interacting with your app. Another important goal of the focus engine is to create a consistent user experience between applications. Because of this, there is no API that allows an application to move the focus.
When the user interacts with the remote of the Apple TV by swiping on the glass Touch surface in a particular direction, the focus engine looks for a possible focusable view in that direction and, if found, moves the focus to that view. If no focusable view is found, the focus remains where it currently is.
In addition to moving the focus in a particular direction, the focus engine also handles several other, more advanced behaviors, such as:
- moving the focus past particular views if, for example, the user swipes fast on the Touch surface of the Apple TV remote
- running animations at speeds based on the velocity of the focus change
- playing navigation sounds when the focus changes
- animating scroll view offsets automatically when the focus needs to move to a currently off-screen view
When determining where the focus should move to in an app, the focus engine takes an internal picture of your app’s current interface and highlights all of the visible elements that are focusable. This means that any hidden views, including views with an alpha value of 0, cannot be focused. This also means that, for any view that is hidden by another view, only the visible part is considered by the focus engine.
If the focus engine finds a view it can move the focus to, it notifies the objects conforming to the
UIFocusEnvironment protocol that are involved with the change. The UIKit classes that conform to the
UIFocusEnvironment protocol are
UIPresentationController. The focus engine calls the
shouldUpdateFocusInContext(_:) method of all the focus environment objects that contain either the currently focused view or the view the focus is moving to. If any of these method calls returns
false, the focus is not changed.
UIFocusEnvironment protocol represents an object that is known as a focus environment. The protocol defines a
preferredFocusView property that specifies where the focus should move to if the current environment becomes focussed itself.
For example, a
UIViewController object’s default
preferredFocusView is its root view. As each
UIView object can also specify its own preferred focus view, a preferred focus chain can be created. The tvOS focus engine follows this chain until a particular object returns either
nil from its
preferredFocusView property. By using these properties, you can redirect focus throughout the user interface and also specify which view should be focussed first when a view controller appears on-screen.
It is important to note that, if you don’t change any of the
preferredFocusView properties of your views and view controllers, the focus by default engine focuses the view closest to the top left corner of the screen.
A focus update occurs when one of three events take place:
- the user causes a focus movement
- the app explicitly requests a focus update
- the system triggers and automatic update
Whenever an update takes place, the following events follow:
- The current
focusedViewproperty is changed to the view that the focus is moving to.
- The focus engine calls the
didUpdateFocusInContext(_:withAnimationCoordinator:)of every focus environment object involved in the focus update. These are the same set of objects which the focus engine checks by calling each object’s
shouldUpdateFocusInContext(_:)method before updating the focus. It is at this point that you can add custom animations to run in conjunction with the focus-related animations the system provides.
- All of the coordinated animations, both system and custom animations, are run simultaneously.
- If the view the focus is moving to is currently off-screen and in a scroll view, the system scrolls the view on-screen so that the view becomes visible to the user.
To manually update the focus in the user interface, you can invoke the
setNeedsFocusUpdate() method of any focus environment object. This resets the focus and moves it back to the environment’s
The system can also trigger an automatic focus update in several situations, including when a focussed view is removed from the view hierarchy, a table or collection view reloads its data, or when a new view controller is presented or dismissed.
While the tvOS focus engine is quite complex and has a lot of moving parts, the UIKit APIs provided to you make it very easy to utilize this system and make it work how you want it to.
2. Controlling the Focus Engine
To extend the focus engine, we are going to implement a wrap-around behavior. Our current app has a grid of six buttons as shown in the below screenshot.
What we are going to do is allow the user to move the focus towards the right, from buttons 3 and 6, and make the focus wrap back around to buttons 1 and 4 respectively. As the focus engine ignores any invisible views, this can not be done by inserting an invisible
UIView (including a view with a width and height of 0) and changing its
Instead, we can accomplish this using the
UIFocusGuide class. This class is a subclass of
UILayoutGuide and represents a rectangular focusable region on the screen while being completely invisible and not interacting with the view hierarchy. On top of all the
UILayoutGuide properties and methods, the
UIFocusGuide class adds the following properties:
preferredFocusedView: This property works as I described earlier. You can think of this as the view that you want the focus guide to redirect to.
enabled: This property lets you enable or disable the focus guide.
In your project, open ViewController.swift and implement the
viewDidAppear(_:) method of the
ViewController class as shown below:
override func viewDidAppear(animated: Bool) super.viewDidAppear(animated) let rightButtonIds = [3, 6] for buttonId in rightButtonIds if let button = buttonWithTag(buttonId) let focusGuide = UIFocusGuide() view.addLayoutGuide(focusGuide) focusGuide.widthAnchor.constraintEqualToAnchor(button.widthAnchor).active = true focusGuide.heightAnchor.constraintEqualToAnchor(button.heightAnchor).active = true focusGuide.leadingAnchor.constraintEqualToAnchor(button.trailingAnchor, constant: 60.0).active = true focusGuide.centerYAnchor.constraintEqualToAnchor(button.centerYAnchor).active = true focusGuide.preferredFocusedView = buttonWithTag(buttonId-2) let leftButtonIds = [1, 4] for buttonId in leftButtonIds if let button = buttonWithTag(buttonId) let focusGuide = UIFocusGuide() view.addLayoutGuide(focusGuide) focusGuide.widthAnchor.constraintEqualToAnchor(button.widthAnchor).active = true focusGuide.heightAnchor.constraintEqualToAnchor(button.heightAnchor).active = true focusGuide.trailingAnchor.constraintEqualToAnchor(button.leadingAnchor, constant: -60.0).active = true focusGuide.centerYAnchor.constraintEqualToAnchor(button.centerYAnchor).active = true focusGuide.preferredFocusedView = buttonWithTag(buttonId+2)
viewDidAppear(_:), we create focus guides to the right of buttons 3 and 6, and to the left of buttons 1 and 4. As these focus guides represent a focusable region in the user interface, they must have a set height and width. With this code, we make the regions the same size as the other buttons so that the momentum-based logic of the focus engine feels consistent with the visible buttons.
To illustrate how coordinated animations work, we update the
alpha property of the buttons when the focus changes. In ViewController.swift, implement the
didUpdateFocusInContext(_:withAnimationCoordinator:) method in the
override func didUpdateFocusInContext(context: UIFocusUpdateContext, withAnimationCoordinator coordinator: UIFocusAnimationCoordinator) super.didUpdateFocusInContext(context, withAnimationCoordinator: coordinator) if let focusedButton = context.previouslyFocusedView as? UIButton where buttons.contains(focusedButton) coordinator.addCoordinatedAnimations( focusedButton.alpha = 0.5 , completion: // Run completed animation )
context parameter of
didUpdateFocusInContext(_:withAnimationCoordinator:) is a
UIFocusUpdateContext object that has the following properties:
previouslyFocusedView: references the view the focus is moving from
nextFocusedView: references the view the focus is moving to
UIFocusHeadingenumeration value representing the direction the focus is moving in
With the implementation of
didUpdateFocusInContext(_:withAnimationCoordinator:), we add a coordinated animation to change the alpha value of the previously focused button to 0.5 and that of the currently focused button to 1.0.
Run the app in the simulator and move the focus between the buttons in the user interface. You can see that the currently focused button has an alpha of 1.0 while the previously focused button has an alpha of 0.5.
The first closure of the
addCoordinatedAnimations(_:completion:) method works similarly to a regular
UIView animation closure. The difference is that it inherits its duration and timing function from the focus engine.
If you want to run an animation with a custom duration, you can add any
UIView animation within this closure with the
OverrideInheritedDuration animation option. The following code is an example of how to implement a custom animation that runs in half the time of the focus animations:
// Running custom timed animation let duration = UIView.inheritedAnimationDuration() UIView.animateWithDuration(duration/2.0, delay: 0.0, options: .OverrideInheritedDuration, animations: // Animations , completion: (completed: Bool) in // Completion block )
By using the
UIFocusGuide class and by utilizing custom animations, you can extend the standard behavior of the tvOS focus engine to suit your needs.
Limiting the Focus Engine
As I mentioned earlier, when deciding whether or not the focus should be moved from one view to another, the focus engine calls the
shouldUpdateFocusInContext(_:) method on every focus environment involved. If any of these method calls returns
false, the focus is not changed.
In our app, we are going to override this method in the
ViewController class so that the focus cannot be moved down if the currently focused button is 2 or 3. To do so, implement
shouldUpdateFocusInContext(_:) in the
ViewController class as shown below:
override func shouldUpdateFocusInContext(context: UIFocusUpdateContext) -> Bool focusedButton == buttonWithTag(3) if context.focusHeading == .Down return false return super.shouldUpdateFocusInContext(context)
shouldUpdateFocusInContext(_:), we first check whether the previously focused view is button 2 or 3. We then inspect the focus heading. If the heading is equal to
Down, we return
false so that the current focus does not change.
Run your app one last time. You cannot move the focus down from buttons 2 and 3 to buttons 5 and 6.
You should now be comfortable controlling and working with the focus engine of tvOS. You now know how the focus engine works and how you can manipulate it to fit whatever needs you have for your own Apple TV apps.
As always, be sure to leave your comments and feedback in the comments below.