javax.microedition.lcdui
クラス Canvas

java.lang.Object
  javax.microedition.lcdui.Displayable
      javax.microedition.lcdui.Canvas

直系の既知のサブクラス:

GameCanvas

public abstract class Canvas
extends Displayable

Canvas クラスは低レベル・イベントの取り扱いおよびディスプレイへグラフィックスの描画を行う必要のあるアプリケーションを記述するための基底クラスです。 おそらくゲーム・アプリケーションは Canvas クラスを非常によく使用するでしょう。 アプリケーションは Canvas クラスを他の標準 Screen クラスと置き換え可能であるため、アプリケーション開発者の考え方によっては必要に応じて Canvas を高レベル・スクリーンと組み合わせて使用することができます。

例えばレーシング・ゲームにおいて、List スクリーンはコースを選択するために使用し、Canvas サブクラスは実際のゲームを実装するのに使用するでしょう。

Canvas はゲーム・イベント、キー・イベントおよび（デバイスによってサポートされるなら）ポインタ・イベントを扱うメソッドを開発者に提供します。 また、デバイスに依存する識別情報とキーをゲーム・アクションにマッピングためのメソッドを提供します。 キー・イベントは、デバイスに依存するキー・コードで通知されます。 実際のキー配置はデバイスに依存するため、特定のキー配置を期待すると他の環境に対するアプリケーションの移植性（機能性）を損ないます。 移植性を持ったアプリケーションを開発するためには、キー・コードの代わりにゲーム・アクションを使用すべきです。

他の Displayable クラスからの派生クラスと同様に、Canvas クラスにはアプリケーションが Command に対するリスナーを登録できます。 しかし、他の Displayable クラスからの派生クラスとは異なり、Canvas クラスはアプリケーションによる派生クラスを必要とします。 paint() メソッドは abstract 宣言されており、アプリケーションはその派生クラスでメソッドをオーバーライドして実装を提供しなければなりません。 その他のイベントを受け取るメソッドは abstract 宣言されておらず、デフォルトの実装では「空」になっています（つまりデフォルトではイベントに対して何も処理を行いません）。 これによりアプリケーションが、必要とするイベントを報告するメソッドだけをオーバーライドして実装することが可能になります。

これは Screen クラスから派生したクラスで行われている、アプリケーションがリスナーを実装し Screen クラスから派生したクラスのインスタンスでそれらを登録してイベントを処理するという方法とは対照的です。 イベントごとに対応したリスナー・インタフェースを作成する必要があり、Canvas クラスで必要とされるスタイルではないため、この方法は使用しません。 これに対する代案としては、より少数のリスナー・インタフェースを定義する方法が考えられます。 しかし、この方法は少数にまとめられたリスナー・インタフェースに対して必要のないイベントを取捨選択する実装を要求するという問題があります。

キー・イベント

アプリケーションはキーストローク・イベントが発生すると Canvas クラスで定義された定数に対応するキー・コードを受け取ることができます。イベントで MIDP アプリケーションに報告されるすべてのキーは、キー・コードが割り当てられています。２つ（あるいはそれ以上）のキーが互いに明らかに同じでない限り、キー・コードの値は個々のハードウェア・キーに対して固有となります。

MIDP は以下のキー・コードを定義します：
KEY_NUM0, KEY_NUM1, KEY_NUM2, KEY_NUM3, KEY_NUM4, KEY_NUM5, KEY_NUM6, KEY_NUM7, KEY_NUM8, KEY_NUM9, KEY_STAR, および KEY_POUND.
（これらのキー・コードは ITU-T 標準規格電話キーパッドのキーと一致しています。）

その他にもキーが存在する可能性があり、一般的にそれらのキーはそれぞれに対応するリスト定義と個別のキー・コードを持ちます。 移植性を保つために、アプリケーションは標準で規定されているキー・コードだけを使用すべきです。

MIDP 標準規格のキー・コード値は、キーが表している文字コード（Unicode）と等しくなっています。 もし、デバイスが明らかに一致する Unicode 文字を持つべきキーを複数持っている場合、それらのキー・コード値はその文字のための Unicode と等しいでしょう。 対応した Unicode 文字をまったく持たないキーのために、実装は負数のキー・コードを用いなければなりません。 ゼロ (0) は、不正なキー・コードであると定義されます。

