javax.microedition.lcdui
クラス CustomItem

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

public class CustomItem
extends Item

CustomItem のサブクラスを作成することで、Form に新しい視覚的で対話的な要素を追加するカスタマイズを可能にします。 サブクラスはサイズ処理、レンダリングと色の選択、フォントとグラフィックスを含む、それらの視覚的外観に責任を負います。 サブクラスはキー、ポインタ動作およびトラバース動作で発生するイベントに応じることにより、ユーザー相互作用モードに責任を負います。 最終的に、CustomItem の値を変更し、リスナーへの通知の契機となるように Item.notifyStateChanged() を呼び出すのはサブクラスの責任です。

他の Item の様に、CustomItem には、最小と好ましいサイズの概念があります。 これらは Item の総領域に関係します（Item は内容、ラベル、境界などのためのスペースを含んでいます）。 領域の全議論に関しては Item のアイテム・サイズを参照してください。

また、CustomItem のサブクラスには、内容サイズの概念があり、これは CustomItem の内容領域だけのサイズです。 内容領域は CustomItem によって占有された総領域内の長方形の領域です。 内容領域は CustomItem のサブクラスが描画および入力イベントを受け取る領域です。 これはラベルと境界によって消費されたスペースは含みません。 実装は内容領域の外にある Item の領域の中における描画および入力イベントを取り扱う責任を負います。

この領域の左上角を (0, 0) として、実装と CustomItem のサブクラスの間で取り扱う全ての座標が Item の内容領域に関連します。 実装と CustomItem のサブクラスの間で取り扱われるサイズ情報は、getMinContentHeight、getMinContentWidth、getPrefContentHeight、getPrefContentWidth および sizeChanged メソッドによって、全ての内容領域のサイズについて参照することができます。 実装は Item のサイズを報告する Item.getMinimumHeight、Item.getMinimumWidth、Item.getPreferredHeight および Item.getPreferredWidth 各メソッドの様に、内容領域のサイズと Item の総領域のサイズの違いを計算し、維持する責任を負います。

実装は、実装によるユーザーインタフェース指針で課された制限を超えるならば、CustomItem が返したサイズ処理情報を無視することがあります。 この場合、実装は常に sizeChanged メソッドと paint メソッドで CustomItem に実際に与えられたサイズを報告しなければなりません。 例えば、実装がスクリーンより Item が広くなることを禁じるなら、この状況が起こるかもしれません。 CustomItem のサブクラスのコードがスクリーンより広い CustomItem を示す値を getMinContentWidth() が返すなら、実装は getMinContentWidth() によって返された最小の幅よりも小さい幅を割り当てるかもしれません。

実装は CustomItem の内容サイズを返す getMinContentHeight、getMinContentWidth、getPrefContentHeight および getPrefContentWidth の各メソッド、他の CustomItem のメソッドをどのような順番でも呼び出すことができます。 これらの全てのメソッドに関しては、CustomItem のサブクラスのコードは CustomItem の現在の内容と一致した値を返さなければなりません。 内容が変化する場合に CustomItem のサブクラスのコードは、単に内容サイズを返すメソッドが異なる値を返し始めるのは十分ではありません。 代わりに内容が変化する場合は常に invalidate メソッドをサブクラスのコードが呼び出さなければなりません。 これはレイアウト計算を実行する必要があるかもしれないことを実装に示し CustomItem の新しい内容に基づく内容サイズの新しい値を取得するためのメソッドの呼び出しを促します。

相互作用モード

CustomItem は多くのアイテム上で適切な編集を行えるように意図されてはいますが、それは考えられるあらゆる対話を許容するというわけではありません。 見た目（ルック・アンド・フィール）に関するプラットフォーム特有の変化を考慮すると共に相互運用性を何も犠牲にすることなく、柔軟性に関する要望はこれらの API が容易に習得できるほど簡単であるべきという要件に対してバランスが取られています。

汎用的な概念は複数の相互作用"モード"があり Form の実装がどれをサポートするかということを伝えることができるというものです。 そして CustomItem は、１つ以上の相互作用モードをサポートすることを選択することができます。 CustomItem が全ての相互作用モードの全ての組み合わせを実装しなければならないということはありません。 通常、特定の相互作用モードを必要とする高度に対話的なアプローチに加えて、CustomItem は全てのプラットフォームで動作する（以下で論じる別々の編集スクリーンのテクニックなどの）アプローチを実装するでしょう。 実行時に、CustomItem コードはこの相互作用モードをサポートするかどうか決定するためにシステムについて問い合わせることができます。 もしそれがサポートされるならば、CustomItem はそのアプローチを使用することができます。 そうでなければ、それは全てのプラットフォームで動作するようなアプローチへ後退することができます。

状態を変更し、次にその通知を notifyStateChanged に行うことにより、少ない数の状態の異なるコンポーネントはシンプルに応じることができましたが、CustomItem は別々の編集スクリーンを呼び出すために、いつでも Item の Command を使用することができます。 別々の編集スクリーンを使用するためのテクニックとは、値を別の Displayable オブジェクト（List など）にロードし、そしてそれを Display.setCurrent(Displayable) を呼び出して表示するという方法です。 ユーザーがこの値の編集が終了したことを示すために、（OK などの）Command を呼び出すと、リスナーはその Displayable オブジェクトから値を取得し、この Item に戻るために Display.setCurrentItem(Item) を呼び出します。

キーパッド入力

