はじめに (対象読者・この記事でわかること)

この記事は、Java で GUI アプリケーションを開発しているが「なぜ KeyListener を実装してもキーイベントが飛んでこない」「processKeyEvent と handleEvent の違いが分からない」と悩んでいる中級者以上の開発者を対象にしています。
この記事を読むことで、AWT/Swing の低レベルイベントディスパッチ機構である processKeyEvent の呼び出され方、デフォルト実装の中身、そして「キー入力を横取りして独自処理を差し込む」ための正しいオーバーライド方法を実践的なコードと共に理解できます。
筆者はカスタムコンポーネントで日本語変換確定前のキー入力をフックする必要があり、KeyListener だけでは届かない KEY_TYPED 以外のイベントをどう拾うか四苦八苦した経験から本記事を執筆しました。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。

  • Java の基本文法と継承の仕組み
  • AWT/Swing のイベントモデル（addKeyListener / KeyEvent クラス）の概要
  • 1 ファイルをコンパイルして実行できる開発環境（javac/java または IDE）

AWT イベント処理の裏側：processKeyEvent とは何か

processKeyEvent は java.awt.Component に定義されている protected なメソッドで、システムからポストされた KeyEvent を「最初に受け取る入口」です。
通常、私たちは KeyListener を addKeyListener で登録してキー操作を捕捉しますが、これは「コンポーネントがイベントをディスパッチした後」に実行されるため、以下のようなケースで手が届きません。

  • 子コンポーネントにフォーカスがあるにもかかわらず、親ウィンドウで全キーをフックしたい
  • 変換確定前の KEY_PRESSED / KEY_RELEASED を拾って独自ショートカットを優先したい
  • 特定のキー（例：Esc）を「処理済み」にせずに次のコンポーネントに渡したい

これらを実現するには、コンポーネントクラスを継承して processKeyEvent をオーバーライドし、必要に応じて super.processKeyEvent(e) を呼ぶかどうかを制御する必要があります。
なお processKeyEvent は KeyEvent 専用です。マウスやフォーカスイベントには対応しておらず、それらには processMouseEvent/processFocusEvent が対応しています。

processKeyEvent を実践的に使いこなす：カスタムコンポーネントでの実装パターン

ステップ1：最低限のオーバーライドとイベント消費の確認

まずは JPanel を継ンドした単純な例で、キーイベントを横取りしてログを出力してみます。

Java

public class KeyCatcherPanel extends JPanel {
    public KeyCatcherPanel() {
        setFocusable(true); // キーイベントを受け取るには必須
        setRequestFocusEnabled(true);
    }

    @Override
    protected void processKeyEvent(KeyEvent e) {
        int id = e.getID();
        String type = switch (id) {
            case KeyEvent.KEY_PRESSED  -> "PRESSED";
            case KeyEvent.KEY_RELEASED -> "RELEASED";
            case KeyEvent.KEY_TYPED    -> "TYPED";
            default -> "UNKNOWN";
        };
        System.out.printf("%s: keyCode=%d keyChar=%s%n",
                type, e.getKeyCode(), e.getKeyChar());

        // ここで consume() すると後続のリスナーには届かない
        // e.consume();

        // 次のコンポーネントへ配送するには super を呼ぶ
        super.processKeyEvent(e);
    }
}

main メソッドでこのパネルを JFrame に載せ、適当なボタンも配置してフォーカスを移動させると、ボタンにフォーカスがあっても KeyCatcherPanel#processKeyEvent が呼ばれることが確認できます。
これは JPanel が JComponent を経て Container を継承しており、Container が子孫フォーカスイベントを再ディスパッチする仕組みによるものです。

ステップ2：複数のイベントディスパッチ戦略を切り替える

実用的には「特定のキーだけ先行処理して、あとは通常通り回したい」という要件が出ます。
以下のように Predicate<KeyEvent> をフィールドに持たせて切り替えられると再利用しやすくなります。

Java

public class FilteringPanel extends JPanel {
    private Predicate<KeyEvent> filter = e -> false; // デフォルトは全スルー

    public void setFilter(Predicate<KeyEvent> f) {
        this.filter = f;
    }

    @Override
    protected void processKeyEvent(KeyEvent e) {
        if (filter.test(e)) {
            handleShortcut(e);           // 独自処理
            e.consume();                   // 他に渡さない
            return;
        }
        // 該当しなければ通常ルートへ
        super.processKeyEvent(e);
    }

    private void handleShortcut(KeyEvent e) {
        if (e.getKeyCode() == KeyEvent.VK_ESCAPE) {
            System.out.println("Esc 押下を検知");
        }
    }
}

handleShortcut 内で SwingUtilities.invokeLater を使って UI 更新を EDT に委ねることを忘れないでください。

ハマった点：KeyListener が登録できてもイベントが来ない

筆者が最初に躓いたのは「KeyListener を JFrame に登録したのにキーが飛んでこない」というものでした。
これは JFrame の RootPane にフォーカスが移動した際、JFrame 自身にキーイベントが配信されないためです。
processKeyEvent をオーバーライドしても同様で、フォーカスオーナーが別のコンポーネントの場合、フレームのメソッドは呼ばれません。

解決策：次の 3 つのいずれかを選ぶ

  1. KeyboardFocusManager#getCurrentKeyboardFocusManager().addKeyEventDispatcher(...) を使ってアプリ全体を横取りする
  2. JPanel 等を経由して processKeyEvent をオーバーライドし、setFocusable(true) でフォーカスを確保した上で requestFocusInWindow() する
  3. 入力マップ／アクションマップ（getInputMap / getActionMap）を活用して Swing 推奨の方法に寄せる

本記事で紹介した processKeyEvent のオーバーライドは、主に「独自コンポーネント内部で完結した特別なキー処理」を実装したい場合に有効です。アプリ全体のグローバルショートカットには KeyEventDispatcher または InputMap の利用を検討しましょう。

まとめ

本記事では、Java AWT/Swing における processKeyEvent の役割と、それを使ってキーイベントを横取りする実装パターンを解説しました。

  • processKeyEvent はコンポーネントが最初に受け取る低レベルな入口
  • super.processKeyEvent(e) を呼ぶか consume() するかで後続の配送を制御できる
  • KeyListener では捕捉できない変換確定前のイベントもここで処理可能
  • フォーカスが別にあると呼ばれないため、適切なフォーカス戦略が必須

この記事を通して、標準のリスナーだけでは実現できない「キー入力の先行フック」や「コンポーネント内部限定の特別ショートカット」を安全に実装できるようになりました。
次回は、Java 17 以れんのデスクトップアプリケーションで processKeyEvent を使ったゲーム入力ループを SwingWorker と組み合わせて実装する方法を紹介する予定です。

参考資料