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 os string. For example: [{id:'yes',title:'Ok to Delete'},{id:'no',title:'No'}]. Using hash this way: [{id:'yes',title:'Ok to Delete'},{id:'no',title:'No'}] Using string example: ['Yes', 'No']. Note: in case of buttons has been specified using strings an id and a title of each button will have same value.

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

Parameters

  • title : STRING

    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

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.