We create an outer rectangle our “screen” and an inner rectangle which is initially hidden and located outside the bottom of the screen (y:200). Both rectangles have a mouse region attached, to control user interaction.

So when we start it, the screen looks like a black panel.

import Qt 4.6

Rectangle {
    width: 200
    height: 200
    color: "black"
    property bool on: false

    MouseRegion { id: region; anchors.fill: parent; onClicked: toolbar.toggle()}

    Rectangle {
      id: toolbar
      color: "gray"
      x: 20; y: 200;
      width: 160; height: 48
      opacity: 0
      function toggle() {
        on = on==true?false:true
      }
      states : State {
        name: "shown"
        when: on
        PropertyChanges{target:toolbar; y: 150; opacity: 1}
      }
      transitions: [
        Transition {
          NumberAnimation { matchProperties: "y,opacity"; duration: 500 }
        }
      ]
      MouseRegion { anchors.fill: parent; onClicked: console.log("toolbar clicked")}
    }
}

When the user clicks on the MouseRegion region the toolbar is toggled and the on property is changed. A change in the on property will result into a state change, which contains the properties for a visible toolbar (y, opacity). The state transition is animated via a NumberAnimation.

The screen with visible toolbar looks like this:

Another click on the MouseRegion region will hide the toolbar again.

Note: It’s important to have the larger mouse region first. Siblings declared later in a QML file are considered to be on top of those declared earlier. So order of declaration is important!

This time we begin with the desired output. Here is the a screenshot of the final example:

Defining the Star

We begin to sketch our star in a Star.qml file.

import Qt 4.6

Item {
  id: container
  width: 24
  height: 24

  property int rating
  property bool on
  signal clicked

  Image {
    id: starImage
    source: "images/star.png"
    x: 6
    y: 7
    opacity: 0.4
    scale: 0.5
  }
  MouseRegion {
    anchors.fill: container
    onClicked: { container.clicked() }
  }
  states: [
  State {
    name: "on"
    when: container.on == true
    PropertyChanges {
      target: starImage
      opacity: 1
      scale: 1
      x: 1
      y: 0
    }
  }
  ]
  transitions: [
  Transition {
    NumberAnimation {
      matchProperties: "opacity,scale,x,y"
      easing: "easeOutBounce"
    }
  }
  ]
}

The star.png image looks like this:

The Star.qml component consist mainly of an Image element, the star.png file, which is displayed at 50% scale and 40% opacity.

The star changes when the property on is set to true. This is controlled by the state "on". It changes the opacity to 100% and scale to 100%, additional the position is adjusted. A transition makes the state switch smooth.

Using the Star

The Star.qml component is used inside the LikeOMeter.qml file.

import Qt 4.6

Item {
  id: container

  property int rating: 2

  Row {
    Star {
      rating: 0
      onClicked: { container.rating = rating }
      on: container.rating >= 0
    }
    Star {
      rating: 1
      onClicked: { container.rating = rating }
      on: container.rating >= 1
    }
    Star {
      rating: 2
      onClicked: { container.rating = rating }
      on: container.rating >= 2
    }
    Star {
      rating: 3
      onClicked: { container.rating = rating }
      on: container.rating >= 3
    }
    Star {
      rating: 4
      onClicked: { container.rating = rating }
      on: container.rating >= 4
    }
  }
}

The LikeOMeter consist of a row of stars. Each star’s on property is set when the rating hits a specific threshold, which then results into painting the star image at 100% scale and 100% opacity based on the star "on" state.

When the star’s mouse region is pressed the clicked signal is emitted and handled in the onClicked handler, in this case it’s updates the container rating property. Which is bound by the threshold to the on property of the star again. So star clicked leads to container rating changes, leads to property on evaluation, can lead to star "on" state. Nice chain!

Using the LikeOMeter

You would use the LikeOMeter similar like this:

import Qt 4.6

Rectangle {
  id: container
  width: 200
  height: 200
  Column {
    anchors.centerIn: parent;
    spacing: 16
    LikeOMeter {
      id: likeOMeter
      width: 150; height: 30
    }
    Text { text: "Rating: " +likeOMeter.rating }
  }
}

The Text is updated, when the rating changes. The rating changes, when a star is clicked. Sweet!

First of all: “What is a Flickable element?”. It’s an element, which surface can be flipped. This is similar like a scroll area. You display content, which is bigger then the element itself. The viewport than shows the content only partially. To move the viewport you can flip the surface.

import Qt 4.6

Rectangle {
  id: container
  width: 200; height: 200;
  Flickable {
    id: flickable
    anchors.fill: parent;
    viewportWidth: image.width; viewportHeight: image.height
    Image { id: image; source: "qt_architecture.png" }
  }
  // extension
}

The image can be any bigger image, which is available. This will give you an image viewer, where you can flip the image in the desired direction.

This is already pretty cool. What you would like to have additional is an indicator, which area of the image you are currently looking at: A scroll bar.

The Scrollbar

import Qt 4.6

Rectangle { // background
    id: container
    color: white;

    property var flickableArea

    Rectangle { // viewport indicator
      y: flickableArea.visibleArea.yPosition * container.height
      width: parent.width
      height: flickableArea.visibleArea.heightRatio * container.height
        color: "black"
        opacity: 0.7
    }

The scroll bar in this case is a white rectangle which will be painted on the right of the visible image area later. The white-rectangle has an inner rectangle which indicates the current visible area.

Using the Scrollbar

We append to our previous flickable code where “extension” is marked the following:

  ScrollBar {
    id: scrollBar
    anchors.right: flickable.right; y: flickable.y
    width: 8; height: flickable.height
    flickableArea: flickable
  }

This adds the scrollbar to the right edge of the flickable with a width of 8 along the whole height.

The result will look like this:

Please note the right scroll indicator.

Polishing

When you add these 2 lines

    opacity: flickableArea.moving? .7 : 0;
    opacity: Behavior { NumberAnimation { duration: 400 } }

to the scrollbar component file, it will make the scrollbar invisible if the image is resting and make the scroll indicator to appear smooth. Please note that the 1st opacity statement gives the default value and the 2nd the behavior.

We will use flickr’s feed services as a data source.

This is how the final list of flickr thumbnails will look like.

First we investigate into the format used. A simple call to curl will provide us the http response.

curl http://api.flickr.com/services/feeds/photos_public.gne?format=rss2

You could also just point your browser to that url. The response looks similar to this (simplified):

<?xml version="1.0" encoding="utf-8"?>
<rss>
    <channel>
        <item>
            <title>Maringá 123</title>
            <media:thumbnail url="http://farm5.static.flickr.com/4052/4362801819_e2f46d6306_s.jpg" height="75" width="75"/>
        </item>
        <item>
            <media:thumbnail url="http://farm5.static.flickr.com/4048/4362801851_b80289ca0e_s.jpg" height="75" width="75"/>

We are mostly interested in the url attribute of the media:thumbnail tag to display later the thumbnail in our delegate.

To catch the url we use an xpath expression: /rss/channel/item. This gives us the list of items in the feed.

To access the url attribute we use in a further step a second selector: media:thumbnail/@url. This gives us the desired url, which we can feed to our delegate.

There is still one roadblock left. We use the xml namespace media:. To make the namespace available we will add it to the XmlListModel later.

Here now the code:

import Qt 4.6

Rectangle {
  width: 200
  height: 200

  Component {
    id: delegate
    Image {
      source: thumbnail
    }
  }

  ListView {
    id: view
    anchors.fill: parent
    model: model
    delegate: delegate
  }
  XmlListModel {
    id: model
    namespaceDeclarations: "declare namespace media=\"http://search.yahoo.com/mrss/\";"
    source: "http://api.flickr.com/services/feeds/photos_public.gne?format=rss2"
    query: "/rss/channel/item"
    XmlRole { name: "thumbnail"; query: 'media:thumbnail/@url/string()' }
  }

}

The most interesting part is the XmlListModel. First we make the xml namespace available to the XmlListModel and then we add the query, which provides us a list of item elements. N

The XmlRole extracts information per item, in this case the thumbnail url attribute, which is converted into a string with string().

We use the thumbnail role now in our delegate to load an image from this url. We have not set a size on the image. It will take in this case the loaded image size.

To display a content in a ListView you need a model (e.g. ListModel) and a delegate (a Component).
The model contains the data to be displayed, the delegate knows how to paint each model element.
The ListView provides a flickable area, which lays out the elements in a vertical line.

import Qt 4.6

Rectangle {
  width: 200; height: 200

  Component {
    id: delegate
    Item {
      width: 200; height: 28
      Text {
        text: title
      }
    }
  }

  ListView {
    anchors.fill: parent
    model: model
    delegate: delegate
  }

  ListModel {
    id: model
    ListElement { title: "Germany" }
    ListElement { title: "France" }
    ListElement { title: "Italy" }
    ListElement { title: "United Kingdom" }
  }
}

The ListView can also have a horizontal orientation or a highlighter component. The delegate is bound to the model by the model element names (here title).

Besides the ListModel there is also a XmlListModel and a VisualItemModel. The XmlListModel get’s the data from an Xml content (e.g. RSS feed) and selects the right parts based on a XPath query. The VisualItemModel contains data and delegate. A good coverage of model data can be found here.

Here a more complex example:

import Qt 4.6

Rectangle {
  id: container
  width: 200; height: 200
  Component {
    id: delegate
    Item {
      width: 200; height: 28
      Text {
        x: 8
        text: title
        anchors.verticalCenter: parent.verticalCenter
      }
      Rectangle {
        height: 12; width: population;
        anchors.right: parent.right
        anchors.verticalCenter: parent.verticalCenter
        color: "lightsteelblue"
      }
    }

  }

  ListView {
    id: view
    anchors.fill: parent
    model: model
    delegate: delegate
  }

  ListModel {
    id: model
    ListElement {
      title: "Germany"
      population: 81
    }
    ListElement {
      title: "France"
      population: 65
    }
    ListElement {
      title: "Italy"
      population: 60
    }
    ListElement {
      title: "United Kingdom"
      population: 62
    }
  }
}

The delegate now display a horizontal bar, based on the population of the country.

Here the screenshot to the example:

The source code of this example called ex1 is now available from my qml-posts repository at gitorious.org

This is a sketch I made for the login view.

As you can see the structuring is made up of nested Row and Column elements.

import Qt 4.6

Rectangle {
  width: 640
  height: 480
  Background { anchors.fill: parent }
  Column {
    anchors.centerIn: parent
    spacing: 16
    Column {
      spacing: 4
      MediumText { text: "Username" }
      LineInput { focus: true }
    }
    Column {
      spacing: 4
      MediumText { text: "Password" }
      LineInput { input.echoMode: TextInput.Password }
    }
    Row {
      spacing: 16
      anchors.horizontalCenter: parent.horizontalCenter
      Button { text: "Login"; onClicked: console.log("login") }
      Button { text: "Guest"; onClicked: console.log("guest") }
    }
  }
}

• MediumText is just a Text element with predefined formatting, so I don’t have to repeat is in the code.
• The LineInput is a TextInput wrapped with a BorderImage for pleasure.
• The background is a small image tiled over the parents area.

These components where discussed in earlier posts.

Here the screenshot of the result:

What currently is not working is the KeyNavigation. For example in the user name text input element, pressing down should move the focus to the password input. QML is in general supporting this with the KeyNavigation attached property. The problem i’m facing is only how I defined the reusable LineInput component, does not allow me to access the attached property KeyNavigation of the text input.

If you know a workaround, please let me know. Thanks.

The Column and Row elements have the same properties: spacing, add and move. Spacing defines the space between positioned elements and add/move defines transitions when an element is added or moved (removed).

First a simple example using Row and Column. You need to take care that the Row and Column element can determine the size of the elements.

Note: In my first try I tried to set the Rectangles width based on the Columns width, which resulted in 0 width. As no element had any real width defined.

import Qt 4.6

Rectangle {
    width: 200
    height: 200

    Column { /* outer column */
      spacing: 10
      Text { text: "Column Element"}
      Column { /* inner column */
        x: 10; y: 10
        spacing: 10
        Rectangle { width: 40; height: 20; color: "red" }
        Rectangle { width: 40; height: 20; color: "green" }
        Rectangle { width: 40; height: 20; color: "blue" }
      }
      Text { text: "Row Element" }
      Row { /* inner row */
        spacing: 10
        Rectangle { width: 40; height: 20; color: "red" }
        Rectangle { width: 40; height: 20; color: "green" }
        Rectangle { width: 40; height: 20; color: "blue" }
      }
    }
}

The result looks like this:

Dynamic Positioners

For trying out a dynamic aspect, I added a mouse region, which cover the whole scene. When pressed two selected rectangles will get invisible. To animate the whole process I added a number animation to the move property to the outer column. As this is a Column, only ‘y’ as a matching property is interesting to us.

import Qt 4.6

Rectangle {
    width: 200
    height: 200

    Column {
      spacing: 10
      move: Transition {
               NumberAnimation {
                   matchProperties: "y"
                   easing: "easeLinear"
                   duration: 500
               }
           }
      Text { text: "Column Element"}
      Column {
        x: 10; y: 10
        spacing: 10
        Rectangle { width: 40; height: 20; color: "green" }
        Rectangle {
          width: 40; height: 20; color: "red"
          opacity: region.pressed? 0 : 1
        }
        Rectangle { width: 40; height: 20; color: "blue" }
      }
      Text { text: "Row Element" }
      Row {
        spacing: 10
        Rectangle { width: 40; height: 20; color: "green" }
        Rectangle {
          width: 40; height: 20; color: "red";
          opacity: region.pressed? 0 : 1
        }
        Rectangle { width: 40; height: 20; color: "blue" }
      }
    }
    MouseRegion {
      id: region
      anchors.fill: parent
    }
}

What happens now is that when you press the mouse region, two rectangles will change to invisible. The column will update it’s size and reposition the remaining rectangles. The repositioning is animated via the number animation. Please have a try and see for yourself.

If you ever wondered which easing curves are available. They are documented here.

The previus developed TextInput scene looked like this:

import Qt 4.6

Item {
    width: 200
    height: 200

    Background { id: background }
    Item {
        property alias text: input.text
        anchors.centerIn: parent
        width: 180; height: 28
        BorderImage {
            source: "images/lineedit.sci"
            anchors.fill: parent
        }
        TextInput {
            id: input
            color: "#151515"; selectionColor: "green"
            font.pixelSize: 16; font.bold: true
            width: parent.width-16
            maximumLength: 16
            anchors.centerIn: parent
            focus: true
        }
    }
}

To be able to extract a text input component we create a new file called LineInput.qml. And extract the relevant parts.

import Qt 4.6

Item {
    property alias text: input.text
    property alias maximumLength: input.maximumLength
    anchors.centerIn: parent
    width: 180; height: 28
    BorderImage {
        source: "images/lineedit.sci"
        anchors.fill: parent
    }
    TextInput {
        id: input
        color: "#151515"; selectionColor: "green"
        font.pixelSize: 16; font.bold: true
        width: parent.width-16
        anchors.centerIn: parent
        focus: true
    }
}

I added an alias to the maximum length for convenience. The calling code changes now to:

LineInput {
    anchors.centerIn: parent
    width: 140
    text: "My LineEdit"
}

What happens now is the TextInput does not get focus for editing. My first attempt was to add just focus: true to the LineInput. But this didn’t solve the problem. Also the LineInput received the focus, its not forwarded to the inner text input.
My second attempt was to add an alias for focus on the LineInput to forward the focus. This resulted in a

Cannot override FINAL property ‘property alias focus: true’

message. What now?

FocusScope to the rescue.

A FocusScope defines a boundary for focus. If one child-element has set focus: true and the focus scope will receive focus it will forward the focus to that element.

You can read more about focus handling in QML here.

So we change our Item in LineInput.qml to a FocusScope:

import Qt 4.6

FocusScope {
    property alias text: input.text
    property alias maximumLength: input.maximumLength
    anchors.centerIn: parent
    width: 180; height: 28
    BorderImage {
        source: "images/lineedit.sci"
        anchors.fill: parent
    }
    TextInput {
        id: input
        color: "#151515"; selectionColor: "green"
        font.pixelSize: 16; font.bold: true
        width: parent.width-16
        anchors.centerIn: parent
        focus: true
    }
}

And the calling code to:

LineInput {
    anchors.centerIn: parent
    width: 140
    text: "My LineEdit"
    focus: true
}

The focus is now forwarded into the focus requesting element inside the scope. Sweet.

Exposing the TextInput

While I aliased some properties of the TextInput in the component for easier access it is also possible to expose the TextInput itself. Just use

property alias input: input

in LineInput.qml and now you can access the TextInput like this:

LineInput {
    anchors.centerIn: parent
    width: 140
    focus: true
    input.text: "No Way"
}

Another sweet thing Take care!

Sweet!

A simple TextInput has no real visual background representation. It only presents a cursor indicator and the text to be displayed. The color property defines the text color and the focus property set on true request focus for this element.

import Qt 4.6

Item {
    width: 200
    height: 200

    TextInput {
        id: input
        color: "red"
        text: "Default Text"
        width: parent.width-16; height: 28
        anchors.centerIn: parent
        focus: true
    }
}

The not so good looking example looks like this:

As you can see, its difficult to identify the TextInputs borders. So in the next step we will add a border on the TextInput.

Beautifying

To beautify the scene, we first apply our Background component, developed in an earlier post.
Then we wrap our TextInput in an Item together with a BorderImage, which will provide a more accurate presentation.

The lineedit.sci is defined as this:

border.left: 10
border.top: 10
border.bottom: 10
border.right: 10
source: lineedit.png

and the lineedit.png looks like this:

They define the border of our TextInput. To make it easier to access the TextInput text property we define an alias on the Item level, which references the TextInput’s text property.

import Qt 4.6

Item {
    width: 200
    height: 200

    Background { id: background }
    Item {
        property alias text: input.text
        anchors.centerIn: parent
        width: 180; height: 28
        BorderImage {
            source: "images/lineedit.sci"
            anchors.fill: parent
        }
        TextInput {
            id: input
            color: "#151515"; selectionColor: "green"
            font.pixelSize: 16; font.bold: true
            width: parent.width-16
            maximumLength: 16
            anchors.centerIn: parent
            focus: true
        }
    }
}

The result will look like this:

And looks already much more appealing. As the TextInput is just a QML element it can also take part in any kind of animations and transitions.

Additional TextInput allows you to set an input mask and validators and redefine the cursor displayed.

Also in this example we could extract a component. This is handled in a following post.