従って、アプリケーションが以下のコードを使って keyCode を Unicode 文字に変換することが可能です：

     if (keyCode > 0) {
         char ch = (char)keyCode;        
         // ...    
     }

この手法は、一部の制限された事例でのみ意味を持ちます。 特に完全なテキスト入力に対して十分ではありません。 なぜなら、それは複数のストロークを要するような文字入力、例えば小文字や日本語の文字などに対応できないためです。 テキストの入力のためには、アプリケーションは常に TextBox クラスまたは TextField クラスを使用すべきです。

場合によっては通知されたキーを表示するためにキーの名称を知る必要があります。 このような場合は、アプリケーションはキーの名称を得るために、getKeyName(int) メソッドを使用します。

ゲーム・アクション

方向キー・イベントおよびゲーム関連のキー・イベントが必要な移植性のあるアプリケーションを記述するためには、キー・コードとキー名より優先してゲーム・アクションを使用すべきです。

MIDP は以下のゲーム・アクションを定義します：
UP, DOWN, LEFT, RIGHT, FIRE, GAME_A, GAME_B, GAME_C, および GAME_D。

個々のキー・コードのほとんどはゲーム・アクションにマップされます。 しかし、ゲーム・アクションは複数のキー・コードにマップされることがあります。 アプリケーションは、getGameAction(int keyCode) メソッドを使用して、キー・コードをゲーム・アクションに変換できます。 同様に、getKeyCode(int gameAction) メソッドを使用してゲーム・アクションをキー・コードに変換することができます。 特定のゲーム・アクションに対応する複数のキー・コードが存在することもありえますが、getKeyCode(int) はそれらの１つだけを返します。 g が有効なゲーム・アクションであり、k がゲーム・アクションに関連しているキーのための有効なキー・コードであると仮定し、以下の式を見てください：

 g == getGameAction(getKeyCode(g))     // (1)
 k == getKeyCode(getGameAction(k))     // (2)

式 (1) は常に true です。 これに対して、式 (2) は true であるかもしれませんが、常に true というわけではありません。

実装は、アプリケーション実行中にゲーム・アクションとキー・コードの対応表を変更してはなりません。

ゲーム・アクションを使用して移植性のあるアプリケーションを書くためには、全てのキー・イベントにおいて getGameAction() メソッドを呼び、その結果を判定することによって次のゲーム上の動作を決めるべきです。 例えば、デバイスによっては、ゲーム・アクションの UP、DOWN、LEFT および RIGHT が 4 方向ナビゲーション矢印キーに割り当てられます。 このケースにおいて、getKeyCode(UP) は矢印キーアップのためのデバイス依存のキー・コードを返します。 他のデバイスでは、それぞれ 2、4、6 および 8 キーに割り当てが行われることがあります。 このケースにおいて、getKeyCode(UP) はキー・コードとして KEY_NUM2 を返します。 どちらの実装であっても、ユーザーがデバイスの自然に「左」を意味すると考えることのできるキーを押すと、getGameAction() メソッドはゲーム・アクションとして LEFT を返します。

コマンド

カレントに設定されている Canvas クラスの派生クラスは、ユーザーが Command を呼び出すことができます。 Command はデバイスに適合する方法でキーあるいはメニューに割り当てられます。 デバイスによっては Command に割り当てられたキー・コードと Canvas へ送るキー・コードとが重なることがあります。 このような場合、デバイスはこれらのキーがコマンドあるいはキー・コード・イベントとしてアプリケーションに通知するか否かを決定するアプリケーションに透過なモードを選択する手段を提供するでしょう。 Canvas がノーマル・モード（下記参照）である場合、現在のコマンドの数あるいはコマンド・リスナーの存在によって Canvas で使用可能なキー・コード・イベントのセットは変化しないでしょう。 Canvas がフルスクリーン・モードである場合、コマンド・リスナーが設定されていなければ、デバイスは Command を呼び出すために予約されているキーのために、キー・コード・イベントを発生させることを選択するかもしれません。 ゲーム開発者はデバイスによってコマンドのアクセス方法が大きく異なり、ゲームのプレイ中に Command を出すことをユーザに要求することが、操作性に大きな影響を及ぼす可能性があることを意識すべきです。

