You are here: Application API

Application API

The Application API provides functions that enable you to control the application-level events and behaviors of your app.

The Application API uses kony.application Namespace and the following API elements:

Constants

Constant Type	Description
Application Constants	Identifies the location from where the app is launched.
Breakpoint Constants	Checks if the current browser window size has gone beyond highest value of breakpoints list defined.
Runtime Permissions Constants	Report the status of runtime permissions.

Functions

Function	Description
`kony.application.addApplicationCallbacks`	Helps you to register multiple callbacks for the same event.
`kony.application.addBMState`	Adds a specified key and value to the parameter list of the URL of the form.
`kony.application.addGestureRecognizerForAllForms`	Enables the developers to set a gesture recognizer for the specified gesture of the specified widget.
`kony.application.addSettingsMenuItemAt`	Enables you to add a menu item at a given index in the Charm settings menu.
`kony.application.beginBackgroundTask`	Used when you want to run a long running or the asynchronous task in the background of the phone app.
`kony.application.checkPermission`	Checks and returns the permission status of one or more resources.
`kony.application.createSettingsMenu`	Enables you to create a Charm settings menu for an application.
`kony.application.dismissLoadingScreen`	Provides you the ability to dismiss the loading screen displayed earlier
`kony.application.destroyForm`	Destroys the target form.
`kony.application.disableZoomedOutView`	Enables you to disable a zoomed out view set for an application using the previous API.
`kony.application.endBackgroundTask`	Invoked when you are done with an execution of long running tasks in the background.
`kony.application.exit`	Terminates the application.
`kony.application.exitLibrary`	Provides you the ability to exit the library. After exiting the library, the control moves to the Native app UI.
`kony.application.getApplicationBadgeValue`	Enables you to read the badge value (if any) attached to the given application icon.
`kony.application.getApplicationMode`	Enables you to get the application mode.
`kony.application.getApplicationState`	Checks whether the app is running in the background or not to make UI updates.
`kony.application.getAppMenuBadgeValue`	Enables you to read the badge value (if any) attached to the specified app menu item.
`kony.application.getAppWindow`	Returns a handle to an AppWindow object.
`kony.application.getBMState`	Retrieves the list of parameters attached to a URL using the above add, set APIs.
`kony.application.getCurrentBreakpoint`	Returns the current breakpoint value.
`kony.application.getCurrentForm`	Returns a handle to the current form.
`kony.application.getCurrentSettingsMenu`	Returns the unique identifier of the current menu that is set through getCurrentSettingsMenu.
`kony.application.getPreviousForm`	Returns a handle to the previous form.
`kony.application.getPreviousSessionParams`	Retrieves the previous session parameters in the application life cycle.
`kony.application.getSettingValue`	Retrieves the current device settings.
`kony.application.invalidateSession`	Invalidates a session on Mobile Web.
`kony.application.isImageTurnedOff`	Gets the status of image settings, which are defined by a particular user, in a web browser.
`kony.application.isInMultiWindowMode`	Returns true if the application is in multi-window mode, and the function returns false if the application is in full-screen mode.
`kony.application.isPopupBlocked`	Gets the status of pop-up settings, which are defined by a particular user, in a web browser.
`kony.application.launchApp`	Launches the application specified by the input URL.
`kony.application.openApplicationSettings`	Opens the application-specific settings or device-level application settings.
`kony.application.openMediaURL`	Launches the native media player and starts playing the media (audio or video) at the specified URL.
`kony.application.openURL`	Opens the web page at the specified URL in the native browser of the mobile device.
`kony.application.openURLAsync`	Opens the web page at the specified URL in the native browser of the mobile device.
`kony.application.postAccessibilityNotification`	Posts a notification to "assistive" applications
`kony.application.registerForIdleTimeout`	Specifies if the application must timeout after a defined period of inactivity and also specifies the action after the timeout interval.
`kony.application.registerOnKeyPress`	Connects an event handler function to a key press event.
`kony.application.registerOnSettingsChangeCallback`	Listens if any settings have been changed in Native settings applications.
`kony.application.removeApplicationCallbacks`	Helps you to clear callback functions associated with the specified appstates.
`kony.application.removeBMState`	Removes a specified key from the parameter list of the URL of the form.
`kony.application.removeGestureRecognizerForAllForms`	Enables you to remove a specified gesture recognizer for all Forms.
`kony.application.removeSecondaryTile`	Enables you to remove and unpin a specified secondary tile which was created earlier.
`kony.application.removeSeoDataReadyFlag`	Clears the flag that caches forms for SEO.
`kony.application.removeSettingsMenuItemAt`	Enables you to removes the specified App Menu item based on the index.
`kony.application.requestPermission`	Requests for the end-user consent to access a particular resource.
`kony.application.requestPermissionSet`	Sends a request for a set of permissions. The status of the request is sent back to the user through a callback.
`kony.application.requestReview`	Requests users to provide a rating and to write a review for an app.
`kony.application.resetBMState`	Resets the state associated with the URL of a form.
`kony.application.sendLibraryResultToNativeApp`	Enables you to send an acknowledgment to a Native app that launched this library.
`kony.application.setApplicationBehaviors`	Enables your app to configure its response to various events.
`kony.application.setApplicationBadgeValue`	Enables you to set a badge value to an application icon on the mobile desktop at the top-right corner of the application icon.
`kony.application.setApplicationCallbacks`	Captures the callback events for various states of the application
`kony.application.setApplicationInitializationEvents`	Configures all initialization events such as, preappinit, postappinit, init, appservice, showstartupform and so on.
`kony.application.setApplicationLayout`	Specifies if the application must have a layout from "left to right" or "right to left".
`kony.application.setApplicationMode`	Enables you to set the application mode to Native, Hybrid, or Wrapper.
`kony.application.setApplicationProperties`	Enables you to set properties at the application level.
`kony.application.setAppMenuBadgeValue`	Enables you to set a badge value to the specified app menu item on the top-right corner of the app menu item.
`kony.application.setAppTile`	Enables you to set the data for an application tile.
`kony.application.setBMState`	Sets the bookmark state to the URL.
`kony.application.setCheckBoxSelectionImageAlignment`	Used to set the alignment of the checkBox selection image.
`kony.application.setCurrentSettingsMenu`	Uses the unique identifier which represents the Charm settings menu and sets it as current settings menu.
`kony.application.setCurrentAppMenuFont`	Sets the font name and font size of various app menu items in the current app menu.
`kony.application.setDefaultListboxPadding`	Customizes the default paddings applied for a ListBox.
`kony.application.setDefaultTextboxPadding`	Customizes the default paddings applied for a Textbox.
`kony.application.setLibraryHeadlessModeCallback`	Registers a listener or a callback that receives request from a Native app to launch Kony library without UI or in headless mode.
`kony.application.setRespectImageSizeForImageWidgetAlignment`	Sets the ImageWidget width to minimum or maximum according to available width or image width in absence of reference width
`kony.application.setSecondaryTile`	Enables you to create or update data for a secondary tile for an application.
`kony.application.setSeoDataReadyFlag`	Sets a flag indicating that the current form is ready to be cached for search engine optimization.
`kony.application.setZoomedOutView`	Enables you to set a form to be shown to the user when a zoom out gesture is performed.
`kony.application.showLoadingScreen`	Enables you to display a loading screen (following a certain color schema) to the user while another action is in progress.
`kony.application.startForegroundService`	Defines the notifications for an app that is running in the background, i.e, an app with which the user is not interacting directly.
`kony.application.stopForegroundService`	Enables you to stop the foreground service for an application that is running in the background.
`kony.application.unregisterForIdleTimeout`	Specifies that the application must not timeout after a defined period of inactivity (time difference between the current device time and the last time you clicked on any user interface component).
`kony.application.updateForegroundNotification`	Enables you to customize and update the existing notifications shown by the foreground service.
`kony.application.zoomIn`	Enables you to zoom in on an application programmatically.

