Bondi logo

The Bondi ui Module - Version 1.1

February 2010

Authors

© 2009-2010 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

To allow widgets to access functions that integrate with the widget runtime user interface.

Table of Contents

Summary of Methods

InterfaceMethod
WidgetActivateCallbackvoid onActivate()
WidgetDeactivateCallbackvoid onDeactivate()
WidgetKeyPressCallbackvoid onKeyPress(unsigned short keyCode)
WidgetOrientationChangeCallbackvoid onOrientationChange()
WidgetMenuSelectCallbackvoid onSelect()
UIManagerMenuItem getSoftKey(unsigned short id)
void setOnActivate(WidgetActivateCallback handler)
void setOnDeactivate(WidgetDeactivateCallback handler)
void setOnKeyPress(WidgetKeyPressCallback handler)
void beep(unsigned long duration, unsigned short frequency)
void startVibrate(unsigned long duration, unsigned short intensity)
void stopVibrate()
void setOnOrientationChange(WidgetOrientationChangeCallback handler)
void lightOn(unsigned long duration, unsigned short intensity, boolean fadeIn)
void lightOff(boolean fadeOut)
Preferences getPreferences()
MenuItemvoid setOnMenuSelect(WidgetMenuSelectCallback handler)
MenuItem getMenuItemById(unsigned long id)
MenuItem appendMenuItem(unsigned long id, DOMString text, WidgetMenuSelectCallback onSelect)
void removeMenuItem(unsigned long id)
void removeAllMenuItems()
Preferencesvoid setWallpaper(DOMString wallpaper)
void setCallRingtone(DOMString ringtone)
void setMessageRingtone(DOMString ringtone)
UIManagerObject

1. Introduction

Copyright 2010 OMTP Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This module provides a mechanism to interact with the end-user or configure the way in which the user visualizes or navigates Web applications. This includes features such as:

- navigation mechanisms

- soft-key and menu configuration

- effectors, vibration, sounds, screen brightness

- configuration of general appearance, e.g. portrait/landscape, full-screen

- behaviour configuration when moving from foreground to background.

Some ui operations are not supported outside of the widget runtime context. Examples are modifying the device soft key menus, and de-activating a widget. A DeviceAPIError exception is thrown with code NOT_SUPPORTED_ERROR when script attempts to perform an operation that is not supported.

1.2. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.

When the feature

is successfully requested, the interface UIManager is instantiated, and the resulting object appears in the global namespace as Bondi.ui.

http://bondi.omtp.org/api/1.1/ui

Allow access to the ui module

Device capabilities:

  • ui

1.3. Device capabilities

ui

Access to the user interaction capability

2. Type Definitions

2.1. Menu

Array of MenuItems. 

        typedef sequence<MenuItem> Menu;

3. Interfaces

3.1. WidgetActivateCallback

Callback interface to handle widget activation notifications. 

        [Callback=FunctionOnly, NoInterfaceObject] interface WidgetActivateCallback {
                void onActivate();
        };

Methods

onActivate

Method invoked when the widget is activated

Signature
void onActivate();

3.2. WidgetDeactivateCallback

Callback interface to handle widget deactivation notifications. 

        [Callback=FunctionOnly, NoInterfaceObject] interface WidgetDeactivateCallback {
                void onDeactivate();
        };

Methods

onDeactivate

Method invoked when the widget is deactivated

Signature
void onDeactivate();

3.3. WidgetKeyPressCallback

Callback interface to handle keypress notifications. 

        [Callback=FunctionOnly, NoInterfaceObject] interface WidgetKeyPressCallback {
                void onKeyPress(in unsigned short keyCode);
        };

Methods

onKeyPress

Method invoked when a key is pressed

Signature
void onKeyPress(in unsigned short keyCode);
Parameters
  • keyCode: Code of the pressed key

3.4. WidgetOrientationChangeCallback

Callback interface to handle display orientation change notifications. 

        [Callback=FunctionOnly, NoInterfaceObject] interface WidgetOrientationChangeCallback {
                void onOrientationChange();
        };

