org.symbian.tools.wrttools.doc.WebDeveloper/html/GUID-94946735-D23B-49C6-BB65-8BE31737AE42.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="Using softkeys"/><meta name="abstract" content="Mobile devices provide limited input facilities for the user and controlling the mouse pointer may be difficult to some people. Therefore, it is recommended that you gather user input in your widget using the mobile device softkeys and an options menu instead of buttons and other such UI components on the screen."/><meta name="description" content="Mobile devices provide limited input facilities for the user and controlling the mouse pointer may be difficult to some people. Therefore, it is recommended that you gather user input in your widget using the mobile device softkeys and an options menu instead of buttons and other such UI components on the screen."/><meta name="DC.Relation" scheme="URI" content="GUID-13E2DE63-47E5-4E2A-85FF-C8B0CAB9D4DE"/><meta name="DC.Relation" scheme="URI" content="GUID-D54DEFE7-E878-4530-B707-A5388DFE1D9D"/><meta name="DC.Relation" scheme="URI" content="GUID-6DD2B3D2-BA3B-4936-BBC9-F61B6757B6F8"/><meta name="DC.Format" content="XHTML"/><meta name="DC.Identifier" content="GUID-94946735-D23B-49C6-BB65-8BE31737AE42"/><title>Using softkeys </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-94946735-D23B-49C6-BB65-8BE31737AE42">Using softkeys</h1><div><p>Mobile devices provide limited input facilities for the user and controlling the mouse pointer may be difficult to some people. Therefore, it is recommended that you gather user input in your widget using the mobile device softkeys and an options menu instead of buttons and other such UI components on the screen.</p>
<div class="note"><p><strong class="note_title">Note: </strong>Consider <a href="GUID-E3EA4F85-E0AE-42AB-8E51-EFD3F0E0A51E.html#GUID-E3EA4F85-E0AE-42AB-8E51-EFD3F0E0A51E">localizing</a> the softkey labels and menu items of your widget to support multiple languages.</p></div>
<div><h3>Naming softkeys</h3><p>To make use of a softkey, you need to map it with a function and label it accordingly. The left softkey is automatically mapped to an options menu. Thus, you can only change the label of the right softkey. By default, the right softkey is mapped to the <span class="uicontrol">Exit</span> function that exits the widget. In some views, you can map the right softkey to a <span class="uicontrol">Cancel</span> or <span class="uicontrol">Back</span> option to return to the previous view.</p><div class="figure" id="GUID-2BDF7598-DB98-4CC4-A237-4F0DB510FCFA"><img src="GUID-D4DD1C07-C851-40C2-8ED5-30173C093E85_d0e3151_href.png"/><p class="figure-title"><strong>Figure: </strong>Using softkeys in a widget</p></div></div>
<div><h3>To show softkeys</h3><p>The control pane that shows the softkey labels is hidden by default in widgets. To manipulate the visibility of the labels:</p><ul>
<li><p>Use the <a href="GUID-ED95464B-9BA7-4294-A06F-CA80429B70ED.html#GUID-ED95464B-9BA7-4294-A06F-CA80429B70ED"><code>showSoftkeys()</code></a> method of the JavaScript <code>menu</code> object to show softkey labels.</p></li>
<li><p>Use the <a href="GUID-876B67CB-99C0-4925-A51C-646EA5F867B6.html#GUID-876B67CB-99C0-4925-A51C-646EA5F867B6"><code>hideSoftkeys()</code></a> method to hide softkey labels.</p></li>
</ul><p>If you rotate the widget screen, the location of the softkey labels changes relative to the other widget UI components. For more information on screen rotation, see <a href="GUID-36CDDA1B-3B62-4936-9E06-7935AAD1CD77.html#GUID-36CDDA1B-3B62-4936-9E06-7935AAD1CD77">Designing for dynamic screen orientation</a>.</p></div>
<div><h3>To set a function for the right softkey</h3><ol>
<li id="GUID-0B2D3339-8D3E-4B3C-8ACF-880F89F13CDA"><a name="GUID-0B2D3339-8D3E-4B3C-8ACF-880F89F13CDA"><!----></a><p>Use the <a href="GUID-5610C4B8-8988-4895-8F88-36F444B4ACFC.html#GUID-5610C4B8-8988-4895-8F88-36F444B4ACFC"><code>setRightSoftkeyLabel()</code></a> method of the <a href="GUID-857CF71D-3398-40C2-981A-DEC428A7BA6B.html#GUID-857CF71D-3398-40C2-981A-DEC428A7BA6B">JavaScript <code>menu</code> object</a> to set a label and function for the softkey.</p></li>
<li id="GUID-ED8C18CD-8A8D-4A81-A411-0D0A11ED3081"><a name="GUID-ED8C18CD-8A8D-4A81-A411-0D0A11ED3081"><!----></a><p>Implement the function in your code. </p></li>
<li id="GUID-DD97D021-9B7E-4644-B96B-D81892CB1A03"><a name="GUID-DD97D021-9B7E-4644-B96B-D81892CB1A03"><!----></a><p>Give the name of the function as a parameter to the <code>setRightSoftkeyLabel()</code> method.</p></li>
</ol></div>
<div><h3>Creating an options menu</h3><p>The options menu allows users to control the widget functionality. For example, users can specify settings or move between views in a widget. Examples of options include: <span class="uicontrol">Open</span>, <span class="uicontrol">Save</span> and <span class="uicontrol">Settings</span>. A menu item in the options menu can also open a submenu.</p><p>All widgets have an options menu with the option <span class="uicontrol">Exit</span> that you cannot remove. Add more options by constructing menu items and appending them to the menu. The label above the left softkey, which can be used to open the options menu and to select an option, is hidden by default. Use the <a href="GUID-ED95464B-9BA7-4294-A06F-CA80429B70ED.html#GUID-ED95464B-9BA7-4294-A06F-CA80429B70ED"><code>showSoftkeys()</code></a> method of the JavaScript <code>menu</code> object to make the softkey labels visible in your widget.</p><div class="figure" id="GUID-BE752430-6AE3-449C-AEB4-429375B6DBCB"><img src="GUID-AFA696FC-475B-410D-B0E4-DDC7A3393A09_d0e3248_href.png"/><p class="figure-title"><strong>Figure: </strong>Creating an options menu for a widget</p></div><p>For an example of creating a dynamic options menu that changes depending on the view, see the <a href="http://www.forum.nokia.com/info/sw.nokia.com/id/1c27d9d7-8946-4e26-947d-2b140c454876/Web_Run-Time_AccuWidget_Example.html" target="_blank">AccuWidget Example</a> on Forum Nokia.</p></div>
<div><h3>To create an options menu</h3><ol>
<li id="GUID-FA23A10F-982D-4F0C-8FCC-5718D1ED7DFC"><a name="GUID-FA23A10F-982D-4F0C-8FCC-5718D1ED7DFC"><!----></a><p>Create a menu item using the <a href="GUID-960AD4A0-AE70-4608-99E7-B663FB99A68D.html#GUID-960AD4A0-AE70-4608-99E7-B663FB99A68D"><code>MenuItem</code> object constructor</a> .</p></li>
<li id="GUID-1898CEA6-AF1A-401F-8D97-38E9C4ADB623"><a name="GUID-1898CEA6-AF1A-401F-8D97-38E9C4ADB623"><!----></a><p>Add the menu item to the options menu using the <a href="GUID-704CF29C-1FDC-4192-9338-C8B9B926111C.html#GUID-704CF29C-1FDC-4192-9338-C8B9B926111C"><code>append()</code></a> method of the JavaScript <code>menu</code> object.</p></li>
<li id="GUID-65F88058-70DE-4A26-B7D5-EA3516A368F3"><a name="GUID-65F88058-70DE-4A26-B7D5-EA3516A368F3"><!----></a><p>Repeat this process for each menu item that you want to add.</p><p>The menu items appear in the options menu in the order in which you add them, the first item at the top.</p></li>
<li id="GUID-1001B1B6-267B-42CF-8A0E-09EC87E44945"><a name="GUID-1001B1B6-267B-42CF-8A0E-09EC87E44945"><!----></a><p>Assign functions to the menu items using the <a href="GUID-A022ED1B-E618-4C44-A437-78393900599C.html#GUID-A022ED1B-E618-4C44-A437-78393900599C"><code>onSelect</code></a> property of the <code>MenuItem</code> object.</p><p>For example, you can create dynamic menu options that change depending on the current selection:</p><pre class="codeblock">// Creates the main menu
function createMenu() {
// Create the menu items
cursorModeMenuItem = new MenuItem("Cursor mode", CMD_CURSOR_MODE);
tabModeMenuItem = new MenuItem("Tab mode", CMD_TAB_MODE);
// Assign callback functions to menu items
cursorModeMenuItem.onSelect = onMenuItemSelected;
tabModeMenuItem.onSelect = onMenuItemSelected;
// Tab mode is the default so let's add cursor mode item to the main menu
window.menu.append(cursorModeMenuItem);
}
// Gets called when a menu item is selected
function onMenuItemSelected(menuId) {
switch (menuId) {
case CMD_CURSOR_MODE:
// Enable cursor mode navigation
widget.setNavigationEnabled(true);
window.menu.append(tabModeMenuItem);
window.menu.remove(cursorModeMenuItem);
break;
case CMD_TAB_MODE:
// Enable tab mode navigation
widget.setNavigationEnabled(false);
window.menu.append(cursorModeMenuItem);
window.menu.remove(tabModeMenuItem);
break;
}
}</pre><div class="figure" id="GUID-DAD7D553-D025-402A-A6B0-1F881196B5CD"><img src="GUID-72B35641-7973-4A16-9B9F-B411107025CB_d0e3306_href.png"/><p class="figure-title"><strong>Figure: </strong>Dynamic menu items</p></div></li>
</ol></div>
<div><h3>To add a submenu to a menu item</h3><ol>
<li id="GUID-C87B6C04-5CC5-4934-B81F-CCBE540A68E1"><a name="GUID-C87B6C04-5CC5-4934-B81F-CCBE540A68E1"><!----></a><p>Create a submenu item using the <a href="GUID-960AD4A0-AE70-4608-99E7-B663FB99A68D.html#GUID-960AD4A0-AE70-4608-99E7-B663FB99A68D"><code>MenuItem</code> object constructor</a>.</p></li>
<li id="GUID-9F25448E-FA32-45FD-9F6A-3F28864B43B1"><a name="GUID-9F25448E-FA32-45FD-9F6A-3F28864B43B1"><!----></a><p>Add the submenu item to the top-level menu item using the <a href="GUID-D498AD58-DF42-4FBA-8767-91FC624873C0.html#GUID-D498AD58-DF42-4FBA-8767-91FC624873C0"><code>append()</code></a> method of the <code>MenuItem</code> object.</p></li>
<li id="GUID-8723DA69-4AC2-4F4E-A490-576A6FB68AF0"><a name="GUID-8723DA69-4AC2-4F4E-A490-576A6FB68AF0"><!----></a><p>Repeat this process for each submenu item that you want to add.</p></li>
<li id="GUID-B33B26CF-5AA4-4001-AB97-73D0129F833A"><a name="GUID-B33B26CF-5AA4-4001-AB97-73D0129F833A"><!----></a><p>Assign functions to the submenu items using the <a href="GUID-A022ED1B-E618-4C44-A437-78393900599C.html#GUID-A022ED1B-E618-4C44-A437-78393900599C"><code>onSelect</code></a> property of the <code>MenuItem</code> object.</p></li>
</ol><div class="p"><div class="figure" id="GUID-F50920E6-B6B1-4D95-A0B1-AA0D7C2F00D6"><img src="GUID-8C55C778-DCB6-48CA-AA88-089720FE4C42_d0e3358_href.png"/><p class="figure-title"><strong>Figure: </strong>Creating a submenu for a menu item</p></div>For example code, see the <a href="GUID-A022ED1B-E618-4C44-A437-78393900599C.html#GUID-EAF0A325-47DD-4AA7-81FA-D26EE10DECB6">example of creating a menu</a> in the Web Runtime API reference.</div></div>
</div></div></div><div class="footer"><hr/><div class="copy">© Nokia 2009.</div></div></body></html>