[come from https://qt-project.org/doc/qt-4.7/qtbinding.html#id-ecf5bb93-5bc5-4bb7-a19f-3af4c4d9338e]


QML is designed to be easily extensible toand from C++. The classes in the Qt Declarative module allow QML components tobe loaded and manipulated from C++, and through Qt's meta-object system,QML and C++ objects can easily communicate through Qt signals and slots. Inaddition, QML plugins can be written to create reusable QML components fordistribution.

You may want to mix QML and C++ for anumber of reasons. For example:

·        To use functionality defined in a C++source (for example, when using a C++ Qt-based data model, or calling functionsin a third-party C++ library)

·        To access functionality in the QtDeclarative module (for example, to dynamically generate p_w_picpaths usingQDeclarativeImageProvider)

·        To write your own QML elements (whether foryour applications, or for distribution to others)

To use the Qt Declarative module, you mustinclude and link to the module appropriately, as shown on the module index page.The Qt Declarative UI Runtime documentation shows howto build a basic C++ application that uses this module.

Core module classes

The Qt Declarative module provides a set ofC++ APIs for extending your QML applications from C++ and embedding QML intoC++ applications. There are several core classes in the Qt Declarative modulethat provide the essential capabilities for doing this. These are:

·        QDeclarativeEngine:A QML engine provides the environment for executing QML code. Every applicationrequires at least one engine instance.

·        QDeclarativeComponent:A component encapsulates a QML document.

·        QDeclarativeContext:A context allows an application to expose data to the QML components created byan engine.

A QDeclarativeEngine allows the configurationof global settings that apply to all of its QML component instances: forexample, the QNetworkAccessManager to be used for networkcommunications, and the file path to be used for persistent storage.

QDeclarativeComponent is used to load QML documents.Each QDeclarativeComponent instance represents asingle document. A component can be created from the URL or file path of a QMLdocument, or the raw QML code of the document. Component instances areinstatiated through theQDeclarativeComponent::create()method, like this:

1.   QDeclarativeEngine engine;

2.   QDeclarativeComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml"));

3.   QObject *rectangleInstance = component.create();

4.    

5.   //...

6.   delete rectangleInstance;

QML documents can also be loaded using QDeclarativeView.This class provides a convenient QWidget-based viewfor embedding QML components into QGraphicsView-basedapplications. (For other methods of integrating QML into QWidget-basedapplications, see Integrating QML Code withexisting Qt UI code.)

Approaches to using QML with C++

There are a number of ways to extend yourQML application through C++. For example, you could:

·        Load a QML component and manipulate it (orits children) from C++

·        Embed a C++ object and its propertiesdirectly into a QML component (for example, to make a particular C++ objectcallable from QML, or to replace a dummy list model with a real data set)

·        Define new QML elements (through QObject-based C++classes) and create them directly from your QML code

These methods are shown below. Naturallythese approaches are not exclusive; you can mix any of these methods throughoutyour application as appropriate.

Loading QML componentsfrom C++

A QML document can be loaded with QDeclarativeComponent or QDeclarativeView. QDeclarativeComponentloadsa QML component as a C++ object; QDeclarativeView also does this, butadditionally loads the QML component directly into a QGraphicsView. It isconvenient for loading a displayable QML component into a QWidget-basedapplication.

For example, suppose there is a MyItem.qml file that looks likethis:

1.   import QtQuick 1.0

2.    

3.   Item  {

4.       width: 100; height: 100

5.   }

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 aninstance of the component, which is accessible via QDeclarativeView::rootObject():

1.   //Using QDeclarativeComponent

2.   QDeclarativeEngine engine;

3.   QDeclarativeComponent component(&engine,

4.          QUrl::fromLocalFile("MyItem.qml"));

5.   QObject *object =component.create();

6.   ...

       delete object;

1. // Using QDeclarativeView

2. QDeclarativeView view;

3. view.setSource(QUrl::fromLocalFile("MyItem.qml"));

4. view.show();

5. QObject *object = view.rootObject();

This object is the instance of the MyItem.qml component that has beencreated. You can now modify the item's properties using QObject::setProperty()or QDeclarativeProperty:

1.   object->setProperty("width", 500);

2.   QDeclarativeProperty(object, "width").write(500);

Alternatively, you can cast the object toits actual type and call functions with compile-time safety. In this case thebase object of MyItem.qml is an Item, which isdefined by theQDeclarativeItem class:

1.                  QDeclarativeItem *item = qobject_cast<QDeclarativeItem*>(object);

2.   item->setWidth(500);

You can also connect to any signals or callfunctions defined in the component usingQMetaObject::invokeMethod()and QObject::connect().See Exchanging data between QML andC++ below for further details.

Locating child objects

QML components are essentially object treeswith children that have siblings and their own children. Child objects of QMLcomponents can be located using the QObject::objectName property withQObject::findChild().For example, if the root item in MyItem.qml had a child Rectangle item:

1.   import QtQuick 1.0

2.    

3.   Item  {

4.       width: 100; height: 100

5.    

6.       Rectangle  {

7.           anchors.fill: parent

8.           objectName: "rect"

9.       }

10.  }

The child could be located like this:

1.                  QObject *rect = object->findChild<QObject*>("rect");

2.   if (rect)

3.       rect->setProperty("color", "red");

If objectName is used inside a delegateof a ListView, Repeater or some other elementthat creates multiple instances of its delegates, there will be multiplechildren with the same objectName. In this case, QObject::findChildren()can be used to find all children with a matching objectName.

Warning: While it is possible touse C++ to access and manipulate QML objects deep into the object tree, werecommend that you do not take this approach outside of application testing andprototyping. One strength of QML and C++ integration is the ability toimplement the QML user interface separately from the C++ logic and datasetbackend, and this strategy breaks if the C++ side reaches deep into the QMLcomponents to manipulate them directly. This would make it difficult to, forexample, swap a QML view component for another view, if the new component wasmissing a required objectName. It is better for theC++ implementation to know as little as possible about the QML user interfaceimplementation and the composition of the QML object tree.

Embedding C++ objectsinto 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 exposingdata to the context of a QML component, allowing data to be injected from C++into QML.

For example, here is a QML item that refersto a currentDateTime value that does not existin the current scope:

1.   //MyItem.qml

2.   import QtQuick 1.0

3.    

4.   Text  { text: currentDateTime }

This currentDateTime value can be set directlyby the C++ application that loads the QML component, using QDeclarativeContext::setContextProperty():

1.                  QDeclarativeView view;

2.   view.rootContext()->setContextProperty("currentDateTime", QDateTime::currentDateTime());

3.   view.setSource(QUrl::fromLocalFile("MyItem.qml"));

4.   view.show();

Context properties can hold either QVariant or QObject* values.This means custom C++ objects can also be injected using this approach, andthese objects can be modified and read directly in QML. Here, we modify theabove example to embed a QObject instance instead of a QDateTime value, and the QML codeinvokes a method on the object instance:

1.   class ApplicationData : public QObject

2.    {

3.       Q_OBJECT

4.   public:

5.       Q_INVOKABLE QDateTime getCurrentDateTime()const  {

6.           return QDateTime::currentDateTime();

7.       }

8.   };

9.    

10.  int main(int argc, char *argv[])  {

11.      QApplication app(argc, argv);

12.   

13.      QDeclarativeView view;

14.   

15.      ApplicationData data;

16.      view.rootContext()->setContextProperty("applicationData", &data);

17.   

18.      view.setSource(QUrl::fromLocalFile("MyItem.qml"));

19.      view.show();

20.   

21.      return app.exec();

       }

1.   //MyItem.qml

2.   import QtQuick 1.0

3.   Text  { text:applicationData.getCurrentDateTime()}

(Note that date/time values returned fromC++ to QML can be formatted through Qt.formatDateTime() and associatedfunctions.)

If the QML item needs to receive signalsfrom the context property, it can connect to them using theConnections element. For example, if ApplicationData has a signal named dataChanged(), this signal can beconnected to using an onDataChanged handler within a Connections object:

1.                  Text  {

2.       text: applicationData.getCurrentDateTime()

3.    

4.       Connections  {

5.           target: applicationData

6.           onDataChanged: console.log("Theapplication data changed!")

7.       }

8.   }

Context properties can be useful for usingC++ based data models in a QML view. See the String ListModel, Object ListModel and AbstractItemModel models for respectiveexamples on usingQStringListModel, QObjectList-basedmodels and QAbstractItemModel in QML views.

Also see the QDeclarativeContext documentation for moreinformation.

Defining new QML elements

While new QML elements can be defined in QML, theycan also be defined by C++ classes; in fact, many of the core QML Elements are implemented throughC++ classes. When you create a QML object using one of these elements, you aresimply creating an instance of a QObject-based C++class and setting its properties.

To create a visual item that fits in withthe Qt Quick elements, base your class off QDeclarativeIteminsteadof QObject directly. You can thenimplement your own painting and functionality like any other QGraphicsObject.Note that QGraphicsItem::ItemHasNoContents is set by default onQDeclarativeItem because it does not paintanything; you will need to clear this if your item is supposed to paintanything (as opposed to being solely for input handling or logical grouping).

For example, here is an ImageViewer class with an p_w_picpath URL property:

1.   #include<QtCore>

2.   #include<QtDeclarative>

3.    

4.   class ImageViewer : public QDeclarativeItem

5.    {

6.       Q_OBJECT

7.       Q_PROPERTY(QUrl p_w_picpath READ p_w_picpath WRITE setImage NOTIFYp_w_picpathChanged)

8.    

9.   public:

10.      void setImage(const QUrl &url);

11.      QUrl p_w_picpath() const;

12.   

13.  signals:

14.      void p_w_picpathChanged();

15.  };

Aside from the fact that it inherits QDeclarativeItem,this is an ordinary class that could exist outside of QML. However, once it isregistered with the QML engine using qmlRegisterType():

1.   qmlRegisterType<ImageViewer>("MyLibrary", 1, 0, "ImageViewer");

Then, any QML code loaded by your C++application or plugin can create and manipulate ImageViewerobjects:

1.   import MyLibrary 1.0

2.    

3.   ImageViewer  { p_w_picpath: "smile.png" }

It is advised that you avoid using QGraphicsItem functionality beyond theproperties documented inQDeclarativeItem.This is because the GraphicsView backend is intended to bean implementation detail for QML, so the QtQuick items can be moved to fasterbackends as they become available with no change from a QML perspective. Tominimize any porting requirements for custom visual items, try to stick to thedocumented properties in QDeclarativeItem where possible.Properties QDeclarativeItem inherits but doesn'tdocument are classed as implementation details; they are not officiallysupported and may disappear between releases.

Note that custom C++ types do not have toinherit from QDeclarativeItem;this is only necessary if it is a displayable item. If the item is notdisplayable, it can simply inherit from QObject.

For more information on defining new QMLelements, see the Writing QML extensions with C++ tutorial and the Extending QML Functionalitiesusing C++ reference documentation.