Floating Mode For Samsung H1/M1 Widgets

A JIL/W3C mobile widget can run in one of the 3 modes: full screen, floating, docked. All runtimes (Samsung, S60, Android) support the full screen mode, but the floating mode is supported only by Samsung (H1/M1) and docked mode is supported only by S60.

The floating mode is that state where the widget runs on the home screen, in a square container, the size of 4 widget/application icons. Multiple widgets can run in floating mode at the same time.

In order to enable floating mode for a widget, the following setting is required in the config.xml file:

• Opera/W3C config format: <widget … floatable=”yes” … >
• JIL 1.2 format: <widget … viewmodes=”fullscreen, floating” … >

On Samsung H1/M1, the runtime will start the widget in floating mode (if this mode was enabled in config.xml). Taping a second time on the widget will cause it to go to full screen mode. From the full screen mode, the user can go back to floating mode (the button in the top-right corner) or he can close the widget.

An important aspect between switching from floating mode to full screen mode and back is to adjust the user interface. In floating mode, since there is less space available, a stripped-down version of the full screen interface should be presented.

The widget object (lowercase ‘w’) has the ‘widgetMode’ property that we can use the find the current mode and it also has the ‘widgetmodechange’ event, which gets fired every time the mode is changed. Putting it all together we get the following Javascript code that we can use to adjust the user interface:

if (window.widget) { 
  widget.addEventListener("widgetmodechange", function (e) {
    switch (e.mode) { // we can use e.mode or widget.widgetMode
      case 'floating':
        // adjust user interface for floating mode
        break;
      case 'application':
        // display full screen interface
        break;
    }
  }, 
  false);
}

If you only want to make some CSS adjustments or show/hide divs when the mode changes, you could use the ‘-o-widget-mode’ media query extension. It takes a widget mode name as argument and applies the corresponding style when the widget is in that mode:

@media all and (-o-widget-mode: floating) {
  .fullScreenContainer { display: none; }
  .floatingContainer { display: block; }
}

The floating mode is a nice way for a widget to provide some useful information, without requiring the user’s undivided attention and taking up the whole phone screen.

The Vodafone developer Support Team