実装はオプションで CustomItem へのキーパッド・イベントのデリバリをサポートすることができます。 実装は getInteractionModes() が返す値に KEY_PRESS、KEY_RELEASE および KEY_REPEAT ビットを設定することによってサポート・レベルを示します。 keyPressed()、keyReleased() および keyRepeated() メソッドの呼び出しによってこれらのビットに対応するイベントを通知します。 また、実装が KEY_RELEASE イベントをサポートするなら、それは KEY_PRESS イベントをサポートしなければなりません。 また、実装が KEY_REPEAT イベントをサポートするなら、それは KEY_PRESS および KEY_RELEASE イベントをサポートしなければなりません。 もしサポートされているならば、対応する KEY_PRESS イベントが通知され、KEY_REPEAT イベントは一般に KEY_PRESS および KEY_RELEASE イベントの間に通知された後に KEY_RELEASE イベントが通知されます。 しかし、CustomItem が可視化される時にキーが押されているなら、CustomItem が対応する KEY_PRESS を通知することなく KEY_RELEASE または KEY_REPEAT イベントが通知されることがあります。

イベントを発生されたキーを示す keyCode はキー・イベント・メソッドに渡されます。 実装はユーザーが発生させたイベントと共に Canvas.KEY_NUM0 から Canvas.KEY_NUM9、Canvas.KEY_STAR および Canvas.KEY_POUND といったキー・コードを通知する手段を提供しなければなりません。 また、実装は他のキーをキー・イベントに通知することがあり、デバイス特有のキーを含むことがあります。 Command がそれに加えられるかどうかによって、CustomItem で利用可能なキーのセットは異なることがあります。

アプリケーションは getGameAction(int) メソッドを使用してキー・コードをゲーム・アクションにマップするかもしれません。 実装が CustomItem でキー・イベントをサポートするなら、実装は十分なキー・コードとのマッピングをゲーム・アクションに提供しなければならないため、すべてのゲーム・アクションが CustomItem で利用可能です。

CustomItem で利用可能なキーのセットとキー・イベントは Canvas で利用可能なものと異なることがあります。 （コンポーネント/アイテムの）トラバースをサポートするシステムの上では、システムは（コンポーネント/アイテムの）トラバースに方向キーを使用して、CustomItem にこれらのキーを通知しないことを選ぶかもしれません。 CustomItem でのキー・コードとゲーム・アクションとの間のマッピングは Canvas のマッピングとは異なるかもしれません。 キー・コードとゲーム・アクションに関する詳細については Canvas クラスのキー・イベントとゲーム・アクションを参照してください。

ポインタ入力

実装はオプションで CustomItem において（スタイラスによるタップなどの）ポインタ・イベントの通知をサポートすることができます。 実装は getInteractionModes() が返す値に POINTER_PRESS、POINTER_RELEASE および POINTER_DRAG ビットを設定することによってサポート・レベルを示します。 pointerPressed()、pointerReleased() および pointerDragged() メソッドの呼び出しによってこれらのビットに対応するイベントを通知します。 また、実装が POINTER_RELEASE イベントをサポートするなら、それは POINTER_PRESS イベントをサポートしなければなりません。 また、実装が POINTER_DRAG イベントをサポートするなら、それは POINTER_PRESS および POINTER_RELEASE イベントをサポートしなければなりません。 もしサポートされているならば、対応する POINTER_PRESS イベントが通知され、POINTER_DRAG イベントは一般に POINTER_PRESS および POINTER_RELEASE イベントの間に通知された後に POINTER_RELEASE イベントが通知されます。 しかし、CustomItem が可視化される時にポインタが押されているなら、CustomItem が対応する POINTER_PRESS を通知することなく POINTER_RELEASE または POINTER_DRAG イベントが通知されることがあります。

ポインタ・イベントの座標 (x, y) はあらゆるポインタ・イベントで通知されます。 この座標は CustomItem の座標系で表現され、それは (0, 0) が CustomItem の左上角です。 ある状況で、ポインタ・イベントは Item 外で起こるかもしれません。

トラバース

実装は CustomItem に対する内部のトラバース（横断および縦断）をサポートするかもしれません。それはつまり、実装は一時的に Item 自身にトラバースに対する責任を託すかもしれません。 例え 1 つのトラバース位置しか CustomItem の中にないとしても、Item をユーザーが実行したとき、それが特化した強調表示、アニメーションなどを実行することができるように、traverse メソッドによってそれらの内部をトラバースするサポートを必要とするかもしれません。

実装は getInteractionModes() が返す値に TRAVERSE_HORIZONTAL または TRAVERSE_VERTICAL ビットを設定することによって CustomItem への内部のトラバースのサポートを示します。 これらのビットのどちらも設定されないなら、実装は CustomItem 内部のトラバースに積極的ではないか、または実装は全くトラバースをサポートしていません。 実装がトラバースをサポートするものの、CustomItem 内部のトラバースのサポートを否定するなら、実装は CustomItem の内容領域にそれ自身のハイライトを提供するでしょう。

CustomItem は内部のトラバースをサポートする義務は全くありません。 それは初期の traverse(int, int, int, int[]) メソッドを呼び出しに false を返すことによって可能です（このメソッドが CustomItem によってオーバーライドされていないのであれば、これはデフォルトの振る舞いです）。 このような場合、システムはユーザーがこの Item の上へおよびそれを超えてトラバースすることができるように手配しなければなりません。 また、特に Item がスクリーンの高さをこえるなら、内部のトラバースが起こっているかどうかに関らず、システムは適切なスクロールが行われるように手配しなければなりません。

