Notification

Enterprise Browser 5.0

Overview

The Notification API allows you to provide feedback to the user, either auditory, tactile or visual. Use this API to give a visual popup window, sound the device beeper or illuminate the device LEDs (hardware permitting).

Enabling the API

There are two methods of enabling the Notification API:

  • Include all ebapi modules
  • Include only the required API modules

For either of these methods, you'll need to include files from the '/Enterprise Browser/JavaScript Files/Enterprise Browser' directory on the computer that you installed the Enterprise Browser.

Include all JS API modules

To include all JS APIs, copy the ebapi-modules.js file to a location accessible by the app's files and include a reference to the JavaScript file in the app's HTML. For instance, to include the modules file in the app's index.html, copy the file to the same directory as that index.html and add the following line to the HTML's HEAD section:


<script type="text/javascript" charset="utf-8" src="ebapi-modules.js"></script>

Note: that the pathing for this file is relative to the current page.

This will define the EB class within the page. Any page you need to use the modules will need to have the .js file included in this fashion.

Include only the required modules

To include single APIs, you must first include the 'ebapi.js' in your HTML as well as the API file you want to use. For instance, to use the Notification API, I would add the following code to my HTML file(s), assuming the API files have been copied to the same directory as the HTML.


<script type="text/javascript" charset="utf-8" src="ebapi.js"></script>
<script type="text/javascript" charset="utf-8" src="eb.notification.js"></script>

The ebapi.js file is necessary for all single API inclusions.

Methods

beep(HASH propertyMap)

If the device is equipped with a beeper then a beep will be emitted.

Parameters

  • propertyMap : HASH

    The properties associated with the beep.

    • frequency : Integer Default: 2000

      The frequency of the beep, in Hz.

    • volume : Integer Default: 1

      A number between 0 and 3. 0 represents minimum volume and 3 is maximum volume, the decibels each volume level represents is device dependent.

    • duration : Integer Default: 1000

      The duration of the beep, in milliseconds.

  • callback : CallBackHandler

Returns

Synchronous Return:

  • Void

Platforms

  • Android
  • Windows Mobile

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • EB.Notification.beep(HASH propertyMap)

hidePopup()

Closes the current popup window. On Windows Mobile/CE only Status window, displayed by showStatus can be hide.

Parameters

  • callback : CallBackHandler

Returns

Synchronous Return:

  • Void

Platforms

  • Android
  • Windows Mobile
  • Windows CE

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • EB.Notification.hidePopup()

playFile(STRING path, STRING media_type)

Play an audio file if that media type is supported by the device.

Parameters

  • path : STRING

    The full absolute path to the file, ending in the file name and extension. The file that you are playing must be located on the device or the file may not play correctly.

  • media_type : STRING Optional Default:

    Media type can be specified explicitly, or can be recognized from the file extension. The known file extensions are ".mp3" - "audio/mpeg" and ".wav" - "audio/x-wav".

  • callback : CallBackHandler

Returns

Synchronous Return:

  • Void

Platforms

  • Android
  • Windows Mobile

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • EB.Notification.playFile(STRING path, STRING media_type)

showPopup(HASH propertyMap)

Bring the application up front and show a message in a popup window. The message can be passed as a string or a hash. The popup window closes after you click on one of the buttons in the 'button' array. All custom icons' paths must be absolute paths to the icon file.

