javax.microedition.lcdui
クラス List

java.lang.Object
  javax.microedition.lcdui.Displayable
      javax.microedition.lcdui.Screen
          javax.microedition.lcdui.List

すべての実装されたインタフェース:

Choice

public class List
extends Screen
implements Choice

選択リストを提供する Screen です。 振る舞いの大部分および API は ChoiceGroup クラスと共通です。 特に、異なる各 List タイプは Choice インタフェースにて定義されています。 List がディスプレイに表示されている場合、ユーザーは無制限（例えば要素が多数ある場合はスクロールして）に対話することができます。 スクロールを伴う操作はアプリケーションから見えるイベントを発生させません。 Command を CommandListener に通知するために呼び出す場合に限り、システムはアプリケーションへ通知を行います。 また、List クラスは、デバイスが持つ能力によって呼び出されることがある選択コマンドをサポートします。

List における、List 要素の選択操作はユーザー操作が中心であるという概念を持ちます。 専用のハードウェアで「選択」または「実行」キーを用意しているデバイスでは、選択操作はそのキーによって実装されます。 専用キーを用意していないデバイスは、例えばソフトキーなどを用いることで選択操作をするための代替手段を提供しなければなりません。 異なるタイプのリストの中の選択操作の振る舞いは以下のセクションで解説します。

List オブジェクトは Choice.EXCLUSIVE、Choice.MULTIPLE、および Choice.IMPLICIT のいずれかの Choice タイプで作成します。 List オブジェクトにおいては Choice タイプの Choice.POPUP を許容しません。

EXCLUSIVE および MULTIPLE 選択 List

選択操作が Command オブジェクトに関連付けられていないので、アプリケーションには操作が実行されるとき、それを通知される手段がないため、それにラベルを設定するなどを行うことができません。 EXCLUSIVE タイプの List では、選択操作はターゲット要素の選択と以前に選択していた要素の選択解除を行います。 MULTIPLE タイプの List では、選択操作はターゲット要素の選択状態を反転します。他の要素の選択状態は変更しません。 ソフトキーを使用することで選択操作を実装するデバイスは、ラベルをソフトキーに提供する必要があるでしょう。 ラベルは EXCLUSIVE タイプの List のために「選択」あるいはそれに類する文言であるべきです。そして、それは MULTIPLE の List では「選択」か「解除」あるいはそれに類する文言であるべきです。

IMPLICIT 選択 List

選択操作は選択コマンドと呼ぶ Command オブジェクトに関連しています。 ユーザーが選択操作を実行すると、システムは選択コマンドを通知するために List の CommandListener を呼び出します。 デフォルトの選択コマンドはシステムによって提供されるコマンドの SELECT_COMMAND です。 選択コマンドは、setSelectCommand メソッドを使用することによってアプリケーションが変更することができます。 ソフトキーを使用することで選択操作を実装するデバイスは、選択コマンドからのラベルを使用するでしょう。 選択コマンドが SELECT_COMMAND であるなら、デバイスは SELECT_COMMAND のラベル属性を用いる代わりに、デバイス自身がラベルを提供することがあります。 一般に、アプリケーションは SELECT_COMMAND を置き換える際には、アプリケーション自身の選択コマンドを提供すべきです。 これにより、システムによって提供される SELECT_COMMAND をあてにすることなく、アプリケーションは重要なラベルを提供することができます。 要素が List にまったく存在しなければ、実装は選択コマンドを発動させてはいけません。List が空の場合には選択対象が存在しないからです。 このような場合、選択コマンドがソフト・ボタンとして、あるいはメニューに存在するなら、取り除くかまたは無効にすべきです。 List が空であるときに、通常は他のコマンドを発動させることができます。

IMPLICIT List の使用

List 要素として操作を提供することで、メニューを構成するために IMPLICIT List を使用することができます。 アプリケーションは List 要素で選択するための Command と、選択コマンドとして使用するための Command を定義して提供します。 また、アプリケーションはユーザーが Command を選択するか、有効にする際に呼ばれる CommandListener を登録しなければなりません：

     String[] elements = { ... }; // List 要素用のメニューアイテム
     List menuList = new List("メニュー", List.IMPLICIT, elements, null);
     Command selectCommand = new Command("開く", Command.ITEM, 1);
     menuList.setSelectCommand(selectCommand);
     menuList.setCommandListener(...);

リスナーはどの要素が選択されているかを決定し、次に対応する動作を実行するために List に対して問い合わせをすることができます。 選択コマンドとして Command を List に設定するとそれが副作用をもたらすので注意が必要です。