イベント・デリバリ

Canvas オブジェクトは、実装によって呼ばれるいくつかのメソッドを定義しています。これらのメソッドはイベントをアプリケーションに通知するために存在し、イベント・デリバリ・メソッドとして使用されます。

定義されているメソッドは以下のとおりです：
showNotify()、 hideNotify()、 keyPressed()、 keyRepeated()、 keyReleased()、 pointerPressed()、 pointerDragged()、 pointerReleased()、 paint paint() および CommandListener の commandAction() メソッド。

これらのメソッドすべては連続的（シリアル）に呼び出します。 すなわち、イベント・デリバリ・メソッドのうちのいずれかへの事前の呼び出しから制御が返る前に、実装は決して次のイベント・デリバリ・メソッドを呼び出しません。 serviceRepaints() メソッドがこの規則への例外であり、paint() を呼び出して制御が戻るまでブロックします。 serviceRepaints() を呼び出すときに、アプリケーションがイベント・デリバリ・メソッドの処理中であったとしてもこれが発生します。

イベント・ストリームの中で、いくつかのアプリケーション定義の処理を連続して行うために、Display.callSerially() メソッドを使用することができます。 詳しくはパッケージ概要のイベントの取り扱いおよび並行処理セクションを参照してください。

Canvas がディスプレイに表示されている間に限り、キー関連、ポインタ関連および paint() メソッドは呼び出されます。 したがって、Canvas オブジェクトのこれらのメソッドが呼び出されるのは、showNotify() の呼び出しから hideNotify() が呼び出される前までです。 hideNotify() が呼び出された後、次に showNotify() が呼び出されてその制御が戻るまで、キー、ポインタおよび paint() メソッドのいずれも呼び出されることはありません。 callSerially() の呼び出しによる run() メソッドの呼び出しは showNotify() および hideNotify() の呼び出しに関りなく行われる可能性があります。

showNotify() メソッドは、実際にディスプレイに表示される前に先駆けて呼び出され、hideNotify() メソッドはディスプレイに表示されなくなった後に呼び出されます。 Canvas クラス（または、どのような他の表示可能なオブジェクトでも）の表示状態は、Displayable.isShown() メソッドで取得することができます。 Canvas クラスの表示状態の変化は、フォアグラウンドあるいはバックグラウンドの状態変化、MIDlet アプリケーション管理ソフトの動作、あるいはシステム・スクリーンで Canvas が覆い隠された場合などに起こされる可能性があります。 このため、showNotify() メソッドと hideNotify() メソッドへの呼び出しは MIDlet でコントロールしていない場合にも、かなり頻繁に行われる可能性があります。 アプリケーション開発者はそれらをできる限り軽量にするため、showNotify() メソッドおよび hideNotify() メソッドの外に（処理に時間のかかる）初期設定処理および終了処理を記述するように推奨します。

Canvas はノーマル・モードあるいはフルスクリーン・モードになることができます。 ノーマル・モードでは、ディスプレイ上のスペースがコマンドラベル、タイトルおよびティッカーによって占有されることがあります。 Canvas をフルスクリーン・モードに設定することにより、アプリケーションは Canvas ができる限り多くの表示スペースを要求することができます。 フルスクリーン・モードでは、それらが Canvas に存在していたとしても、タイトルとティッカーを表示せずに、いくつかの代替手段（ポップアップ・メニューなど）を用いてコマンドの呼び出しを可能にするかもしれません。 表示されている Canvas がフルスクリーン・モードであったとしても、実装がステータス・インジケータのようなもののためにディスプレイの一部を消費しているかもしれないことに注意が必要です。 フルスクリーン・モードではタイトルを表示しませんが、コマンドのポップアップ・メニューのタイトルのような他の目的には指定されたテキストを使用する可能性があります。

Canvas オブジェクトはデフォルトでノーマル・モードです。 ノーマル及びフルスクリーン・モードの設定は setFullScreenMode(boolean) メソッドの呼び出しで制御します。

