SBDashBoardPageViewController

From iPhone Development Wiki
Revision as of 14:41, 5 June 2017 by PoomSmart (talk | contribs) (→‎requiredCapabilities: 0x20 = 32)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

An instance of SBDashBoardPageViewController defines a page on the iOS 10 lockscreen. You should not directly create an instance of it; subclass it instead.

As of iOS 10.1.1, three subclasses of SBDashBoardPageViewController are present:

  1. SBDashBoardMainPageViewController (displays notifications, clock, etc)
  2. SBDashBoardTodayPageViewController (displays widgets)
  3. SBDashBoardCameraPageViewController (provides access to the camera)

Thus, to create a new page you should create a subclass of SBDashBoardPageViewController, as below:

#import <objc/runtime.h>

%subclass XXXMyPageViewController : SBDashBoardPageViewController

// Override methods here as needed. 

%end

Adding your new page

After creating your page, you can load it into the lockscreen by hooking:

- (id)initWithPageViewControllers:(NSArray*)arg1 mainPageViewController:(SBDashBoardPageViewController*)arg2 legibilityProvider:(id)arg3;

within SBDashBoardViewController. Simply append a new instance of your subclass into arg1 - note that you will need a mutable copy of it.

Arranging pages can be achieved by hooking

-(void)_setAllowedPageViewControllers:(NSArray*)controllers;

and arranging the controllers array yourself. Note that this will be called for each available page that satisfies +requiredCapabilities and +isAvailableForConfiguration as detailed below. The count of available pages is based upon the count of the _allowedPageViewControllers iVar, as well as the order.

Be aware that other tweaks may be overriding this method and arranging pages themselves! It's recommended to rely on LockPages (when updated) or another such tweak to arrange pages as needed for you.

Customization

SBDashBoardPageViewController provides a significant degree of customization, such as through overriding the following methods:

+ (unsigned long long)requiredCapabilities;
+ (_Bool)isAvailableForConfiguration;
- (void)aggregateAppearance:(SBDashBoardAppearance*)arg1;
- (void)aggregateBehavior:(SBDashBoardBehavior*)arg1;
- (long long)backgroundStyle;

Be aware the two class methods are called after a respring; before -init. In contrast, -aggregateAppearance: and -aggregateBehavior: are called just before the page is made visible on the lockscreen by the user.

Note that there are other methods that can be overridden, but not documented yet. Make sure to check the header!

requiredCapabilities

Defines a flag to be checked against the current device's capabilities as to whether it can utilise this page. Not much research has been undertaken for this yet (please contribute further findings!).

Return value Note
0 No capabilities required
4 Returned by Camera page subclass
32 Returned by Today page subclass

isAvailableForConfiguration

Defines whether a given page subclass can be loaded for use on the lockscreen. This is useful if you want to restrict a page based upon any other criteria not covered by requiredCapabilities, such as screen size for example.

Return value Note
NO Don't load an instance of this subclass
YES Can load.

As mentioned, this is only called once per respring, so if you want to conditionally enable pages whilst SpringBoard is still running, you will need to look at overriding other methods, or hide your view.

aggregateAppearance:

The lockscreen in iOS 10 has introduced a new class, SBDashBoardAppearance, which defines how a page on the lockscreen will be presented to the user. It acts as a container of SBDashBoardComponent objects. For example, the Camera page's override for -aggregateAppearance: looks something like so:

-(void)aggregateAppearance:(SBDashBoardAppearance*)arg1 {
    [super aggregateAppearance:arg1];

    // Unknown functionality
    SBDashBoardComponent *pageContent = [[objc_getClass("SBDashBoardComponent") pageContent] flag:0];
    [arg1 addComponent:pageContent];
   
    // Slide dateView with the lockscreen when presenting page.
    SBDashBoardComponent *dateView = [[objc_getClass("SBDashBoardComponent") dateView] hidden:YES];
    [arg1 addComponent:dateView];

    // Slide wallpaper with the lockscreen when presenting page. (needs confirmation)
    SBDashBoardComponent *wallpaper = [[objc_getClass("SBDashBoardComponent") wallpaper] hidden:YES];
    [arg1 addComponent:wallpaper];

    // Slide statusBar with the lockscreen when presenting page. (needs confirmation)
    SBDashBoardComponent *statusBar = [[objc_getClass("SBDashBoardComponent") statusBar] hidden:YES];
    [arg1 addComponent:statusBar];

    // Ensure the lockscreen will slide over to the left (< 0) to present the page
    SBDashBoardComponent *slideableContent = [objc_getClass("SBDashBoardComponent") slideableContent];
    [slideableContent setOffset:CGPointMake(-303030.0, 0)];
    [arg1 addComponent:slideableContent];
}

You can also hide the UIPageControl on the lockscreen when your page is visible with:

SBDashBoardComponent *pageControl = [[objc_getClass("SBDashBoardComponent") pageControl] hidden:YES];
[arg1 addComponent:pageControl];

There are a number of other components and settings available in SBDashBoardComponent.h.

aggregateBehavior:

The behaviour of the lockscreen can also be configured for when your page is visible. An example implementation of this may look as follow:

- (void)aggregateBehavior:(SBDashBoardBehavior*)arg1 {
    [super aggregateBehavior:arg1];

    arg1.idleTimerDuration = 120;
    
    // TODO: Add more to example.
}

Again, more properties to set can be found in SBDashBoardBehavior.h.

backgroundStyle

You can request a blurred background to your page by returning a value from this method.

Return value Note
1 No blur
2 Slight dark tinting
3 Blur, no tinting
4 CC style light blur
5 Vibrant dark-ish blur
6 NC style dark blur