/*!
\page qmlforcpp.html
\target qmlforcpp
\title QML for C++ Programmers
This page describes the QML format and how to use and extend it from C++.
The QML syntax declaratively describes how to construct an in memory
object tree. QML is usually used to describe a visual scene graph
but it is not conceptually limited to this: the QML format is an abstract
description of \bold any object tree.
QML also includes property bindings. Bindings are ECMAScript expressions
of a properties value. Whenever the value of the expression changes -
either for the first time at startup or subsequently thereafter - the
property is automatically updated with the new value.
\section1 Loading and using QML Files
QmlComponent is used to load a QML file and to create object instances.
In QML a component is the unit of instantiation, and the most basic unit
of scope. A component is like a template for how to construct an object
tree. One component can create multiple instances of this tree, but the
template remains constant.
The following code uses the C++ interface to create 100 red rectangles
based on a simple declarative component description.
\code
QmlComponent redRectangle("Rect { color: \"red\"; width: 100; height: 100 }");
for (int ii = 0; ii < 100; ++ii) {
QObject *rectangle = redRectangle.create();
// ... do something with the rectangle ...
}
\endcode
Each independent file describes a QML component, but it is also possible to
create sub-components within a QML file as will be shown later.
\section1 QML Format 101
This is some sample QML code.
\code
Image {
id: myRect
x: 10
y: 10
width: 100
height: 100
source: "background.png"
Text {
height: 50
width: 100
color: "white"
font.fontSize: 16
text: "Hello world!"
}
}
\endcode
The QML snippet shown above instantiates one \c Image instance and one
\c Text instance and sets properties on both. \bold Everything in QML
ultimately comes down to either instantiating an object instance, or
assigning a property a value. QML relies heavily on Qt's meta object system
and can only instantiate classes that derive from QObject.
In the above example, each property is placed on its own line. You can
also place multiple properties on one line by separating them with a
semi-colon. The code below is equivalent to the example above.
\code
Image {
id: myRect
x: 10; y: 10; width: 100; height: 100
source: "background.png"
Text { height: 50; width: 100; color: "white"; font.fontSize: 16; text: "Hello world!" }
}
\endcode
QML can set properties that are more complex than just simple types like
integers and strings. Properties can be object pointers or Qt interface
pointers or even lists of object or Qt interface pointers! QML is typesafe,
and will ensure that only the valid types are assigned to properties.
Assigning an object to a property is as simple as assigning a basic
integer. Attempting to assign an object to a property when type coercian
fails will produce an error. The following shows an example of valid and of
invalid QML and the corresponding C++ classes.
\table
\row \o
\code
class Image : public QObject
{
...
Q_PROPERTY(ImageFilter *filter READ filter WRITE setFilter)
};
class ImageFilter : public QObject
{
...
};
\endcode
\o \code
// OK
Image {
filter: ImageFilter {}
}
// NOT OK: Image cannot be cast into ImageFilter
Image {
filter: Image {}
}
\endcode
\endtable
Classes can also define an optional default property. The default property
is used for assignment if no explicit property has been specified.
Any object property can be the default, even complex properties like lists
of objects. The default property of the \c Rect class is the \c children
property, a list of \c Item's. In the following example, as both \c Image
and \c Text inherit from \c Item the \c Image and \c Text instances are
added to the parent's \c children property.
\code
Rect {
Image {}
Text {}
}
\endcode
Properties that return read-only object pointers can be used recursively.
This can be used, for example, to group properties together. The
\c Text element has a \c font property that returns an object with a number
of sub-properties such as \c family, \c bold, \c italic and \c size.
QML makes it easy to interact with these grouped properties, as the
following shows - everything you would expect to work, just does.
\table
\row \o
\code
class Text : public ...
{
...
Q_PROPERTY(Font *font READ font);
};
class Font : public QObject
{
...
Q_PROPERTY(QString family READ family WRITE setFamily);
Q_PROPERTY(bool bold READ bold WRITE setBold);
Q_PROPERTY(bool italic READ italic WRITE setItalic);
Q_PROPERTY(int size READ size WRITE setSize);
};
\endcode
\o
\code
Text {
font.family: "helvetica"
font.size: 12
font {
bold: true
italic: true
}
}
\endcode
\endtable
\section1 Defining QML Types
The QML engine has no intrinsic knowledge of any class types. Instead
the programmer must define the C++ types, and their corresponding QML
name.
\code
#define QML_DECLARE_TYPE(T)
#define QML_DEFINE_TYPE(T,QmlName)
\endcode
Adding these macros to your library or executable automatically makes the
C++ type \a T available from the declarative markup language under the
name \a QmlName. Of course there's nothing stopping you using the same
name for both the C++ and the QML name!
Any type can be added to the QML engine using these macros. The only
requirements are that \a T inherits QObject and that it has a default constructor.
\section1 Property Binding
Assigning constant values and trees to properties will only get you so
far. Property binding allows a property's value to be dependant on the
value of other properties and data. Whenever these dependencies change,
the property's value is automatically updated.
Property bindings are ECMAScript expressions and can be applied to any
object property. C++ classes don't have to do anything special to get
binding support other than define appropriate properties. When a non-literal
property assignment appears in a QML file, it is automatically treated as a
property binding.
Here's a simple example that stacks a red, blue and green rectangle.
Bindings are used to ensure that the height of each is kept equal to it's
parent's. Were the root rectangle's height property to change, the child
rectangles height would be updated automatically.
\code
Rect {
color: "red"
width: 100
Rect {
color: "blue"
width: 50
height: parent.height
Rect {
color: "green"
width: 25
height: parent.height
}
}
}
\endcode
Binding expressions execute in a context. A context behaves as a scope and
defines how the expression resolves property and variable names. Although
the two expressions in the last example are the same, the value of \c parent
resolves differently because each executes in a different context. Although
QML generally takes care of everything for the programmer, a thorough
understanding of bind contexts is important in some of the more complex QML
structures.
Every expression is executed in a bind context, encapsulated by the
QmlBindContext C++ class. As covered in the class documentation, a
bind context contains a map of names to values, and a list of default
objects. When resolving a name, the name to value map is searched first.
If the name cannot be found, the default object's are iterated in turn and
the context attempts to resolve the name as a property of one of the default
objects.
There are generally two contexts involved in the execution of a binding.
The first is the "object context" - a bind context associated with the
closest instantiated object and containing just one default object, and
that's instantiated object itself. The effect of the object
context is pretty simple - names in the binding expression resolve to
properties on the object first. It is important to note - particularly in
the case of grouped properties - the object context is that of the
instantiated object, the consequences of which are shown below.
\code
// OK // NOT OK
Text { Text {
font { font {
bold: font.italic bold: italic
} }
} }
\endcode
The second context is the "component context". Each QML component (and
consequently each QML file) is created in its own unique binding context.
Like the object context, the component context contains just one default
object - but in this case it is the component's root object. An example
will illustrate best - the resultant text will read "background.png".
\code
Image {
source: "background.png"
Text {
text: source
}
}
\endcode
If the name is not found in either of these contexts, the context heirarchy
is searched parent-by-parent until the name is either found, or the
heirarchy is exhausted.
The first property binding example shown involved fixing the height of three
rectangles. It did this by fixing the height of each rectangle to its
parent, rather than fixing them all to a single common point. Here's the
example rewritten to do just that.
\code
Rect {
color: "red"
width: 100
Rect {
color: "blue"
width: 50
height: parent.height
Rect {
color: "green"
width: 25
height: parent.parent.height
}
}
}
\endcode
Clearly this sort of fragile relationship is undesirable and unmanageable -
moving the green rectangle to be a sibling of the blue or introducing a
further rectangle between the two would break the example.
To address this problem, QML includes a way to directly reference any object
within a component (or parent component for that matter), called "ids".
Developers assign an object an id, and can then reference it directly by
name. Developers assign an object an id by setting the special \c id
property. Every object automatically has this magical property (if the
object also has an actual property called \c id, that gets set too). As
an id allows an object to be referenced directly, it must be unique within
a component. By convention, id's should start with an uppercase letter.
\code
Rect {
id: Root
color: "red"
width: GreenRect.width + 75
height: Root.height
Rect {
color: "blue"
width: GreenRect.width + 25
Rect {
id: GreenRect
color: "green"
width: 25
height: Root.height
}
}
}
\endcode
To relate id's back to QmlBindContext, id's exist as properties on the
component context.
Bind expressions can reference any object property. The QML bind engine
relies on the presence of the NOTIFY signal in the Q_PROPERTY declaration
on a class to alert it that a property's value has changed. If this is
omitted, the bind expression can still access the property's value, but
the expression will not be updated if the value changes. The following is
an example of a QML friendly property declaration.
\code
class Example : public QObject
{
Q_OBJECT
Q_PROPERTY(int sample READ sample WRITE setSample NOTIFY sampleChanged)
public:
int sample() const;
void setSample(int);
signals:
void sampleChanged(int);
};
\endcode
While generally no changes are needed to a C++ class to use property
binding, sometimes more advanced interaction between the binding engine and
an object is desirable. To facilitate this, there is a special exception
in the bind engine for allowing an object to access the binding directly.
If a binding is assigned to a property with a type of QmlBindableValue
pointer (ie. QmlBindableValue *), each time the binding value changes,
a QmlBindableValue instance is assigned to that property. The
QmlBindableValue instance allows the object to read the binding and to
evaluate the binding's current value.
\section1 Signal Properties
In addition to reading and writing regular properties, QML allows you to
easily associate ECMAScript with signals. Consider the following example,
in which Button is a made-up type with a clicked() signal.
\code
Button {
text: "Hello world!"
onClicked: print(text)
}
\endcode
Clicking on the button causes "Hello world!" to be printed to the console
(or lost forever if you're running Windows).
Like properties, signals automatically become available in QML without
any additional work. As illustrated signals are mapped into QML as special
"signal properties", using the name "on" where the first
character of the signal's name is uppercased. If more than one signal of
the same name is exist on a class, only the first is available (see the
\l Connection element for more general signal connections).
An important observation to make here is the lack of braces. While both
property bindings and signal properties involve executing ECMAScript code,
property bindings dynamically update the property value (hence the braces),
whereas with signal properties the constant script "value" is actually
assigned to the signal property. Trying to bind a value to a signal
property will not work!
Signal parameters are also available to the executing script, as shown
below, as long as you remember to name the parameters of your signal
in C++ (see QMetaMethod::parameterNames()).
\table
\row \o
\code
Example {
onDoSomething: for(var ii = 0; ii < count; ++ii)
print(message)
}
\endcode
\o
\code
class Example : public QObject
{
Q_OBJECT
signals:
void doSomething(int count, const QString &message);
};
\endcode
\endtable
Just like property bindings, signal scripts are executed in a context. The
signal script context is identical in scope to the "object context" under
property binding, with the exception that it has the signal parameters
bound in.
In addition to scripts, it is possible to assign objects to signal properties.
This automatically connects the signal to the object's default method. A
default method is defined just like a default property, though the special
"DefaultMethod" class info.
\code
Q_CLASSINFO("DefaultMethod", "myMethod(int)");
\endcode
This is useful in achieving several use cases, like that below which moves
the button when it is clicked.
\code
Button {
id: MyButton
onClicked: NumericAnimation {
target: MyButton
property: "x"
to: 100
}
}
\endcode
If the class itself actually defines a property called "on", this will
be assigned the string value and the signal handling behaviour will be
disabled.
\section1 Attached Properties
Attached properties allow unrelated types to annotate another type with some
additional properties. Some APIs or operations are inherintly imperative,
and attached properties help out when translating these APIs into the
declarative QML language.
Qt's QGridLayout is one such example.
\code
QGridLayout {
QLabel {
QGridLayout.row: 0
QGridLayout.column: 0
text: "Name:"
}
QLineEdit {
QGridLayout.row: 0
QGridLayout.column: 1
}
QLabel {
QGridLayout.row: 1
QGridLayout.column: 0
text: "Occupation:"
}
QLineEdit {
QGridLayout.row: 1
QGridLayout.column: 1
}
}
\endcode
Attached properties are identified by the use of a type name, in the
case shown \c QGridLayout, as a grouped property specifier. To prevent
ambiguity with actual class instantiations, attached properties must
always be specified to include a period but can otherwise be used just like
regular properties.
C++ types provide attached properties by declaring the public function \c qmlAttachedProperties like this example.
\table
\row \o
\code
static QObject *Type::qmlAttachedProperties(QObject *);
\endcode
\o
\code
class Example : public QObject
{
Q_OBJECT
public:
static QObject *qmlAttachedProperties(QObject *);
};
\endcode
\endtable
When an attached property is accessed, the QML engine will call this method
to create an attachment object, passing in the object instance that the
attached property applies to. The attachment object should define all
the attached properties, and is generally parented to the provided object
instance to avoid memory leaks. The QML engine does not saves this object,
so it is not necessary for the attached property function to ensure that
multiple calls for the same instance object return the same attached object.
While conceptually simple, implementing an attachment object is not quite
so easy. The \c qmlAttachedProperties function is static - attachment
objects are not associated with any particular instance. How the values
of the attached properties apply to the behaviour they are controlling is
entirely implementation dependent. An additional consequence of this is
that \bold any object can attach \bold any attached property. The following is
perfectly valid, although the attached property has no actual effect:
\code
FancyGridLayout {
Item {
Button {
QGridLayout.row: 1
}
}
}
\endcode
The property has no effect because the (made-up) FancyGridLayout type defines the meaning
of the \c row attached property only to apply to its direct children. It
is possible that other types may have attached properties that affect
objects that aren't their direct children.
Attached properties are an advanced feature that should be used with
caution.
\note We may implement a convenience wrapper that makes using attached
properties easier for the common "attach to children" case.
\section1 Property Value Sources
Intrinsically, the QML engine can assign a property either a static value,
such as a number or an object tree, or a property binding. It is possible for
advanced users to extend the engine to assign other "types" of values to
properties. These "types" are known as property value sources.
Consider the following example.
\code
Rect {
x: NumericAnimation { running: true; repeat; true; from: 0; to: 100; }
}
\endcode
Here the \c x property of the rectangle will be animated from 0 to 100.
To support this, the NumericAnimation class inherits the
QmlPropertyValueSource class. If a type inherits this class and is assigned
to a property for which type assignment would otherwise fail (ie. the
property itself doesn't have a type of QmlPropertyValueSource *), the QML
engine will automatically set the property as the target of the value
source.
\section1 Extending types in QML
QML is designed to allow you to build fully working types without writing
a line of C++ code. This is, for example, used extensively when designing
applications using the Fluid UI primitives. To create new types, it is
necessary to be able to define new signals, slots and properties in QML.
In this example, a Button is extended to have an additional
"text2" property (which always returns "Hello world!") and an additional
signal "clicked2" that is also emitted when the button is clicked. Not
a very useful extension, but an extension nonetheless.
\table
\row
\o
\code
QmlComponent component(xmlData);
QObject *object = component.create();
// Will print "Hello world!"
qDebug() << object->property("text2");
// Will be emitted whenever the button is clicked
QObject::connect(object, SIGNAL(clicked2()), this, SLOT(...));
\endcode
\o
\code
Button {
property string text2
signal clicked2
text: "Hello!"
text2: "Hello world!"
onClicked: clicked2.emit()
}
\endcode
\endtable
The general syntax for defining new properties and signals is:
\list
\o
\code
[default] property [: ]
\endcode
Where type can be one of \e int, \e bool, \e double, \e real, \e string,
\e color, \e date, \e var or \e variant.
\o
\code
signal
\endcode
Currently only parameterless signals are supported.
\endlist
\section1 Parser Status
Generally using QML is a breeze - you implement your classes in C++, add
the appropriate properties, signals and slots and off you go. The QML
engine takes care of instantiating your classes and setting the properties
and everything works fine.
However, sometimes it is helpful to know a little more about the status of
the QML parser. For example, it might be beneficial from a performance
standpoint to delay initializing some data structures until all the
properties have been set.
To assist with this, the QML engine defines an interface class called
QmlParserStatus. The interface defines a number of virtual methods that are
invoked at various stages of the component instantiation. To receive
these notifications, all a class has to do is to inherit the interface, and
notify the Qt meta system using the Q_INTERFACES() macro. For example,
\code
class Example : public QObject, public QmlParserStatus
{
Q_OBJECT
Q_INTERFACES(QmlParserStatus)
public:
virtual void componentComplete()
{
qDebug() << "Woohoo! Now to do my costly initialization";
}
};
\endcode
\section1 Extended Type Definitions
QML requires that types have the appropriate properties and signals to
work well within the declarative environment. In the case of existing
types, it is sometimes necessary to add signals, properties or slots to a
target class to make it more QML friendly but the original type cannot be
modified. For these cases, the QML engine supports extended type
definitions.
An extended type definition allows the programmer to supply an additional
type - known as the extension type - when registering the target class
whose properties, signals and slots are transparently merged with the
original target class when used from within QML.
An extension class is a regular QObject, with a constructor that takes a
QObject pointer. When needed (extension classes are delay created
until the first extension attribute is accessed) the extension
class is created and the target object is passed in as the parent. When
an extension attribute on the original is accessed, the appropriate signal,
property or slots on the extension object is used instead.
When an extended type is installed, the
\code
#define QML_DEFINE_EXTENDED_TYPE(T,QmlName,ExtendedTypeName)
\endcode
macro should be used instead of the regular \c QML_DEFINE_TYPE.
This example shows the addition of a read-only \c textLength property to
QLabel being implemented as an extension.
\table
\row
\o
\code
class QLabelExtension : public QObject
{
Q_OBJECT
Q_PROPERTY(int textLength READ textLength)
public:
QWidgetExtension(QObject *parent) : QObject(parent) {}
int textLength() const {
return static_cast(parent())->text().count();
}
};
QML_DEFINE_EXTENDED_TYPE(QLabel,QLabel,QLabelExtension);
\endcode
\o
\code
QLabel {
id: Label1
text: "Hello World!"
}
QLabel {
text: "Label1 text length: " + Label1.textLength
}
\endcode
\endtable
Attributes defined through extensions are inherited, just like attributes
defined on a normal class. Any types that inherit from \c QLabel, will
also have the \c textLength property. Derived types can include additional
extensions which are merged together, but only a single extension can be
specified for each single C++ class.
Extended type definitions can even be used to add an attached properties
function to a type - just declare the \c qmlAttachedProperties function on
the extension object.
*/