From Symbian Developer Community

Comes with Code:	File:MyWidget.wgz

Home screen customisation has traditionally been possible only using manufacturer-specific APIs and Symbian C++. The introduction of Web Runtime (WRT) has made it possible to write installable HTML/JavaScript applications for Symbian and the latest cool addition to WRT is support for home screen representation of widgets.

Contents 1 Introduction to home screen WRT widgets 1.1 Widget lifecycle 2 Four easy steps to a home screen widget 2.1 Declare support for home screen 2.2 Determine which view should be rendered 2.3 Supporting dual views: Implementation pattern 2.4 Handle WRT events 3 Home screen Widget with WRTKit

Introduction to home screen WRT widgets

Home screen WRT widgets allow active content to be added to the phone's home screen. Because home screen contains a lot of other information, such as battery level, time and shortcuts, widgets are only allowed access to a limited amount of screen space. Hence the challenge: Home screen support requires the ability to render two different views of the application.

Figure 1. Full view of the widget	Figure 2. Home screen view of the widget

Let us consider File:MyWidget.wgz as an example. The full view has a form which allows the user to write a short textual message and choose a "mood" icon. In the home screen mode, however, the widget displays only the text and the icon, but not the form.

Widget lifecycle

Without the home screen, the widget lifecycle is very straightforward: It does not differ from that of a regular application. With a home screen the lifecycle model gets an additional state - when the widget is selected for home screen. The new state and transistions are shown in green in Figure 3. The transitions illustrated in red are only possible if the widget is not added to the home screen.

The widget lifecycle is described in Web Developer's Library as follows:

• The user downloads and installs a home-screen-enabled widget on a compatible device.

• The user adds the widget to the home screen, and might have to grant permissions.

• The user selects the widget to open it in full screen view.

The user can interact with the widget in full screen view; for example by making selections, requesting specific data, specifying settings and so on. Exiting the full screen view does not shut down the widget, it is hidden from view and remains running in the background.

• The user removes the widget from the home screen to shut it down.

Removing the widget from the home screen removes it from the open applications list.

• The user uninstalls the widget.

Four easy steps to a home screen widget

Any widget can support a home screen view with very little effort. The remainder of this page provides all the information that you require to add a home screen in four easy steps.

1. Declare support for home screen
2. Be able to determine which view should be rendered
3. Be able to render both full screen and home screen views
4. Handle WRT events

This might sound like a lot of work - but it is, in fact, extraordinarily easy!

Declare support for home screen

Declare that a widget is capable of providing 'home screen' view by including following information in your info.plist file.

 
	<key>MiniViewEnabled</key>
	<true/>
 

On phones where home screen widgets are supported, your widget will now be available for addition to the home screen. On phones where home screen widgets are not supported, this option is ignored.

Determine which view should be rendered

Currently, the preferred way of determining the display mode (full view vs home screen view) is to check the container size. Do this by setting a threshold value - for example, 150 pixels. When in full screen mode the value of window.innerHeight will be a number larger than the 150px threshold. When in home screen mode the value of window.innerHeight will be less.

 
// 'constant' size threshold
var HOME_SCREEN_VIEW_THRESHOLD = 150;
 
// Returns true if in Home screen mode, false otherwise
function isHomeScreenViewMode() {
	var screenHeight = window.innerHeight;
	return ( screenHeight < HOME_SCREEN_VIEW_THRESHOLD );
}
 

The lack of a dedicated API to determine widget state is clearly an oversight. Future releases should bring a more reliable way to determine state.

Supporting dual views: Implementation pattern

The general idea is to have two top level DIV elements; one for home screen, one for full view, and to control the visibility of the elements depending on the required view. Typically, only one element will be shown and the other hidden via style modification.

In our attached example, the relevant part of the HTML looks like this:

 
        . . .
		<!-- Full view container element -->
		<div id="main" class="mainview">
				. . .
		</div>
 
		<!-- Home screen view container element -->
		<div id="mini" class="miniview">
		</div>
	. . .
 

Once set up like this, the code can manipulate the visibility of the two elements independantly. You would typically hide "main" when displaying "mini" and vice versa.

In our example however, we keep "mini" visible all of the time as a preview. Hence, the "mini" element is not hidden in full screen view. The following function does the necessary style manipulations:

 
// /////////////////////////////////
// Support for home screen view
function setViewMode(){
 
	// Find document elements for main and mini view
	var mainView = document.getElementById("main");
	var miniView = document.getElementById("mini");
 
	// Get the view mode
	var hsView = isHomeScreenViewMode(); 
 
	// Set div visibility
	if ( hsView ) {
		// Home screen view - only shows mini view
		mainView.style.visibility = 'hidden';
		miniView.style.position = 'absolute';
		miniView.style.top = '0';
	}
	else {
		// Normal view	- shows both views
		mainView.style.visibility = 'visible';
		miniView.style.position = 'static';
		miniView.style.top = null;
	}
}
 

Note: It is not enough just to control the visibiliy of the element - you must also make sure the box location is correct. You can do this by manipulating style as shown in the example above.

Handle WRT events

Web Runtime emits several events to notify the widget of screen state changes. A simple way to handle all of the necessary interactions is to pass all these events to the setViewMode function above. To do this, register this function as an event handler in the body section of the html file as below:

 
	<body 	onLoad="javascript:init();" 
		onShow="javascript:setViewMode();" 
		onResize="javascript:setViewMode();" >
 

Web Runtime sends the following events in response to screen changes such as orientation change and switching between Home screen and Full view:

• onLoad when the widget is started on the home screen or run as an application
• onShow when the widget is shown on the screen (e.g. by task switching)
• onResize when there is an orientation change

Home screen Widget with WRTKit

The widget in the previous example does not use WRTKit javascript library. Essentially, we have used two div elements for mini and full views and the app renders them 'manually'.

Same two-element trick can be used with WRTKit. However, most of the time we only want to use WRTKit when rendering the full view. To make this distinction, we need to tell the UIManager to bind to the particular DOM element which acts as full view container. This is easily achieved as follows:

 
  ...
  // mainview is the id of the div used as full view container
  uiManager = new UIManager("mainview");
  ...
 

This way WRTKit will only be used for full view, and we can separately / manually render home screen view.

Comments

Sign in to comment…