org.symbian.tools.wrttools.doc.WebDeveloper/html/GUID-EAE0823B-5914-49C2-9DBC-15B61DE49E60.html
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="copyright" content="(C) Copyright 2009"/><meta name="DC.rights.owner" content="(C) Copyright 2009"/><meta name="DC.Type" content="concept"/><meta name="DC.Title" content="Managing widgets on mobile devices"/><meta name="DC.Relation" scheme="URI" content="GUID-4F4EE10B-BC2C-4046-ADDB-AD4B67DB2A11"/><meta name="DC.Relation" scheme="URI" content="GUID-CCA3FA0B-9D75-453A-947C-B3CB2A85C684"/><meta name="DC.Relation" scheme="URI" content="GUID-4BE0F634-6995-4738-A650-5D3CCBC26647"/><meta name="DC.Format" content="XHTML"/><meta name="DC.Identifier" content="GUID-EAE0823B-5914-49C2-9DBC-15B61DE49E60"/><title>Managing widgets on mobile devices </title><script type="text/javascript">
function initPage() {}
</script><link href="../PRODUCT_PLUGIN/book.css" rel="stylesheet" type="text/css"/><link href="css/s60/style.css" rel="stylesheet" type="text/css" media="all"/></head><body onload="initPage();"><div class="body"><div class="contentLeft prTxt"><h1 class="pageHeading" id="GUID-EAE0823B-5914-49C2-9DBC-15B61DE49E60">Managing widgets on mobile devices</h1><div>
<p>Managing widgets on a mobile device is very straightforward, as most of the management is performed automatically by the S60 platform and the Web Runtime (WRT) environment. Managing a widget means handling its general cooperation with the platform and other applications on the device, including:</p>
<ul>
<li><p>Launching a widget</p></li>
<li><p>Moving a widget to the background or foreground</p></li>
<li><p>Exiting a widget</p></li>
<li><p>Creating a self-updating widget</p></li>
</ul>
<div><h3>Launching a widget</h3><p>When you implement the widget deployment correctly, a widget can be installed successfully on a mobile device. Once installed, the widget is treated in many ways the same as any mobile application. First of all, it is automatically added to the S60 application menu. Users can launch the widget by navigating to it and opening it, or possibly by pressing a softkey. In addition to creating all the mandatory <a href="GUID-0E3095DB-03FF-4240-83F2-6D876AD2083A.html#GUID-0E3095DB-03FF-4240-83F2-6D876AD2083A">widget component files</a>, with all the mandatory properties defined, no special registering is required to enable launching.</p><p>For more information on launching widgets, see section <a href="GUID-05A1F618-5FB1-4821-8408-A213F38F2EDA.html#GUID-05A1F618-5FB1-4821-8408-A213F38F2EDA">Introduction to widgets</a>.</p></div>
<div><h3>Moving a widget to the background/foreground</h3><p>When a widget is running, it is automatically moved to the background if there is an incoming call, for example. If you launch an S60 mobile application from your widget, it appears in the foreground and the widget is moved to the background. When the application is closed, the widget returns to the foreground. The same happens when you launch a Web page from your widget. The Web page is accessed using the Web Browser for S60.</p><p>For more information on launching an application from a widget, see the <a href="GUID-180F11FD-8D26-4305-814F-01BF8DB2DDC8.html#GUID-180F11FD-8D26-4305-814F-01BF8DB2DDC8"><code>openApplication()</code></a> method in the Web Runtime API reference. For more information on launching a Web page, see the <a href="GUID-EFCCE3CA-A1D2-4CD0-8D10-BD6320B19E5A.html#GUID-EFCCE3CA-A1D2-4CD0-8D10-BD6320B19E5A"><code>openURL()</code></a> method.</p><p>You can make your widget react in a certain way when it is moved to the foreground or to the background by using the <code><a href="GUID-F18FD3A0-9CCC-4117-8CC4-4222842E8C59.html#GUID-F18FD3A0-9CCC-4117-8CC4-4222842E8C59">onshow</a></code> and <code><a href="GUID-55F6778A-D1DA-4288-93B2-0863558D34B7.html#GUID-55F6778A-D1DA-4288-93B2-0863558D34B7">onhide</a></code> properties.</p></div>
<div><h3>Exiting a widget</h3><p>Users can exit a widget in several ways:</p><ul>
<li><p>Right softkey</p><p>The right softkey is, by default, assigned to the "Exit" function, which terminates a running widget. So if you have not associated a new operation with the right softkey, your widget exits when the user presses this softkey.</p><div class="note"><p><strong class="note_title">Note: </strong>The control pane that shows the softkey labels is hidden by default in widgets. To have the softkey labels visible, use the <a href="GUID-ED95464B-9BA7-4294-A06F-CA80429B70ED.html#GUID-ED95464B-9BA7-4294-A06F-CA80429B70ED"><code>showSoftkeys()</code></a> method. To hide the softkey labels again, call <a href="GUID-876B67CB-99C0-4925-A51C-646EA5F867B6.html#GUID-876B67CB-99C0-4925-A51C-646EA5F867B6"><code>hideSoftkeys()</code></a>.</p></div></li>
<li><p>Options menu</p><p>There is also an <span class="uicontrol">Exit</span> option in the <span class="uicontrol">Options</span> menu of every widget. This requires no implementation in the widget code. For more information on the <span class="uicontrol">Options</span> menu, see section <a href="GUID-94946735-D23B-49C6-BB65-8BE31737AE42.html#GUID-94946735-D23B-49C6-BB65-8BE31737AE42">Using softkeys</a> and the <a href="GUID-857CF71D-3398-40C2-981A-DEC428A7BA6B.html#GUID-857CF71D-3398-40C2-981A-DEC428A7BA6B">JavaScript <code>menu</code> object</a> in the Web Runtime API reference.</p><div class="figure" id="GUID-17AAC2F0-B9E0-4856-ACA6-DAB5594DD4EE"><img src="GUID-4F6019AE-993E-4B22-942F-65878CB0EF47_d0e13006_href.png"/><p class="figure-title"><strong>Figure: </strong>Exiting a widget using the Options menu</p></div></li>
<li><p>Call termination key</p><p>If users press the call termination key, the widget automatically exits. This functionality requires no implementation in the widget code.</p><div class="figure" id="GUID-3AED7745-1745-4E4D-985D-1122A7266BF8"><img src="GUID-4AB052A7-D87A-48C4-AFD0-4D617B321B90_d0e13020_href.png"/><p class="figure-title"><strong>Figure: </strong>Call termination key</p></div></li>
</ul></div>
<div><h3>Creating self-updating widgets</h3><p>In the JavaScript code of your widget, you can implement functionality that enables the widget to update itself without user action. Updates require a Web service or server from which the widget can query information on possible new widget versions.</p><p>To enable self-updating in a widget:</p><ol>
<li id="GUID-C04DCC22-CEB1-4064-A7EA-084FA00C175F"><a name="GUID-C04DCC22-CEB1-4064-A7EA-084FA00C175F"><!----></a><p>Use a variable for indicating the current version of the widget.</p></li>
<li id="GUID-F6FAE483-1EC7-4266-9032-1F063ABFAC75"><a name="GUID-F6FAE483-1EC7-4266-9032-1F063ABFAC75"><!----></a><p>Send <code>XMLHttpRequest</code> to the Web server to query whether there is a new version of the widget available.</p><p>The reply sent by the Web server should include a URL for the widget update.</p></li>
<li id="GUID-93BBD6F7-A7DD-47A7-8CD7-8BED2F7DB58D"><a name="GUID-93BBD6F7-A7DD-47A7-8CD7-8BED2F7DB58D"><!----></a><p>Compare the server answer to the value of the current version variable.</p></li>
<li id="GUID-D97D5896-F922-442E-8EA9-A7461F596BB9"><a name="GUID-D97D5896-F922-442E-8EA9-A7461F596BB9"><!----></a><p>If there is a newer version of the widget available on the server, launch the browser using the URL of the new widget version.</p><p>When the new version of the widget has been downloaded to the mobile device, the S60 Software Installer receives the widget and installs it on top of the old version.</p></li>
</ol><p>For an example of how to create a self-updating widget, see <a href="http://wiki.forum.nokia.com/index.php/How-to_create_self-updating_WRT_widgets" target="_blank">How to create self-updating WRT widgets</a> available at Forum Nokia.</p></div>
</div></div></div><div class="footer"><hr/><div class="copy">© Nokia 2009.</div></div></body></html>