QML/Keyboard navigation

Contents 1 Overview 2 Pre-requisites 2.1 System Setup 3 How to 3.1 Create a QML application with basic input elements 3.2 Adding key navigation

Overview

This tutorial explains how to make a QML user interface entirely navigable by keyboard.

Pre-requisites

If you don't know anything about QML, reading the introductory Qt/QML documentation might be helpful.

System Setup

Install the MeeGo SDK first. Alternatively, you could just install the meego-sdk-qt-creator and meego-sdk-qt packages (see the same page for the location of the repos).

I'm using Fedora 13 Linux, and have run the application on Fedora 13 and MeeGo 1.1.

How to

You basically need to create a QML application with some input elements to start with.

Then add keyboard navigation using the following QML elements:

• KeyNavigation, for defining paths between pairs of UI elements (e.g. to move between input elements)
• Keys, for connecting key presses to actions (e.g. to submit data entered in input elements)

Create a QML application with basic input elements

1. In the Qt Creator Welcome screen, click Create Project.
2. Select Qt Quick Project and QML Application, then click Choose.
3. Enter a name for the project (e.g. key-nav), then click Next and Finish.
4. Edit the key-nav.qml file, which contains the main UI definition. The first version just displays three input elements:
   • A single line text edit box for a name.
   • A list of countries a user can select from.
   • A button to submit the input data.
   • A label to display a greeting message based on the name and selected country.

   This is what the QML looks like for these elements:

   import Qt 4.7
   
   Rectangle {
     id: window
     width: 600
     height: 300
   
     ListModel {
       id: countries
   
       ListElement {
         name: "Finland"
       }
       ListElement {
         name: "United Kingdom"
       }
       ListElement {
         name: "USA"
       }
     }
   
     Column {
       anchors.left: parent.left
       anchors.leftMargin: 10
   
       anchors.top: parent.top
       anchors.topMargin: 10
   
       spacing: 20
       width: 180
   
       Row {
         spacing: 10
         width: parent.width
   
         Text {
           text: "Name:"
         }
   
         TextInput {
           id: nameInput
   
           maximumLength: 30
           width: maximumLength * 10
           focus: true
           fillColor: "darkgrey"
         }
       }
   
       Row {
         spacing: 10
         height: countries.count * 20
         width: parent.width
   
         Text {
           text: "Country:"
         }
   
         ListView {
           id: countrySelector
   
           width: parent.width
           height: parent.height
           model: countries
           highlight: Rectangle {
             color: "darkgrey"
             radius: 5
           }
           delegate: Item {
             width: parent.width
             anchors.horizontalCenter: parent.horizontalCenter
             height: 20
             Text { text: name }
           }
         }
       }
   
       Row {
         width: parent.width
         height: 20
   
         Rectangle {
           id: submitButton
   
           width: parent.width
           height: parent.height
           color: "darkgrey"
           radius: 5
   
           Text {
             text: "Submit"
             anchors.horizontalCenter: parent.horizontalCenter
             anchors.verticalCenter: parent.verticalCenter
           }
         }
       }
   
       Row {
         width: parent.width
         height: 20
   
         Text {
           id: greeting
           text: "the greeting will be here"
         }
       }
     }
   }
   

   (I made no attempt at modularisation here, but kept everything in one file to make the explanations simpler. Also, this isn't usable at all yet.)

5. Run the application using Qt Creator's qmlviewer (big green button, bottom left in Qt Creator). You should see something like this:
   

Adding key navigation

Navigating from one QML element to another means that you shift the focus from the currently-focused element to another element. To do this, you add a KeyNavigation property to the element you're navigating from, associated with the key which will trigger the focus shift.

For example, say you had two rectangles, rect1 and rect2. You want a user to be able to navigate from rect1 to rect2 by pressing the right cursor key. To implement this, you would add the following property to rect1:

KeyNavigation.right: rect2

Which means "on pressing the right cursor key, shift the focus to the element with id rect2.

Key navigation is not symmetrical by default, so if you wanted to be able to go back to rect1 from rect2 by pressing the left cursor key, you need to add a property to rect2 as well:

KeyNavigation.left: rect1

Here's a complete example:

import Qt 4.7

Rectangle {
  width: 200
  height: 100

  Rectangle {
    id: rect1
    focus: true
    width: 100
    height: 100
    opacity: activeFocus ? 1.0 : 0.5
    color: "red"
    KeyNavigation.right: rect2
  }

  Rectangle {
    id: rect2
    width: 100
    height: 100
    x: 100
    opacity: activeFocus ? 1.0 : 0.5
    color: "red"
    KeyNavigation.left: rect1
  }
}

You can navigate from the left-hand red square (rect1) to the right-hand one by pressing the right cursor key; and from the right-hand red square to the left-hand one by pressing the left cursor key. When the focus shifts, the opacity of the focused element is set to 1.0, and the unfocused one to 0.5.