Methods

onOrientationChange

Method invoked when the display orientation is changed

Signature
void onOrientationChange();

3.5. WidgetMenuSelectCallback

Callback interface to handle menu selection notifications. 

        [Callback=FunctionOnly, NoInterfaceObject] interface WidgetMenuSelectCallback {
                void onSelect();
        };

Methods

onSelect

Method invoked when a menu option has been selected

Signature
void onSelect();

3.6. UIManager

UIManager interface. 

        interface UIManager {

                const unsigned short LEFT_SOFT_KEY = 0;

                const unsigned short RIGHT_SOFT_KEY = 1;

                readonly attribute Preferences preferences;

                MenuItem getSoftKey(in unsigned short id)
                        raises(DeviceAPIError);

                void setOnActivate(in WidgetActivateCallback handler)
                        raises(DeviceAPIError);

                void setOnDeactivate(in WidgetDeactivateCallback handler)
                        raises(DeviceAPIError);

                attribute boolean isActive
                        setraises(DeviceAPIError);

                const unsigned short NAVIGATION_CURSOR = 0;

                const unsigned short NAVIGATION_TABBED = 1;

                attribute unsigned short navigationMode
                        setraises(DeviceAPIError);

                void setOnKeyPress(in WidgetKeyPressCallback handler)
                        raises(DeviceAPIError);

                void beep(in unsigned long duration,in unsigned short frequency);

                const unsigned short INFINITE_DURATION = 0;

                void startVibrate(in unsigned long duration, in unsigned short intensity);

                void stopVibrate();

                readonly attribute boolean isRotationSupported;

                const unsigned short ORIENTATION_0 = 0;

                const unsigned short ORIENTATION_90 = 90;

                const unsigned short ORIENTATION_180 = 180;

                const unsigned short ORIENTATION_270 = 270;

                attribute unsigned short displayOrientation;

                void setOnOrientationChange(in WidgetOrientationChangeCallback handler)
                        raises(DeviceAPIError);

                attribute boolean softKeysVisible
                        setraises(DeviceAPIError);

                attribute boolean statusBarVisible
                        setraises(DeviceAPIError);

                void lightOn(in unsigned long duration, in unsigned short intensity, in boolean fadeIn);

                void lightOff(in boolean fadeOut);

                Preferences getPreferences();
        };

This is the top-level interface for the org.omtp.bondi.ui module. It allows widgets to access functions that integrate with the WRT user interface

Constants

unsigned short LEFT_SOFT_KEY

Constant for getSoftKey method.

This constant is used in conjunction with getSoftKey to specify which soft key to retrieve.

Code example
        // Get the left soft key menu item and set the text.
        var leftMenu = bondi.ui.getSoftKey(bondi.ui.LEFT_SOFT_KEY);
        leftMenu.text = "Close";
unsigned short RIGHT_SOFT_KEY

Constant for getSoftKey method.

This constant is used in conjunction with getSoftKey to specify which soft key to retrieve.

Code example
        // Get the right soft key menu item and set the text.
        var rightMenu = bondi.ui.getSoftKey(bondi.ui.RIGHT_SOFT_KEY);
        rightMenu.text = "Options";
unsigned short NAVIGATION_CURSOR

Constant for navigationMode property.

Indicates that the widget will use a pointer type mode of navigation.

unsigned short NAVIGATION_TABBED

Constant for navigationMode property.

Indicates that the widget wants to receive keyboard navigation.

unsigned short INFINITE_DURATION

Vibration constants.

unsigned short ORIENTATION_0

Constant for displayOrientation property.

unsigned short ORIENTATION_90

Constant for displayOrientation property.

unsigned short ORIENTATION_180

Constant for displayOrientation property.

unsigned short ORIENTATION_270

Constant for displayOrientation property.

Attributes

readonly Preferences preferences

Access to the ui Preferences.

This property is read-only.

boolean isActive

Property for access to the foreground status of the widget.

