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

このクラスは選択リストを含んだスクリーンです。 ほとんどの振る舞いは ChoiceGroup クラスと共通です。 この共通 API は Choice インタフェースの中で定義しています。 List がディスプレイに表示されている場合、ユーザーはそれと無制限（例えば要素が多数ある場合はスクロールして）に対話することができます。 スクロールを伴う操作はアプリケーションから見えるイベントを発生させません。 何らかの Command が発生した場合、システムはアプリケーションへ通知します。 アプリケーションはこの通知を commandAction(Command, Displayable) によって受け取ります。

List は任意の Choice を、「選択 (select)」あるいは「決定 (go)」する際に利用する機能をデバイスに提供します。 一般に、選択機能とソフト・ボタンは別個のものですが、デバイスによっては選択のためにソフトキーを使用することがあります。 いずれにしても、アプリケーションは選択用のキーにラベルを設定することはできません。

選択を行う機能には以下の３種類のタイプがあります。

• Choice.IMPLICIT

  ユーザーがリスト中の要素の選択を行うとアプリケーションが登録している CommandListener へ通知を行います。 この List が CommandListener 呼び出す前に、フォーカスを持っていた要素が選択されます。 SELECT_COMMAND は Choice.IMPLICIT による通知のためのパラメータとして使用します。

• Choice.EXCLUSIVE

  ユーザーの操作によってリスト中の要素を１つ選択します。 この際、アプリケーションへの通知は行いません。

• Choice.MULTIPLE

  ユーザーの操作によってリスト中の要素の選択状態を反転します。 この際、アプリケーションへの通知は行いません。

Choice.IMPLICIT による List は、論理的なコマンドを割り当てることにより、メニューを構築するために使用することができます。 このケースでは、アプリケーションは定義済みのコマンドを用意する必要はありません。 アプリケーションはユーザーが「選択 (select)」した際に呼ばれる CommandListener を登録する必要があります。

他の用途では、「選択 (select)」が押された時に実行されるデフォルトオペレーションを持つスクリーンの実装かもしれません。 例えば、List は電子メールヘッダーおよび３つのオペレーション「読む」、「返信」、「削除」、を含んでいるとします。 ここではデフォルトのオペレーションは「読む」であると仮定します。

     void initialize() {
         myScreen = new List(" 電子メール ", List.IMPLICIT);
         readCommand = new Command(Command.SCREEN, " 読む ", 1);
         replyCommand = new Command(Command.SCREEN, " 返信 ", 1);
         deleteCommand = new Command(Command.SCREEN, " 削除 ", 1);
         myScreen.addCommand(readCommand);
         myScreen.addCommand(replyCommand);
         myScreen.addCommand(deleteCommand);
         myScreen.setCommandListener(this);
     }

List のタイプは Choice.IMPLICIT のため、選択操作によって commandAction(Command, Displayable) メソッドをパラメータに SELECT_COMMAND 渡して呼び出します。 commandAction の実装では通知された内容による判定を行い、「読む」ための処理を開始することができます。

     public void commandAction (Command c, Displayable d) {
         if (d == myScreen) {
             if (c == readCommand || c == List.SELECT_COMMAND) {
                 // メールをユーザーに表示する処理
             }
             // ...
         }
     }

この種のデフォルトオペレーションは慎重に使用しなければならないことは言うまでもありません。 このことを常に意識し、結果として提供するユーザーインタフェースの有用性を確保しなければなりません。

アプリケーションは、List を表示する前に、選択肢の特定の要素を選択状態に設定することができます。

注釈：必須メソッドの多くはインタフェース Choice においてドキュメント化しています。

SELECT_COMMAND

public static final Command SELECT_COMMAND

ユーザーが IMPLICIT による List で選択を行った場合に commandAction(Command, Displayable) へ通知する特別なコマンドです。

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

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

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

List

public List(String title,
            int listType)

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

パラメータ:

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

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

例外:

IllegalArgumentException - listType に不適切な値を渡した場合に 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 ではない場合に以下のいずれかの条件が成立した場合には IllegalArgumentException を throw します。
  • imageElements の配列長が stringElements の配列長と一致しない場合。
  • imageElements の配列内に可変タイプのイメージが含まれている場合。
• choiceType に 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 は 0 〜 size() - 1 の範囲内で指定しなければなりません。

定義:

インタフェース Choice 内の getString

パラメータ:

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

戻り値:

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

例外:

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

関連項目:

getImage(int)

getImage

public Image getImage(int elementNum)

保持している要素内の指定地に設定されているイメージを返します。 パラメータ elementNum は 0 〜 size() - 1 の範囲内で指定しなければなりません。

定義:

インタフェース Choice 内の getImage

パラメータ:

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

戻り値:

指定された要素のイメージを返します。

例外:

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

関連項目:

getString(int)

append

public int append(String stringPart,
                  Image imagePart)

要素に選択肢を追加します。 追加した選択肢は要素の最後に追加されます。 要素数は追加によって１つ増えます。

選択肢にイメージが不要な場合は imagePart に null を渡します。

定義:

インタフェース Choice 内の append

パラメータ:

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

imagePart - 追加する選択肢のイメージ部分あるいは null を渡します。

戻り値:

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

例外:

IllegalArgumentException - 渡されたイメージが可変タイプの場合に throw します。

NullPointerException - 渡された文字列が null の場合に throw します。

insert

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

要素内の指定位置に選択肢を挿入します。 Choice のサイズは挿入によって１つ拡張されます。

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

最後の要素の位置は size() - 1 であり、size() の位置には要素は存在しません。 もし、elementNum に size() の位置を渡した場合、選択肢は最後のエレメントの直後に挿入されます。 これは append(java.lang.String, javax.microedition.lcdui.Image) メソッドによって要素を追加するのと同一です。

選択肢にイメージが不要な場合は imagePart に null を渡します。

定義:

インタフェース Choice 内の insert

パラメータ:

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

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

imagePart - 挿入する選択肢のイメージ部分あるいは null を渡します。

例外:

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

IllegalArgumentException - 渡されたイメージが可変タイプの場合に throw します。

NullPointerException - 渡された文字列が null の場合に throw します。

delete

public void delete(int elementNum)

要素内の指定位置に存在する選択肢を削除します。 Choice のサイズは削除によって１つ縮小されます。

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

定義:

インタフェース Choice 内の delete

パラメータ:

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

例外:

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

set

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

要素内の指定位置に存在する選択肢を新たな選択肢に置き換えます。 パラメータ elementNum は 0 〜 size() の範囲内で指定しなければなりません。

選択肢にイメージが不要な場合は imagePart に null を渡します。

定義:

インタフェース Choice 内の set

パラメータ:

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

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

imagePart - 置き換える選択肢のイメージ部分あるいは null を渡します。

例外:

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

IllegalArgumentException - 渡されたイメージが可変タイプの場合に throw します。

NullPointerException - 渡された文字列が null の場合に throw します。

isSelected

public boolean isSelected(int elementNum)

要素内の指定位置の選択肢が選択状態か否かを返します。 選択している場合は true を、そうでなければ false を返します。

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

定義:

インタフェース Choice 内の isSelected

パラメータ:

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

戻り値:

選択状態の場合は true を、そうでなければ false を返します。

例外:

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

getSelectedIndex

public int getSelectedIndex()

選択されている要素内の位置を返します。 選択タイプとして Choice.EXCLUSIVE を指定している場合、いずれか１つの要素が選択されています。 この Choice 中の選択されている要素に対応する位置あるいは、選択されている要素がない場合は -1 を返します。

選択タイプとして Choice.MULTIPLE を指定している場合は複数の要素を選択することができます。 このため単一の選択状態を表現することができないため、常に -1 を返します。

Choice.MULTIPLE にて完全な選択状態を取得するためには getSelectedFlags(boolean[]) メソッドを使用します。

定義:

インタフェース Choice 内の getSelectedIndex

戻り値:

選択されている場合は選択されている要素の位置が、選択されていない場合は -1 を返します。

getSelectedFlags

public int getSelectedFlags(boolean[] selectedArray_return)

全ての要素の選択状態を boolean 型の配列に返します。 配列には対応する位置の要素が選択状態にあれば true が、そうでなければ false が設定されます。

結果を受け取る selectedArray_return の配列長は size() メソッドで返されるサイズと同じかそれ以上長くなければなりません。 配列が要素数よりも長い場合、配列内の余りの部分には false をセットします。 配列の長さが足りない場合は IllegalArgumentException を throw します。

このメソッドは Choice.EXCLUSIVE あるいは Choice.MULTIPLE のいずれの選択タイプで使用することができます。

定義:

インタフェース Choice 内の getSelectedFlags

パラメータ:

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

戻り値:

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

例外:

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

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

setSelectedIndex

public void setSelectedIndex(int elementNum,
                             boolean selected)

要素内の指定位置の選択肢を選択状態を設定します。 selected が true の場合、指定された要素を選択状態にします。 逆に false の場合は指定された要素を非選択状態にします。

選択タイプが Choice.MULTIPLE の場合、単純に指定された要素の選択状態を設定します。

選択タイプが Choice.EXCLUSIVE および Choice.IMPLICIT の場合の場合、同時に選択状態にできる要素は１つしかありません。 このため、新たに要素を選択状態にすると、それ以前に選択状態になっていた要素は非選択状態となります。

このメソッドの呼び出しによっていかなる Command の活性化は発生しません。

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

定義:

インタフェース Choice 内の setSelectedIndex

パラメータ:

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

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

例外:

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

setSelectedFlags

public void setSelectedFlags(boolean[] selectedArray)

全ての要素の選択状態を設定します。 selectedArray は size() メソッドの返り値と同じか大きくなければなりません。 配列内の要素数を超える部分は無視されます。

配列の対応する位置の要素を、true の場合は選択状態に、false の場合は非選択状態にします。

選択タイプが Choice.MULTIPLE の場合、全ての要素は指定された通りの選択状態となります。

選択タイプが Choice.EXCLUSIVE および Choice.IMPLICIT の場合、selectedArray は１つの true 値を持っていなければなりません。 もしも１つも true がない場合は先頭の要素を選択状態にします。 また、複数の true が存在する場合、実装は最初に現れる true に対応した要素を選択状態とします。

定義:

インタフェース Choice 内の setSelectedFlags

パラメータ:

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

例外:

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

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