diff options
Diffstat (limited to 'doc/src')
52 files changed, 1426 insertions, 345 deletions
diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc index 751bf00..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,11 +83,7 @@ directory. \previouspage QML Advanced Tutorial \nextpage QML Advanced Tutorial 2 - Populating the Game Canvas -In this chapter: - -\tableofcontents - -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 @@ -109,7 +105,7 @@ is the \l SystemPalette item. This provides access to the Qt system palette and is used to give the button a more native look-and-feel. Notice the anchors for the \c Item, \c Button and \c Text elements are set using -\l {Grouped Properties}{group notation} for readability. +\l {codingconventions.html#Grouped-properties}{group notation} for readability. \section2 Adding \c Button and \c Block components @@ -152,12 +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 -In this chapter: - -\tableofcontents - -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 @@ -224,11 +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 -In this chapter: - -\tableofcontents - -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 @@ -313,11 +300,7 @@ until the next chapter - where your application becomes alive! \contentspage QML Advanced Tutorial \previouspage QML Advanced Tutorial 3 - Implementing the Game Logic -In this chapter: - -\tableofcontents - -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 @@ -432,7 +415,7 @@ If the player enters a name, we send the data to the service using this code in \snippet declarative/tutorials/samegame/samegame4/content/samegame.js 1 -The \c XMLHttpRequest in this code is the same \c XMLHttpRequest() as you'll find in standard browser JavaScript, and can be used in the same way to dynamically get XML +The \l XMLHttpRequest in this code is the same as the \c XMLHttpRequest() as you'll find in standard browser JavaScript, and can be used in the same way to dynamically get XML or QML from the web service to display the high scores. We don't worry about the response in this case - we just post the high score data to the web server. If it had returned a QML file (or a URL to a QML file) you could instantiate it in much the same way as you did with the blocks. 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/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc index 7ae5cbd..7ca206b 100644 --- a/doc/src/declarative/codingconventions.qdoc +++ b/doc/src/declarative/codingconventions.qdoc @@ -72,6 +72,7 @@ For example, a hypothetical \e photo QML object would look like this: \snippet doc/src/snippets/declarative/codingconventions/photo.qml 0 +\target Grouped properties \section1 Grouped properties If using multiple properties from a group of properties, diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index a2a5283..d79c4d2 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -40,19 +40,28 @@ ****************************************************************************/ /*! -\title Declarative UI (QML) +\title Declarative UI Using QML \page declarativeui.html \brief The Qt Declarative module provides a declarative framework for building highly dynamic, custom user interfaces. +\section1 \l{QML Elements}{Fast QML Elements Reference Page} + +\raw HTML +<br> +\endraw + +\section1 Preamble + Qt Declarative UI provides a declarative framework for building highly dynamic, custom user interfaces. Declarative UI helps programmers and designers collaborate to build the animation rich, fluid user interfaces that are becoming common in portable consumer devices, such as mobile phones, media players, set-top boxes and netbooks. -The Qt Declarative module provides an engine for interpreting the declarative QML -language, and a rich set of \l {QML Elements}{QML elements} that can be used -from QML. + +The Qt Declarative module provides an engine for interpreting the declarative +QML language, and a rich set of \bold { \l {QML Elements}{QML elements} } +that can be used from QML. QML is an extension to \l {http://www.ecma-international.org/publications/standards/Ecma-262.htm} {JavaScript}, that provides a mechanism to declaratively build an object tree @@ -75,8 +84,7 @@ completely new applications. QML is fully \l {Extending QML in C++}{extensible \o \l {Introduction to the QML language} \o \l {QML Tutorial}{Tutorial: 'Hello World'} \o \l {QML Advanced Tutorial}{Tutorial: 'Same Game'} -\o \l {QML Examples and Walkthroughs} -\o \l {Using QML in C++ Applications} +\o \l {QML Examples and Demos} \o \l {QML for Qt programmers} \endlist @@ -98,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 ce3a6e3..79fe909 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -44,9 +44,7 @@ \target elements \title QML Elements -The following table lists the QML elements provided by the Qt Declarative module. - -\bold {Standard Qt Declarative Elements} +The following table lists the QML elements provided by the \l {QtDeclarative}{Qt Declarative} module. \table 80% \header @@ -81,6 +79,7 @@ The following table lists the QML elements provided by the Qt Declarative module \o \l PropertyAction \o \l ScriptAction \o \l Transition +\o \l SmoothedFollow \o \l SpringFollow \o \l Behavior \endlist @@ -109,11 +108,7 @@ The following table lists the QML elements provided by the Qt Declarative module \o \l QtObject \o \l WorkerScript \endlist -\endtable -\bold {QML Items} - -\table 80% \header \o \bold {Basic Visual Items} \o \bold {Basic Interaction Items} @@ -127,6 +122,7 @@ The following table lists the QML elements provided by the Qt Declarative module \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 3d8325e..e01459f 100644 --- a/doc/src/declarative/examples.qdoc +++ b/doc/src/declarative/examples.qdoc @@ -41,18 +41,22 @@ /*! \page qdeclarativeexamples.html -\title QML Examples and Walkthroughs +\title QML Examples and Demos -\section1 Running Examples and Demos +\previouspage Graphics View Examples +\contentspage Qt Examples +\nextpage Painting Examples + +\section1 Running the examples You can find many simple examples in the \c examples/declarative sub-directory that show how to use various aspects of QML. In addition, the \c demos/declarative sub-directory contains more sophisticated demos of large applications. These demos are intended to show integrated functionality -rather than being instructive on specifice elements. +rather than being instructive on specific elements. -To run the examples and demos, use the included \l {Qt Declarative UI Runtime}{qml} -application. It has some useful options, revealed by: +To run the examples and demos, you can use Qt Creator or the included \l {Qt Declarative UI Runtime}{qml} +command-line application. It has some useful options, revealed by: \code bin/qml -help @@ -66,18 +70,59 @@ For example, from your build directory, run: \section1 Examples -These will be documented, and demonstrate how to achieve various things in QML. +\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 -\table -\row - \o Elastic Dial - \o \image dial-example.gif -\row - \o \l{qdeclarativeexampletoggleswitch.html}{Toggle Switch} - \o \image switch-example.gif -\row - \o \l{QML Advanced Tutorial}{SameGame} - \o \image declarative-adv-tutorial4.gif -\endtable +\list +\o \l{demos/declarative/calculator}{Calculator} +\o \l{demos/declarative/minehunt}{Minehunt} +\o \l{demos/declarative/photoviewer}{Photo Viewer} +\o \l{demos/declarative/flickr}{Flickr Mobile} +\o \l{demos/declarative/samegame}{Same Game} +\o \l{demos/declarative/snake}{Snake} +\endlist */ diff --git a/doc/src/declarative/extending-examples.qdoc b/doc/src/declarative/extending-examples.qdoc index cc66838..307162e 100644 --- a/doc/src/declarative/extending-examples.qdoc +++ b/doc/src/declarative/extending-examples.qdoc @@ -57,11 +57,6 @@ element, the C++ class can be named differently, or appear in a namespace. \snippet examples/declarative/extending/adding/person.h 0 -Following the class declaration, we include the QML_DECLARE_TYPE() macro. This -is necessary to declare the type to QML. It also includes the logic necessary -to expose the class to Qt's meta system - that is, it includes the -Q_DECLARE_METATYPE() functionality. - \section1 Define the Person class \snippet examples/declarative/extending/adding/person.cpp 0 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 e1c6469..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 @@ -59,20 +59,19 @@ QML for their own independent use. \snippet examples/declarative/extending/adding/example.qml 0 The QML snippet shown above instantiates one \c Person instance and sets -the name and shoeSize properties on it. Everything in QML ultimately comes down +the \c name and \c shoeSize properties on it. Everything in QML ultimately comes down to either instantiating an object instance, or assigning a property a value. 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 declared QML types using a macro and a template function: +Custom C++ types are registered using a template function: \quotation \code -#define QML_DECLARE_TYPE(T) template<typename T> int qmlRegisterType(const char *uri, int versionMajor, int versionMinor, const char *qmlName) \endcode @@ -81,10 +80,6 @@ Calling qmlRegisterType() registers the C++ type \a T with the QML system, and m under the name \a qmlName in library \a uri version \a versionMajor.versionMinor. The \a qmlName can be the same as the C++ type name. -Generally the QML_DECLARE_TYPE() macro should be included immediately following -the type declaration (usually in its header file), and the template function qmlRegisterType() -called by the implementation. - Type \a T must be a concrete type that inherits QObject and has a default constructor. \endquotation @@ -129,7 +124,7 @@ the \c Person type. \snippet examples/declarative/extending/properties/example.qml 0 The QML snippet shown above assigns a \c Person object to the \c BirthdayParty's -celebrant property, and assigns three \c Person objects to the guests property. +\c host property, and assigns three \c Person objects to the guests property. QML can set properties of types that are more complex than basic intrinsics like integers and strings. Properties can also be object pointers, Qt interface @@ -138,42 +133,37 @@ is typesafe it ensures that only valid types are assigned to these properties, just like it does for primitive types. Properties that are pointers to objects or Qt interfaces are declared with the -Q_PROPERTY() macro, just like other properties. The celebrant property +Q_PROPERTY() macro, just like other properties. The \c host property declaration looks like this: \snippet examples/declarative/extending/properties/birthdayparty.h 1 -As long as the property type, in this case Person, is registered with QML the +As long as the property type, in this case \c Person, is registered with QML the property can be assigned. QML also supports assigning Qt interfaces. To assign to a property whose type is a Qt interface pointer, the interface must also be registered with QML. As they cannot be instantiated directly, registering a Qt interface is different -from registering a new QML type. The following macro and function are used instead: +from registering a new QML type. The following function is used instead: \quotation \code -#define QML_DECLARE_INTERFACE(T) template<typename T> int qmlRegisterInterface(const char *typeName) \endcode -Registers the C++ interface \a T with the QML system as \a typeName. - -Generally the QML_DECLARE_INTERFACE() macro should be included immediately -following the interface declaration (usually in its header file), and the -qmlRegisterInterface() template function called by the implementation. +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. \endquotation -The guests property is a list of \c Person objects. Properties that are lists +The \c 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 {QDeclarativeListProperty<T>}. As with object properties, the type \a T must be registered with QML. -The guest property declaration looks like this: +The \c guest property declaration looks like this: \snippet examples/declarative/extending/properties/birthdayparty.h 2 @@ -185,37 +175,32 @@ code used to create the \c BirthdayParty type. \snippet examples/declarative/extending/coercion/example.qml 0 The QML snippet shown above assigns a \c Boy object to the \c BirthdayParty's -celebrant property, and assigns three other objects to the guests property. +\c host property, and assigns three other objects to the \c guests property. -QML supports C++ inheritance heirarchies and can freely coerce between known, +QML supports C++ inheritance hierarchies and can freely coerce between known, valid object types. This enables the creation of common base classes that allow the assignment of specialized classes to object or list properties. In the -snippet shown, both the celebrant and the guests properties retain the Person -type used in the previous section, but the assignment is valid as both the Boy -and Girl objects inherit from Person. +snippet shown, both the \c host and the \c guests properties retain the \c Person +type used in the previous section, but the assignment is valid as both the \c Boy +and \c Girl objects inherit from \c Person. To assign to a property, the property's type must have been registered with QML. Both the qmlRegisterType() and qmlRegisterInterface() template functions 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 macro and function can be used: +registered, the following function can be used: \quotation \code - #define QML_DECLARE_TYPE(T) template<typename T> 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. -Generally the QML_DECLARE_TYPE() macro should be included immediately following -the type declaration (usually in its header file), and the -qmlRegisterType() template function 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. \endquotation @@ -234,10 +219,10 @@ code used to create the \c Boy and \c Girl types. The QML snippet shown above assigns a collection of objects to the \c BirthdayParty's default property. -The default property is a syntactic convenience that allows a type designer to +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: @@ -247,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 @@ -263,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 @@ -272,12 +257,12 @@ may also simplify the implementation of common property collections across different types through implementation reuse. A grouped property block is implemented as a read-only object property. The -shoe property shown is declared like this: +\c shoe property shown is declared like this: \snippet examples/declarative/extending/grouped/person.h 1 -The ShoeDescription type declares the properties available to the grouped -property block - in this case the size, color, brand and price properties. +The \c ShoeDescription type declares the properties available to the grouped +property block - in this case the \c size, \c color, \c brand and \c price properties. Grouped property blocks may declared and accessed be recusively. @@ -288,16 +273,16 @@ implement the \c shoe property grouping. \snippet examples/declarative/extending/attached/example.qml 1 -The QML snippet shown above assigns the 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 -Boy instance the attachee object instance. +\c Boy instance the attachee object instance. For the attaching type, an attached property block is implemented as a new QObject derived type, called the attachment object. The properties on the @@ -320,9 +305,8 @@ public: }; QML_DECLARE_TYPEINFO(MyType, QML_HAS_ATTACHED_PROPERTIES) -QML_DECLARE_TYPE(MyType) \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. @@ -342,7 +326,7 @@ their effect may be so limited. For example, a common usage scenario is for a type to enhance the properties available to its children in order to gather instance specific data. Here we -add a rsvp field to all the guests coming to a birthday party: +add a \c rsvp field to all the guests coming to a birthday party: \code BirthdayParty { Boy { BirthdayParty.rsvp: "2009-06-01" } @@ -365,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, @@ -378,11 +362,11 @@ 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 +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 @@ -443,7 +427,7 @@ implement the onPartyStarted signal property. \snippet examples/declarative/extending/valuesource/example.qml 0 \snippet examples/declarative/extending/valuesource/example.qml 1 -The QML snippet shown above assigns a property value to the speaker property. +The QML snippet shown above applies a property value source to the \c announcment property. A property value source generates a value for a property that changes over time. Property value sources are most commonly used to do animation. Rather than @@ -451,9 +435,9 @@ constructing an animation object and manually setting the animation's "target" property, a property value source can be assigned directly to a property of any type and automatically set up this association. -The example shown here is rather contrived: the speaker property of the -BirthdayParty object is a string that is printed every time it is assigned and -the HappyBirthday value source generates the lyrics of the song +The example shown here is rather contrived: the \c announcment property of the +\c BirthdayParty object is a string that is printed every time it is assigned and +the \c HappyBirthdaySong value source generates the lyrics of the song "Happy Birthday". \snippet examples/declarative/extending/valuesource/birthdayparty.h 0 @@ -467,11 +451,11 @@ Property value sources are special types that derive from the 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: +the \c HappyBirthdaySong type declaration looks like this: -\snippet examples/declarative/extending/valuesource/happybirthday.h 0 -\snippet examples/declarative/extending/valuesource/happybirthday.h 1 -\snippet examples/declarative/extending/valuesource/happybirthday.h 2 +\snippet examples/declarative/extending/valuesource/happybirthdaysong.h 0 +\snippet examples/declarative/extending/valuesource/happybirthdaysong.h 1 +\snippet examples/declarative/extending/valuesource/happybirthdaysong.h 2 In all other respects, property value sources are regular QML types. They must be registered with the QML engine using the same macros as other types, and can @@ -479,11 +463,11 @@ contain properties, signals and methods just like other types. When a property value source object is assigned to a property, QML first tries to assign it normally, as though it were a regular QML type. Only if this -assignment fails does the engine call the setTarget() method. This allows +assignment fails does the engine call the \l {QDeclarativePropertyValueSource::}{setTarget()} method. This allows the type to also be used in contexts other than just as a value source. \l {Extending QML - Property Value Source Example} shows the complete code used -implement the HappyBirthday property value source. +implement the \c HappyBirthdaySong property value source. \section1 Property Binding @@ -491,7 +475,7 @@ implement the HappyBirthday property value source. \snippet examples/declarative/extending/binding/example.qml 1 The QML snippet shown above uses a property binding to ensure the -HappyBirthday's name property remains up to date with the celebrant. +\c HappyBirthdaySong's \c name property remains up to date with the \c host. Property binding is a core feature of QML. In addition to assigning literal values, property bindings allow the developer to assign an arbitrarily complex @@ -504,9 +488,9 @@ All properties on custom types automatically support property binding. However, for binding to work correctly, QML must be able to reliably determine when a property has changed so that it knows to reevaluate any bindings that depend on the property's value. QML relies on the presence of a -\c {Qt's Property System}{NOTIFY signal} for this determination. +\l {Qt's Property System}{NOTIFY signal} for this determination. -Here is the celebrant property declaration: +Here is the \c host property declaration: \snippet examples/declarative/extending/binding/birthdayparty.h 0 @@ -578,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 97f5d91..57eaae7 100644 --- a/doc/src/declarative/globalobject.qdoc +++ b/doc/src/declarative/globalobject.qdoc @@ -190,10 +190,10 @@ This function attempts to open the specified \c target url in an external applic This function returns a hex string of the md5 hash of \c data. \section3 Qt.btoa(data) -This function returns a base64 encoding of \c data. +Binary to ASCII - this function returns a base64 encoding of \c data. \section3 Qt.atob(data) -This function returns a base64 decoding of \c data. +ASCII to binary - this function returns a base64 decoding of \c data. \section3 Qt.quit() This function causes the QML engine to emit the quit signal, which in @@ -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{ @@ -258,6 +258,11 @@ of their use. } \endcode + The methods and properties of the Component element are defined in its own + page, but when using it dynamically only two methods are usually used. + Component.createObject() returns the created object or null if there is an error. + If there is an error, Component.errorsString() describes what the error was. + If you want to just create an arbitrary string of QML, instead of loading a QML file, consider the createQmlObject() function. @@ -277,7 +282,9 @@ of their use. similarly to eval, but for creating QML elements. Returns the created object, or null if there is an error. In the case of an - error, details of the error are output using qWarning(). + error, a QtScript Error object is thrown. This object has the additional property, + qmlErrors, which is an array of all the errors encountered when trying to execute the + QML. Each object in the array has the members: lineNumber, columnNumber, fileName and message. Note that this function returns immediately, and therefore may not work if the QML loads new components. If you are trying to load a new component, @@ -286,11 +293,81 @@ of their use. been loaded, and so it is safe to use createQmlObject to load built-in components. -\section1 Asynchronous JavaScript and XML -QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain data from over a network. -\section2 XMLHttpRequest() -In QML you can construct an XMLHttpRequest object just like in a web browser! TODO: Real documentation for this object. +\section1 XMLHttpRequest + +\target XMLHttpRequest + +QML script supports the XMLHttpRequest object, which can be used to asynchronously obtain +data from over a network. + +The XMLHttpRequest API implements the same \l {http://www.w3.org/TR/XMLHttpRequest/}{W3C standard} +as many popular web browsers with following exceptions: +\list +\i QML's XMLHttpRequest does not enforce the same origin policty. +\i QML's XMLHttpRequest does not support \e synchronous requests. +\endlist + +Additionally, the \c responseXML XML DOM tree currently supported by QML is a reduced subset +of the \l {http://www.w3.org/TR/DOM-Level-3-Core/}{DOM Level 3 Core} API supported in a web +browser. The following objects and properties are supported by the QML implementation: +\table +\header +\o \bold {Node} +\o \bold {Document} +\o \bold {Element} +\o \bold {Attr} +\o \bold {CharacterData} +\o \bold {Text} + +\row +\o +\list +\o nodeName +\o nodeValue +\o nodeType +\o parentNode +\o childNodes +\o firstChild +\o lastChild +\o previousSibling +\o nextSibling +\o attribtes +\endlist + +\o +\list +\o xmlVersion +\o xmlEncoding +\o xmlStandalone +\o documentElement +\endlist + +\o +\list +\o tagName +\endlist + +\o +\list +\o name +\o value +\o ownerElement +\endlist + +\o +\list +\o data +\o length +\endlist + +\o +\list +\o isElementContentWhitespace +\o wholeText +\endlist + +\endtable \section1 Offline Storage API diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/declarative/integrating.qdoc index d4034fa..0051f09 100644 --- a/doc/src/declarative/integrating.qdoc +++ b/doc/src/declarative/integrating.qdoc @@ -115,8 +115,7 @@ any custom C++ types and create a plugin that registers the custom types so that they can be used from your QML file. Here is an example. Suppose you have two classes, \c RedSquare and \c BlueCircle, -that both inherit from QGraphicsWidget. First, you need to register these two types -using the \c QML_DECLARE_TYPE macro from \c <QtDeclarative/qdeclarative.h>, like this: +that both inherit from QGraphicsWidget: \c [graphicswidgets/redsquare.h] \snippet doc/src/declarative/snippets/integrating/graphicswidgets/redsquare.h 0 @@ -153,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 8ffe58c..2db7e8e 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -47,7 +47,7 @@ QML encourages building UIs declaratively, using \l {Property Binding} and the composition of existing \l {QML Elements}. To allow the implementation of more advanced behavior, QML integrates tightly with imperative JavaScript code. -The JavaScript environment provided by QML is stricter than that in a webbrowser. +The JavaScript environment provided by QML is stricter than that in a web browser. In QML you cannot add, or modify, members of the JavaScript global object. It is possible to do this accidentally by using a variable without declaring it. In QML this will throw an exception, so all local variables should be explicitly @@ -66,7 +66,7 @@ them. \code Item { function factorial(a) { - a = Integer(a); + a = parseInt(a); if (a <= 0) return 1; else @@ -75,7 +75,7 @@ Item { MouseArea { anchors.fill: parent - onClicked: print(factorial(10)) + onClicked: console.log(factorial(10)) } } \endcode @@ -99,17 +99,17 @@ import "factorial.js" as MathFunctions Item { MouseArea { anchors.fill: parent - onClicked: print(MathFunctions.factorial(10)) + onClicked: console.log(MathFunctions.factorial(10)) } } \endcode -Both relative and absolute JavaScript URLs can be imported. In the case of a -relative URL, the location is resolved relative to the location of the -\l {QML Document} that contains the import. If the script file is not accessible, -an error will occur. If the JavaScript needs to be fetched from a network +Both relative and absolute JavaScript URLs can be imported. In the case of a +relative URL, the location is resolved relative to the location of the +\l {QML Document} that contains the import. If the script file is not accessible, +an error will occur. If the JavaScript needs to be fetched from a network resource, the QML document has a "Loading" -\l {QDeclarativeComponent::status()}{status} until the script has been +\l {QDeclarativeComponent::status()}{status} until the script has been downloaded. Imported JavaScript files are always qualified using the "as" keyword. The @@ -143,7 +143,7 @@ stateless library through the use of a pragma, as shown in the following example .pragma library function factorial(a) { - a = Integer(a); + a = parseInt(a); if (a <= 0) return 1; else @@ -160,7 +160,7 @@ parameters. \section1 Running JavaScript at Startup It is occasionally necessary to run some imperative code at application (or -component instance) "startup". While it is tempting to just include the startup +component instance) startup. While it is tempting to just include the startup script as \e {global code} in an external script file, this can have severe limitations as the QML environment may not have been fully established. For example, some objects might not have been created or some \l {Property Binding}s may not have been run. @@ -180,10 +180,13 @@ Rectangle { } \endcode -Any element in a QML file - including nested elements and nested QML component +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 0a26c68..68768c6 100644 --- a/doc/src/declarative/network.qdoc +++ b/doc/src/declarative/network.qdoc @@ -69,8 +69,10 @@ Network transparency is supported throughout QML, for example: \endlist Even QML types themselves can be on the network - if the \l {Qt Declarative UI Runtime}{qml} tool is used to load -\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", this -will load from \tt http://example.com/mystuff/World.qml just as it would for a local file. +\tt http://example.com/mystuff/Hello.qml and that content refers to a type "World", the engine +will load \tt http://example.com/mystuff/qmldir and resolve the type just as it would for a local file. +For example if the qmldir file contains the line "World World.qml", it will load +\tt http://example.com/mystuff/World.qml Any other resources that \tt Hello.qml referred to, usually by a relative URL, would similarly be loaded from the network. @@ -128,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/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 02f9868..ab3682d 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -78,16 +78,52 @@ Rectangle { } \endcode -Being JavaScript expressions, bindings are evaluated in a scope chain. The \l {QML Scope} -documentation covers the specifics of scoping in QML. - -\list -\o When does a binding not get updated? -\o Scope -\o Assigning a constant/other binding clears existing binding -\o Loops -\o Using model data -\endlist +While syntactically bindings can be of arbitrary complexity, if a binding starts to become +overly complex - such as involving multiple lines, or imperative loops - it may be better +to refactor the component entirely, or at least factor the binding out into a separate +function. + +\section1 Changing Bindings + +The \l PropertyChanges element can be used within a state change to modify the bindings on +properties. + +This example modifies the \l Rectangle's width property binding to be \c {otherItem.height} +when in the "square" state. When it returns to its default state, width's original property +binding will have been restored. + +\code +Rectangle { + id: rectangle + width: otherItem.width + height: otherItem.height + + states: State { + name: "square" + PropertyChanges { + target: rectangle + width: otherItem.height + } + } +} +\endcode + +Imperatively assigning a value directly to a property will also implicitly remove a binding +on a property. A property can only have one value at a time, and if code explicitly sets +this value the binding must be removed. The \l Rectangle in the example below will have +a width of 13, regardless of the otherItem's width. + +\code +Rectangle { + width: otherItem.width + + Component.onCompleted: { + width = 13; + } +} +\endcode + +There is no way to create a property binding directly from imperative JavaScript code. \section1 Binding Element 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/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index d8b2a5d..91acb3c 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -206,8 +206,16 @@ The default role names set by Qt are: \endtable QAbstractItemModel presents a heirachy of tables. Views currently provided by QML -can only display list data. In order to display child lists of a heirachical model -use the VisualDataModel element with \e rootIndex set to a parent node. +can only display list data. +In order to display child lists of a heirachical model +the VisualDataModel element provides several properties and functions for use +with models of type QAbstractItemModel: +\list +\o \e hasModelChildren role property to determine whether a node has child nodes. +\o \l VisualDataModel::rootIndex allows the root node to be specifed +\o \l VisualDataModel::modelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex +\o \l VisualDataModel::parentModelIndex() returns a QModelIndex which can be assigned to VisualDataModel::rootIndex +\endlist \section2 QStringList @@ -225,7 +233,7 @@ dataList.append("Ginger"); dataList.append("Skipper"); QDeclarativeContext *ctxt = view.rootContext(); -ctxt->setContextProperty("myModel", QVariant::fromValue(&dataList)); +ctxt->setContextProperty("myModel", QVariant::fromValue(dataList)); \endcode \o diff --git a/doc/src/declarative/qdeclarativereference.qdoc b/doc/src/declarative/qdeclarativereference.qdoc index b2cfba8..4c1f449 100644 --- a/doc/src/declarative/qdeclarativereference.qdoc +++ b/doc/src/declarative/qdeclarativereference.qdoc @@ -55,7 +55,7 @@ That is, you specify \e what the UI should look like and how it should behave rather than specifying step-by-step \e how to build it. Specifying a UI declaratively does not just include the layout of the interface items, but also the way each - individual item looks and behaves and the overall flow of the application. + individual item looks and behaves and the overall flow of the application. The QML elements provide a sophisticated set of graphical and behavioral building blocks. These different elements are combined together in \l {QML Documents}{QML documents} to build components @@ -67,7 +67,7 @@ \o \l {Introduction to the QML language} \o \l {QML Tutorial}{Tutorial: 'Hello World'} \o \l {QML Advanced Tutorial}{Advanced Tutorial: 'Same Game'} - \o \l {QML Examples and Walkthroughs} + \o \l {QML Examples and Demos} \endlist \section1 Core QML Features: diff --git a/doc/src/declarative/qdeclarativesecurity.qdoc b/doc/src/declarative/qdeclarativesecurity.qdoc index 290d78f..91d6d87 100644 --- a/doc/src/declarative/qdeclarativesecurity.qdoc +++ b/doc/src/declarative/qdeclarativesecurity.qdoc @@ -72,7 +72,7 @@ A non-exhaustive list of the ways you could shoot yourself in the foot is: \list \i Using \c import to import QML or JavaScript you do not control. BAD \i Using \l Loader to import QML you do not control. BAD - \i Using \l{XMLHttpRequest()}{XMLHttpRequest} to load data you do not control and executing it. BAD + \i Using \l{XMLHttpRequest}{XMLHttpRequest} to load data you do not control and executing it. BAD \endlist However, the above does not mean that you have no use for the network transparency of QML. @@ -81,7 +81,7 @@ There are many good and useful things you \e can do: \list \i Create \l Image elements with source URLs of any online images. GOOD \i Use XmlListModel to present online content. GOOD - \i Use \l{XMLHttpRequest()}{XMLHttpRequest} to interact with online services. GOOD + \i Use \l{XMLHttpRequest}{XMLHttpRequest} to interact with online services. GOOD \endlist The only reason this page is necessary at all is that JavaScript, when run in a \e{web browser}, 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/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index cbb2146..670a218 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -70,9 +70,7 @@ \macro QML_DECLARE_TYPE() \relates QDeclarativeEngine - Declares a C++ type to be usable in the QML system. In addition - to this, a type must also be registered with the QML system using - qmlRegisterType(). + Equivalent to Q_DECLARE_METATYPE(TYPE) and Q_DECLARE_METATYPE(QDeclarativeListProperty<TYPE>) */ @@ -81,9 +79,8 @@ \relates QDeclarativeEngine This template function registers the C++ type in the QML system with - the name \a qmlName. in the library imported from \a uri having the + the name \a qmlName, in the library imported from \a uri having the version number composed from \a versionMajor and \a versionMinor. - The type should also haved been declared with the QML_DECLARE_TYPE() macro. Returns the QML type id. @@ -94,6 +91,63 @@ qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game"); \endcode + Note that it's perfectly reasonable for a library to register types to older versions + than the actual version of the library. Indeed, it is normal for the new library to allow + QML written to previous versions to continue to work, even if more advanced versions of + some of its types are available. +*/ + +/*! + \fn int qmlRegisterUncreatableType(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) + \relates QDeclarativeEngine + + This template function registers the C++ type in the QML system with + the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor. + + While the type has a name and a type, it cannot be created, and the + given error \a message will result if creation is attempted. + + This is useful where the type is only intended for providing attached properties or enum values. + + Returns the QML type id. + + \sa qmlRegisterTypeNotAvailable +*/ + +/*! + \fn int qmlRegisterTypeNotAvailable(const char *uri, int versionMajor, int versionMinor, const char *qmlName, const QString& message) + \relates QDeclarativeEngine + + This function registers a type in the QML system with the name \a qmlName, in the library imported from \a uri having the + version number composed from \a versionMajor and \a versionMinor, but any attempt to instantiate the type + will produce the given error \a message. + + Normally, the types exported by a module should be fixed. However, if a C++ type is not available, you should + at least "reserve" the QML type name, and give the user of your module a meaningful error message. + + Returns the QML type id. + + Example: + + \code + #ifdef NO_GAMES_ALLOWED + qmlRegisterTypeNotAvailable("MinehuntCore", 0, 1, "Game", "Get back to work, slacker!"); + #else + qmlRegisterType<MinehuntGame>("MinehuntCore", 0, 1, "Game"); + #endif + \endcode + + This will cause any QML which uses this module and attempts to use the type to produce an error message: + \code +fun.qml: Get back to work, slacker! + Game { + ^ + \endcode + + Without this, a generic "Game is not a type" message would be given. + + \sa qmlRegisterUncreatableType */ /*! @@ -114,7 +168,6 @@ This template function registers the C++ type in the QML system under the name \a typeName. - The type should also haved been declared with the QML_DECLARE_TYPE() macro. Returns the QML type id. 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/integrating/graphicswidgets/bluecircle.h b/doc/src/declarative/snippets/integrating/graphicswidgets/bluecircle.h index 028718f..73d66b7 100644 --- a/doc/src/declarative/snippets/integrating/graphicswidgets/bluecircle.h +++ b/doc/src/declarative/snippets/integrating/graphicswidgets/bluecircle.h @@ -39,7 +39,6 @@ ** ****************************************************************************/ //![0] -#include <QtDeclarative/qdeclarative.h> #include <QGraphicsWidget> #include <QPainter> @@ -53,6 +52,4 @@ public: painter->drawEllipse(0, 0, size().width(), size().height()); } }; - -QML_DECLARE_TYPE(BlueCircle) //![0] diff --git a/doc/src/declarative/snippets/integrating/graphicswidgets/redsquare.h b/doc/src/declarative/snippets/integrating/graphicswidgets/redsquare.h index 76e7d11..3050662 100644 --- a/doc/src/declarative/snippets/integrating/graphicswidgets/redsquare.h +++ b/doc/src/declarative/snippets/integrating/graphicswidgets/redsquare.h @@ -39,7 +39,6 @@ ** ****************************************************************************/ //![0] -#include <QtDeclarative/qdeclarative.h> #include <QGraphicsWidget> #include <QPainter> @@ -52,6 +51,4 @@ public: painter->fillRect(0, 0, size().width(), size().height(), QColor(Qt::red)); } }; - -QML_DECLARE_TYPE(RedSquare) //![0] 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(); diff --git a/doc/src/examples/plugandpaint.qdoc b/doc/src/examples/plugandpaint.qdoc index a502e18..0e2bfd0 100644 --- a/doc/src/examples/plugandpaint.qdoc +++ b/doc/src/examples/plugandpaint.qdoc @@ -513,7 +513,7 @@ Since the approach is identical to \l{tools/plugandpaintplugins/basictools}{Basic Tools}, we won't - review the code here. The only part of interes is the + review the code here. The only part of interest is the \c .pro file, since Extra Filters is a dynamic plugin (\l{tools/plugandpaintplugins/basictools}{Basic Tools} is linked statically into the Plug & Paint executable). diff --git a/doc/src/examples/qml-calculator.qdoc b/doc/src/examples/qml-calculator.qdoc new file mode 100644 index 0000000..ca05da9 --- /dev/null +++ b/doc/src/examples/qml-calculator.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \title Calculator + \example demos/declarative/calculator + + This demo shows how to write a simple calculator application in QML and JavaScript. + + \image qml-calculator-example.png +*/ diff --git a/doc/src/examples/qml-examples.qdoc b/doc/src/examples/qml-examples.qdoc new file mode 100644 index 0000000..93e4a46 --- /dev/null +++ b/doc/src/examples/qml-examples.qdoc @@ -0,0 +1,260 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \title Animations + \example declarative/animations + + This example shows how to use animations in QML. +*/ + +/*! + \title AspectRatio + \example declarative/aspectratio + + This example shows how to implement different aspect ratios in QML. +*/ + +/*! + \example declarative/behaviors + \title Behaviors +*/ + +/*! + \title Border Image + \example declarative/border-image + + This example shows how to use a BorderImage in QML. +*/ + +/*! + \title Clocks + \example declarative/clocks + + This example shows how to create a Clock component and reuse it in a grid. +*/ + +/*! + \title Connections + \example declarative/connections + + This example shows how to use a Connection element in QML. +*/ + +/*! + \title Dial + \example declarative/dial + + This example shows how to implement a dial in QML. +*/ + +/*! + \title Dynamic + \example declarative/dynamic + + This example shows how to create dynamic objects QML. +*/ + +/*! + \example declarative/extending + \title Extending +*/ + +/*! + \example declarative/fillmode + \title Fillmode +*/ + +/*! + \title Flipable + \example declarative/flipable + + This example shows how to use a Flipable element in QML. +*/ + +/*! + \title Focus + \example declarative/focus + + This example shows how to handle keys and focus in QML. + + \image qml-focus-example.png +*/ + +/*! + \example declarative/fonts + \title Fonts +*/ + +/*! + \example declarative/gridview + \title GridView +*/ + +/*! + \example declarative/imageprovider + \title Image Provider +*/ + +/*! + \example declarative/images + \title Images +*/ + +/*! + \example declarative/layouts + \title Layouts +*/ + +/*! + \example declarative/listmodel-threaded + \title ListModel Threaded +*/ + +/*! + \example declarative/listview + \title ListView +*/ + +/*! + \example declarative/mousearea + \title Mouse Area +*/ + +/*! + \example declarative/objectlistmodel + \title Object ListModel +*/ + +/*! + \example declarative/package + \title Package +*/ + +/*! + \example declarative/parallax + \title Parallax +*/ + +/*! + \example declarative/plugins + \title Plugins +*/ + +/*! + \example declarative/progressbar + \title Progress Bars +*/ + +/*! + \example declarative/proxywidgets + \title Proxy Widgets +*/ + +/*! + \example declarative/scrollbar + \title Scrollbar +*/ + +/*! + \example declarative/searchbox + \title Search Box +*/ + +/*! + \example declarative/slideswitch + \title Slide Switch +*/ + +/*! + \example declarative/sql + \title SQL +*/ + +/*! + \example declarative/states + \title States +*/ + +/*! + \example declarative/stringlistmodel + \title String ListModel +*/ + +/*! + \example declarative/tabwidget + \title Tab Widget +*/ + +/*! + \example declarative/tic-tac-toe + \title Tic-Tac-Toe +*/ + +/*! + \example declarative/tvtennis + \title TV Tennis +*/ + +/*! + \example declarative/velocity + \title Velocity +*/ + +/*! + \example declarative/webview + \title WebView +*/ + +/*! + \example declarative/workerscript + \title WorkerScript +*/ + +/*! + \example declarative/xmldata + \title XML Data +*/ + +/*! + \example declarative/xmlhttprequest + \title XMLHttpRequest +*/ diff --git a/doc/src/examples/qml-flickr.qdoc b/doc/src/examples/qml-flickr.qdoc new file mode 100644 index 0000000..ebf3250 --- /dev/null +++ b/doc/src/examples/qml-flickr.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \title Flickr Mobile + \example demos/declarative/flickr + + This demo shows how to write a mobile Flickr browser application in QML. + + \image qml-flickr-example.png +*/ diff --git a/doc/src/examples/qml-minehunt.qdoc b/doc/src/examples/qml-minehunt.qdoc new file mode 100644 index 0000000..773f216 --- /dev/null +++ b/doc/src/examples/qml-minehunt.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \title Minehunt + \example demos/declarative/minehunt + + This demo shows how to create a simple Minehunt game with QML and C++. + + \image qml-minehunt-example.png +*/ diff --git a/doc/src/examples/qml-photoviewer.qdoc b/doc/src/examples/qml-photoviewer.qdoc new file mode 100644 index 0000000..d1c3da2 --- /dev/null +++ b/doc/src/examples/qml-photoviewer.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \title Photo Viewer + \example demos/declarative/photoviewer + + This demo shows how to write a Flickr photo viewer application in QML. + + \image qml-photoviewer-example.png +*/ diff --git a/doc/src/examples/qml-samegame.qdoc b/doc/src/examples/qml-samegame.qdoc new file mode 100644 index 0000000..d9a9c7c --- /dev/null +++ b/doc/src/examples/qml-samegame.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \title Same Game + \example demos/declarative/samegame + + This demo shows how to write a Same Game in QML. + + \image qml-samegame-example.png +*/ diff --git a/doc/src/examples/qml-snake.qdoc b/doc/src/examples/qml-snake.qdoc new file mode 100644 index 0000000..373ca13 --- /dev/null +++ b/doc/src/examples/qml-snake.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \title Snake + \example demos/declarative/snake + + This demo shows how to write a Snake game in QML. + + \image qml-snake-example.png +*/ diff --git a/doc/src/getting-started/examples.qdoc b/doc/src/getting-started/examples.qdoc index 885e96c..071a107 100644 --- a/doc/src/getting-started/examples.qdoc +++ b/doc/src/getting-started/examples.qdoc @@ -151,6 +151,16 @@ classes. \clearfloat + \section1 \l{QML Examples and Demos}{Declarative} + \beginfloatleft + \l{QML Examples and Demos}{\inlineimage declarative-examples.png + } + + \endfloat + The Qt Declarative module provides a declarative framework for building + highly dynamic, custom user interfaces. + + \clearfloat \section1 \l{Painting Examples}{Painting} \beginfloatleft \l{Painting Examples}{\inlineimage painting-examples.png @@ -626,7 +636,7 @@ \previouspage Item Views Examples \contentspage Qt Examples - \nextpage Painting Examples + \nextpage QML Examples and Demos \image graphicsview-examples.png @@ -669,7 +679,7 @@ \page examples-painting.html \title Painting Examples - \previouspage Graphics View Examples + \previouspage QML Examples and Demos \contentspage Qt Examples \nextpage Rich Text Examples @@ -1323,7 +1333,7 @@ \o \l{dbus/complexpingpong}{Complex Ping Pong} \o \l{dbus/listnames}{List Names} \o \l{dbus/pingpong}{Ping Pong} - \o \l{dbus/remotecontrolledcar}{Remote Controlled Car} + \o \l{dbus/remotecontrolledcar}{Remote Controlled Car} \endlist Examples marked with an asterisk (*) are fully documented. diff --git a/doc/src/images/declarative-examples.png b/doc/src/images/declarative-examples.png Binary files differnew file mode 100644 index 0000000..913dfac --- /dev/null +++ b/doc/src/images/declarative-examples.png diff --git a/doc/src/images/qml-calculator-example.png b/doc/src/images/qml-calculator-example.png Binary files differnew file mode 100644 index 0000000..19ce1b6 --- /dev/null +++ b/doc/src/images/qml-calculator-example.png diff --git a/doc/src/images/qml-flickr-example.png b/doc/src/images/qml-flickr-example.png Binary files differnew file mode 100644 index 0000000..71ea567 --- /dev/null +++ b/doc/src/images/qml-flickr-example.png diff --git a/doc/src/images/qml-focus-example.png b/doc/src/images/qml-focus-example.png Binary files differnew file mode 100644 index 0000000..5a114a0 --- /dev/null +++ b/doc/src/images/qml-focus-example.png diff --git a/doc/src/images/qml-minehunt-example.png b/doc/src/images/qml-minehunt-example.png Binary files differnew file mode 100644 index 0000000..3b69569 --- /dev/null +++ b/doc/src/images/qml-minehunt-example.png diff --git a/doc/src/images/qml-photoviewer-example.png b/doc/src/images/qml-photoviewer-example.png Binary files differnew file mode 100644 index 0000000..be6f1bf --- /dev/null +++ b/doc/src/images/qml-photoviewer-example.png diff --git a/doc/src/images/qml-samegame-example.png b/doc/src/images/qml-samegame-example.png Binary files differnew file mode 100644 index 0000000..c17b4e0 --- /dev/null +++ b/doc/src/images/qml-samegame-example.png diff --git a/doc/src/images/qml-snake-example.png b/doc/src/images/qml-snake-example.png Binary files differnew file mode 100644 index 0000000..d3c077d --- /dev/null +++ b/doc/src/images/qml-snake-example.png diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index 2f23e6e..2e6f9bd 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -75,7 +75,7 @@ <li><a href="classes.html">All classes</a></li> <li><a href="namespaces.html">All namespaces</a></li> <li><a href="functions.html">All functions</a></li> - <li><a href="platform-specific.html">Platform support & speciffics</a></li> + <li><a href="platform-specific.html">Platform support & specifics</a></li> </ul> </div> <div class="sectionlist"> diff --git a/doc/src/snippets/code/src_qdbus_qdbusmetatype.cpp b/doc/src/snippets/code/src_qdbus_qdbusmetatype.cpp index d97d61a..800a332 100644 --- a/doc/src/snippets/code/src_qdbus_qdbusmetatype.cpp +++ b/doc/src/snippets/code/src_qdbus_qdbusmetatype.cpp @@ -40,5 +40,6 @@ ****************************************************************************/ //! [0] +#include <QDBusMetaType> qDBusRegisterMetaType<MyClass>(); //! [0] diff --git a/doc/src/snippets/declarative/script.js b/doc/src/snippets/declarative/script.js new file mode 100644 index 0000000..cd67311 --- /dev/null +++ b/doc/src/snippets/declarative/script.js @@ -0,0 +1 @@ +# Just here so that workerscript.qml succeeds. diff --git a/doc/src/template/style/style.css b/doc/src/template/style/style.css index 1c78118..d5920b9 100755 --- a/doc/src/template/style/style.css +++ b/doc/src/template/style/style.css @@ -719,6 +719,21 @@ float: right; color: #254117; } + + .qmldefault + { + float: right; + color: red; + } + + .qmldoc + { + } + + *.qmlitem p + { + } + #feedbackBox { display:none; |
