Back to Qt.io
Contact Us Blog Download Qt

Keys QML Type

アイテムにキーハンドリングを提供する。詳細...

Import Statement: import QtQuick

プロパティ

信号

詳細説明

すべてのビジュアル・プリミティブは、Keys アタッチ・プロパティによるキー操作をサポートしています。キーは、onPressed および onReleased シグナルプロパティで処理できます。

シグナルプロパティには、イベントの詳細を含むeventという KeyEvent パラメータがあります。キーが処理される場合、event.acceptedをtrueに設定し、イベントがアイテム階層に伝搬しないようにする必要があります。

使用例

次の例は、一般的なonPressedハンドラを使用して、特定のキー（この場合は左カーソルキー）をテストする方法を示しています：

Item {
    anchors.fill: parent
    focus: true
    Keys.onPressed: (event)=> {
        if (event.key == Qt.Key_Left) {
            console.log("move left");
            event.accepted = true;
        }
    }
}

キーによっては、例えばonSelectPressedのように、特定のシグナル・プロパティで処理することもできます。これらのハンドラは自動的にevent.acceptedをtrueに設定します。

Item {
    anchors.fill: parent
    focus: true
    Keys.onLeftPressed: console.log("move left")
}

キーボードコードの一覧はQt.Key を参照してください。

キー操作の優先順位

Keys attachedプロパティは、アタッチされているアイテムの前後でキーイベントを処理するように設定できます。これにより、アイテムのデフォルト動作をオーバーライドするためにイベントをインターセプトしたり、アイテムで処理されないキーのフォールバックとして動作したりすることが可能になります。

priority が Keys.BeforeItem（デフォルト）の場合、キーイベントの処理順序は次のようになります：

  1. キーイベントの処理順序は次のようになります。forwardTo
  2. 特定のキーハンドラで指定された項目。
  3. onPressed、onReleased ハンドラ。
  4. アイテム固有のキー処理（例：TextInput キー処理
  5. 親アイテム

優先順位がKeys.AfterItemの場合、キーイベントの処理順序は次のようになります：

  1. 項目固有のキー処理、例：TextInput キー処理
  2. で指定された項目。forwardTo
  3. 特定のキーハンドラで指定された項目。
  4. onPressed、onReleasedハンドラ
  5. 親アイテム

上記のステップのいずれかでイベントが受け入れられた場合、キー伝搬は停止する。

KeyEvent およびKeyNavigation attached propertyも参照してください 。

プロパティの説明

enabled : bool

このフラグは、true（デフォルト）の場合、キーハンドリングを有効にします。


forwardTo : list<Item> [read-only]

このプロパティは、キーのプレス、キーのリリース、および入力メソッドから来るキーボード入力を他のアイテムに転送する方法を提供します。これは、あるアイテムにいくつかのキー（例えば、上下の矢印キー）を処理させ、別のアイテムに他のキー（例えば、左右の矢印キー）を処理させたい場合に便利です。キーを転送されたアイテムがイベントを受け取ると、リストの後のアイテムには転送されなくなります。

この例では、キーイベントを2つのリストに転送しています：

Item {
    ListView {
        id: list1
        // ...
    }
    ListView {
        id: list2
        // ...
    }
    Keys.forwardTo: [list1, list2]
    focus: true
}

forwardTo を使用した場合のイベントの受信順序については、Key Handling Priorities を参照してください。


priority : enumeration

このプロパティは、キーがアタッチされたアイテム自身のキー処理の前に処理されるか後に処理されるかを決定します。

定数説明
Keys.BeforeItem(デフォルト) 通常のアイテムのキー処理の前にキーイベントを処理します。イベントが受け入れられた場合、そのイベントはアイテムに渡されません。
Keys.AfterItem通常のアイテムキー処理の後にキーイベントを処理する。アイテムがキーイベントを受け付けた場合、キーに付属するプロパティハンドラでは処理されません。

Key Handling Prioritiesも参照してください 。


シグナルの説明

asteriskPressed(KeyEvent event)

このシグナルは、アスタリスク '*' が押されたときに発信されます。event パラメータはイベントに関する情報を提供する。

注意： 対応するハンドラはonAsteriskPressed です。


backPressed(KeyEvent event)

このシグナルはBackキーが押されたときに発生する。event パラメーターはイベントに関する情報を提供する。

