モジュール java.desktop
パッケージ java.awt.event

クラスKeyEvent

java.lang.Object
java.util.EventObject
java.awt.AWTEvent
java.awt.event.ComponentEvent
java.awt.event.InputEvent
java.awt.event.KeyEvent
すべての実装されたインタフェース:
Serializable
直系の既知のサブクラス:
MenuKeyEvent
public class KeyEvent
extends InputEvent
コンポーネント内でキー・ストロークが発生したことを示すイベントです。

この低レベルのイベントは、キーを押したり(キー・プレス)、離したり(キー・リリース)、入力した(キー・タイプ)ときに、コンポーネント・オブジェクト(テキスト・フィールドなど)によって生成されます。 イベントは、そのコンポーネントのaddKeyListenerメソッドを使ってこれらのイベントを受け取るように登録されている、すべてのKeyListenerまたはKeyAdapterオブジェクトに渡されます。 (KeyAdapterオブジェクトはKeyListenerインタフェースを実装します。) 各リスナー・オブジェクトは、イベントが発生したときにこのKeyEventを取得します。

「キー・タイプ」イベントは、ほかの2つのイベントと比べてレベルの高いイベントであり、プラットフォームやキーボードの配置には依存しません。 これらはUnicode文字が入力されたときに生成され、文字入力の検出で推奨される方法です。 もっとも単純な例としては、「a」などの一度のキー・プレスでキー・タイプ・イベントが発生します。 しかし、一連のキー・プレス('shift' +'a' など)で文字を作ることがよくあります。また、キー・プレス・イベントからキー・タイプ・イベントへのマッピングは、多対1または多対多になる場合があります。 キー・リリースは通常キー・タイプ・イベントを生成する必要はありませんが、キーがリリースされるまでキー・タイプ・イベントが生成されないケースがあります(WindowsでASCIIシーケンスをAlt-テンキー方式で入力するなど)。 アクション・キー、修飾キーなどUnicode文字を生成しないキーでは、キー・タイプ・イベントは発生しません。

getKeyCharメソッドは常に有効なUnicode文字またはCHAR_UNDEFINEDを返します。 文字入力はKEY_TYPEDイベントによって報告されます。KEY_PRESSEDおよびKEY_RELEASEDイベントは必ずしも文字入力に関連付けられていません。 そのため、getKeyCharメソッドの結果は、KEY_TYPEDイベントに対してのみ有効です。

キー・プレスおよびキー・リリース・イベントに対しては、getKeyCodeメソッドはイベントのkeyCodeを返します。 キー・タイプ・イベントに対しては、getKeyCodeメソッドは常にVK_UNDEFINEDを返します。 getExtendedKeyCodeメソッドは、多くのインターナショナル・キーボードの配置でも使用できます。

「キー・プレス」および「キー・リリース」イベントは、「キー・タイプ」イベントより低レベルのイベントであり、プラットフォームおよびキーボードの配置によって異なります。 これらのイベントは、キーを押したとき、または離したときに発生します。文字入力が発生しないキー(アクション・キー、修飾キーなど)についての状態を知るには、これらのイベントに依存するしか方法はありません。 押されているキーや離されているキーは、getKeyCodeメソッドおよびgetExtendedKeyCodeメソッドによって取得できます。これらのメソッドは、仮想キー・コードを返します。

仮想キー・コードは、1つ以上のキー・ストロークの組み合わせによって生成された文字(たとえば、Shiftキーと「a」キーで「A」が生成されます)ではなく、キーボード上のどのキーが押されたのか、または離されたのかを報告するために使用されます。

たとえば、Shiftキーを押すとVK_SHIFTキー・コードでKEY_PRESSEDイベントが発生し、「a」キーを押すとVK_AというkeyCodeが発生します。 「a」キーを離すとVK_AでKEY_RELEASEDイベントが発生します。 これとは別にkeyChar値「A」でKEY_TYPEDイベントが生成されます。

キーボードのキーを押してから離すと、次に示すキー・イベントが順に生成されます 

    KEY_PRESSED
    KEY_TYPED (is only generated if a valid Unicode character could be generated.)
    KEY_RELEASED
ただし、場合によっては(オートリピート・メソッドやオートインプット・メソッドがアクティブになっている場合など)、順序が異なることやプラットフォームに依存することがあります。

