QML Basic Elements

QML's basic elements allow the easy inclusion of objects into the scene.

Basic Elements

This is a list of some of the elements readily available for users.

• Item
• Rectangle
• Image
• Text
• TextInput
• TextEdit
• FocusScope
• Component
• MouseArea

For a complete list of QML elements, please visit the QML Elements page.

Properties and Qt Declarative Module

When using QML elements, keep in mind that elements may possess properties that other elements also possess. This is because QML and its underlying engine is implemented in C++ using Qt. More importantly, the chain of property inheritance is directly due to QML's use of the Qt Declarative Module and Qt's meta-object and property systems. For example, visual elements that have C++ implementation are sublcasses of QDeclarativeItem. As a result, elements such as Rectangle and Text elements inherit properties such as clip and smooth.

Item Element

Many QML elements inherit Item properties. Item possesses important properties such as focus, children, and dimension properties such as width and height. Although Item has physical properties, it is not a visual element. Using Item as the top-level QML element (as the screen) will not produce a visual result, use the Rectangle element instead. Use the Item to create opacity effects, such as when creating an invisible container to hold other components.

Rectangle Element

The Rectangle element is the basic visual element, for displaying different types of items onto the screen. The Rectangle is customizable and utilizes other elements such as Gradient and BorderImage for displaying advanced customized graphics.

Image Element

To insert an image into a QML scene, merely declare an Image element. The Image element can load images in formats supported by Qt.

Text Elements

The Text and TextEdit elements display formatted text onto the screen. TextEdit features multi-line editing while the TextInput element is for single line text input.

Using Elements as the Top-Level Component

For creating components (or displaying a simple scene), there are different elements that could be used as the top-level component. To display a simple scene, a Rectangle as the top-level component may suffice. Rectangle, FocusScope, Component, QtObject, Item, are some of the commonly used elements as the top-level component.

When importing components, the top-level component is important because the top-level component's properties are the only properties exposed to the parent.

For example, a Button component may be implemented using different elements as its top-level component. When this component is loaded into another QML scene, the component will retain the top-level component's properties. If a non-visual component is the top-level component, the visual properties should be aliased to the top-level to display the component properly.

For more information on how to build upon QML elements, see the Importing Reusable Components document.