javax.microedition.lcdui
クラス Form

java.lang.Object
  javax.microedition.lcdui.Displayable
      javax.microedition.lcdui.Screen
          javax.microedition.lcdui.Form

public class Form
extends Screen

Form は任意のアイテム（イメージ、読み取り専用のテキストフィールド、編集可能なテキストフィールド、編集可能な日付フィールド、ゲージおよび選択グループ）を載せるためのスクリーンです。 一般に Item クラスの全てのサブクラスは Form に載せることができます。 実装はレイアウト、フォーカスおよびスクロールの管理を行います。 フォーム内のコンポーネントはいずれもどのような内部スクロールも行いません。 内容全体が一緒にスクロールします。 これが他のクラスの挙動と異なることに注意が必要です。 例えば List は内部だけがスクロールします。

フォームに含まれるアイテムは append(javax.microedition.lcdui.Item)、delete(int)、delete(int)、set(int, javax.microedition.lcdui.Item) の各メソッドによって編集することができます。 フォーム内のアイテムは 0 から size() - 1 の範囲の連続的な正数（最初のアイテムが 0、最後のアイテムが size() - 1 となる）で参照することができます。

アイテムは１つの Form にのみ置くことができます。 アプリケーションが Form にアイテムを置くこうとした際に、アイテムがこのあるいは別の Form に既に置かれている場合、IllegalStateException を throw します。 アプリケーションはアイテムを別の Form に置く前に、以前に置いていた Form からそのアイテムを削除しなければなりません。

他のスクリーンの様に、ほとんどのデバイスはレイアウト方針として垂直配置を行います。 この方針はフォームにおいて、ユーザーによる入力に関係するアイテムに当てはまります。 したがって、復帰改行はテキストフィールド（TextField）、日付フィールド（DateField）、ゲージ（Gauge）、選択グループ（ChoiceGroup）のようなフォーカスを受け取れるアイテムに対して常に行います。

ユーザーと対話の行わない文字列およびイメージは異なったふるまいをします。 復帰改行が文字列に埋め込まれているか、ImageItem のレイアウト指示が復帰改行を強制しない限り、それらは水平方向に配置されます。 テキストの場合は内容を折りたたんで、イメージの場合はディスプレイの幅に合わせて切り取って表示します。 垂直方向へのスクロールは行われますが、水平方向へはスクロールしません。

ディスプレイへ表示されているフォームの内容をアプリケーションが修正した場合、直ちに表示は更新されます。 アプリケーションはフォームの内容を修正後、ディスプレイ上の表示を更新するために特別な処理を行う必要はありません。

フォームがディスプレイ上に表示されている場合、ユーザーはフォームとそのアイテムと無制限に（例えば最初のアイテムから最後のアイテムまでスクロールを伴って）対話することができます。 縦断してスクロールする操作はアプリケーションに見えるイベントを引き起こしません。 ユーザーがフォーム内に置かれた対話型のアイテムの状態を変化させると、システムはアプリケーションにイベントの通知を行います。 この通知は ItemStateListener インタフェースの itemStateChanged() メソッドを呼び出して通知します。 この通知を受け取るリスナーは ItemStateListener インタフェースを実装したオブジェクトを setItemStateListener(javax.microedition.lcdui.ItemStateListener) メソッドを呼び出して設定します。

他の表示可能なオブジェクトの様に、フォームはコマンドを設定し、setCommandListener() メソッドを実装したリスナーを設定することができます。 CommandListener オブジェクトは ItemStateListener オブジェクトとは異なるオブジェクトです。 また、それらは別々に設定し、別々のイベントによって起動されます。

アプリケーション開発者のための注釈：

• このクラスのコンポーネントは任意の組み合わせを行うことができますが、アプリケーション開発者はディスプレイのサイズを理解しておくべきです。 フォームには少数の緊密に関連するユーザーインタフェース要素を置くことを目的としています。
• アイテムの数がディスプレイ内に表示しきれない場合、実装はアイテムをスクロールすることができるようにするか、複数の画面にアイテムを展開してコンポーネントを折り重ねたように表示することがあるかもしれません。

関連項目:

Item

Form

public Form(String title)

指定されたタイトルの新しいオブジェクトを構築します。 このメソッドの呼び出しは以下の記述と等価です。

     Form(title, null);

title に null を渡した場合、タイトルなしのオブジェクトを構築します。

パラメータ:

title - このフォームのタイトルあるいは null を渡します。

Form

public Form(String title,
            Item[] items)

指定されたアイテムを持つオブジェクトを構築します。 これは、空のフォームオブジェクトを作成し、次に append(javax.microedition.lcdui.Item) メソッドによってアイテムを設定することと等価です。 アイテム配列には null を指定することができます。 null を指定した場合、アイテムは指定されていないものとして処理します。 アイテム配列が null ではない場合、各アイテム要素は別のフォームに含まれていない、有効なアイテムでなければなりません。 他のフォームに含まれているアイテムが含まれていた場合、IllegalStateException を throw します。

パラメータ:

title - このフォームのタイトルを渡します。

items - このフォームに設定するアイテム配列あるいは null を渡します。

例外:

IllegalStateException - アイテム配列に他のフォームに含まれるアイテムが含まれていた場合に throw します。