実装がトラバース・イベントの CustomItem への通知をサポートを提供しないとしても、キーパッドまたはポインタ・イベントの CustomItem への通知をサポートすることができます。 実装がキーパッドまたはポインタ・イベントの CustomItem への通知をサポートするなら、初期の traverse() 呼び出しに false を返すことによって内部のトラバースを拒否したもののためにも、それはあらゆる CustomItem のためにそうする手段を提供しなければなりません。 これは、その Item が内部のトラバースをサポートしていなくても、そのような実装がまだ Item のためのフォーカスの何らかの概念をサポートしなければならないことを暗示します。

内部のトラバースを実行するための振る舞いと Item のために必要とされている責任の完全な仕様については traverse メソッドの記述を参照してください。

アイテム外観

それぞれの Item の視覚表現はラベル（実装によって扱われる）とその内容（サブクラスによって扱われる）から成ります。

ラベルは Item ではなく実装の責任です。 その内容のために CustomItem に割り当てられるスクリーン領域は実装が CustomItem のラベルを表示するために使用する領域とは別です。 実装はラベルの描画と内容領域に関して、そのレイアウトを制御します。

CustomItem は paint メソッドが呼び出されたときに、常に内容を描画する責任を負います。

前景色、背景色、ハイライトの前景色、ハイライトの背景色、境界色およびハイライトの境界色は Display.getColor(int) から取得すべきです。 これにより CustomItem はデバイスに提供された他の Item のカラー構成と一致するでしょう。 CustomItem は動向を把握して、それ自身のハイライトおよび非ハイライト状態に責任を持たなければなりません。

使用するフォントは Font.getFont(int) から取得すべきです。 これにより、デバイスに提供された他の Item に使用されるフォントと一貫性を持つことができるでしょう。

導入されたバージョン:

MIDP 2.0

TRAVERSE_HORIZONTAL

protected static final int TRAVERSE_HORIZONTAL

CustomItem への内部的な水平トラバース（横断）のサポートを示す相互作用モードのビットです。

TRAVERSE_HORIZONTAL の値は 1 です。

関連項目:

getInteractionModes(), traverse(int, int, int, int[]), 定数フィールド値

TRAVERSE_VERTICAL

protected static final int TRAVERSE_VERTICAL

CustomItem への内部的な垂直トラバース（縦断）のサポートを示す相互作用モードのビットです。

TRAVERSE_VERTICAL の値は 2 です。

関連項目:

getInteractionModes(), traverse(int, int, int, int[]), 定数フィールド値

KEY_PRESS

protected static final int KEY_PRESS

キー押下イベントのサポートを示す相互作用モードのビットです。

KEY_PRESS の値は 4 です。

関連項目:

getInteractionModes(), traverse(int, int, int, int[]), 定数フィールド値

KEY_RELEASE

protected static final int KEY_RELEASE

キー開放イベントのサポートを示す相互作用モードのビットです。

KEY_RELEASE の値は 8 です。

関連項目:

getInteractionModes(), traverse(int, int, int, int[]), 定数フィールド値

KEY_REPEAT

protected static final int KEY_REPEAT

キー・リピート・イベントのサポートを示す相互作用モードのビットです。

KEY_REPEAT の値は 0x10 です。

関連項目:

getInteractionModes(), traverse(int, int, int, int[]), 定数フィールド値

POINTER_PRESS

protected static final int POINTER_PRESS

ポインタ押下イベントのサポートを示す相互作用モードのビットです。

POINTER_PRESS の値は 0x20 が設定されています。

関連項目:

getInteractionModes(), traverse(int, int, int, int[]), 定数フィールド値

POINTER_RELEASE

protected static final int POINTER_RELEASE

ポインタ開放イベントのサポートを示す相互作用モードのビットです。

POINTER_RELEASE の値は 0x40 です。

関連項目:

getInteractionModes(), traverse(int, int, int, int[]), 定数フィールド値

POINTER_DRAG

protected static final int POINTER_DRAG

ポインタ・ドラッグ・イベントのサポートを示す相互作用モードのビットです。

POINTER_DRAG の値は 0x80 です。

関連項目:

getInteractionModes(), traverse(int, int, int, int[]), 定数フィールド値

NONE

protected static final int NONE

トラバースが入ったか、あるいはこの Item 内の場所の選択を変更したが、どの方向もこのトラバース・イベントに関係していないことを示す、トラバース方向のための値です。

NONE の値は 0 です。

関連項目:

getInteractionModes(), traverse(int, int, int, int[]), 定数フィールド値

CustomItem

protected CustomItem(String label)

CustomItem のサブクラスが、ラベルを指定することができるように提供されたスーパークラスのコンストラクタです。

パラメータ:

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

getInteractionModes

protected final int getInteractionModes()

使用可能な相互作用モードを取得します。 どのような種類の入力をこのデバイスにて使用可能であるかを決定するために、CustomItem サブクラスのコードによってこのメソッドが呼び出されることを意図しています。 使用可能なモードはいくつかの要素に依存しているかもしれません：実際のデバイス上のハードウェア・キー、システムが適切なナビゲーションを行うために必要となるキー、ポインティング・デバイスの存在、など。 さらなる議論については相互作用モードを参照してください。

このメソッドが 0 を返すなら、使用可能な唯一の相互作用は Item の Command です。

戻り値:

使用可能な相互作用モードのビットマスクを返します。