Overview

This functions in the Application API handle such tasks as setting application callbacks, starting and stopping background tasks, showing and dismissing the loading screen, and so forth.

Note: All of the Application API functions are in the kony.application namespace. However, the kony.application namespace contains some functions that are not part of the Application API. Only the functions listed above are part of the Application API.

During the lifecycle of an application, the mobile device usually triggers several events. The functions in the Application API allow you to listen for these events and override them with application-specific functionality. Your app should register for application events during the application load event of the project or masterdataload event of the startup form.

Deep Linking

Applications can use deep linking and the kony.application.launchApp function to launch target apps from the current source app. To use deep linking, first perform the following steps.

Step 1: Register for deep linking in Kony Visualizer.

Load the project for the target app.
From the Kony Visualizer Project pane, choose Project Settings.
In the dialog box that appears, click the Native tab.
On Windows Phone, select the Windows Phone tab. On Windows Tablet, choose the Windows Tablet tab.
On Windows Phone, select the Common tab. On Windows Tablet, click the Packaging tab.
Enter the deep linking schema name in the Deeplink URL Scheme text box. The schema name should be a string that uniquely identifies your app from all other apps. It must be 2-39 characters in length, and it can contain numbers, lowercase characters, periods ('.'), plus signs ('+'), or hyphens ('-'). The string cannot start with a period.

Step 2: In the source app, launch the target app.

Launch the target app from the source app using code similar to the following example.

var protocolName = "KonyApp1234567.8";
var data = {
    navigatetoForm ": "
    FrmHome ",
    "
    TexttoShow ": "
    Launched FrmHome by Deeplinking "
};
kony.application.launchApp(protocolName,data);

As the example code shows, your source app must use the deep linking protocol name specified in the target app's Kony Visualizer project file. It can also pass whatever data the target app is designed to accept.

Step 3: In the target app, process input parameters as needed.

The target app should process input parameters when it launches, if there are any. To do so, it can use code similar to the following.

function AppEvents(eventobject) {
    // Extract the deep linking data from the input parameters.
    var launchParams = eventobject["launchparams"];
    var deeplinkData = launchParams["deeplinkinglaunchparams"];

    // Now deeplinkData contains the same information as the data
    // that was passed to kony.application.launchApp
    var toForm = deeplinkData["navigatetoForm"];
    var frmtext = deeplinkData["TexttoShow"];
    if (toForm == "FrmHome")
        FrmHome.lb1.text = frmtext;
}

In this example, the AppEvents function extracts the launch parameters from the eventobject parameter. The function then retrieves the deep linking data from the launch parameters. Next, it declares two variables to receive the individual pieces of data that the source app passed to the kony.application.launchApp function when it launched the target app.