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

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

ChoiceGroup, List

public interface Choice

Choice は、選択のあらかじめ決められた番号から選択を行うユーザーインタフェース・コンポーネント（以下、UI コンポーネント）のための API を定義します。 そのような UI コンポーネントとは List および ChoiceGroup です。 Choice の内容は文字列およびオプションの Image で構成されています。

Choice の個々の要素は文字列、画像および文字修飾を全て一体とした構成で取り扱います。 文字修飾はテキスト部分に適用され、アプリケーションによって制御することができます。 要素に画像部分が不要である場合、アプリケーションは Image の代わりに null を渡します。 実装はテキスト文字列の先頭にイメージを表示しなければなりません。 また、Choice が選択インジケータ（ラジオ・ボタンまたはチェックボックスなど）の先頭に置かれるならば、要素のイメージは選択インジケータとテキスト文字列の先頭の間に置くべきです。

新しい要素を挿入または追加する際に、実装はデフォルト・フォントを文字修飾に使用します。 このデフォルト・フォントはアプリケーションが setFont(i, null) を呼び出した場合にも使用するフォントです。 全ての ChoiceGroup インスタンスおよび List には同じデフォルト・フォントを設定しなければなりません。 しかし、Choice オブジェクトで使用するデフォルト・フォントは Font.getDefaultFont() が返すフォントと異なることがあります。

Choice 要素の Image 部分は、可変または不変タイプのいずれかの状態です。 Image が可変タイプの場合、Choice の要素はこの Image が append、insert または set に渡された際のスナップショットを構築してそれを使用します。 Choice の要素が表示される際には、常にこのスナップショットを内容として用います。 アプリケーションが呼び出し時の Image オブジェクトに対して描画を行ったとしても、次の上記メソッドの呼び出しまでスナップショットの更新は行われません。 Choice が表示状態の場合にはスナップショットによる画面の更新は行われません（これはアプリケーションから Displayable が正確にいつ表示されて、いつディスプレイから消えるかコントロールすることができないためです）。

以下のコードは Choice ch の要素 k のイメージ部分をリフレッシュするためのテクニック例です：

 ch.set(k, ch.getString(k), ch.getImage(k));

アプリケーションがイメージを提供し、それがデバイスの表示サイズを超える場合、実装はイメージの先端を切り捨てることを選択するかもしれません。 同一の Choice オブジェクト内の各要素に設定するイメージは全て同一の表示サイズのものを使用すべきです。 実装は各要素を表示する際のスペースを同一とすることが一般的であるためです。 アプリケーションは、Display.getBestImageWidth(int) および Display.getBestImageHeight(int) を呼び出すことで実装が推奨するイメージサイズを問い合わせることができます。

要素が非常に長いか行末切断を含んでいる場合、実装はその一部分だけを表示するかもしれません。 このような場合、実装は要素についてできる限り全体を見る手段をユーザーに提供すべきです。 要素を複数行にまたがって表示する場合、２番目およびその後の行はそれらが同じ要素の一部であり新しい要素ではないことを明確にユーザーに示すべきです。

アプリケーションは長い要素に含まれる行末切断キャラクタを実装が表示を行う際に優先する指針を表明することができます。 指針がそれを可能にする場合に限り、最初の行末切断後のキャラクタが表示されるかもしれません。 この指針は setFitPolicy(int) および getFitPolicy() メソッドで制御します。 有効な設定は TEXT_WRAP_DEFAULT、TEXT_WRAP_ON、TEXT_WRAP_OFF です。 他の方法で Choice 実装クラスによって指定されない場合、要素適合指針の初期値は TEXT_WRAP_DEFAULT です。

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

Choice には四つのタイプがあります：暗黙の選択（List でのみ有効）、排他的な選択、複数の選択、そしてポップアップ（ChoiceGroup でのみ有効）です。

排他的な選択は、一連の要素を提示してユーザーと対話します。 そしてユーザーが要素を選択すると、その要素は異なった視覚表現を使用することで選択していることを示します。 そのときの Choice に要素があるなら、常に１つの要素を選択しなければなりません。 もしも要素を１つも選択していない状態になった場合、実装は選択可能ないずれかの要素を選択状態にします。 これは空の Choice オブジェクトに初めて要素を追加した場合および選択中の要素を Choice オブジェクトから削除した場合に発生します。 このような場合、Choice がどの要素を選択するかは実装に委ねられます。 アプリケーションは選択された要素が重要である場合、選択を明示的に設定すべきです。 ユーザーが排他的な Choice 内の要素を非選択にする方法はありません。

