This tutorial walks step-by-step through the creation of a full application using QML.
It assumes that you already know the basics of QML (for example, from reading the
-\l{QML Tutorial}{simple tutorial}).
+\l{QML Tutorial}{simple tutorial}).
In this tutorial we write a game, \e {Same Game}, based on the Same Game application
included in the declarative \c examples directory, which looks like this:
\image declarative-samegame.png
We will cover concepts for producing a fully functioning application, including
-JavaScript integration, using QML \l{State}{States} and \l{Behavior}{Behaviors} to
+JavaScript integration, using QML \l{State}{States} and \l{Behavior}{Behaviors} to
manage components and enhance your interface, and storing persistent application data.
An understanding of JavaScript is helpful to understand parts of this tutorial, but if you don't
later on in the tutorial, the image will be scaled automatically to the
correct size.
-Notice the relative path for the Image element's \c source property.
+Notice the relative path for the Image element's \c source property.
This path is relative to the location of the file that contains the \l Image element.
Alternatively, you could set the Image source to an absolute file path or a URL
that contains an image.
The first task is to generate the game blocks. Each time the New Game button
is clicked, the game canvas is populated with a new, random set of
blocks. Since we need to dynamically generate new blocks for each new game,
-we cannot use \l Repeater to define the blocks. Instead, we will
+we cannot use \l Repeater to define the blocks. Instead, we will
create the blocks in JavaScript.
Here is the JavaScript code for generating the blocks, contained in a new
\snippet declarative/tutorials/samegame/samegame2/samegame.qml 2
This allows us to refer to any functions within \c samegame.js using "SameGame"
-as a prefix: for example, \c SameGame.startNewGame() or \c SameGame.createBlock().
+as a prefix: for example, \c SameGame.startNewGame() or \c SameGame.createBlock().
This means we can now connect the New Game button's \c onClicked handler to the \c startNewGame()
function, like this:
\li \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 QML.
+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
Note the \c{opacity: 0} which means the block is transparent when it is first created. We could set the opacity
in \c samegame.js when we create and destroy the blocks,
-but instead we'll use \l{QML States}{states}, since this is useful for the next animation we're going to add.
+but instead we'll use \l{States}{states}, since this is useful for the next animation we're going to add.
Initially, we add these States to the root element of \c{BoomBlock.qml}:
\code
property bool dying: false
\snippet declarative/tutorials/samegame/samegame4/samegame.qml 0
-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.
+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:
\list
\li Build your application with \l {{QML Elements}}{QML elements}
\li Add application logic \l{JavaScript Expressions in QML}{with JavaScript code}
-\li Add animations with \l {Behavior}{Behaviors} and \l{QML States}{states}
+\li Add animations with \l {Behavior}{Behaviors} and \l{States}{states}
\li Store persistent application data using, for example, the \l{Offline Storage API} or \l XMLHttpRequest
\endlist
\li 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}.
+For more information on states see \l{States}.
\section2 Functions
The \l ParallelAnimation element makes sure that the two types of animations (number and color) start at the same time.
We could also run them one after the other by using \l SequentialAnimation instead.
-For more details on states and transitions, see \l {QML States} and the \l{declarative/animation/states}{states and transitions example}.
+For more details on states and transitions, see \l {States} and the \l{declarative/animation/states}{states and transitions example}.
*/
****************************************************************************/
/*!
\page qml-localstorage.html
-\title QML Local Storage
+\title Local Storage
\brief SQL storage for QML
The local storage API provides a JavaScript interface to an SQL relational
/*!
\page qml-particlesystem-performance.html
\inqmlmodule QtQuick 2
- \title Qt Quick Particle System Performance Guide
+ \title Particle System Performance Guide
The performance of the particle system scales with the number of particles it is maintaining. After prototyping the desired
effect, performance can be improved by lowering the particle count. Conversely, if performance is well within the acceptable
It should be noted that a particle system can be disabled when not in use
(e.g., on a non-visible element) to avoid doing unnecessary simulation.
-See the \l{Qt Quick Particle System Performance Guide} for more in-depth information.
+See the \l{Particle System Performance Guide} for more in-depth information.
\section2 Shaders
\li \l{JavaScript Expressions in QML}{JavaScript functions} - for performing routines and logic
\li \l{QML Signal and Handler Event System}{Signals and handlers} - t notify other
objects about events
-\li \l{QML States}{States} and \l{QML Animation and Transitions}{Transitions}
+\li \l{States} and \l{QML Animation and Transitions}{Transitions}
\li many others
\endlist
For information about these features, visit the respective overviews or the
/*!
\page qtquick-animation.html
-\ingroup qml-features
-\title QML Animation and Transitions
+\title Animation and Transitions
\brief the animation system in Qt Quick
-\keyword qml-animation-elements
\section1 Animation and Transitions Elements
\list
\li \l {Transition} - Animates transitions during state changes
\li \l {ScriptAction} - Runs scripts during an animation
\endlist
-\keyword qml-property-animation-elements
Elements that animate properties based on data types
\list
\li \l {PropertyAnimation} - Animates property changes
\li \l {AnchorAnimation} - Animates anchor changes
\endlist
-In QML, animations are created by applying animation elements to property
+Animations are created by applying animation elements to property
values. Animation elements will interpolate property values to create smooth
transitions. As well, state transitions may assign animations to state changes.
the property that is to be animated, and apply the animation depending on the
type of behavior that is required.
-\keyword qml-triggering-animations
\section1 Triggering Animations
There are several ways of setting animation to an object.
-\keyword qml-direct-animation
\section2 Direct Property Animation
To create an immediate movement or animated movement, set the property value
\keyword qml-transition-animations
\section2 Transitions during State Changes
-\l{QML States}{States} are property configurations where a property may have different values to reflect different states. State changes introduce
+\l{States}{States} are property configurations where a property may have different values to reflect different states. State changes introduce
abrupt property changes; animations smooth transitions to produce visually
appealing state changes.
/*!
\page qtquick-basicelements.html
\ingroup qml-features
-\title Qt Quick Basic Elements
+\title Basic Elements
\brief introduction to the Qt Quick Elements
Qt Quick includes \e elements for placing components. These can be combined
\section1 Additional Elements
-The \l{QML Local Storage}{SQL Local Storage API} provides a JavaScript interface to an SQL relational
+The \l{Local Storage}{SQL Local Storage API} provides a JavaScript interface to an SQL relational
database. The import statement needs a namespace
\code
/*!
\page qtquick-elements.html
-\title QML Elements
-\brief a listing of standard QML elements
+\title Qt Quick Elements
+\brief a listing of standard elements in Qt Quick
\target elements
-These are the functionally grouped lists of QML elements as part of
+These are the functionally grouped lists of Qt Quick elements as part of
\l{Qt Quick}. You can also browse the module pages for \l{QtQuick 2} and \l{QtQuick.Particles 2}
Elements are declared with the their name and two curly braces. Elements may
be nested in elements, thereby creating a parent-child relationship between the
two elements.
-To see the QML elements listed by functional area, see the
-\l{Groups Of Related QML Elements} page.
-
-\section1 Basic QML Elements
+\section1 Basic Elements
\list
-\li \l {Item} - Basic item element inherited by QML elements
-\li \l {Component} - Encapsulates QML elements during importing
-\li \l {QtObject} {QtObject} - Basic element containing only the \c {objectName} property
+\li \l {Item} - Basic item element inherited by visual elements
\endlist
\section1 Graphics
\list
\li \l {Connections} - Explicitly connects signals and signal handlers
\li \l {Timer} - Provides timed triggers
-\li \l {QmlGlobalQtObject}{Qt} - The QML global Qt object provides useful enums and functions from Qt.
-\li \l {WorkerScript} - Enables the use of threads in QML
\li \l {Loader} - Controls the loading of items or components
\endlist
\endlist
*/
-
-
-/*!
- \group qml-groups
- \title Groups Of Related QML Elements
-
- \brief If you know what kind of QML element you want (Basic Visual,
- Interaction, Animation, etc), look here.
-
- This is a list of functional groups of QML elements.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-basic-visual-elements
- \title Basic QML Visual Elements
- \ingroup qml-groups
-
- \brief Elements for constructing basic visual items.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-basic-interaction-elements
- \title Basic QML Interaction Elements
- \ingroup qml-groups
-
- \brief Elements for handling basic interactions.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-state-elements
- \title QML State Elements
- \ingroup qml-groups
-
- \brief Elements for handling state changes.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-event-elements
- \title QML Event Elements
- \ingroup qml-groups
-
- \brief Elements for handling events.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-animation-transition
- \title QML Animation and Transition Elements
- \ingroup qml-groups
-
- \brief Elements for handling animations and transitions.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-working-with-data
- \title Working With Data in QML
- \ingroup qml-groups
-
- \brief Elements for working with data.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-view-elements
- \title QML View Elements
- \ingroup qml-groups
-
- \brief Elements for handling views.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-positioning-elements
- \title QML Positioning Elements
- \ingroup qml-groups
-
- \brief Elements for positioning items.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-utility-elements
- \title QML Utility Elements
- \ingroup qml-groups
-
- \brief Elements for handling misc operations.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-transform-elements
- \title QML Transform Elements
- \ingroup qml-groups
-
- \brief Elements for handling transformations.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-particle-elements
- \title QML Particle Elements
- \ingroup qml-groups
-
- \brief Elements for handling particle effects.
-
- This is the QtQuick 1.0 particle system, incompatible with QtQuick 2.0
-
- There is a completely separate \l{QtQuick.Particles 2}{QtQuick 2.0 particle system}
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-shader-elements
- \title QML Shader Elements
- \ingroup qml-groups
-
- \brief Elements for using OpenGL shading language code together with the QML code.
-
- \generatelist{related}
-
-*/
-
-/*!
- \group qml-shader-elements
- \title QML Shader Elements
- \ingroup qml-groups
-
- \brief Elements for using OpenGL shading language code together with the QML code.
-
- \generatelist{related}
-
-*/
****************************************************************************/
/*!
\page qtquick-modelview.html
-\title QML Models and Views
+\title Models and Views
\brief how to display and form data in QML
Simply put, applications need to form data and display the data. QML has the
/*!
\page qtquick-mouseevents.html
\ingroup QML Features
-\title QML Mouse Events
+\title Mouse Events
\brief handling mouse events in QML
\tableofcontents
user interfaces. Where there are lots of items to be arranged, it can be more
productive to use \l{#Positioners}{positioners} and
\l{Generating Items with Repeaters}{repeaters}, or
-\l{QML Models and Views}{models and views}.
+\l{Models and Views}{models and views}.
Connections between anchors cannot be deleted and will override explicit
declarations of positions and sizes using the \l{Item::}{x}, \l{Item::}{y},
/*!
\page qtquick-texthandling.html
-\ingroup QML Features
-
-\title QML Text Handling and Validators
+\title Text Handling and Validators
\brief elements that accept and handle text input
\tableofcontents
Graphics and Special Effects
\enddiv
\list
- \li \l{Qt Quick Basic Elements}{Basic Elements}
+ \li \l{Basic Elements}{Basic Elements}
\li \l{Painting with Canvas API}
\li \l{Using the Qt Quick Particle System}{Particle Effects}
\li \l{Shader Effects in QML}{Shader Effects}
\list
\li \l{Component Layouts}
\li \l{Layouts with Anchors}
- \li \l{QML Right-to-left User Interfaces}{Right-to-left User Interfaces}
+ \li \l{Right-to-left User Interfaces}{Right-to-left User Interfaces}
\endlist
\enddiv
\div {class="threecolumn_piece"}
Mouse and Keyboard Input
\enddiv
\list
- \li \l{QML Mouse Events}{Mouse Events}
- \li \l{QML Text Handling and Validators}{Text Handling and Validators}
+ \li \l{Mouse Events}{Mouse Events}
+ \li \l{Text Handling and Validators}{Text Handling and Validators}
\li \l{Keyboard Focus in QML}{Keyboard Focus}
\endlist
\enddiv
States and Transitions
\enddiv
\list
- \li \l{QML States}{States}
+ \li \l{States}{States}
\li \l{QML Animation and Transitions}{Animation and Transitions}
\endlist
\enddiv
Data with Models and Views
\enddiv
\list
- \li \l{QML Models and Views}{Models and Views}
- \endlist
+ \li {Models and Views}
+ \endlist
\enddiv
\div {class="threecolumn_piece"}
\div {class="heading"}
Data Storage and Resources
\enddiv
\list
- \li \l{QML Local Storage}{SQL Local Storage}
+ \li \l{Local Storage}{SQL Local Storage}
\li \l{Resource Loading and Network Transparency in QML}{Resources and Network Transparency}
\endlist
\enddiv
/*!
\page qtquick-righttoleft.html
\ingroup qml-features
-\title QML Right-to-left User Interfaces
+\title Right-to-left User Interfaces
\brief switching text flow and layout
\section1 Overview
The attached property \l LayoutMirroring is provided as a convenience for easily implementing right-to-left
support for existing left-to-right Qt Quick applications. It mirrors the behavior of \l {anchor-layout}
{Item anchors}, the layout direction of \l{Composing User Interfaces with QML#Positioners}{positioners} and
-\l{QML Models and Views}{model views}, and the explicit text alignment of QML text elements.
+\l{Models and Views}{model views}, and the explicit text alignment of QML text elements.
You can enable layout mirroring for a particular \l Item:
/*!
\page qtquick-states.html
-\ingroup qml-features
-\title QML States
-\brief creating and setting states in QML
+\title States
+\brief Creating and setting states
\target qmlstates
\section1 States Elements
default states, the NumberAnimation animates the angle between
its old and new values.
- See \l {QML States} for details on state changes and the default
+ See \l {States} for details on state changes and the default
state, and \l {QML Animation and Transitions} for more information on how
animations work within transitions.
multiple animations within a Behavior, use ParallelAnimation or
SequentialAnimation.
- If a \l{QML States}{state change} has a \l Transition that matches the same property as a
+ If a \l{States}{state change} has a \l Transition that matches the same property as a
Behavior, the \l Transition animation overrides the Behavior for that
state change. For general advice on using Behaviors to animate state changes, see
\l{Using QML Behaviors with States}.
\ingroup qml-state-elements
\brief The PropertyChanges element describes new property bindings or values for a state.
- PropertyChanges is used to define the property values or bindings in a
+ PropertyChanges is used to define the property values or bindings in a
\l State. This enables an item's property values to be changed when it
- \l {QML States}{changes between states}.
+ \l {States}{changes between states}.
- To create a PropertyChanges object, specify the \l target item whose
+ To create a PropertyChanges object, specify the \l target item whose
properties are to be modified, and define the new property values or
bindings. For example:
-
- \snippet doc/src/snippets/qml/propertychanges.qml import
+
+ \snippet doc/src/snippets/qml/propertychanges.qml import
\codeline
\snippet doc/src/snippets/qml/propertychanges.qml 0
When the mouse is pressed, the \l Rectangle changes to the \e resized
- state. In this state, the PropertyChanges object sets the rectangle's
+ state. In this state, the PropertyChanges object sets the rectangle's
color to blue and the \c height value to that of \c container.height.
- Note this automatically binds \c rect.height to \c container.height
+ Note this automatically binds \c rect.height to \c container.height
in the \e resized state. If a property binding should not be
established, and the height should just be set to the value of
\c container.height at the time of the state change, set the \l explicit
property to \c true.
-
+
A PropertyChanges object can also override the default signal handler
for an object to implement a signal handler specific to the new state:
if (ownedExpression == rewindExpression)
ownedExpression = 0;
}
- virtual void saveCurrentValues() {
+ virtual void saveCurrentValues() {
rewindExpression = QQmlPropertyPrivate::signalExpression(property);
}
\qmlproperty bool QtQuick2::PropertyChanges::restoreEntryValues
This property holds whether the previous values should be restored when
- leaving the state.
+ leaving the state.
The default value is \c true. Setting this value to \c false creates a
temporary state that has permanent effects on property values.
projects / profile / ivi / qtdeclarative.git / commitdiff