getMinContentWidth

protected abstract int getMinContentWidth()

サブクラスによって実装される、内容領域の最小幅をピクセル単位で返します。 このメソッドはレイアウト・アルゴリズムの一部として実装によって呼ばれます。 与えられた実際の幅は sizeChanged および paint メソッドに報告されます。

戻り値:

最小の内容の幅をピクセル数で返します。

getMinContentHeight

protected abstract int getMinContentHeight()

サブクラスによって実装される、内容領域の最小の高さをピクセル単位で返します。 このメソッドはレイアウト・アルゴリズムの一部として実装によって呼ばれます。 与えられた実際の高さは sizeChanged および paint メソッドに報告されます。

戻り値:

最小の内容の高さをピクセル数で返します。

getPrefContentWidth

protected abstract int getPrefContentWidth(int width)

サブクラスによって実装される、内容領域の好ましい幅をピクセル単位で返します。 このメソッドはレイアウト・アルゴリズムの一部として実装によって呼ばれます。

パラメータ width は内容領域に割り当てられた一時的な高さです。 サブクラスのコードは好ましい幅の計算にこの値を使用することができます。 実装が高さに一時的な値を割り当てていないならば、パラメータ width は -1 になるでしょう。 そうでなければ、アプリケーションが CustomItem の高さをロックしたか、またはコンテナのレイアウト・アルゴリズムがこの呼び出しの時点で既に一時的な高さを計算したのであれば、width は特定の値になるでしょう。 サブクラスは渡された仮の高さが渡されると仮定してはなりません。また、好ましい高さとして返した値が認められると仮定してはなりません。 与えられた実際のサイズは sizeChanged および paint メソッドに報告されます。

パラメータ:

width - 一時的な高さが計算されているならそのピクセル数、計算されていないなら -1 を渡します。

戻り値:

好ましい内容の幅をピクセル単位で返します。

getPrefContentHeight

protected abstract int getPrefContentHeight(int height)

サブクラスによって実装される、内容領域の好ましい高さをピクセル単位で返します。 このメソッドはレイアウト・アルゴリズムの一部として実装によって呼ばれます。

パラメータ height は内容領域に割り当てられた一時的な幅です。 サブクラスのコードは好ましい高さの計算にこの値を使用することができます。 実装が幅に一時的な値を割り当てていないならば、パラメータ height は -1 になるでしょう。 そうでなければ、アプリケーションが CustomItem の幅をロックしたか、またはコンテナのレイアウト・アルゴリズムがこの呼び出しの時点で既に一時的な幅を計算したのであれば、height は特定の値になるでしょう。 サブクラスは渡された仮の幅が渡されると仮定してはなりません。また、好ましい幅として返した値が認められると仮定してはなりません。 与えられた実際のサイズは sizeChanged および paint メソッドに報告されます。

パラメータ:

height - 一時的な幅が計算されているならそのピクセル数、計算されていないなら -1 を渡します。

戻り値:

好ましい内容の高さをピクセル単位で返します。

sizeChanged

protected void sizeChanged(int w,
                           int h)

サブクラスにおいて、サイズ変化イベントを扱うために実装します。 この CustomItem の内容領域のサイズが変化した時に、このメソッドがシステムによって呼び出されます。

もし、CustomItem がディスプレイにおいて可視状態でサイズが変更されると、それは自動的な再描画リクエストのトリガーとなるかもしれません。 このような場合、sizeChanged への呼び出しは paint の呼び出しに先行して発生します。 CustomItem が変更前よりも小さくなり、CustomItem の残りの内容が保存されたなら、実装は再描画リクエストを行わないことを選択するかもしれません。 同様に CustomItem が変更前よりも大きくなったなら、実装は新しい領域だけを対象にした再描画リクエストを行うことを選択するかもしれません。 どちらの場合も、保存された内容は CustomItem の基点座標に対して静止したままで残っていなければなりません。 もしサイズ変化が CustomItem の内容にとって重要であるならば、アプリケーションは明示的に変更された領域のために、再描画リクエストを行わなければなりません。 未実行の既存再描画要求と併合することができるため、アプリケーションの再描画リクエストは、複数の再描画を引き起こすとは限らないことに気をつけてください。

もし、Item のサイズが変更された時に内容領域が可視状態ではない場合は、このメソッドの呼び出しは延期されるかもしれません。 Item が目に見えない状態でサイズが変化したならば、Item が再度見えるようになる前に少なくとも一度は sizeChanged が呼び出されます。

このメソッドのデフォルトの実装は何も処理を行いません。

パラメータ:

w - Item の内容領域の新しい幅が渡されます。

h - Item の内容領域の新しい高さが渡されます。

invalidate

protected final void invalidate()

CustomItem のサイズとトラバース位置を更新する必要があるということを通知します。 CustomItem サブクラスのコードがこのメソッドが呼び出すことによって、CustomItem の内容領域か内部のトラバース位置のサイズが変化する必要がある可能性を実装に通知することを意図しています。 CustomItem の内容が変更される時に、これがしばしば起こります。 このメソッドの呼び出しはすぐに戻ります。そしてコンテナのレイアウト・アルゴリズムは、その後何らかのポイントで実行します。必要に応じて以下のメソッドを呼び出します： getMinContentHeight、getMinContentWidth、getPrefContentHeight、getPrefContentWidth、sizeChanged または traverse。 また、再描画がレイアウト操作の結果必要となるなら、paint メソッドが呼び出されるかもしれません。 CustomItem が可視状態にない場合に内容サイズが無効にされるなら、レイアウト操作は延期されるかもしれません。 invalidate が呼ばれたときに、CustomItem が現在のトラバース位置にあると traverse メソッドが呼び出されるでしょう。