setFullScreenMode(boolean) メソッドを呼び出した結果、sizeChanged() の呼び出しが発生するかもしれません。 このメソッドのデフォルト実装は何も処理を行いません。 アプリケーションは使用可能な描画領域のサイズ変化を扱うこのメソッドをオーバーライドすることができます。

注意：概要の"仕様上の要求事項"で言及されているように、実装はネットワークの使用に関する表示をユーザーに提供しなければなりません。 インジケータをスクリーンに描画するならば、ネットワーク活動を行う際に Canvas がフルスクリーン・モードであったとしても、表示が行われるでしょう。

導入されたバージョン:

MIDP 1.0

UP

public static final int UP

ゲーム・アクションの上を示す定数（=1）です。

関連項目:

定数フィールド値

DOWN

public static final int DOWN

ゲーム・アクションの下を示す定数（=6）です。

関連項目:

定数フィールド値

LEFT

public static final int LEFT

ゲーム・アクションの左を示す定数（=2）です。

関連項目:

定数フィールド値

RIGHT

public static final int RIGHT

ゲーム・アクションの右を示す定数（=5）です。

関連項目:

定数フィールド値

FIRE

public static final int FIRE

ゲーム・アクションの FIRE を示す定数（=8）です。

関連項目:

定数フィールド値

GAME_A

public static final int GAME_A

ゲーム・アクションの汎用ボタン A を示す定数（=9）です。

関連項目:

定数フィールド値

GAME_B

public static final int GAME_B

ゲーム・アクションの汎用ボタン B を示す定数（=10）です。

関連項目:

定数フィールド値

GAME_C

public static final int GAME_C

ゲーム・アクションの汎用ボタン C を示す定数（=11）です。

関連項目:

定数フィールド値

GAME_D

public static final int GAME_D

ゲーム・アクションの汎用ボタン D を示す定数（=12）です。

関連項目:

定数フィールド値

KEY_NUM0

public static final int KEY_NUM0

ITU-T 定義０キーのキー・コードを示す定数（=48）です。

関連項目:

定数フィールド値

KEY_NUM1

public static final int KEY_NUM1

ITU-T 定義１キーのキー・コードを示す定数（=49）です。

関連項目:

定数フィールド値

KEY_NUM2

public static final int KEY_NUM2

ITU-T 定義２キーのキー・コードを示す定数（=50）です。

関連項目:

定数フィールド値

KEY_NUM3

public static final int KEY_NUM3

ITU-T 定義３キーのキー・コードを示す定数（=51）です。

関連項目:

定数フィールド値

KEY_NUM4

public static final int KEY_NUM4

ITU-T 定義４キーのキー・コードを示す定数（=52）です。

関連項目:

定数フィールド値

KEY_NUM5

public static final int KEY_NUM5

ITU-T 定義５キーのキー・コードを示す定数（=53）です。

関連項目:

定数フィールド値

KEY_NUM6

public static final int KEY_NUM6

ITU-T 定義６キーのキー・コードを示す定数（=54）です。

関連項目:

定数フィールド値

KEY_NUM7

public static final int KEY_NUM7

ITU-T 定義７キーのキー・コードを示す定数（=55）です。

関連項目:

定数フィールド値

KEY_NUM8

public static final int KEY_NUM8

ITU-T 定義８キーのキー・コードを示す定数（=56）です。

関連項目:

定数フィールド値

KEY_NUM9

public static final int KEY_NUM9

ITU-T 定義９キーのキー・コードを示す定数（=57）です。

関連項目:

定数フィールド値

KEY_STAR

public static final int KEY_STAR

ITU-T 定義＊キーのキー・コードを示す定数（=42）です。

関連項目:

定数フィールド値

KEY_POUND

public static final int KEY_POUND

ITU-T 定義＃キーのキー・コードを示す定数（=35）です。

関連項目:

定数フィールド値

Canvas

protected Canvas()

新しい Canvas クラスのオブジェクトを構築します。

getWidth

public int getWidth()

Canvas の表示可能領域の幅（ピクセル数）を返します。 返す値はアプリケーションの実行中に変化することがあります。 このような場合は sizeChanged(int, int) メソッドを呼び出してアプリケーションに通知を行います。

