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 を混合して含むことができる Screen です： イメージ、書き込み禁止テキスト・フィールド、編集可能なテキスト・フィールド、編集可能な日付フィールド、ゲージ、選択グループ、およびカスタム・アイテム。 一般に、Item クラスの全てのサブクラスを Form に含めることができます。 実装はレイアウト、トラバースおよびスクロールを扱います。 Form の内容は全体が一緒にスクロールします。

Item 管理

Form の中に含まれる Item は append、delete、insert および set メソッドを用いて編集することができます。 Form 内の Item は 0 から size() - 1 の範囲の連続的な正数（最初の Item が 0、最後の Item が size() - 1 となる）で参照することができます。

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

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

レイアウト

Form のレイアウト指針は列の周辺で整理を行います。 通常、列はマージン、スクロール・バーおよびそのスクリーンの幅にそれぞれ関連します。 特定の Form の全ての列は同じ幅でしょう。 列は Form の中に含まれた Item に基づく幅において異なりません。スクロール・バーが加えられるか、あるいは取り除かれる必要がある時の様に、これらは全てある特定の状況では幅を変えるかもしれません。 一般に Form は水平スクロールを行いません。

Form は、必要に応じて垂直に大きくなり、垂直にスクロールします。 列の数とそれぞれの列の高さによって、Form の高さは異なります。 それぞれの列の高さはその列で位置調整される Item によって確定します。 列は全てが同じ高さである必要はありません。 また実装は Item ラベルの適切なパディングまたは垂直整列を提供するために列の高さを変更することができます。

実装は Item を使用中の言語慣習に依存して、右から左または右から左へと拡張する方向を選択することができます。 レイアウト指示は特定の Form の中の全ての列に同じ選択が適用されなければなりません。

レイアウト・アルゴリズムの開始する前に、Form の先端に１つの空の列が存在すると考えることができます。 Form において Item レイアウト・アルゴリズムは順番に各 Item を処理進行します。Item 通し番号ゼロから始まって、個々の Item を通して Form の最後の Item まで順番に処理します。 レイアウト方向が（上で述べられているように）右から左なら、列の始まりは Form の左端です。 Item はそれぞれの列の初めから貼り付けを開始し、各列は選択されたレイアウト方向の向こう側に向けて、フィットするように各列に同じくらいの量の Item を詰め込み、状況に応じてそれが列の詰め込みを早く終わらせることができるようにします。 次に新しい列を加え、そして Item を上記で説明したようにそれに詰め込みます。 Item は列に詰め込み、そして全ての Item がレイアウト・アルゴリズムで処理されるまで、新しい列は必要に応じて既存の列の下に加えられます。

レイアウト・アルゴリズムにはカレント・アライメント（現在の位置合わせ）の概念があります。 それらの値として、LAYOUT_LEFT、LAYOUT_CENTER、または LAYOUT_RIGHT を指定することができます。 当初のレイアウト・アルゴリズムのカレント・アライメントの値は、この Form のために有効なレイアウト指示に依存します。 レイアウト方向が左から右なら、初期の位置合わせの値は LAYOUT_LEFT でなければなりません。 レイアウト方向が右から左なら、初期の位置合わせの値は LAYOUT_RIGHT でなければなりません。 カレント・アライメントは、レイアウト・アルゴリズムがいつレイアウト指示 LAYOUT_LEFT、LAYOUT_CENTER、または LAYOUT_RIGHT の１つを持つ Item に遭遇するかで異なります。 これらの方向のいずれも Item に存在していないなら、現在のレイアウト指示は変化しません。 この規則には Form の内容を、位置合わせ値を共有する連続した Item 系列に分類するという効果があります。 それぞれの Item の位置合わせ値は内部的に Form で保持され、getLayout メソッドが報告する Item のレイアウト値には影響しません。

一般に、レイアウト・アルゴリズムは、"改行"を引き起こす特定の状態が現れない限り、Item を前の Item と同じ列に置くことを試みます。 改行がある時には、余地があったとしても、現在の Item は前の Item の後に置く代わりに新しい列の初めに置かれるでしょう。

以下の条件のいずれかが成立するなら、改行は Item の前に起こります：

• 前の Item はそれの後に改行があります。
• この Item には LAYOUT_NEWLINE_BEFORE 指示があります。
  または
• それは StringItem で内容が"\n"で始まります。
  または
