From 89d4a5c5df14f085387032830a87afd73296971c Mon Sep 17 00:00:00 2001 From: Pawel Kaczmarek Date: Thu, 27 Aug 2015 13:35:03 +0200 Subject: [PATCH] [Web Device Api][Application] Add info about broadcasting user events Change-Id: I4596fc2de121e6b6f47b358506a806e83e5d3e93 Signed-off-by: Pawel Kaczmarek --- .../html/web/tizen/application/application_w.htm | 29 +- .../tizen/application/application_tutorial_w.htm | 41 +- .../html/device_api/mobile/tizen/application.html | 445 ++++++++++++++++++- .../device_api/wearable/tizen/application.html | 469 ++++++++++++++++++++- 4 files changed, 945 insertions(+), 39 deletions(-) diff --git a/org.tizen.guides/html/web/tizen/application/application_w.htm b/org.tizen.guides/html/web/tizen/application/application_w.htm index 9fcb63c..50e020b 100644 --- a/org.tizen.guides/html/web/tizen/application/application_w.htm +++ b/org.tizen.guides/html/web/tizen/application/application_w.htm @@ -476,7 +476,34 @@ window.addEventListener("appcontrol", function onAppControl()    } }); +

Broadcasting and listening to the events

+

Since Tizen 2.4 Web applications can broadcast own events. Events can be broadcasted to all listeners which are listening for these events.

+

Web applications can also broadcast trusted events only for trusted listeners with the same certificate as the sender's application.

+

The following code example demonstrates how to broadcast an event:

+
+var app = tizen.application.getCurrentApplication();
+var appEvent = {name: "custom_user_event"};
+var data = {foo: "bar"};
+
+app.broadcastEvent(appEvent, data);
+
+// for trusted events
+app.broadcastTrustedEvent(appEvent, data);
+
+ +

If you want to receive event data from other application addEventListener() with sender's application ID and event name should be invoked.

+
+var watchId = app.addEventListener({appId: "a234567890.TestWidget", name: "custom_user_event"}, function(event, data) {
+   console.log("Data: " + JSON.stringify(data));
+   // do something
+});
+
+ +

If you want to stop receiving event data from other application removeEventListener() with proper watchId should be invoked.

+
+app.removeEventListener(watchId);
+
@@ -500,4 +527,4 @@ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga - \ No newline at end of file + diff --git a/org.tizen.tutorials/html/web/tizen/application/application_tutorial_w.htm b/org.tizen.tutorials/html/web/tizen/application/application_tutorial_w.htm index d88ca54..9232809 100644 --- a/org.tizen.tutorials/html/web/tizen/application/application_tutorial_w.htm +++ b/org.tizen.tutorials/html/web/tizen/application/application_tutorial_w.htm @@ -257,8 +257,45 @@ try

For more information on launching an application, see Launching Applications with the Application Control.

- - + +

Broadcasting and listening to the events

+ +

Learning how to broadcast and listen to the events allows you to create Web applications that can send and receive data between each other.

+
    +
  1. The first application can broadcast an event. +

    To broadcast events use broadcastEvent() method:

    +
    +var app = tizen.application.getCurrentApplication();
+var appEvent = {name: "first_app_event_1"};
+var data = {foo: "bar"};
+
+app.broadcastEvent(appEvent, data);
+
    +

    Web applications can also broadcast trusted events only for trusted listeners with the same certificate as the sender's application.

    +

    To broadcast trusted events use broadcastTrustedEvent() method:

    +
    +app.broadcastTrustedEvent(appEvent, data);
+
    +
    2. +
  2. +The second application can listen to first application and receives data. +

    To receive data from the first application use addEventListener() method with sender's application ID and event name.

    +
    +var app = tizen.application.getCurrentApplication();
+
+var watchId = app.addEventListener({appId: "a234567890.FirstApp", name: "first_app_event_1"}, function(event, data) {
+   /* data from first app should be received here */
+   console.log("Data: " + JSON.stringify(data));
+});
+
    + +

    To stop receiving data from the first application use removeEventListener() method with proper watchId.

    +
    +app.removeEventListener(watchId);
+
    +
    3. +