オーバーライド:

クラス Displayable 内の getWidth

戻り値:

表示可能領域の幅（単位：ピクセル数）を返します。

getHeight

public int getHeight()

Canvas の表示可能領域の高さ（ピクセル数）を返します。 返す値はアプリケーションの実行中に変化することがあります。 このような場合は sizeChanged(int, int) メソッドを呼び出してアプリケーションに通知を行います。

オーバーライド:

クラス Displayable 内の getHeight

戻り値:

表示可能領域の高さ（単位：ピクセル数）を返します。

isDoubleBuffered

public boolean isDoubleBuffered()

ダブル・バッファによるグラフィック描画が実装されているかどうかチェックします。

戻り値:

true ならばダブル・バッファ、false ならばそうではありません。

hasPointerEvents

public boolean hasPointerEvents()

プラットフォームがポインタの押し離しイベントをサポートしているかどうかチェックします。

戻り値:

true ならばポインタ・イベントをサポートしているデバイスです。

hasPointerMotionEvents

public boolean hasPointerMotionEvents()

プラットフォームがポインタ移動イベント（ポインタ・ドラッグ）をサポートしているか否かをチェックします。 アプリケーションはプラットフォームが移動イベントをサポートしている可能性があるか否かを確定するためにこのメソッドを用いることができます。

戻り値:

true ならばポインタ移動イベントをサポートしているデバイスです。

hasRepeatEvents

public boolean hasRepeatEvents()

プラットフォームがキーが押されつづけるときにキー・リピート・イベントを生成するか否かをチェックします。

戻り値:

true ならばリピート・イベントをサポートしているデバイスです。

getKeyCode

public int getKeyCode(int gameAction)

指定されたゲーム・アクションに対応する、このデバイスのキー・コードを返します。 実装は、ゲーム・アクションごとに１つの対応するキー・コードを提供します。 このため、指定されたゲーム・アクションに対応する常に有効なキー・コードを返します。 ゲーム・アクションの詳細は上記を参照してください。 同じゲーム・アクションが複数のキー・コードに対応している場合があります。 しかし、このメソッドはそれらのうちの１つだけを返します。 アプリケーションは初期化の際にこのメソッドを使用してキー・コードのテーブルを生成するのではなく、あらゆるキー・イベントのキー・コードを getGameAction(int) でゲーム・アクションに変換し、結果として返されたゲーム・アクションを解釈すべきです。

キー・コードとゲーム・アクションの間の対応表はアプリケーションの実行中に変わる事はありません。

パラメータ:

gameAction - 対象のゲーム・アクションを渡します。

戻り値:

ゲーム・アクションと一致しているキー・コードを返します。

例外:

IllegalArgumentException - もし gameAction が有効なゲーム・アクションでないならば throw します。

getKeyName

public String getKeyName(int keyCode)

キー・コードに対応する情報文字列を取得します。 返す文字列は、キーに物理的に印刷されたテキストと同じか近いものになります。 この文字列はユーザーに表示するのに適しています。 例えば F1 から F4 までのファンクションキーを持つデバイスにおいて、F1 キーに対応する keyCode から、このメソッドを呼び出して「F1」という文字列を得ることができます。 この文字列の典型的な用途は「開始するには F1 キーを押してください。」といったヘルプメッセージを作成することにあります。

このメソッドは１つの有効なキー・コードごとに１つの空ではない文字列を返します。

ゲーム・アクションからキーの名称を直接得ることはできません。 ゲーム・アクションからキーの名称を得る場合はアプリケーションから、

    getKeyName(getKeyCode(GAME_A))

のように呼び出します。

パラメータ:

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

戻り値:

キー名称の入った文字列を返します。

例外:

IllegalArgumentException - キー・コードが不正だった場合に throw します。

getGameAction

public int getGameAction(int keyCode)

デバイスと関連するキー・コードをゲーム・アクションへ置き換えます。 もしもキー・コードがゲーム・アクションと関連しない場合は０となります。 詳しくは上記のゲーム・アクションに関する項目を参照してください。

キー・コードとゲーム・アクションの間の対応表はアプリケーションの実行中に変わる事はありません。

パラメータ:

keyCode - 置き換える対象のキー・コードを渡します。

戻り値:

キー・コードと一致しているゲーム・アクションあるいは一致するゲーム・アクションが無い場合は 0 を返します。

例外:

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

setFullScreenMode

public void setFullScreenMode(boolean mode)

Canvas をフルスクリーン・モードにするかノーマル・モードにするか制御します。

パラメータ:

mode - フルスクリーン・モードにする場合は true を、ノーマル・モードにする場合には false を渡します。

導入されたバージョン:

MIDP 2.0

keyPressed

protected void keyPressed(int keyCode)

キーが押されると実装によって呼び出されます。

キー・コードに対応するゲーム・アクションを確定させる必要がある場合は、getGameAction メソッドを呼び出します。

Canvas クラスはこのメソッドの空の実装を持ちます。 MIDlet アプリケーションがこのイベント情報を必要とするならば、このクラスを継承したサブクラスにおいてこのメソッドをオーバーライドして必要な処理を実装します。

パラメータ:

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

keyRepeated

protected void keyRepeated(int keyCode)

キーが押されつづけてキー・リピートが発生する場合に実装によって呼び出されます。

キー・コードに対応するゲーム・アクションを確定させる必要がある場合は、getGameAction メソッドを呼び出すことができます。

Canvas クラスはこのメソッドの空の実装を持ちます。 MIDlet アプリケーションがこのイベント情報を必要とするならば、このクラスを継承したサブクラスにおいてこのメソッドをオーバーライドして必要な処理を実装します。

パラメータ:

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

関連項目:

hasRepeatEvents()

keyReleased

protected void keyReleased(int keyCode)

キーが離されると実装によって呼び出されます。

キー・コードに対応するゲーム・アクションを確定させる必要がある場合は、getGameAction メソッドを呼び出すことができます。

Canvas クラスはこのメソッドの空の実装を持ちます。 MIDlet アプリケーションがこのイベント情報を必要とするならば、このクラスを継承したサブクラスにおいてこのメソッドをオーバーライドして必要な処理を実装します。

パラメータ:

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

pointerPressed

protected void pointerPressed(int x,
                              int y)

ポインタが押されると実装によって呼び出されます。

デバイスがポインタ・イベントをサポートするか否かを確定するために hasPointerEvents() メソッドを呼び出すことができます。

Canvas クラスはこのメソッドの空の実装を持ちます。 MIDlet アプリケーションがこのイベント情報を必要とするならば、このクラスを継承したサブクラスにおいてこのメソッドをオーバーライドして必要な処理を実装します。

パラメータ:

x - ポインタが押された水平位置がキャンバス内の相対位置で渡されます。

y - ポインタが押された垂直位置がキャンバス内の相対位置で渡されます。

関連項目:

hasPointerEvents()

pointerReleased

protected void pointerReleased(int x,
                               int y)

ポインタが離されたときに実装によって呼び出されます。

デバイスがポインタ・イベントをサポートするか否かを確定するために hasPointerEvents() メソッドを呼び出すことができます。

Canvas クラスはこのメソッドの空の実装を持ちます。 MIDlet アプリケーションがこのイベント情報を必要とするならば、このクラスを継承したサブクラスにおいてこのメソッドをオーバーライドして必要な処理を実装します。

パラメータ:

x - ポインタが離された水平位置がキャンバス内の相対位置で渡されます。

y - ポインタが離された垂直位置がキャンバス内の相対位置で渡されます。

関連項目:

hasPointerEvents()

pointerDragged

protected void pointerDragged(int x,
                              int y)

ポインタがドラッグされたときに実装によって呼び出されます。

デバイスがポインタ・イベントをサポートするか否かを確定するために hasPointerEvents() メソッドを呼び出すことができます。

Canvas クラスはこのメソッドの空の実装を持ちます。 MIDlet アプリケーションがこのイベント情報を必要とするならば、このクラスを継承したサブクラスにおいてこのメソッドをオーバーライドして必要な処理を実装します。

パラメータ:

x - ポインタがドラッグされた水平位置がキャンバス内の相対位置で渡されます。

y - ポインタがドラッグされた垂直位置がキャンバス内の相対位置で渡されます。

関連項目:

hasPointerEvents()

repaint

public final void repaint(int x,
                          int y,
                          int width,
                          int height)

スクリーンの指定された領域の再描画要求を行います。

このメソッドを呼び出すと、Graphics オブジェクトにクリップ領域を設定し paint() メソッドを呼び出すことにつながります。

もし、Canvas が非表示状態かクリップ領域の幅と高さが０以下であるか、または矩形がディスプレイの可視の領域を指していないのであれば、この呼び出しは何も行いません。

paint() への呼び出しは repaint() の呼び出しとは関係なく（非同期に）発生します。 すなわち、repaint() は paint() 処理が終わるまで待機しません。 repaint() の呼び出し元が実装（呼び出し元がコールバックであるなら）か別のスレッドへ完全に復帰してから paint() メソッドは呼び出されます。

アプリケーションは paint() メソッドと連動するために、Display.callSerially() あるいは serviceRepaints() を用いることができます。また、これらは明示的な同期を paint() ルーチンに記述することができます。

再描画の原点座標は左上となり、幅は右に向かって増加、高さは下に向かって増加します。

パラメータ:

x - 再描画を開始する矩形の開始 X 座標を渡します。

y - 再描画を開始する矩形の開始 Y 座標を渡します。

width - 再描画する矩形の幅を渡します。

height - 再描画する矩形の高さを渡します。

関連項目:

Display.callSerially(Runnable), serviceRepaints()

repaint

public final void repaint()

Canvas 全体の再描画を要求します。 このメソッドの呼び出しは以下の呼び出しと等価です。

repaint(0, 0, getWidth(), getHeight());

serviceRepaints

public final void serviceRepaints()

直ちに未処理の再描画要求を処理することを要求します。 未処理の再描画要求がすべて処理されるまで呼び出し元に制御は戻りません（ブロックします）。 未処理の再描画要求が存在しなかったり Canvas が画面上に表示されていない場合にはこの呼び出しは何もせずに戻ります。

警告:このメソッドはアプリケーションの paint() メソッドの呼び出しが戻るまでブロックします。 アプリケーションはどのスレッドが paint() メソッドを呼び出すか管理できません。 それは異なる実装によって変わる可能性があります。 したがって、serviceRepaints() メソッドの呼び出し元は paint() メソッドの中で使用されるかもしれないロックを保持してはなりません。 デッドロックの危険性を回避して描画が終了したあとにアプリケーションをコールバックするために、Display.callSerially() メソッドが提供されています。

関連項目:

Display.callSerially(Runnable)

showNotify

protected void showNotify()

実装は Canvas がディスプレイ上に表示される直前に showNotify メソッドを呼び出します。 Canvas クラスから派生したアプリケーションのクラスでは、タイマーやアニメーションをセットアップするなどの処理を表示開始の前に行うためにこのメソッドを使用することができます。 Canvas クラスのこのメソッドのデフォルトの実装は空です。

hideNotify

protected void hideNotify()

実装は Canvas がディスプレイの表示対象から外れた直後に hideNotify() メソッドを呼び出します。 Canvas クラスから派生したアプリケーションのクラスでは、タイマーやアニメーションを停止したりポーズするなどの処理を行うためにこのメソッドを使用することができます。 Canvas クラスのこのメソッドのデフォルトの実装は空です。

paint

protected abstract void paint(Graphics g)

Canvas を描画します。

アプリケーションは任意のグラフィックを描画するためにこのメソッドを実装しなければなりません。

Graphics オブジェクトのクリップ領域は無効と考えられるスクリーン上のエリアを定義しています。 正しく書かれた paint() メソッドはこの領域内のすべてのピクセルを描画しなければなりません。 アプリケーションはクリップ領域内の部分的な描画を行うために、paint() メソッドの呼び出しの要因を考慮したり Canvas に描画済みの仮定を行ってはなりません。 それは当該の paint() メソッドの呼び出しが複数の再描画要求に起因する可能性があるためです。 また、そのうちのいくつかはアプリケーションの外で生成されたものかもしれません。 例えば、スクリーンに表示されている内容が通話によって無効にされた場合、アプリケーションが必要と仮定した内容だけを描画すると描画結果は不適切なものになる可能性があります。

