javax.microedition.lcdui
クラス ChoiceGroup

java.lang.Object
  javax.microedition.lcdui.Item
      javax.microedition.lcdui.ChoiceGroup

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

Choice

public class ChoiceGroup
extends Item
implements Choice

ChoiceGroup は Form 内に置くことができる、選択可能な要素のグループを表すユーザーインタフェース・コンポーネントです。 グループは単一の選択の選択を行う排他選択モードか、複数の選択を行う複数選択モードのいずれかで作成します。 実装は、これらのモードの表示上の表現において視覚的に異なる表示をそれぞれのモードに提供します。 例えば単一の選択を行うモードでは「ラジオ・ボタン」による表現を行い、複数選択を行うモードでは「チェックボックス」による表現を行うのが一般的です。

注記：不可欠なメソッドの大部分は Choice インタフェースで定義されています。

導入されたバージョン:

MIDP 1.0

ChoiceGroup

public ChoiceGroup(String label,
                   int choiceType)

選択対象の要素を持っていない、指定されたラベルおよびタイプのオブジェクトを構築します。 指定可能なタイプは EXCLUSIVE、MULTIPLE および POPUP のみです。 ChoiceGruop では IMPLICIT を指定することはできません。

パラメータ:

label - 設定するラベルを渡します。

choiceType - 選択するタイプ（EXCLUSIVE、MULTIPLE または POPUP）を渡します。

例外:

IllegalArgumentException - choiceType が EXCLUSIVE、MULTIPLE および POPUP のいずれでもない場合に throw します。

関連項目:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT, Choice.POPUP

ChoiceGroup

public ChoiceGroup(String label,
                   int choiceType,
                   String[] stringElements,
                   Image[] imageElements)

指定されたタイプのオブジェクトを、ラベル、選択要素の文字列配列、選択要素のイメージ配列を受け取って構築します。 指定可能なタイプは EXCLUSIVE、MULTIPLE および POPUP のみです。 ChoiceGruop では IMPLICIT を指定することはできません。

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

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

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

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

パラメータ:

label - 設定するラベルを渡します。

choiceType - 選択するタイプ（EXCLUSIVE、MULTIPLE または POPUP）を渡します。

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

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

例外:

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

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

関連項目:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT, Choice.POPUP

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)

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

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

定義:

インタフェース Choice 内の append

パラメータ:

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

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

戻り値:

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

例外:

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

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

insert

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

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

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

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

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

定義:

インタフェース Choice 内の insert

パラメータ:

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

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

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

例外:

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

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

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

delete

public void delete(int elementNum)

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

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

定義:

インタフェース Choice 内の delete

パラメータ:

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

例外:

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

deleteAll

public void deleteAll()

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

定義:

インタフェース Choice 内の deleteAll

導入されたバージョン:

MIDP 2.0

set

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

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

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

定義:

インタフェース Choice 内の set

パラメータ:

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

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

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

例外:

IndexOutOfBoundsException - elementNum に不適切な値が渡された場合に 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.POPUP を指定している場合、いずれか１つの要素が選択されています。 この ChoiceGroup 中の選択されている要素に対応する位置あるいは、選択されている要素がない場合は -1 を返します。

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

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

定義:

インタフェース Choice 内の getSelectedIndex

戻り値:

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

getSelectedFlags

public int getSelectedFlags(boolean[] selectedArray_return)

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

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

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

定義:

インタフェース 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.POPUP の場合、同時に選択状態にできる要素は１つしかありません。 このため、新たに要素を選択状態にすると、それ以前に選択状態になっていた要素は非選択状態となります。 selected が false の場合、このメソッドは処理は何も行いません。

このメソッドの呼び出しによっていかなる 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 します。

setFitPolicy

public void setFitPolicy(int fitPolicy)

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

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

定義:

インタフェース Choice 内の setFitPolicy

パラメータ:

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

例外:

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

導入されたバージョン:

MIDP 2.0

関連項目:

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 〜 size() の範囲内で指定しなければなりません。

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

定義:

インタフェース Choice 内の setFont

パラメータ:

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

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

例外:

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

導入されたバージョン:

MIDP 2.0

関連項目:

getFont(int)

getFont

public Font getFont(int elementNum)

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

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

定義:

インタフェース Choice 内の getFont

パラメータ:

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

戻り値:

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

例外:

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

導入されたバージョン:

MIDP 2.0

関連項目:

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