+ diff --git a/org.tizen.web.apireference/html/device_api/mobile/tizen/application.html b/org.tizen.web.apireference/html/device_api/mobile/tizen/application.html index b178a02..f577379 100644 --- a/org.tizen.web.apireference/html/device_api/mobile/tizen/application.html +++ b/org.tizen.web.apireference/html/device_api/mobile/tizen/application.html @@ -29,6 +29,9 @@ The Application interface defines the current application's information the basic operations for the current application such as exit or hide.

+Since Tizen 2.4 the Application interface provides application event broadcasting and listening features. An application can broadcast user events to other listening applications and listen to broadcasted user events from other applications. In a future Tizen release, applications will also be able to receive pre-defined system events from the platform. +

+

For more information on the Application features, see Application Guide.

@@ -43,7 +46,11 @@ For more information on the Application features, see ApplicationContextId -
  • 1.3. ApplicationControlLaunchMode +
  • 1.3. UserEventData +
    • +
  • 1.4. EventData +
    • +
  • 1.5. ApplicationControlLaunchMode
    • @@ -78,6 +85,12 @@ For more information on the Application features, see ApplicationInformationEventCallback +
  • 2.16. SystemEventData +
    • +
  • 2.17. EventCallback +
    • +
  • 2.18. EventInfo +
  • 3. Full WebIDL @@ -117,7 +130,11 @@ For more information on the Application features, see Application void exit ()
    void hide ()
    - RequestedApplicationControl getRequestedAppControl () + RequestedApplicationControl getRequestedAppControl ()
    + long addEventListener (EventInfo event, EventCallback callback)
    + void removeEventListener (long watchId)
    + void broadcastEvent (EventInfo event, UserEventData data)
    + void broadcastTrustedEvent (EventInfo event, UserEventData data) ApplicationInformation @@ -171,6 +188,18 @@ For more information on the Application features, see onupdated (ApplicationInformation info)
    void onuninstalled (ApplicationId id) + +SystemEventData + + + +EventCallback +void onevent (EventInfo event, EventData data) + + +EventInfo + +
    @@ -197,8 +226,30 @@ For more information on the Application features, see +

    1.3. UserEventData

    +
    + Specifies the user event data. +
    +
      typedef object UserEventData;
    +

    + Since: + 2.4 +

    +
    +
    +

    1.4. EventData

    +
    + Specifies the user or system defined event data. +
    +
      typedef (SystemEventData or UserEventData) EventData;
    +

    + Since: + 2.4 +

    +
    -

    1.3. ApplicationControlLaunchMode

    +

    1.5. ApplicationControlLaunchMode

    Specifies the application launch mode when it is launched by launchAppControl(). This value may be overriden if application launched by launchAppControl() has value SINGLE configured in application manifest.
    @@ -287,7 +338,6 @@ The tizen.application object allows access to the Application API's fun long addAppInfoEventListener(ApplicationInformationEventCallback eventCallback) raises(WebAPIException); void removeAppInfoEventListener(long watchId) raises(WebAPIException); - };

    Since: @@ -1106,7 +1156,7 @@ an empty array is returned on a device.

    Deprecated. - Deprecated since Tizen 2.4. Instead, use tizen.package.setPackageInfoEventListener() allows the app developers to set a listener for getting notified for the changes(add/remove/update) of applications on a device. + Deprecated since 2.4. Instead, tizen.package.setPackageInfoEventListener() allows the app developers to set a listener for getting notified for the changes(add/remove/update) of applications on a device. 

    long addAppInfoEventListener(ApplicationInformationEventCallback eventCallback);
    @@ -1241,6 +1291,14 @@ the basic operations (such as exit or hide) for the current application. void hide() raises(WebAPIException); RequestedApplicationControl getRequestedAppControl() raises(WebAPIException); + + long addEventListener(EventInfo event, EventCallback callback) raises(WebAPIException); + + void removeEventListener(long watchId) raises(WebAPIException); + + void broadcastEvent(EventInfo event, UserEventData data) raises(WebAPIException); + + void broadcastTrustedEvent(EventInfo event, UserEventData data) raises(WebAPIException); };

    Since: @@ -1373,6 +1431,220 @@ appropriately when it is launched. +

    +addEventListener +
    +
    +
    + Adds a listener which will invoke a callback function when an event occurs. +
    +
    long addEventListener(EventInfo event, EventCallback callback);
