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

27 July 2009

Authors

Toby Ealden <toby.ealden@gmail.com>

Abstract

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

1. Introduction
2. Type Definitions
- 2.1. Menu
3. Interfaces
- 3.1. WidgetActivateCallback
- 3.2. WidgetDeactivateCallback
- 3.3. WidgetKeyPressCallback
- 3.4. WidgetOrientationChangeCallback
- 3.5. WidgetMenuSelectCallback
- 3.6. UIManager
- 3.7. MenuItem

Summary of Methods

Interface	Method
WidgetActivateCallback	void onActivate()
WidgetDeactivateCallback	void onDeactivate()
WidgetKeyPressCallback	void onKeyPress(unsigned short keyCode)
WidgetOrientationChangeCallback	void onOrientationChange()
WidgetMenuSelectCallback	void onSelect()
UIManager	MenuItem 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)
MenuItem	void 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.
                leftMenu.setOnSelect(function() { bondi.ui.isActive = false; });
        }

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

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

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

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

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;

unsigned short navigationMode

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

3.7. `MenuItem`

MenuItem interface.

        interface MenuItem {

                readonly attribute unsigned long id;

                attribute DOMString text;

                void setOnSelect(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";

[readonly] Menu menuItems

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

setOnSelect

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

Signature

void setOnSelect(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.setOnSelect(function() { alert("hello!"); });

getMenuItemById

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

Signature

MenuItem getMenuItemById(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(unsigned long id, DOMString text, 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(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();

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

27 July 2009

Authors

Abstract

Table of Contents

Summary of Methods

1. Introduction

Code example

2. Type Definitions

2.1. Menu

3. Interfaces

3.1. WidgetActivateCallback

Methods

Signature

3.2. WidgetDeactivateCallback

Methods

Signature

3.3. WidgetKeyPressCallback

Methods

Signature

Parameters

3.4. WidgetOrientationChangeCallback

Methods

Signature

3.5. WidgetMenuSelectCallback

Methods

Signature

3.6. UIManager

Code example

Constants

Code example

Code example

Attributes

Exceptions

Code example

Exceptions

Code example

Code example

Exceptions

Code example

Exceptions

Code example

Methods

Signature

Parameters

Return value

Exceptions

Code example

Signature

Parameters

Exceptions

Code example

Signature

Parameters

Exceptions

Code example

Signature

Parameters

Exceptions

Signature

Parameters

Signature

Parameters

Signature

Signature

Parameters

Exceptions

Signature

Parameters

Signature

Parameters

3.7. MenuItem

Code example

Attributes

Code example

Code example

Code example

Methods

Signature

Parameters

2.1. `Menu`

3.1. `WidgetActivateCallback`

3.2. `WidgetDeactivateCallback`

3.3. `WidgetKeyPressCallback`

3.4. `WidgetOrientationChangeCallback`

3.5. `WidgetMenuSelectCallback`

3.6. `UIManager`

3.7. `MenuItem`