This property can be used to query the foreground status of the widget as well as to send the widget to the background or bring it to the foreground.

  • DeviceAPIError:

    NOT_SUPPORTED_ERROR if called from a web-page rather than a widget.

    • Code example
            // Send widget to background.
        bondi.ui.isActive = false;

    Property for access to the navigation mode.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if handler is invalid.

    NOT_SUPPORTED_ERROR if called from a web-page rather than a widget.

    • Code example
            // Set the navigation mode.
        bondi.ui.navigationMode = bondi.ui.NAVIGATION_TABBED;
    readonly boolean isRotationSupported

    Determines if the device supports changes in display orientation.

    This property is read-only.

    unsigned short displayOrientation

    Display orientation property.

    This method can be used to query the current display orientation, as well as to set a new display orientation.

    Code example
            // Set the display orientation to 90 degrees.
        bondi.ui.displayOrientation = bondi.ui.ORIENTATION_90;
    boolean softKeysVisible

    Property to set the soft key visibility.

    This property can be used to query as well as set the visibility of the device softkey menu bar.

    Note: if you hide the softKeys remember to add a means to close/deactivate your widget to the user interface.

  • DeviceAPIError:

    NOT_SUPPORTED_ERROR if called from a web-page rather than a widget.

    • Code example
            // Hide the softkeys.
        bondi.ui.softKeysVisible = false;
    boolean statusBarVisible

    Property to set the status bar visibility.

    This property can be used to query as well as set the visibility of the device status bar.

  • DeviceAPIError:

    NOT_SUPPORTED_ERROR if called from a web-page rather than a widget.

    • Code example
            // Go fullscreen.
        bondi.ui.softKeysVisible = false;
        bondi.ui.statusBarVisible = false;

    Methods

    getSoftKey

    Access the top-level menuitem object.

    Signature
    MenuItem getSoftKey(in unsigned short id);

    Used to access the top-level menuitem object of the device soft-key for the specified side.

    Parameters
    • id: - the identifier of the soft key to retrieve.
    Return value
    the MenuItem object representing the requested soft key, undefined if id not found.
    Exceptions
    • DeviceAPIError:

      NOT_SUPPORTED_ERROR if called from a web-page rather than a widget.

    Code example
            // Get the left soft-key.
        var leftMenu = bondi.ui.getSoftKey(bondi.ui.LEFT_SOFT_KEY);
        // Set the soft-key text.
        leftMenu.text = 'Close';
        // Set a handler so that when the soft-key is pressed the widget is sent to the background.
        leftMenu.setOnMenuSelect(function() { bondi.ui.isActive = false; });
    setOnActivate

    Set handler for widget activation notification.

    Signature
    void setOnActivate(in WidgetActivateCallback handler);

    Notifies when the widget is activated and brought to the foreground.

    Parameters
    • handler: - callback that receives notification.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if handler is invalid.

      NOT_SUPPORTED_ERROR if called from a web-page rather than a widget.

    Code example
            // Request to be notified when the widget is activated.
        function goToForeground()
        {
                // Widget is now in the foreground.
                // Start processor intensive routine...
        }
        bondi.ui.setOnActivate(goToForeground);
    setOnDeactivate

    Set handler for widget de-activation notification.

    Signature
    void setOnDeactivate(in WidgetDeactivateCallback handler);

    Notifies when the widget is de-activated and sent to the background.

    Parameters
    • handler: - callback that receives notification.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if handler is invalid.

      NOT_SUPPORTED_ERROR if called from a web-page rather than a widget.

    Code example
            // Request to be notified when the widget is de-activated.
        function goToBackground()
        {
                // Widget is now in the background.
                // kill processor intensive routine...
        }
        bondi.ui.setOnDeactivate(goToBackground);
    setOnKeyPress

    Sets the handler to receive key input.

    Signature
    void setOnKeyPress(in WidgetKeyPressCallback handler);

    This handler is called if the navigation mode is set to NAVIGATION_TABBED.

    Parameters
    • handler: - the callback to receive key codes.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if handler is invalid.

      NOT_SUPPORTED_ERROR if called from a web-page rather than a widget.

    beep

    Produce a beep from the device.

    Signature
    void beep(in unsigned long duration, in unsigned short frequency);

    Note: duration and frequency parameters are ignored in this implementation.

    Parameters
    • duration: value in milliseconds.
    • frequency: value in Hz
    startVibrate

    Switch on the device vibration for the specified period and intensity.

    Signature
    void startVibrate(in unsigned long duration, in unsigned short intensity);

    Note: intensity parameter is ignored in this implementation.

    Parameters
    • duration: value in milliseconds.
    • intensity: value as a percentage (0-100).
    stopVibrate

    Switches off the device vibration.

    Signature
    void stopVibrate();
    setOnOrientationChange

    Sets a handler to receive notification when screen orientation changes.

    Signature
    void setOnOrientationChange(in WidgetOrientationChangeCallback handler);
    Parameters
    • handler: - callback to use when orientation changes.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if handler is invalid.

    lightOn

    Switches the backlight on for the given duration.

    Signature
    void lightOn(in unsigned long duration, in unsigned short intensity, in boolean fadeIn);
    Parameters
    • duration: - the period in milliseconds.
    • intensity: - the intensity (0-100).
    • fadeIn: - flag indicating if the light should be faded in.
    lightOff

    Switches the backlight off.

    Signature
    void lightOff(in boolean fadeOut);
    Parameters
    • fadeOut: - flag indicating if the light should be faded out.
    getPreferences

    Gets a reference to the the preferences object

    Signature
    Preferences getPreferences();

    3.7. MenuItem

    MenuItem interface. 

            interface MenuItem {

                readonly attribute unsigned long id;

                attribute DOMString text;

                void setOnMenuSelect(in WidgetMenuSelectCallback handler)
                        raises(DeviceAPIError);

                readonly attribute Menu menuItems;

                MenuItem getMenuItemById(in unsigned long id);

                MenuItem appendMenuItem(in unsigned long id, in DOMString text, in WidgetMenuSelectCallback onSelect)
                        raises(DeviceAPIError);

                void removeMenuItem(in unsigned long id)
                        raises(DeviceAPIError);

                void removeAllMenuItems();
        };

    This interface provides the ability to interact with and modify the widget runtime soft-key menus. MenuItem has access to the collection of child menu items via menuItems array.

    Code example
            var leftMenu = bondi.ui.getSoftKey(bondi.ui.LEFT_SOFT_KEY);
        leftMenu.text = "refresh";

    Attributes

    readonly unsigned long id

    Get the id of this menu item.

    This property is read-only.

    Code example
            var id = menuItem.id;
    DOMString text

    Gets/Sets the text of the menu item.

    Code example
            var menuItem = bondi.ui.getSoftKey(bondi.ui.RIGHT_SOFT_KEY);
        var menuItem.text = "Options";

    Gets the child items of this menu item.

    Code example
            var menuItem = bondi.ui.getSoftKey(bondi.ui.RIGHT_SOFT_KEY);
        var subMenu = menuItem.menuItems;

    Methods

    setOnMenuSelect

    Sets the handler to be called when the menu item is selected.

    Signature
    void setOnMenuSelect(in WidgetMenuSelectCallback handler);
    Parameters
    • handler: the callback handler.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if handler is invalid.

    Code example
            var menuItem = bondi.ui.getSoftKey(bondi.ui.RIGHT_SOFT_KEY);
        var menuItem.text = "Say hello";
        menuItem.setOnMenuSelect(function() { alert("hello!"); });
    getMenuItemById

    Retrieves a menu item from the child nodes (menuItems) using the id.

    Signature
    MenuItem getMenuItemById(in unsigned long id);
    Parameters
    • id: - the id of the menu item to retrieve.
    Return value
    the menu item if found, undefined otherwise.
    appendMenuItem

    Adds a child menu item to this menu item.

    Signature
    MenuItem appendMenuItem(in unsigned long id, in DOMString text, in WidgetMenuSelectCallback onSelect);
    Parameters
    • id: - the id of the new item. If this is 0 then a unique id will be automatically assigned.
    • text: - the text value of the new item.
    • onSelect: - the callback handler for the new item.
    Return value
    the newly created menu item.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if any arguments are invalid.

    Code example
            var menuItem = bondi.ui.getSoftKey(bondi.ui.RIGHT_SOFT_KEY);
        var menuItem.text = "Options";
        var colourMenu = menuItem.appendMenuItem(0,"Change colour",onColourChange);
    removeMenuItem

    Removes the menu item with the given id from the child nodes (menuItems).

    Signature
    void removeMenuItem(in unsigned long id);
    Parameters
    • id: - the id of the menu item to remove.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if no item exists with given id.

    removeAllMenuItems

    Removes all child menu items from this menu item.

    Signature
    void removeAllMenuItems();

    3.8. Preferences

    Preferences interface. 

            interface Preferences {

                attribute unsigned long callRingtoneVolume;

                attribute unsigned long messageRingtoneVolume;

                attribute boolean isVibrationActive;

                void setWallpaper(in DOMString wallpaper)
                        raises(DeviceAPIError);

                void setCallRingtone(in DOMString ringtone)
                        raises(DeviceAPIError);

                void setMessageRingtone(in DOMString ringtone)
                        raises(DeviceAPIError);

        };

    It allows widgets to configure the settings linked to the device User Experience such as ringtones, wallpapers, volume...

    Attributes

    unsigned long callRingtoneVolume

    Incoming call ringtone volume

    The range of possible values is from 0 (no sound) to 100 (maximum value)

    Code example
       bondi.ui.preferences.callRingtoneVolume = 100;
    unsigned long messageRingtoneVolume

    Incoming message ringtone volume

    The range of possible values is from 0 (no sound) to 100 (maximum value)

    Code example
       bondi.ui.preferences.messageRingtoneVolume = 100;
    boolean isVibrationActive

    Incoming event vibration setting

    If false the device will not vibrate upon an incoming event, if true the device will vibrate.

    Code example
       if (bondi.ui.preferences.isVibrationActive == true)
      alert("Vibration is set to active);
   else
      alert("The device won't vibrate);

    Methods

    setWallpaper

    Set idle screen wallpaper.

    Signature
    void setWallpaper(in DOMString wallpaper);

    Configures the idle screen wallpaper with the image file passed as input parameter. In case the file format is not supported or the file is invalid an INVALID_ARGUMENT_ERROR will be raised.

    Parameters
    • wallpaper: - the fully qualified file path to the file to be used as wallpaper
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if the wallpaper is invalid or the format is not supported

    Code example
            var myImage = "/pictures/myImage.jpg");
  bondi.ui.preferences.setWallpaper(myImage);
    setCallRingtone

    Set default ringtone for incoming calls.

    Signature
    void setCallRingtone(in DOMString ringtone);

    Configures the default ringtone for incoming calls with the sound file passed as input parameter. In case the file format is not supported or the file is invalid and INVALID_ARGUMENT_ERROR will be raised.

    Parameters
    • ringtone: - the fully qualified file path to the file to be used as ringtone
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if the ringtone is invalid or the format is not supported

    Code example
            var mySound = "/sounds/ring.wav");
  bondi.ui.preferences.setCallRingtone(mySound);
    setMessageRingtone

    Set default ringtone for incoming messages.

    Signature
    void setMessageRingtone(in DOMString ringtone);

    Configures the default ringtone for incoming messages with the sound file passed as input parameter. In case the file format is not supported or the file is invalid and INVALID_ARGUMENT_ERROR will be raised.

    Parameters
    • ringtone: - the fully qualified file path to the file to be used as ringtone
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if the ringtone is invalid or the format is not supported

    Code example
            var mySound = "/sounds/message.wav");
  bondi.ui.preferences.setMessageRingtone(mySound);

    3.9. UIManagerObject

    Specifies what is instantiated at feature request 

            interface UIManagerObject {
                readonly attribute UIManager ui;
        };
            Bondi implements UIManagerObject;