javax.microedition.lcdui.game
クラス GameCanvas

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

public class GameCanvas
extends Canvas

GameCanvas クラスはゲーム向けユーザーインタフェースの基礎を提供します。 また、Canvas（コマンド、入力イベントなど）から引き継いだ特長に加えて、オフスクリーン・グラフィックス・バッファやキー状態取得などのゲーム特有の機能を提供します。

それぞれの GameCanvas インスタンスのために専用のバッファが作成されます。 それぞれの GameCanvas インスタンスに固有のバッファが提供されるため、ヒープ使用量を最小にするために１つの GameCanvas インスタンスを再利用することが望まれます。 開発者は、このバッファの中身が GameCanvas インスタンスから取得した Graphics オブジェクトへの呼び出しのみで変更されると仮定できます; 内容は他の MIDlet あるいはシステム・レベルの通知など外部要因によって変更されることはありません。 バッファは初期状態で白いピクセルでクリアされます。

バッファのサイズは GameCanvas の最大サイズによって決定します。 しかしながら、フラッシュが要求された時にフラッシュされるであろう領域は、GameCanvas（Ticker、Command などの存在によって影響を受けて）の現在のサイズによって制限されます。 GameCanvas の現在のサイズは getWidth と getHeight を呼び出すことによって得ることができます。

ゲームは、ゲーム・ループを動かすためにそれ自身のスレッドを提供するかもしれません。典型的なループ入力があるか否かをチェックし、ゲーム・ロジックを実装して、次に更新後のユーザーインタフェースをレンダリングするでしょう。 以下のコードは一般的なゲーム・ループの構造を例示します:

 // オフスクリーン・バッファへの Graphics オブジェクトの取得
 Graphics g = getGraphics();
 
 while (true) {
      // 必要に応じてユーザー入力と更新位置をチェック
      int keyState = getKeyStates();
      if ((keyState & LEFT_PRESSED) != 0) {
          sprite.move(-1, 0);
      }
      else if ((keyState & RIGHT_PRESSED) != 0) {
          sprite.move(1, 0);
      }
 
      // 白色に背景をクリア
      g.setColor(0xFFFFFF);
      g.fillRect(0,0,getWidth(), getHeight());
 
      // スプライトの描画
      sprite.paint(g);
 
      // オフスクリーン・バッファのフラッシュ
      flushGraphics();
 }

導入されたバージョン:

MIDP 2.0

UP_PRESSED

public static final int UP_PRESSED

↑キーを表現するビットです。 この定数には 0x0002(1 << Canvas.UP) の値が割り当てられています。

関連項目:

定数フィールド値

DOWN_PRESSED

public static final int DOWN_PRESSED

↓キーを表現するビットです。 この定数には 0x0040(1 << Canvas.DOWN) の値が割り当てられています。

関連項目:

定数フィールド値

LEFT_PRESSED

public static final int LEFT_PRESSED

←キーを表現するビットです。 この定数には 0x0004(1 << Canvas.LEFT) の値が割り当てられています。

関連項目:

定数フィールド値

RIGHT_PRESSED

public static final int RIGHT_PRESSED

→キーを表現するビットです。 この定数には 0x0020(1 << Canvas.RIGHT) の値が割り当てられています。

関連項目:

定数フィールド値

FIRE_PRESSED

public static final int FIRE_PRESSED

FIRE キーを表現するビットです。 この定数には 0x0100(1 << Canvas.FIRE) の値が割り当てられています。

関連項目:

定数フィールド値

GAME_A_PRESSED

public static final int GAME_A_PRESSED

GAME_A キー（全てのデバイスにおいてサポートされるわけではありません）を表現するビットです。 この定数には 0x0200(1 << Canvas.GAME_A) の値が割り当てられています。

関連項目:

定数フィールド値

GAME_B_PRESSED

public static final int GAME_B_PRESSED

GAME_B キー（全てのデバイスにおいてサポートされるわけではありません）を表現するビットです。 この定数には 0x0400(1 << Canvas.GAME_B) の値が割り当てられています。

関連項目:

定数フィールド値

GAME_C_PRESSED

public static final int GAME_C_PRESSED

