Home · All Classes · All Functions · Overviews

QML Documents

A QML document is a block of QML source code. QML documents generally correspond to files stored on a disk or network resource, but can also be constructed directly from text data.

Here is a simple QML document:

 import Qt 4.6

 Rectangle {
     width: 240; height: 320;

     resources: [
         Component {
             id: contactDelegate
             Text {
                 text: modelData.firstName + " " + modelData.lastName
             }
         }
     ]

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

QML documents are always encoded in UTF-8 format.

A QML document always begins with one or more import statements. To prevent elements introduced in later versions from affecting existing QML programs, the element types available within a document are controlled by the imported QML Modules. That is, QML is a versioned language.

Syntactically a QML document is self contained; QML does not have a preprocessor that modifies the document prior to presentation to the QML runtime. import statements do not "include" code in the document, but instead instruct the QML runtime on how to resolve type references found in the document. Any type reference present in a QML document - such as Rectangle and ListView - including those made within an JavaScript Block or Property Bindings, are resolved based exclusively on the import statements. QML does not import any modules by default, so at least one import statement must be present or no elements will be available!

A QML document defines a single, top-level QML component. A QML component is a template that is interpreted by the QML runtime to create an object with some predefined behaviour. As it is a template, a single QML component can be "run" multiple times to produce several objects, each of which are said to be instances of the component.

Once created, instances are not dependent on the component that created them, so they can operate on independent data. Here is an example of a simple "button" component that is instantiated four times, each with a different value for its text property.

 import Qt 4.6

 BorderImage {
     property alias text: textElement.text
     width: 100; height: 30; source: "images/toolbutton.sci"

     Text {
         id: textElement
         anchors.centerIn: parent
         font.pointSize: 20
         style: Text.Raised
         color: "white"
     }
 }

In addition to the top-level component that all QML documents define, documents may also include additional inline components. Inline components are declared using the Component element, as can be seen in the first example above. Inline components share all the characteristics of regular top-level components and use the same import list as their containing QML document. Components are one of the most basic building blocks in QML, and are frequently used as "factories" by other elements. For example, the ListView element uses the delegate component as the template for instantiating list items - each list item is just a new instance of the component with the item specific data set appropriately.

Like other QML Elements, the Component element is an object and must be assigned to a property. Component objects may also have an object id. In the first example on this page, the inline component is added to the Rectangle's resources list, and then Property Binding is used to assign the Component to the ListView's delegate property. While using property binding allows the Component object to be shared (for example, if the QML document contained multiple ListView's with the same delegate), in this case the Component could have been assigned directly to the ListView's delegate. The QML language even contains a syntactic optimization when assigning directly to a component property for this case where it will automatically insert the Component tag.

These final two examples are behaviorally identical to the original document.

 import Qt 4.6

 Rectangle {
     width: 240; height: 320;

     ListView {
         anchors.fill: parent
         model: contactModel
         delegate: Component {
             Text {
                 text: modelData.firstName + " " + modelData.lastName
             }
         }
     }
 }
 import Qt 4.6

 Rectangle {
     width: 240; height: 320;

     ListView {
         anchors.fill: parent
         model: contactModel
         delegate: Text {
             text: modelData.firstName + " " + modelData.lastName
         }
     }
 }

See also QDeclarativeComponent.


Copyright © 2010 Nokia Corporation and/or its subsidiary(-ies) Trademarks
Qt 4.7.0