注 ：対応するハンドラはonBackPressed です。


backtabPressed(KeyEvent event)

このシグナルは、Shift+Tabキーの組み合わせ（Backtab）が押されたときに発せられます。event パラメーターはイベントに関する情報を提供する。

注： 対応するハンドラはonBacktabPressed です。


callPressed(KeyEvent event)

このシグナルは、Callキーが押されたときに発せられる。event パラメータはイベントに関する情報を提供する。

注： 対応するハンドラはonCallPressed です。


cancelPressed(KeyEvent event)

このシグナルは Cancel キーが押されたときに発せられます。event パラメータは、イベントに関する情報を提供する。

注： 対応するハンドラはonCancelPressed です。


context1Pressed(KeyEvent event)

このシグナルは、Context1 キーが押されたときに発信されます。event パラメータはイベントに関する情報を提供する。

注： 対応するハンドラはonContext1Pressed です。


context2Pressed(KeyEvent event)

このシグナルは、Context2 キーが押されたときに発せられます。event パラメータがイベントに関する情報を提供する。

注： 対応するハンドラはonContext2Pressed です。


context3Pressed(KeyEvent event)

このシグナルは、Context3 キーが押されたときに発せられます。event パラメータがイベントに関する情報を提供する。

注： 対応するハンドラはonContext3Pressed です。


context4Pressed(KeyEvent event)

このシグナルは、Context4 キーが押されたときに発せられます。event パラメータがイベントに関する情報を提供する。

注： 対応するハンドラはonContext4Pressed です。


deletePressed(KeyEvent event)

このシグナルは、Deleteキーが押されたときに発生します。event パラメータは、イベントに関する情報を提供する。

注： 対応するハンドラはonDeletePressed です。


digit0Pressed(KeyEvent event)

このシグナルは、数字の「0」が押されたときに発せられる。event パラメータはイベントに関する情報を提供する。

注： 対応するハンドラはonDigit0Pressed です。


digit1Pressed(KeyEvent event)

このシグナルは、数字の「1」が押されたときに発せられます。event パラメータはイベントに関する情報を提供する。

注： 対応するハンドラはonDigit1Pressed です。


digit2Pressed(KeyEvent event)

このシグナルは、数字の「2」が押されたときに発せられます。event パラメータがイベントに関する情報を提供する。

注： 対応するハンドラはonDigit2Pressed です。


digit3Pressed(KeyEvent event)

このシグナルは、数字の「3」が押されたときに発せられます。event パラメータは、イベントに関する情報を提供する。

注： 対応するハンドラはonDigit3Pressed です。


digit4Pressed(KeyEvent event)

このシグナルは、数字の「4」が押されたときに発せられます。event パラメータは、イベントに関する情報を提供する。

注： 対応するハンドラはonDigit4Pressed です。


digit5Pressed(KeyEvent event)

このシグナルは、数字の「5」が押されたときに発せられます。event パラメータがイベントに関する情報を提供する。

注： 対応するハンドラはonDigit5Pressed です。


digit6Pressed(KeyEvent event)

このシグナルは、数字の「6」が押されたときに発せられます。event パラメータがイベントに関する情報を提供する。

注： 対応するハンドラはonDigit6Pressed です。


digit7Pressed(KeyEvent event)

このシグナルは、数字「7」が押されたときに発せられます。event パラメータがイベントに関する情報を提供する。

注： 対応するハンドラはonDigit7Pressed です。


digit8Pressed(KeyEvent event)

このシグナルは、数字の「8」が押されたときに発せられます。event パラメータがイベントに関する情報を提供する。

注： 対応するハンドラはonDigit8Pressed です。


digit9Pressed(KeyEvent event)

このシグナルは、数字の「9」が押されたときに発せられます。event パラメータがイベントに関する情報を提供する。

注： 対応するハンドラはonDigit9Pressed です。


downPressed(KeyEvent event)

このシグナルは、下矢印が押されたときに発せられます。event パラメーターはイベントに関する情報を提供する。

注： 対応するハンドラはonDownPressed です。


enterPressed(KeyEvent event)

このシグナルは、Enterキーが押されたときに発生します。event パラメーターはイベントに関する情報を提供する。

注： 対応するハンドラはonEnterPressed です。


escapePressed(KeyEvent event)