GAME_C キー（全てのデバイスにおいてサポートされるわけではありません）を表現するビットです。 この定数には 0x0800(1 << Canvas.GAME_C) の値が割り当てられています。

関連項目:

定数フィールド値

GAME_D_PRESSED

public static final int GAME_D_PRESSED

GAME_D キー（全てのデバイスにおいてサポートされるわけではありません）を表現するビットです。 この定数には 0x1000(1 << Canvas.GAME_D) の値が割り当てられています。

関連項目:

定数フィールド値

GameCanvas

protected GameCanvas(boolean suppressKeyEvents)

GameCanvas の新しいインスタンスを作成します。 新しいバッファはそれぞれの GameCanvas のために作成され、初期状態で白色ピクセルにクリアされます。

開発者が getKeyStates メソッドを使用してキー・ステータスについて問い合わせをする必要があるだけならば、この GameCanvas が表示されている間、ゲーム・キーのために通常のキー・イベント・メカニズムを抑制することができます。 アプリケーションで必要としないのなら、キー・イベントの抑制は keyPressed、keyRepeated および keyReleased メソッドの不要なシステム・コールを排除することにより、性能を向上させることができるかもしれません。

もし要求したなら、キー・イベントの抑制は、指定の GameCanvas が表示される時（言い換えれば showNotify が呼ばれた時）に開始され、隠される時（言い換えれば hideNotify が呼ばれた時）に停止します。 スクリーンの表示と隠蔽（非表示）はイベント・キューに順番に並べられます。この整理により抑制の意図に対応する GameCanvas のために、それらのキー・イベントだけに効果を発揮することを確実にします。 したがって、別のスクリーンがまだ表示されている間にキー・イベントが発生すると、それらのキー・イベントは、そのスクリーンが隠蔽（非表示）されて、それが（該当する）GameCanvas に切り替えられるまで、キューに入れられて発信され続けます。

定義されたゲーム・キー（UP、DOWN、FIRE など）のためだけにキー・イベントを抑制できることに注意してください； キー・イベントは他の全てのキーのためにいつでも生成されます。

パラメータ:

suppressKeyEvents - ゲーム・キーのための通常のキー・イベント・メカニズムを抑制するならば true、そうでなければ false を渡します。

getGraphics

protected Graphics getGraphics()

GameCanvas にレンダリングするための Graphics オブジェクトを取得します。 返された Graphics オブジェクトは、この GameCanvas に属するオフスクリーン・バッファへのレンダリングを行います。

flushGraphics() が呼び出されるまで、レンダリング操作はディスプレイ上には現れません； バッファをフラッシュしても内容は変化しません（フラッシュ操作の結果としてピクセルのクリアは行われません）。

このメソッドが呼ばれるたびに、新しい Graphics オブジェクトを作成して返します。 したがって、ゲームのはじめの前に必要な Graphics オブジェクトを入手して、ゲームが動作している間はそのオブジェクトを再利用すべきです。 それぞれの GameCanvas インスタンスのために提供された Graphics オブジェクトの全てが同じオフスクリーン・バッファを提供するでしょう。

新たに作成された Graphics オブジェクトは以下の設定がなされています：

• 描画対象はこの GameCanvas のバッファです；
• クリップ領域はバッファ全体を包含します；
• 現在の色は黒です；
• フォントは Font.getDefaultFont() で返されるフォントと同一です；
• ストローク・スタイルは SOLID です；
  そして
• 座標系の原点はバッファの左上角に位置しています。

戻り値:

GameCanvas のオフスクリーン・バッファにレンダリングするための Graphics オブジェクトを返します。

関連項目:

flushGraphics(), flushGraphics(int, int, int, int)

getKeyStates

public int getKeyStates()

物理的なゲーム・キーの状態を取得します。 返す整数における各ビットはデバイスにおける特定のキーに対応します。 このメソッドが最後に呼ばれてから少なくとも一度は押されたか、あるいは現在押下されているキーのビットは 1 になります。 このメソッドが最後に呼ばれてから一度も押されていないか、あるいは現在押下されていないキーのビットは 0 になります。 このラッチ・ビヘイビア（１度の反応を維持し続ける振る舞い）は、急速なキーの押し・離しが、ループが如何にゆっくり動くかに関わらず、常にゲーム・ループによって検出されることを確実にします。

