summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorAlan Alpert <alan.alpert@nokia.com>2010-05-05 18:56:41 (GMT)
committerAlan Alpert <alan.alpert@nokia.com>2010-05-05 18:56:41 (GMT)
commit57c6b39a72e037fe50cda7005cea79d1c4dcd888 (patch)
tree1c594add8e5b8598322d2cd88a537e965738cac0 /doc
parent0a8379d9f01118d7ff0121e6ecbbc0307e1e7f63 (diff)
parentd340dc6e4b3f1f4f8737d0d1d34e76ae68e007d6 (diff)
downloadQt-57c6b39a72e037fe50cda7005cea79d1c4dcd888.zip
Qt-57c6b39a72e037fe50cda7005cea79d1c4dcd888.tar.gz
Qt-57c6b39a72e037fe50cda7005cea79d1c4dcd888.tar.bz2
Merge branch '4.7' of git@scm.dev.nokia.troll.no:qt/qt-qml into 4.7
Diffstat (limited to 'doc')
-rw-r--r--doc/src/declarative/advtutorial.qdoc52
-rw-r--r--doc/src/declarative/basictypes.qdoc9
-rw-r--r--doc/src/declarative/qdeclarativemodels.qdoc11
-rw-r--r--doc/src/declarative/qmlruntime.qdoc17
-rw-r--r--doc/src/declarative/tutorial.qdoc29
5 files changed, 89 insertions, 29 deletions
diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc
index 42ce246..8f95190 100644
--- a/doc/src/declarative/advtutorial.qdoc
+++ b/doc/src/declarative/advtutorial.qdoc
@@ -109,12 +109,16 @@ Notice the anchors for the \c Item, \c Button and \c Text elements are set using
\section2 Adding \c Button and \c Block components
-The \c Button item in the code above is defined in a separate file named \c Button.qml.
+The \c Button item in the code above is defined in a separate component file named \c Button.qml.
To create a functional button, we use the QML elements \l Text and \l MouseArea inside a \l Rectangle.
Here is the \c Button.qml code:
\snippet declarative/tutorials/samegame/samegame1/Button.qml 0
+This essentially defines a rectangle that contains text and can be clicked. The \l MouseArea
+has an \c onClicked() handler that is implemented to emit the \c clicked() signal of the
+\c container when the area is clicked.
+
In Same Game, the screen is filled with small blocks when the game begins.
Each block is just an item that contains an image. The block
code is defined in a separate \c Block.qml file:
@@ -226,14 +230,14 @@ until it is won or lost.
To do this, we have added the following functions to \c samegame.js:
\list
-\o function \c{handleClick(x,y)}
-\o function \c{floodFill(xIdx,yIdx,type)}
-\o function \c{shuffleDown()}
-\o function \c{victoryCheck()}
-\o function \c{floodMoveCheck(xIdx, yIdx, type)}
+\o \c{handleClick(x,y)}
+\o \c{floodFill(xIdx,yIdx,type)}
+\o \c{shuffleDown()}
+\o \c{victoryCheck()}
+\o \c{floodMoveCheck(xIdx, yIdx, type)}
\endlist
-As this is a tutorial about QML, not game design, we will only discuss \c handleClick() and \c victoryCheck() below since they interface directly with the QML elements. Note that although the game logic here is written in JavaScript, it could have been written in C++ and then exposed to JavaScript.
+As this is a tutorial about QML, not game design, we will only discuss \c handleClick() and \c victoryCheck() below since they interface directly with the QML elements. Note that although the game logic here is written in JavaScript, it could have been written in C++ and then exposed to QML.
\section3 Enabling mouse click interaction
@@ -269,6 +273,8 @@ And this is how it is used in the main \c samegame.qml file:
\snippet declarative/tutorials/samegame/samegame3/samegame.qml 2
+We give the dialog a \l {Item::z}{z} value of 100 to ensure it is displayed on top of our other components. The default \c z value for an item is 0.
+
\section3 A dash of color
@@ -383,15 +389,41 @@ The theme change here is produced simply by replacing the block images. This can
Another feature we might want to add to the game is a method of storing and retrieving high scores.
-In \c samegame.qml we now pop up a dialog when the game is over and requests the player's name so it can be added to a High Scores table. The dialog is created using \c Dialog.qml:
+To do this, we will show a dialog when the game is over to request the player's name and add it to a High Scores table.
+This requires a few changes to \c Dialog.qml. In addition to a \c Text element, it now has a
+\c TextInput child item for receiving keyboard text input:
+
+\snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 0
+\dots 4
+\snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 2
+\dots 4
+\snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 3
+
+We'll also add a \c showWithInput() function. The text input will only be visible if this function
+is called instead of \c show(). When the dialog is closed, it emits a \c closed() signal, and
+other elements can retrieve the text entered by the user through an \c inputText property:
+
+\snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 0
+\snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 1
+\dots 4
+\snippet declarative/tutorials/samegame/samegame4/content/Dialog.qml 3
+
+Now the dialog can be used in \c samegame.qml:
\snippet declarative/tutorials/samegame/samegame4/samegame.qml 0
-When the dialog is closed, we call the new \c saveHighScore() function in \c samegame.js, which stores the high score locally in an SQL database and also send the score to an online database if possible.
+When the dialog emits the \c closed signal, we call the new \c saveHighScore() function in \c samegame.js, which stores the high score locally in an SQL database and also send the score to an online database if possible.
+The \c nameInputDialog is activated in the \c victoryCheck() function in \c samegame.js:
+
+\snippet declarative/tutorials/samegame/samegame4/content/samegame.js 3
+\dots 4
+\snippet declarative/tutorials/samegame/samegame4/content/samegame.js 4
\section3 Storing high scores offline
+Now we need to implement the functionality to actually save the High Scores table.
+
Here is the \c saveHighScore() function in \c samegame.js:
\snippet declarative/tutorials/samegame/samegame4/content/samegame.js 2
@@ -436,6 +468,6 @@ By following this tutorial you've seen how you can write a fully functional appl
\endlist
There is so much more to learn about QML that we haven't been able to cover in this tutorial. Check out all the
-demos and examples and the \l {Declarative UI (QML)}{documentation} to find out all the things you can do with QML!
+demos and examples and the \l {Declarative UI Using QML}{documentation} to find out all the things you can do with QML!
*/
diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc
index 6901947..8db1c35 100644
--- a/doc/src/declarative/basictypes.qdoc
+++ b/doc/src/declarative/basictypes.qdoc
@@ -43,9 +43,12 @@
\page qdeclarativebasictypes.html
\title QML Basic Types
- QML uses a set of property types, which are primitive within QML.
- These basic types are referenced throughout the documentation of the
- QML elements. Almost all of them are exactly what you would expect.
+ QML has a set of primitive types, as listed below, that are used throughout
+ the \l {QML Elements}.
+
+ The simpler types in this list can also be used for defining a new
+ \c property in a component. See \l{Extending types from QML} for the
+ list of types that can be used for custom properties.
\annotatedlist qmlbasictypes
*/
diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc
index 91acb3c..9b706a1 100644
--- a/doc/src/declarative/qdeclarativemodels.qdoc
+++ b/doc/src/declarative/qdeclarativemodels.qdoc
@@ -283,7 +283,9 @@ QDeclarativeContext *ctxt = view.rootContext();
ctxt->setContextProperty("myModel", QVariant::fromValue(dataList));
\endcode
-The properties of the object may then be accessed in the delegate:
+The QObject* is available as the \c modelData property. As a convenience,
+the properties of the object are also made available directly in the
+delegate's context:
\code
ListView {
@@ -295,13 +297,18 @@ ListView {
Rectangle {
height: 25
width: 100
- color: model.color
+ color: model.modelData.color
Text { text: name }
}
}
}
\endcode
+Note the use of the fully qualified access to the \c color property.
+The properties of the object are not replicated in the \c model
+object, since they are easily available via the modelData
+object.
+
Note: There is no way for the view to know that the contents of a QList
have changed. If the QList is changed, it will be necessary to reset
the model by calling QDeclarativeContext::setContextProperty() again.
diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc
index a724c7d..23c5c32 100644
--- a/doc/src/declarative/qmlruntime.qdoc
+++ b/doc/src/declarative/qmlruntime.qdoc
@@ -112,6 +112,23 @@
When run with the \c -help option, qml shows available options.
+ \section2 Translations
+
+ When the runtime loads an initial QML file, it will install a translation file from
+ a "i18n" subdirectory relative to that initial QML file. The actual translation file
+ loaded will be according to the system locale and have the form
+ "qml_<language>.qm", where <language> is a two-letter ISO 639 language,
+ such as "qml_fr.qm", optionally followed by an underscore and an uppercase two-letter ISO 3166 country
+ code, such as "qml_fr_FR.qm" or "qml_fr_CA.qm".
+
+ Such files can be created using \l{Qt Linguist}.
+
+ See \l{scripting.html#internationalization} for information about how to make
+ the JavaScript in QML files use translatable strings.
+
+ Additionally, the QML runtime will load translation files specified on the
+ command line via the \c -translation option.
+
\section2 Dummy Data
The secondary use of the qml runtime is to allow QML files to be viewed with
diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc
index 1a93d05..75c0f851 100644
--- a/doc/src/declarative/tutorial.qdoc
+++ b/doc/src/declarative/tutorial.qdoc
@@ -57,10 +57,10 @@ The tutorial's source code is located in the $QTDIR/examples/declarative/tutoria
Tutorial chapters:
-\list
-\o \l {QML Tutorial 1 - Basic Types}
-\o \l {QML Tutorial 2 - QML Component}
-\o \l {QML Tutorial 3 - States and Transitions}
+\list 1
+\o \l {QML Tutorial 1 - Basic Types}{Basic Types}
+\o \l {QML Tutorial 2 - QML Components}{QML Components}
+\o \l {QML Tutorial 3 - States and Transitions}{States and Transitions}
\endlist
*/
@@ -86,7 +86,7 @@ Here is the QML code for the application:
\section2 Import
First, we need to import the types that we need for this example. Most QML files will import the built-in QML
-types (like \l{Rectangle}, \l{Image}, ...) that come with Qt with:
+types (like \l{Rectangle}, \l{Image}, ...) that come with Qt, using:
\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 3
@@ -95,7 +95,7 @@ types (like \l{Rectangle}, \l{Image}, ...) that come with Qt with:
\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 1
We declare a root element of type \l{Rectangle}. It is one of the basic building blocks you can use to create an application in QML.
-We give it an \c{id} to be able to refer to it later. In this case, we call it \e page.
+We give it an \c{id} to be able to refer to it later. In this case, we call it "page".
We also set the \c width, \c height and \c color properties.
The \l{Rectangle} element contains many other properties (such as \c x and \c y), but these are left at their default values.
@@ -103,15 +103,16 @@ The \l{Rectangle} element contains many other properties (such as \c x and \c y)
\snippet examples/declarative/tutorials/helloworld/tutorial1.qml 2
-We add a \l Text element as a child of our root element that will display the text 'Hello world!'.
+We add a \l Text element as a child of the root Rectangle element that displays the text 'Hello world!'.
The \c y property is used to position the text vertically at 30 pixels from the top of its parent.
-The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{dot properties}{dot notation}.
-
The \c anchors.horizontalCenter property refers to the horizontal center of an element.
In this case, we specify that our text element should be horizontally centered in the \e page element (see \l{anchor-layout}{Anchor-based Layout}).
+The \c font.pointSize and \c font.bold properties are related to fonts and use the \l{dot properties}{dot notation}.
+
+
\section2 Viewing the example
To view what you have created, run the \l{Qt Declarative UI Runtime}{qml} tool (located in the \c bin directory) with your filename as the first argument.
@@ -124,7 +125,7 @@ bin/qml $QTDIR/examples/declarative/tutorials/helloworld/tutorial1.qml
/*!
\page qml-tutorial2.html
-\title QML Tutorial 2 - QML Component
+\title QML Tutorial 2 - QML Components
\contentspage QML Tutorial
\previouspage QML Tutorial 1 - Basic Types
\nextpage QML Tutorial 3 - States and Transitions
@@ -134,10 +135,10 @@ This chapter adds a color picker to change the color of the text.
\image declarative-tutorial2.png
Our color picker is made of six cells with different colors.
-To avoid writing the same code multiple times, we first create a new \c Cell component.
+To avoid writing the same code multiple times for each cell, we create a new \c Cell component.
A component provides a way of defining a new type that we can re-use in other QML files.
-A QML component is like a black-box and interacts with the outside world through properties, signals and slots and is generally
-defined in its own QML file (for more details, see \l {Defining new Components}).
+A QML component is like a black-box and interacts with the outside world through properties, signals and functions and is generally
+defined in its own QML file. (For more details, see \l {Defining new Components}).
The component's filename must always start with a capital letter.
Here is the QML code for \c Cell.qml:
@@ -157,7 +158,7 @@ An \l Item is the most basic visual element in QML and is often used as a contai
We declare a \c cellColor property. This property is accessible from \e outside our component, this allows us
to instantiate the cells with different colors.
-This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{intro-properties}{Properties}).
+This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Adding new properties}).
\snippet examples/declarative/tutorials/helloworld/Cell.qml 5