What is QML?

QML, or Qt Markup Language, is a declarative language used to simplify the development of complex user interfaces. QML is also known as QtQuick, as it's easy to learn Javascript-based declarative markup allows the quick creation and deployment of GUIs.

Getting Started with Qt/QML

Start by downloading and installing the Qt SDK which includes the Qt libraries and the Qt Creator IDE.
Once you've installed the Qt SDK, go ahead and launch QtCreator, the well-built IDE for anything Qt. Create a new project. Choose a new Qt Quick Application which will allow maximum flexibility in creating C++/QML hybrid applications.
Continue through the project setup wizard. Choose a Desktop target, add to version control, and click finish. You should now have main.qml loaded up in your editor.
Go ahead and hit the large green "Play" button to run your application. You should see a 360x360 window with "Hello World" centered in the window.

QML Basic Elements

Item - This element is the absolute basic element. It is a pure QDeclarativeItem with no visible or drawn pixels. Every QML element extends the Item element. I generally use this element as a wrapper element for pages, screens, dialogs, etc. It's generally preferred for structures over the Rectangle element due to it's undrawn and invisible nature.

anchors is a object property of Item that allows you to position any Item-derived element relative to any other Item-derived element. This is one of the greatest features of QML when designing GUIs for multiple resolution.

Rectangle - This element is basically an Item element with a colored fill. It is possible to have an uncolored Rectangle by using color: "transparent" as a property. Again, Item is usually preferred to a Rectangle due to this colored fill. It is more efficient to use an Item as a wrapper as it reduces the number of pixels required to be drawn; especially on GL graphics views where the entire screen is repainted when one pixel is changed. Another advantage of the Rectangle element over the Item element is that it contains a border property. This can prove useful when one requires other items, such as Images, to be surrounded by a colored border of variable width. See more properties of Rectangle in the Qt Documentation.

Image - This element is used to load an image, from a local file or from a URL. It is important to understand the asynchronous property of the Image element. By default, if your source is a local file, asynchronous: false is default. If your source is a network file (indicated by the http search path), asynchronous: true would be the default. This is an important consideration when building GUIs with image-based structures, or GUIs that rely on the width/height of the image that's expected to be loaded. We'll go over more of this later on in this guide. View the Qt documentation for more helpful properties of the Image element.

BorderImage - This element is great for using one graphic at multiple width/height scenarios. This is very similar to Android's 9-patch image drawing mechanism. This element is very useful when building different sized buttons with the same graphic. View the Qt documentation for several visual examples.

AnimatedImage - This element allows the display of animated GIFs. Sadly, this element does not support animated MNGs. It does; however, provide several features to stop/play the GIFs on demand. View more Qt Documentation for more information.

Gradient - This element draws a color-blend (gradient). It can be assigned to the gradient property of Rectangle. I've never personally used this class; when dealing with low-power embedded devices, it's preferable to use images rather than requiring the system to calculate the band of colors in a gradient.

Text - This element is the preferred choice when displaying text on a GUI. This element accepts HTML as an input to the text property. This will prove useful when you need to bold or italicize only parts of text; for example, text: "<b>Name:</b>John Doe". You will need to consider alignment whenever using the Text element. Lucky for us, the guys at Qt developed a very intuitive method of aligning any piece of text.

Here're a couple examples you can refer to when dealing with text:

When dealing with paragraphs of text, maximumLineCount (available in QtQuick 1.1), wrapMode, and elide will prove immensely useful.

Combining a Text element with a Flickable element can give you a neat panning effect for scrollable Text views. Just set the Flickable's contentWidth and contentHeight to the Text element's paintedWidth and paintedHeight respectively.

TextEdit - This element can be used to provide keyboard input into your GUI. I prefer using a heavily modified Text element to achieve this task when using a touchscreen device as this element doesn't provide the flexibility in alignment and fill as the Text element. View more information about TextEdit in the Qt Documentation.

MouseArea - This element allows hitareas to be placed in your GUIs. This element (using anchors) can fill every Item-derived element with a hitarea. It is generally acceptable to subclass the basic MouseArea element with a MouseArea element that contains anchors.fill: parent as the MouseArea must know who to apply the hitarea to; in more cases than not, the MouseArea will fill it's parent.

The Qt MouseEvent system employs three crucial mouse events; including press, release, and click. A click is always built of one press and one release. Mouse events always follow this order: press, release, click. A click is only achieved if the press and release occur on the same MouseArea.

This is an important concept when building GUIs for touchscreen devices where a user may accidentally "press" a button, but "release" over another part of the GUI. This will have no effect on the GUI as the click event will not be created. This allows the user to change their mind while navigating a GUI.

Also, when building GUIs for touchscreens, one must take into consideration the touch resolution of the touchscreen. If a resistive touchscreen is used, accuracy can be within ~20%. By increasing the size of the mousearea relative to the button it is covering, can allow a more user-friendly experience. To do this, use anchors.centerIn: parent assuming the parent is the button. Then, set the width and height of the MouseArea to 1.5x the width and height of the intended button target.

The MouseArea element also contains several drag properties to allow dragging of any Item-derived element across a screen. This is particularly tricky as you would have to implement a position persisting mechanism to triumph the deletion of any QML components. Read more about the MouseArea in the Qt Documentation.

QML View Elements

View elements in QML strictly adhere to the model-view paradigm in that each View element we cover in this section has a model and a delegate property.

The model can be a ListModel, XmlListModel, QAbstractListModel, a QList of QObjects, a QStringList, and several other Javascript-based data structures.

The delegate is generally a Component-based object that you would like to repeat. For a list view of text, this would be a rectangle with text in it. For a coverflow-esque carousel, this would be an image. Components are useful in low-resource environments as they're not instantiated until needed.

ListView - This element is useful in creating lists or carousels of objects. The ListView element does not allow a repeating or circular carousel. The ListView element can be positioned horizontally or vertically using the orientation property.

ListView inherits Flickable; allowing developers to modify the contentX and contentY of the element.



PathView - This element is useful in creating more customized carousels of objects. The PathView includes an additional path property and a pathItemCount property that allows you to set the track on which the objects move around the view. The PathView is always a repeating or circular view. The PathView element can be positioned horizontally, vertically, diagonally, along any axis using the path property with the Path element. The PathAttribute property helps add different attributes for objects on different parts of the path make the PathView one of the most flexible views available in QML.

PathView does not inherit Flickable. If you're trying to modify the position of an item along a PathView, consider the highlightRangeMode by modifying the preferredHighlightBegin and the preferredHighlightEnd of your PathView.

The choice between a ListView element and a PathView element for your next carousel or list relies on one simple fact: Does your view need to repeat? If so, you need a PathView. Does your view require non-straight paths? If so, you need a PathView.



GridView - This element is useful in creating grids of objects. GridView relies on two important properties, cellWidth and cellHeight to properly calculate the size of each object's wrapper. The component delegate would be placed within this cell.

GridView also inherits Flickable; allowing developers to modify the contentX and contentY of the element.