paint

protected abstract void paint(Graphics g,
                              int w,
                              int h)

サブクラスによって実装され、コンテナの中に Item を描きます。 呼び出し時点において、Graphics コンテキストの対象はこの CustomItem（または、そのためのバック・バッファ）の内容領域です。 座標調整が設定されるため、(0, 0) は内容領域の左上隅になり、そして描画対象となる領域にクリップが設定されます。 アプリケーションは与えられたクリップ領域の中の全ての画素を描画しなければなりません。 Item はクリップ領域を変更することができますが、システムはどのような変更も Item の内容領域の外に対して描画を許してはなりません。 渡された w と h は Item の内容領域の幅と高さです。 これらの値は常に直近の呼び出しで sizeChanged() に通知された値と等しくなるでしょう。 また、これらは利便性向上のために渡されます。

Graphics オブジェクトの他の値は以下の通りです：

• 現在の色は黒です。
• フォントは Font.getDefaultFont() によって返されたフォントと同一です。
• ストローク・スタイルは SOLID です。

paint() メソッドが呼び出されるのは、この Item の showNotify() が呼び出されてから、その後この Item の hideNotify() が呼び出されるまでの間です。 言い換えるなら、少なくとも Item の一部がディスプレイに表示されている間ということです。 さらに、Item の幅と高さが共にゼロよりも大きい場合に限り、paint() メソッドは呼ばれるでしょう。

パラメータ:

g - Item を描くために使用する Graphics オブジェクトが渡されます。

w - Item の現在の幅（単位：ピクセル）が渡されます。

h - Item の現在の高さ（単位：ピクセル）が渡されます。

repaint

protected final void repaint()

サブクラスのコードによって呼ばれ、Item の再描画を要求します。 この Item がディスプレイに表示されていれば、次に CustomItem を次回表示される時に paint() を呼び出すという結果をもたらすでしょう。 CustomItem サブクラスは内部の状態が更新されたため、視覚表現の更新が必要となるときにこのメソッドを呼び出すべきです。

repaint

protected final void repaint(int x,
                             int y,
                             int w,
                             int h)

サブクラスのコードによって呼ばれ、Item の指定された矩形領域の再描画を要求します。 その領域がディスプレイに表示されていれば、これは指定された矩形領域を含めるように設定された Graphics で paint を呼び出すという結果をもたらすでしょう。 領域は CustomItem の内容領域の相対で指定します。 CustomItem はこのメソッドを、Item の内部の状態が更新され、視覚表現の一部の更新が必要となるときにこのメソッドを呼び出すべきです。

パラメータ:

x - 更新すべきである矩形領域の X 座標を渡します。

y - 更新すべきである矩形領域の Y 座標を渡します。

w - 更新すべきである矩形領域の幅を渡します。

h - 更新すべきである矩形領域の高さを渡します。

traverse

protected boolean traverse(int dir,
                           int viewportWidth,
                           int viewportHeight,
                           int[] visRect_inout)

トラバースが Item に入ったか、または Item の中に現れた時にシステムによって呼び出されます。 トラバースの方向と Item の可視状態にある矩形領域がこのメソッドに渡されます。 メソッドは以下の１つをしなければなりません： それは内部のトラバース位置に関連する状態の情報を更新し、メソッドから返す矩形にこの位置に関連する領域を示すように設定し、そして true を返さなければなりません； または、この Item が内部のトラバースをサポートしないことを示すか、または、その内部のトラバースは Item とそのトラバースの端に到達し、次の Item に進むべきであることを示すために false を返さなければなりません。

実装は getInteractionModes メソッドによって返される値で TRAVERSE_HORIZONTAL または TRAVERSE_VERTICAL ビットの片方か両方を設定することによって、CustomItem の中の内部トラバースのサポートを示します。 dir パラメータは Canvas のゲーム・アクション Canvas.UP、Canvas.DOWN、Canvas.LEFT および Canvas.RIGHT によってトラバースの方向を示します。または NONE によってこのトラバース・イベントに関連するどのような特定のサポートもないことを示します。 TRAVERSE_HORIZONTAL ビットが設定されているなら、これは Canvas.LEFT と Canvas.RIGHT の値がトラバース方向を示すのに使用されることを示します。 TRAVERSE_VERTICAL ビットが設定されているなら、これは Canvas.UP と Canvas.DOWN の値がトラバース方向を示すのに使用されることを示します。 両方のビットが設定されているなら、Item が二次元トラバースを実行すべきであることを示し、全ての四つの方向値をトラバース方向で使用することができます。 TRAVERSE_HORIZONTAL と TRAVERSE_VERTICAL ビットのいかなる組み合わせでも、dir パラメータには NONE がありえます。

Canvas のゲーム・アクションはトラバース方向を示すために使用しますが、これは、これらのゲーム・アクションにマップされたキーがトラバースに使用されていることを暗示しません。または、そのキーはトラバースに全く使用されていません。

viewportWidth と viewportHeight パラメータは、Item のコンテナが Item に与えた見えている領域のサイズを示します。これは、その時々で可視状態になる可能性のある Item の最も広大な領域を表します（この領域をビューポートと呼びます）。