ノート:

  • アクション・キーのF1やHELPなど、Unicode文字が生成されないキーの組み合わせでは、KEY_TYPEDイベントは発生しません。
  • すべてのキーボードまたはシステムが、すべての仮想キー・コードを発生できるわけではありません。 Javaでは、こうしたキーを人為的に生成する試みはされていません。
  • 仮想キー・コードは物理的なキーを識別するものではなく、プラットフォームやキーボードの配置により異なります。 たとえば、米国語仕様キーボード配置を使用した場合にVK_Qを生成するキーは、フランス語仕様キーボード配置を使用した場合にはVK_Aを生成します。
  • 米国語仕様キーボード配置を使用した場合にVK_Qを生成するキーは、ロシア語やヘブライ語の配置でも独自のコードを生成します。 その他の配置では、これらおよびその他の多くのコードにVK_定数はありません。 これらのコードはgetExtendedKeyCodeを使用して取得でき、VK_定数が使用されるときに使用されます。
  • すべての文字にキー・コードが関連付けられているわけではありません。 たとえば、疑問符がプライマリ・レイヤーに表示されるキーボードはないため、疑問符のキー・コードはありません。
  • プラットフォームに依存しないアクション・キーの取扱いをサポートするために、Javaプラットフォームでは、いくつかの追加の仮想キー定数を使用します(使用しない場合は、仮想キー・コードおよび修飾子を解釈することで認識する必要があります)。 たとえば、日本語版Windowsのキーボードでは、VK_CONVERTとALT修飾子の代わりにVK_ALL_CANDIDATESが返されます。
  • Focus Specificationに規定されているように、デフォルトではキー・イベントはフォーカス所有者にディスパッチされます。

警告: Java言語で定義されているキー(VK_ENTER、VK_BACK_SPACE、VK_TAB)を除き、VK_定数の値に頼らないでください。 プラットフォーム管理者は、今後、より広範囲のキーボードに対応するために、これらの値を必要に応じて変更する権利を留保します。

特定のKeyEventインスタンスのidパラメータがKEY_FIRSTからKEY_LASTまでの範囲にない場合に、未指定の動作が発生します。

