Mobile Web Wearable Web

Application

Tizen provides various application management features, including application launching, event handling, and information retrieval.

The Application API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. All mandatory APIs are supported on the Tizen Emulators.

The main application management and launch features are:

  • Application management

    You can manage and retrieve information about the current application with the Application object (in mobile and wearable applications). The Application object is retrieved using the getCurrentApplication() method of the ApplicationManager interface (in mobile and wearable applications). You can exit or hide the current application using the Application interface.

  • Application information retrieval

    You can retrieve information about applications in various ways:

    • Retrieve information about installed applications with the getAppInfo() and getAppsInfo() methods of the ApplicationManager interface.

      These methods can be used to access the ApplicationInformation interface (in mobile and wearable applications) to retrieve information about installed applications, such as their name, icon path, and version.

    • Retrieve information about running applications with the getAppContext() and getAppsContext() methods of the ApplicationManager interface.

      These methods can be used to access the ApplicationContext interface (in mobile and wearable applications) to retrieve the application ID and context ID of the running application.

      The application ID can be used to retrieve application information, or to launch an application. The context ID is a unique identifier given by the platform to a running application.

  • Application controls

    You can request other applications to perform specific operations using the ApplicationControl (in mobile and wearable applications) and RequestedApplicationControl (in mobile and wearable applications) interfaces. The operations can be, for example, making a phone call, browsing local files so the user can pick an image of their choosing, or playing a video in a video player.

    With the application control, you can send a request to launch other applications based on their functionality using the launchAppControl() method of the ApplicationManager interface. The launched provider application performs a specific operation and sends back a response.

    Your application can export application control functionality. This means that the application can register itself as a provider application, allowing it to receive application control requests from other applications. You can handle an incoming application control request using the getRequestedAppControl() method of the Application interface, and respond to the incoming request using the RequestedApplicationControl interface.

  • Event handling

    You can send and receive events between 2 applications using events. Your application can broadcast its own events, and listen for events broadcast by others.

  • Background execution

    Usually, when a Web application moves to the background, it gets suspended. To enable background execution, you must declare a background category for your application.

Application Controls

An application control is a mechanism for using operations, such as calling, Web browsing, and playing media items, which are exported by other applications. It allows you to conveniently launch other applications whose functionalities you need in your application. If you need to use functionality from another application, launching an application control allows you to request the system to launch that application according to your requirements. You can launch applications based on your immediate needs - you do not need to know their identifiers or specifications.

Each application has a launch mode, which determines how the application is launched: in a separate instance or in the same group as the calling application. For more information on the launch modes, see Application Group.

The application control consists of an operation, URI, MIME type, and some data, and it describes the request to be performed by the newly launched application. This information is used to resolve the application control. When the system gets an application control request, it finds the proper provider application by resolving the application control, and then launches the provider application. Once the provider application has performed the requested task, it must pass control back to the calling application and provide the result of the operation. Basically, the application control process flows as follows:

  1. The calling application launches the application control with the launchAppControl() method of the Application interface.
  2. The provider application calls the getRequestedAppControl() method of the Application interface to get the reference of the RequestedApplicationControl object. This object contains the application control passed by the launchAppControl() method from the calling application.
  3. The provider application calls either the replyResult() method (in case of success) or the replyFailure() method (in case of failure) of the RequestedApplicationControl interface to return control back to the calling application. The result of the provided operation (if any), is delivered as an array of ApplicationControlData objects (in mobile and wearable applications).
  4. The calling application receives the result through the ApplicationControlDataArrayReplyCallback event handler (in mobile and wearable applications).

The application control uses the following primary information:

  • Application ID

    Used to identify the provider application of the requested application control. Besides the application ID, a common application control has a special alias name for the application ID with the prefix tizen. For example, the platform phone application has the alias application ID of tizen.phone.

    Used to identify the provider application of the requested application control.

    Note
    From Tizen 2.4 onwards, the platform-defined application controls and aliased application IDs which were defined in previous Tizen versions may not be supported. If they are used, the application control behavior is undefined and cannot be guaranteed.
  • Operation

    Describes an action to be performed by the provider application. The operation ID of the platform-provided operation is in the http://tizen.org/appcontrol/operation/<verb> format. For example, http://tizen.org/appcontrol/operation/view. For more information on valid operations, see Common Application Controls.

There are different types of application control requests for launching other applications:

  • Explicit launch

    You determine which application must be launched by explicitly specifying an application ID. The application ID determines which application is launched and the application performs the operation as specified in the application control request.

  • Implicit launch

    You provide information to describe the request to be performed by the newly launched application without specifying the application ID. The system uses the information to resolve the application control. It does this by trying to find a proper application to perform the application control request and then launching the selected application.