visRect_inout パラメータは情報をこのメソッドに渡して、このメソッドから情報を返すために使用します。 それは int[4] 配列であるに違いありません。 この配列は [x, y, w, z] 形の矩形を示し、(x, y) は Item の左上隅を原点とする矩形の相対的な位置、(w, h) は矩形の幅と高さの情報です。 traverse() メソッドが true を返す場合に限り、この配列に設定された戻り値は意味を持ちます。 traverse() メソッドが false を返す場合には値は無視されます。

このメソッドが呼ばれるとき、visRect_inout 配列は現在可視状態の Item の領域を示す矩形が格納されています。 この領域には、Item のどの部分も可視状態になければゼロ領域となることがあります。例えばスクロールによって画面外へ移動した場合です。 以下では返された矩形の意味について議論します。

CustomItem はこの Item の中にトラバースがあり、それがあるか否かを追跡する状態を維持しなければなりません。また、それは現在の内部の位置を記録しなければなりません。 初めに、Item の外にトラバースがあります。 traverse() メソッドへの初期の呼び出しは、トラバースが Item に入ったことを示します。 このメソッドへのその後の呼び出しは、トラバースがこの Item の中に起こっていることを示します。 traverseOut メソッドが呼ばれるまで、トラバースは Item に残っています。 CustomItem は、Item の中 (within) でのトラバースと Item に入る (entering) トラバースを区別できるように、トラバース状態の動向を捕捉しておかなければなりません。

トラバースが Item に入るとき、トラバース・コードは内部のトラバース位置を Item の構造とトラバース方向にとって適切な"一番目"の位置に初期化すべきです。 後者の指針に関する例として、トラバース方向が DOWN であるなら、初期の位置は Item の最も上にある内部の要素であるべきです。 同様にトラバース方向が UP であるなら、初期の位置は Item の最も下にある内部の要素であるべきです。 主軸がトラバースの軸と直行していても、CustomItem はまだ適切に"一番目"の位置を選択しているべきです。 例えば、トラバース・モードのサポートが TRAVERSE_VERTICAL である、CustomItem が水平な列の要素として構造化されていると仮定してください。 初期のトラバース方向が DOWN ならば、初期の位置は一番左の要素であるかもしれません。同様に、初期のトラバース方向が UP ならば、初期の位置は一番右の要素であるかもしれません。

トラバースは全く特定の方向を持たずに Item に入るかもしれません。その場合、トラバース方向は NONE になります。 ユーザーが直接（例えばポインティング・デバイスで）Item を選択するか、または格納している Form がカレントになり Item がフォーカスを獲得するなら、これが起こるかもしれません。 CustomItem はデフォルトのトラバース位置を選択すべきです。 CustomItem が以前にトラバースしており、CustomItem のユーザーインタフェースにとってそれが適切であるなら、前のトラバース位置を回復すべきです。

トラバースが Item の中で起こるとき、トラバースの向きに適切な次の領域に内部のトラバース位置を動かさなければなりません。 Item は以下に説明するように visRect_inout パラメータに対して、更新された内部のトラバース位置を報告して true を返さなければなりません。 Item はユーザーに内部のトラバース位置を表示するために通常はハイライトを提供するでしょう。 そのため、通常はトラバース・イベントで旧および新トラバース位置に対して再描画要求を行います。 領域が visRect_inout によって戻される矩形と、Item が再描画要求する領域が同じでなければならないという要件は一切ありません。 システムはスクロールの結果発生するいくつかの追加の再描画を、いくつかの再描画要求に結合します。

既に CustomItem の中にトラバースがあるとき、traverse() メソッドが方向は NONE で呼ばれるかもしれません。 これは invalidate() メソッドを呼んだ CustomItem サブクラスのコードに対応して発生するでしょう。 このような場合、CustomItem は単純にトラバース位置の現在の概念を返すべきです。 例えば、内容の変化の様に、CustomItem が自然（すなわち、トラバース・イベントに対応してではなく）にトラバース位置を更新する必要があるなら、このメカニズムが有効です。

もしも内部のトラバース位置が、トラバース・イベントによってトラバースが論理的に Item の外へ移るようなものであるなら、Item は traverse() メソッドから false を返すべきです。 例えば、現在のトラバース位置が Item の最も下の内部要素であり、トラバース方向が DOWN であるなら、traverse() メソッドは単に false を返すべきです。 このような場合、メソッドは visRect_inout 配列の値を更新する必要はありません。 Item は内部のトラバース位置を変更せずに抜けなければなりません。そして、それはハイライトを更新するために再描画要求をリクエストすべきではありません。 traverseOut() メソッドが呼び出されるまで、それはこれらの動作を延期すべきです。 トラバースが実際に Item を抜けるとき、システムは traverseOut() メソッドを呼び出すでしょう。 システムは、この Item が Form の端にあるか、またはトラバースを受け入れることができる他の Item がひとつも無ければ、traverseOut() メソッドを呼び出さないかもしれません。 traverse() メソッドが false を返したとしても、まだこの Item の中にトラバース位置があります。 traverseOut() が呼び出されるまで、それはこの Item に残っています。

Item に入ることを意味する初期の traverse() の呼び出しと Item の中でのトラバースを意味するその後の呼び出しの間における、微妙な区別をここに述べます。 初期の呼び出しに false を戻り値とすると、この Item は内部のトラバースをまったく実行しないことを示します。そして、その後の呼び出しに false を返すことはトラバースがこの Item の中にあり、今出るかもしれないことを示します。