+
    +

    + Since: + 2.4 +

    +
    +

    +System events do not require an application identifier to be specified. Therefore, the appId attribute of the EventInfo dictionary should not be specified when listening for system events. If it is specified, the event to listen for will be interpreted as an user event. +

    +
    +
    +

    Parameters:

    +
      +
    • +event: + Event which will invoke the callback +
      • +
    • +callback: + Callback function to be invoked when the event occurs +
      • +
    +
    +
    +

    Return value:

    + long Listener identifier +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type TypeMismatchError, if any input parameter is not compatible with the expected type. +

        • +

      • + with error type UnknownError in any other error case. +

        • +
      +
    +
    +
    +

    Code example:

     var app = tizen.application.getCurrentApplication();
+
+ // for user events: sender's application ID  and event name must be provided by using a dictionary
+ var watchId = app.addEventListener({"appId": "a234567890.TestWidget", "name": "custom_user_event"}, function(event, data) {
+   console.log("Data: " + JSON.stringify(data));
+   // do something
+ });
+
    +
    +
    +
    +removeEventListener +
    +
    +
    + Removes an event listener with a specified listener identifier. +
    +
    void removeEventListener(long watchId);
+
    +

    + Since: + 2.4 +

    +
    +

    Parameters:

    +
      +
    • +watchId: + Listener identifier +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException

      • + with error type UnknownError in any other error case. +

      +
    +
    +
    +

    Code example:

     var watchId, app = tizen.application.getCurrentApplication();
+
+ function eventListenerCallback(event, data) {
+   console.log("Data: " + JSON.stringify(data));
+   // do something and then remove the listener
+   app.removeEventListener(watchId);
+ }
+
+ watchId = app.addEventListener({"appId": "a234567890.TestWidget", "name": "custom_user_event"}, eventListenerCallback);
+
    +
    +
    +
    +broadcastEvent +
    +
    +
    + Broadcasts a user defined event to all the listeners which are listening for this event. +
    +
    void broadcastEvent(EventInfo event, UserEventData data);
+
    +

    + Since: + 2.4 +

    +
    +

    +An application can listen to events from other applications. However, it can only broadcast it's own events. Therefore, the appId attribute of the EventInfo dictionary must be the identifier of the application which calls this method. +

    +
    +
    +

    Parameters:

    +
      +
    • +event: + Event to broadcast +
      • +
    • +data: + User defined event data to broadcast +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter. +

        • +

      • + with error type InvalidValuesError, if any of the input parameters contain an invalid value. +

        • +

      • + with error type UnknownError in any other error case. +

        • +
      +
    +
    +
    +

    Code example:

     var myCustomData = {
+   foo: 'bar'
+ };
+
+ var app = tizen.application.getCurrentApplication();
+
+ app.broadcastEvent({"name": "custom_user_event"}, myCustomData);
+
    +
    +
    +
    +broadcastTrustedEvent +
    +
    +
    + Broadcasts a user defined event to all the trusted listeners which are listening for this event. Applications which have the same certificate as the sending application can receive the event. +
    +
    void broadcastTrustedEvent(EventInfo event, UserEventData data);
+
    +

    + Since: + 2.4 +

    +
    +

    +An application can listen to events from other applications. However, it can only broadcast it's own events. Therefore, the appId attribute of the EventInfo dictionary must be the identifier of the application which calls this method. +

    +
    +
    +

    Parameters:

    +
      +
    • +event: + Trusted event to broadcast +
      • +
    • +data: + User defined trusted event data to broadcast +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter. +

        • +

      • + with error type InvalidValuesError, if any of the input parameters contain an invalid value. +

        • +

      • + with error type UnknownError in any other error case. +

        • +
      +
    +
    +
    +

    Code example:

     var myTrustedCustomData = {
+   foo: 'bar'
+ };
+
+ var app = tizen.application.getCurrentApplication();
+
+ app.broadcastTrustedEvent({"name": "custom_user_event"}, myTrustedCustomData);
+
    +
    +
    @@ -1529,7 +1801,6 @@ application. readonly attribute ApplicationContextId id; readonly attribute ApplicationId appId; - };

    Since: @@ -1573,7 +1844,6 @@ between applications through the ApplicationControl interface. attribute DOMString key; attribute DOMString[] value; - };

    Since: @@ -1638,7 +1908,6 @@ and launches the selected application. attribute ApplicationControlData[] data; attribute ApplicationControlLaunchMode launchMode; - };

    Since: @@ -1739,7 +2008,6 @@ required action requested by the calling application. void replyResult(optional ApplicationControlData[]? data) raises(WebAPIException); void replyFailure() raises(WebAPIException); - };

    Since: @@ -1865,7 +2133,6 @@ to perform the requested action. readonly attribute DOMString type; readonly attribute DOMString value; - };

    Since: @@ -1907,7 +2174,6 @@ to perform the requested action. readonly attribute DOMString key; readonly attribute DOMString value; - };

    Since: @@ -2250,6 +2516,129 @@ an application is installed, updated, or uninstalled. +

    +

    2.16. SystemEventData

    +
    + The SystemEventData interface defines what is retrieved from the event listener. +
    +
      [NoInterfaceObject] interface SystemEventData {
+    attribute DOMString value;
+    attribute DOMString type;
+  };
    +

    + Since: + 2.4 +

    +
    +

    +Platform modules will be able to broadcast system events in a future Tizen release. +

    +
    +
    +
    +

    2.17. EventCallback

    +
    + The EventCallback interface specifies a callback for getting notified when a specified event occurs. +
    +
      [Callback=FunctionOnly, NoInterfaceObject] interface EventCallback {
+    void onevent(EventInfo event, EventData data);
+  };
    +

    + Since: + 2.4 +

    +
    +

    Methods

    +
    +
    +onevent +
    +
    +
    + Called when the event occurs. +
    +
    void onevent(EventInfo event, EventData data);
+
    +

    + Since: + 2.4 +

    +
    +

    Parameters:

    +
      +
    • +event: + Broadcasted event which invokes this callback +
      • +
    • +data: + Broadcasted event data +
      • +
    +
    +
    +
    +
    +
    +
    +

    2.18. EventInfo

    +
    + The EventInfo dictionary identifies an event with information such as event name. If it is an user event, the broadasting application's identifier is also specified. +
    +
      dictionary EventInfo {
+    ApplicationId appId;
+
+    DOMString name;
+  };
    +

    + Since: + 2.4 +

    +
    +

    +System events do not require an application identifier to be specified. If one is specified, the event will be interpreted as an user event. +

    +
    +
    +

    Dictionary members

    +
    +
    ApplicationId appId
    +
    +
    + The unique identifier of the application which is broadcasting an event. +
    +
    +

    +An application can listen to events from other applications. However, it can only broadcast it's own events. Therefore, when broadcasting an event, this dictionary member must be the identifier of the application which is broadcasting the event. +

    +

    +System events do not require an application identifier to be specified. If one is specified, the event will be interpreted as an user event. +

    +
    +

    + Since: + 2.4 +

    +
    +
    DOMString name
    +
    +
    + Name which describes the event. +
    +
    +

    +Must only contain the ASCII characters "[A-Z][a-z][0-9]_" and may not begin with a digit. +Must be at least 1 byte in length and not exceed the maximum name length of 127 bytes. +

    +
    +

    + Since: + 2.4 +

    +
    +
    +
    +

    3. Full WebIDL

    module Application {
@@ -2258,6 +2647,10 @@ an application is installed, updated, or uninstalled.
 
   typedef DOMString ApplicationContextId;
 
+  typedef object UserEventData;
+
+  typedef (SystemEventData or UserEventData) EventData;
+
   enum ApplicationControlLaunchMode { "SINGLE", "GROUP" };
 
   [NoInterfaceObject] interface ApplicationManagerObject {
@@ -2306,7 +2699,6 @@ an application is installed, updated, or uninstalled.
     long addAppInfoEventListener(ApplicationInformationEventCallback eventCallback) raises(WebAPIException);
 
     void removeAppInfoEventListener(long watchId) raises(WebAPIException);
-
   };
 
   [NoInterfaceObject] interface Application {
@@ -2320,8 +2712,15 @@ an application is installed, updated, or uninstalled.
     void hide() raises(WebAPIException);
 
     RequestedApplicationControl getRequestedAppControl() raises(WebAPIException);
-  };
 
+    long addEventListener(EventInfo event, EventCallback callback) raises(WebAPIException);
+
+    void removeEventListener(long watchId) raises(WebAPIException);
+
+    void broadcastEvent(EventInfo event, UserEventData data) raises(WebAPIException);
+
+    void broadcastTrustedEvent(EventInfo event, UserEventData data) raises(WebAPIException);
+  };
 
   [NoInterfaceObject] interface ApplicationInformation {
 
@@ -2349,7 +2748,6 @@ an application is installed, updated, or uninstalled.
     readonly attribute ApplicationContextId id;
 
     readonly attribute ApplicationId appId;
-
   };
 
   [Constructor(DOMString key, DOMString[] value)]
@@ -2358,7 +2756,6 @@ an application is installed, updated, or uninstalled.
     attribute DOMString key;
 
     attribute DOMString[] value;
-
   };
 
   [Constructor(DOMString operation, optional DOMString? uri,
@@ -2377,7 +2774,6 @@ an application is installed, updated, or uninstalled.
     attribute ApplicationControlData[] data;
 
     attribute ApplicationControlLaunchMode launchMode;
-
   };
 
   [NoInterfaceObject] interface RequestedApplicationControl {
@@ -2389,7 +2785,6 @@ an application is installed, updated, or uninstalled.
     void replyResult(optional ApplicationControlData[]? data) raises(WebAPIException);
 
     void replyFailure() raises(WebAPIException);
-
   };
 
   [NoInterfaceObject] interface ApplicationCertificate {
@@ -2397,7 +2792,6 @@ an application is installed, updated, or uninstalled.
     readonly attribute DOMString type;
 
     readonly attribute DOMString value;
-
   };
 
   [NoInterfaceObject] interface ApplicationMetaData {
@@ -2405,7 +2799,6 @@ an application is installed, updated, or uninstalled.
     readonly attribute DOMString key;
 
     readonly attribute DOMString value;
-
   };
 
 
@@ -2435,6 +2828,20 @@ an application is installed, updated, or uninstalled.
     void onuninstalled(ApplicationId id);
   };
 
+  [NoInterfaceObject] interface SystemEventData {
+    attribute DOMString value;
+    attribute DOMString type;
+  };
+
+  [Callback=FunctionOnly, NoInterfaceObject] interface EventCallback {
+    void onevent(EventInfo event, EventData data);
+  };
+
+  dictionary EventInfo {
+    ApplicationId appId;
+
+    DOMString name;
+  };
 };
    diff --git a/org.tizen.web.apireference/html/device_api/wearable/tizen/application.html b/org.tizen.web.apireference/html/device_api/wearable/tizen/application.html index ff2bbfd..2f05d03 100644 --- a/org.tizen.web.apireference/html/device_api/wearable/tizen/application.html +++ b/org.tizen.web.apireference/html/device_api/wearable/tizen/application.html @@ -29,6 +29,9 @@ The Application interface defines the current application's information the basic operations for the current application such as exit or hide.

    +Since Tizen 2.4 the Application interface provides application event broadcasting and listening features. An application can broadcast user events to other listening applications and listen to broadcasted user events from other applications. In a future Tizen release, applications will also be able to receive pre-defined system events from the platform. +

    +

    For more information on the Application features, see Application Guide.

    @@ -43,6 +46,12 @@ For more information on the Application features, see ApplicationContextId
    • +
  • 1.3. UserEventData +
    • +
  • 1.4. EventData +
    • +
  • 1.5. ApplicationControlLaunchMode +
  • 2. Interfaces
  • 3. Full WebIDL @@ -115,7 +130,11 @@ For more information on the Application features, see Application void exit ()
    void hide ()
    - RequestedApplicationControl getRequestedAppControl () + RequestedApplicationControl getRequestedAppControl ()
    + long addEventListener (EventInfo event, EventCallback callback)
    + void removeEventListener (long watchId)
    + void broadcastEvent (EventInfo event, UserEventData data)
    + void broadcastTrustedEvent (EventInfo event, UserEventData data) ApplicationInformation @@ -169,6 +188,18 @@ For more information on the Application features, see onupdated (ApplicationInformation info)
    void onuninstalled (ApplicationId id) + +SystemEventData + + + +EventCallback +void onevent (EventInfo event, EventData data) + + +EventInfo + +
    @@ -195,6 +226,50 @@ For more information on the Application features, see +

    1.3. UserEventData

    +
    + Specifies the user event data. +
    +
      typedef object UserEventData;
    +

    + Since: + 2.4 +

    +
    +
    +

    1.4. EventData

    +
    + Specifies the user or system defined event data. +
    +
      typedef (SystemEventData or UserEventData) EventData;
    +

    + Since: + 2.4 +

    +
    +
    +

    1.5. ApplicationControlLaunchMode

    +
    + Specifies the application launch mode when it is launched by launchAppControl(). This value may be overriden if application launched by launchAppControl() has value SINGLE configured in application manifest. +
    +
      enum ApplicationControlLaunchMode { "SINGLE", "GROUP" };
    +

    + Since: + 2.4 +

    +
    +

    +The launch modes defined by this enumerator are: +

    +
      +
    • +SINGLE - Launch application as standalone instance
      • +
    • +GROUP - Launch application in subgroup
      • +
    +
    +

    2. Interfaces

    @@ -263,7 +338,6 @@ The tizen.application object allows access to the Application API's fun long addAppInfoEventListener(ApplicationInformationEventCallback eventCallback) raises(WebAPIException); void removeAppInfoEventListener(long watchId) raises(WebAPIException); - };

    Since: @@ -1082,7 +1156,7 @@ an empty array is returned on a device.

    Deprecated. - Deprecated since Tizen 2.4. Instead, use tizen.package.setPackageInfoEventListener() allows the app developers to set a listener for getting notified for the changes(add/remove/update) of applications on a device. + Deprecated since 2.4. Instead, tizen.package.setPackageInfoEventListener() allows the app developers to set a listener for getting notified for the changes(add/remove/update) of applications on a device. 

    long addAppInfoEventListener(ApplicationInformationEventCallback eventCallback);
    @@ -1172,7 +1246,7 @@ applications on a device.

    Parameters:

    • -watchId: +watchId: An ID that identifies the listener
    @@ -1217,6 +1291,14 @@ the basic operations (such as exit or hide) for the current application. void hide() raises(WebAPIException); RequestedApplicationControl getRequestedAppControl() raises(WebAPIException); + + long addEventListener(EventInfo event, EventCallback callback) raises(WebAPIException); + + void removeEventListener(long watchId) raises(WebAPIException); + + void broadcastEvent(EventInfo event, UserEventData data) raises(WebAPIException); + + void broadcastTrustedEvent(EventInfo event, UserEventData data) raises(WebAPIException); };

    Since: @@ -1349,6 +1431,220 @@ appropriately when it is launched. +

    +addEventListener +
    +
    +
    + Adds a listener which will invoke a callback function when an event occurs. +
    +
    long addEventListener(EventInfo event, EventCallback callback);
+
    +

    + Since: + 2.4 +

    +
    +

    +System events do not require an application identifier to be specified. Therefore, the appId attribute of the EventInfo dictionary should not be specified when listening for system events. If it is specified, the event to listen for will be interpreted as an user event. +

    +
    +
    +

    Parameters:

    +
      +
    • +event: + Event which will invoke the callback +
      • +
    • +callback: + Callback function to be invoked when the event occurs +
      • +
    +
    +
    +

    Return value:

    + long Listener identifier +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type TypeMismatchError, if any input parameter is not compatible with the expected type. +

        • +

      • + with error type UnknownError in any other error case. +

        • +
      +
    +
    +
    +

    Code example:

     var app = tizen.application.getCurrentApplication();
+
+ // for user events: sender's application ID  and event name must be provided by using a dictionary
+ var watchId = app.addEventListener({"appId": "a234567890.TestWidget", "name": "custom_user_event"}, function(event, data) {
+   console.log("Data: " + JSON.stringify(data));
+   // do something
+ });
+
    +
    +
    +
    +removeEventListener +
    +
    +
    + Removes an event listener with a specified listener identifier. +
    +
    void removeEventListener(long watchId);
+
    +

    + Since: + 2.4 +

    +
    +

    Parameters:

    +
      +
    • +watchId: + Listener identifier +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException

      • + with error type UnknownError in any other error case. +

      +
    +
    +
    +

    Code example:

     var watchId, app = tizen.application.getCurrentApplication();
+
+ function eventListenerCallback(event, data) {
+   console.log("Data: " + JSON.stringify(data));
+   // do something and then remove the listener
+   app.removeEventListener(watchId);
+ }
+
+ watchId = app.addEventListener({"appId": "a234567890.TestWidget", "name": "custom_user_event"}, eventListenerCallback);
+
    +
    +
    +
    +broadcastEvent +
    +
    +
    + Broadcasts a user defined event to all the listeners which are listening for this event. +
    +
    void broadcastEvent(EventInfo event, UserEventData data);
+
    +

    + Since: + 2.4 +

    +
    +

    +An application can listen to events from other applications. However, it can only broadcast it's own events. Therefore, the appId attribute of the EventInfo dictionary must be the identifier of the application which calls this method. +

    +
    +
    +

    Parameters:

    +
      +
    • +event: + Event to broadcast +
      • +
    • +data: + User defined event data to broadcast +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter. +

        • +

      • + with error type InvalidValuesError, if any of the input parameters contain an invalid value. +

        • +

      • + with error type UnknownError in any other error case. +

        • +
      +
    +
    +
    +

    Code example:

     var myCustomData = {
+   foo: 'bar'
+ };
+
+ var app = tizen.application.getCurrentApplication();
+
+ app.broadcastEvent({"name": "custom_user_event"}, myCustomData);
+
    +
    +
    +
    +broadcastTrustedEvent +
    +
    +
    + Broadcasts a user defined event to all the trusted listeners which are listening for this event. Applications which have the same certificate as the sending application can receive the event. +
    +
    void broadcastTrustedEvent(EventInfo event, UserEventData data);
+
    +

    + Since: + 2.4 +

    +
    +

    +An application can listen to events from other applications. However, it can only broadcast it's own events. Therefore, the appId attribute of the EventInfo dictionary must be the identifier of the application which calls this method. +

    +
    +
    +

    Parameters:

    +
      +
    • +event: + Trusted event to broadcast +
      • +
    • +data: + User defined trusted event data to broadcast +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter. +

        • +

      • + with error type InvalidValuesError, if any of the input parameters contain an invalid value. +

        • +

      • + with error type UnknownError in any other error case. +

        • +
      +
    +
    +
    +

    Code example:

     var myTrustedCustomData = {
+   foo: 'bar'
+ };
+
+ var app = tizen.application.getCurrentApplication();
+
+ app.broadcastTrustedEvent({"name": "custom_user_event"}, myTrustedCustomData);
+
    +
    +
    @@ -1505,7 +1801,6 @@ application. readonly attribute ApplicationContextId id; readonly attribute ApplicationId appId; - };

    Since: @@ -1549,7 +1844,6 @@ between applications through the ApplicationControl interface. attribute DOMString key; attribute DOMString[] value; - };

    Since: @@ -1704,7 +1998,6 @@ required action requested by the calling application. void replyResult(optional ApplicationControlData[]? data) raises(WebAPIException); void replyFailure() raises(WebAPIException); - };

    Since: @@ -1830,7 +2123,6 @@ to perform the requested action. readonly attribute DOMString type; readonly attribute DOMString value; - };

    Since: @@ -1872,7 +2164,6 @@ to perform the requested action. readonly attribute DOMString key; readonly attribute DOMString value; - };

    Since: @@ -2215,6 +2506,129 @@ an application is installed, updated, or uninstalled. +

    +

    2.16. SystemEventData

    +
    + The SystemEventData interface defines what is retrieved from the event listener. +
    +
      [NoInterfaceObject] interface SystemEventData {
+    attribute DOMString value;
+    attribute DOMString type;
+  };
    +

    + Since: + 2.4 +

    +
    +

    +Platform modules will be able to broadcast system events in a future Tizen release. +

    +
    +
    +
    +

    2.17. EventCallback

    +
    + The EventCallback interface specifies a callback for getting notified when a specified event occurs. +
    +
      [Callback=FunctionOnly, NoInterfaceObject] interface EventCallback {
+    void onevent(EventInfo event, EventData data);
+  };
    +

    + Since: + 2.4 +

    +
    +

    Methods

    +
    +
    +onevent +
    +
    +
    + Called when the event occurs. +
    +
    void onevent(EventInfo event, EventData data);