このシグナルは、Escapeキーが押されたときに発せられます。event パラメーターはイベントに関する情報を提供する。

注： 対応するハンドラはonEscapePressed です。


flipPressed(KeyEvent event)

このシグナルはFlipキーが押されたときに発せられます。event パラメーターはイベントに関する情報を提供する。

注： 対応するハンドラはonFlipPressed です。


hangupPressed(KeyEvent event)

このシグナルは Hangup キーが押されたときに発せられます。event パラメータはイベントに関する情報を提供する。

注： 対応するハンドラはonHangupPressed です。


leftPressed(KeyEvent event)

このシグナルは、左矢印が押されたときに発信されます。event パラメータはイベントに関する情報を提供する。

注： 対応するハンドラはonLeftPressed です。


このシグナルは、Menuキーが押されたときに発生します。event パラメーターは、イベントに関する情報を提供します。

注： 対応するハンドラはonMenuPressed です。


noPressed(KeyEvent event)

このシグナルは、No キーが押されたときに発せられます。event パラメータは、イベントに関する情報を提供する。

注： 対応するハンドラはonNoPressed です。


pressed(KeyEvent event)

このシグナルは、キーが押されたときに発せられます。event パラメータは、イベントに関する情報を提供する。

注： 対応するハンドラはonPressed です。


released(KeyEvent event)

このシグナルは、キーが離されたときに発せられます。event パラメーターは、イベントに関する情報を提供する。

注： 対応するハンドラはonReleased です。


returnPressed(KeyEvent event)

このシグナルは、Returnキーが押されたときに発せられます。event パラメーターはイベントに関する情報を提供する。

注： 対応するハンドラはonReturnPressed です。


rightPressed(KeyEvent event)

このシグナルは、右矢印が押されたときに発生します。event パラメータはイベントに関する情報を提供する。

注 : 対応するハンドラはonRightPressed です。


selectPressed(KeyEventイベント)

このシグナルは、セレクトキーが押されたときに発せられる。event パラメーターはイベントに関する情報を提供する。

注： 対応するハンドラはonSelectPressed です。


shortcutOverride(KeyEvent event)

このシグナルは、ショートカットとして使われる可能性のあるキーが押されたときに発せられます。event パラメーターは、イベントに関する情報を提供します。

押されたキーが他の型（Shortcut など）でショートカットとして使われるのを防ぎたい場合は、event.accepted をtrue に設定してください。例えば

Item {
    id: escapeItem
    focus: true

    // Ensure that we get escape key press events first.
    Keys.onShortcutOverride: (event)=> event.accepted = (event.key === Qt.Key_Escape)

    Keys.onEscapePressed: {
        console.log("escapeItem is handling escape");
        // event.accepted is set to true by default for the specific key handlers
    }
}

Shortcut {
    sequence: "Escape"
    onActivated: console.log("Shortcut is handling escape")
}

他のシグナルと同様に、shortcutOverride は、そのアイテムがactiveFocus を持っている場合にのみ発生します。

注： 対応するハンドラはonShortcutOverride です。

Shortcutも参照してください 。


spacePressed(KeyEvent event)

このシグナルはSpaceキーが押されたときに発せられる。event パラメータはイベントに関する情報を提供します。

注： 対応するハンドラはonSpacePressed です。


tabPressed(KeyEvent event)

このシグナルはTabキーが押されたときに発生する。event パラメーターはイベントに関する情報を提供する。

注： 対応するハンドラはonTabPressed です。


upPressed(KeyEvent event)

このシグナルは上矢印が押されたときに発生します。event パラメーターはイベントに関する情報を提供する。

注： 対応するハンドラはonUpPressed です。


volumeDownPressed(KeyEvent event)

このシグナルは、VolumeDownキーが押されたときに発せられます。event パラメーターは、イベントに関する情報を提供する。

注： 対応するハンドラはonVolumeDownPressed です。


volumeUpPressed(KeyEvent event)

このシグナルは、VolumeUpキーが押されたときに発せられます。event パラメーターは、イベントに関する情報を提供する。

注： 対応するハンドラはonVolumeUpPressed です。


yesPressed(KeyEvent event)

このシグナルは、Yesキーが押されたときに発せられます。event パラメーターは、イベントに関する情報を提供する。

注： 対応するハンドラはonYesPressed です。


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.