Parameters

  • propertyMap : HASH

    The properties associated with the popup.

    • message : String Default:

      Text displayed in the popup window.

    • title : String Default:

      Title of the popup window.

    • icon : String Default:

      Icon to be displayed in the popup window. path to an image, or :alert for ! icon, :question for ? icon, :info for information icon. On Windows Mobile/CE only predefined icons are supported. The file that you are playing must be located on the device or the icon may not display properly. Platforms: Android

    • buttons : Array Default:

      Array of buttons. Specify each button either by hash with :id and :title keys or string.When using strings, the 'id' and 'title' will have the same value. For example: :::javascript buttonHash = [{id:'yes',title:'Ok to Delete'},{id:'no',title:'No'}]; buttonString = ['Yes', 'No']; >NOTE: For Android, if TYPE_NOTIFICATION_DIALOG is used, every button in the notification uses an icon. By default a star icon is used. If the button id is 'accept' then the system accept icon is used. If the button id is 'cancel' then the system cancel icon is used.

    • types : Array

      List which notification kinds will be shown. Several types may be listed at same time. 'TYPE_NOTIFICATION' and 'TYPE_NOTIFICATION_DIALOG' take no effect if application is in the foreground. By default '[Rho.Notification.TYPE_DIALOG, Rho.Notification.TYPE_NOTIFICATION]' is used. Example: :::javascript typeToast = [Rho.Notification.TYPE_DIALOG, Rho.Notification.TYPE_TOAST];

      Possible Values :

      Constant: EB.Notification.TYPE_DIALOG
      String:dialog
      Show common dialog window with buttons visible if application is active.
      Constant: EB.Notification.TYPE_NOTIFICATION
      String:notification
      Show message in Android notification bar if application is at background. Touch the message opens the application.
      Constant: EB.Notification.TYPE_NOTIFICATION_DIALOG
      String:notificationDialog
      This is the same as 'TYPE_DIALOG' + 'TYPE_NOTIFICATION'. >NOTE: In Android 4.1 and above, buttons are also added to the notification message so the user can interact with the application without application activation (dialog window is not shown if user pressed button in notification). Buttons are not always displayed in the notification area - this depends on screen size and layout and system decides whether to show buttons. You need to drag notification to make buttons appear.
      Constant: EB.Notification.TYPE_TOAST
      String:toast
      Show toast window with message at foreground for a short time. The toast is visible nevertheless the application is at background or foreground but is not shown same time with any foreground pop-up.
  • callback : CallBackHandler

Callback

Async Callback Returning Parameters: HASH

    • button_id : STRING

      ID assigned to the button when showing the popup.

    • button_title : STRING

      Button text.

    • button_index : STRING

      The index in the 'buttons' array.

Returns

Synchronous Return:

  • Void

Platforms

  • Android
  • Windows Mobile
  • Windows CE

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • EB.Notification.showPopup(HASH propertyMap)

showStatus(STRING title, STRING status_text, STRING hide_button_label)

Display a window containing a status message. The window closes after the user clicks on its hide button. Note: Android will show a toast message for a short time in addition to a dialog window.

Parameters

  • title : STRING Optional

    The title on the status message popup window.

  • status_text : STRING

    The status message displayed in the popup status window.

  • hide_button_label : STRING

    The label text for the hide button in the popup status window. On Windows Mobile/CE Close icon used to hide the status window.

  • callback : CallBackHandler

Returns

Synchronous Return:

  • Void

Platforms

  • Android
  • Windows Mobile
  • Windows CE

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • EB.Notification.showStatus(STRING title, STRING status_text, STRING hide_button_label)

vibrate(Integer duration)

Vibrate the device's pager hardware. Need 'vibrate' capability set at build.yml for Android.

Parameters

  • duration : Integer Optional Default: 1000

    The duration of the vibration, in milliseconds. Note you may also need to add the vibration capability to your build.yml file. See remarks for maximum duration. Android and Windows devices have default vibration time 1000 ms.

  • callback : CallBackHandler

Returns

Synchronous Return:

  • Void

Platforms

  • Android
  • Windows Mobile

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • EB.Notification.vibrate(Integer duration)

Remarks

Maximum vibrate duration

On Android, the maximum duration for vibrate is 15 seconds (15000ms).

Spuriously reported hardware

Some Windows Mobile or CE devices may report hardware which is not present on the device such as a pager or LEDs. This is a limitation of the underlying driver layer reporting spurious results to the application, though all real hardware will be controllable.

Maximum Button text size

It is recommend to use maximum 15 Character for the button text in pop up , above to this limit it behave as per OS Behavior.