• この Item には、Form のカレント・アライメントと異なる LAYOUT_LEFT、Item.LAYOUT_CENTER、または Item.LAYOUT_RIGHT 指示があります。

以下の条件のいずれかが成立するなら、改行は Item の後ろに起こります：

• それは StringItem で内容が"\n"で終わります。
  または
• この Item には LAYOUT_NEWLINE_AFTER 指示があります。
  または
• それは、ChoiceGroup、DateField、Gauge、または TextField で LAYOUT_2 指示が設定されていません。

LAYOUT_NEWLINE_BEFORE あるいは LAYOUT_NEWLINE_AFTER 指示のうち、既に存在している１つがあれば、追加の改行を引き起こしません。 例えば、LAYOUT_NEWLINE_BEFORE 指示が、中身が"\n"で始まる StringItem に現れるなら、１つの改行だけが行われます。 同様の規則は終端の"\n"と LAYOUT_NEWLINE_AFTER にも当てはまります。 また、Item に LAYOUT_NEWLINE_AFTER 指示があり、次の Item には LAYOUT_NEWLINE_BEFORE 指示があるなら、１つの改行しかありません。 しかし、１つの StringItem か隣接している StringItem で、連続した"\n"キャラクタが存在する時は、"\n"キャラクタと同数の改行を引き起こすでしょう。 これは空の列を生み出す原因となります。 列を終わらせる"\n"を含む StringItem に使用されている Font の高さに従って、空の列の高さは決定します。

実装は改行が起こる追加条件を提供するかもしれません。 例えば、実装のレイアウト指針は、暗黙のうちにラベルがあるあらゆる Item の前の改行を引き起こして、ラベルを展開するかもしれません。 また、別の例としては、特定の実装のユーザーインタフェース・スタイルは DateField アイテムが列にいつもそれのみが現れると決めているかもしれません。 このような場合、この実装では、あらゆる DateField アイテムの前後両方に改行が起こるかもしれません。

隣接する２つの Form インデックスを持つ２つの Item 間に、改行のための指示または実装特有の状態のいずれも現れずスペースも問題がなければ、これらの Item は同じ列に置かれるべきです。

列に Item を詰め込む時、Item の幅と列の残りのスペースを比較します。 この目的のために、Item に LAYOUT_SHRINK 指示がなければ使用する幅は Item の好ましい幅ですが、そうでなければ Item の最小の幅を使用します。 Item が列に残っているスペースに適切に詰め込むことができなくらい大きいなら、列はフルであると考えられ、新しい列がこの列の下に加えられ、Item はこの新しい列に貼り付けます。

一度列の内容が決定すれば、Item を拡大することによって、および Item の間にスペースを加えることによって、列で使用可能なスペースを分配します。 この列の上の Item に、LAYOUT_SHRINK 指示がある（つまり、それらは縮小可能です）なら、スペースは最初にこれらの Item に分配されます。 それぞれの Item の好ましいサイズとその最小のサイズの間の差分に応じて、スペースをバランスよくこれらの Item のそれぞれに分配します。 この段階では、縮小可能な Item は、その好ましいサイズの幅を超えて拡張されません。

例えば、30 ピクセルの使用可能なスペースと、２つの縮小可能な Item A と B を持っている列を思い浮かべてください。 Item A の好ましいサイズは 15、最小サイズは 10 です。 Item B の好ましいサイズは 30、最小サイズは 20 です。 A の好ましいおよび最小のサイズの違いは 5、同様に B の違いは 10 です。 30 ピクセルをこれらの Item に、これらの違いに応じた比例に合わせて分配します。 したがって、10 ピクセルを Item A に、20 ピクセルを Item B に分配します。

全ての縮小可能な Item を、それらの好ましい幅に拡張した後にスペースがまだ列に残っている場合、この残っているスペースを LAYOUT_EXPAND 指示（伸長可能な Item）がなされている Item の中に等しく分配します。 いくつかの伸長可能な Item が列にあると、この列の Item は列の全ての幅を占有します。

この列にどのような伸長可能な Item も存在せず、この列に使用可能なスペースが残っている場合、Item はできる限りぴったりと圧縮して、これの列で Item によって共有したアライメント値に応じて、配置します（以後、現在のアライメントを変更すると、列の分断が引き起こされ、同じ列の全ての Item が同じアライメント値を共有しなければなりません）。 アライメント値が LAYOUT_LEFT ならば、Item は列の左端に置きます。そして残ったスペースは列の右端に置きます。 アライメント値が LAYOUT_RIGHT ならば、Item は列の右端に置きます。そして残ったスペースは列の左端に置きます。 アライメント値が LAYOUT_CENTER ならば、Item は中央に置きます。そして残ったスペースは列の左右に均等に分割配置します。

