diff options
Diffstat (limited to 'doc/src/declarative')
22 files changed, 546 insertions, 188 deletions
diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc index c465da4..2d05850 100644 --- a/doc/src/declarative/advtutorial.qdoc +++ b/doc/src/declarative/advtutorial.qdoc @@ -66,13 +66,13 @@ control QML elements. Tutorial chapters: \list 1 -\o \l {QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks}{Creating the Game Canvas and Blocks} -\o \l {QML Advanced Tutorial 2 - Populating the Game Canvas}{Populating the Game Canvas} -\o \l {QML Advanced Tutorial 3 - Implementing the Game Logic}{Implementing the Game Logic} -\o \l {QML Advanced Tutorial 4 - Finishing Touches}{Finishing Touches} +\o \l {declarative/tutorials/samegame/samegame1}{Creating the Game Canvas and Blocks} +\o \l {declarative/tutorials/samegame/samegame2}{Populating the Game Canvas} +\o \l {declarative/tutorials/samegame/samegame3}{Implementing the Game Logic} +\o \l {declarative/tutorials/samegame/samegame4}{Finishing Touches} \endlist -All the code in this tutorial can be found in the $QTDIR/examples/declarative/tutorials/samegame +All the code in this tutorial can be found in Qt's \c examples/declarative/tutorials/samegame directory. */ @@ -83,7 +83,7 @@ directory. \previouspage QML Advanced Tutorial \nextpage QML Advanced Tutorial 2 - Populating the Game Canvas -The files referenced on this page can be found in \c $QTDIR\examples\tutorials\samegame\samegame1. +\example declarative/tutorials/samegame/samegame1 \section2 Creating the application screen @@ -148,8 +148,7 @@ elements to get started. Next, we will populate the game canvas with some blocks \previouspage QML Advanced Tutorial 1 - Creating the Game Canvas and Blocks \nextpage QML Advanced Tutorial 3 - Implementing the Game Logic -The files referenced on this page can be found in \c $QTDIR\examples\tutorials\samegame\samegame2. - +\example declarative/tutorials/samegame/samegame2 \section2 Generating the blocks in JavaScript @@ -216,7 +215,7 @@ Now, we have a screen of blocks, and we can begin to add the game mechanics. \previouspage QML Advanced Tutorial 2 - Populating the Game Canvas \nextpage QML Advanced Tutorial 4 - Finishing Touches -The files referenced on this page can be found in \c $QTDIR\examples\tutorials\samegame\samegame3. +\example declarative/tutorials/samegame/samegame3 \section2 Making a playable game @@ -301,7 +300,7 @@ until the next chapter - where your application becomes alive! \contentspage QML Advanced Tutorial \previouspage QML Advanced Tutorial 3 - Implementing the Game Logic -The files referenced on this page can be found in \c $QTDIR\examples\tutorials\samegame\samegame4. +\example declarative/tutorials/samegame/samegame4 \section2 Adding some flair diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc index ff47694..5340de6 100644 --- a/doc/src/declarative/anchor-layout.qdoc +++ b/doc/src/declarative/anchor-layout.qdoc @@ -44,10 +44,16 @@ \target anchor-layout \title Anchor-based Layout in QML -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. Each item can be thought of as having a set of 6 invisible "anchor lines": \e left, \e horizontalCenter, \e right, \e top, \e verticalCenter, and \e bottom. +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. +Each item can be thought of as having a set of 7 invisible "anchor lines": +\e left, \e horizontalCenter, \e right, \e top, \e verticalCenter, \e baseline, and \e bottom. \image edges_qml.png +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: \code diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 9969e8f..88aca1b 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -94,7 +94,7 @@ Rectangle { Rectangle { color: "red" width: 50; height: 50 - NumberAnimation on x { to: 50; } + NumberAnimation on x { to: 50 } } } \endqml diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 3ee7fc1..d79c4d2 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -85,7 +85,6 @@ completely new applications. QML is fully \l {Extending QML in C++}{extensible \o \l {QML Tutorial}{Tutorial: 'Hello World'} \o \l {QML Advanced Tutorial}{Tutorial: 'Same Game'} \o \l {QML Examples and Demos} -\o \l {Using QML in C++ Applications} \o \l {QML for Qt programmers} \endlist @@ -107,12 +106,18 @@ completely new applications. QML is fully \l {Extending QML in C++}{extensible \o \l {qmlruntime.html}{The Qt Declarative Runtime} \endlist +\section1 Using QML with C++: +\list +\o \l {Tutorial: Writing QML extensions with C++} +\o \l {Extending QML in C++} +\o \l {Using QML in C++ Applications} +\o \l {Integrating QML with existing Qt UI code} +\endlist + \section1 Reference: \list \o \l {QML Elements} \o \l {QML Global Object} -\o \l {Extending QML in C++} -\o \l {Integrating QML with existing Qt UI code} \o \l {QML Internationalization} \o \l {QML Security} \o \l {QtDeclarative Module} diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index 6495f58..79fe909 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -122,6 +122,7 @@ The following table lists the QML elements provided by the \l {QtDeclarative}{Qt \o \l Rectangle \o \l Image \o \l BorderImage +\o \l AnimatedImage \o \l Text \o \l TextInput \o \l TextEdit diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc index dc6b76c..e01459f 100644 --- a/doc/src/declarative/examples.qdoc +++ b/doc/src/declarative/examples.qdoc @@ -71,7 +71,47 @@ For example, from your build directory, run: \section1 Examples \list +\o \l{declarative/animations}{Animations} +\o \l{declarative/aspectratio}{Aspect Ratio} +\o \l{declarative/behaviors}{Behaviors} +\o \l{declarative/border-image}{Border Image} +\o \l{declarative/clocks}{Clocks} +\o \l{declarative/connections}{Connections} +\o \l{declarative/dial}{Dial} +\o \l{declarative/dynamic}{Dynamic} +\o \l{declarative/extending}{Extending} +\o \l{declarative/fillmode}{Fillmode} +\o \l{declarative/flipable}{Flipable} \o \l{declarative/focus}{Focus} +\o \l{declarative/fonts}{Fonts} +\o \l{declarative/gridview}{GridView} +\o \l{declarative/imageprovider}{Image Provider} +\o \l{declarative/images}{Images} +\o \l{declarative/layouts}{Layouts} +\o \l{declarative/listmodel-threaded}{ListModel Threaded} +\o \l{declarative/listview}{ListView} +\o \l{declarative/mousearea}{Mouse Area} +\o \l{declarative/objectlistmodel}{Object ListModel} +\o \l{declarative/package}{Package} +\o \l{declarative/parallax}{Parallax} +\o \l{declarative/plugins}{Plugins} +\o \l{declarative/progressbar}{Progress Bars} +\o \l{declarative/proxywidgets}{Proxy Widgets} +\o \l{declarative/scrollbar}{Scrollbar} +\o \l{declarative/searchbox}{Search Box} +\o \l{declarative/slideswitch}{Slide Switch} +\o \l{declarative/sql}{SQL} +\o \l{declarative/states}{States} +\o \l{declarative/stringlistmodel}{String ListModel} +\o \l{declarative/tabwidget}{Tab Widget} +\o \l{declarative/tic-tac-toe}{Tic-Tac-Toe} +\o \l{declarative/tvtennis}{TV Tennis} +\o \l{declarative/velocity}{Velocity} +\o \l{declarative/webview}{WebView} +\o \l{declarative/workerscript}{WorkerScript} +\o \l{declarative/xmldata}{XML Data} +\o \l{declarative/xmlhttprequest}{XMLHttpRequest} + \endlist \section1 Demos diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc new file mode 100644 index 0000000..f00b858 --- /dev/null +++ b/doc/src/declarative/extending-tutorial.qdoc @@ -0,0 +1,420 @@ +/**************************************************************************** +** +** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the Technology Preview License Agreement accompanying +** this package. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain additional +** rights. These rights are described in the Nokia Qt LGPL Exception +** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** +** +** +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + +\page qml-extending-tutorial-index.html +\title Tutorial: Writing QML extensions with C++ + +The QtDeclarative 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/declarative/tutorials/extending directory. + +Tutorial chapters: + +\list 1 +\o \l{declarative/tutorials/extending/chapter1-basics}{Creating a New Type} +\o \l{declarative/tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals} +\o \l{declarative/tutorials/extending/chapter3-bindings}{Adding Property Bindings} +\o \l{declarative/tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types} +\o \l{declarative/tutorials/extending/chapter5-plugins}{Writing an Extension Plugin} +\o \l{qml-extending-tutorial6.html}{In Summary} +\endlist + +*/ + +/*! +\title Chapter 1: Creating a New Type + +\example declarative/tutorials/extending/chapter1-basics + +Let's create a new QML type called "Musician" that has two properties: a name +and an instrument. We will make it available in a \l {Modules}{module} called "Music", with +a module version of 1.0. +We want this \c Musician type to be usable from QML like this: + +\code + import Music 1.0 + + Musician { + name: "Reddy the Rocker" + instrument: "Guitar" + } +\endcode + +To do this, we need a C++ class that encapsulates this \c Musician type and its two +properties. Since QML relies heavily on Qt's \l{Meta-Object System}{meta object system}, +this new class must: + +\list +\o inherit from QObject +\o declare its properties using the Q_PROPERTY() macro +\endlist + +Here is our \c Musician class, defined in \c musician.h: + +\snippet declarative/tutorials/extending/chapter1-basics/musician.h 0 + +It defines the two properties, \c name and \c instrument, with the Q_PROPERTY() macro. +The class implementation in \c musician.cpp simply sets and returns the \c m_name and +\c m_instrument values as appropriate. + +Our QML file, \c app.qml, creates a \c Musician item and display the musician's details +using a standard QML \l Text item: + +\quotefile declarative/tutorials/extending/chapter1-basics/app.qml + +We'll also create a C++ application that uses a QDeclarativeView to run and +display \c app.qml. The application must register the \c Musician 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 Musician. + +Here is the application \c main.cpp: + +\snippet declarative/tutorials/extending/chapter1-basics/main.cpp 0 + +This call to qmlRegisterType() registers the \c Musician type as a type called "Musician", in a module named "Music", +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 declarative/tutorials/extending/chapter1-basics/chapter1-basics.pro + +Now we can build and run the application. Try it yourself with the code in Qt's \c examples/tutorials/extending/chapter1-basics directory. + +\example declarative/tutorials/extending/chapter1-basics + +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 standard \c qml tool. +Later on, we'll show how to create a plugin so that you can run \c app.qml using the +\c qml tool instead. + +*/ + + +/*! +\title Chapter 2: Connecting to C++ Methods and Signals + +\example declarative/tutorials/extending/chapter2-methods + +Suppose we want \c Musician to have a "perform" method that prints a message +to the console and then emits a "performanceEnded" signal. +Other elements would be able to call \c perform() and receive +\c performanceEnded() signals like this: + +\quotefile declarative/tutorials/extending/chapter2-methods/app.qml + +To do this, we add a \c perform() method and a \c performanceEnded() signal +to our C++ class: + +\snippet declarative/tutorials/extending/chapter2-methods/musician.h 0 +\dots +\snippet declarative/tutorials/extending/chapter2-methods/musician.h 1 +\dots +\snippet declarative/tutorials/extending/chapter2-methods/musician.h 2 +\dots +\snippet declarative/tutorials/extending/chapter2-methods/musician.h 3 + +The use of Q_INVOKABLE makes the \c perform() 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 perform() method simply prints a message to the console and +then emits \c performanceEnded(): + +\snippet declarative/tutorials/extending/chapter2-methods/musician.cpp 0 + +Now when we run the application and click the window, the application outputs: + +\code + "Reddy the Rocker" is playing the "Guitar" + The performance has now ended +\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 declarative/tutorials/extending/chapter3-bindings + +Property bindings 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 change. + +Let's enable property bindings for the \c instrument property. That means +if we have code like this: + +\quotefile declarative/tutorials/extending/chapter3-bindings/app.qml + +The "instrument: reddy.instrument" statement binds the \c instrument value of +\c craig to the \c instrument of \c reddy. +Whenever \c reddy's \c instrument value changes, \c craig's \c instrument value +updates to the same value. When the window is clicked, the application outputs: + +\code + "Reddy the Rocker" is playing the "Guitar" + "Craig the Copycat" is playing the "Guitar" + "Reddy the Rocker" is playing the "Drums" + "Craig the Copycat" is playing the "Drums" +\endcode + +It's easy to enable property binding for the \c instrument property. +We add a \l{Qt's Property System}{NOTIFY} feature to its Q_PROPERTY() declaration to indicate that a "instrumentChanged" signal +is emitted whenever the value changes. + +\snippet declarative/tutorials/extending/chapter3-bindings/musician.h 0 +\dots +\snippet declarative/tutorials/extending/chapter3-bindings/musician.h 1 +\dots +\snippet declarative/tutorials/extending/chapter3-bindings/musician.h 2 +\dots +\snippet declarative/tutorials/extending/chapter3-bindings/musician.h 3 + +Then, we emit this signal in \c setInstrument(): + +\snippet declarative/tutorials/extending/chapter3-bindings/musician.cpp 0 + +It's important for \c setInstrument() to check that the instrument value has actually changed +before emitting \c instrumentChanged(). This ensures the signal is not emitted unnecessarily and +also prevents loops when other elements respond to the value change. + +*/ + +/*! +\title Chapter 4: Using Custom Property Types + +\example declarative/tutorials/extending/chapter4-customPropertyTypes + +The \c Musician type currently has two properties that are both strings. +It could have all sorts of other properties. For example, we could add an +integer-type property to store the age of each musician: + +\code + class Musician : public QObject + { + ... + Q_PROPERTY(int age READ age WRITE setAge) + public: + ... + int age() const; + void setAge(int age); + ... + }; +\endcode + +We can also use various other property types. QML has built-in support for the following +types: + +\list +\o bool +\o unsigned int, int +\o float, double, qreal +\o QString +\o QUrl +\o QColor +\o QDate, QTime, QDateTime +\o QPoint, QPointF +\o QSize, QSizeF +\o QRect, QRectF +\o 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 change the type of the \c instrument property from a string to a +new type called "Instrument". Instead of assigning a string value to \c instrument, +we assign an \c Instrument value: + +\quotefile declarative/tutorials/extending/chapter4-customPropertyTypes/app.qml + +Like \c Musician, this new \c Instrument type has to inherit from QObject and declare +its properties with Q_PROPERTY(): + +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/instrument.h 0 + +To use it from \c Musician, we modify the \c instrument property declaration +and associated method signatures: + +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/musician.h 0 +\dots +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/musician.h 1 +\dots +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/musician.h 2 +\dots +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/musician.h 3 + +Like the \c Musician type, the \c Instrument type has to be registered +using qmlRegisterType() to be used from QML. As with \c Musician, we'll add the +type to the "Music" module, version 1.0: + +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 0 +\dots +\snippet declarative/tutorials/extending/chapter4-customPropertyTypes/main.cpp 1 +\dots +\snippet declarative/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: Writing an Extension Plugin + +\example declarative/tutorials/extending/chapter5-plugins + +Currently the \c Musician and \c Instrument types are used by \c app.qml, +which is displayed using a QDeclarativeView 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 means we could load \c app.qml using the standard \c qml tool +(or some other QML runtime application) instead of writing a \c main.cpp file and +loading our own C++ application. + +To create a plugin library, we need: + +\list +\o A plugin class that registers our QML types +\o A project file that describes the plugin +\o A "qmldir" file that tells the QML engine to load the plugin +\endlist + +First, we create a plugin class named \c MusicPlugin. It subclasses QDeclarativeExtensionPlugin +and registers our QML types in the inherited \l{QDeclarativeExtensionPlugin::}{registerTypes()} method. It also calls +Q_EXPORT_PLUGIN2 for Qt's \l{How to Create Qt Plugins}{plugin system}. + +Here is the \c MusicPlugin definition in \c musicplugin.h: + +\snippet declarative/tutorials/extending/chapter5-plugins/musicplugin.h 0 + +And its implementation in \c musicplugin.cpp: + +\snippet declarative/tutorials/extending/chapter5-plugins/musicplugin.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 declarative/tutorials/extending/chapter5-plugins/chapter5-plugins.pro + +Finally, we add a \c qmldir file that is automatically parsed by the QML engine. +Here, we specify that a plugin named "chapter5-plugin" (the name +of the example project) can be found in the "lib" subdirectory: + +\quotefile declarative/tutorials/extending/chapter5-plugins/qmldir + +Now we have a plugin, and instead of having a main.cpp and an executable, we can build +the project and then run the QML file directly using the \c qml tool: + +\code + qml app.qml +\endcode + +Notice the "import Music 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 Musician.qml and Instrument.qml files inside the project directory, which could both +be used by \c app.qml without import statements. +*/ + +/*! +\page qml-extending-tutorial6.html +\title Chapter 6: In Summary + +In this tutorial, we've shown the basic steps for creating a QML extension: + +\list +\o Define new QML types by subclassing QObject and registering them with qmlRegisterType() +\o Add callable methods using Q_INVOKABLE or Qt slots, and connect to Qt signals with an \c onSignal syntax +\o Add property bindings by defining \l{Qt's Property System}{NOTIFY} signals +\o Define custom property types if the built-in types are not sufficient +\o Create a plugin library by defining a Qt plugin and writing a \c qmldir file +\endlist + + +The \l {Extending QML in C++} reference documentation shows other useful features that can be added to +QML extensions. For example, we could use \l{Object and List Property Types}{list properties} to allow multiple instruments for a \c Musician: + +\code + Musician { + instruments: [ + Instrument { type: "Guitar" } + Instrument { type: "Drums" } + Instrument { type: "Keyboard" } + ] + } +\endcode + +Or use \l{Default Property}{default properties} and avoid an +\c instruments property altogether: + +\code + Musician { + Instrument { type: "Guitar" } + Instrument { type: "Drums" } + Instrument { type: "Keyboard" } + } +\endcode + +Or even change the \c instrument of a \c Musician from time to time using \l{Property Value Sources}{property value sources}: + +\code + Musician { + InstrumentRandomizer on instrument {} + } +\endcode + + +See the \l{Extending QML in C++}{reference documentation} for more information. + +Additionally, \l {Integrating QML with existing Qt UI code} shows how to create +and integrate with QML extensions that have drawing and graphical capabilities (through QGraphicsWidget). + +*/ + diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index c27d091..1c159e4 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -43,7 +43,7 @@ \page qml-extending.html \title Extending QML in C++ -The QML syntax declaratively describes how to construct an in memory object +The QML syntax declaratively describes how to construct an in-memory object tree. In Qt, QML is mainly used to describe a visual scene graph, but it is not conceptually limited to this: the QML format is an abstract description of any object tree. All the QML element types included in Qt are implemented using @@ -65,7 +65,7 @@ QML relies heavily on Qt's meta object system and can only instantiate classes that derive from QObject. The QML engine has no intrinsic knowledge of any class types. Instead the -programmer must define the C++ types, and their corresponding QML name. +programmer must register the C++ types with their corresponding QML names. Custom C++ types are registered using a template function: @@ -152,7 +152,7 @@ template<typename T> int qmlRegisterInterface(const char *typeName) \endcode -Registers the C++ interface \a T with the QML system as \a typeName. +This 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. @@ -196,7 +196,7 @@ registered, the following function can be used: int qmlRegisterType() \endcode -Registers the C++ type \a T with the QML system. The parameterless call to the template +This registers the C++ type \a T with the QML system. The parameterless call to the template function qmlRegisterType() 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. @@ -222,7 +222,7 @@ The QML snippet shown above assigns a collection of objects to the The \e {default property} is a syntactic convenience that allows a type designer to specify a single property as the type's default. The default property is assigned to whenever no explicit property is specified. As a convenience, it is -behaviorally identical to assigning the default property explicitly by name. +behaviorally identical to assigning to the default property explicitly by name. From C++, type designers mark the default property using a Q_CLASSINFO() annotation: @@ -232,7 +232,7 @@ annotation: Q_CLASSINFO("DefaultProperty", "property") \endcode -Mark \a property as the class's default property. \a property must be either +This marks \a property as the class's default property. \a property must be either an object property, or a list property. A default property is optional. A derived class inherits its base class's @@ -248,7 +248,7 @@ specify a default property. \snippet examples/declarative/extending/grouped/example.qml 1 -The QML snippet shown above assigns a number properties to the \c Boy object, +The QML snippet shown above assigns a number of properties to the \c Boy object, including four properties using the grouped property syntax. Grouped properties collect similar properties together into a single named @@ -273,13 +273,13 @@ implement the \c shoe property grouping. \snippet examples/declarative/extending/attached/example.qml 1 -The QML snippet shown above assigns the \c rsvp property using the attached +The QML snippet shown above assigns a date to the \c rsvp property using the attached property syntax. Attached properties allow unrelated types to annotate other types with some additional properties, generally for their own use. Attached properties are identified through the use of the attacher type name, in the case shown -\c BirthdayParty, as a suffix to the property name. +\c BirthdayParty, as a prefix to the property name. In the example shown, \c BirthdayParty is called the attaching type, and the \c Boy instance the attachee object instance. @@ -306,7 +306,7 @@ public: QML_DECLARE_TYPEINFO(MyType, QML_HAS_ATTACHED_PROPERTIES) \endcode -Return an attachment object, of type \a AttachedPropertiesType, for the +This 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. @@ -349,7 +349,7 @@ an instance can be accessed using the following method: template<typename T> QObject *qmlAttachedPropertiesObject<T>(QObject *attachee, bool create = true); \endcode -Returns the attachment object attached to \a attachee by the attaching type +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, @@ -366,7 +366,7 @@ It is an element's 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 +\o 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 @@ -562,19 +562,22 @@ extension type - when registering the target class whose properties are transparently merged with the original target class when used from within QML. An extension class is a regular QObject, with a constructor that takes a QObject -pointer. When needed (extension classes are delay created until the first extended +pointer. When needed (extension class creation is delayed until the first extended property is accessed) the extension class is created and the target object is passed in as the parent. When an extended property on the original is accessed, the appropriate property on the extension object is used instead. When an extended type is installed, one of the \code - #define QML_REGISTER_EXTENDED_TYPE(URI, VMAJ, VFROM, VTO, QDeclarativeName,T, ExtendedT) - #define QML_REGISTER_EXTENDED_NOCREATE_TYPE(T, ExtendedT) +template<typename T, typename ExtendedT> +int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) + +template<typename T, typename ExtendedT> +int qmlRegisterType() \endcode -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 +functions should be used instead of the regular \c qmlRegisterType() variations. +The arguments are identical to the corresponding non-extension registration functions, +except for the ExtendedT parameter which is the type of the extension object. \section1 Optimization diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc index 6709ab4..57eaae7 100644 --- a/doc/src/declarative/globalobject.qdoc +++ b/doc/src/declarative/globalobject.qdoc @@ -223,7 +223,7 @@ of their use. function finishCreation(){ if(component.isReady()){ sprite = component.createObject(); - if(sprite == 0){ + if(sprite == null){ // Error Handling }else{ sprite.parent = page; @@ -248,7 +248,7 @@ of their use. \code component = createComponent("Sprite.qml"); sprite = component.createObject(); - if(sprite == 0){ + if(sprite == null){ // Error Handling console.log(component.errorsString()); }else{ diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/declarative/integrating.qdoc index 65413ec..0051f09 100644 --- a/doc/src/declarative/integrating.qdoc +++ b/doc/src/declarative/integrating.qdoc @@ -152,8 +152,8 @@ Here is a screenshot of the result: \image declarative-integrating-graphicswidgets.png -Note this approach of creating your graphics widgets from QML does not work -with QGraphicsItem objects that are not QGraphicsWidget-based, since they are not QObjects. +Note this approach of creating your graphics objects from QML does not work +with QGraphicsItems that are not QGraphicsObject-based, since they are not QObjects. See \l{Extending QML in C++} for further information on using C++ types. diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 7c0570e..2db7e8e 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -75,7 +75,7 @@ Item { MouseArea { anchors.fill: parent - onClicked: print(factorial(10)) + onClicked: console.log(factorial(10)) } } \endcode @@ -99,7 +99,7 @@ import "factorial.js" as MathFunctions Item { MouseArea { anchors.fill: parent - onClicked: print(MathFunctions.factorial(10)) + onClicked: console.log(MathFunctions.factorial(10)) } } \endcode @@ -184,6 +184,9 @@ Any element in a QML file - including nested elements and nested QML component instances - can use this attached property. If there is more than one \c onCompleted() handler to execute at startup, they are run sequentially in an undefined order. +Likewise, the \l {Component::onDestruction} attached property is triggered on +component destruction. + \section1 QML JavaScript Restrictions QML executes standard JavaScript code, with the following restrictions: @@ -204,16 +207,18 @@ is illegal in QML. \code // Illegal modification of undeclared variable a = 1; -for (var ii = 1; ii < 10; ++ii) a = a * ii; - console.log("Result: " + a); +for (var ii = 1; ii < 10; ++ii) + a = a * ii; +console.log("Result: " + a); \endcode It can be trivially modified to this legal code. \code var a = 1; -for (var ii = 1; ii < 10; ++ii) a = a * ii; - console.log("Result: " + a); +for (var ii = 1; ii < 10; ++ii) + a = a * ii; +console.log("Result: " + a); \endcode Any attempt to modify the global object - either implicitly or explicitly - will diff --git a/doc/src/declarative/measuring-performance.qdoc b/doc/src/declarative/measuring-performance.qdoc deleted file mode 100644 index cb608bf..0000000 --- a/doc/src/declarative/measuring-performance.qdoc +++ /dev/null @@ -1,122 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the Technology Preview License Agreement accompanying -** this package. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain additional -** rights. These rights are described in the Nokia Qt LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** If you have questions regarding the use of this file, please contact -** Nokia at qt-info@nokia.com. -** -** -** -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page optimizing-performance.html -\target optimizing-performance -\title Optimizing Performance in QML - -The Qt Declarative module includes several tools to help measure performance. - -\section1 Performance Logging - -The declarative module uses the functionality provided by QPerformanceLog to log performance information. To see this information you can add the following to src.pro: - -\code -DEFINES += Q_ENABLE_PERFORMANCE_LOG -\endcode - -The performance information will be printed to screen on a QML application startup, or when running the viewer can be forced at anytime by pressing 'F3' on the keyboard. - -Additional logging can be enabled by adding the relevant categories to qfxperf.h and qfxperf.cpp. - -For example, to measure the cost of calculating the size of a text item, you would first define a TextSize category by adding the following: - -\code -//in qfxperf.h -Q_DECLARE_PERFORMANCE_METRIC(TextSize); - -//in qfxperf.cpp -Q_DEFINE_PERFORMANCE_METRIC(TextSize, "Text Size Calculation"); -\endcode - -You could then use this category in the code: - -\code -void QDeclarativeText::updateSize() -{ - QDeclarativePerfTimer<QDeclarativePerf::TextSize> perf; - ... -} -\endcode - -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 - -When running the viewer, pressing 'F2' on the keyboard while a QML program is running will cause information on cost-per-frame and frames-per-second (FPS) to be printed to the console. - -The information printed includes: -\list -\o \e repaint(): the total time spent painting. -\o \e paint(): the time spent by Qt painting. -\o \e timeBetweenFrames: the total time spent per frame. This number minus repaint() gives a good idea of how much time is spent on things besides painting. A high number here with a low number for repaint() indicates expensive calculations happening each frame. -\endlist - -\section1 Improving Performance - -The following tips can help decrease startup time for QML-based appications. - -\section2 Images - -\list -\o Use jpg instead of png for photo-like images. On the N810, this can save 150ms for a large (320x480) image. - -\o If you are configuring Qt, configure out any image plugins you don't plan to support (mng and svg are the most expensive). On the N810, this can save 75-100ms startup time. For example: - -\code -configure -no-libmng -no-svg -no-libtiff -\endcode - -\o In some cases running pngcrush, optipng, gifsicle or other similar tools can give some improvement. - -We are also investigating support for the loading of uncompressed images. This will provide opportunites to decrease startup time at the cost of increased storage space. -\endlist - -\section2 Fonts - -\list -\o Use qpf instead of ttf. When using multiple font sizes and weights on the N810, this can save 125ms startup time compared to a ttf 'clean' run, and 40-50ms on subsequent runs (ttfs are shared by open applications). -\endlist - -*/ - -*/ diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc index d268a13..68768c6 100644 --- a/doc/src/declarative/network.qdoc +++ b/doc/src/declarative/network.qdoc @@ -130,11 +130,12 @@ 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 QDeclarativeEngine which executes the QML. -By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager using -QDeclarativeEngine::setNetworkAccessManager() as appropriate for the policies of your application. -For example, the \l {Qt Declarative UI Runtime}{qml} 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. +By default, this is an unmodified Qt QNetworkAccessManager. You may set a different manager by +providing a QDeclarativeNetworkAccessManagerFactory and setting it via +QDeclarativeEngine::setNetworkAccessManagerFactory(). +For example, the \l {Qt Declarative UI Runtime}{qml} tool sets a QDeclarativeNetworkAccessManagerFactory 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 diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc index cf3aae2..bc099ce 100644 --- a/doc/src/declarative/qdeclarativedocument.qdoc +++ b/doc/src/declarative/qdeclarativedocument.qdoc @@ -93,7 +93,7 @@ behaviour. As it is a template, a single QML component can be "run" multiple ti 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 that is +operate on independent data. Here is an example of a simple "Button" component that is instantiated four times, each with a different value for its \c text property. \table diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc index 0a48dd9..c7dbd4d 100644 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -86,7 +86,7 @@ lupdate hello.qml -ts hello.ts \endcode Then we open \c hello.ts in \l{Qt Linguist Manual} {Linguist}, provide -a translation and create the release file \c hello.qml. +a translation and create the release file \c hello.qm. Finally, we can test the translation: \code diff --git a/doc/src/declarative/qdeclarativeintro.qdoc b/doc/src/declarative/qdeclarativeintro.qdoc index 4d05a8c..a98c9e1 100644 --- a/doc/src/declarative/qdeclarativeintro.qdoc +++ b/doc/src/declarative/qdeclarativeintro.qdoc @@ -142,8 +142,8 @@ Commenting in QML is similar to JavaScript. \quotefile doc/src/snippets/declarative/comments.qml -Comments are ignored by the engine. The are useful for explaining what you -are doing: for referring back to at a later date, or for others reading +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 diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index 0fea6f8..fd0c677 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -70,7 +70,7 @@ In QML: \o A state can affect the properties of other objects, not just the object owning the state (and not just that object's children). \endlist -Here is an example of using states. In the default state \c myRect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. Clicking within the mouse region changes the state from the default state to the 'moved' state, thus moving the rectangle. +Here is an example of using states. In the default state \c myRect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. Clicking within the mouse area changes the state from the default state to the 'moved' state, thus moving the rectangle. \qml Item { diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc index 9f7183a..a724c7d 100644 --- a/doc/src/declarative/qmlruntime.qdoc +++ b/doc/src/declarative/qmlruntime.qdoc @@ -52,7 +52,7 @@ QML is a runtime, as you can run plain qml files which pull in their required modules. To run apps with the QML runtime, you can either start the runtime - from your on application (using a QDeclarativeView) or with the simple \c qml application. + from your own application (using a QDeclarativeView) or with the simple \c qml application. The \c qml application can be installed in a production environment, assuming that it is not already present in the system. It is generally packaged alongside Qt. @@ -137,8 +137,8 @@ \section2 Runtime Object All applications using the qmlruntime will have access to the 'runtime' - property on the root context. This property contains several information - about the runtime environment of the application. + property on the root context. This property contains several pieces of + information about the runtime environment of the application. \section3 Screen Orientation @@ -150,11 +150,11 @@ which can be either Orientation.Landscape or Orientation.Portrait and which can be bound to in your application. An example is below: -\code + \code Item { state: (runtime.orientation == Orientation.Landscape) ? 'landscape' : '' } -\endcode + \endcode This allows your application to respond to the orientation of the screen changing. The runtime will automatically update this on some platforms (currently the N900 only) to match the physical @@ -163,12 +163,12 @@ \section3 Window Active The runtime.isActiveWindow property tells whether the main window of the qml runtime is currently active - or not. This is specially useful for embedded devices when you want to pause parts of your application, + or not. This is especially useful for embedded devices when you want to pause parts of your application, including animations, when your application loses focus or goes to the background. The example below, stops the animation when the application's window is deactivated and resumes on activation: -\code + \code Item { width: 300; height: 200 Rectangle { @@ -182,6 +182,6 @@ } } } -\endcode + \endcode */ diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc index 05ffeb0..0b40840 100644 --- a/doc/src/declarative/qtprogrammers.qdoc +++ b/doc/src/declarative/qtprogrammers.qdoc @@ -62,7 +62,7 @@ QML provides direct access to the following concepts from Qt: \o QObject signals and slots - available as functions to call in JavaScript \o QObject properties - available as variables in JavaScript \o QWidget - QDeclarativeView is a QML-displaying widget - \o Qt models - used directly in data binding (QAbstractItemModel and next generation QListModelInterface) + \o Qt models - used directly in data binding (QAbstractItemModel) \endlist Qt knowledge is \e required for \l {Extending QML in C++}, and also for \l{Integrating QML with existing Qt UI code}. @@ -104,7 +104,7 @@ and exactly how it respond to mouse, key, or touch input, should all be left for in QML. It is illustrative to note that QDeclarativeTextEdit is built upon QTextControl, -QDeclarativeWebView is built upon QWebPage, and ListView uses QListModelInterface, +QDeclarativeWebView is built upon QWebPage, and ListView uses QAbstractItemModel, just as QTextEdit, QWebView, and QListView are built upon those same UI-agnostic components. diff --git a/doc/src/declarative/snippets/qtbinding/contextproperties/main.cpp b/doc/src/declarative/snippets/qtbinding/contextproperties/main.cpp index 15e3d4c..4073a6c 100644 --- a/doc/src/declarative/snippets/qtbinding/contextproperties/main.cpp +++ b/doc/src/declarative/snippets/qtbinding/contextproperties/main.cpp @@ -56,7 +56,7 @@ int main(int argc, char *argv[]) context->setContextProperty("backgroundColor", QColor(Qt::yellow)); - view.setSource(QUrl("main.qml")); + view.setSource(QUrl::fromLocalFile("main.qml")); view.show(); return app.exec(); diff --git a/doc/src/declarative/snippets/qtbinding/custompalette/main.cpp b/doc/src/declarative/snippets/qtbinding/custompalette/main.cpp index c723688..dc651f6 100644 --- a/doc/src/declarative/snippets/qtbinding/custompalette/main.cpp +++ b/doc/src/declarative/snippets/qtbinding/custompalette/main.cpp @@ -53,7 +53,7 @@ int main(int argc, char *argv[]) QDeclarativeView view; view.rootContext()->setContextProperty("palette", new CustomPalette); - view.setSource(QUrl("main.qml")); + view.setSource(QUrl::fromLocalFile("main.qml")); view.show(); return app.exec(); diff --git a/doc/src/declarative/snippets/qtbinding/stopwatch/main.cpp b/doc/src/declarative/snippets/qtbinding/stopwatch/main.cpp index 13e3b9f..537a288 100644 --- a/doc/src/declarative/snippets/qtbinding/stopwatch/main.cpp +++ b/doc/src/declarative/snippets/qtbinding/stopwatch/main.cpp @@ -54,7 +54,7 @@ int main(int argc, char *argv[]) view.rootContext()->setContextProperty("stopwatch", new Stopwatch); - view.setSource(QUrl("main.qml")); + view.setSource(QUrl::fromLocalFile("main.qml")); view.show(); return app.exec(); |