例：

      // キーの状態を取得してそれを保存する
      int keyState = getKeyStates();
      if ((keyState & LEFT_KEY) != 0) {
          positionX--;
      }
      else if ((keyState & RIGHT_KEY) != 0) {
          positionX++;
      }

このメソッドの呼び出しは全てのラッチ状態をクリアする副作用があります。 したがって、getKeyStates の別の呼び出しの直後の別の呼び出しは、現在のキーの状態の確実な情報をシステムは報告します。

デバイスによっては直接キーパッド・ハードウェアに問い合わせることができません。このような場合、このメソッドはキー押しおよびキー離しイベントをモニターすることで代替実装されるかもしれません。 キー情報の適時性は、それぞれのデバイスの能力に影響を受けることがあり、このため getKeyStates によって報告される状態は、物理的なキーの実際の状態から遅延したものであるかもしれません。 また、デバイスによっては複数のキーの同時押下を検出できないかもしれません。

Displayable.isShown() が報告する GameCanvas の現在の状態が不可視であれば、このメソッドは 0 を返します。 可視状態になると、GameCanvas は初期状態で全てのキーが押されていない（0）ことを示します。 GameCanvas が可視状態の間にキーを押下されたなら、キーが先に離されても GameCanvas はキーの押下を報告しなければなりません。

戻り値:

キーの状態情報を含む整数（１ビットが１つのキーに対応）または GameCanvas が不可視状態ならば 0 を返します。

関連項目:

UP_PRESSED, DOWN_PRESSED, LEFT_PRESSED, RIGHT_PRESSED, FIRE_PRESSED, GAME_A_PRESSED, GAME_B_PRESSED, GAME_C_PRESSED, GAME_D_PRESSED

paint

public void paint(Graphics g)

この GameCanvas への描画を行います。 デフォルトで、このメソッドは (0, 0) へオフスクリーン・バッファをレンダリングします。 バッファのレンダリングは Graphics オブジェクトのクリップ領域と原点設定の影響を受けることがあります。

定義:

クラス Canvas 内の paint

パラメータ:

g - スクリーンをレンダリングする Graphics オブジェクトを渡します。

例外:

NullPointerException - もしも g パラメータが null ならば throw します。

flushGraphics

public void flushGraphics(int x,
                          int y,
                          int width,
                          int height)

オフスクリーン・バッファの指定された矩形をディスプレイにフラッシュします。 フラッシュ操作の結果、オフスクリーン・バッファに関する内容が変更されることはありません。 フラッシュが終了するまでこのメソッドは制御を返しません。このメソッドから制御が返ると、アプリケーションはすぐに次のフレームを同じバッファへの描画を開始することができます。

指定された領域が GameCanvas の現在の範囲を超えているなら、交差する領域だけをフラッシュします。 もしも指定された幅あるいは高さが１未満であれば全てのピクセルをフラッシュしません。

現在、GameCanvas が可視状態にないか、システムがビジーでフラッシュ要求を尊重することができないなら、このメソッドは何もせずにすぐに処理を返します。

パラメータ:

x - フラッシュすべき領域の左端Ｘ座標を渡します。

y - フラッシュすべき領域の上端Ｙ座標を渡します。

width - フラッシュすべき領域の幅を渡します。

height - フラッシュすべき領域の高さを渡します。

関連項目:

flushGraphics()

flushGraphics

public void flushGraphics()

オフスクリーン・バッファをディスプレイへフラッシュします。 フラッシュする領域のサイズは GameCanvas のサイズと一致します。 フラッシュ操作の結果、オフスクリーン・バッファに関する内容が変更されることはありません。 フラッシュが終了するまでこのメソッドは制御を返しません。このメソッドから制御が返ると、アプリケーションはすぐに次のフレームを同じバッファへの描画を開始することができます。

現在、GameCanvas が可視状態にないか、システムがビジーでフラッシュ要求を尊重することができないなら、このメソッドは何もせずにすぐに処理を返します。

関連項目:

flushGraphics(int, int, int, int)