Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Notification

Methods 6  
Examples 2
Remarks 2

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

This API is part of the coreapi extension that is included automatically.

extensions: ["coreapi"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

beep(HASH propertyMap)

If the device is equipped with a beeper then a beep will be emitted. Not supported on iOS devices.

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 dependant.

    • duration : Integer Default: 1000

      The duration of the beep, in milliseconds.

Synchronous Return:

  • Void

Method Access:

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

hidePopup()

Closes the current popup window.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Javascript: Rho.Notification.hidePopup()
    • Ruby: Rho::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 path to the file, ending in the file name and extension.

  • 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”.

Synchronous Return:

  • Void

Method Access:

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

showPopup(HASH propertyMap, CallBackHandler callback)

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. Icon is not supported on iOS devices.

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.

      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:

      buttonHash = [{id:'yes',title:'Ok to Delete'},{id:'no',title:'No'}];
buttonString = ['Yes', 'No'];

      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:

      typeToast = [Rho.Notification.TYPE_DIALOG, Rho.Notification.TYPE_TOAST];

      Possible Values :

      Constant: Rho::Notification.TYPE_DIALOG (For Ruby use "::" instead of ".")
      String:dialog

      Show common dialog window with buttons visible if application is active.

      Constant: Rho::Notification.TYPE_NOTIFICATION (For Ruby use "::" instead of ".")
      String:notification

      Show message in Android notification bar if application is at background. Touch the message opens the application.

      Constant: Rho::Notification.TYPE_NOTIFICATION_DIALOG (For Ruby use "::" instead of ".")
      String:notificationDialog

      This is the same as TYPE_DIALOG + TYPE_NOTIFICATION.

      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: Rho::Notification.TYPE_TOAST (For Ruby use "::" instead of ".")
      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 Optional

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.

Synchronous Return:

  • Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Javascript: Rho.Notification.showPopup(HASH propertyMap, CallBackHandler callback)
    • Ruby: Rho::Notification.showPopup(HASH propertyMap, CallBackHandler callback)

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.

Synchronous Return:

  • Void

Method Access:

  • Class Method: This method can only be accessed via the API class object.
    • Javascript: Rho.Notification.showStatus(STRING title, STRING status_text, STRING hide_button_label)
    • Ruby: Rho::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. iOS devices have fixed system vibration time. It could not be changed. Android and Windows devices have default vibration time 1000 ms.

Synchronous Return:

  • Void

Method Access:

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

Examples

Sound the device beeper

Not every device is equipped with a hardware beeper but if present this code snippet will cause the beeper to sound.

# ---------------
# controller.rb  
# ---------------
         
def sound_beeper
  # Obtain list of available leds on the device. 
  beeperProps = Hash.new
  beeperProps['frequency'] = 3000;
  beeperProps['volume'] = 2;
  beeperProps['duration'] = 1500;
  Rho::Notification.beep(beeperProps)
end
Show an alert

This example shows how to show an alert in JavaScript.

function show_alert()
{
    //creates a popup with a message and two buttons
    Rho.Notification.showPopup({
        title:'My Popup',
        message:'Do you really want to delete this record',
        buttons:[
            {id:'yes',title:'Ok to Delete'},
            {id:'no',title:'No'}]
        },
            function(e){
                if(e.button_id == "yes")
                {
                    // go ahead and delete the record
                }
            }
    );
}

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.