Keys Class Reference

The Keys attached property provides key handling to Items. More...

Detailed Description

The Keys attached property provides key handling to Items.

Since

4.7

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: {
        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. onKeyPress, onKeyRelease 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. onKeyPress, onKeyRelease handlers
5. parent item

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

See also

KeyEvent, {KeyNavigation}{KeyNavigation attached property}

---

The documentation for this class was generated from the following file:

• /src/declarative/graphicsitems/qdeclarativeitem.cpp