Notification

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. :::ruby 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.

JavaScript Ruby Android Windows Mobile, Windows CE, Windows Embedded Windows Desktop

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.

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. On Windows Mobile/CE, Windows and RhoSimulators only Status window, displayed by showStatus can be hide.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Desktop

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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

path : STRING

The full absolute 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)

removeScheduler

()

JavaScript Ruby Android iphone, ipod touch, ipad

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Notification.removeScheduler()
- Ruby: Rho::Notification.removeScheduler()

setScheduler

(HASH propertyMap)

JavaScript Ruby Android iphone, ipod touch, ipad

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.
start : HASH

Time to start h:m:s.

hour : Integer

Hour in hours
minute : Integer

Minute in minutes
seconds : Integer

Seconds in seconds

interval : Integer Default:

The time interval in seconds.
repeats : Boolean Default: true

Repeat or not.

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Notification.setScheduler(HASH propertyMap)
- Ruby: Rho::Notification.setScheduler(HASH propertyMap)

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. All custom icons' paths must be absolute paths to the icon file. Icon is not supported on iOS devices.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Desktop

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, Windows and RhoSimulators only predefined icons are supported.
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 "::" for all "." when referencing constants) String:dialog

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

Constant: Rho::Notification.TYPE_NOTIFICATION (For Ruby use "::" for all "." when referencing constants) 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 "::" for all "." when referencing constants) 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 "::" for all "." when referencing constants)
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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded Windows Desktop

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, Windows and RhoSimulators Windows Close icon used to hide the 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.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

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.

Ruby

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

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.

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.

Notification

Methods - Class

Enabling the API

JavaScript Usage

Ruby Usage

Methods

Examples

Remarks