iPhone X Home Indicator Adaptation

Preface

Apple has always liked doing things in its own way, and the arrival of iPhone X was even more surprising. Apple fans were naturally excited, but because of the notch, iOS engineers had to deal with a rather painful adaptation process.

There are already many articles about iPhone X adaptation online, including some excellent ones. I once handled the iPhone X adaptation work for QQReader by myself, but many solutions to common adaptation issues are similar. This article will not repeat those well-known problems. Instead, it focuses on the iPhone X Home Indicator, a seemingly minor adaptation point that is easy to forget.

Where the Problem Starts

For most apps, adapting the Home Indicator may not be necessary at all, because the home bar constantly reminds users to change their old Home button habits. Its purpose is to replace the original Home button.

However, for certain apps, such as reading apps, video apps, and games, the core experience is immersive. In those scenarios, the Home Indicator becomes especially distracting, particularly the white glow in night mode.

You can feel it first. The screenshots below are from the simulator; on a real device, the experience is even more uncomfortable.

iPhone X Home Indicator Adaptation: Where the Problem Starts (figure 1)
iPhone X Home Indicator Adaptation: Where the Problem Starts (figure 2)

I roughly checked several reading apps, including iReader, WeChat Reading, Baidu Reading, and Shuqi Novel. Basically none of them adapted this behavior. Maybe the iPhone X market share was still small at the time. But from the current perspective, adapting the Home Indicator is still necessary. Next, let’s use QQReader as an example to analyze the adaptation process.

Initial Adaptation in Day Mode

Following the official guidance, let’s start adapting.

First look at the UIViewController header. iOS 11 added a UIHomeIndicatorAutoHidden category to UIViewController, used to control automatic hiding of the home indicator.

1
2
3
4
5
6
7
8
9
10
11
12
@interface UIViewController (UIHomeIndicatorAutoHidden)

// Override to return a child view controller or nil. If non-nil, that view controller's home indicator auto-hiding will be used. If nil, self is used. Whenever the return value changes, -setNeedsHomeIndicatorAutoHiddenUpdate should be called.
- (nullable UIViewController *)childViewControllerForHomeIndicatorAutoHidden API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(watchos, tvos);

// Controls the application's preferred home indicator auto-hiding when this view controller is shown.
- (BOOL)prefersHomeIndicatorAutoHidden API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(watchos, tvos);

// This should be called whenever the return values for the view controller's home indicator auto-hiding have changed.
- (void)setNeedsUpdateOfHomeIndicatorAutoHidden API_AVAILABLE(ios(11.0)) API_UNAVAILABLE(watchos, tvos);

@end

The control mechanism for HomeIndicator is actually quite similar to status-bar control. So adaptation starts with the APIs above.

    1. Override prefersHomeIndicatorAutoHidden in the view controller where you want to hide the indicator.
1
2
3
- (BOOL)prefersHomeIndicatorAutoHidden{
return YES;
}
    1. Call setNeedsUpdateOfHomeIndicatorAutoHidden at the appropriate time.
1
2
3
if (@available(iOS 11.0, *)) {
[self setNeedsUpdateOfHomeIndicatorAutoHidden];
}

Is that enough? Apparently not. The code above may not take effect. The reason is:

Overriding this method on a controller only applies when the controller has no parent controller. Most apps use UITabBarController or UINavigationController as the root controller of the window, with UIViewController used to present content. In that case, the root controller’s childViewControllerForHomeIndicatorAutoHidden method also needs to be overridden.

Also note that the root controller is not necessarily UINavigationController or UITabBarController. It may come from a third-party framework, or be custom. For example, QQReader’s root controller, XXXViewController, is custom.

Here is the override of childViewControllerForHomeIndicatorAutoHidden in the root controller XXXViewController:

1
2
3
4
5
6
7
8
9
10
11
12
13
- (UIViewController*)childViewControllerForHomeIndicatorAutoHidden
{
id<UIApplicationDelegate> * appDelegate = UIApplication sharedApplication].delegate
UIViewController *topViewController = appDelegate.viewController.topViewController;

// XXXViewController is the VC whose Home Indicator we want to control.
if ([topViewController isKindOfClass:[XXXViewController class]])
{
return topViewController;
}

return nil;
}

After the adaptation above, entering the reading page in day mode shows the Home Indicator at first. If there is no tap operation, it automatically hides after about one second. Once the reading page receives a tap, the Home Indicator appears again, but soon hides automatically.

If adaptation ended here, there would be no need for this article. The real trap in adapting QQReader’s Home Indicator had only just begun.

Switching the Reading Page to Night Mode

In my understanding, a normal night mode should use a dedicated skin system. That is simple and reliable. If your project implements night mode this way, you probably will not hit the issue I encountered.