paint() メソッドの呼び出し時に渡される Graphics オブジェクトは paint() メソッド内でのみ有効です。 その後の Graphics オブジェクトに対するオペレーションの実行結果は不確定です。 このため、アプリケーションは paint() メソッドの呼び出し時に渡された Graphics オブジェクトを保存して、paint() メソッドの外で使用してはなりません。

実装は paint() メソッドの終了まで描画操作の可視化を延期することがあります。

Canvas が非表示になった後、次に再び表示状態になる場合、Canvas の描画内容は保存されていません。 したがって、showNotify() メソッドが呼ばれた直後、paint() メソッドはクリップ領域が Canvas の表示可能領域全体に指定された Graphics オブジェクトで常に呼ばれるでしょう。 アプリケーションは前回の最新描画結果に依存してはなりません。 他のキー、ポインタ関係のメソッドおよび commandAction() メソッドの呼び出しの前に paint() メソッドが必ずしも呼び出されるとは限りません。 再描画個所の再計算が高価（＝高負荷）なアプリケーションはオフスクリーン・イメージを作成して、そこへ描画を行い、そして次に paint() メソッドが呼ばれる際に Canvas 上にこのイメージを描画することもできます。

アプリケーションのコードは paint() メソッドを呼び出してはなりません。このメソッドは実装によってのみ呼ばれます。

paint() メソッドに渡される Graphics オブジェクトは次の特性を持っています。

• 描画先は実際のディスプレイあるいはダブル・バッファリングのバック・バッファを指しています。
• クリップ領域は Canvas 内の少なくとも１ピクセルを含んでいます。
• デフォルト・カラーは黒です。
• フォントは Font.getDefaultFont() メソッドで返されるフォントと同じです。
• ストローク・スタイルは SOLID です。
• 座標系の原点は左上に位置します。
• Canvas は可視状態、つまり Displayable.isShown() メソッドが true を返す状態です。

パラメータ:

g - Canvas を描画するための Graphics オブジェクトが渡されます。

sizeChanged

protected void sizeChanged(int w,
                           int h)

Canvas の描画可能領域が変更された場合に呼び出します。 Displayable.sizeChanged(int, int) と比較して、このメソッドでは適用範囲が拡大されています。

Displayable.sizeChanged(int, int) に記載された原因に加えて、Canvas でのサイズの変化はノーマル及びフルスクリーン・モードの変化によって発生することがあります。

Canvas のサイズが変更された際に実際にディスプレイに表示されている場合、自動的に再描画のリクエストを発生させるトリガーとなるかもしれません。 このような場合、sizeChanged の呼び出しは paint() の呼び出しの前に行われます。 Canvas が変更前よりも小さくなり、Canvas に描画されている内容が保存されているならば、実装は再描画要求を出さない決定を下すかもしれません。 同様に、Canvas が変更前よりも大きくなり、Canvas に描画されている内容が保存されているならば、実装は新たな領域だけを再描画要求の対象とするかもしれません。 どちらの場合も、保存された内容は Canvas の原点座標に対して移動せずに残っていなければなりません。 サイズの変化が Canvas の内容にとって重要であるなら、アプリケーションで明示的に変更された領域に対する再描画を要求しなければなりません。 再描画の要求は既存の未解決の要求と一体化することができるため、アプリケーションの再描画要求が複数回の再描画を引き起こすべきではないことに注意してください。

Canvas が表示されていない状態でサイズが変更になる場合、実装は showNotify の直前まで sizeChanged の呼び出しを遅らせることを選択することができます。 この場合、サイズの変化の回数に関らず一度だけ sizeChanged を呼び出します。

サイズの変化に敏感なアプリケーションは、sizeChanged の実装でインスタンス変数をアップデートすることができます。 これらのアップデートした値は、showNotify()、hideNotify() および paint() によるコードで利用可能です。

オーバーライド:

クラス Displayable 内の sizeChanged

パラメータ:

w - Canvas の描画可能領域の新しい幅（ピクセル単位）が渡されます。

h - Canvas の描画可能領域の新しい高さ（ピクセル単位）が渡されます。

導入されたバージョン:

MIDP 2.0