+
    +

    + Since: + 2.4 +

    +
    +

    Parameters:

    +
      +
    • +event: + Broadcasted event which invokes this callback +
      • +
    • +data: + Broadcasted event data +
      • +
    +
    +
    +
    +
    +
    +
    +

    2.18. EventInfo

    +
    + The EventInfo dictionary identifies an event with information such as event name. If it is an user event, the broadasting application's identifier is also specified. +
    +
      dictionary EventInfo {
+    ApplicationId appId;
+
+    DOMString name;
+  };
    +

    + Since: + 2.4 +

    +
    +

    +System events do not require an application identifier to be specified. If one is specified, the event will be interpreted as an user event. +

    +
    +
    +

    Dictionary members

    +
    +
    ApplicationId appId
    +
    +
    + The unique identifier of the application which is broadcasting an event. +
    +
    +

    +An application can listen to events from other applications. However, it can only broadcast it's own events. Therefore, when broadcasting an event, this dictionary member must be the identifier of the application which is broadcasting the event. +

    +

    +System events do not require an application identifier to be specified. If one is specified, the event will be interpreted as an user event. +

    +
    +

    + Since: + 2.4 +

    +
    +
    DOMString name
    +
    +
    + Name which describes the event. +
    +
    +

    +Must only contain the ASCII characters "[A-Z][a-z][0-9]_" and may not begin with a digit. +Must be at least 1 byte in length and not exceed the maximum name length of 127 bytes. +

    +
    +

    + Since: + 2.4 +

    +
    +
    +
    +

    3. Full WebIDL

    module Application {
@@ -2223,6 +2637,12 @@ an application is installed, updated, or uninstalled.
 
   typedef DOMString ApplicationContextId;
 
+  typedef object UserEventData;
+
+  typedef (SystemEventData or UserEventData) EventData;
+
+  enum ApplicationControlLaunchMode { "SINGLE", "GROUP" };
+
   [NoInterfaceObject] interface ApplicationManagerObject {
     readonly attribute ApplicationManager application;
   };
@@ -2269,7 +2689,6 @@ an application is installed, updated, or uninstalled.
     long addAppInfoEventListener(ApplicationInformationEventCallback eventCallback) raises(WebAPIException);
 
     void removeAppInfoEventListener(long watchId) raises(WebAPIException);
-
   };
 
   [NoInterfaceObject] interface Application {
@@ -2283,8 +2702,15 @@ an application is installed, updated, or uninstalled.
     void hide() raises(WebAPIException);
 
     RequestedApplicationControl getRequestedAppControl() raises(WebAPIException);
-  };
 
+    long addEventListener(EventInfo event, EventCallback callback) raises(WebAPIException);
+
+    void removeEventListener(long watchId) raises(WebAPIException);
+
+    void broadcastEvent(EventInfo event, UserEventData data) raises(WebAPIException);
+
+    void broadcastTrustedEvent(EventInfo event, UserEventData data) raises(WebAPIException);
+  };
 
   [NoInterfaceObject] interface ApplicationInformation {
 
@@ -2312,7 +2738,6 @@ an application is installed, updated, or uninstalled.
     readonly attribute ApplicationContextId id;
 
     readonly attribute ApplicationId appId;
-
   };
 
   [Constructor(DOMString key, DOMString[] value)]
@@ -2321,12 +2746,11 @@ an application is installed, updated, or uninstalled.
     attribute DOMString key;
 
     attribute DOMString[] value;
-
   };
 
   [Constructor(DOMString operation, optional DOMString? uri,
                optional DOMString? mime, optional DOMString? category,
-               optional ApplicationControlData[]? data)]
+               optional ApplicationControlData[]? data, optional ApplicationControlLaunchMode? launchMode)]
   interface ApplicationControl {
 
     attribute DOMString operation;
@@ -2350,7 +2774,6 @@ an application is installed, updated, or uninstalled.
     void replyResult(optional ApplicationControlData[]? data) raises(WebAPIException);
 
     void replyFailure() raises(WebAPIException);
-
   };
 
   [NoInterfaceObject] interface ApplicationCertificate {
@@ -2358,7 +2781,6 @@ an application is installed, updated, or uninstalled.
     readonly attribute DOMString type;
 
     readonly attribute DOMString value;
-
   };
 
   [NoInterfaceObject] interface ApplicationMetaData {
@@ -2366,7 +2788,6 @@ an application is installed, updated, or uninstalled.
     readonly attribute DOMString key;
 
     readonly attribute DOMString value;
-
   };
 
 
@@ -2396,6 +2817,20 @@ an application is installed, updated, or uninstalled.
     void onuninstalled(ApplicationId id);
   };
 
+  [NoInterfaceObject] interface SystemEventData {
+    attribute DOMString value;
+    attribute DOMString type;
+  };
+
+  [Callback=FunctionOnly, NoInterfaceObject] interface EventCallback {
+    void onevent(EventInfo event, EventData data);
+  };
+
+  dictionary EventInfo {
+    ApplicationId appId;
+
+    DOMString name;
+  };
 };
    -- 2.7.4