QML/Keyboard navigation

Revision as of 16:16, 25 November 2010

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.

You 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 the 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). You should see something like this: