Bondi logo

The Bondi User Interaction Module: bondi.ui - Version 1.0

28 May 2009

Authors

© 2009 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)
MenuItemvoid setOnSelect(WidgetMenuSelectCallback handler)
MenuItem getMenuItemById(unsigned long id)
MenuItem appendMenuItem(unsigned long id, DOMString text, WidgetMenuSelectCallback onSelect)
void removeMenuItem(unsigned long id)
void removeAllMenuItems()

1. Introduction

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.


No permissions are required for this package.

Code example
        function errorCB(err) {
                alert("BONDI ui API couldn't be requested: " + err.message);
        }

        function successCB() {
                // Create a single menu on the left soft key to close the widget.
                var leftMenu = bondi.ui.getSoftKey(bondi.ui.LEFT_SOFT_KEY);
                var d = leftMenu.removeAllMenuItems();
                leftMenu.text = "Close";
                // When the menu is selected, de-activate the widget.
                d = leftMenu.setOnSelect(function() { bondi.ui.isActive = false; });
        }

        bondi.requestFeature(successCB, errorCB, "ui");

2. Type Definitions

3. Interfaces

3.1. WidgetActivateCallback

Callback interface to handle widget activation notifications. 

        [Callback] interface WidgetActivateCallback {
                void onActivate();
        };

3.2. WidgetDeactivateCallback

Callback interface to handle widget deactivation notifications. 

        [Callback] interface WidgetDeactivateCallback {
                void onDeactivate();
        };

3.3. WidgetKeyPressCallback

Callback interface to handle keypress notifications. 

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

3.4. WidgetOrientationChangeCallback

Callback interface to handle display orientation change notifications. 

        [Callback] interface WidgetOrientationChangeCallback {
                void onOrientationChange();
        };

3.5. WidgetMenuSelectCallback

Callback interface to handle menu selection notifications. 

        [Callback] interface WidgetMenuSelectCallback {
                void onSelect();
        };

3.6. UIManager

UIManager interface. 

        interface UIManager {

                const unsigned short LEFT_SOFT_KEY = 0;

                const unsigned short RIGHT_SOFT_KEY = 1;

                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);
        };

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

Code example
        function errorCB(err) {
                alert("BONDI ui API couldn't be requested: " + err.message);
        }

        function successCB() {
                // Create a single menu on the left soft key to close the widget.
                var leftMenu = bondi.ui.getSoftKey(bondi.ui.LEFT_SOFT_KEY);
                var d = leftMenu.removeAllMenuItems();
                leftMenu.text = "Close";
                // When the menu is selected, de-activate the widget.
                d = leftMenu.setOnSelect(function() { bondi.ui.isActive = false; });
        }

        bondi.requestFeature(successCB, errorCB, "ui");

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";

Constant for navigationMode property.

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

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

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.

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

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

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

Exceptions
  • 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(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.setOnSelect(function{ bondi.ui.isActive = false; });
setOnActivate

Set handler for widget activation notification.

Signature
void setOnActivate(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.
        bondi.ui.setOnActivate(goToForeground);
        function goToForeground()
        {
                // Widget is now in the foreground.
                startProcessorIntensiveTimer();
        }
setOnDeactivate

Set handler for widget de-activation notification.

Signature
void setOnDeactivate(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 weidget is de-activated.
        bondi.ui.setOnDeactivate(goToBackground);
        function goToBackground()
        {
                // Widget is now in the background.
                killProcessorIntensiveTimer();
        }
setOnKeyPress

Sets the handler to receive key input.

Signature
void setOnKeyPress(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(unsigned long duration, 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(unsigned long duration, 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(WidgetOrientationChangeCallback handler);

Note: not implemented in v1.0.

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(unsigned long duration, unsigned short intensity, boolean fadeIn);

Note: intensity and fadeIn parameters are ignored in this implementation.

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(boolean fadeOut);

Note: fadeOut parameter ignored in this implementation.

Parameters
  • fadeOut: - flag indicating if the light should be faded out.