You can take advantage of the Tizen common application functionalities through the application control feature. You can also export your application functionality to allow other applications to launch your application.

Explicit Launch

If you specify the exact application ID of the application for the launchAppControl() method of the Application interface, you can request the application control from a specific application. The application ID determines which application is launched and the application performs the operation as specified in the control request.

Note
An explicit launch request cannot be completed if the user does not have the specified application on their device. Hence implicit launches can be more effective, because the system can find an available application to complete the request. The implicit launch can also enhance the user experience because it allows the user to select a preferred application to complete the task.

Implicit Launch

If you do not explicitly provide an exact application ID with the application control request in the launchAppControl() method of the Application interface, you must provide enough information for the system to determine which of the available applications can best handle the control request. For example, the nature of the service or the file types that the application can handle.

The application control consists of an operation ID, URI, MIME type, some additional data, and a launch mode setting. The system compares some of the attributes of the control request against the service descriptions of the installed applications to determine which of the available applications are suitable for the request. The request is resolved only if all specified information matches the service descriptions retrieved from the installed applications. The application control data attribute is not used in resolving the control request.

The following attributes are used to resolve application control requests:

  • Operation

    Mandatory string that defines the action to be performed by the application control. You can define your own operation to describe a specific action of your application.

  • URI scheme

    Data on which the action is performed. For example, if you want to use the http://tizen.org/appcontrol/operation/view operation to view a specific image, the URI must be the URI of the image (which can be obtained using the toURI() method after resolving the file path). The same operation can be used to launch a Web page in a browser, except that the URI in that case is the URL of the Website, such as https://www.tizen.org/.

  • MIME type

    Specific type of the URI. For example, if you want to view only JPEG images, you must use the image/jpeg MIME type. The MIME type can be important because it ensures that the system finds an application that is capable of supporting a specified MIME type.

For more information on valid operations, see Common Application Controls. You can also see which operations allow a URI to be specified and which MIME types an operation supports.

The following code example shows an ApplicationControl instance (in mobile and wearable applications) that launches an application to pick images. If there are multiple applications that can fulfill the request, the system shows a pop-up which allows the user to select the application of their choice:

var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/pick",
                                              null, "image/*", null, null);

tizen.application.launchAppControl(appControl, null, successCb, errCb, null);

Selecting and Launching a Suitable Application

To select and launch an application that provides a specific operation, you can use the findAppControl() method of Application interface to search for applications which provide the functionalities that you need. The following code example demonstrates an implicit launch of an application to provide the image view operation that is found using the findAppControl() method:

/* Assuming that the filesystem virtual root "images" has been resolved and saved in variable images */
var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/view",
                                              images.resolve("image12.jpg").toURI(),
                                              "image/*", null , null);

tizen.application.findAppControl(appControl, function(appInfos, appCtrl) 
{
   if (appInfos.length >= 1) 
   {
      tizen.application.launchAppControl(appCtrl, appInfos[0].id, successCB, errCB, null);
   }
}, function(e) {/* Error handling */});

Common Application Controls

The Tizen common application controls specify a standard protocol for sharing application functionalities. You can use the common application controls to perform some basic tasks, such as selecting a file or taking a picture.

The following common application controls are available:

Exporting Application Control Functionality

The system compares the attributes of the application control request against the service descriptions of installed applications to determine which of the available applications are suitable for the request. The service description of the installed applications contains information about the requests that they can handle. The request is resolved only if all specified information in the request matches with the service description retrieved from an installed application. The application control data attribute is not used in resolving the control request.

To advertise your application features to other applications, allow other applications to use the functionalities of your application, and launch your application implicitly without an application ID, you can define 1 or more application control service descriptions in the config.xml file of your application. Each description specifies the operation, URI scheme, and MIME type of the application control service your application can offer.

The following code example shows a service description which allows an application to handle requests to view JPEG images:

  • The src field describes the application page (usually an HTML file) that handles the request.
  • The operation field is mandatory, while the uri and mime fields are optional. If the value of uri field is file, the value can be left out.
  • The uri field in the service description is used to inform the platform about how to interpret and process the rest of the URI. For example, the http URI scheme informs the platform to interpret and process the URI as a Web resource using HTTP. However, if the uri field value is set to file, leave the attribute out of the service description.
<tizen:app-control>
   <src name="view.html"/>
   <operation name="http://tizen.org/appcontrol/operation/view"/>
   <uri name="file"/>
   <mime name="image/jpeg"/>
</tizen:app-control>

For example, consider the following example of an ApplicationControl instance:

/* Assuming that the filesystem virtual root "images" has been resolved and saved in variable images */
var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/view",
                                              images.resolve("image12.jpg").toURI(),
                                              null, null , null);

