-
- BlackBerry Dynamics
- Runtime library for iOS applications
- 13.1.0.48
This class represents the main application view controller class comprised of a floating Launcher button, Launcher's main view, and a base view controller. More...
#import <BlackBerryDynamics/GD/GTLauncherViewController.h>
The “Launcher” is a UX concept whereby an icon is displayed permanently on each screen, “floating” over the content. From the Launcher a user is able to launch other BlackBerry Dynamics apps, as well as take Quick Actions such as compose an email or schedule a meeting.
Setup
The Launcher will be automatically started, and present the floating Launcher button from every view. Applications can control the behavior by getting an instance of Launcher using `GDiOS.sharedInstance().getManagedLauncherViewController()` and then setting the Launcher delegate to the delegate object.
Alternatively, Launcher can be disabled completely by adding the following to the application’s info.plist:
The Launcher includes an affordance to open a settings page for the application. Applications may provide their own settings implementation, by implementing the applicationSettingsTableViewControllerForLauncher: (GTLauncherViewControllerDelegate-p) method. If an application does not provide its own implementation, a default one will be provided, which includes basic functionality such as changing the application password and uploading logs.
View Controller Heirarchy
The Launcher view controller is intended to be a container view controller whose base view controller is a single child view controller. The base view controller's view's bounds are set to that of the Launcher view controller's view. While the base view controller can have child view controllers, it is not recommended that Launcher's view controller's child view controllers be directly set. The GTLauncherViewController class should also not be subsclassed.
The view layers are setup such that the Launcher button and view shown in the open state are always on top of the base view controller. The open state of launcher is not displayed modally so any modal view controllers will display properly over the Launcher view controller and no special steps need to be taken to present and dismiss them.
By default Launcher handles childViewControllerForStatusBarHidden call, to redirect related methods to baseViewController please implement GTLauncherViewController category with next methods:
View State
There are several properties and methods to manage the state of the Launcher. The following are valid states:
showingLauncher property is set to YES. This property cannot be set if the launcher view is an open state.Settings
The settings button within Launcher allows for a host app to display its own custom settings. If no settings view controller is provided via the delegate call the default Launcher settings view will be presented modally.
If the host app does choose to present its settings through Launcher, it must add the Launcher view controller in an appropriate place within its settings heirarchy.
GTLauncherSettingsViewController Instance Methods | |
| (nullable instancetype) | - initWithBaseViewController: |
| Create and load the Launcher view controller. More... | |
| (void) | - startServicesWithOptions: |
| Grant Launcher Access to the various Dynamics Services [Deprecated]. More... | |
| (void) | - startServices |
| Grant Launcher Access to the various Dynamics Services [Deprecated]. More... | |
| (void) | - setOpen:animated: |
| Set open and closed state of Launcher, providing option to animate transition. More... | |
| (void) | - dismissSettings |
| Dismiss the presented settings. More... | |
| (void) | - presentSettings |
| Method to present settings. More... | |
| (void) | - setGDPushConnectionStatus: |
| Update Launcher's internal push connection status [Deprecated]. More... | |
| (void) | - openCertificatesStatus |
| Indicate that the Launcher view will be set to Certificate Status page. More... | |
| (void) | - storeLaunchPadButtonImageViewCenterCoordinates: |
| Control location of Launcher button. More... | |
Class Methods | |
| ("This method will be removed in a future release.") | + launcherVersion |
| The Launcher version [Deprecated]. More... | |
| (void) | + setCacheExpiry: |
| Sets interval when launcher data cache will be considered as fresh. More... | |
| (void) | + shouldShowCoachmarkScreen: |
| Control showing of coachmark tutorial. More... | |
| (void) | + setSectionEnabled:forSectionWithIdentifier: |
| Set the state of a Launcher Collection View Element provided by the host application. More... | |
| (BOOL) | + isSectionEnabled: |
| Check the state of a Launcher Collection View Element provided by the host application. More... | |
Protected Types | |
| enum | GTLauncherServicesStartupOptions : NSInteger { GTLInternalGDAuthTokenAndPushConnectionManagement = (1 << 0), GTLHostGDAuthTokenManagement = (1 << 1), GTLHostGDPushConnectionManagement = (1 << 2) } |
| Options for Launcher startup [Deprecated]. More... | |
Properties | |
| UIViewController * | baseViewController |
| Launcher's base view controller. More... | |
| BOOL | open |
| Launcher view status. More... | |
| BOOL | launcherButtonHidden |
| Launcher button's visibility status. More... | |
| id< GTLauncherViewControllerDelegate > | delegate |
| Delegate for Launcher view controller. More... | |
|
protected |
These options represents the handling of a push connection status and the requesting of auth tokens. The parameter of
method requires either the GTLInternalGDAuthTokenAndPushConnectionManagement option or one of both of the other options. These options are required as GDUtility and GDPushConnection classes are singletons with a single delegate.
Type of options to pass to BlackBerry Dynamics Launcher to tell it how to manage GDAuthToken and push connection.
| Enumerator | |
|---|---|
| GTLInternalGDAuthTokenAndPushConnectionManagement | Launcher will utilize GDAuthToken and the GDPushConnection status internally. Host application that neither utilize GDAuthToken or rely on the status of a GDPushConnection can provide this startup option. Launcher will internally set itself as the delegate for |
| GTLHostGDAuthTokenManagement | Host application will provide auth tokens upon request. Host application that use the -[id<GTLauncherViewControllerDelegate> launcherViewController:didRequestGDAuthTokenForServerName:]
|
| GTLHostGDPushConnectionManagement | Host application will update Launcher of GDPushConnection status. Host application that set themselves as the -[GTLauncherViewController setGDPushConnectionStatus:]
method when the |
| - (nullable instancetype) initWithBaseViewController: | (UIViewController *__nullable) | viewController |
Creates and loads the Launcher view controller, using resources from GTLauncherBundle, with an initial base view controller. The base view controller can be nil at startup, though the user will be presented with a black screen if one is not set. Setting and changing this value can be done via the baseViewController property.
Use this or init method to load the Launcher view controller. Using initWithNibName:bundle: will throw an exception.
| viewController | UIViewController that will be the initial base view controller. This value can be nil. |
| - (void) startServicesWithOptions: | ("This method will be removed in a future release.") | options |
Launcher relies on a number of Dynamics APIs internally. These APIs are not available when the app is not yet in an authorized state. Call this method when the host application's GDiOSDelegate receives a handleEvent: call. Because Launcher relies on several Dynamics APIs that are singleton's in nature, startup options are provided to allow for use of these APIs by both Launcher and the host application.
When providing options other than GTLInternalGDAuthTokenAndPushConnectionManagement, certain methods must either be implemented or called when appropriate.
| options | GTLauncherServicesStartupOptions representing the behavior for GDAuthToken and GDPushConnection management. |
| - (void) startServices |
Launcher relies on a number of Dynamics APIs internally. These APIs are not available when the app is not yet in an authorized state. Call this method when the host application's GDiOSDelegate recieves a handleEvent: call.
| - (void) setOpen: | (BOOL) | open | |
| animated: | (BOOL) | animated | |
Programmatically set Launcher's view to an open or close state, allowing for an option to do the transition with or without animation.
This method does nothing if Launcher's button is set to hidden.
| open | BOOL indicating whether to set the state of Launcher to be open or closed. |
| animated | BOOL indicating whether to set the open or closed state with or without animation. |
| - (void) dismissSettings |
Dismiss the presented settings view controller.
| - (void) presentSettings |
Can be used to present settings screen via other than settings button in Launcher actions.
| - (void) setGDPushConnectionStatus: | ("This method will be removed in a future release.") | status |
Host application that start with GTLHostGDPushConnectionManagement are assumed to have a GDPushConnectionDelegate within their app. Delegate calls to onStatus: must be forwarded to the current Launcher view controller via this method, passing along the status parameter that was provided from the delegate callback.
| status | int value of the push connection status. |
| + ("This method will be removed in a future release.") launcherVersion |
A value in the form of "X.Y.Z" where X represents the major version, Y represents the minor version, and Z represents the build number. This value is retrieved from the Dynamic bundle.. Use this value for either logging or to diplay in a settings view.
| + (void) setCacheExpiry: | (NSTimeInterval) | seconds |
Sets interval when launcher data cache will be considered as fresh.
| - (void) openCertificatesStatus |
Indicate that the Launcher view will be set to Certificate Status page.
This method is called when the the app is in an open state and the user manually taps on the Certificate Status button
| + (void) shouldShowCoachmarkScreen: | (BOOL) | shouldShow |
Indicate that the Launcher view will be set to show the Coachmark screen i.e. first time setup screen, this is your launcher walk through
This method overrides the default behavior which shows the walk-through on first use only. If called prior to showing launcher button with NO, the walkthough will not be shown.
| - (void) storeLaunchPadButtonImageViewCenterCoordinates: | (CGPoint) | point |
Stores Launch Pad Button Image View Center Coordinates in containing view's coordinates. Must be valid coordinates with respect to device orientation or default position will be used.
This method overrides the default behavior which uses either default button position or last position as user left the button. The coordinates can only be set once, after that last stored coods are used.
| + (void) setSectionEnabled: | (BOOL) | enabled | |
| forSectionWithIdentifier: | (NSString *) | identifier | |
To set the state of a host application provided Launcher Collection View Element
Setting state to disabled will hide the element.
| enabled | BOOL indicating whether to set the state of element is enabled or disabled |
| identifier | NSString id of the element |
| + (BOOL) isSectionEnabled: | (NSString *) | identifier |
To check the state of a host application provided Launcher Collection View Element *
| identifier | NSString id of the element |
|
readwritenonatomicstrong |
The view controller on which Launcher's view and button will be displayed over. The value of this property can be initially set through the initWithBaseViewController: initializer.
If a base view controller has not been set at initialization time, setting this property sets it up as a child view controller to the GTLauncherViewController instance. Otherwise, the existing child view controller is swapped out with the one being set. Setting this value to nil for an extended period of time is not recommended as the user will see a black screen.
|
readwritenonatomicassign |
Read the value of this property, using the isOpen accessor, to check whether Launcher's view is open or closed.
This property has the value:
YES if Launcher is openNO otherwiseSetting this property has the affect of providing an animated transition with these values:
YES sets Launcher's view state to open.NO sets Launcher's view state to closed.
|
readwritenonatomicassign |
Read the value of this property, using the isLauncherButtonHidden accessor, to check whether Launcher's button is showing or is hidden. Use this method if special, non-modal views are to be displayed, such an application welcome screen, and the Launcher button would be inhibiting.
This property has the value:
YES if the launcher button is visibleNO otherwise.Setting this property changes the visibility of the Launcher button:
YES sets Launcher button to be hidden.NO sets Launcher button to be visible.Attempts to change the value of this property while the Launcher's view is in an open state are ignored.
|
readwriteatomicweak |
Delegate for Launcher view controller.
With the exception of GTLHostGDAuthTokenManagement as a startup option, setting a delegate for the Launcher view controller is optional.