diff options
Diffstat (limited to 'doc/src/qml/qmlengine.qdoc')
| -rw-r--r-- | doc/src/qml/qmlengine.qdoc | 481 |
1 files changed, 0 insertions, 481 deletions
diff --git a/doc/src/qml/qmlengine.qdoc b/doc/src/qml/qmlengine.qdoc deleted file mode 100644 index ad77d43cb5..0000000000 --- a/doc/src/qml/qmlengine.qdoc +++ /dev/null @@ -1,481 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** GNU Free Documentation License -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\target qmlengine -\page qmlengine.html -\ingroup qml-features -\title The QML Engine -\brief the engine runs QML applications - -The QML engine runs and executes QML -applications. The engine loads, instantiates, and executes the QML context as -specified in QML files, plugins, or applications. - -\section1 Core Module Classes - - The \l{QtQml}{Qt Declarative} 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 Qt Declarative module - that provide the essential capabilities for doing this. These are: - - \list - \li QQmlEngine: A QML engine provides the environment for executing QML code. Every - application requires at least one engine instance. - \li QQmlComponent: A component encapsulates QML information. - \li QQmlContext: A context allows an application to expose data to - the QML components created by an engine. - \endlist - - The Qt Declarative module consists of the engine, - context, component encapsulation, and visual items. - - \list - \li QQuickItem - \li QQuickPaintedItem - \li QQuickView - \endlist - - \section2 Declarative Engine - A QQmlEngine 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. - - QQmlComponent is used to load QML documents. Each - QQmlComponent 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 QQmlComponent::create() method, like this: - - \code - QQmlEngine engine; - QQmlComponent component(&engine, QUrl::fromLocalFile("MyRectangle.qml")); - QObject *rectangleInstance = component.create(); - - // ... - delete rectangleInstance; - \endcode - - QML documents can also be loaded using QQuickView. 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 Code with - existing Qt UI code}.) - -\section1 Engine and Context Initialization - - \section2 Loading QML Components from C++ - - A QML document can be loaded with QQmlComponent or QQuickView. - QQmlComponent loads a QML component as a C++ object; - QQuickView 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/qml/qtbinding/loading/MyItem.qml start - \snippet doc/src/snippets/qml/qtbinding/loading/MyItem.qml end - - This QML document can be loaded with QQmlComponent or - QQuickView with the following C++ code. Using a QQmlComponent - requires calling QQmlComponent::create() to create a new instance of - the component, while a QQuickView automatically creates an instance of - the component, which is accessible via QQuickView::rootObject(): - - \table - \row - \li - \snippet doc/src/snippets/qml/qtbinding/loading/main.cpp QQmlComponent-a - \dots 0 - \snippet doc/src/snippets/qml/qtbinding/loading/main.cpp QQmlComponent-b - \li - \snippet doc/src/snippets/qml/qtbinding/loading/main.cpp QQuickView - \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 QQmlProperty: - - \snippet doc/src/snippets/qml/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 QQuickItem class: - - \snippet doc/src/snippets/qml/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/qml/qtbinding/loading/MyItem.qml start - \codeline - \snippet doc/src/snippets/qml/qtbinding/loading/MyItem.qml child - \snippet doc/src/snippets/qml/qtbinding/loading/MyItem.qml end - - The child could be located like this: - - \snippet doc/src/snippets/qml/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. QQmlContext 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/qml/qtbinding/context/MyItem.qml 0 - - This \c currentDateTime value can be set directly by the C++ application - that loads the QML component, using - QQmlContext::setContextProperty(): - - \snippet doc/src/snippets/qml/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 - \li - \snippet doc/src/snippets/qml/qtbinding/context-advanced/applicationdata.h 0 - \codeline - \snippet doc/src/snippets/qml/qtbinding/context-advanced/main.cpp 0 - \li - \snippet doc/src/snippets/qml/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/qml/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 QQmlContext documentation for more information. - - -\section1 Invoking QML Entities through the Engine - - 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++. - - The \l{Creating QML Types} article covers the topic of exposing Qt functions - and properties to the declarative engine. - - \section2 Calling Functions - - QML functions can be called from C++ and vice-versa. - - 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: - - \table - \row - \li \snippet doc/src/snippets/qml/qtbinding/functions-qml/MyItem.qml 0 - \li \snippet doc/src/snippets/qml/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 QQmlContext::setContextProperty(): - - \table - \row - \li - \snippet doc/src/snippets/qml/qtbinding/functions-cpp/MyItem.qml 0 - \li - \snippet doc/src/snippets/qml/qtbinding/functions-cpp/myclass.h 0 - \codeline - \snippet doc/src/snippets/qml/qtbinding/functions-cpp/main.cpp 0 - \endtable - - QML supports the calling of overloaded C++ functions. If there are multiple - C++ functions with the same name but different arguments, the correct - function will be called according to the number and the types of arguments - that are provided. - - - \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. In return, any C++ - signal can be received by a QML object using \l {Signal Handlers}{signal - handlers}. - - Here is a QML component with a signal named \c qmlSignal. This signal is - connected to a C++ object's slot using QObject::connect(), so that the \c - cppSlot() method is called whenever the \c qmlSignal is emitted: - - \table - \row - \li - \snippet doc/src/snippets/qml/qtbinding/signals-qml/MyItem.qml 0 - \li - \snippet doc/src/snippets/qml/qtbinding/signals-qml/myclass.h 0 - \codeline - \snippet doc/src/snippets/qml/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 - \li - - \snippet doc/src/snippets/qml/qtbinding/signals-cpp/imageviewer.h start - \dots 4 - \snippet doc/src/snippets/qml/qtbinding/signals-cpp/imageviewer.h end - - \li - \snippet doc/src/snippets/qml/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 - QQmlContext::setContextProperty() - then the \l Connections element - can be used instead to create the signal handler: - - \table - \row - \li \snippet doc/src/snippets/qml/qtbinding/signals-cpp/main.cpp connections - \li \snippet doc/src/snippets/qml/qtbinding/signals-cpp/MyItem.qml 0 - \endtable - - C++ signals can use enum values as parameters provided that the enum is - declared in the class that is emitting the signal, and that the enum is - registered using Q_ENUMS. See \l {Using enumerations of a custom type} below - for details. - - - \section2 Modifying Properties - - Any properties declared in a QML object are automatically accessible from - C++. Given a QML item like this: - - \snippet doc/src/snippets/qml/qtbinding/properties-qml/MyItem.qml 0 - - The value of the \c someNumber property can be set and read using - QQmlProperty, or QObject::setProperty() and QObject::property(): - - \snippet doc/src/snippets/qml/qtbinding/properties-qml/main.cpp 0 - - You should always use QObject::setProperty(), QQmlProperty 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: - - \badcode - // BAD! - QQmlComponent component(engine, "MyButton.qml"); - PushButton *button = qobject_cast<PushButton*>(component.create()); - button->m_buttonText = "Click me"; - \endcode - 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. - - \target properties-cpp - - 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: - - \table - \row - \li \snippet doc/src/snippets/qml/qtbinding/properties-cpp/applicationdata.h 0 - \li \snippet doc/src/snippets/qml/qtbinding/properties-cpp/MyItem.qml 0 - \endtable - - 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. - - The \l{Creating QML Types} article covers the topic of exposing Qt - properties to the runtime. For more information, the - \l{Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} - tutorial demonstrates basic usage patterns. - -\section1 Loading QML Plugins - - Additional Qt code is runnable in the engine as a QML plugin. The \l{QML - Plugins} article covers the creation and usage patterns of QML plugins. The - QQmlExtensionPlugin class is an abstract class for writing QML - plugins. The \l {How to Create Qt Plugins} contains more information about - Qt's plugin system. - -\target qml-engine-optimization -\section1 Optimization - - Often, to develop high performance elements it is helpful to know more about - the status of the QML engine. For example, it might be beneficial to delay - initializing some costly data structures until after all the properties have - been set. - - The QML engine defines an interface class called QQmlParserStatus, - which contains a number of virtual methods that are invoked at various - stages during component instantiation. To receive these notifications, an - element implementation inherits QQmlParserStatus and notifies the Qt - meta system using the Q_INTERFACES() macro. - - \code - class Example : public QObject, public QQmlParserStatus - { - Q_OBJECT - Q_INTERFACES(QQmlParserStatus) - public: - virtual void componentComplete() - { - qDebug() << "Woohoo! Now to do my costly initialization"; - } - }; - \endcode - -\section1 Memory Management and QVariant types - - It is a component's responsibility to ensure that it does not access or - return pointers to invalid objects. QML makes the following guarentees: - - \list - \li An object assigned to a QObject (or QObject-derived) pointer property - will be valid at the time of assignment. - - Following assignment, it is the responsibility of the class to subsequently - guard this pointer, either through a class specific method or the generic - QPointer class. - - \li An object assigned to a QVariant will be valid at the time of assignment. - - When assigning an object to a QVariant property, QML will always use a - QMetaType::QObjectStar typed QVariant. It is the responsibility of the class - to guard the pointer. A general rule when writing a class that uses QVariant - properties is to check the type of the QVariant when it is set and if the - type is not handled by your class, reset it to an invalid variant. - - \li An object assigned to a QObject (or QObject-derived) list property will - be valid at the time of assignment. - - Following assignment, it is the responsibility of the class to subsequently - guard this pointer, either through a class specific method or the generic - QPointer class. - \endlist - - Components should assume that any QML assigned object can be deleted at any - time, and respond accordingly. If documented as such an element need not - continue to work in this situation, but it must not crash. - -\section1 JavaScript Runtime - - The runtime implements the \l{ECMA-262}{ECMAScript Language Specification} standard, - 5th edition. The reserved words, conditionals, variables, and object behaviors - follow after the standard. - - The \l{QML JavaScript Host Environment} article has information about the - JavaScript host environment provided by QML, which is different than the - browser host environment many are familiar with. - - The \l{JavaScript Code} article has information about placing JavaScript - code within QML code. - -*/ |