Use Case - Responding To User Input in QML

Supported types of user input

The Qt Quick module provides support for the most common types of user input, including mouse and touch events, text input, and key-press events. Other modules provide support for other types of user input for example, the Qt Sensors module provides support for shake-gestures in QML applications.

This article covers how to handle basic user input; for further information about motion-gesture support, see the Qt Sensors documentation. For information about audio-visual input, see the Qt Multimedia documentation.

Mouse and touch events

The input handlers let QML applications handle mouse and touch events. For example, you could create a button by adding a TapHandler to an Image, or to a Rectangle with a Text object inside. The TapHandler responds to taps or clicks on any type of pointing device.

 import QtQuick 2.12

 Item {
     id: root

     width: 320
     height: 480

     Rectangle {
         color: "#272822"
         width: 320
         height: 480
     }

     Rectangle {
         id: rectangle
         x: 40
         y: 20
         width: 120
         height: 120
         color: "red"

         TapHandler {
             onTapped: rectangle.width += 10
         }
     }
 }

For more advanced use cases such as, drag, pinch and zoom gestures, see documentation for the DragHandler and PinchHandler types.

Keyboard and button events

Button and key presses, from buttons on a device, a keypad, or a keyboard, can all be handled using the Keys attached property. This attached property is available on all Item derived types, and works with the Item::focus property to determine which type receives the key event. For simple key handling, you can set the focus to true on a single Item and do all your key handling there.

 import QtQuick 2.3

 Item {
     id: root

     width: 320
     height: 480

     Rectangle {
         color: "#272822"
         width: 320
         height: 480
     }

     Rectangle {
         id: rectangle
         x: 40
         y: 20
         width: 120
         height: 120
         color: "red"

         focus: true
         Keys.onUpPressed: rectangle.y -= 10
         Keys.onDownPressed: rectangle.y += 10
         Keys.onLeftPressed: rectangle.x += 10
         Keys.onRightPressed: rectangle.x -= 10
     }
 }

For text input, we have several QML types to choose from. TextInput provides an unstyled single-line editable text, while TextField is more suitable for form fields in applications. TextEdit can handle multi-line editable text, but TextArea is a better alternative as it adds styling.

The following snippet demonstrates how to use these types in your application:

 import QtQuick 2.12
 import QtQuick.Controls 2.4
 import QtQuick.Layouts 1.3

 ApplicationWindow {
     width: 300
     height: 200
     visible: true

     ColumnLayout {
         anchors.fill: parent
         TextField {
             id: singleline
             text: "Initial Text"
             Layout.alignment: Qt.AlignHCenter | Qt.AlignTop
             Layout.margins: 5
             background: Rectangle {
                implicitWidth: 200
                implicitHeight: 40
                border.color: singleline.focus ? "#21be2b" : "lightgray"
                color: singleline.focus ? "lightgray" : "transparent"
             }
         }

         TextArea {
             id: multiline
             placeholderText: "Initial text\n...\n...\n"
             Layout.alignment: Qt.AlignLeft
             Layout.fillWidth: true
             Layout.fillHeight: true
             Layout.margins: 5
             background: Rectangle {
                implicitWidth: 200
                implicitHeight: 100
                border.color: multiline.focus ? "#21be2b" : "lightgray"
                color: multiline.focus ? "lightgray" : "transparent"
             }
         }
     }
 }