diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/declarative/advtutorial.qdoc | 2 | ||||
| -rw-r--r-- | doc/src/declarative/advtutorial1.qdoc | 2 | ||||
| -rw-r--r-- | doc/src/declarative/advtutorial2.qdoc | 6 | ||||
| -rw-r--r-- | doc/src/declarative/advtutorial3.qdoc | 18 | ||||
| -rw-r--r-- | doc/src/declarative/advtutorial4.qdoc | 10 | ||||
| -rw-r--r-- | doc/src/declarative/example-slideswitch.qdoc | 134 | ||||
| -rw-r--r-- | doc/src/declarative/examples.qdoc | 50 | ||||
| -rw-r--r-- | doc/src/declarative/globalobject.qdoc | 20 | ||||
| -rw-r--r-- | doc/src/declarative/qtdeclarative.qdoc | 32 |
9 files changed, 199 insertions, 75 deletions
diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc index c796633..60dc0e6 100644 --- a/doc/src/declarative/advtutorial.qdoc +++ b/doc/src/declarative/advtutorial.qdoc @@ -47,6 +47,8 @@ This tutorial goes step-by-step through creating a full application using just Q It is assumed that you already know basic QML (such as from doing the simple tutorial) and the focus is on showing how to turn that knowledge into a complete and functioning application. +This tutorial involves a significant amount of javascript to implement the game logic. An understanding of javascript is helpful to understand the javascript parts of this tutorial, but if you don't understand javascript you can still get a feel for how to integrate QML elements with backend logic which creates and controls them. From the QML perspective, there is little difference between integrating with backend logic written in C++ and backend logic written in javascript. + In this tutorial we recreate, step by step, the Same Game demo in $QTDIR/demos/declarative/samegame.qml. The results of the individual steps are in the $QTDIR/examples/declarative/tutorials/samegame directory. diff --git a/doc/src/declarative/advtutorial1.qdoc b/doc/src/declarative/advtutorial1.qdoc index 66fa607..a96485c 100644 --- a/doc/src/declarative/advtutorial1.qdoc +++ b/doc/src/declarative/advtutorial1.qdoc @@ -70,7 +70,7 @@ And here is a simple block: Since it doesn't do anything yet it's very simple, just an image. As the tutorial progresses and the block starts doing things the file will become -more than just an image. Note that we've set the image to be the size of the itm. +more than just an image. Note that we've set the image to be the size of the item. This will be used later, when we dynamically create and size the block items the image will be scaled automatically to the correct size. diff --git a/doc/src/declarative/advtutorial2.qdoc b/doc/src/declarative/advtutorial2.qdoc index abfdbc6..9fab289 100644 --- a/doc/src/declarative/advtutorial2.qdoc +++ b/doc/src/declarative/advtutorial2.qdoc @@ -62,15 +62,15 @@ The \c initBoard function will be hooked up to the new game button soon, and sho The \c createBlock function is a lot bigger, and I'll explain it block by block. First we ensure that the component has been constructed. QML elements, including composite ones like the \c Block.qml that we've written, are never created directly in script. While there is a function to parse and create an arbitrary QML string, -in the case where you are repeatedly creating the sme item you will want to use the \c createComponent function. \c createComponent is +in the case where you are repeatedly creating the same item you will want to use the \c createComponent function. \c createComponent is a built-in function in the declarative ECMAScript, and returns a component object. A component object prepares and stores a QML element (usually a composite element) for easy and efficient use. When the component is ready, you can create a new instance of the loaded QML with the \c createObject method. If the component is loaded remotely (over HTTP for example) then you will have to wait for the component to finish loading -before calling \c createObject. Since we don't wait here (the waiting is a syncronous, the component object has a signal to tell +before calling \c createObject. Since we don't wait here (the waiting is asyncronous, the component object will send a signal to tell you when it's done) this code will only work if the block QML is a local file. -As we aren't waiting for he component, the next block of code creates a game block with \c{component.createObject}. +As we aren't waiting for the component, the next block of code creates a game block with \c{component.createObject}. Since there could be an error in the QML file you are trying to load, success is not guaranteed. The first bit of error checkign code comes right after \c{createObject()}, to ensure that the object loaded correctly. If it did not load correctly the function returns false, but we don't have that hooked up to the main UI to indicate diff --git a/doc/src/declarative/advtutorial3.qdoc b/doc/src/declarative/advtutorial3.qdoc index 0d236e4..5ac1be3 100644 --- a/doc/src/declarative/advtutorial3.qdoc +++ b/doc/src/declarative/advtutorial3.qdoc @@ -44,7 +44,7 @@ \example declarative/tutorials/samegame/samegame3 \title Advanced Tutorial 3 - Implementing the Game Logic -To the \c initBoard function we added clearing the board beforehand, so that clicking new game won't leave the previous game +First we add to the \c initBoard function clearing of the board before filling it up again, so that clicking new game won't leave the previous game lying around in the background. To the \c createComponent function we have added setting the type of the block to a number between one and three - it's fundamental to the game logic that the blocks be different types if you want a fun game. @@ -58,33 +58,33 @@ The main change was adding the following game logic functions: \endlist As this is a tutorial about QML, not game design, these functions will not be discussed in detail. The game logic here -was written in script, but it could have been written in C++ and had these functions exposed just as well (in fact, probably faster). -The interfacing between these funcions and QML is of interest though. Of these functions, only \c handleClick and \c victoryCheck +was written in script, but it could have been written in C++ and had these functions exposed in the same way (except probably faster). +The interfacing of these functions and QML is what we will focus on. Of these functions, only \c handleClick and \c victoryCheck interface closely with the QML. Those functions are shown below (the rest are still in the code for this tutorial located at \c{$QTDIR/examples/declarative/tutorials/samegame}). \snippet declarative/tutorials/samegame/samegame3/samegame.js 1 \snippet declarative/tutorials/samegame/samegame3/samegame.js 2 -You'll notice them referring to the \c gameCanvas item. This is an item that has been added to the QML for easy interfacing. +You'll notice them referring to the \c gameCanvas item. This is an item that has been added to the QML for easier interfacing with the game logic. It is placed next to the background image and replaces the background as the item to create the blocks in. Its code is shown below: \snippet declarative/tutorials/samegame/samegame3/samegame.qml 1 This item is the exact size of the board, contains a score property, and a mouse region for input. -The blocks are now created as its children, and its size is used to determining the board size. +The blocks are now created as its children, and its size is used to determining the board size, so as to scale to the available screen size. Since it needs to bind its size to a multiple of \c tileSize, \c tileSize needs to be moved into a QML property and out of the script file. -It can still be accessed from the script. +Note that it can still be accessed from the script. The mouse region simply calls \c{handleClick()}, which deals with the input events. Should those events cause the player to score, \c{gameCanvas.score} is updated. The score display text item has also been changed to bind its text property to \c{gamecanvas.score}. Note that if score was a global variable in the \c{samegame.js} file you could not bind to it. You can only bind to QML properties. -\c victoryCheck() mostly just updates score. But it also pops up a dialog saying \e {Game Over} when the game is over. +\c victoryCheck() primarily updates the score variable. But it also pops up a dialog saying \e {Game Over} when the game is over. In this example we wanted a pure-QML, animated dialog, and since QML doesn't contain one, we wrote our own. -Below is the code for the \c Dialog element, note how it's designed so as to be quite usable imperatively from within the script file: +Below is the code for the \c Dialog element, note how it's designed so as to be usable imperatively from within the script file (via the functions and signals): \snippet declarative/tutorials/samegame/samegame3/Dialog.qml 0 @@ -107,7 +107,7 @@ And the code for the block: \snippet declarative/tutorials/samegame/samegame3/Block.qml 0 -The game works, but it's a little boring right now. Where's the smooth animated transitions? Where's the high scores? +The game works, but it's a little boring right now. Where are the smooth animated transitions? Where are the high scores? If you were a QML expert you could have written these in for the first iteration, but in this tutorial they've been saved until the next chapter - where your application becomes alive! diff --git a/doc/src/declarative/advtutorial4.qdoc b/doc/src/declarative/advtutorial4.qdoc index f4724d8..2599e32 100644 --- a/doc/src/declarative/advtutorial4.qdoc +++ b/doc/src/declarative/advtutorial4.qdoc @@ -71,7 +71,7 @@ parameters specified). This is shown in the below snippet of code from \c Block. We also have to change the \c{samegame.js} code, so that wherever it was setting the \c x or \c y it now sets \c targetX and \c targetY (including when creating the block). This simple change is all you need to get spring moving blocks that no longer teleport around the board. If you try doing just this though, you'll notice that they now never jump from one point to another, even in -the initialization! This gives an odd effect of having them all jump out of the corner (0,0) on start up. We'd rather that they +the initialization! This gives an odd effect of having them all slide out of the corner (0,0) on start up. We'd rather that they fall down from the top in rows. To do this, we disable the \c x follow (but not the \c y follow) and only enable it after we've set the \c x in the \c createBlock function. The above snippet now becomes: @@ -84,7 +84,7 @@ image's opacity, like so: \snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 2 -Note that the \c{opacity: 0} makes it start out transparent. We could set the opacity in the script file when we create the blocks, +Note that the \c{opacity: 0} makes it start out transparent. We could set the opacity in the script file when we create and destroy the blocks, but instead we use states (as this is useful for the next animation we'll implement). The below snippet is set on the root element of \c{Block.qml}: \code @@ -129,7 +129,7 @@ if they exit this dialog without entering it they have a way to opt out of posti For offline storage, we use the HTML 5 offline storage javascript API to maintain a persistant SQL database unique to this application. This first line in this function calls the function for the web-based high scores, described later, if it has been setup. Next we create an offline storage database for the high scores using openDatabase and prepare the data and SQL query that we want to use to save it. The offline storage API uses SQL queries for data manipulation and retrival, and in the db.transaction call we use three SQL queries to initialize the database (if necessary), and then add to and retrieve high scores. To use the returned data, we turn it into a string with one line per row returned, and show a dialog containing that string. For a more detailed explanation of the offline storage API in QML, consult the global object documentation. -This is one way of storing and displaying high scores locally, but not the only way. A more complex alternative would have been to create a high score dialog component, and pass the results to it for processing and display (instead of resusing the Dialog). This would allow a more themable dialog that could present the high scores better. If your QML is the UI for a C++ application, you could also have passed the score to a C++ function to store it locally in a variety of ways, including a simple format without SQL. +This is one way of storing and displaying high scores locally, but not the only way. A more complex alternative would have been to create a high score dialog component, and pass the results to it for processing and display (instead of resusing the Dialog). This would allow a more themable dialog that could present the high scores better. If your QML is the UI for a C++ application, you could also have passed the score to a C++ function to store it locally in a variety of ways, including a simple format without SQL or in another SQL database. \section2 Web-based High Scores @@ -143,7 +143,7 @@ if the player entered their name we can send the data to the web service in the \snippet declarative/tutorials/samegame/samegame4/content/samegame.js 1 This is the same \c XMLHttpRequest() as you'll find in 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 here though, we just post the high +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 the blocks. @@ -152,7 +152,7 @@ makes it very easy to fetch and display XML based data such as RSS in a QML appl By following this tutorial you've now ben shown how to write a fully functional application in QML, with the application logic written in a script file and with both many fluid animations and being web-enabled. Congratulations, you should now be skilled -enough to write your own QML applications. +enough to write entire applications in QML. [Previous: \l {Advanced Tutorial 3 - Implementing the Game Logic}] [\l {advtutorial.html}{Advanced Tutorial}] */ diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc new file mode 100644 index 0000000..c942918 --- /dev/null +++ b/doc/src/declarative/example-slideswitch.qdoc @@ -0,0 +1,134 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** 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.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmlexampletoggleswitch.html +\title QML Example - Toggle Switch + +This example shows how to create a reusable switch component in QML. + +The code for this example can be found in the \c $QTDIR/examples/declarative/slideswitch directory. + +\section1 Overview + +The elements that composed the switch are: + +\list +\o a \c on property (the interface to interact with the switch), +\o two images (the background image and the knob), +\o two mouse regions for user interation (on the background image and on the knob), +\o two states (a \e on state and a \e off state), +\o two functions or slots to react to the user interation (\c toggle() and \c dorelease()), +\o and a transition that describe how to go from one state to the other. +\endlist + +\section1 Switch.qml +\snippet examples/declarative/slideswitch/content/Switch.qml 0 + +\section1 Walkthrough + +\section2 Interface +\snippet examples/declarative/slideswitch/content/Switch.qml 1 + +This property is the interface of the switch. By default, the switch is off and this property is \c false. +It can be used to activate/disactivate the switch or to query its current state. + +In this example: + +\qml +Switch { id: mySwitch; on: true } +Text { text: "The switch is on"; visible: mySwitch.on == true } +\endqml + +the text will only be visible when the switch is on. + +\section2 Images and user interaction +\snippet examples/declarative/slideswitch/content/Switch.qml 4 + +First, we create the background image of the switch. +In order for the switch to toggle when the user clicks on the background, we add a \l{MouseRegion} as a child item of the image. +A \c MouseRegion has a \c onClicked property that is triggered when the item is clicked. For the moment we will just call a +\c toggle() function. We will see what this function does in a moment. + +\snippet examples/declarative/slideswitch/content/Switch.qml 5 + +Then, we place the image of the knob on top of the background. +The interaction here is a little more complex. We want the knob to move with the finger when it is clicked. That is what the \c drag +property of the \c MouseRegion is for. We also want to toggle the switch if the knob is released between state. We handle this case +in the \c dorelease() function that is called in the \c onReleased property. + +\section2 States +\snippet examples/declarative/slideswitch/content/Switch.qml 6 + +We define the two states of the switch: +\list +\o In the \e on state the knob is on the right (\c x position is 78) and the \c on property is \c true. +\o In the \e off state the knob is on the left (\c x position is 1) and the \c on property is \c false. +\endlist + +For more information on states see \l{qmlstates}{QML States}. + +\section2 Functions + +We add two ECMAScript functions to our switch: + +\snippet examples/declarative/slideswitch/content/Switch.qml 2 + +This first function is called when the background image or the knob are clicked. We simply want the switch to toggle between the two +states (\e on and \e off). + + +\snippet examples/declarative/slideswitch/content/Switch.qml 3 + +This second function is called when the knob is released and we want to make sure that the knob does not end up between states +(neither \e on nor \e off). If it is the case call the \c toggle() function otherwise we do nothing. + +For more information on scripts see \l{qmlecmascript.html}{ECMAScript Blocks}. + +\section2 Transition +\snippet examples/declarative/slideswitch/content/Switch.qml 7 + +At this point, when the switch toggles between the two states the knob will instantly change its \c x position between 1 and 78. +In order for the the knob to move smoothly we add a transistion that will animate the \c x property with an easing curve for a duration of 200ms. + +For more information on transitions see \l{state-transitions}{QML Transitions}. + +*/ diff --git a/doc/src/declarative/examples.qdoc b/doc/src/declarative/examples.qdoc index 9d66089..7950f66 100644 --- a/doc/src/declarative/examples.qdoc +++ b/doc/src/declarative/examples.qdoc @@ -65,47 +65,25 @@ or Many other simple examples can be found under the \c examples/declarative sub directory. Some can be run directly using the viewer like those above, and -others require you to build and run an executable. More sophisticated demos of -large applications can be found under the \c demos/declarative sub directory. -These are intended to show more integrated functionality rather than to be +others require you to build and run an executable. More sophisticated demos of +large applications can be found under the \c demos/declarative sub directory. +These are intended to show more integrated functionality rather than to be instructive on specific elements. \section1 Examples These will be documented, and demonstrate how to achieve various things in QML. -\raw HTML -<center> -<table cellspacing="10"> -<tr> -<td> -\endraw -\image dial-example.gif -\raw HTML -</td> -<td> -\endraw -\image switch-example.gif -\raw HTML -</td> -<td> -\endraw -\image declarative-adv-tutorial4.gif -\raw HTML -</td> -</tr> -<tr> -<td> -<center>Elastic Dial</center> -</td> -<td> -<center>Touch Toggle Switch</center> -</td> -<td> -<center>Samegame</center> -</td> -</table> -</center> -\endraw +\table +\row + \o Elastic Dial + \o \image dial-example.gif +\row + \o \l{qmlexampletoggleswitch.html}{Toggle Switch} + \o \image switch-example.gif +\row + \o \l{Advanced Tutorial}{SameGame} + \o \image declarative-adv-tutorial4.gif +\endtable */ diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc index e983ad0..e3c8b9a 100644 --- a/doc/src/declarative/globalobject.qdoc +++ b/doc/src/declarative/globalobject.qdoc @@ -64,7 +64,7 @@ files. The Qt object contains all enums in the Qt namespace. For example, you can access the AlignLeft member of the Qt::AlignmentFlag enum with \c Qt.AlignLeft. -For a full list of enums, see the Qt Namespace documentation. +For a full list of enums, see the \l{Qt Namespace} documentation. \section2 Types The Qt object also contains helper functions for creating objects of specific @@ -88,20 +88,20 @@ This function returns a Color with the specified \c red, \c green, \c blue and \ This function returns a Color with the specified \c hue, \c saturation, \c lightness and \c alpha components. All components should be in the range 0-1 inclusive. \section3 Qt.rect(int x, int y, int width, int height) -This function returns a Rect with the top-left corner at \c x,\c y and the specified \c width and \c height. +This function returns a Rect with the top-left corner at \c x, \c y and the specified \c width and \c height. \section3 Qt.point(int x, int y) This function returns a Point with the specified \c x and \c y coordinates. \section3 Qt.size(int width, int height) -This function returns as Size with the specified width and height. +This function returns as Size with the specified \c width and \c height. \section3 Qt.vector3d(real x, real y, real z) -This function returns a Vector3D with the specified x, y and z. +This function returns a Vector3D with the specified \c x, \c y and \c z. \section2 Functions The Qt object also contains the following miscellaneous functions which expose Qt functionality for use in QML. \section3 Qt.lighter(color baseColor) This function returns a color 50% lighter than \c baseColor. See QColor::lighter() for further details. \section3 Qt.darker(color baseColor) -This function returns a color 50% darker than \c baseColor. See QColor::lighter() for further details. +This function returns a color 50% darker than \c baseColor. See QColor::darker() for further details. \section3 Qt.tint(color baseColor, color tintColor) This function allows tinting one color with another. @@ -117,6 +117,16 @@ This function returns a color 50% darker than \c baseColor. See QColor::lighter( \section3 Qt.closestAngle(number fromAngle, number toAngle) This function returns an equivalent angle to toAngle, such that the difference between fromAngle and toAngle is never more than 180 degrees. This is useful when animating angles using a NumberAnimation, which does not know about equivalent angles, when you always want to take the shortest path. +For example, the following would rotate myItem counterclockwise from 350 degrees to 10 degrees, for a total of 340 degrees of rotation. +\qml +NumberAnimation { target: myItem; property: "rotation"; from: 350; to: 10 } +\endqml + +while the following would rotate myItem clockwise from 350 degrees to 370 degrees (which is visually equivilant to 10 degrees), for a total of 20 degrees of rotation. +\qml +NumberAnimation { target: myItem; property: "rotation"; from: 350; to: Qt.closetAngle(350, 10) } +\endqml + \section3 Qt.playSound(url soundLocation) This function plays the audio file located at \c soundLocation. Only .wav files are supported. diff --git a/doc/src/declarative/qtdeclarative.qdoc b/doc/src/declarative/qtdeclarative.qdoc index ea8e198..e46cbab 100644 --- a/doc/src/declarative/qtdeclarative.qdoc +++ b/doc/src/declarative/qtdeclarative.qdoc @@ -45,29 +45,29 @@ \ingroup modules \brief The Qt Declarative module provides a declarative framework for building -highly dynamic, custom UIs +highly dynamic, custom user interfaces. -Qt Declarative aids programmers and designers in building the animation rich, -highly fluid user interfaces that are becoming common in portable consumer -electronics 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} that can be used +Qt Declarative aids programmers and designers in building the animation rich, +highly fluid user interfaces that are becoming common in portable consumer +electronics 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. QML is an extension to \l {http://www.ecma-international.org/publications/standards/Ecma-262.htm} -{ECMAScript}, that provides a mechanism to declaratively build an object tree -of \l {QML Elements}. QML improves the integration between ECMAScript and Qt's -existing QObject based type system, adds support for automatic -\l {Property Binding}s and provides \l {Network Transparency} at the language +{ECMAScript}, that provides a mechanism to declaratively build an object tree +of QML elements. QML improves the integration between ECMAScript and Qt's +existing QObject based type system, adds support for automatic +\l {Property Binding}{property bindings} and provides \l {Network Transparency}{network transparency} at the language level. -The \l {QML Elements} are a sophisticated set of graphical and behavioral building -blocks. \l {QML Elements} are combined together in \l {QML Documents} to build components -ranging in complexity from simple pushbuttons and sliders, to complete -internet-enabled applications like a \l {http://www.flickr.com}{flickr} photo browser. +The QML elements are a sophisticated set of graphical and behavioral building +blocks. These different elements are combined together in \l {QML Documents}{QML documents} to build components +ranging in complexity from simple buttons and sliders, to complete +internet-enabled applications like a \l {http://www.flickr.com}{Flickr} photo browser. Qt Declarative builds on \l {QML for Qt programmers}{Qt's existing strengths}. -QML can be be used to incrementally extend an existing application or to build +QML can be be used to incrementally extend an existing application or to build completely new applications. QML is fully \l {Extending QML}{extensible from C++}. \section1 Getting Started: @@ -76,7 +76,7 @@ completely new applications. QML is fully \l {Extending QML}{extensible from C+ \o \l {Tutorial}{Tutorial: 'Hello World'} \o \l {advtutorial.html}{Tutorial: 'Same Game'} \o \l {QML Examples and Walkthroughs} -\o \l {Using QML in C++ Applications} +\o \l {Using QML in C++ Applications} \endlist \section1 Core QML Features: |