Tiny Mobile Widgets - Board channel

An application can use different types of Messages for different events/features. The scene that shall receive the message set a key as url parameter of Message Node. In manager, the key is 'Board'. So, all scene that want to communicate with [Manager|ULManager] (matters of title, softkeys, popups, menu or loading scene) use the ['Board' channel/url | ULMessageBoard].

This chapter describe "Board" channel and this message.

Send message

To send message on "Board" channel, we use the sendMessage(...) method of Browser class.
Example:

//Initialize widget title and soft key
Browser.sendMessage ('Board', 'INIT', 'Mobile Widgets', 'Menu', 'Quit');

'INIT' message

'INIT' message is use to initialize title and soft keys.

Browser.sendMessage ('Board', 'INIT', title, lsk, rsk, iconOption);

title: Widget title
lsk: Left soft key label
rsk: Right soft key label
iconOption: icon display and position option, authorized values:
- 0: no icon, title is left justified
- 1: icon is displayed at left, title is left justified
- -1: icon is displayed at right, title is right justified

Example:

Browser.sendMessage ('Board', 'INIT', 'My Title', 'Option', 'Close', 1);

'LOAD' message

'LOAD' message is use to load another VRML page/file.

Note:
Namespace is not changed.
Use 'LOAD_WIDGET' to change the Namespace.

Browser.sendMessage ('Board', 'LOAD', file);

file: File of the new VRML page ('m4m' file).

Example:

Browser.sendMessage ('Board', 'LOAD', 'cache://catalog.m4m');

'LOAD_WIDGET' message

'LOAD_WIDGET' message is use to load another widget (load widget page and change the Namespace).

Browser.sendMessage ('Board', 'LOAD_WIDGET', file);

file: File of the new VRML page ('m4m' file).

Example:

Browser.sendMessage ('Board', 'LOAD_WIDGET', 'cache://test.m4m');

'MENU' message

'MENU' message is use to display a menu.

Note:
Catch the 'ANSWER' message to read user selection.

Browser.sendMessage ('Board', 'MENU', title, lsk, rsk, items..., '');

title: Widget title
lsk: Left soft key label
rsk: Right soft key label
items...: Menu items
'': Empty string to flag the end of the items list.

Example:

Browser.sendMessage ('Board', 'MENU', 'My Menu', 'Ok', 'Cancel', 'Item1', 'Item2', 'Item3', '');

See Menu tutorial.

'POPUP' message

'POPUP' message is used to display a popup frame.

Note:
Catch the 'ANSWER' message to read the popup result.

Browser.sendMessage ('Board', 'POPUP', title, msg, lsk, rsk, type);

title: Widget title
msg: Popup message
lsk: Left soft key label
rsk: Right soft key label
type: Define the popup type
'error': Error popup (display error icon)
'warning': Warning popup (display warning icon)
Other/nothing: Default popup

Example:

Browser.sendMessage ('Board', 'POPUP', 'Quit', 'Quit the widget?', 'Yes', 'No');

See Popup tutorial.

'POPUP_AUTO_HIDE' message

'POPUP_AUTO_HIDE' message is used to hide the popup frame.

Browser.sendMessage ('Board', 'POPUP_AUTO_HIDE');

See Popup tutorial.

'PROGRESS' message

'PROGRESS' message is used to display and update a progress bar into current popup frame.

Note:
Progress require an opened popup.

Browser.sendMessage ('Board', 'PROGRESS', progress);

progress: Progress value (between 0 and 100).

Example:

Browser.sendMessage ('Board', 'PROGRESS', 10);

'RESET' message

'RESET' message is used to quit widget. Load carousel page and quit the widget Namespace.

Browser.sendMessage ('Board', 'RESET');

'CATALOG_UPDATE' message

'CATALOG_UPDATE' message is used to update the catalog.

Note:
Don't use this message. This message is only use by Catalog and Manager.

Browser.sendMessage ('Board', 'CATALOG_UPDATE', param);

param: Parameter used by Catalog and Manager.

Example:

Browser.sendMessage ('Board', 'CATALOG_UPDATE', 'REFRESH');

'HIDE_BARS' message

Message is sent by Manager when widget developper want to hide title and softkeys bar (canvas space optimization).
message.set_data[0]: 'HIDE_BARS'