特定の列の Item のセットを考慮して、これらの Item の高さを調査します。 各 Item について、Item に LAYOUT_VSHRINK 指示が無い場合、高さとして好ましい高さを使用し、そうでなければ最小の高さを使用します。 最も高い Item の高さを列の高さとして決定します。 （Item が列）より小さいなら、LAYOUT_VSHRINK 指示を持つ Item は好ましい高さ、または列の高さに拡張します。 列の高さよりも短い Item および LAYOUT_VEXPAND 指示を持つ Item は列の高さに拡張します。 Item における LAYOUT_VEXPAND 指示が、決して列の高さを拡張することはありません。

列の高さより Item の高さの方が短ければ、列の中に垂直配置する際に LAYOUT_TOP、LAYOUT_BOTTOM、および LAYOUT_VCENTER 指示を使用します。 どのような垂直レイアウト指示も指定されていなければ、列の下部に沿って Item を並べなければなりません。

特に StringItem は上記のアルゴリズムで扱います。 StringItem（ラベルを除いた文字列値）の内容に改行キャラクタ（"\n"）が含まれるなら、文字列はそのポイントで分割し、その残りは次の列に配置します。

StringItem の好ましいサイズの片方あるいは両方の軸がロックされたなら、StringItem はその幅と高さに合うように折り返し、その最小の好ましい幅と高さの矩形を、この矩形の幅と高さとして扱います。 このような場合、LAYOUT_SHRINK、LAYOUT_EXPAND、および LAYOUT_VEXPAND 指示は無視します。

StringItem の好ましいサイズの両方の軸がロックされていなければ、StringItem によるテキストは複数の列に改行されるかもしれません。 Item の幅と列に残っているスペースと比較し、レイアウト・アルゴリズムによる位置で、現在の列の上にフィットする同程度のテキストを StringItem の先頭から取り出します。 そして、カレント・アライメント値に応じて、この列の内容を配置します。 StringItem のテキストの残りは、テキストに対応するために必要な新しい列の全幅に合わせて行折込を行います。 カレント・アライメント値に応じ、それぞれの行を満たして配置を行います。 テキストの最後の行は列に利用可能なスペースを残すかもしれません。 この StringItem の直後に列の分断が無ければ、後続の Item は残りのスペースに収容し、カレント・アライメント値に応じて列の内容を配置します。 このルールは、カレント・アライメント値がそれぞれ LAYOUT_LEFT、LAYOUT_RIGHT、または LAYOUT_CENTER のいずれかによって、StringItem の内容のテキストの一部分に左寄せ、右寄せ、または中央寄せを設定して表示を行うという効果を持ちます。 Item.getPreferredWidth および Item.getPreferredHeight メソッドの返す値は、複数の列にまたがって折り返された StringItem の好ましい幅と高さは折り返したテキストを包括する矩形の幅と高さを表します。

また、特に ImageItem は前述のアルゴリズムによって扱います。 このルールは水平アライメント値と LAYOUT_LEFT、LAYOUT_RIGHT、および LAYOUT_CENTER 指示と関連し、Item.LAYOUT_2 指示がその Item に設定されている場合に限り、ImageItem に適用します。 Item.LAYOUT_2 指示が ImageItem に設定されていなければ、LAYOUT_LEFT、LAYOUT_RIGHT、および LAYOUT_CENTER 指示の振る舞いは実装に依存します。

Form のレイアウトは必要に応じて自動的に再計算します。 これは内容の変化やアプリケーションの要求で Item の好ましいサイズを変更するなどの要因で Item のサイズが変化することにより起こるかもしれません。 また、アプリケーションが Item のレイアウト指示を変更することによっても起こるかもしれません。 アプリケーションは、Form のレイアウトを更新するために、どのような特定の要求を実行する必要もありません。

改行と折り返し

テキストを折り返す全てのケースのために、改行がそれぞれの改行キャラクタ（'\n' == '\u000a'）にて生じなければなりません。 空白は、全文を表示することが許されないのであれば改行で省略します。 全ての適切な改行が存在しなければ、実装が単語の境界でテキストを区切ることを推奨します。 単語の境界がまったく存在しなければ、実装が文字の境界でテキストを区切ることを推奨します。