ポップアップ選択は排他的な選択と同様です。 ポップアップ選択における選択の振る舞いは排他的な選択と同様です。 しかし、ポップアップ選択はプレゼンテーションと相互作用において排他的な選択と異なります。 排他的な選択では、全ての要素がインライン表示されるべきです。 ポップアップ選択では、選択された要素を常に表示します。そして、他の要素はユーザーがそれらを見るために特定のアクションを起こすまで、隠された状態を維持します。 例えば、排他的な選択は常に１つが選択されたラジオ・ボタンとして実装することができます。 ポップアップ選択はポップアップ・メニューを用意し、メニュー・ボタンに選択された要素を表示するという実装をすることができます。

暗黙な選択はコマンドが開始される時にフォーカスがあたっているか強調されている要素を暗黙の唯一に選択する排他的な選択です。 排他的な選択の様に、そのときの Choice に要素があれば、常に１つの要素を選択します。

複数の選択は一連の要素を提示して、ユーザーが各種要素をどのような組み合わせでも選択することを許容します。 排他的な選択の様に、複数の選択はオブジェクト・オペレーション・モードでユーザーと対話します。 複数の選択の視覚的表現では、複数の要素が選択できるかもしれないことをユーザーに示すのと同様に、個々の要素の選択状態を示す排他的な選択とは異なる視覚表現が行われます。

要素の選択された状態は要素のプロパティです。 他の要素が挿入されるか削除され、要素の移動を引き起こしたとしても、その状態はその要素に保持されます。 例えば要素 n が選択されており、新しい要素をインデックス 0 に挿入したとします。 選択された要素の現在のインデックスは n + 1 となります。 同様の規則は削除にも適用されます。 n が 0 以上であると仮定し、要素 0 を削除すると要素 n - 1 が選択されたままになります。 要素の内容を設定しても、選択状態は変更されません。 新しい要素を挿入または追加する際、それは常に非選択状態となります（上記の様に空の排他、ポップアップまたは暗黙の選択に要素を加える特殊なケースを除く）。

アプリケーションは setSelectedFlags および setSelectedIndex メソッドにより Choice オブジェクトの選択状態を制御することができます。 アプリケーションはこの状態を getSelectedFlags および getSelectedIndex メソッドにより取得することができます。 一般に、これらのメソッドで報告された選択状態は以下の例外を除いてアプリケーションで設定した内容と同じです。 要素を加えるか取り除くと選択は変化するかもしれません。 また、Choice がディスプレイに表示されている場合、実装によるユーザーインタフェース指針とユーザーによる直接の相互作用はオブジェクトの選択状態に影響を与えるかもしれません。 例えば、ユーザーがハイライトを動かしている時に実装は選択を現在のハイライト位置に更新するかもしれませんし、またはユーザーがコマンドを呼び出そうとしている場合に限りハイライトから選択を設定するかもしれません。 また別の例としては、List がカレントになる度に実装は List 内の最初の要素へハイライト（そしてその結果選択する）を移動させるかもしれません。 Choice オブジェクトがディスプレイに表示されている時には、アプリケーションは CommandListener あるいは ItemStateListener の中に限って選択状態を取得すべきです。 他の時に状態を取得すると、アプリケーションで設定したのとは異なる値がもたらされるかもしれません。また、（ユーザーあるいは実装の UI 指針がそれを選択状態を変更する可能性があるため）それはユーザーの意図を反映していないことがあります（ユーザーがまだ選択している途中の可能性があるため）。

注記：バージョン 2.0 において Choice インタフェースにメソッドが加えられます。 通常、インタフェースにメソッドを加えることは互換性を持たない変更です。 しかし、どのようなフィールド、メソッド・パラメータ、メソッド戻り値、そしてアプリケーションが作成するクラスのためにも役立たない型です。 この仕様の将来のバージョンでは更なる変化を Choice インタフェースにもたらすかもしれません。 この仕様の将来のバージョンとの互換性を確保するために、アプリケーションは Choice インタフェースを実装するクラスの作成を避けるべきです。

導入されたバージョン:

MIDP 1.0

EXCLUSIVE

static final int EXCLUSIVE

EXCLUSIVE は、一度に単一の要素を選択できる選択です。 EXCLUSIVE タイプの Choice は全ての要素がインライン表示されるべきです。 すなわち、ユーザーは横断と要素の選択について、全ての特別なアクションを実行する必要はありません。

EXCLUSIVE の値は 1 です。

関連項目:

定数フィールド値

MULTIPLE