選択コマンドは、選択キーが押されたときに行われるデフォルト操作であるとみなすべきです。 例えば、メール・ヘッダを表示する List が３つの操作を持っているとします：読む、返信、そして削除。 読む、はデフォルト操作であると考えることができます。

     List list = new List(" 電子メール ", List.IMPLICIT, headers);
     readCommand = new Command(" 読む ", Command.ITEM, 1);
     replyCommand = new Command(" 返信 ", Command.ITEM, 2);
     deleteCommand = new Command(" 削除 ", Command.ITEM, 3);
     list.setSelectCommand(readCommand);
     list.addCommand(replyCommand);
     list.addCommand(deleteCommand);
     list.setCommandListener(...);

専用の選択キーのあるデバイスでは、このキーを押すと readCommand が発動されます。 選択キーのないデバイスにおいても、普通の Command としてそれが提供されるので、ユーザーは readCommand を発動することができます。

この種類のデフォルト操作は、ユーザーインタフェースは常にユーザービリティを得られることを念頭に置いて、慎重に使用しなければならないことに注意すべきです。 常にデフォルト操作はその List において直感的な操作であるべきです。

導入されたバージョン:

MIDP 1.0

SELECT_COMMAND

public static final Command SELECT_COMMAND

IMPLICIT List のためのデフォルト選択コマンドです。 IMPLICIT List を使用するアプリケーションは、setSelectCommand を使用して自らの選択コマンドを設定すべきです。

SELECT_COMMAND に設定されている Command の内容は以下の通りです：

• label = ""（つまり「空」の文字列）
• type = SCREEN
• priority = 0

（type が ITEM であれば、さらに適切ですが、歴史的な経緯により type には SCREEN が設定されています）

アプリケーションは SELECT_COMMAND を認識するためにこれらの内容を参照してはなりません。 代わりに Command と Displayable（つまり List）のオブジェクトが一致するか否かで判定しなければなりません。

これが他の Displayable とともに使用されるなら、通常の Command と同様に SELECT_COMMAND は扱われます。

List

public List(String title,
            int listType)

タイトルおよびリストのタイプを指定して、新しい空のオブジェクトを作成します。

パラメータ:

title - スクリーンのタイトルを渡します。

listType - IMPLICIT、EXCLUSIVE、MULTIPLE のいずれかのリストタイプを渡します。

例外:

IllegalArgumentException - listType が IMPLICIT、EXCLUSIVE、MULTIPLE のいずれかではない場合に throw します。

関連項目:

Choice

List

public List(String title,
            int listType,
            String[] stringElements,
            Image[] imageElements)

タイトル、リストのタイプおよび初期設定する選択肢の文字列およびイメージの配列を指定して、新しいオブジェクトを作成します。

stringElements は null であってはなりません。 また、全ての配列要素も null であってはなりません。 stringElements の配列長が選択肢の要素数となります。

imageElements はイメージが不要の場合は null を渡すことができます。 同様に個々の配列要素もイメージが不要な場合は null とすることができます。 imageElements が null ではない場合、その配列長は stringElements の配列長と同じでなければなりません。

以下の場合に例外を throw します。

• stringElements が null か、配列に null が含まれる場合には NullPointerException を throw します。
• imageElements が null ではなく imageElements の配列長が stringElements の配列長と一致しない場合は IllegalArgumentException を throw します。
• choiceType に IMPLICIT、EXCLUSIVE および MULTIPLE 以外が渡された場合は IllegalArgumentException を throw します。

パラメータ:

title - スクリーンのタイトルを渡します。詳しくは Screen を参照してください。

listType - IMPLICIT、EXCLUSIVE、MULTIPLE のいずれかのリストタイプを渡します。

stringElements - 選択肢の文字列部分を配列で渡します。

imageElements - 選択肢のイメージ部分を配列で渡します。

例外:

NullPointerException - パラメータに不適切な null が含まれていた場合に throw します。

IllegalArgumentException - パラメータに不適切な値が含まれていた場合に throw します。

関連項目:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT

size

public int size()

保持している要素数を返します。

定義:

インタフェース Choice 内の size

戻り値:

保持している要素数を返します。

getString

public String getString(int elementNum)

elementNum が示す要素の文字列部分を取得します。

定義:

インタフェース Choice 内の getString

パラメータ:

elementNum - 文字列を取り出す要素内の位置を渡します。

戻り値:

指定された要素の文字列を返します。

例外:

IndexOutOfBoundsException - elementNum に不適切な値が渡された場合に throw します。

関連項目:

getImage(int)

getImage

public Image getImage(int elementNum)

elementNum が示す要素のイメージ部分を取得します。

定義:

インタフェース Choice 内の getImage

パラメータ:

elementNum - イメージを取り出す要素内の位置を渡します。

戻り値:

指定された要素のイメージを返します。イメージが存在しなければ null を返します。

例外:

IndexOutOfBoundsException - elementNum に不適切な値が渡された場合に throw します。

関連項目:

getString(int)

append

