javax.microedition.lcdui
インタフェース Choice

既知の実装クラスの一覧:

ChoiceGroup, List

public interface Choice

このインタフェースは選択を伴うユーザーインタフェース・コンポーネント（UI コンポーネント）に共通の API を定義します。 個々の要素は文字列とオプションの Image オブジェクトによるイメージから構成されます。

選択肢の要素にイメージの表示が不要なアプリケーションは Image オブジェクトに null を指定します。 また、アプリケーションが表示対象の Image オブジェクトを指定した場合であっても、実装がイメージの表示をサポートしていない場合はイメージの表示を省くことがあります。 イメージを表示する実装は、イメージと文字列が単一の要素であると分かるように表示を行います。

同一の Choice オブジェクト内の各要素に設定するイメージは全て同一の表示サイズのものを使用すべきです。 実装は各要素を表示する際の１行の高さを同一とすることが一般的であるためです。

Choice オブジェクトに含まれる要素が多数存在し画面に表示しきれない場合、インプリメンテーションは全ての要素をユーザーに表示し選択する手段を提供します。 また一つの要素を複数の行にまたがって表示を行う場合は、実装はそれが単一の要素であると認識できるように表示を行います。

Choice オブジェクトの要素は、挿入、追加、削除を行うことができます。 また個々の要素の文字列部分およびイメージ部分を取得および設定することができます。 それぞれの要素は 0 から size() - 1 の間の連続する正数によるインデックス番号で指定します。

Choice インタフェースが定義する選択方式は、排他選択（EXCLUSIVE）、複数選択（MULTIPLE）、そして暗黙選択（IMPLICIT）の３つです。

排他選択はユーザーが１つの要素だけを選択することができます。 この選択方式では常に１つの要素が選択状態にあります。 実装は選択状態にある要素は区別が付くように表示を行います。 もしも要素を１つも選択していない状態になった場合、実装は選択可能ないずれかの要素を選択状態にします。 これは空の Choice オブジェクトに初めて要素を追加した場合および選択中の要素を Choice オブジェクトから削除した場合に発生します。

複数選択はユーザーがどのような組み合わせでも自由に複数の要素を選択することができます。 ユーザーが選択を行った全ての要素を選択状態にすることができます。 実装は複数の選択が行えることが分かるような表示を行います。 同様に選択状態にある要素は選択状態ではない要素と明らかに異なる表示を行います。

暗黙選択は List オブジェクトでのみ有効な選択方式で、Command オブジェクトが生成された際に最後にフォーカスがあたっていた要素を選択するという方式です。 この方式は ChoiceGroup クラスでは使用できません。

デフォルトでは排他選択が選択方式として設定されています。

ディスプレイに Choice オブジェクトが表示されている際に、ユーザーはそれを制限無く操作することができます。 例えば要素から要素への移動時にはスクロールを行います。 これらの移動およびスクロールに際して、アプリケーションから見えるイベントは一切発生しません。

アプリケーションによって定義された Command オブジェクトが送信された場合、高レベルイベントは Screen クラスに登録されたリスナーの commandAction() メソッドに通知します。 また、ChoiceGroup オブジェクトの選択状態が変化した際に実装はイベントをアプリケーションの ItemStateListener オブジェクトに通知します。 この際アプリケーションは現在選択している要素に関連する情報を持つ Choice オブジェクトを取得することができます。

EXCLUSIVE

static final int EXCLUSIVE

EXCLUSIVE は、一度に単一の要素を選択できる Choice を示す定数（=1）です。

関連項目:

定数フィールド値

MULTIPLE

static final int MULTIPLE

MULTIPLE は、一度に複数の要素を選択できる Choice を示す定数（=2）です。

関連項目:

定数フィールド値

IMPLICIT

static final int IMPLICIT

IMPLICIT は Command が開始される時に、フォーカスがあたっているアイテムを選択する Choice を示す定数（=3）です。 ChoiceGroup は IMPLICIT を受け入れることはできません。

関連項目:

定数フィールド値

size

int size()

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

戻り値:

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

getString

String getString(int elementNum)

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

パラメータ:

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

戻り値:

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

例外:

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

関連項目:

getImage(int)

getImage

Image getImage(int elementNum)

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

パラメータ:

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

戻り値:

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

例外:

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

関連項目:

getString(int)

append

int append(String stringElement,
           Image imageElement)

要素に選択肢を追加します。 追加した選択肢は要素の最後に追加されます。 Choice のサイズは追加によって１つ拡張されます。

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

パラメータ:

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

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

戻り値:

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

例外:

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

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

insert

void insert(int elementNum,
            String stringElement,
            Image imageElement)

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

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

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

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

パラメータ:

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

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

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

例外:

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

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

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

delete

void delete(int elementNum)

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

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

パラメータ:

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

例外:

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

set

void set(int elementNum,
         String stringElement,
         Image imageElement)

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

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

パラメータ:

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

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

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

例外:

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

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

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

isSelected

boolean isSelected(int elementNum)

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

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

パラメータ:

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

戻り値:

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

例外:

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

getSelectedIndex

int getSelectedIndex()

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

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

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

戻り値:

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

getSelectedFlags

int getSelectedFlags(boolean[] selectedArray_return)

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

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

このメソッドは全ての選択タイプで使用することができます。

パラメータ:

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

戻り値:

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

例外:

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

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

setSelectedIndex

void setSelectedIndex(int elementNum,
                      boolean selected)

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

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

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

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

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

パラメータ:

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

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

例外:

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

setSelectedFlags

void setSelectedFlags(boolean[] selectedArray)

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

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

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

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

パラメータ:

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

例外:

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

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