visRect_inout 配列で返した矩形の幅と高さは、スクロールと描画をする目的で Form が使用します。 Form は常に Item の位置を調整しなければならないため、位置 (x, y) によって指定されるこの矩形の左上隅は目に見えます。 また、さらに Item も幅と高さを指定することがあり、そのような場合、Form が Item の位置調整を試みて、この矩形ができる限り多く目に見えるようにします。 幅と高さがビューポートのサイズよりも大きいのなら、この矩形の下部と右側部分はおそらくユーザーにとって見えるようにはならないでしょう。 このようにして返した矩形は Item の内部要素の１つのサイズと位置を通常は意味するでしょう。そしてまた、それは要素のハイライトによって描画されるところに通常は（必ずではありませんが）対応するでしょう。 幅と高さの値がゼロであることは正しく、特に扱われません。 幅と高さの値が負数の場合、それはゼロであるかのように扱います。

トラバース方向に関しては、visRect_inout 配列で返した矩形の位置を必須としません。 例えば、CustomItem が内部のスクロールを実装するなら、DOWN のトラバース方向によって、Item の内容は古い位置の上に返した矩形があることができるように、十分遠くに上向きスクロールするかもしれません。 CustomItem サブクラスは、一方向への継続的なトラバースが、最終的に Item の端に達して、次にこのメソッドから false を返すことによって、トラバースがこの Item から出ることを確実にしなければなりません。 これが Item の中のトラバースをトラップにかけるので、CustomItem は"回り込み"の振る舞い（例えば、トラバース位置を一番下の要素から一番上の要素に下向きにトラバースする）をしてはなりません。

CustomItem がコンテナのビューポートより小さな内部の要素から構成されるなら、返した矩形はこれらの要素の１つと同じサイズであるべきです。 しかし、CustomItem がその要素のビューポートより大きい内容を持っているかもしれません。あるいは、それがどのような内部の構造も持っていない内容があるかもしれません。 このような場合のどちらかでは、Item はユーザーが参照するために重要な内容領域の意図を最もよく表す矩形を返すべきです。 トラバースが起こると、ビューポート・サイズに基づく量に従って、Item はトラバース位置を移動させるべきです。 例えば、ビューポートの高さが 80 ピクセルであり、トラバースが下向きに起こるなら、Item は内容の次の画面分の表示をするために、前後関係を示す 10 ピクセルをオーバーラップさせ、トラバース位置を 70 ピクセル下げるかもしれません。

実装がどのトラバース・モードを提供するかに関らず、全ての内部のトラバース位置に到達するに違いありません。 これは、もし実装が一次元のトラバースを提供するならば、CustomItem がその内部の位置を線にしなければならないことを意味します。 例えば、トラバース・モードが TRAVERSE_VERTICAL であり、CustomItem が水平な列の要素から構成されると仮定してください。 トラバース方向が DOWN であるなら、内部のトラバース位置は右に動くべきです。そして、トラバース方向が UP であるなら、内部のトラバース位置は左に動くべきです（左から右へのテキストを使用する言語に以上の慣例は適切です。反対の慣例は右から左へのテキストを使用する言語に使用すべきです）。 トラバース・モードが TRAVERSE_VERTICAL で CustomItem の要素が格子から構成されるような例を考えてください。 DOWN のトラバース方向は各列の向こう側へ左向きに続くかもしれません。位置が、並んでいる一番右の要素に達すると、下向きに次の列に移動します。

実装が二次元トラバースを提供するものの、CustomItem が一次元であるなら、Item の軸に沿ったトラバース方向ならば Item の中をトラバースすべきです。また、Item の軸と直行するトラバース方向の場合は、このメソッドから false で戻ることによって、即座に Item からトラバースを外に出すべきです。 例えば、CustomItem が要素の垂直な堆積（スタック）を実装していて、Item の中にトラバースが既にあると仮定してください。 トラバース・イベントでトラバース方向として UP または DOWN を受け取ったなら、traverse() メソッドは次の要素に移動して true を返すべきです。 他方では、トラバース・イベントでトラバース方向として RIGHT または LEFT を受け取ったなら、traverse() メソッドは常に false を返すべきで、その結果トラバースはすぐに Item の外に出ます。 内部のトラバースを実装する Item は常にトラバースを受け入れるべきです。すなわち、traverse() への初期の呼び出しは、トラバース方向の軸に関らず true を返すべきです。

トラバースが Item に入っているとき、traverse() メソッドが false を返すなら、これは Item が内部のトラバースをサポートしないことをシステムに示します。 このような場合、Item はそれ自身のハイライトを何も実施すべきではなく、システムはプラットフォームに適切なハイライトをアイテムの外側に実施するでしょう。

デフォルトの traverse() メソッドの実装は常に false を返します。

パラメータ:

dir - トラバース方向として Canvas.UP、Canvas.DOWN、Canvas.LEFT、Canvas.RIGHT または NONE のいずれか１つが渡されます。

viewportWidth - コンテナのビューポートの幅が渡されます。

viewportHeight - コンテナのビューポートの高さが渡されます。

visRect_inout - メソッドの呼び出し時に可視状態の矩形が渡されます。メソッドの中でトラバース矩形に更新して返します。

戻り値:

内部でトラバースが起こったなら true を、トラバースが外へ続くなら false を返します。

関連項目:

getInteractionModes(), traverseOut(), TRAVERSE_HORIZONTAL, TRAVERSE_VERTICAL

traverseOut