public int append(String stringPart,
                  Image imagePart)

List に要素を追加します。

定義:

インタフェース Choice 内の append

パラメータ:

stringPart - 追加する選択肢の文字列部分を渡します。

imagePart - 追加する選択肢のイメージ部分あるいはイメージ部分が存在しなければ null を渡します。

戻り値:

選択肢が追加された要素内の位置を返します。

例外:

NullPointerException - stringPart が null の場合に throw します。

insert

public void insert(int elementNum,
                   String stringPart,
                   Image imagePart)

指定した要素を List の指定した位置の要素のすぐ手前に挿入します。

定義:

インタフェース Choice 内の insert

パラメータ:

elementNum - 選択肢を挿入する要素内の位置を渡します。

stringPart - 挿入する選択肢の文字列部分を渡します。

imagePart - 挿入する選択肢のイメージ部分あるいはイメージ部分が存在しなければ null を渡します。

例外:

IndexOutOfBoundsException - elementNum に不適切な値が渡された場合に throw します。

NullPointerException - stringPart が null の場合に throw します。

delete

public void delete(int elementNum)

elementNum が示す要素を削除します。

定義:

インタフェース Choice 内の delete

パラメータ:

elementNum - 削除する対象の要素内の位置を渡します。

例外:

IndexOutOfBoundsException - elementNum に不適切な値が渡された場合に throw します。

deleteAll

public void deleteAll()

この List から全ての要素を削除します。

定義:

インタフェース Choice 内の deleteAll

導入されたバージョン:

MIDP 2.0

set

public void set(int elementNum,
                String stringPart,
                Image imagePart)

elementNum が示す String と Image を新しい内容で置き換えます。

定義:

インタフェース Choice 内の set

パラメータ:

elementNum - 置き換える対象の要素内の位置を渡します。

stringPart - 置き換える選択肢の文字列部分を渡します。

imagePart - 挿入する選択肢のイメージ部分あるいはイメージ部分が存在しなければ null を渡します。

例外:

IndexOutOfBoundsException - elementNum に不適切な値が渡された場合に throw します。

NullPointerException - stringPart が null の場合に throw します。

isSelected

public boolean isSelected(int elementNum)

要素内の指定位置の選択肢が選択状態か否かを返します。

定義:

インタフェース Choice 内の isSelected

パラメータ:

elementNum - 選択状態を取得する対象の要素内の位置を渡します。

戻り値:

選択状態を返します。

例外:

IndexOutOfBoundsException - elementNum に不適切な値が渡された場合に throw します。

getSelectedIndex

public int getSelectedIndex()

List で選択されている要素のインデックス番号を返します。

定義:

インタフェース Choice 内の getSelectedIndex

戻り値:

選択されている場合は選択されている要素のインデックス番号が、選択されていない場合は -1 を返します。

getSelectedFlags

public int getSelectedFlags(boolean[] selectedArray_return)

List の状態を問い合わせ、boolean 配列の selectedArray_return に全ての要素の状態を返します。

定義:

インタフェース Choice 内の getSelectedFlags

パラメータ:

selectedArray_return - 結果を受け取る配列を渡します。

戻り値:

選択されていた要素の数を返します。

例外:

IllegalArgumentException - 配列長が不足している場合に throw します。

NullPointerException - selectedArray_return に null が渡された場合に throw します。

setSelectedIndex

public void setSelectedIndex(int elementNum,
                             boolean selected)

要素の選択状態を設定します。

定義:

インタフェース Choice 内の setSelectedIndex

パラメータ:

elementNum - ゼロから始まる要素のインデックス番号を渡します。

selected - 対象の要素を選択する場合 true を、非選択状態にする場合 false を渡します。

例外:

IndexOutOfBoundsException - elementNum に不適切な値が渡された場合に throw します。

setSelectedFlags

public void setSelectedFlags(boolean[] selectedArray)

List の全ての要素の選択状態を設定します。

定義:

インタフェース Choice 内の setSelectedFlags

パラメータ:

selectedArray - 設定する選択状態を示す配列を渡します。

例外:

IllegalArgumentException - 配列長が不足している場合に throw します。

NullPointerException - selectedArray に null が渡された場合に throw します。

removeCommand

public void removeCommand(Command cmd)

Displayable.removeCommand と同じですが、以下の追加の意味があります。

取り除く対象のコマンドがもしも選択コマンドであるなら、選択コマンドを持たぬように設定し、List からコマンドを取り除きます。

以下のコード：

     // コマンド c は、リスト list における選択コマンドです
     list.removeCommand(c);

以下のコードと等価です：

     // コマンド c は、リスト list における選択コマンドです
     list.setSelectCommand(null);
     list.removeCommand(c);

オーバーライド:

クラス Displayable 内の removeCommand

パラメータ:

cmd - 取り除く対象のコマンドを渡します。

導入されたバージョン:

MIDP 2.0

setSelectCommand

public void setSelectCommand(Command command)

Command を IMPLICIT List の選択動作で使用するように設定します。 デフォルトで暗黙の選択において List は事前に定義された SELECT_COMMAND を用います。 適切なパラメータ値で List.setSelectCommand() メソッドを呼び出すことで、この振る舞いをオーバーライドすることができます。 null 参照が渡されるなら、これは、この List の内容には、どのような「選択」アクションも適切ではないことを意味します。

コマンドオブジェクトの参照が渡され、それが特別なコマンドである SELECT_COMMAND ではなく、またそれが現在この List オブジェクトに存在していなければ、コマンドオブジェクトは addCommand(command) の呼び出しと等価であるようにこの List に加え、選択コマンドとして使用できるようにします。 これは、このコマンドがユーザーがこの List の要素に対して「選択」を行った際に、発動されることを示します。

選択コマンドとして、現在選択されているオブジェクトはコマンドタイプとして ITEM を示すべきです。 ある他のタイプを持つコマンドがあるとしても、それは誤りではありません（List.SELECT_COMMAND は歴史的経緯から SCREEN タイプを持ちます）。 ユーザーインタフェースにおける提供と交換を目的として、実装はまるでタイプ ITEM であるかのように選択コマンドを扱うことができます。

あとで removeCommand() によって List から選択コマンドを取り除くと、まるで List.setSelectCommand(null) を呼び出したかのように、選択コマンドを持たない状態に List を設定します。

List.SELECT_COMMAND を引数に setSelectCommand() を呼び出すことにより、デフォルトの振る舞いを明示的に回復させることができます。

このメソッドは List のタイプが IMPLICIT でなければ効果はありません。

パラメータ:

command - Choice.IMPLICIT List の選択アクションで使用するコマンドか、コマンドを設定しないのであれば null を渡します。

導入されたバージョン:

MIDP 2.0

setFitPolicy

public void setFitPolicy(int fitPolicy)

利用可能な画面スペースに Choice 要素コンテンツを表示する際のアプリケーションに都合のよい適合指針を設定します。 指定された指針は全ての要素に適用します。 有効な値は、Choice.TEXT_WRAP_DEFAULT、Choice.TEXT_WRAP_ON および Choice.TEXT_WRAP_OFF です。

適合指針はヒントとし使用します。実装はアプリケーションが設定した適合指針を無視することがあります。

定義:

インタフェース Choice 内の setFitPolicy

パラメータ:

fitPolicy - Choice 要素に適応する適合指針を渡します。

導入されたバージョン:

MIDP 2.0

関連項目:

Choice.getFitPolicy()

getFitPolicy

public int getFitPolicy()

利用可能な画面スペースに Choice 要素コンテンツを表示する際のアプリケーションに都合のよい適合指針を返します。 設定された適合指針を無視する場合でも、返す値は常にアプリケーションが設定した適合指針です。

定義:

インタフェース Choice 内の getFitPolicy

戻り値:

Choice.TEXT_WRAP_DEFAULT、Choice.TEXT_WRAP_ON または Choice.TEXT_WRAP_OFF のいずれかを返します。

導入されたバージョン:

MIDP 2.0

setFont

public void setFont(int elementNum,
                    Font font)

指定した要素を描画する際に使用するフォントを設定します。 要素のフォントはヒントとして扱います。実装はアプリケーションが指定したフォントを無視することがあります。

パラメータ elementNum は 0 〜 Choice.size() の範囲内で指定しなければなりません。

パラメータ font は有効な Font オブジェクトか null でなければなりません。 パラメータ font が null ならば、実装は要素の描画にデフォルトのフォントを使用しなければなりません。

定義:

インタフェース Choice 内の setFont

パラメータ:

elementNum - フォントを設定する対象の要素内の位置を渡します。

font - 要素を描画する際に使用するフォントを渡します。

導入されたバージョン:

MIDP 2.0

関連項目:

Choice.getFont(int)

getFont

public Font getFont(int elementNum)

指定した要素を描画する際に使用するフォントを返します。 設定されたフォントを無視する場合でも、返すフォントは常にアプリケーションが設定したフォントです。 どのようなフォントもアプリケーションが設定していないか、アプリケーションが null を明示して設定した場合は、実装が選択したデフォルト・フォントを返します。

パラメータ elementNum は 0 〜 Choice.size() の範囲内で指定しなければなりません。

定義:

インタフェース Choice 内の getFont

パラメータ:

elementNum - フォントを取得する対象の要素内の位置を渡します。

戻り値:

要素を描画する際に使用するフォントを返します。

導入されたバージョン:

MIDP 2.0

関連項目:

Choice.setFont(int, javax.microedition.lcdui.Font)