You should hide bars only when it has sense: on small size resolution. You should always think of an action that will display the bars again and communicate this action to the user before hiding the bar (ex: "Press Fire button to show bars") so that user will never be blocked.

'SHOW_BARS' message

Message is sent by Manager when widget developper want to show title and softkeys bar once they were hidden.
message.set_data[0]: 'SHOW_BARS'

SHOW_BARS shall be used only associated with the HIDE_BARS message. By default, bars are always displayed.

'SHOW_WAIT' message (available from SDK V2.3.0)

Message is sent by Manager when widget developper want to show a loading hourglass.
message.set_data[0]: 'SHOW_WAIT'

You should hide the loading hourglass (by message HIDE_WAIT) when the data you wanted to load is loaded. This mechanism is complementary to the Loader prototype. This mechanism is used to display an unknown time loading whereas Loader is often used fo known time loading.

'HIDE_WAIT' message (available from SDK V2.3.0)

Message is sent by Manager when widget developper want to stop the showing of a loading hourglass.
message.set_data[0]: 'HIDE_WAIT'

HIDE_WAIT shall be used only associated with the SHOW_WAIT message.

'THEME' message (available from SDK V2.3.0)

Message is sent by Manager when widget developper wants to define some customization colors. Available color customization are background color, softkeys and title bar, background color of popup, focus color (list selection, text title colors, progressbar color). Manager always sets the current theme color values in 4 cookies: 'theme.bg', 'theme.bar', theme.alert' and 'theme.focus'.
Browser.sendMessage ('Board', 'THEME', bgColor, barsColor, popupColor, focusColor);

Colors value are set in hexadecimal. Color of the scrollbar(grey), color of other texts (black in scrollable text content and in menu items, white otherwise), and color of the menu background (white) are not customizable yet.

Default values are: 'FFFFFF' for background color, '3D3D3D' for title and softkeys bars color, '666666' for alert background color and 'FF6E00' for focus color. Those values are called "application theme values" and can change if the application is rebranded for partnership. When a widget defines a specific THEME, it will crush the application theme.

User can fall back to initial theme configuration by calling Browser.sendMessage ('Board', 'THEME'); It will reset theme to the application theme. Reseting theme to application's one is automatically done by manager when the widget is closed.

Example:

Browser.sendMessage ('Board', 'THEME', 'EEEEEE', '7E587E', '555A9A', '28903A');

'SOCIAL' message (available from SDK V3.0.0)

'SOCIAL' message is use to load the 'social' Widget to allow Widgets to share content (text and URLs) to the users socials networks. For now, only Facebook and Twitter are available.

Note:
Catch the 'SOCIAL' message in your Widget to be aware of the end of the publication process.

Browser.sendMessage ('Board', 'SOCIAL', socialMsg, socialUrl);

Receive message

To read messages on "Board" channel, we use a Message.

1. Define the Message to read message.

# Node to read messages on "Board" channel
DEF MESSAGE Message { url "Board" }

2. Write a JavaScript function to read and process messages.

# Script
DEF SCRIPT Script {
  # Define 'data changed' event
  eventIn MFString data_changed
  url "
    //Function to process 'data changed' event
    function data_changed (val, time) {
      //Test message
      if (data_changed[0] == 'RSK') {
        // Right softkey event
        Browser.print('Right softkey pressed');
      }
    }
  "
}

3. Link "Board" channel and data_changed(...) function.

# Link "Board" channel and JavaScript function
ROUTE MESSAGE.data_changed TO SCRIPT.data_changed

'ANSWER' message

Message is sent by Manager.
This message is used to read menu or popup result.

Popup result:
message.set_data[0]: 'ANSWER'
message.set_data[1]:
'LSK': left softkey is pressed
'RSK': right softkey is pressed
Menu result:
message.set_data[0]: 'ANSWER'
message.set_data[1]: Index of the selected item (start by 0) or 'RSK' (on right softkey)

See Menu and Popup tutorials.

'LSK' message

Message is sent by Manager when left softkey is pressed.
message.set_data[0]: 'LSK'

See softkeys tutorial.

'RSK' message

Message is sent by Manager when right softkey is pressed.
message.set_data[0]: 'RSK'

See softkeys tutorial.