protected void traverseOut()

トラバースがこのアイテムの外に出たときにシステムによって呼び出されます。 これは直前の traverse() に対する呼び出しが false を返した CustomItem に応じて起こるかもしれません。また、ユーザーが別の Item と対話を開始するか、この Item を含む Form がカレントではなくなった場合も同様です。 CustomItem が内部のトラバースを示すのにハイライトを使用しているなら、CustomItem は、状態を非ハイライトに設定し、再描画を要求すべきです（Item が既に不可視の場合には描画が発生しないことに注意してください）。

関連項目:

getInteractionModes(), traverse(int, int, int, int[]), TRAVERSE_HORIZONTAL, TRAVERSE_VERTICAL

keyPressed

protected void keyPressed(int keyCode)

キーが押された時にシステムによって呼ばれます。 実装は getInteractionModes メソッドで返す値に KEY_PRESS ビットをセットすることで、キー押下イベントの通知をサポートすることを示します。

パラメータ:

keyCode - 押されたキーに対応するキー・コードが渡されます。

関連項目:

getInteractionModes()

keyReleased

protected void keyReleased(int keyCode)

キーが離された時にシステムによって呼ばれます。 実装は getInteractionModes メソッドで返す値に KEY_RELEASE ビットをセットすることで、キー開放イベントの通知をサポートすることを示します。

パラメータ:

keyCode - 離されたキーに対応するキー・コードが渡されます。

関連項目:

getInteractionModes()

keyRepeated

protected void keyRepeated(int keyCode)

キー・リピートが発生した時にシステムによって呼ばれます。 実装は getInteractionModes メソッドで返す値に KEY_REPEAT ビットをセットすることで、キー・リピート・イベントの通知をサポートすることを示します。

パラメータ:

keyCode - リピートが発生したキーに対応するキー・コードが渡されます。

関連項目:

getInteractionModes()

getGameAction

public int getGameAction(int keyCode)

デバイスに割り当てられているキー・コードに対応するゲーム・アクションを返します。 全てのゲーム・アクションがキー・コードに対応していないのであればゼロ（0）を返します。 ゲーム・アクションの詳細な議論については Canvas クラスのゲーム・アクションを参照してください。

ゲーム・アクションへのキー・コードに対するマッピングは CustomItem と Canvas の間で異なることがあります。

パラメータ:

keyCode - キー・コードを渡します。

戻り値:

このキーに対応するゲーム・アクション、または対応するゲーム・アクションがなければ 0 を返します。

例外:

IllegalArgumentException - keyCode が有効なキー・コードではない場合に throw します。

pointerPressed

protected void pointerPressed(int x,
                              int y)

ポインタ・ダウン・アクション（例えばペンでタップ）が Item の中で起こった時にシステムによって呼ばれます。 (x, y) 座標は Item を基点とした相対座標です。そして、それは常に Item の中の位置を示します。 実装は getInteractionModes メソッドで返す値に POINTER_PRESS ビットをセットすることで、ポインタ・ダウン・イベントの通知をサポートすることを示します。

パラメータ:

x - ポインタダウンしたＸ座標が渡されます。

y - ポインタダウンしたＹ座標が渡されます。

pointerReleased

protected void pointerReleased(int x,
                               int y)

ポインタ・ダウン・アクションが Item の中で起こった後に、ポインタ・アップ・アクション（例えばペンの浮上）が起こった時にシステムによって呼ばれます。 (x, y) 座標は Item を基点とした相対座標です。 リリースが起こった時にポインタが Item の外へ移動していたとしても、実装はポインタ・リリース・イベントを Item に通知すべきです。 このような場合、(x, y) 座標は Item の領域外の位置を示すかもしれません。 実装は getInteractionModes メソッドで返す値に POINTER_RELEASE ビットをセットすることで、ポインタ・アップ・イベントの通知をサポートすることを示します。

パラメータ:

x - ポインタ・アップしたＸ座標が渡されます。

y - ポインタ・アップしたＹ座標が渡されます。

pointerDragged

protected void pointerDragged(int x,
                              int y)

ポインタ・ドラッグ・アクション（例えばペンを下ろした後、ペンを浮上させる前にペンを動かす）が起こった時にシステムによって呼ばれます。 (x, y) 座標は Item を基点とした相対座標です。 ポインタが Item の外へ動かされたとしても、実装はポインタ・ドラッグ・イベントを Item に通知すべきです。 このような場合、(x, y) 座標は Item の領域外の位置を示すかもしれません。 実装は getInteractionModes メソッドで返す値に POINTER_DRAG ビットをセットすることで、ポインタ・ドラッグ・イベントの通知をサポートすることを示します。

パラメータ:

x - ポインタ・ドラッグしたＸ座標が渡されます。

y - ポインタ・ドラッグしたＹ座標が渡されます。

showNotify

protected void showNotify()

Item が以前完全に目に見えなかった時に、現在少なくとも部分的に目に見えることを通知するためにシステムによって呼ばれます。 showNotify() が呼び出された後に Item は paint() の呼び出しを受け取るかもしれません。

このメソッドのデフォルトの実装は何も処理を行いません。

hideNotify

protected void hideNotify()

Item が以前少なくとも部分的に目に見えていた時に、現在完全に目に見えないことを通知するためにシステムによって呼ばれます。 hideNotify() が呼び出された後に Item が paint() の呼び出しを受け取ることは全くないでしょう。

このメソッドのデフォルトの実装は何も処理を行いません。