Categories: Lang-JP | JP How To | JP Web Runtime (WRT) | JP Code Examples | JP S60

This page was last modified 07:28, 6 June 2008.

From Forum Nokia Wiki

原文（英語）: How-to use the menu object in WRT widgets

コード例

下記サイトを参照。
http://wiki.forum.nokia.com/index.php/Image:Themenu.zip

Menuオブジェクト

Menuオブジェクトは、Web Runtime 1.0からサポートしています。Menuオブジェクトは、Widgetエンジンの組み込みオブジェクトの1つです。MenuオブジェクトはWindowオブジェクトの拡張オブジェクトで、WidgetのOptionsメニューやソフトキーを操作するため、Widget独自のAPIとして提供されます。Menuオブジェクトは、Windowオブジェクトとしての window.menu または簡単に menu と記述することによりアクセスできます。このように、Web Runtime環境において menu は予約語の1つなので、他の形式のオブジェクトのために、ユーザ定義のグローバル変数名として使用してはいけません。

WidgetのOptionsメニューは、Menuオブジェクトを使用して作ることができます。Optionsメニューは自動的に端末の左ソフトキーに関連付けられ、他のソフトキー(例．右ソフトキー)に再割り当てすることはできません。左ソフトキーのOptionsメニューのラベルは、現在端末で使用しているシステム言語で定義された表記(例えば、英語の場合は"Options")になります。このように、左ソフトキーのラベルは変更することができません。

Menuオブジェクトのメソッド

• void append(MenuItem menuItem)
• void remove(MenuItem menuItem)
• void replace(MenuItem oldMenuItem, MenuItem newMenuItem)
• Object MenuItem getMenuItemById(Integer menuItemId)
• Object MenuItem getMenuItemByName(String menuItemLabel)
• void setRightSoftkeyLabel(String label, Function callbackfunction)
• void showSoftkeys()
• void hideSoftkeys()
• void clear()

Menuオブジェクトのプロパティ

• void [Function] onShow

Menuオブジェクトメソッドの詳細記述

append()

構文:
[void] window.menu.append(MenuItem menuItem) または [void] menu.append(MenuItem menuItem)

記述:
Optionsメニューリストのトップレベルにメニュー項目を追加するため、appendメソッドを使用します。メニュー項目は、追加した順番でOptionsメニューリスト上に表示されます。

引数:

• menuItem:

Optionsメニューのトップレベルに追加する、MenuItemオブジェクトのインスタンス。

戻り値:
本メソッドは値を返しません。

コメント:
menuオブジェクトをカスケードするサブメニューは、MenuItemオブジェクトを使用して作ります。MenuItem.appendメソッドの記述を参照のこと。

remove()

構文:
[void] window.menu.remove(MenuItem menuItem) または [void] menu.remove(MenuItem menuItem)

記述:
Optionsメニューリストのトップレベルにメニュー項目を追加するため、appendメソッドを使用します。メニュー項目は、追加した順番でOptionsメニューリスト上に表示されます。

引数:

• menuItem:

Optionsメニューのトップレベルから削除する、MenuItemオブジェクトのインスタンス。

戻り値:
本メソッドは値を返しません。

コメント:
カスケードしたサブメニュー中のメニュー項目は、MenuItemオブジェクトのメソッドを使用して削除します。

replace()

このメソッドは廃止されました。今後Web Runtimeでサポートしません。

代わりに、removeメソッドとappendメソッドを使用します。

getMenuItemById()

構文:
[MenuItem] window.menu.getMenuItemById(Integer id) または [MenuItem] menu.getMenuItemById(Integer id)

記述:
MenuItemオブジェクトのインスタンスハンドルを取得するため、指定したMenuItemのIDを用いてgetMenuItemByIdメソッドを使用します。

引数:

• id:

取得する、メニューアイテムハンドルのID

戻り値:
戻り値は、MenuItemオブジェクトのインスタンス。IDが無効の場合、メソッドは"undefined"を返します。

コメント:
なし。

getMenuItemByName()

構文:
[MenuItem] window.menu.getMenuItemByName(String menuItemLabel) または [MenuItem] menu.getMenuItemByName(String menuItemLabel)

記述:
MenuItemオブジェクトのインスタンスハンドルを取得するため、指定したMenuItemのラベルを用いてgetMenuItemByNameメソッドを使用します。

引数:

• menuItemLabel:

取得する、メニューアイテムハンドルのラベル。MenuItemオブジェクトの記述を参照のこと。

戻り値:
戻り値は、存在しているMenuItemオブジェクトのインスタンス。ラベルが無効の場合、メソッドは"undefined"を返します。

setRightSoftkeyLabel()

構文:
[void] window.menu.setRightSoftkeyLabel(String label, Function callbackfunc) または [void] menu.setRightSoftkeyLabel(String label, Function callbackfunc)

記述:
右ソフトキーにおけるラベルと、その関連付けられた操作をカスタマイズするため、setRightSoftKeyLabelメソッドを使います。デフォルトでは、端末の右ソフトキーは"Exit"機能が割当てられ、起動中のWidgetを終了します。デフォルトのラベルは、現在の使用端末のシステム言語に依存(英語の場合は"Exit")します。

引数:

• label:

右ソフトキーに表示するラベルとして指定するテキスト文字

• callbackfunc:

コールバック関数への参照。コールバック関数は、右ソフトキーが押下された時にシステムによって呼び出されます。

戻り値:
本メソッドは値を返しません。

コメント:
右ソフトキーにおけるデフォルトのラベルと"Exit"機能は、setRightSoftkeyLabelメソッドのlabel引数に空文字("")を指定し、callbackfunc引数にnullを指定してメソッドを呼び出すことによって戻すことができます。

コード例:

function switchToSettingsView()
{
// implement and show settings
...
// customize the right softkey
window.menu.setRightSoftkeyLabel('Back', returnToMainView);
}
function returnToMainView()
{
// show main view
...
// restore the default right softkey
window.menu.setRightSoftkeyLabel('', null);
}

showSoftkeys()

構文:
[void] window.menu.showSoftkeys(void) または [void] menu.showSoftkeys(void)

記述:
ソフトキーペインを常に表示する場合、setSoftkeyメソッドを使います。デフォルトでは、端末のソフトキーペインは非表示になっています。ソフトキーペインは、プログラムでshowSoftkeysメソッドを使用した時、または、ユーザーがソフトキーの1つを押下した時に表示されます。

引数:
本メソッドは引数を持ちません。

戻り値:
本メソッドは値を返しません。

コード例:

// choose to show the softkey pane at all times
window.menu.showSoftkeys();

hideSoftkeys()

構文:
[void] window.menu.hideSoftkeys(void) または [void] menu.hideSoftkeys(void)

記述:
ソフトキーペインを非表示にする場合、hideSoftkeyメソッドを使います。デフォルトでは、端末のソフトキーペインは非表示になっています。ソフトキーペインは、プログラムでshowSoftkeysメソッドを使用した時、または、ユーザーがソフトキーの1つを押下した時に表示されます。

引数:
本メソッドは引数を持ちません。

戻り値:
本メソッドは値を返しません。

コード例:

function useFullScreen()
{
// choose to hide the softkey pane to get more screen space
window.menu.hideSoftkeys();
...
}

clear()

構文:
[void] window.menu.clear(void) または [void] menu.clear(void)

記述:
Optionsメニューペインにおけるメニュー項目を削除する場合、clearメソッドを使います。この操作は、サブメニューが含まれている場合はそれも全て削除されます。

引数:
本メソッドは引数を持ちません。

戻り値:
本メソッドは値を返しません。

Menuオブジェクトプロパティの詳細記述

onShow

構文:
[void] window.menu.onShow = function() { } または [void] menu.onShow = menupaneShown

function menupaneShown()
{
// ...
}

記述:
MenuオブジェクトのonShowプロパティは、Optionsメニューを開いた時に呼ばれるイベントハンドラです。言いかえると、ユーザーが左ソフトキーを押下した時にシステムがイベントを発動し、Widgetはコールバック関数を提供することによってそのイベントを拾うことができます。

MenuItemオブジェクト

MenuItemオブジェクトは、Web Runtime 1.0からサポートしています。MenuItemオブジェクトはWidgetエンジンの組み込みオブジェクトの1つです。MenuItemオブジェクトは、Widgetのメニュー項目を操作するためのAPIを提供するリファレンス型です。MenuItemオブジェクトは、Widgetのメインメニューとカスケードしたサブメニューを作成、操作するため、Menuオブジェクトと共に使用する設計になっています。MenuItemオブジェクトは、new演算子を使用して作成します。

MenuItemオブジェクトメソッド:

• Object MenuItem(String label, Integer Id)
• void append(MenuItem childMenuItem)
• void remove(MenuItem childMenuItem)
• void replace(MenuItem oldMenuItem, MenuItem newMenuItem)
• void setDimmed(Boolean true|false)

MenuItemオブジェクトプロパティ:

• void [Function] onSelect

MenuItemオブジェクトメソッドの詳細記述

コンストラクタ

構文:
[MenuItem] new MenuItem(String label, Integer id)

記述:
new演算子を使用して、MenuItemオブジェクトのインスタンスを生成します。

引数:

• label:

メニュー項目のラベルを定義するテキスト文字列。

• id:

メニュー項目を一意に識別するための固有の数値。

戻り値:
MenuItemオブジェクトの初期化されたインスタンス。

