diff options
Diffstat (limited to 'doc/src/declarative')
27 files changed, 182 insertions, 165 deletions
diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index d80c3fa..2b75211 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlanimation.html +\page qdeclarativeanimation.html \title QML Animation Animation in QML is done by animating properties of objects. Properties of type @@ -72,9 +72,9 @@ Rectangle { y: 0 y: SequentialAnimation { repeat: true - NumberAnimation { to: 200-img.height; easing: "easeOutBounce"; duration: 2000 } + NumberAnimation { to: 200-img.height; easing.type: "OutBounce"; duration: 2000 } PauseAnimation { duration: 1000 } - NumberAnimation { to: 0; easing: "easeOutQuad"; duration: 1000 } + NumberAnimation { to: 0; easing.type: "OutQuad"; duration: 1000 } } } } @@ -135,7 +135,7 @@ transitions: [ Transition { NumberAnimation { properties: "x,y" - easing: "easeOutBounce" + easing.type: "OutBounce" duration: 200 } } @@ -156,7 +156,7 @@ Transition { SequentialAnimation { NumberAnimation { duration: 1000 - easing: "easeOutBounce" + easing.type: "OutBounce" // animate myItem's x and y if they have changed in the state target: myItem properties: "x,y" @@ -198,7 +198,7 @@ Transition { ParallelAnimation { NumberAnimation { duration: 1000 - easing: "easeOutBounce" + easing.type: "OutBounce" targets: box1 properties: "x,y" } @@ -226,7 +226,7 @@ Rectangle { id: redRect color: "red" width: 100; height: 100 - x: Behavior { NumberAnimation { duration: 300; easing: "InOutQuad" } } + x: Behavior { NumberAnimation { duration: 300; easing.type: "InOutQuad" } } } \endqml diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index a260812..c60847e 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! - \page qmlbasictypes.html + \page qdeclarativebasictypes.html \title QML Basic Types QML uses a set of property types, which are primitive within QML. diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 1129f00..4b61bd9 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -88,10 +88,10 @@ completely new applications. QML is fully \l {Extending QML}{extensible from C+ \o \l {Network Transparency} \o \l {Data Models} \o \l {anchor-layout.html}{Anchor-based Layout} -\o \l {qmlstates.html}{States} -\o \l {qmlanimation.html}{Animation} -\o \l {qmlmodules.html}{Modules} -\o \l {qmlfocus.html}{Keyboard Focus} +\o \l {qdeclarativestates.html}{States} +\o \l {qdeclarativeanimation.html}{Animation} +\o \l {qdeclarativemodules.html}{Modules} +\o \l {qdeclarativefocus.html}{Keyboard Focus} \o \l {Extending types from QML} \o \l {Dynamic Object Creation} \endlist diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index 7a489c0..033c0d1 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmldynamicobjects.html +\page qdeclarativedynamicobjects.html \title Dynamic Object Management QML has some support for dynamically loading and managing QML objects from @@ -139,7 +139,7 @@ will not have an id in QML. A restriction which you need to manage with dynamically created items, is that the creation context must outlive the -created item. The creation context is the QmlContext in which createComponent +created item. The creation context is the QDeclarativeContext in which createComponent was called, or the context in which the Component element, or the item used as the second argument to createQmlObject, was specified. If the creation context is destroyed before the dynamic item is, then bindings in the dynamic item will diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index 682a2ac..1fd4dad 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlelements.html +\page qdeclarativeelements.html \target elements \title QML Elements @@ -88,6 +88,8 @@ The following table lists the QML elements provided by the Qt Declarative module \o \l Binding \o \l ListModel, \l ListElement \o \l VisualItemModel +\o \l VisualDataModel +\o \l Package \o \l XmlListModel and XmlRole \o \l DateTimeFormatter \o \l NumberFormatter @@ -96,7 +98,7 @@ The following table lists the QML elements provided by the Qt Declarative module \o \list \o \l Script -\o \l Connection +\o \l Connections \o \l Component \o \l Timer \o \l QtObject diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc index d1b1066..42351c5 100644 --- a/doc/src/declarative/example-slideswitch.qdoc +++ b/doc/src/declarative/example-slideswitch.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlexampletoggleswitch.html +\page qdeclarativeexampletoggleswitch.html \title QML Example - Toggle Switch This example shows how to create a reusable switch component in QML. @@ -121,7 +121,7 @@ states (\e on and \e off). This second function is called when the knob is released and we want to make sure that the knob does not end up between states (neither \e on nor \e off). If it is the case call the \c toggle() function otherwise we do nothing. -For more information on scripts see \l{qmljavascript.html}{JavaScript Blocks}. +For more information on scripts see \l{qdeclarativejavascript.html}{JavaScript Blocks}. \section2 Transition \snippet examples/declarative/slideswitch/content/Switch.qml 7 diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc index 0478731..b7da508 100644 --- a/doc/src/declarative/examples.qdoc +++ b/doc/src/declarative/examples.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlexamples.html +\page qdeclarativeexamples.html \title QML Examples and Walkthroughs \section1 Running Examples and Demos @@ -77,7 +77,7 @@ These will be documented, and demonstrate how to achieve various things in QML. \o Elastic Dial \o \image dial-example.gif \row - \o \l{qmlexampletoggleswitch.html}{Toggle Switch} + \o \l{qdeclarativeexampletoggleswitch.html}{Toggle Switch} \o \image switch-example.gif \row \o \l{QML Advanced Tutorial}{SameGame} diff --git a/doc/src/declarative/extending-examples.qdoc b/doc/src/declarative/extending-examples.qdoc index b84ae0e..cc66838 100644 --- a/doc/src/declarative/extending-examples.qdoc +++ b/doc/src/declarative/extending-examples.qdoc @@ -69,7 +69,7 @@ Q_DECLARE_METATYPE() functionality. The Person class implementation is quite basic. The property accessors simply return members of the object instance. -The implementation must also include the QML_DEFINE_TYPE() macro. This macro +The implementation must also be registered using the QML_REGISTER_TYPE() macro. This macro registers the Person class with QML as a type in the People library version 1.0, and defines the mapping between the C++ and QML class names. @@ -108,11 +108,11 @@ The class contains a member to store the celebrant object, and also a QList<Person *> member. In QML, the type of a list properties - and the guests property is a list of -people - are all of type QmlListProperty<T>. QmlListProperty is simple value +people - are all of type QDeclarativeListProperty<T>. QDeclarativeListProperty is simple value type that contains a set of function pointers. QML calls these function pointers whenever it needs to read from, write to or otherwise interact with the list. In addition to concrete lists like the people list used in this -example, the use of QmlListProperty allows for "virtual lists" and other advanced +example, the use of QDeclarativeListProperty allows for "virtual lists" and other advanced scenarios. \section2 Define the BirthdayParty @@ -160,13 +160,13 @@ previous example. However, as we have repurposed the People class as a common base for Boy and Girl, we want to prevent it from being instantiated from QML directly - an explicit Boy or Girl should be instantiated instead. -\snippet examples/declarative/extending/coercion/person.cpp 0 +\snippet examples/declarative/extending/coercion/main.cpp 0 While we want to disallow instantiating Person from within QML, it still needs to be registered with the QML engine, so that it can be used as a property type and other types can be coerced to it. To register a type, without defining a -named mapping into QML, we use the QML_DEFINE_NOCREATE_TYPE() macro instead of -the QML_DEFINE_TYPE() macro used previously. +named mapping into QML, we call the QML_REGISTER_NOCREATE_TYPE() macro instead of +the QML_REGISTER_TYPE() macro used previously. \section2 Define Boy and Girl diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 0456f3f..5aaa7bd 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -72,24 +72,23 @@ Custom C++ types are made available to QML using these two macros: \quotation \code #define QML_DECLARE_TYPE(T) -#define QML_DEFINE_TYPE(URI,VMAJ,VMIN,QmlName,T) +#define QML_REGISTER_TYPE(URI,VMAJ,VMIN,QDeclarativeName,T) \endcode Register the C++ type \a T with the QML system, and make it available in QML -under the name \a QmlName in library URI version VMAJ.VMIN. -\a T and \a QmlName may be the same. +under the name \a QDeclarativeName in library URI version VMAJ.VMIN. +\a T and \a QDeclarativeName may be the same. Generally the QML_DECLARE_TYPE() macro should be included immediately following -the type declaration (usually in its header file), and the QML_DEFINE_TYPE() -macro in the implementation file. QML_DEFINE_TYPE() must not be present in -a header file. +the type declaration (usually in its header file), and the QML_REGISTER_TYPE() +macro called by the implementation. Type \a T must be a concrete type that inherits QObject and has a default constructor. \endquotation Types can be registered by libraries (such as Qt does), application code, -or by plugins (see QmlModulePlugin). +or by plugins (see QDeclarativeExtensionPlugin). Once registered, all of the \l {Qt's Property System}{properties} of a supported type are available for use within QML. QML has intrinsic support for properties @@ -153,15 +152,14 @@ from registering a new QML type. The following macros are used instead: \quotation \code #define QML_DECLARE_INTERFACE(T) - #define QML_DEFINE_INTERFACE(T) + #define QML_REGISTER_INTERFACE(T) \endcode Register the C++ interface \a T with the QML system. Generally the QML_DECLARE_INTERFACE() macro should be included immediately following the interface declaration (usually in its header file), and the -QML_DEFINE_INTERFACE() macro in an implementation file. QML_DEFINE_INTERFACE() -must not be present in a header file. +QML_REGISTER_INTERFACE() macro called by the implementation. Following registration, QML can coerce objects that implement this interface for assignment to appropriately typed properties. @@ -169,7 +167,7 @@ for assignment to appropriately typed properties. The guests property is a list of \c Person objects. Properties that are lists of objects or Qt interfaces are also declared with the Q_PROPERTY() macro, just -like other properties. List properties must have the type \c {QmlListProperty<T>}. +like other properties. List properties must have the type \c {QDeclarativeListProperty<T>}. As with object properties, the type \a T must be registered with QML. The guest property declaration looks like this: @@ -194,7 +192,7 @@ type used in the previous section, but the assignment is valid as both the Boy and Girl objects inherit from Person. To assign to a property, the property's type must have been registered with QML. -Both the QML_DEFINE_TYPE() and QML_DEFINE_INTERFACE() macros already shown can +Both the QML_REGISTER_TYPE() and QML_REGISTER_INTERFACE() macros already shown can be used to register a type with QML. Additionally, if a type that acts purely as a base class that cannot be instantiated from QML needs to be registered these macros can be used: @@ -202,18 +200,17 @@ registered these macros can be used: \quotation \code #define QML_DECLARE_TYPE(T) - #define QML_DEFINE_NOCREATE_TYPE(T) + #define QML_REGISTER_NOCREATE_TYPE(T) \endcode -Register the C++ type \a T with the QML system. QML_DEFINE_NOCREATE_TYPE() -differs from QML_DEFINE_TYPE() in that it does not define a mapping between the +Register the C++ type \a T with the QML system. QML_REGISTER_NOCREATE_TYPE() +differs from QML_REGISTER_TYPE() in that it does not define a mapping between the C++ class and a QML element name, so the type is not instantiable from QML, but it is available for type coercion. Generally the QML_DECLARE_TYPE() macro should be included immediately following the type declaration (usually in its header file), and the -QML_DEFINE_NOCREATE_TYPE() macro in the implementation file. -QML_DEFINE_NOCREATE_TYPE() must not be present in a header file. +QML_REGISTER_NOCREATE_TYPE() macro called from the implementation. Type \a T must inherit QObject, but there are no restrictions on whether it is concrete or the signature of its constructor. @@ -375,6 +372,37 @@ object will only be returned if it has previously been created. \l {Extending QML - Attached Properties Example} shows the complete code used to implement the rsvp attached property. +\section1 Memory Management and QVariant types + +It is an elements responsibility to ensure that it does not access or return +pointers to invalid objects. QML makes the following guarentees: + +\list +\o An object assigned to an 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. + +\o 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. + +\o 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 + +Elements 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 Signal Support \snippet examples/declarative/extending/signal/example.qml 0 @@ -393,9 +421,8 @@ C++ signature: \snippet examples/declarative/extending/signal/birthdayparty.h 0 In classes with multiple signals with the same name, only the final signal -is accessible as a signal property. Although QML provides an element, -\l Connection, for accessing the other signals it is less elegant. For the best -QML API, class developers should avoid overloading signal names. +is accessible as a signal property. Note that signals with the same name +but different parameters cannot be distinguished. Signal parameters become accessible by name to the assigned script. An unnamed parameter cannot be accessed, so care should be taken to name all the @@ -433,8 +460,8 @@ 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 -QmlPropertyValueSource base class. This base class contains a single method, -QmlPropertyValueSource::setTarget(), that the QML engine invokes when +QDeclarativePropertyValueSource base class. This base class contains a single method, +QDeclarativePropertyValueSource::setTarget(), that the QML engine invokes when associating the property value source with a property. The relevant part of the HappyBirthday type declaration looks like this: @@ -526,18 +553,6 @@ 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 Binding and Script Properties - -While generally no changes are needed to a C++ class to use property -binding, sometimes more advanced interaction between the binding engine and -an object is desirable. To facilitate this, there is a special exception -in the bind engine for allowing an object to access the binding directly. - -If a binding is assigned to a property with a type of QmlBinding -pointer (ie. \c {QmlBinding *}), each time the binding value changes, -a QmlBinding instance is assigned to that property. The QmlBinding instance -allows the object to read the binding and to evaluate the binding's current value. - \section1 Extension Objects \snippet examples/declarative/extending/extended/example.qml 0 @@ -566,11 +581,11 @@ the appropriate property on the extension object is used instead. When an extended type is installed, one of the \code - #define QML_DEFINE_EXTENDED_TYPE(URI, VMAJ, VFROM, VTO, QmlName,T, ExtendedT) - #define QML_DEFINE_EXTENDED_NOCREATE_TYPE(T, ExtendedT) + #define QML_REGISTER_EXTENDED_TYPE(URI, VMAJ, VFROM, VTO, QDeclarativeName,T, ExtendedT) + #define QML_REGISTER_EXTENDED_NOCREATE_TYPE(T, ExtendedT) \endcode -macros should be used instead of the regular \c QML_DEFINE_TYPE or -\c QML_DEFINE_NOCREATE_TYPE. The arguments are identical to the corresponding +macros should be used instead of the regular \c QML_REGISTER_TYPE or +\c QML_REGISTER_NOCREATE_TYPE. The arguments are identical to the corresponding non-extension object macro, except for the ExtendedT parameter which is the type of the extension object. @@ -581,18 +596,18 @@ 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 QmlParserStatus, which contains a +The QML engine defines an interface class called QDeclarativeParserStatus, which contains a number of virtual methods that are invoked at various stages during component instantiation. To receive these notifications, an element implementation inherits -QmlParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro. +QDeclarativeParserStatus and notifies the Qt meta system using the Q_INTERFACES() macro. For example, \code -class Example : public QObject, public QmlParserStatus +class Example : public QObject, public QDeclarativeParserStatus { Q_OBJECT - Q_INTERFACES(QmlParserStatus) + Q_INTERFACES(QDeclarativeParserStatus) public: virtual void componentComplete() { diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc index 6459a2e..d7e890c 100644 --- a/doc/src/declarative/focus.qdoc +++ b/doc/src/declarative/focus.qdoc @@ -41,7 +41,7 @@ /*! \target qmlfocus -\page qmlfocus.html +\page qdeclarativefocus.html \title Keyboard Focus in QML When a key is pressed or released, a key event is generated and delivered to the @@ -56,7 +56,7 @@ and to address some of the cases unique to fluid user interfaces, the QML items When the user presses or releases a key, the following occurs: \list 1 \o Qt receives the key action and generates a key event. -\o If the Qt widget containing the \l QmlView has focus, the key event is delivered to it. Otherwise, regular Qt key handling continues. +\o If the Qt widget containing the \l QDeclarativeView has focus, the key event is delivered to it. Otherwise, regular Qt key handling continues. \o The key event is delivered by the scene to the QML \l Item with \e {active focus}. If no \l Item has \e {active focus}, the key event is \l {QEvent::ignore()}{ignored} and regular Qt key handling continues. \o If the QML \l Item with \e {active focus} accepts the key event, propagation stops. Otherwise the event is "bubbled up", by recursively passing it to each \l Item's parent until either the event is accepted, or the root \l Item is reached. diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc index fb33664..c718a6d 100644 --- a/doc/src/declarative/globalobject.qdoc +++ b/doc/src/declarative/globalobject.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlglobalobject.html +\page qdeclarativeglobalobject.html \title QML Global Object Contains all the properties of the JavaScript global object, plus: @@ -71,7 +71,7 @@ when the property has one of the following types: \o Vector3D \endlist -There are also string based constructors for these types, see \l{qmlbasictypes.html}{Qml Types}. +There are also string based constructors for these types, see \l{qdeclarativebasictypes.html}{Qml Types}. \section3 Qt.rgba(qreal red, qreal green, qreal blue, qreal alpha) This function returns a Color with the specified \c red, \c green, \c blue and \c alpha components. All components should be in the range 0-1 inclusive. @@ -218,7 +218,7 @@ The \c openDatabase() and related functions provide the ability to access local offline storage in an SQL database. These databases are user-specific and QML-specific. They are stored in the \c Databases subdirectory -of QmlEngine::offlineStoragePath(), currently as SQLite databases. +of QDeclarativeEngine::offlineStoragePath(), currently as SQLite databases. The API conforms to the Synchronous API of the HTML5 Web Database API, \link http://www.w3.org/TR/2009/WD-webdatabase-20091029/ W3C Working Draft 29 October 2009\endlink. diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/declarative/integrating.qdoc index b3d6306..c685d3d 100644 --- a/doc/src/declarative/integrating.qdoc +++ b/doc/src/declarative/integrating.qdoc @@ -49,16 +49,16 @@ add QML to your UI, without having to rewrite it. \section1 Adding QML to a \l{QWidget} based UI If you have an existing QWidget based UI you can simply write new custom widgets in QML. To integrate them into your application you can create a -QmlView widget, and load the QML file into that. You'll then have a new widget +QDeclarativeView widget, and load the QML file into that. You'll then have a new widget containing your declarative UI, and you can interact with it through the -QmlView interface. The one drawback of this approach is that QmlView is a lot +QDeclarativeView interface. The one drawback of this approach is that QDeclarativeView is a lot heavier than a QWidget in terms of memory consumption and initialization speed, and so having large numbers of them may lead to performance degredation. For a smooth transition from a QWidget based UI to a QML based UI, simply rewrite your widgets in QML one at a time, using the above method. When all of your widgets are written in QML you can rewrite your main widget in -QML, so as to load the other widgets in QML instead of using QmlViews. Then +QML, so as to load the other widgets in QML instead of using QDeclarativeViews. Then you just load the main QML file on startup. Keep in mind that QWidgets were designed for different sorts of UIs than QML @@ -70,7 +70,7 @@ of simple and dynamic elements. \section1 Adding QML to a QGraphicsView based UI If you have an existing Graphics View based UI you can create new -items in QML, and use \l{QmlComponent} to create \l{QGraphicsObject}s +items in QML, and use \l{QDeclarativeComponent} to create \l{QGraphicsObject}s from the QML files. These \l{QGraphicsObject}s can then be placed into your \l{QGraphicsScene} using \l{QGraphicsScene::addItem()} or by reparenting them to an item already in the \l{QGraphicsScene}. @@ -79,8 +79,8 @@ Example, for local QML files: \code QGraphicsScene* scene = new QGraphicsScene; -QmlEngine *engine = new QmlEngine; -QmlComponent component(engine, QUrl::fromLocalFile(filename)); +QDeclarativeEngine *engine = new QDeclarativeEngine; +QDeclarativeComponent component(engine, QUrl::fromLocalFile(filename)); QGraphicsObject *object = qobject_cast<QGraphicsObject *>(component.create()); scene->addItem(object); diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index cde8eb8..98183bb 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmljavascript.html +\page qdeclarativejavascript.html \title JavaScript Blocks QML encourages building UIs declaratively, using \l {Property Binding} and the @@ -124,7 +124,7 @@ The \c source property may reference a relative file, or an absolute path. In t case of a relative file, the location is resolved relative to the location of the \l {QML Document} that contains the \l Script element. If the script file is not accessible, an error will occur. If the source is on a network resource, the -enclosing QML document will remain in the \l {QmlComponent::status()}{waiting state} +enclosing QML document will remain in the \l {QDeclarativeComponent::status()}{waiting state} until the script has been retrieved. \section1 Running Script at Startup diff --git a/doc/src/declarative/measuring-performance.qdoc b/doc/src/declarative/measuring-performance.qdoc index 8f6fe7d..cb608bf 100644 --- a/doc/src/declarative/measuring-performance.qdoc +++ b/doc/src/declarative/measuring-performance.qdoc @@ -71,14 +71,14 @@ Q_DEFINE_PERFORMANCE_METRIC(TextSize, "Text Size Calculation"); You could then use this category in the code: \code -void QmlGraphicsText::updateSize() +void QDeclarativeText::updateSize() { - QmlPerfTimer<QmlPerf::TextSize> perf; + QDeclarativePerfTimer<QDeclarativePerf::TextSize> perf; ... } \endcode -Because there is no cost for a QmlPerfTimer when Q_ENABLE_PERFORMANCE_LOG is not defined, this line can persist in the code and be used to help detect performance bottlenecks and regressions. See the QPerformanceLog documentation for more information on this performance framework. +Because there is no cost for a QDeclarativePerfTimer when Q_ENABLE_PERFORMANCE_LOG is not defined, this line can persist in the code and be used to help detect performance bottlenecks and regressions. See the QPerformanceLog documentation for more information on this performance framework. \section1 FPS Measurements diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc index b2fd149..ab75f8d 100644 --- a/doc/src/declarative/modules.qdoc +++ b/doc/src/declarative/modules.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlmodules.html +\page qdeclarativemodules.html \title Modules A \bold module is a collection of QML types. @@ -63,7 +63,7 @@ This makes available all types in Qt that were available in Qt 4.6, regardless o actual version of Qt executing the QML. So even if Qt 4.7 adds a type that would conflict with a type you defined while using 4.6, that type is not imported, so there is no conflict. -Types defined by plugins are made using QmlModulePlugin. Installed plugins and QML files +Types defined by plugins are made using QDeclarativeExtensionPlugin. Installed plugins and QML files can both contribute types to the same module. @@ -82,7 +82,7 @@ QML, a URI import is used: import com.nokia.Example 1.0 \endcode -Files imported in this way are found on the paths added by QmlEngine::addImportPath(), +Files imported in this way are found on the paths added by QDeclarativeEngine::addImportPath(), which by default only inludes \c $QTDIR/qml, so the above would make available those types defined in \c $QTDIR/qml/com/nokia/Example which are specified as being in version 1.0. Installed plugins and QML files can both contribute types to the same module. diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc index fc4761e..e642257 100644 --- a/doc/src/declarative/network.qdoc +++ b/doc/src/declarative/network.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlnetwork.html +\page qdeclarativenetwork.html \title Network Transparency QML supports network transparency by using URLs (rather than file names) for all @@ -128,9 +128,9 @@ See the \tt demos/declarative/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 QmlEngine which executes the QML. +All network access from QML is managed by a QNetworkAccessManager set on the QDeclarativeEngine which executes the QML. By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager using -QmlEngine::setNetworkAccessManager() as appropriate for the policies of your application. +QDeclarativeEngine::setNetworkAccessManager() as appropriate for the policies of your application. For example, the \l qmlviewer tool sets a new QNetworkAccessManager which 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. @@ -143,7 +143,7 @@ the executable using \l{The Qt Resource System}. Using this, an executable can r that is compiled into the executable: \code - QmlView *canvas = new QmlView; + QDeclarativeView *canvas = new QDeclarativeView; canvas->setUrl(QUrl("qrc:/dial.qml")); \endcode diff --git a/doc/src/declarative/qmldebugging.qdoc b/doc/src/declarative/qdeclarativedebugging.qdoc index 56bd7d2..3ef9ce7 100644 --- a/doc/src/declarative/qmldebugging.qdoc +++ b/doc/src/declarative/qdeclarativedebugging.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmldebugging.html +\page qdeclarativedebugging.html \title Debugging QML \section1 Logging diff --git a/doc/src/declarative/qmldocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc index 977b4ac..a210c98 100644 --- a/doc/src/declarative/qmldocument.qdoc +++ b/doc/src/declarative/qdeclarativedocument.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmldocuments.html +\page qdeclarativedocuments.html \title QML Documents A QML document is a block of QML source code. QML documents generally correspond to files @@ -87,7 +87,7 @@ document - such as \c Rectangle and \c ListView - including those made within an import statements. QML does not import any modules by default, so at least one \c import statement must be present or no elements will be available! -A QML document defines a single, top-level \l {QmlComponent}{QML component}. A QML component +A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}. A QML component is a template that is interpreted by the QML runtime 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. @@ -186,5 +186,5 @@ Rectangle { \endcode \endtable -\sa QmlComponent +\sa QDeclarativeComponent */ diff --git a/doc/src/declarative/qmli18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc index 0803d6c..9c10a46 100644 --- a/doc/src/declarative/qmli18n.qdoc +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmli18n.html +\page qdeclarativei18n.html \title QML Internationalization \section1 Overview diff --git a/doc/src/declarative/qmlintro.qdoc b/doc/src/declarative/qdeclarativeintro.qdoc index b353e44..4d05a8c 100644 --- a/doc/src/declarative/qmlintro.qdoc +++ b/doc/src/declarative/qdeclarativeintro.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlintroduction.html +\page qdeclarativeintroduction.html \title Introduction to the QML language \tableofcontents diff --git a/doc/src/declarative/qmlmodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index 4843a7b..c0e028e 100644 --- a/doc/src/declarative/qmlmodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlmodels.html +\page qdeclarativemodels.html \target qmlmodels \title Data Models @@ -99,7 +99,7 @@ There are a number of QML elements that operate using data models: \endlist QML supports several types of data model, which may be provided by QML -or C++ (via QmlContext::setContextProperty(), for example). +or C++ (via QDeclarativeContext::setContextProperty(), for example). \section1 QML Data Models @@ -210,7 +210,7 @@ dataList.append("Fred"); dataList.append("Ginger"); dataList.appenf("Skipper"); -QmlContext *ctxt = view.rootContext(); +QDeclarativeContext *ctxt = view.rootContext(); ctxt->setContextProperty("myModel", QVariant::fromValue(&dataList)); \endcode @@ -234,7 +234,7 @@ ListView { \note There is no way for the view to know that the contents of a QStringList have changed. If the QStringList is changed, it will be necessary to reset -the model by calling QmlContext::setContextProperty() again. +the model by calling QDeclarativeContext::setContextProperty() again. \section2 QList<QObject*> @@ -257,7 +257,7 @@ dataList.append(new DataObject("Item 2", "green")); dataList.append(new DataObject("Item 3", "blue")); dataList.append(new DataObject("Item 4", "yellow")); -QmlContext *ctxt = view.rootContext(); +QDeclarativeContext *ctxt = view.rootContext(); ctxt->setContextProperty("myModel", QVariant::fromValue(dataList)); \endcode @@ -282,7 +282,7 @@ ListView { Note: There is no way for the view to know that the contents of a QList have changed. If the QList is changed, it will be necessary to reset -the model by calling QmlContext::setContextProperty() again. +the model by calling QDeclarativeContext::setContextProperty() again. \section1 Other Data Models diff --git a/doc/src/declarative/qmlreference.qdoc b/doc/src/declarative/qdeclarativereference.qdoc index 107d579..01af7f5 100644 --- a/doc/src/declarative/qmlreference.qdoc +++ b/doc/src/declarative/qdeclarativereference.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! - \page qmlreference.html + \page qdeclarativereference.html \title QML Reference \target qtdeclarativemainpage @@ -80,8 +80,8 @@ \o \l {qmlmodels}{Data Models} \o \l {anchor-layout}{Anchor-based Layout} \o \l {qmlstates}{States} - \o \l {qmlanimation.html}{Animation} - \o \l {qmlmodules.html}{Modules} + \o \l {qdeclarativeanimation.html}{Animation} + \o \l {qdeclarativemodules.html}{Modules} \o \l {qmlfocus}{Keyboard Focus} \o \l {Extending types from QML} \endlist diff --git a/doc/src/declarative/qmlstates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index 2118c2b..0fea6f8 100644 --- a/doc/src/declarative/qmlstates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlstates.html +\page qdeclarativestates.html \target qmlstates \title QML States diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/declarative/qmlruntime.qdoc index c2b29d3..6d3e109 100644 --- a/doc/src/declarative/qmlviewer.qdoc +++ b/doc/src/declarative/qmlruntime.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! - \page qmlviewer.html + \page qmlruntime.html \title Qt Declarative UI Viewer (qmlviewer) \ingroup qttools \keyword qmlviewer @@ -82,17 +82,17 @@ a simple orientation property. The orientation can be set via the settings menu in the application, or by pressing Ctrl+T to toggle it. - To use this from within your QML file, import QmlViewer 1.0 and create a + To use this from within your QML file, import QDeclarativeViewer 1.0 and create a Screen object. This object has a property, orientation, which can be either Screen.Landscape or Screen.Portrait and which can be bound to in your application. An example is below: \code - import QmlViewer 1.0 as QmlViewer + import QDeclarativeViewer 1.0 as QDeclarativeViewer Item { - QmlViewer.Screen { id: qmlviewerScreen } - state: (qmlviewerScreen.orientation == QmlViewer.Screen.Landscape) ? 'landscape' : '' + QDeclarativeViewer.Screen { id: qmlviewerScreen } + state: (qmlviewerScreen.orientation == QDeclarativeViewer.Screen.Landscape) ? 'landscape' : '' } \endcode diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc index 732ff86..66d537d 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/declarative/qtbinding.qdoc @@ -46,50 +46,50 @@ \tableofcontents -The QML API is split into three main classes - QmlEngine, QmlComponent and QmlContext. -QmlEngine provides the environment in which QML is run, QmlComponent encapsulates -\l {QML Documents}, and QmlContext allows applications to expose data to QML component instances. +The QML API is split into three main classes - QDeclarativeEngine, QDeclarativeComponent and QDeclarativeContext. +QDeclarativeEngine provides the environment in which QML is run, QDeclarativeComponent encapsulates +\l {QML Documents}, and QDeclarativeContext allows applications to expose data to QML component instances. -QML also includes a convenience API, QmlView, for applications that simply want to embed QML -components into a new QGraphicsView. QmlView covers up many of the details discussed below. -While QmlView is mainly intended for rapid prototyping it can have uses in production applications. +QML also includes a convenience API, QDeclarativeView, for applications that simply want to embed QML +components into a new QGraphicsView. QDeclarativeView covers up many of the details discussed below. +While QDeclarativeView is mainly intended for rapid prototyping it can have uses in production applications. If you are looking at retrofitting an existing Qt application with QML, read \l{Integrating QML with existing Qt UI code}. \section1 Basic Usage -Every application requires at least one QmlEngine. A QmlEngine allows the configuration of +Every application requires at least one QDeclarativeEngine. A QDeclarativeEngine allows the configuration of global settings that apply to all the QML component instances - such as the QNetworkAccessManager that is used for network communications, and the path used for persistent storage. -Multiple QmlEngine's are only needed if the application requires these settings to differ +Multiple QDeclarativeEngine's are only needed if the application requires these settings to differ between QML component instances. -\l {QML Documents} are loaded using the QmlComponent class. Each QmlComponent instance -represents a single QML document. A QmlComponent can be passed a document URL, or raw text +\l {QML Documents} are loaded using the QDeclarativeComponent class. Each QDeclarativeComponent instance +represents a single QML document. A QDeclarativeComponent can be passed a document URL, or raw text representing the content of the document. The document URL can be a local filesystem URL, or any network URL supported by QNetworkAccessManager. -QML component instances can then be created by calling the QmlComponent::create() method. Here's +QML component instances can then be created by calling the QDeclarativeComponent::create() method. Here's an example of loading a QML document, and creating an object from it. \code -QmlEngine *engine = new QmlEngine(parent); -QmlComponent component(engine, QUrl("main.qml")); +QDeclarativeEngine *engine = new QDeclarativeEngine(parent); +QDeclarativeComponent component(engine, QUrl("main.qml")); QObject *myObject = component.create(); \endcode \section1 Exposing Data -QML components are instantiated in a QmlContext. A context allows the application to expose data -to the QML component instance. A single QmlContext can be used to instantiate all the objects -used by an application, or several QmlContext can be created for more fine grained control over -the data exposed to each instance. If a context is not passed to the QmlComponent::create() -method, the QmlEngine's \l {QmlEngine::rootContext()}{root context} is used. Data exposed through +QML components are instantiated in a QDeclarativeContext. A context allows the application to expose data +to the QML component instance. A single QDeclarativeContext can be used to instantiate all the objects +used by an application, or several QDeclarativeContext can be created for more fine grained control over +the data exposed to each instance. If a context is not passed to the QDeclarativeComponent::create() +method, the QDeclarativeEngine's \l {QDeclarativeEngine::rootContext()}{root context} is used. Data exposed through the root context is available to all object instances. \section1 Simple Data -To expose data to a QML component instance, applications set \l {QmlContext::setContextProperty()} +To expose data to a QML component instance, applications set \l {QDeclarativeContext::setContextProperty()} {context properties} which are then accessible by name from QML \l {Property Binding}s and \l {JavaScript Blocks}. The following example shows how to expose a background color to a QML file. @@ -99,11 +99,11 @@ file. \o \code // main.cpp -QmlContext *windowContext = new QmlContext(engine->rootContext()); +QDeclarativeContext *windowContext = new QDeclarativeContext(engine->rootContext()); windowContext->setContextProperty("backgroundColor", QColor(Qt::lightsteelblue)); -QmlComponent component(&engine, "main.qml"); +QDeclarativeComponent component(&engine, "main.qml"); QObject *window = component.create(windowContext); \endcode \o @@ -125,14 +125,14 @@ Rectangle { Context properties work just like normal properties in QML bindings - if the \c backgroundColor context property in the previous example was changed to red, the component object instances would all be automatically updated. Note that it is the responsibility of the creator to delete any -QmlContext it constructs. If the \c windowContext in the example above is no longer needed when +QDeclarativeContext it constructs. If the \c windowContext in the example above is no longer needed when the \c window component instantiation is destroyed, the \c windowContext must be destroyed explicitly. The simplest way to ensure this is to set \c window as \c windowContext's parent. -QmlContexts form a tree - each QmlContext except for the root context has a parent. Child -QmlContexts effectively inherit the context properties present in their parents. This gives +QDeclarativeContexts form a tree - each QDeclarativeContext except for the root context has a parent. Child +QDeclarativeContexts effectively inherit the context properties present in their parents. This gives applications more freedom in partitioning the data exposed to different QML object instances. -If a QmlContext sets a context property that is also set in one of its parents, the new context +If a QDeclarativeContext sets a context property that is also set in one of its parents, the new context property shadows that in the parent. In The following example, the \c background context property in \c {Context 1} shadows the \c background context property in the root context. @@ -185,10 +185,10 @@ int main(int argc, char **argv) { // ... - QmlContext *windowContext = new QmlContext(engine->rootContext()); + QDeclarativeContext *windowContext = new QDeclarativeContext(engine->rootContext()); windowContext->setContextProperty("palette", new CustomPalette); - QmlComponent component(&engine, "main.qml"); + QDeclarativeComponent component(&engine, "main.qml"); QObject *window = component.create(windowContext); } \endcode @@ -230,7 +230,7 @@ binding that does not have a NOTIFY signal will cause QML to issue a warning at \section2 Dynamic Structured Data If an application is too dynamic to structure data as compile-time QObject types, dynamically -structured data can be constructed at runtime using the QmlPropertyMap class. +structured data can be constructed at runtime using the QDeclarativePropertyMap class. \section1 Calling C++ methods from QML @@ -279,7 +279,7 @@ int main(int argc, char **argv) { // ... - QmlContext *context = engine->rootContext(); + QDeclarativeContext *context = engine->rootContext(); context->setContextProperty("ledBlinker", new LEDBlinker); // ... @@ -329,15 +329,15 @@ Of course, it is also possible to call \l {Adding new methods}{functions declare \section1 Network Components -If the URL passed to QmlComponent is a network resource, or if the QML document references a -network resource, the QmlComponent has to fetch the network data before it is able to create -objects. In this case, the QmlComponent will have a \l {QmlComponent::Loading}{Loading} -\l {QmlComponent::status()}{status}. An application will have to wait until the component -is \l {QmlComponent::Ready}{Ready} before calling \l {QmlComponent::create()}. +If the URL passed to QDeclarativeComponent is a network resource, or if the QML document references a +network resource, the QDeclarativeComponent has to fetch the network data before it is able to create +objects. In this case, the QDeclarativeComponent will have a \l {QDeclarativeComponent::Loading}{Loading} +\l {QDeclarativeComponent::status()}{status}. An application will have to wait until the component +is \l {QDeclarativeComponent::Ready}{Ready} before calling \l {QDeclarativeComponent::create()}. The following example shows how to load a QML file from a network resource. After creating -the QmlComponent, it tests whether the component is loading. If it is, it connects to the -QmlComponent::statusChanged() signal and otherwise calls the \c {continueLoading()} method +the QDeclarativeComponent, it tests whether the component is loading. If it is, it connects to the +QDeclarativeComponent::statusChanged() signal and otherwise calls the \c {continueLoading()} method directly. This test is necessary, even for URLs that are known to be remote, just in case the component has been cached and is ready immediately. @@ -345,9 +345,9 @@ the component has been cached and is ready immediately. MyApplication::MyApplication() { // ... - component = new QmlComponent(engine, QUrl("http://www.example.com/main.qml")); + component = new QDeclarativeComponent(engine, QUrl("http://www.example.com/main.qml")); if (component->isLoading()) - QObject::connect(component, SIGNAL(statusChanged(QmlComponent::Status)), + QObject::connect(component, SIGNAL(statusChanged(QDeclarativeComponent::Status)), this, SLOT(continueLoading())); else continueLoading(); @@ -381,7 +381,7 @@ For example: MyApplication::MyApplication() { // ... - component = new QmlComponent(engine, QUrl("qrc:/main.qml")); + component = new QDeclarativeComponent(engine, QUrl("qrc:/main.qml")); if (component->isError()) { qWarning() << component->errors(); } else { diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc index 343359c..ca1d596 100644 --- a/doc/src/declarative/qtprogrammers.qdoc +++ b/doc/src/declarative/qtprogrammers.qdoc @@ -61,7 +61,7 @@ QML provides direct access to the following concepts from Qt: \o QAction - the \l {QML Basic Types}{action} type \o QObject signals and slots - available as functions to call in JavaScript \o QObject properties - available as variables in JavaScript - \o QWidget - QmlView is a QML-displaying widget + \o QWidget - QDeclarativeView is a QML-displaying widget \o Qt models - used directly in data binding (QAbstractItemModel and next generation QListModelInterface) \endlist @@ -84,14 +84,14 @@ QML Items also serve these purposes. Each is considered separately below. \section2 Simple Widgets -The most important rule to remember while implementing a new QmlGraphicsItem in C++ +The most important rule to remember while implementing a new QDeclarativeItem 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 QmlGraphicsItem subclass to implement a button, +decided to write a QDeclarativeItem subclass to implement a button, just as QToolButton subclasses QWidget for this purpose, following the rule above, your -\c QmlGraphicsButton would not have any appearance - just the notions of enabled, triggering, etc. +\c QDeclarativeButton would not have any appearance - just the notions of enabled, triggering, etc. But there is already an object in Qt that does this: QAction. @@ -103,13 +103,13 @@ The look and feel of an action - the appearance of the button, the transition be and exactly how it respond to mouse, key, or touch input, should all be left for definition in QML. -It is illustrative to note that QmlGraphicsTextEdit is built upon QTextControl, -QmlGraphicsWebView is built upon QWebPage, and ListView uses QListModelInterface, +It is illustrative to note that QDeclarativeTextEdit is built upon QTextControl, +QDeclarativeWebView is built upon QWebPage, and ListView uses QListModelInterface, just as QTextEdit, QWebView, and QListView are built upon those same UI-agnostic components. The encapsulation of the look and feel that QWidgets gives is important, and for this -the QML concept of \l {qmldocuments.html}{components} serves the same purpose. If you are building a complete +the QML concept of \l {qdeclarativedocuments.html}{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. diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc index f709335..218af89 100644 --- a/doc/src/declarative/scope.qdoc +++ b/doc/src/declarative/scope.qdoc @@ -40,7 +40,7 @@ ****************************************************************************/ /*! -\page qmlscope.html +\page qdeclarativescope.html \title QML Scope \tableofcontents @@ -348,14 +348,14 @@ Item { } \endcode -\section1 QmlContext chain +\section1 QDeclarativeContext chain -The \l QmlContext chain allows C++ applications to pass data into QML applications. -\l QmlComponent object instances created from C++ are passed a \l QmlContext in which they -are created. Variables defined in this context appear in the scope chain. Each QmlContext -also defines a parent context. Variables in child QmlContext's shadow those in its parent. +The \l QDeclarativeContext chain allows C++ applications to pass data into QML applications. +\l QDeclarativeComponent object instances created from C++ are passed a \l QDeclarativeContext in which they +are created. Variables defined in this context appear in the scope chain. Each QDeclarativeContext +also defines a parent context. Variables in child QDeclarativeContext's shadow those in its parent. -Consider the following QmlContext tree. +Consider the following QDeclarativeContext tree. \image qml-context-tree.png |