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

ChoiceGroup

public ChoiceGroup(String label,
                   int choiceType)

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

パラメータ:

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

choiceType - 選択するタイプを渡します。

例外:

IllegalArgumentException - choiceType が EXCLUSIVE と MULTIPLE のいずれでもない場合に throw します。

関連項目:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT

ChoiceGroup

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

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

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

パラメータ:

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

choiceType - 選択するタイプを渡します。

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

定義:

インタフェース Choice 内の delete

パラメータ:

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

例外:

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

set

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

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

選択肢にイメージが不要な場合は 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() - 1 の範囲内で指定しなければなりません。

定義:

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

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

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

定義:

インタフェース 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 します。

setLabel

public void setLabel(String label)

ラベルを設定します。 label に null が渡された場合、ラベルが指定されていないものとして処理します。

オーバーライド:

クラス Item 内の setLabel

パラメータ:

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