When the system attempts to resolve the request and find the application to be launched, it checks the service descriptions. In the following example, the application with the first service description is not launched, since the uri information does not match the request. However, the application with the second service description is a match and can be launched:

<!--First service description: not a match-->
<tizen:app-control>
   <operation name="http://tizen.org/appcontrol/operation/view"/>
   <uri name="file"/>
   <mime name="image/*"/>
</tizen:app-control>

<!--Second service description: a match-->
<tizen:app-control>
   <operation name="http://tizen.org/appcontrol/operation/view"/>
   <mime name="image/*"/>
</tizen:app-control>

If your application offers the same service (operation) with different parameters (for example, different MIME types), you must define each set of parameters separately in their own service description. For example, if your application can handle both image and audio file MIME types with the view operation, 2 <tizen:app-control> elements with different MIME types and the same http://tizen.org/appcontrol/operation/view operation are required. The following example shows how to define the service descriptions for 2 MIME types for the same operation in the config.xml file:

<tizen:app-control>
   <operation name="http://tizen.org/appcontrol/operation/view"/>
   <mime name="image/*"/>
</tizen:app-control>

<tizen:app-control>
   <operation name="http://tizen.org/appcontrol/operation/view"/>
   <mime name="audio/*"/>
</tizen:app-control>

Using the appcontrol Event Instead of Page Reloading

When a Web application receives an application control request from another application, the receiving application finds the proper page for that request and loads that page. If the found page is already loaded and displayed, the page is reloaded (refreshed) to process the incoming application control request. However, in some cases, a Web application is able to handle the application control request without reloading the page in order to keep the previous context.

From Tizen 2.4 onwards, the Web runtime provides a way to handle application control requests without page reloading by extending the <tizen:app-control> element of the config.xml file and sending a new appcontrol event to the receiving application.

The following code example demonstrates a service description in the config.xml file, which can handle an image editing application control request without reloading the Web page:

<tizen:app-control>
   <src name="edit.html" reload="disable"/>
   <operation name="http://tizen.org/appcontrol/operation/edit"/>
   <mime name="image/*"/>
</tizen:app-control>

The reload attribute is added to the src element (in mobile and wearable applications), and used to set whether the page must be reloaded when an application control request is received. The reload attribute is optional and the default value is enable. If the attribute is not set, the page reloads.

If the currently loaded page is selected by an incoming application control request, and the reload attribute of the service description is set to disable, an appcontrol event is dispatched to that page instead of reloading it. By using an appcontrol event listener, the Web application can get the requested information by calling the getRequestedAppControl() method of the Application interface. An appcontrol event is dispatched only if the reload attribute of the service description is set to disable.

The following example demonstrates adding an appcontrol event listener and handling an event:

window.addEventListener("appcontrol", function onAppControl()
{
   var reqAppControl = tizen.application.getCurrentApplication.getRequestedAppControl();
   if (reqAppControl)
   {
      // Handle the application control request
   }
});

Broadcasting and Listening for Events

Since Tizen 2.4, Web applications can broadcast their own events to all listeners who are listening for these events. Web applications can also broadcast trusted events for trusted listeners who have the same certificate as the sender application.

To manage event broadcasting:

  • You can broadcast an event with the broadcastEvent() or broadcastTrustedEvent() method.
  • You can receive event data from other applications with the addEventListener() method.
  • You can stop receiving event data from other applications with the removeEventListener() method.

Allowing Applications to Run on the Background

When a Web application becomes invisible (moves to the background), it is suspended. Before Tizen 2.4, to continue to execute the application on the background, you had to set the background-support attribute of the <tizen:setting> element to enable in the config.xml file (in mobile and wearable applications).

Since Tizen 2.4, the background process management policy has been changed. The system does not allow applications to run on the background except when they are explicitly declared to do so by having a specific background category. For more information on the available background categories, see the Allowed background application policy table.

Note
To guarantee that a Web application runs on the background, at least one background-category element must be declared in the config.xml file (in mobile and wearable applications), and the background-support attribute of the <tizen:setting> element must be set to enable.

The following config.xml file example shows how an application can be configured to run on the background:

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets" xmlns:tizen="http://tizen.org/ns/widgets" 
        id="http://yourdomain/BackgroundCategory" version="1.0.0" viewmodes="maximized">
   <tizen:application id="background.category" package="background" required_version="2.4"/>
   <content src="index.html"/>
   <icon src="icon.png"/>
   <name>BackgroundCategoryTest</name>
   <tizen:background-category value="media"/>
   <tizen:background-category value="download"/>
   <tizen:background-category value="background-network"/>
   <tizen:setting background-support="enable"/>
</widget>
Go to top