But for historical reasons, some projects may not do this. Instead, they use another approach: add a window that does not respond to events above the current window, then set the opacity of its root view controller’s view to create a night-mode visual effect. This approach may require less work, but it can cause all kinds of problems. It once affected page navigation, and this time it affected Home Indicator adaptation.

The night mode implementation looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
- (void)enableNightMode
{
UIWindow *window = [[UIWindow alloc] initWithFrame:CGRectMake(0,0,kScreenWidth, kScreenHeight)];
window.userInteractionEnabled = NO;
window.backgroundColor = [UIColor clearColor];
window.windowLevel = XXXLevelGlobalNightMode;
XXXNightModeMaskViewController *vc = [[XXXNightModeMaskViewController alloc] init];
vc.view.backgroundColor = [[UIColor blackColor] colorWithAlphaComponent:0.35];
window.rootViewController = vc;
[window makeKeyAndVisible];
self.nightModeWindow = window;
}

Because a window is overlaid above the original one, whenever the reading page switches to night mode and childViewControllerForHomeIndicatorAutoHidden is called, it is called on XXXNightModeMaskViewController instead of the normal window’s root controller mentioned earlier. As a result, the code we set before cannot be called, and control fails.

The solution is to override childViewControllerForHomeIndicatorAutoHidden in XXXNightModeMaskViewController.

Here is the override:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
- (UIViewController*)childViewControllerForHomeIndicatorAutoHidden
{
// Find the normal window.
...

// Find topViewController.
UIViewController *topViewController = window.rootViewController.topViewController;

// Put the VC you want to control here, or use a whitelist.
if ([topViewController isKindOfClass:[XXXViewController class]])
{
return topViewController;
}

return nil;
}

Entering the Reading Page in Night Mode

Is the problem solved? Not yet. In night mode, if you enter the reading page directly from outside, such as from the bookshelf, the Home Indicator still cannot disappear.

    1. First, look at the previous call stack when switching to night mode on the reading page:
iPhone X Home Indicator Adaptation: Entering the Reading Page in Night Mode (figure 3)

If night mode is switched while already on the reading page, [UIWindow makeKeyAndVisiable] is triggered, which then triggers childViewControllerForHomeIndicatorAutoHidden. Because this window does not respond to any events, this is the only opportunity for it to trigger childViewControllerForHomeIndicatorAutoHidden.

    1. Now look at the call stack when entering the reading page directly from the bookshelf in day mode:
iPhone X Home Indicator Adaptation: Entering the Reading Page in Night Mode (figure 4)

It looks like [UINavigationController pushViewController:animated:] can also trigger childViewControllerForHomeIndicatorAutoHidden.

    1. In night mode, [UINavigationController pushViewController:animated:] is also called, but it cannot trigger the root controller’s childViewControllerForHomeIndicatorAutoHidden, so it fails again. I suspect this may be related to keyWindow, but unfortunately I did not find the exact reason. If anyone knows, advice is welcome. Still, that does not mean there is no solution: in the XXXViewController we want to control, just trigger night mode again.
1
2
3
4
5
6
7
- (void)viewDidLoad
{
[super viewDidLoad];
if(IS_IPHONEX && !_isDayMode){
[ThemeMgr enableNightMode];
}
}

Result

Here is the effect after adaptation:

iPhone X Home Indicator Adaptation: Result (figure 5)
iPhone X Home Indicator Adaptation: Result (figure 6)

Summary

If Home Indicator adaptation is done step by step like this, it usually does not take too much time. Unfortunately, I fell into the night-mode trap at the very beginning and did not expect Home Indicator adaptation to have anything to do with that night-mode implementation, so I spent quite a long time on it.

For a while, I thought this adaptation might be like in-app rating: the client has very weak control. I also trusted Apple’s official opinion quite strongly:

  • The indicator will automatically adjust itself depending on what’s below it, and it’s not something you can directly control. As described in Designing for iPhone X, you generally don’t want to do anything in your app specific to the home indicator

In practice, even after adaptation, the client still has weak control and there remains one limitation: whenever a touch happens inside the reading page, the Home Indicator briefly appears and then slowly disappears. This is likely caused by Apple’s internal implementation, and there may be little we can do. I checked several video and game apps that adapted Home Indicator, and basically all of them have this issue.

Fortunately, gestures do not have much impact. Gesture-based page turning in QQReader’s reading page basically does not make the Home Indicator appear. I suspect this may be related to gesture response priority.

Hopefully there will be a better solution in the future.

-------------本文结束 感谢您的阅读-------------
If this article helped you, your support encourages me to keep writing.

Title:iPhone X Home Indicator Adaptation

Author:lingyun

Published:2018-01-28 23:43

Updated:2026-10-07 00:00

Original link:https://tsuijunxi.github.io/en/2018/01/28/iphonex-home-indicator-adaptation/

License: Attribution-NonCommercial-NoDerivatives 4.0 International Please keep the original link and author when sharing.