導入されたバージョン:
1.1
関連項目:
KeyAdapter, KeyListener, Tutorial: Writing a Key Listener, 直列化された形式

  • フィールド詳細

  • コンストラクタの詳細

    • KeyEvent

      public KeyEvent​(Component source, int id, long when, int modifiers, int keyCode, char keyChar, int keyLocation)
      KeyEventオブジェクトを構築します。

      このメソッドはsourceがnullの場合にIllegalArgumentExceptionをスローします。

      パラメータ:
      source - イベントを発生させたComponent
      id - イベントのタイプを示す整数。 許容される値については、KeyEventのクラスの説明を参照してください。
      when - イベントが発生した時間を指定するlong整数。 負またはゼロの値を渡すことはお薦めできません
      modifiers - イベント中に押された修飾キー(Shift、Ctrl、Alt、Meta)。 負の値を渡すことはお薦めできません。 ゼロの値は修飾子が渡されなかったことを意味します。 拡張された_DOWN_MASK修飾子か古い_MASK修飾子を使用しますが、1つのイベントでモデルを混合しないでください。 拡張修飾子の使用が推奨されます。
      keyCode - 実際のキーに対応する整数型コード、またはVK_UNDEFINED (キー・タイプ・イベントの場合)
      keyChar - イベントによって生成されたUnicode文字、またはCHAR_UNDEFINED (有効なUnicode文字にマッピングしないキー・プレス・イベントおよびキー・リリース・イベントの場合)
      keyLocation - キーの場所を識別します。 有効な値は、KEY_LOCATION_UNKNOWN、KEY_LOCATION_STANDARD、KEY_LOCATION_LEFT、KEY_LOCATION_RIGHT、およびKEY_LOCATION_NUMPADのみです。
      例外:
      IllegalArgumentException - idがKEY_TYPEDでkeyCharがCHAR_UNDEFINEDの場合、idがKEY_TYPEDでkeyCodeがVK_UNDEFINEDでない場合、idがKEY_TYPEDでkeyLocationがKEY_LOCATION_UNKNOWNでない場合、keyLocationが上記に列挙した有効な値のいずれでもない場合。
      IllegalArgumentException - sourceがnullである場合
      導入されたバージョン:
      1.4
      関連項目:
      EventObject.getSource(), AWTEvent.getID(), InputEvent.getWhen(), InputEvent.getModifiers(), getKeyCode(), getKeyChar(), getKeyLocation()

    • KeyEvent

      public KeyEvent​(Component source, int id, long when, int modifiers, int keyCode, char keyChar)
      KeyEventオブジェクトを構築します。

      このメソッドはsourceがnullの場合にIllegalArgumentExceptionをスローします。

      パラメータ:
      source - イベントを発生させたComponent
      id - イベントのタイプを示す整数。 許容される値については、KeyEventのクラスの説明を参照してください。
      when - イベントが発生した時間を指定するlong整数。 負またはゼロの値を渡すことはお薦めできません
      modifiers - イベント中に押された修飾キー(Shift、Ctrl、Alt、Meta)。 負の値を渡すことはお薦めできません。 ゼロの値は修飾子が渡されなかったことを意味します。 拡張された_DOWN_MASK修飾子か古い_MASK修飾子を使用しますが、1つのイベントでモデルを混合しないでください。 拡張修飾子の使用が推奨されます。
      keyCode - 実際のキーに対応する整数型コード、またはVK_UNDEFINED (キー・タイプ・イベントの場合)
      keyChar - イベントによって生成されたUnicode文字、またはCHAR_UNDEFINED (有効なUnicode文字にマッピングしないキー・プレス・イベントおよびキー・リリース・イベントの場合)
      例外:
      IllegalArgumentException - if idがKEY_TYPEDでkeyCharがCHAR_UNDEFINEDの場合、またはidがKEY_TYPEDでkeyCodeがVK_UNDEFINEDでない場合
      IllegalArgumentException - sourceがnullである場合
      関連項目:
      EventObject.getSource(), AWTEvent.getID(), InputEvent.getWhen(), InputEvent.getModifiers(), getKeyCode(), getKeyChar()

    • KeyEvent

      @Deprecatedpublic KeyEvent​(Component source, int id, long when, int modifiers, int keyCode)
      Deprecated.
      JDK 1.1以降。代わりにKeyEvent(Component, int, long, int, int, char)を使用してください
      パラメータ:
      source - イベントを発生させたComponent
      id - イベントのタイプを示す整数。 許容される値については、KeyEventのクラスの説明を参照してください。
      when - イベントが発生した時間を指定するlong整数。 負またはゼロの値を渡すことはお薦めできません
      modifiers - イベント中に押された修飾キー(Shift、Ctrl、Alt、Meta)。 負の値を渡すことはお薦めできません。 ゼロの値は修飾子が渡されなかったことを意味します。 拡張された_DOWN_MASK修飾子か古い_MASK修飾子を使用しますが、1つのイベントでモデルを混合しないでください。 拡張修飾子の使用が推奨されます。
      keyCode - 実際のキーに対応する整数型コード、またはVK_UNDEFINED (キー・タイプ・イベントの場合)

  • メソッドの詳細

    • getKeyCode

      public int getKeyCode()
      このイベントのキーに関連付けられた整数型のkeyCodeを返します。
      戻り値:
      キーボード上の実際のキーに対応する整数型のコード (KEY_TYPEDイベントの場合、keyCodeはVK_UNDEFINED。)

    • setKeyCode

      public void setKeyCode​(int keyCode)
      物理キーを示すkeyCode値を設定します。
      パラメータ:
      keyCode - キーボード上の実際のキーに対応する整数。

    • getKeyChar

      public char getKeyChar()
      このイベントのキーに関連付けられた文字を返します。 たとえば、Shift+「a」のKEY_TYPEDイベントは値「A」を返します。

      KEY_PRESSEDおよびKEY_RELEASEDイベントは文字入力の報告を目的としていません。 そのため、このメソッドによって返される値はKEY_TYPEDイベントに対してのみ有効です。

      戻り値:
      このキー・イベントに対して定義されているUnicode文字。 このキー・イベントに対する有効なUnicode文字がない場合、CHAR_UNDEFINEDが返される。

    • setKeyChar

      public void setKeyChar​(char keyChar)
      論理文字を示すkeyChar値を設定します。
      パラメータ:
      keyChar - このイベントを構成するキーストロークの組み合わせに対応するchar。

    • setModifiers

      @Deprecatedpublic void setModifiers​(int modifiers)
      Deprecated.
      JDK1.1.4以降
      InputEventの一部として定義されている、追加的に押されたキー(Shift、Ctrl、Alt、Metaなど)を示す修飾子を設定します。

      ノート:このメソッドの使用は非推奨です。これは、AWT実装の多くが修飾子の変更を認識しないためです。 シフト修飾子が変更されたときのKEY_TYPEDイベントの使用は、特に推奨できません。

      パラメータ:
      modifiers - 修飾子定数の整数組み合わせ
      関連項目:
      InputEvent

    • getKeyLocation

      public int getKeyLocation()
      このキー・イベントを発生させたキーの位置を返します。 左Shiftキーや右Shiftキーなど一部のキーは、キーボード上で複数回発生します。 さらに、一部のキーは数値入力キー・パッドで発生します。 これは、この種のキーを区別するために使用されます。
      戻り値:
      押された/離されたキーの位置。 KEY_TYPEDイベントの場合は常にKEY_LOCATION_UNKNOWNを返す。
      導入されたバージョン:
      1.4

    • getKeyText

      public static String getKeyText​(int keyCode)
      HOME、F1、AなどのkeyCodeを記述するStringを返します。 これらの文字列はawt.propertiesファイルを変更することによりローカライズが可能です。
      パラメータ:
      keyCode - 説明が返されるキー
      戻り値:
      keyCodeで特定される、物理キーのテキスト記述を含む文字列

    • getKeyModifiersText

      @Deprecated(since="9")public static String getKeyModifiersText​(int modifiers)
      Deprecated.
      代わりに拡張修飾キーとInputEvent.getModifiersExText(int)を使用することをお勧めします
      「Shiftキー」や「Ctrl+Shiftキー」などの修飾キーを記述するStringを返します。 これらの文字列はawt.propertiesファイルを変更することによりローカライズが可能です。

      InputEvent.ALT_MASKとInputEvent.BUTTON2_MASKは同じ値になるため、どちらの修飾子に対しても文字列「Alt」が返されます。 同様に、InputEvent.META_MASKとInputEvent.BUTTON3_MASKは同じ値になるため、どちらの修飾子に対しても文字列「Meta」が返されます。

      パラメータ:
      modifiers - 処理される修飾子マスク
      戻り値:
      イベント時に押された修飾キーの組み合わせのテキスト記述を含む文字列
      関連項目:
      InputEvent.getModifiersExText(int)

    • isActionKey

      public boolean isActionKey()
      このイベントのキーが「アクション」キーであるかどうかを返します。 通常アクション・キーはUnicode文字をトリガーせず、修飾キーではありません。
      戻り値:
      キーが「アクション」キーの場合はtrue、そうでない場合はfalse

    • paramString

      public String paramString()
      このイベントを特定するパラメータ文字列を返します。 このメソッドは、イベント・ログの作成およびデバッグに便利です。
      オーバーライド:
      paramString、クラス: ComponentEvent
      戻り値:
      イベントを特定する文字列とその属性

    • getExtendedKeyCode

      public int getExtendedKeyCode()
      イベントの拡張キー・コードを返します。 拡張キー・コードは、keyCodeと同様に、キーボードのキーに割り当てられている一意のIDです。 ただし、keyCodeとは異なり、この値は現在のキーボードの配置によって異なります。 たとえば、一般的な英語の配置の左上の文字キーを押すと、keyCode、VK_Qと同じ値が返されます。 一般的なロシア語の配置で同じキーを押すと、別のコードが生成されます。このコードは、「キリル文字の短いI」の文字に対して一意です。
      戻り値:
      イベントの拡張キー・コード
      導入されたバージョン:
      1.7

    • getExtendedKeyCodeForChar

      public static int getExtendedKeyCodeForChar​(int c)
      Unicode文字の拡張キー・コードを返します。
      パラメータ:
      c - 処理されるUnicode文字
      戻り値:
      対応するVK_を持つUnicode文字の場合 - このVK_定数。一般的なキーボード配置のプライマリ・レベルに表示される文字の場合は、一意の整数。 一般的なキーボードのプライマリ・レベルに文字が表示されない場合は、VK_UNDEFINEDが返される。
      導入されたバージョン:
      1.7