NullPointerException - アイテム配列に null が含まれていた場合に throw します。

append

public int append(Item item)

アイテムをフォームへ加えます。 可能な限り、現在のラインに継続できるように文字列を配置します。 テキスト幅がディスプレイの幅よりも大きな場合、実装は現在のライン上の残りを次の行に配置します。 可能な限り実装は単語を２行に分割すること避けるべきです。 代わりに余白（スペースまたはタブ）の出現位置を分割のためのヒントとして使用すべきです。 また、文字列中の復帰改行文字は、新しい行への分割を引き起こします。

もし、ImageItem オブジェクトのレイアウト指示が行われていない限り、イメージは文字列と同様の方法でレイアウトされます。 フォーカスを設定できるアイテム（TextField、ChoiceGroup、DateField、Gauge）はそれらが占有した行に配置されます。

アイテム要素は別のフォームに含まれていない、有効なアイテムでなければなりません。 他のフォームに含まれているアイテムの場合、IllegalStateException を throw します。

パラメータ:

item - このフォームに追加するアイテムを渡します。

戻り値:

アイテムを配置した位置を返します。

例外:

IllegalStateException - アイテムが既に他のフォームに配置されている場合に throw します。

NullPointerException - item に null を渡した場合に throw します。

append

public int append(String str)

フォームに１つの文字列からなるアイテムを追加します。 このメソッドの呼び出しは以下の記述と等価です。

     append(new StringItem(null, str))

パラメータ:

str - 追加する文字列を渡します。

戻り値:

アイテムを配置した位置を返します。

例外:

NullPointerException - str が null の場合に throw します。

関連項目:

append(Item)

append

public int append(Image image)

フォームへ１つのイメージからなるアイテムを追加します。 このメソッドの呼び出しは以下の記述と等価です。

     append(new ImageItem(null, img, ImageItem.LAYOUT_DEFAULT, null));

パラメータ:

image - 追加するイメージを渡します。

戻り値:

アイテムが追加された位置を返します。

例外:

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

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

関連項目:

append(Item)

insert

public void insert(int index,
                   Item item)

指定された位置にアイテムを挿入します。 フォームが保持するアイテムの数は１つ増加します。 位置を指定するパラメータ itemNum は 0 から size() の範囲内で指定しなければなりません。 最後のアイテムの位置は size() - 1 です。 したがって、size() の位置のアイテムは存在しません。 この値が itemNum に対して指定されている場合、新しいアイテムは最後のアイテムの直後に挿入されます。 この結果は、append(Item) メソッドの呼び出しと等価です。

その他の動作は append(Item) メソッドと等価です。

パラメータ:

index - 挿入するアイテムの位置を渡します。

item - 挿入するアイテムを渡します。

例外:

IndexOutOfBoundsException - アイテムの位置が不適切な場合に throw します。

IllegalStateException - アイテムが既に他のフォームに配置されているアイテムが含まれている場合に throw します。

NullPointerException - item に null を渡した場合に throw します。

関連項目:

append(Item)

delete

public void delete(int index)

指定された位置のアイテムを削除します。 フォームが保持するアイテムの数は１つ縮小します。 フォームから全てのアイテムを削除することは有効な操作です。 位置を指定するパラメータ itemNum は 0 〜 size() - 1 の範囲内でなければなりません。

パラメータ:

index - 削除するアイテムの位置を渡します。

例外:

IndexOutOfBoundsException - アイテムの位置が不適切な場合に throw します。

set

public void set(int index,
                Item item)

指定された位置のアイテムを新たなアイテムに置き換えます。 以前のアイテムはこのフォームから取り除かれます。 位置を指定するパラメータ itemNum は 0 〜 size() - 1 の範囲内でなければなりません。

この操作の結果は以下の記述と等価です。ただし、実装はディスプレイの再描画を最適化するかもしれません。

     insert(n, item);
     delete(n + 1);

パラメータ:

index - 置き換えるアイテムの位置を渡します。

item - 置き換えて新たに配置するアイテムを渡します。

例外:

IndexOutOfBoundsException - アイテムの位置が不適切な場合に throw します。

IllegalStateException - アイテムが既に他のフォームに配置されているアイテムが含まれている場合に throw します。

NullPointerException - item に null を渡した場合に throw します。

get

public Item get(int index)

指定された位置のアイテムを返します。 フォームの内容は変更しません。 位置を指定するパラメータ itemNum は 0 〜 size() - 1 の範囲内でなければなりません。

パラメータ:

index - 取得するアイテムの位置を渡します。

戻り値:

指定された位置のアイテムを返します。

例外:

IndexOutOfBoundsException - アイテムの位置が不適切な場合に throw します。

setItemStateListener

public void setItemStateListener(ItemStateListener iListener)

アイテムで発生したイベントを受け取るリスナーを設定します。 以前のリスナーは新しいリスナーと置き換えます。 リスナーとして null を渡した場合、設定されているリスナーを削除します。

パラメータ:

iListener - 新しく設定するリスナーあるいは null を渡します。

size

public int size()

このフォームに登録されているアイテムの総数を返します。

戻り値:

登録されているアイテムの総数を返します。