改行を含むラベルは改行までの先頭を切り取り、ラベルの残りの部分を表示しないかもしれません。

ユーザー相互作用

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

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

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

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

導入されたバージョン:

MIDP 1.0

関連項目:

Item

Form

public Form(String title)

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

     Form(title, null);

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

パラメータ:

title - この Form のタイトルあるいは null を渡します。

Form

public Form(String title,
            Item[] items)

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

パラメータ:

title - この Form のタイトルを渡します。

items - この Form に設定する Item 配列あるいは null を渡します。

例外:

IllegalStateException - Item 配列に他の Form に含まれる Item が含まれていた場合に throw します。

NullPointerException - Item 配列に null が含まれていた場合に throw します。

append

public int append(Item item)

Item を Form へ加えます。 新たに加えた Item は Form における最後の Item になり、Form のサイズは 1 増加します。

Item 要素は別の Form に含まれていない、有効な Item でなければなりません。 他の Form に含まれている Item の場合、IllegalStateException を throw します。

パラメータ:

item - この Form に追加する Item を渡します。

戻り値:

Item を配置した位置を返します。

例外:

IllegalStateException - Item が既に他の Form に配置されている場合に throw します。

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

append

public int append(String str)

Form に１つの文字列からなる Item を追加します。 このメソッドの呼び出しは以下の記述と等価です。

     append(new StringItem(null, str))

パラメータ:

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

戻り値:

Item を配置した位置を返します。

例外:

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

関連項目:

append(Item)

append

public int append(Image image)

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

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

パラメータ:

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

戻り値:

Item が追加された位置を返します。

例外:

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

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

関連項目:

append(Item)

insert

public void insert(int index,
                   Item item)

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

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

パラメータ:

index - 挿入する Item の位置を渡します。

item - 挿入する Item を渡します。

例外:

IndexOutOfBoundsException - Item の位置が不適切な場合に throw します。

IllegalStateException - Item が既に他の Form に配置されている Item が含まれている場合に throw します。

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

関連項目:

append(Item)

delete

public void delete(int index)

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

パラメータ:

index - 削除する Item の位置を渡します。

例外:

IndexOutOfBoundsException - Item の位置が不適切な場合に throw します。

deleteAll

public void deleteAll()

この Form から全ての Item を削除し、Item 数をゼロにします。 すでに Form の中身が空ならばこのメソッドはなにもしません。

導入されたバージョン:

MIDP 2.0

set

public void set(int index,
                Item item)

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

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

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

実装は配列への Item の格納と再描画を最適化するかもしれません。

パラメータ:

index - 置き換える Item の位置を渡します。

item - 置き換えて新たに配置する Item を渡します。

例外:

IndexOutOfBoundsException - Item の位置が不適切な場合に throw します。

IllegalStateException - Item が既に他の Form に配置されている Item が含まれている場合に throw します。

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

get

public Item get(int index)

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

パラメータ:

index - 取得する Item の位置を渡します。

戻り値:

指定された位置の Item を返します。

例外:

IndexOutOfBoundsException - Item の位置が不適切な場合に throw します。

setItemStateListener

public void setItemStateListener(ItemStateListener iListener)

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

パラメータ:

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

size

public int size()

この Form に登録されている Item の総数を返します。

戻り値:

登録されている Item の総数を返します。

getWidth

public int getWidth()

Item を表示するために使用可能な領域の幅をピクセル数で返します。 値はデバイスがスクリーンをどのように使用するかによって、ティッカー、タイトル、またはコマンドの存在または不在が影響することがあります。 Form の Item はこの幅の中に合うように広げられます。

オーバーライド:

クラス Displayable 内の getWidth

戻り値:

Form の幅をピクセル数で返します。

導入されたバージョン:

MIDP 2.0

getHeight

public int getHeight()

Item を表示するために使用可能な領域の高さをピクセル数で返します。 この値はスクロールしないで表示することができる Form の高さです。 値はデバイスがスクリーンをどのように使用するかによって、ティッカー、タイトル、またはコマンドの存在または不在が影響することがあります。

オーバーライド:

クラス Displayable 内の getHeight

戻り値:

Form の表示可能な領域の高さをピクセル数で返します。

導入されたバージョン:

MIDP 2.0