static final int MULTIPLE

MULTIPLE は一度に複数の要素を選択することができる選択です。

MULTIPLE の値は 2 です。

関連項目:

定数フィールド値

IMPLICIT

static final int IMPLICIT

IMPLICIT は Command が開始される時に、フォーカスがあたっているアイテムを選択する選択です。

ChoiceGroup オブジェクトには IMPLICIT は有効ではありません。

IMPLICIT の値は 3 です。

関連項目:

定数フィールド値

POPUP

static final int POPUP

POPUP は一度に１つだけ要素を選択することができる選択です。 選択した要素は常に表示されます。 ユーザーがそれらを見るために特定の動作を実行するまで、他の要素は隠蔽されます。 ユーザーがこの動作を実行すると、全ての要素がアクセスできるようになります。 例えば、実装は POPUP タイプの ChoiceGroup の要素を表示するためにポップアップ・メニューを表示するかもしれません。

List オブジェクトには POPUP は有効ではありません。

IMPLICIT の値は 4 です。

導入されたバージョン:

MIDP 2.0

関連項目:

定数フィールド値

TEXT_WRAP_DEFAULT

static final int TEXT_WRAP_DEFAULT

アプリケーションは、テキスト要素の内容について回り込みでも切り捨てでもよく、実装がデフォルトの振る舞いを用いるべきであることを示す定数です。

このフィールドの値は 0 です。

導入されたバージョン:

MIDP 2.0

関連項目:

setFitPolicy(int), 定数フィールド値

TEXT_WRAP_ON

static final int TEXT_WRAP_ON

テキスト要素コンテンツが利用可能なコンテンツ表示スペースに適合させるために、必要であれば複数行を用いるべきであることを暗示する定数です。 実装はテキスト要素の表示に用いることができる行数を制限することがあります。

このフィールドの値は 1 です。

導入されたバージョン:

MIDP 2.0

関連項目:

setFitPolicy(int), 定数フィールド値

TEXT_WRAP_OFF

static final int TEXT_WRAP_OFF

テキスト要素コンテンツを一行だけで表示することを暗示する定数です。 文章が長く一行に表示しきれなければ、行末で強制的に表示を終了します。 実装は完全なテキスト要素コンテンツを表示するためにいくつかな手段を提供すべきです。

例えば、特別なポップアップ式のウィンドウを使用したり、フォーカスがあたっている要素のテキストをスクロールしたりすることが考えられます。

このフィールドの値は 2 です。

導入されたバージョン:

MIDP 2.0

関連項目:

setFitPolicy(int), 定数フィールド値

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 します。

deleteAll

void deleteAll()

この Choice からすべての要素を削除し、１つも要素がない状態にします。 Choice が既に空であれば、このメソッドは何も処理を行いません。

導入されたバージョン:

MIDP 2.0

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、POPUP および IMPLICIT を指定している場合、いずれか１つの要素が選択されています。 この Choice 中の選択されている要素に対応する位置あるいは、選択されている要素がない場合は -1 を返します。

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

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

戻り値:

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

getSelectedFlags

int getSelectedFlags(boolean[] selectedArray_return)

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

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

このメソッドは全ての選択タイプで使用することができます。 MULTIPLE では、複数の要素が結果配列で true に設定されるかもしれません。 EXCLUSIVE、POPUP および IMPLICIT では、１つの要素のみが選択されます（要素が１つも Choice に存在しない場合を除く）。

パラメータ:

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

戻り値:

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

例外:

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

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

setSelectedIndex

void setSelectedIndex(int elementNum,
                      boolean selected)

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

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

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

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

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

パラメータ:

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

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

例外:

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

setSelectedFlags

void setSelectedFlags(boolean[] selectedArray)

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

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

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

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

パラメータ:

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

例外:

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

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

setFitPolicy

void setFitPolicy(int fitPolicy)

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

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

パラメータ:

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

例外:

IllegalArgumentException - fitPlicy に不正な値が指定された場合に throw します。

導入されたバージョン:

MIDP 2.0

関連項目:

getFitPolicy()

getFitPolicy

int getFitPolicy()

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

戻り値:

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

導入されたバージョン:

MIDP 2.0

setFont

void setFont(int elementNum,
             Font font)

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

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

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

パラメータ:

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

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

例外:

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

導入されたバージョン:

MIDP 2.0

関連項目:

getFont(int)

getFont

Font getFont(int elementNum)

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

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

パラメータ:

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

戻り値:

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

例外:

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

導入されたバージョン:

MIDP 2.0

関連項目:

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