Back to Qt.io
Contact Us Blog Download Qt

Keys QML Type

Provides key handling to Items. More...

Import Statement: import QtQuick

Properties

Signals

Detailed Description

All visual primitives support key handling via the Keys attached property. Keys can be handled via the onPressed and onReleased signal properties.

The signal properties have a KeyEvent parameter, named event which contains details of the event. If a key is handled event.accepted should be set to true to prevent the event from propagating up the item hierarchy.

Example Usage

The following example shows how the general onPressed handler can be used to test for a certain key; in this case, the left cursor key:

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

Some keys may alternatively be handled via specific signal properties, for example onSelectPressed. These handlers automatically set event.accepted to true.

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

See Qt.Key for the list of keyboard codes.

Key Handling Priorities

The Keys attached property can be configured to handle key events before or after the item it is attached to. This makes it possible to intercept events in order to override an item's default behavior, or act as a fallback for keys not handled by the item.

If priority is Keys.BeforeItem (default) the order of key event processing is:

  1. Items specified in forwardTo
  2. specific key handlers, e.g. onReturnPressed
  3. onPressed, onReleased handlers
  4. Item specific key handling, e.g. TextInput key handling
  5. parent item

If priority is Keys.AfterItem the order of key event processing is:

  1. Item specific key handling, e.g. TextInput key handling
  2. Items specified in forwardTo
  3. specific key handlers, e.g. onReturnPressed
  4. onPressed, onReleased handlers
  5. parent item

If the event is accepted during any of the above steps, key propagation stops.

See also KeyEvent and KeyNavigation attached property.

Property Documentation

enabled : bool

This flags enables key handling if true (default); otherwise no key handlers will be called.


[read-only] forwardTo : list<Item>

This property provides a way to forward key presses, key releases, and keyboard input coming from input methods to other items. This can be useful when you want one item to handle some keys (e.g. the up and down arrow keys), and another item to handle other keys (e.g. the left and right arrow keys). Once an item that has been forwarded keys accepts the event it is no longer forwarded to items later in the list.

This example forwards key events to two lists:

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

To see the order in which events are received when using forwardTo, see Key Handling Priorities.


priority : enumeration

This property determines whether the keys are processed before or after the attached item's own key handling.

ConstantDescription
Keys.BeforeItem(default) process the key events before normal item key processing. If the event is accepted, it will not be passed on to the item.
Keys.AfterItemprocess the key events after normal item key handling. If the item accepts the key event, it will not be handled by the Keys attached property handler.

See also Key Handling Priorities.


Signal Documentation

asteriskPressed(KeyEvent event)

This signal is emitted when the Asterisk '*' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onAsteriskPressed.


backPressed(KeyEvent event)

This signal is emitted when the Back key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onBackPressed.


backtabPressed(KeyEvent event)

This signal is emitted when the Shift+Tab key combination (Backtab) has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onBacktabPressed.


callPressed(KeyEvent event)

This signal is emitted when the Call key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onCallPressed.


cancelPressed(KeyEvent event)

This signal is emitted when the Cancel key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onCancelPressed.


context1Pressed(KeyEvent event)

This signal is emitted when the Context1 key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onContext1Pressed.


context2Pressed(KeyEvent event)

This signal is emitted when the Context2 key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onContext2Pressed.


context3Pressed(KeyEvent event)

This signal is emitted when the Context3 key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onContext3Pressed.


context4Pressed(KeyEvent event)

This signal is emitted when the Context4 key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onContext4Pressed.


deletePressed(KeyEvent event)

This signal is emitted when the Delete key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDeletePressed.


digit0Pressed(KeyEvent event)

This signal is emitted when the digit '0' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDigit0Pressed.


digit1Pressed(KeyEvent event)

This signal is emitted when the digit '1' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDigit1Pressed.


digit2Pressed(KeyEvent event)

This signal is emitted when the digit '2' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDigit2Pressed.


digit3Pressed(KeyEvent event)

This signal is emitted when the digit '3' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDigit3Pressed.


digit4Pressed(KeyEvent event)

This signal is emitted when the digit '4' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDigit4Pressed.


digit5Pressed(KeyEvent event)

This signal is emitted when the digit '5' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDigit5Pressed.


digit6Pressed(KeyEvent event)

This signal is emitted when the digit '6' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDigit6Pressed.


digit7Pressed(KeyEvent event)

This signal is emitted when the digit '7' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDigit7Pressed.


digit8Pressed(KeyEvent event)

This signal is emitted when the digit '8' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDigit8Pressed.


digit9Pressed(KeyEvent event)

This signal is emitted when the digit '9' has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDigit9Pressed.


downPressed(KeyEvent event)

This signal is emitted when the Down arrow has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onDownPressed.


enterPressed(KeyEvent event)

This signal is emitted when the Enter key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onEnterPressed.


escapePressed(KeyEvent event)

This signal is emitted when the Escape key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onEscapePressed.


flipPressed(KeyEvent event)

This signal is emitted when the Flip key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onFlipPressed.


hangupPressed(KeyEvent event)

This signal is emitted when the Hangup key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onHangupPressed.


leftPressed(KeyEvent event)

This signal is emitted when the Left arrow has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onLeftPressed.


This signal is emitted when the Menu key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onMenuPressed.


noPressed(KeyEvent event)

This signal is emitted when the No key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onNoPressed.


pressed(KeyEvent event)

This signal is emitted when a key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onPressed.


released(KeyEvent event)

This signal is emitted when a key has been released. The event parameter provides information about the event.

Note: The corresponding handler is onReleased.


returnPressed(KeyEvent event)

This signal is emitted when the Return key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onReturnPressed.


rightPressed(KeyEvent event)

This signal is emitted when the Right arrow has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onRightPressed.


selectPressed(KeyEvent event)

This signal is emitted when the Select key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onSelectPressed.


shortcutOverride(KeyEvent event)

This signal is emitted when a key has been pressed that could potentially be used as a shortcut. The event parameter provides information about the event.

Set event.accepted to true if you wish to prevent the pressed key from being used as a shortcut by other types, such as Shortcut. For example:

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")
}

As with the other signals, shortcutOverride will only be emitted for an item if that item has activeFocus.

Note: The corresponding handler is onShortcutOverride.

See also Shortcut.


spacePressed(KeyEvent event)

This signal is emitted when the Space key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onSpacePressed.


tabPressed(KeyEvent event)

This signal is emitted when the Tab key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onTabPressed.


upPressed(KeyEvent event)

This signal is emitted when the Up arrow has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onUpPressed.


volumeDownPressed(KeyEvent event)

This signal is emitted when the VolumeDown key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onVolumeDownPressed.


volumeUpPressed(KeyEvent event)

This signal is emitted when the VolumeUp key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onVolumeUpPressed.


yesPressed(KeyEvent event)

This signal is emitted when the Yes key has been pressed. The event parameter provides information about the event.

Note: The corresponding handler is onYesPressed.


© 2024 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.