diff options
Diffstat (limited to 'doc/src/declarative')
| -rw-r--r-- | doc/src/declarative/basictypes.qdoc | 85 | ||||
| -rw-r--r-- | doc/src/declarative/extending-tutorial.qdoc | 20 | ||||
| -rw-r--r-- | doc/src/declarative/extending.qdoc | 9 | ||||
| -rw-r--r-- | doc/src/declarative/qtbinding.qdoc | 631 |
4 files changed, 575 insertions, 170 deletions
diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 6abe96f..8ab06ab 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -355,9 +355,11 @@ \brief A list of objects. - A list of objects. While not technically a basic type, QML also - supports lists of object types. When used from QML, the engine - automatically appends each value to the list. + A list type contains a list of objects. While not technically + a basic type, QML supports lists of object types. When used + from QML, the engine automatically appends each value to the list. + Items in the list can be accessed by index using the usual + \c listName[index] syntax. For example, the \l Item class contains a list property named children that can be used like this: @@ -366,14 +368,87 @@ Item { children: [ Item { id: child1 }, - Rectangle { id: child2 }, + Rectangle { id: child2; width: 200 }, Text { id: child3 } ] + + Component.onCompleted: { + console.log("Width of child rectangle:", children[1].width) + } } \endqml - \c child1, \c child2 and \c child3 will all be added to the children list + \c child1, \c child2 and \c child3 will be added to the children list in the order in which they appear. + List \l {Adding new properties}{properties} can be created as a + \c variant type, or as a \c list<Type> type, where \c Type is the + type of the object in the list: + + \qml + Item { + property variant values: [ 10, 20, 'abc', 'xyz' ] + + property list<Rectangle> rects: [ + Rectangle { width: 100; height: 100}, + Rectangle { width: 200; height: 200} + ] + } + \endqml + + A \c variant list can contain values of any of the \l {QML Basic Types}{basic QML types} + such as numbers, strings, etc. while a \c list<Type> list can only contain values + that match (or are derived from) the specified \c Type. + + A list property can be cleared by setting it to an empty list: + + \qml + Item { + children: [] + } + \endqml + + A list property cannot be modified in any other way. Items cannot be dynamically added to + or removed from the list through JavaScript operations; any \c push() operations on the + list only modify a \e copy of the list and not the actual list. (These current limitations + are due to restrictions on \l {Property Binding} where lists are involved.) + + To create a modifiable list, create an array object from within a \c .js JavaScript file, + or implement a custom list element in C++. Here is a QML element that modifies the list in a + JavaScript file: + + \table + \row + \o + \qml + // QML + import "script.js" as Script + + Item { + Component.onCompleted: { + Script.addItem('abc') + console.log("Added:", Script.getList()[0]) + } + } + \endqml + + \o + \code + // script.js + var myArray = new Array() + + function getList() { + return myArray + } + + function addItem(item) { + myArray.push(item) + } + \endcode + \endtable + + However, note that a JavaScript list should not be used as a QML \c property value, + as the property is not updated when the list changes. + \sa {QML Basic Types} */ diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc index 3b2fe3b..2bfe62e 100644 --- a/doc/src/declarative/extending-tutorial.qdoc +++ b/doc/src/declarative/extending-tutorial.qdoc @@ -260,32 +260,28 @@ custom QML types may see unexpected behavior if bindings are not implemented. The \c PieChart type currently has a string-type property and a color-type property. It could have many other types of properties. For example, it could have an -enum-type property to store a display mode for each chart: +int-type property to store an identifier for each chart: \code // C++ class PieChart : public QDeclarativeItem { - Q_ENUMS(DisplayMode) - Q_PROPERTY(DisplayMode displayMode READ displayMode WRITE setDisplayMode) + Q_PROPERTY(int chartId READ chartId WRITE setChartId NOTIFY chartIdChanged) ... public: - enum DisplayMode { - MultiLevel, - Exploded, - ThreeDimensional - }; - - void setDisplayMode(DisplayMode mode); - DisplayMode displayMode() const; + void setChartId(int chartId); + int chartId() const; ... + + signals: + void chartIdChanged(); }; // QML PieChart { ... - displayMode: PieChart.Exploded + chartId: 100 } \endcode diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 18887c7..5c1b977 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -647,7 +647,8 @@ language. \section1 Adding new properties -New properties can be added to an existing type. These new properties are +New properties can be added to an existing type using the \c property keyword. +These new properties are available for use within QML, and also appear as regular Qt properties on the C++ object, accessible through the regular property access mechanisms. @@ -679,8 +680,12 @@ like this: property list<Item> listOfItemsProperty \endcode +Custom types must be registered with qmlRegisterType() to be usable as a property +type. Also note that list properties cannot be modified like ordinary JavaScript +arrays; see the \l {list}{list type documentation} for details. + QML supports two methods for adding a new property to a type: a new property -definition, and a property alias. +definition, and a property alias. These are shown below. \section2 Property definitions diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc index 58d53de..8a969eb 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/declarative/qtbinding.qdoc @@ -30,126 +30,389 @@ \target qtbinding \title Using QML in C++ Applications -\tableofcontents +QML is designed to be easily extensible from C++. The classes in the +QtDeclarative module allow QML components to be loaded and manipulated from C++, and through +Qt's \l{The Meta-Object System}{meta-object system}, QML and C++ objects can easily +communicate through Qt signals and slots. In addition, QML plugins can be written to create +reusable QML components for distribution. -The QML API is split into three main classes - QDeclarativeEngine, QDeclarativeComponent and QDeclarativeContext. -QDeclarativeEngine provides the environment in which QML is run, QDeclarativeComponent encapsulates -\l {QML Documents}, and QDeclarativeContext allows applications to expose data to QML component instances. +You may want to mix QML and C++ for a number of reasons. For example: -QML also includes a convenience API, QDeclarativeView, for applications that simply want to embed QML -components into a new QGraphicsView. QDeclarativeView covers up many of the details discussed below. -While QDeclarativeView is mainly intended for rapid prototyping it can have uses in production applications. +\list +\o To use functionality defined in a C++ source (for example, when using a C++ Qt-based data model, or +calling functions in a third-party C++ library) +\o To access functionality in the QtDeclarative module (for example, to dynamically generate +images using QDeclarativeImageProvider) +\o To write your own QML elements (whether for your applications, or for distribution to others) +\endlist + +To use the QtDeclarative module, you must include and link to the module appropriately, as shown on +the \l {QtDeclarative}{module index page}. The \l {Qt Declarative UI Runtime} documentation +shows how to build a basic C++ application that uses this module. + + +\section1 Core module classes -If you are looking at retrofitting an existing Qt application with QML, -read \l{Integrating QML with existing Qt UI code}. -\section1 Basic Usage +The QtDeclarative module provides a set of C++ APIs for extending your QML applications from C++ and +embedding QML into C++ applications. There are several core classes in the QtDeclarative module +that provide the essential capabilities for doing this. These are: -Every application requires at least one QDeclarativeEngine. A QDeclarativeEngine allows the configuration of -global settings that apply to all the QML component instances - such as the QNetworkAccessManager -that is used for network communications, and the path used for persistent storage. -Multiple QDeclarativeEngine's are only needed if the application requires these settings to differ -between QML component instances. +\list +\o QDeclarativeEngine: A QML engine provides the environment for executing QML code. Every +application requires at least one engine instance. +\o QDeclarativeComponent: A component encapsulates a \l{QML Documents}{QML document}. +\o QDeclarativeContext: A context allows an application to expose data to the QML components +created by an engine. +\endlist -\l {QML Documents} are loaded using the QDeclarativeComponent class. Each QDeclarativeComponent instance -represents a single QML document. A QDeclarativeComponent can be passed a document URL, or raw text -representing the content of the document. The document URL can be a local filesystem URL, or -any network URL supported by QNetworkAccessManager. +A QDeclarativeEngine allows the configuration of global settings that apply to all of its QML +component instances: for example, the QNetworkAccessManager to be used for network communications, +and the file path to be used for persistent storage. -QML component instances can then be created by calling the QDeclarativeComponent::create() method. Here's -an example of loading a QML document, and creating an object from it. +QDeclarativeComponent is used to load QML documents. Each QDeclarativeComponent instance represents +a single document. A component can be created from the URL or file path of a QML document, or the raw +QML code of the document. Component instances are instatiated through the +QDeclarativeComponent::create() method, like this: \code - QDeclarativeEngine *engine = new QDeclarativeEngine(parent); - QDeclarativeComponent component(engine, QUrl::fromLocalFile("main.qml")); - QObject *myObject = component.create(); +QDeclarativeEngine engine; +QDeclarativeComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml")); +QObject *rectangleInstance = component.create(); + +// ... +delete rectangleInstance; \endcode -\section1 Exposing Data +QML documents can also be loaded using QDeclarativeView. This class provides a convenient +QWidget-based view for embedding QML components into QGraphicsView-based applications. (For other +methods of integrating QML into QWidget-based applications, see \l {Integrating QML with existing Qt +UI code}.) + + +\section1 Approaches to using QML with C++ + +There are a number of ways to extend your QML application through C++. For example, you could: + +\list +\o Load a QML component and manipulate it (or its children) from C++ +\o Embed a C++ object and its properties directly into a QML component (for example, to make a +particular C++ object callable from QML, or to replace a dummy list model data with a real data set) +\o Define new QML elements (through QObject-based C++ classes) and create them directly from your +QML code +\endlist + +These methods are shown below. Naturally these approaches are not exclusive; you can mix any of +these methods throughout your application as appropriate. + + +\section2 Loading QML components from C++ + +A QML document can be loaded with QDeclarativeComponent or QDeclarativeView. QDeclarativeComponent +loads a QML component as a C++ object; QDeclarativeView also does this, +but additionally loads the QML component directly into a QGraphicsView. It is convenient for loading +a displayable QML component into a QWidget-based application. + +For example, suppose there is a \c MyItem.qml file that looks like this: + +\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml start +\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml end + +This QML document can be loaded with QDeclarativeComponent or QDeclarativeView with the following +C++ code. Using a QDeclarativeComponent requires calling QDeclarativeComponent::create() to create +a new instance of the component, while a QDeclarativeView automatically creates an instance of the +component, which is accessible via QDeclarativeView::rootObject(): + +\table +\row +\o +\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeComponent-a +\dots 0 +\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeComponent-b +\o +\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp QDeclarativeView +\endtable + +This \c object is the instance of the \c MyItem.qml component that has been created. You can now +modify the item's properties using QObject::setProperty() or QDeclarativeProperty: + +\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp properties + +Alternatively, you can cast the object to its actual type and call functions with compile-time +safety. In this case the base object of \c MyItem.qml is an \l Item, which is defined by the +QDeclarativeItem class: + +\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp cast + +You can also connect to any signals or call functions defined in the component using +QMetaObject::invokeMethod() and QObject::connect(). See \l {Exchanging data between QML and C++} +below for further details. + +\section3 Locating child objects + +QML components are essentially object trees with children that have siblings and their own children. +Child objects of QML components can be located using the QObject::objectName property with +QObject::findChild(). For example, if the root item in \c MyItem.qml had a child \l Rectangle item: + +\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml start +\codeline +\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml child +\snippet doc/src/snippets/declarative/qtbinding/loading/MyItem.qml end + +The child could be located like this: + +\snippet doc/src/snippets/declarative/qtbinding/loading/main.cpp findChild + +If \c objectName is used inside a delegate of a ListView, \l Repeater or some other +element that creates multiple instances of its delegates, there will be multiple children with +the same \c objectName. In this case, QObject::findChildren() can be used to find all children +with a matching \c objectName. + +\warning While it is possible to use C++ to access and manipulate QML objects deep into the +object tree, we recommend that you do not take this approach outside of application +testing and prototyping. One strength of QML and C++ integration is the ability to implement the +QML user interface separately from the C++ logic and dataset backend, and this strategy breaks if the +C++ side reaches deep into the QML components to manipulate them directly. This would make it difficult +to, for example, swap a QML view component for another view, if the new component was missing a +required \c objectName. It is better for the C++ implementation to know as little as possible about +the QML user interface implementation and the composition of the QML object tree. + + +\section2 Embedding C++ objects into QML components + +When loading a QML scene into a C++ application, it can be useful to directly embed C++ data into +the QML object. QDeclarativeContext enables this by exposing data to the context of a QML +component, allowing data to be injected from C++ into QML. + +For example, here is a QML item that refers to a \c currentDateTime value that does not exist in +the current scope: + +\snippet doc/src/snippets/declarative/qtbinding/context/MyItem.qml 0 + +This \c currentDateTime value can be set directly by the C++ application that loads the QML +component, using QDeclarativeContext::setContextProperty(): + +\snippet doc/src/snippets/declarative/qtbinding/context/main.cpp 0 + +Context properties can hold either QVariant or QObject* values. This means custom C++ objects can +also be injected using this approach, and these objects can be modified and read directly in QML. +Here, we modify the above example to embed a QObject instance instead of a QDateTime value, and the QML code +invokes a method on the object instance: + +\table +\row +\o +\snippet doc/src/snippets/declarative/qtbinding/context-advanced/applicationdata.h 0 +\codeline +\snippet doc/src/snippets/declarative/qtbinding/context-advanced/main.cpp 0 +\o +\snippet doc/src/snippets/declarative/qtbinding/context-advanced/MyItem.qml 0 +\endtable + +(Note that date/time values returned from C++ to QML can be formatted through +\l{QML:Qt::formatDateTime}{Qt.formatDateTime()} and associated functions.) + +If the QML item needs to receive signals from the context property, it can connect to them using the +\l Connections element. For example, if \c ApplicationData has a signal named \c +dataChanged(), this signal can be connected to using an \c onDataChanged handler within +a \l Connections object: + +\snippet doc/src/snippets/declarative/qtbinding/context-advanced/connections.qml 0 + +Context properties can be useful for using C++ based data models in a QML view. See the +\l {declarative/modelviews/stringlistmodel}{String ListModel}, +\l {declarative/modelviews/objectlistmodel}{Object ListModel} and +\l {declarative/modelviews/abstractitemmodel}{AbstractItemModel} models for +respective examples on using QStringListModel, QObjectList-based models and QAbstractItemModel +in QML views. + +Also see the QDeclarativeContext documentation for more information. + + +\section2 Defining new QML elements + +While new QML elements can be \l {Defining new Components}{defined in QML}, they can also be +defined by C++ classes; in fact, many of the core \l {QML Elements} are implemented through +C++ classes. When you create a QML object using one of these elements, you are simply creating an +instance of a QObject-based C++ class and setting its properties. + +For example, here is an \c ImageViewer class with an \c image URL property: + +\snippet doc/src/snippets/declarative/qtbinding/newelements/imageviewer.h 0 + +Aside from the fact that it inherits QDeclarativeItem, this is an ordinary class that could +exist outside of QML. However, once it is registered with the QML engine using qmlRegisterType(): + +\snippet doc/src/snippets/declarative/qtbinding/newelements/main.cpp register + +Then, any QML code loaded by your C++ application or \l{QDeclarativeExtensionPlugin}{plugin} can create and manipulate +\c ImageViewer objects: + +\snippet doc/src/snippets/declarative/qtbinding/newelements/standalone.qml 0 + +Note that custom C++ types do not have to inherit from QDeclarativeItem; this is only necessary if it is +a displayable item. If the item is not displayable, it can simply inherit from QObject. + +For more information on defining new QML elements, see the \l {Tutorial: Writing QML extensions with C++} +{Writing QML extensions with C++} tutorial and the \l {Extending QML in C++} reference +documentation. + + + +\section1 Exchanging data between QML and C++ + +QML and C++ objects can communicate with one another through signals, slots and property +modifications. For a C++ object, any data that is exposed to Qt's \l{The Meta-Object System}{Meta-Object System} +- that is, properties, signals, slots and Q_INVOKABLE methods - become available to QML. On +the QML side, all QML object data is automatically made available to the meta-object system and can +be accessed from C++. + + +\section2 Calling functions -QML components are instantiated in a QDeclarativeContext. A context allows the application to expose data -to the QML component instance. A single QDeclarativeContext can be used to instantiate all the objects -used by an application, or several QDeclarativeContext can be created for more fine grained control over -the data exposed to each instance. If a context is not passed to the QDeclarativeComponent::create() -method, the QDeclarativeEngine's \l {QDeclarativeEngine::rootContext()}{root context} is used. Data exposed through -the root context is available to all object instances. +QML functions can be called from C++ and vice-versa. -\section1 Simple Data +All QML functions are exposed to the meta-object system and can be called using +QMetaObject::invokeMethod(). Here is a C++ application that uses this to call a QML function: -To expose data to a QML component instance, applications set \l {QDeclarativeContext::setContextProperty()} -{context properties} which are then accessible by name from QML \l {Property Binding}s and JavaScript. -The following example shows how to expose a background color to a QML file through QDeclarativeView: +\table +\row +\o \snippet doc/src/snippets/declarative/qtbinding/functions-qml/MyItem.qml 0 +\o \snippet doc/src/snippets/declarative/qtbinding/functions-qml/main.cpp 0 +\endtable + +Notice the Q_RETURN_ARG() and Q_ARG() arguments for QMetaObject::invokeMethod() must be specified as +QVariant types, as this is the generic data type used for QML functions and return values. + +To call a C++ function from QML, the function must be either a Qt slot, or a function marked with +the Q_INVOKABLE macro, to be available to QML. In the following example, the QML code invokes +methods on the \c myObject object, which has been set using QDeclarativeContext::setContextProperty(): + +\table +\row +\o +\snippet doc/src/snippets/declarative/qtbinding/functions-cpp/MyItem.qml 0 +\o +\snippet doc/src/snippets/declarative/qtbinding/functions-cpp/myclass.h 0 +\codeline +\snippet doc/src/snippets/declarative/qtbinding/functions-cpp/main.cpp 0 +\endtable + +Note that QML does not support overloaded functions. If a C++ has more than one function with the +same name, there is no guarantee which overloaded function will be called from QML. + + +\section2 Receiving signals + +All QML signals are automatically available to C++, and can be connected to using QObject::connect() +like any ordinary Qt C++ signal. + +Here is a QML component with a signal named \c qmlSignal. This signal is connected to a C++ object's +slot using QObject::connect(): + +\table +\row +\o +\snippet doc/src/snippets/declarative/qtbinding/signals-qml/MyItem.qml 0 +\o +\snippet doc/src/snippets/declarative/qtbinding/signals-qml/myclass.h 0 +\codeline +\snippet doc/src/snippets/declarative/qtbinding/signals-qml/main.cpp 0 +\endtable + +To connect to Qt C++ signals from within QML, use a signal handler with the \c on<SignalName> syntax. +If the C++ object is directly creatable from within QML (see \l {Defining new QML elements} above) +then the signal handler can be defined within the object declaration. In the following example, the +QML code creates a \c ImageViewer object, and the \c imageChanged and \c loadingError signals of the +C++ object are connected to through \c onImagedChanged and \c onLoadingError signal handlers in QML: \table \row \o -\c {// main.cpp} -\snippet doc/src/snippets/declarative/qtbinding/contextproperties/main.cpp 0 + +\snippet doc/src/snippets/declarative/qtbinding/signals-cpp/imageviewer.h start +\dots 4 +\snippet doc/src/snippets/declarative/qtbinding/signals-cpp/imageviewer.h end \o -\c {// main.qml} -\snippet doc/src/snippets/declarative/qtbinding/contextproperties/main.qml 0 +\snippet doc/src/snippets/declarative/qtbinding/signals-cpp/standalone.qml 0 +\endtable + +(Note that if a signal has been declared as the NOTIFY signal for a property, QML allows it to be +received with an \c on<Property>Changed handler even if the signal's name does not follow the \c +<Property>Changed naming convention. In the above example, if the "imageChanged" signal was named +"imageModified" instead, the \c onImageChanged signal handler would still be called.) + +If, however, the object with the signal is not created from within the QML code, and the QML item only has a +reference to the created object - for example, if the object was set using +QDeclarativeContext::setContextProperty() - then the \l Connections element can be used +instead to create the signal handler: +\table +\row +\o \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/main.cpp connections +\o \snippet doc/src/snippets/declarative/qtbinding/signals-cpp/MyItem.qml 0 \endtable -Or, if you want \c main.cpp to create the component without showing it in a QDeclarativeView, you could create an instance of QDeclarativeContext using QDeclarativeEngine::rootContext() instead: -\snippet doc/src/snippets/declarative/qtbinding/contextproperties/main.cpp 1 +\section2 Modifying properties -Context properties work just like normal properties in QML bindings - if the \c backgroundColor -context property in this example was changed to red, the component object instances would -all be automatically updated. Note that it is the responsibility of the creator to delete any -QDeclarativeContext it constructs. If the \c windowContext is no longer needed when -the \c window component instantiation is destroyed, the \c windowContext must be destroyed -explicitly. The simplest way to ensure this is to set \c window as \c windowContext's parent. +Any properties declared in a QML object are automatically accessible from C++. Given a QML item +like this: -QDeclarativeContexts form a tree - each QDeclarativeContext except for the root context has a parent. Child -QDeclarativeContexts effectively inherit the context properties present in their parents. This gives -applications more freedom in partitioning the data exposed to different QML object instances. -If a QDeclarativeContext sets a context property that is also set in one of its parents, the new context -property shadows that in the parent. In The following example, the \c background context property -in \c {Context 1} shadows the \c background context property in the root context. +\snippet doc/src/snippets/declarative/qtbinding/properties-qml/MyItem.qml 0 -\image qml-context-tree.png +The value of the \c someNumber property can be set and read using QDeclarativeProperty, or +QObject::setProperty() and QObject::property(): -\section2 Structured Data +\snippet doc/src/snippets/declarative/qtbinding/properties-qml/main.cpp 0 -Context properties can also be used to expose structured and writable data to QML objects. In -addition to all the types already supported by QVariant, QObject derived types can be assigned to -context properties. QObject context properties allow the data exposed to be more structured, and -allow QML to set values. +You should always use QObject::setProperty(), QDeclarativeProperty or QMetaProperty::write() to +change a QML property value, to ensure the QML engine is made aware of the property change. For example, +say you have a custom element \c PushButton with a \c buttonText property that internally reflects +the value of a \c m_buttonText member variable. Modifying the member variable directly like this is +not a good idea: -The following example creates a \c CustomPalette object, and sets it as the \c palette context -property. +\badcode +// BAD! +QDeclarativeComponent component(engine, "MyButton.qml"); +PushButton *button = qobject_cast<PushButton*>(component.create()); +button->m_buttonText = "Click me"; +\endcode -\snippet doc/src/snippets/declarative/qtbinding/custompalette/custompalette.h 0 +Since the value is changed directly, this bypasses Qt's \l{The Meta-Object System}{meta-object system} +and the QML engine is not made aware of the property change. This means property bindings to +\c buttonText would not be updated, and any \c onButtonTextChanged handlers would not be called. -\snippet doc/src/snippets/declarative/qtbinding/custompalette/main.cpp 0 -The QML that follows references the palette object, and its properties, to set the appropriate -background and text colors. When the window is clicked, the palette's text color is changed, and -the window text will update accordingly. +\target properties-cpp -\snippet doc/src/snippets/declarative/qtbinding/custompalette/main.qml 0 +Any \l {The Property System}{Qt properties} - that is, those declared with the Q_PROPERTY() +macro - are accessible from QML. Here is a modified version of the \l {Embedding C++ objects into +QML components}{earlier example} on this page; here, the \c ApplicationData class has a \c backgroundColor +property. This property can be written to and read from QML: -To detect when a C++ property value - in this case the \c CustomPalette's \c text property - -changes, the property must have a corresponding NOTIFY signal. The NOTIFY signal specifies a signal -that is emitted whenever the property changes value. Implementers should take care to only emit the -signal if the value \e changes to prevent loops from occurring. Accessing a property from a -binding that does not have a NOTIFY signal will cause QML to issue a warning at runtime. +\table +\row +\o \snippet doc/src/snippets/declarative/qtbinding/properties-cpp/applicationdata.h 0 +\o \snippet doc/src/snippets/declarative/qtbinding/properties-cpp/MyItem.qml 0 +\endtable -\section2 Dynamic Structured Data +Notice the \c backgroundColorChanged signal is declared as the NOTIFY signal for the +\c backgroundColor property. If a Qt property does not have an associated NOTIFY signal, +the property cannot be used for \l {Property Binding} in QML, as the QML engine would not be +notified when the value changes. If you are using custom types in QML, make sure their +properties have NOTIFY signals so that they can be used in property bindings. -If an application is too dynamic to structure data as compile-time QObject types, dynamically -structured data can be constructed at runtime using the QDeclarativePropertyMap class. +See \l {Tutorial: Writing QML extensions with C++} for further details and examples +on using Qt properties with QML. -\section1 Calling C++ methods from QML +\section1 Supported data types -It is possible to call methods of QObject derived types by either exposing the -methods as public slots, or by marking the methods Q_INVOKABLE. +Any C++ data that is used from QML - whether as custom properties, or parameters for signals or +functions - must be of a type that is recognizable by QML. -The C++ methods can also have parameters and return values. QML has support for -the following types: +By default, QML recognizes the following data types: \list \o bool @@ -163,102 +426,168 @@ the following types: \o QSize, QSizeF \o QRect, QRectF \o QVariant +\o QObject* +\o Enumerations declared with Q_ENUMS() \endlist -This example toggles the "Stopwatch" object on/off when the MouseArea is clicked: +To allow a custom C++ type to be created or used in QML, the C++ class must be registered as a QML +type using qmlRegisterType(), as shown in the \l {Defining new QML elements} section above. -\table -\row -\o -\c {// main.cpp} -\snippet doc/src/snippets/declarative/qtbinding/stopwatch/stopwatch.h 0 -\snippet doc/src/snippets/declarative/qtbinding/stopwatch/main.cpp 0 -\o -\c {// main.qml} -\snippet doc/src/snippets/declarative/qtbinding/stopwatch/main.qml 0 +\section2 Using enumerations of a custom type -\endtable +To use an enumeration from a custom C++ component, the enumeration must be declared with Q_ENUMS() to +register it with Qt's meta object system. For example, the following C++ type has a \c Status enum: -Note that in this particular example a better way to achieve the same result -is to have a "running" property in \c main.qml. This leads to much nicer QML code: +\snippet doc/src/snippets/declarative/qtbinding/enums/imageviewer.h start +\snippet doc/src/snippets/declarative/qtbinding/enums/imageviewer.h end + +Providing the \c ImageViewer class has been registered using qmlRegisterType(), its \c Status enum can +now be used from QML: + +\snippet doc/src/snippets/declarative/qtbinding/enums/standalone.qml 0 + +The C++ type must be registered with QML to use its enums. If your C++ type is not instantiable, it +can be registered using qmlRegisterUncreatableType(). + +See the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} tutorial and +the \l {Extending QML in C++} reference documentation for more information. + + +\section2 Automatic type conversion + +As a convenience, some basic types can be specified in QML using format strings to make it easier to +pass simple values from QML to C++. \table +\header +\o Type +\o String format +\o Example \row -\o -\code -// main.qml -import QtQuick 1.0 - -Rectangle { - MouseArea { - anchors.fill: parent - onClicked: stopwatch.running = !stopwatch.running - } -} -\endcode +\o QColor +\o Color name, "#RRGGBB", "#RRGGBBAA" +\o "red", "#ff0000", "#ff000000" +\row +\o QDate +\o "YYYY-MM-DD" +\o "2010-05-31" +\row +\o QPoint +\o "x,y" +\o "10,20" +\row +\o QRect +\o "x,y,WidthxHeight" +\o "50,50,100x100" +\row +\o QSize +\o "WidthxHeight" +\o "100x200" +\row +\o QTime +\o "hh:mm:ss" +\o "14:22:55" +\row +\o QUrl +\o URL string +\o "http://www.example.com" +\row +\o QVector3D +\o "x,y,z" +\o "0,1,0" +\row +\o Enumeration value +\o Enum value name +\o "AlignRight" \endtable -Of course, it is also possible to call \l {Adding new methods}{functions declared in QML from C++}. +(More details on these string formats and types can be found in the +\l {QML Basic Types}{basic type documentation}.) + +These string formats can be used to set QML \c property values and pass arguments to C++ +functions. This is demonstrated by various examples on this page; in the above +\l{#properties-cpp}{Qt properties example}, the \c ApplicationData class has a \c backgroundColor +property of a QColor type, which is set from the QML code with the string "red" rather rather +than an actual QColor object. + +If it is preferred to pass an explicitly-typed value rather than a string, the global +\l{QmlGlobalQtObject}{Qt object} provides convenience functions for creating some of the object +types listed above. For example, \l{QML:Qt::rgba()}{Qt.rgba()} creates a QColor value from four +RGBA values. The QColor returned from this function could be used instead of a string to set +a QColor-type property or to call a C++ function that requires a QColor parameter. + + +\section1 Writing QML plugins + +The QtDeclarative module includes the QDeclarativeExtensionPlugin class, which is an abstract +class for writing QML plugins. This allows QML extension types to be dynamically loaded into +QML applications. + +See the QDeclarativeExtensionPlugin documentation and \l {How to Create Qt Plugins} for more +details. + + +\section1 Managing resource files with the Qt resource system +The \l {The Qt Resource System}{Qt resource system} allows resource files to be stored as +binary files in an application executable. This can be useful when building a mixed +QML/C++ application as it enables QML files (as well as other resources such as images +and sound files) to be referred to through the resource system URI scheme rather than +relative or absolute paths to filesystem resources. Note, however, that if you use the resource +system, the application executable must be re-compiled whenever a QML source file is changed +in order to update the resources in the package. -\section1 Network Components +To use the resource system in a mixed QML/C++ application: -If the URL passed to QDeclarativeComponent is a network resource, or if the QML document references a -network resource, the QDeclarativeComponent has to fetch the network data before it is able to create -objects. In this case, the QDeclarativeComponent will have a \l {QDeclarativeComponent::Loading}{Loading} -\l {QDeclarativeComponent::status()}{status}. An application will have to wait until the component -is \l {QDeclarativeComponent::Ready}{Ready} before calling \l {QDeclarativeComponent::create()}. +\list +\o Create a \c .qrc \l {The Qt Resource System}{resource collection file} that lists resource + files in XML format +\o From C++, load the main QML file as a resource using the \c :/ prefix or as a URL with the + \c qrc scheme +\endlist + +Once this is done, all files specified by relative paths in QML will be loaded from +the resource system instead. Use of the resource system is completely transparent to +the QML layer; this means all QML code should refer to resource files using relative +paths and should \e not use the \c qrc scheme. This scheme should only be used from +C++ code for referring to resource files. -The following example shows how to load a QML file from a network resource. After creating -the QDeclarativeComponent, it tests whether the component is loading. If it is, it connects to the -QDeclarativeComponent::statusChanged() signal and otherwise calls the \c {continueLoading()} method -directly. This test is necessary, even for URLs that are known to be remote, just in case -the component has been cached and is ready immediately. +Here is a application packaged using the \l {The Qt Resource System}{Qt resource system}. +The directory structure looks like this: \code -MyApplication::MyApplication() -{ - // ... - component = new QDeclarativeComponent(engine, QUrl("http://www.example.com/main.qml")); - if (component->isLoading()) - QObject::connect(component, SIGNAL(statusChanged(QDeclarativeComponent::Status)), - this, SLOT(continueLoading())); - else - continueLoading(); -} - -void MyApplication::continueLoading() -{ - if (component->isError()) { - qWarning() << component->errors(); - } else { - QObject *myObject = component->create(); - } -} +project + |- example.qrc + |- main.qml + |- images + |- background.png + |- main.cpp + |- project.pro \endcode -\section1 Qt Resources +The \c main.qml and \c background.png files will be packaged as resource files. This is +done in the \c example.qrc resource collection file: -QML content can be loaded from \l {The Qt Resource System} using the \e qrc: URL scheme. -For example: +\quotefile doc/src/snippets/declarative/qtbinding/resources/example.qrc -\c [project/example.qrc] -\quotefile doc/src/snippets/declarative/qtbinding/resources/example.qrc +Since \c background.png is a resource file, \c main.qml can refer to it using the relative +path specified in \c example.qrc: + +\snippet doc/src/snippets/declarative/qtbinding/resources/main.qml 0 -\c [project/project.pro] -\quotefile doc/src/snippets/declarative/qtbinding/resources/resources.pro +To allow QML to locate resource files correctly, the \c main.cpp loads the main QML +file, \c main.qml, as a resource file using the \c qrc scheme: -\c [project/main.cpp] \snippet doc/src/snippets/declarative/qtbinding/resources/main.cpp 0 -\c [project/main.qml] -\snippet doc/src/snippets/declarative/qtbinding/resources/main.qml 0 +Finally \c project.pro uses the RESOURCES variable to indicate that \c example.qrc should +be used to build the application resources: + +\quotefile doc/src/snippets/declarative/qtbinding/resources/resources.pro + +See \l {The Qt Resource System} for more information. -Note that the resource system cannot be accessed from QML directly. If the main QML file is -loaded as a resource, all files specified as relative paths in QML will also be loaded from -the resource system. Using the resource system is completely transparent to the QML layer. -This also means that if the main QML file is not loaded as a resource then files in the resource -system cannot be accessed from QML. */ + |