Keyboard Focus in QML

Acquiring Focus and Focus Scopes

An Item requests focus by setting the focus property to true.

For very simple cases simply setting the focus property is sometimes sufficient. If we run the following example with the QML Viewer, we see that the keyHandler element has active focus and pressing the A, B, or C keys modifies the text appropriately.

 Rectangle {
     color: "lightsteelblue"; width: 240; height: 25
     Text { id: myText }
     Item {
         id: keyHandler
         focus: true
         Keys.onPressed: {
             if (event.key == Qt.Key_A)
                 myText.text = 'Key A was pressed'
             else if (event.key == Qt.Key_B)
                 myText.text = 'Key B was pressed'
             else if (event.key == Qt.Key_C)
                 myText.text = 'Key C was pressed'
         }
     }
 }

However, were the above example to be used as a reusable or imported component, this simple use of the focus property is no longer sufficient.

To demonstrate, we create two instances of our previously defined component and set the first one to have focus. The intention is that when the A, B, or C keys are pressed, the first of the two components receives the event and responds accordingly.

The code that imports and creates two MyWidget instances:

 //Window code that imports MyWidget
 Rectangle {
     id: window
     color: "white"; width: 240; height: 150

     Column {
         anchors.centerIn: parent; spacing: 15

         MyWidget {
             focus: true             //set this MyWidget to receive the focus
             color: "lightblue"
         }
         MyWidget {
             color: "palegreen"
         }
     }
 }

The MyWidget code:

 Rectangle {
     id: widget
     color: "lightsteelblue"; width: 175; height: 25; radius: 10; smooth: true
     Text { id: label; anchors.centerIn: parent}
     focus: true
     Keys.onPressed: {
         if (event.key == Qt.Key_A)
             label.text = 'Key A was pressed'
         else if (event.key == Qt.Key_B)
             label.text = 'Key B was pressed'
         else if (event.key == Qt.Key_C)
             label.text = 'Key C was pressed'
     }
 }

We would like to have the first MyWidget object to have the focus by setting its focus property to true. However, by running the code, we can confirm that the second widget receives the focus.

Looking at both MyWidget and window code, the problem is evident - there are three elements that set the focus property set to true. The two MyWidget sets the focus to true and the window component also sets the focus. Ultimately, only one element can have keyboard focus, and the system has to decide which element receives the focus. When the second MyWidget is created, it receives the focus because it is the last element to set its focus property to true.

This problem is due to visibility. The MyWidget component would like to have the focus, but it cannot control the focus when it is imported or reused. Likewise, the window component does not have the ability to know if its imported components are requesting the focus.

To solve this problem, the QML introduces a concept known as a focus scope. For existing Qt users, a focus scope is like an automatic focus proxy. A focus scope is created by declaring the FocusScope element.

In the next example, a FocusScope element is added to the component, and the visual result shown.

 FocusScope {

     //FocusScope needs to bind to visual properties of the Rectangle
     property alias color: rectangle.color
     x: rectangle.x; y: rectangle.y
     width: rectangle.width; height: rectangle.height

     Rectangle {
         id: rectangle
         anchors.centerIn: parent
         color: "lightsteelblue"; width: 175; height: 25; radius: 10; smooth: true
         Text { id: label; anchors.centerIn: parent }
         focus: true
         Keys.onPressed: {
             if (event.key == Qt.Key_A)
                 label.text = 'Key A was pressed'
             else if (event.key == Qt.Key_B)
                 label.text = 'Key B was pressed'
             else if (event.key == Qt.Key_C)
                 label.text = 'Key C was pressed'
         }
     }
 }

Conceptually focus scopes are quite simple.

• Within each focus scope one element may have Item::focus set to true. If more than one Item has the focus property set, the last element to set the focus will have the focus and the others are unset, similar to when there are no focus scopes.
• When a focus scope receives active focus, the contained element with focus set (if any) also gets the active focus. If this element is also a FocusScope, the proxying behavior continues. Both the focus scope and the sub-focused item will have activeFocus property set.

Note that, since the FocusScope element is not a visual element, the properties of its children need to be exposed to the parent item of the FocusScope. Layouts and positioning elements will use these visual and styling properties to create the layout. In our example, the Column element cannot display the two widgets properly because the FocusScope lacks visual properties of its own. The MyWidget component directly binds to the rectangle properties to allow the Column element to create the layout containing the children of the FocusScope.

So far, the example has the second component statically selected. It is trivial now to extend this component to make it clickable, and add it to the original application. We still set one of the widgets as focused by default. Now, clicking either MyClickableWidget gives it focus and the other widget loses the focus.

The code that imports and creates two MyClickableWidget instances:

 Rectangle {
     id: window

     color: "white"; width: 240; height: 150

     Column {
         anchors.centerIn: parent; spacing: 15

         MyClickableWidget {
             focus: true             //set this MyWidget to receive the focus
             color: "lightblue"
         }
         MyClickableWidget {
             color: "palegreen"
         }
     }

 }

The MyClickableWidget code:

 FocusScope {

     id: scope

     //FocusScope needs to bind to visual properties of the children
     property alias color: rectangle.color
     x: rectangle.x; y: rectangle.y
     width: rectangle.width; height: rectangle.height

     Rectangle {
         id: rectangle
         anchors.centerIn: parent
         color: "lightsteelblue"; width: 175; height: 25; radius: 10; smooth: true
         Text { id: label; anchors.centerIn: parent }
         focus: true
         Keys.onPressed: {
             if (event.key == Qt.Key_A)
                 label.text = 'Key A was pressed'
             else if (event.key == Qt.Key_B)
                 label.text = 'Key B was pressed'
             else if (event.key == Qt.Key_C)
                 label.text = 'Key C was pressed'
         }
     }
     MouseArea { anchors.fill: parent; onClicked: { scope.focus = true } }
 }

When a QML Item explicitly relinquishes focus (by setting its focus property to false while it has active focus), the system does not automatically select another element to receive focus. That is, it is possible for there to be no currently active focus.

See the Keyboard Focus example for a demonstration of moving keyboard focus between multiple areas using FocusScope elements.

 Rectangle {
     color: "lightsteelblue"; width: 100; height: 50

     ListView {
         anchors.fill: parent
         focus: true

         model: ListModel {
             ListElement { name: "Bob" }
             ListElement { name: "John" }
             ListElement { name: "Michael" }
         }

         delegate: FocusScope {
                 width: childrenRect.width; height: childrenRect.height
                 x:childrenRect.x; y: childrenRect.y
                 TextInput {
                     focus: true
                     text: name
                     Keys.onReturnPressed: console.log(name)
                 }
         }
     }
 }