コメント:
引数が不正の場合、エラー型を示すJavaScript例外がスローされます。 正しい引数とは、引数idにおける数値型、引数labelにおける文字列型を含みます。ラベルの文字列長が40文字以上の場合、超えた分が切り捨てられます。全てのメニューツリー上において、メニュー項目は独立していて、そのIDによって識別されます。

append()

構文:
[void] MenuItem.append(MenuItem childMenuItem)

記述:
Optionsメニューリスト中の親メニュー項目に子メニュー項目を追加するため、appendメソッドを使用します。これにより、メニューツリー中にサブメニューリストを作成します。カスケードするサブメニューの作成が必要な場合にこのメソッドを使用します。メニュー項目は、appendメソッドで追加した順番でOptionsのメニューリスト上に表示します。

引数:

• childMenuItem:

親メニュー項目に追加する、MenuItemオブジェクトのインスタンス。Optionsメニューリストのトップレベルにメニュー項目を追加する方法については、menu.appendメソッドに関する記述を参照のこと。

戻り値:
本メソッドは値を返しません。

コメント:
画面が小さい端末の場合、サブメニューを多段にカスケードするのは実用的ではありません。最大2レベルが、サブメニューの推奨レベルです。同じメニュー項目(同じレベルで、既存のメニュー項目と同じIDまたは同じラベルを持つ)を作成しようとした場合、メニューアイテムの追加に失敗します。

remove()

構文:
[void] MenuItem.remove(MenuItem childMenuItem)

記述:
親メニュー項目から、子メニュー項目とそれにカスケードする子メニュー項目を削除する場合、removeメソッドを使用します。

引数:

• childMenuItem:

親メニュー項目から削除する、MenuItemオブジェクトのインスタンス。Optionsメニューリストのトップレベルからメニューアイテムを削除する方法については、menu.removeメソッドに関する記述を参照のこと。

戻り値:
本メソッドは値を返しません。

コメント:
Optionsメニューのトップレベルからメニュー項目とその子メニュー項目を削除する場合、Menuオブジェクトのメソッドを使用します。

replace()

このメソッドは廃止されました。今後Web Runtimeでサポートしません。 代わりに、removeメソッドとappendメソッドを使用します。

setDimmed()

構文:
[void] MenuItem.setDimmed(Boolean flag)

記述:
既存のメニュー項目を表示／非表示にする場合に、setDimmedメソッドを使用します。デフォルトでは、Optionsメニューにメニュー項目を追加した時は、表示モードになっています。

引数:

• flag:

メニュー項目を表示する場合はtrue、非表示にする場合はfalse。

戻り値:
本メソッドは値を返しません。

MenuItemオブジェクトプロパティの詳細記述

onSelect

構文:
MenuItem.onSelect = function(Integer id) { } または MenuItem.onSelect = onMenuItemSelected;

function onMenuItemSelected(id)
{
// ...
}

記述:
MenuItemオブジェクトのonSelectプロパティは、メニュー項目が選択された時のイベントハンドラです。言いかえると、ユーザーがOptionsメニューを開き、トップレベルメニューリストまたはサブメニューリストからメニュー項目を選択すると、システムがイベントを発動し、Widgetがコールバック関数を提供することによりそのイベントを拾うことができます。コールバック関数は1つの引数を持ち、それは選択されたメニュー項目を識別するためのID値です。id引数を無視できるように、それぞれのメニュー項目にコールバック関数を割り当てることもできます。

コメント:
サブメニュー項目のコールバック関数は、親メニュー項目をメインメニューペインに追加した後で、onSelectプロパティに割り当てる必要があります。

コード例:

// Creating a menu:
window.onload = createMenu();
// function to create a menu
function createMenu()
{
// Create a Menu Object
var optionsMenu = window.menu;
// Set a callback function for Menu
optionsMenu.onShow = function()
{
alert('Event Trigger: optionsMenu.onShow');
}
// Create two Menu items
var m1 = new MenuItem('Beverages', 2001);
var m2 = new MenuItem('Snacks', 2002);
// Assign a callback function for the menu items
m1.onSelect = menuEventHandler;
m2.onSelect = menuEventHandler;
// Append two Menu items to Menu
optionsMenu.append(m1);
optionsMenu.append(m2);
// Create two more Menu items for Sub-Menu
var m11 = new MenuItem('Coca Cola', 3001);
var m12 = new MenuItem('Pepsi', 3002);
// Assign a callback function for the submenu items
m11.onSelect = submenuEventHandler;
m12.onSelect = submenuEventHandler;
// Append two Sub Menu Items to Menu 'Beverages'
// get Menu Item reference by ID
optionsMenu.getMenuItemById(2001).append(m11);
// get Menu Item reference by Name
optionsMenu.getMenuItemByName('Beverages').append(m12);
}
 
// Implement menu event handler:
function menuEventHandler(id)
{
switch (id)
{
case 2001:
break;
case 2002:
Web Runtime API Reference 32
Forum.Nokia.com
// do something
break;
}
}