diff options
Diffstat (limited to 'doc/src')
35 files changed, 1767 insertions, 821 deletions
diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc index e9f79d1..70381de 100644 --- a/doc/src/declarative/anchor-layout.qdoc +++ b/doc/src/declarative/anchor-layout.qdoc @@ -28,7 +28,14 @@ /*! \page qml-anchor-layout.html \target anchor-layout +<<<<<<< HEAD +\contentspage QML Features +\previouspage {Using QML Positioner and Repeater Items}{Component Layouts} +\nextpage {QML Mouse Events}{Mouse Events} +\title Anchor-based Layout in QML +======= \title Anchor-Based Layout in QML +>>>>>>> f44f7084a3020ed8e249644d5b5e07f74cb7b070 \section1 Overview @@ -36,7 +43,7 @@ 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": \l {Item::anchors.left}{left}, \l {Item::anchors.horizontalCenter}{horizontalCenter}, -\l {Item::anchors.right}{right}, \l {Item::anchors.top}{top}, +\l {Item::anchors.right}{right}, \l {Item::anchors.top}{top}, \l {Item::anchors.verticalCenter}{verticalCenter}, \l {Item::anchors.baseline}{baseline}, and \l {Item::anchors.bottom}{bottom}. diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 208a1c4..099f02d 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -27,7 +27,11 @@ /*! \page qdeclarativeanimation.html -\title QML Animation +\ingroup qml-features +\contentspage QML Features +\previouspage {QML States}{States} +\nextpage {QML Data Models}{Structuring Data with Models} +\title QML Animation and Transitions In QML, animations are created by applying animation objects to object property @@ -80,7 +84,7 @@ States}{state changes} These methods are demonstrated below. Notice these examples use PropertyAnimation, which is one of several QML elements that can be used to -create an animation. See the \l {Animation Elements} section further below for +create an animation. See the \l {Animation Elements} section further below for details. @@ -92,7 +96,7 @@ source} using the \e Animation \bold on \e Property syntax. Here is a \l Rectangle whose movement is animated using this method: \snippet doc/src/snippets/declarative/animation-propertyvaluesource.qml 0 - + This applies a PropertyAnimation to the \l Rectangle's \c x and \c y properties to animate from their current values (i.e. zero) to 50, over 1000 milliseconds. The animation starts as soon as the \l Rectangle is loaded. To animate from @@ -141,7 +145,7 @@ demonstration of behavioral animations. An animation can be created within a signal handler to be triggered when the signal is received. For example: - + \snippet doc/src/snippets/declarative/animation-signalhandler.qml 0 The PropertyAnimation is triggered when the MouseArea is clicked, animating the @@ -156,8 +160,8 @@ The \l {PropertyAnimation::}{to} property is also required to specify the new \section2 Standalone Animations Animations can also be created as ordinary QML objects that are not bound to -any particular objects and properties. Here is an example, using a -PropertyAnimation object. The animation is explicitly started when the +any particular objects and properties. Here is an example, using a +PropertyAnimation object. The animation is explicitly started when the \l Rectangle is clicked: \snippet doc/src/snippets/declarative/animation-standalone.qml 0 @@ -187,10 +191,10 @@ object and add it to an item's \l {Item::}{transitions} property. An example: The PropertyChanges object in the \e moved state defines that when the \l Rectangle is in this state, its position should be changed -to (50, 50). When the \l Rectangle changes to the \e moved state, the +to (50, 50). When the \l Rectangle changes to the \e moved state, the \l Transition will be triggered, and the transition's \l PropertyAnimation will animate the changes in the \c x and \c y properties to their new values. -The animation will not be applied at any time other than during the state +The animation will not be applied at any time other than during the state change. Notice the example does not set any \l {PropertyAnimation::}{from} and \l @@ -231,13 +235,13 @@ It can also define the number of \l {Animation::}{loops} for an animation. PropertyAnimation is the most basic animation element for animating a property. It can be used to animate \c real, \c int, \c color, \c rect, \c point, \c size, and \c vector3d properties. It is inherited by NumberAnimation, ColorAnimation, -RotationAnimation and Vector3dAnimation: NumberAnimation provides a more -efficient implementation for animating \c real and \c int properties, and -Vector3dAnimation does the same for \c vector3d properties. ColorAnimation -and RotationAnimation provide more specific attributes for animating color -and rotation changes. +RotationAnimation and Vector3dAnimation: NumberAnimation provides a more +efficient implementation for animating \c real and \c int properties, and +Vector3dAnimation does the same for \c vector3d properties. ColorAnimation +and RotationAnimation provide more specific attributes for animating color +and rotation changes. -A ColorAnimation allows color values for the \l {ColorAnimation::}{from} +A ColorAnimation allows color values for the \l {ColorAnimation::}{from} and \l {ColorAnimation::}{to} properties. The following animates the rectangle's \l {Rectangle::}{color} property: @@ -251,10 +255,10 @@ animates the rectangle's \l {Item::rotation} property: In addition, the following specialized animation elements are available: \list -\o SmoothedAnimation: a specialized NumberAnimation that provides smooth +\o SmoothedAnimation: a specialized NumberAnimation that provides smooth changes in animation when the target value changes -\o SpringAnimation: provides a spring-like animation with specialized -attributes such as \l {SpringAnimation::}{mass}, +\o SpringAnimation: provides a spring-like animation with specialized +attributes such as \l {SpringAnimation::}{mass}, \l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon} \o ParentAnimation: used for animating a parent change (see ParentChange) \o AnchorAnimation: used for animating an anchor change (see AnchorChanges) diff --git a/doc/src/declarative/basicelements.qdoc b/doc/src/declarative/basicelements.qdoc new file mode 100644 index 0000000..d0c16b6 --- /dev/null +++ b/doc/src/declarative/basicelements.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qmlbasicelements.html + \ingroup qml-features + \contentspage QML Features + \previouspage {QML Basic Types}{Data Types} + \nextpage {Using QML Positioner and Repeater Items}{Component Layouts} + + \title QML Basic Elements + +*/ diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 034b7d1..59772c5 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -27,13 +27,17 @@ /*! \page qdeclarativebasictypes.html + \ingroup qml-features + \contentspage QML Features + \previouspage {Property Binding} + \nextpage {QML Basic Elements}{Basic Elements} \title QML Basic Types QML has a set of primitive types, as listed below, that are used throughout the \l {QML Elements}. - Some of these types can also be used for defining - \c property values in QML. See \l{Writing QML Components: Properties, Methods and Signals} for the + Some of these types can also be used for defining + \c property values in QML. See \l{Importing Reusable Components} for the list of types that can be used for \c property values. \annotatedlist qmlbasictypes @@ -43,7 +47,7 @@ \qmlbasictype int \ingroup qmlbasictypes - \brief An integer is a whole number, e.g. 0, 10, or -20. + \brief An integer is a whole number, e.g. 0, 10, or -20. An integer is a whole number, e.g. 0, 10, or -20. The possible \c int values range from around -2000000000 to around 2000000000, @@ -117,7 +121,7 @@ \qmlbasictype url \ingroup qmlbasictypes - \brief A URL is a resource locator, like a file name. + \brief A URL is a resource locator, like a file name. A URL is a resource locator, like a file name. It can be either absolute, e.g. "http://qt.nokia.com", or relative, e.g. @@ -198,7 +202,7 @@ /*! \qmlbasictype size \ingroup qmlbasictypes - + \brief A size type has width and height attributes A \c size type has \c width and \c height attributes. @@ -237,7 +241,7 @@ For example, to read the \l {Item::childrenRect.x}{Item::childrenRect} \c rect property: \qml - Rectangle { + Rectangle { width: childrenRect.width height: childrenRect.height @@ -273,7 +277,7 @@ MyDatePicker { minDate: "2000-01-01"; maxDate: "2020-12-31" } \endqml - To read a date value returned from a C++ extension class, use + To read a date value returned from a C++ extension class, use \l{QML:Qt::formatDate()}{Qt.formatDate()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. \sa {QML Basic Types} @@ -292,7 +296,7 @@ MyTimePicker { time: "14:22:15" } \endqml - To read a time value returned from a C++ extension class, use + To read a time value returned from a C++ extension class, use \l{QML:Qt::formatTime()}{Qt.formatTime()} and \l{QML:Qt::formatDateTime()}{Qt.formatDateTime()}. \sa {QML Basic Types} @@ -493,7 +497,7 @@ \qml Text { horizontalAlignment: "AlignRight" } \endqml - + or as \c {<Element>.<value>}: \qml Text { horizontalAlignment: Text.AlignRight } diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index e10c5c8..473cbdd 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -31,12 +31,12 @@ \ingroup qt-gui-concepts \brief Qt Quick provides a declarative framework for building highly -dynamic, custom user interfaces. +dynamic user interfaces. \section1 Introduction Qt Quick is a collection of technologies that are designed to help -developers create the kind of intuitive, modern-looking, fluid user +developers create the kind of intuitive, modern, fluid user interfaces that are increasingly used on mobile phones, media players, set-top boxes and other portable devices. @@ -45,7 +45,7 @@ language for describing user interfaces and a language runtime. A collection of C++ APIs is used to integrate these high level features with classic Qt applications. -\section2 QML, Elements and the Qt Declarative Module +\section2 QML User interfaces and their behavior are described using QML, an extension to \l{About JavaScript}{JavaScript} that lets developers and designers @@ -55,104 +55,113 @@ graphical and behavioral building blocks that can be combined together in \l{QML Documents}{QML documents} to build components ranging in complexity from simple buttons and sliders, to complete Internet-enabled applications. -QML improves the integration between JavaScript 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. +\section2 Qt Declarative Module -The Qt Declarative module implements the interface between the QML language -and the elements available to it. It also provides a C++ API that can be -used to load and interact with QML files from within Qt applications. +The Qt Declarative module provides a C++ API that is for interacting with QML files from within Qt applications. The module allows the programmer to build applications' backend logic using Qt. -Qt Quick 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 completely new applications. QML is fully -\l{Extending QML in C++}{extensible from C++} through the Qt Declarative -Module. +QML and the Qt Declarative Module separate the frontend UI logic from the backend logic. \section1 Getting Started \list -\o \l{What's new in Qt Quick} -\o \l{Introduction to the QML language} -\o \l{QML for Qt Programmers} +\o \l{Intro to Qt Quick}{Introduction to Qt Quick} +\o \l{QML for Qt Programmers}{QML Programming for Qt Programmers} \o \l{Getting Started Programming with QML} -\o \l{Intro to Qt Quick} -\endlist -\list -\o \l{QML Tutorial}{Tutorial: "Hello World"} -\o \l{QML Advanced Tutorial}{Tutorial: "Same Game"} +\o \l{What's new in Qt Quick}{What's New in the Qt Quick Release} \o \l{QML Examples and Demos} \endlist -\section1 QML Concepts +\section1 QML Features \list -\o \l{QML Documents} +\o \l{QML Syntax} \o \l{Property Binding} -\o \l{Anchor-Based Layout in QML} -\o \l{Writing QML Components: Properties, Methods and Signals} -\o \l{QML Scope} -\o \l{QML Modules} +\o \l{QML Basic Types}{Data Types} +\o \l{QML Basic Elements}{Basic Elements} +\o \l{Using QML Positioner and Repeater Items}{Component Layouts} +\o \l{Anchor-based Layout in QML}{Layouts using Anchors} +\o \l{Mouse Events} +\o \l{QML Text Handling and Validators}{Text Handling and Validators} +\o \l{Keyboard Focus in QML}{Keyboard Focus} +\o \l{Importing Reusable Components} +\o \l{QML States}{States} +\o \l{QML Animation and Transitions}{Animation and Transitions} +\o \l{QML Data Models}{Structuring Data with Models} +\o \l{Presenting Data with Views} +\o \l{Extending QML Functionalities using C++} +\o \l{Using QML Bindings in C++ Applications} +\o \l{Integrating QML Code with Existing Qt UI Code} +\o \l{QML Signal and Handler Event System}{Signal and Handler Event System} +\o \l{Dynamic Object Management in QML}{Dynamic Object Management} +\o \l{Network Transparency}{Loading Resources in QML} +\o \l{QML Internationalization}{Internationalization} +\o \l{QML Graphical Effects}{Graphical Effects} \endlist -\section1 User Interaction +\section1 QML Add-Ons \list -\o \l{Keyboard Focus in QML} -\o \l{QML States} -\o \l{QML Animation} +\o \l{QtWebKit QML Module} +\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} \endlist -\section1 Handling Data +\section1 Qt Quick Tools \list -\o \l{QML Basic Types}{QML Basic Data Types} -\o \l{Using QML Positioner and Repeater Items} -\o \l{QML Data Models} -\o \l{Presenting Data with QML} -\o \l{Network Transparency} +\o \l{Debugging QML} +\o \l{Developing Qt Quick Applications with Creator}{Developing with Qt Creator} +\o \l{QML Viewer} \endlist -\section1 Architecture +\section1 Reference \list -\o \l{Qt Declarative UI Runtime} -\o \l{Integrating JavaScript} -\o \l{Dynamic Object Management in QML} +\o \l{Introduction to the QML language}{QML Syntax} +\o \l{QML Elements} +\o \l{Qt Declarative Module} +\o \l{QML Basic Types}{QML Data Types} +\o \l{QML Coding Conventions} +\o \l{Qt Creator Manual} +\o \l{Programming with Qt} +\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility Documentation} \endlist -\section1 Using QML with C++ +\section1 Architecture \list \o \l{Qt Declarative UI Runtime} -\o \l{Using QML in C++ Applications} -\o \l{Integrating QML with existing Qt UI code} -\o \l{Tutorial: Writing QML extensions with C++} -\o \l{Extending QML in C++} -\endlist - -\section1 Reference - -\list -\o \l{QML Elements} -\o \l{QML Basic Types} +\o \l{Integrating JavaScript} +\o \l{QML Scope} +\o \l{QML Modules} +\o \l{QML Documents} \o \l{QML Global Object} -\o \l{QML Internationalization} \o \l{QML Security} \o \l{Qt Declarative Module} -\o \l{Debugging QML} -\o \l{QML Viewer} -\o \l{QML Performance} -\o \l{QML Coding Conventions} \endlist -\section1 Online Examples +\section1 Examples \list +\o \l{QML Tutorial}{"Hello World" Tutorial} +\o \l{Getting Started Programming with QML} +\o \l{QML Advanced Tutorial}{Tutorial: "Same Game"} +\o \l{Tutorial: Writing QML extensions with C++} +\o \l{QML Examples and Demos} + \o Forum Nokia: \l{http://wiki.forum.nokia.com/index.php/Qt_Quick_examples_for_porting}{Qt Quick examples for porting} \endlist + +\section1 Best Practices + +\list +\o \l{QML Best Practices: Data Types}{Using Data Types in QML} +\o \l{QML Best Practices: Coding Conventions}{Coding Tips} +\o \l{QML Performance}{Performance Tips} +\omit +\o \l{Geir's screen size document} +\endomit +\endlist */ diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index fcc9fd4..e5077ba 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -27,13 +27,17 @@ /*! \page qdeclarativedynamicobjects.html +\ingroup qml-features +\contentspage {QML Features} +\previouspage {QML Signal and Handler Event System}{Signal and Handler Event System} +\nextpage {Network Transparency}{Loading Resources in QML} \title Dynamic Object Management in QML -QML provides a number of ways to dynamically create and manage QML objects. +QML provides a number of ways to dynamically create and manage QML objects. The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements -all support dynamic object management. Objects can also be created and managed +all support dynamic object management. Objects can also be created and managed from C++, and this is the preferred method for hybrid QML/C++ applications -(see \l{Using QML in C++ Applications}). +(see \l{Using QML Bindings in C++ Applications}). QML also supports the dynamic creation of objects from within JavaScript code. This is useful if the existing QML elements do not fit the needs of your @@ -45,20 +49,20 @@ of the concepts discussed on this page. \section1 Creating Objects Dynamically -There are two ways to create objects dynamically from JavaScript. You can either call +There are two ways to create objects dynamically from JavaScript. You can either call \l {QML:Qt::createComponent()}{Qt.createComponent()} to dynamically create a \l Component object, or use \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} to create an item from a string of QML. -Creating a component is better if you have an existing component defined in a \c .qml +Creating a component is better if you have an existing component defined in a \c .qml file, and you want to dynamically create instances of that component. Otherwise, -creating an item from a string of QML is useful when the item QML itself is generated +creating an item from a string of QML is useful when the item QML itself is generated at runtime. \section2 Creating a Component dynamically -To dynamically load a component defined in a QML file, call the -\l {QML:Qt::createComponent()}{Qt.createComponent()} function on the \l{QML Global Object}. +To dynamically load a component defined in a QML file, call the +\l {QML:Qt::createComponent()}{Qt.createComponent()} function on the \l{QML Global Object}. This function takes the URL of the QML file as its only argument and creates a \l Component object from this URL. @@ -88,14 +92,14 @@ in case the QML file is loaded over a network and thus is not ready immediately. \codeline \snippet doc/src/snippets/declarative/componentCreation.js finishCreation -If you are certain the QML file to be loaded is a local file, you could omit the \c finishCreation() +If you are certain the QML file to be loaded is a local file, you could omit the \c finishCreation() function and call \l {Component::createObject()}{createObject()} immediately: \snippet doc/src/snippets/declarative/componentCreation.js func \snippet doc/src/snippets/declarative/componentCreation.js local \snippet doc/src/snippets/declarative/componentCreation.js func-end -Notice in both instances, \l {Component::createObject()}{createObject()} is called with +Notice in both instances, \l {Component::createObject()}{createObject()} is called with \c appWindow passed as an argument so that the created object will become a child of the \c appWindow item in \c main.qml. Otherwise, the new item will not appear in the scene. @@ -156,7 +160,7 @@ items that you did not dynamically create yourself. Items can be deleted using the \c destroy() method. This method has an optional argument (which defaults to 0) that specifies the approximate delay in milliseconds -before the object is to be destroyed. +before the object is to be destroyed. Here is an example. The \c application.qml creates five instances of the \c SelfDestroyingRect.qml component. Each instance runs a NumberAnimation, and when the animation has finished, calls @@ -188,7 +192,7 @@ Item { } \endqml -This would result in an error, since items can only be dynamically +This would result in an error, since items can only be dynamically destroyed if they were dynamically created. Objects created with \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc index c998c5c..25be0f9 100644 --- a/doc/src/declarative/extending-tutorial.qdoc +++ b/doc/src/declarative/extending-tutorial.qdoc @@ -33,7 +33,7 @@ The Qt Declarative 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 +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. @@ -67,18 +67,18 @@ like network programming that are not accessible through built-in QML features. In this tutorial, we will show how to use the C++ classes in the Qt Declarative module to extend QML. The end result will be a simple Pie Chart display implemented by -several custom QML types connected together through QML features like bindings and +several custom QML types connected together through QML features like bindings and signals, and made available to the QML runtime through a plugin. To begin with, let's create a new QML type called "PieChart" that has two properties: a name and a color. We will make it available in a \l {Modules}{module} called "Charts", with -a module version of 1.0. +a module version of 1.0. We want this \c PieChart type to be usable from QML like this: \code import Charts 1.0 - + PieChart { width: 100; height: 100 name: "A simple pie chart" @@ -99,16 +99,16 @@ Here is our \c PieChart class, defined in \c piechart.h: \snippet declarative/tutorials/extending/chapter1-basics/piechart.h 0 -The class inherits from QDeclarativeItem because we want to override +The class inherits from QDeclarativeItem because we want to override QDeclarativeItem::paint() in order to draw. If the class just represented some data type and was not an item that actually needed to be displayed, it could simply inherit -from QObject. Or, if we want to extend the functionality of an existing QObject-based +from QObject. Or, if we want to extend the functionality of an existing QObject-based class, it could inherit from that class instead. The \c PieChart class defines the two properties, \c name and \c color, with the Q_PROPERTY macro, -and overrides QDeclarativeItem::paint(). The class implementation in \c piechart.cpp -simply sets and returns the \c m_name and \c m_color values as appropriate, and -implements \c paint() to draw a simple pie chart. It also turns off the +and overrides QDeclarativeItem::paint(). The class implementation in \c piechart.cpp +simply sets and returns the \c m_name and \c m_color values as appropriate, and +implements \c paint() to draw a simple pie chart. It also turns off the QGraphicsItem::ItemHasNoContents flag to enable painting: \snippet declarative/tutorials/extending/chapter1-basics/piechart.cpp 0 @@ -150,19 +150,19 @@ Try it yourself with the code in Qt's \c examples/tutorials/extending/chapter1-b 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 \l {QML Viewer}. -Later on, we'll show how to create a plugin so that you can run \c app.qml using the +Later on, we'll show how to create a plugin so that you can run \c app.qml using the \l {QML Viewer} instead. */ /*! -\title Chapter 2: Connecting to C++ Methods and Signals +\title Chapter 2: Connecting to C++ Methods and Signals \example declarative/tutorials/extending/chapter2-methods Suppose we want \c PieChart to have a "clearChart()" method that erases the -chart and then emits a "chartCleared" signal. Our \c app.qml would be able +chart and then emits a "chartCleared" signal. Our \c app.qml would be able to call \c clearChart() and receive \c chartCleared() signals like this: \snippet declarative/tutorials/extending/chapter2-methods/app.qml 0 @@ -210,7 +210,7 @@ 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 are changed. -Let's enable property bindings for the \c color property. That means +Let's enable property bindings for the \c color property. That means if we have code like this: \snippet declarative/tutorials/extending/chapter3-bindings/app.qml 0 @@ -224,7 +224,7 @@ updates to the same value. When the window is clicked, the \c onClicked handler in the MouseArea changes the color of \c chartA, thereby changing both charts to the color blue. -It's easy to enable property binding for the \c color property. +It's easy to enable property binding for the \c color property. We add a \l{Qt's Property System}{NOTIFY} feature to its Q_PROPERTY() declaration to indicate that a "colorChanged" signal is emitted whenever the value changes. @@ -244,7 +244,7 @@ It's important for \c setColor() to check that the color value has actually chan before emitting \c colorChanged(). This ensures the signal is not emitted unnecessarily and also prevents loops when other elements respond to the value change. -The use of bindings is essential to QML. You should always add NOTIFY +The use of bindings is essential to QML. You should always add NOTIFY signals for properties if they are able to be implemented, so that your properties can be used in bindings. Properties that cannot be bound cannot be automatically updated and cannot be used as flexibly in QML. Also, since @@ -299,7 +299,7 @@ listed in the \l{Adding Properties} documentation, which includes the following: 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 replace the use of the \c property with a type called +For example, let's replace the use of the \c property with a type called "PieSlice" that has a \c color property. Instead of assigning a color, we assign an \c PieSlice value which itself contains a \c color: @@ -358,10 +358,10 @@ have a \c slices property that accepts a list of \c PieSlice items: \image extending-tutorial-chapter5.png To do this, we replace the \c pieSlice property in \c PieChart with a \c slices property, -declared as a QDeclarativeListProperty type. The QDeclarativeListProperty class enables the +declared as a QDeclarativeListProperty type. The QDeclarativeListProperty class enables the creation of list properties in QML extensions. We replace the \c pieSlice() -function with a \c slices() function that returns a list of slices, and add -an internal \c append_slice() function (discussed below). We also use a QList to +function with a \c slices() function that returns a list of slices, and add +an internal \c append_slice() function (discussed below). We also use a QList to store the internal list of slices as \c m_slices: \snippet declarative/tutorials/extending/chapter5-listproperties/piechart.h 0 @@ -409,7 +409,7 @@ 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 project file that describes the plugin \o A \l{Writing a qmldir file}{qmldir} file that tells the QML engine to load the plugin \endlist @@ -468,8 +468,9 @@ In this tutorial, we've shown the basic steps for creating a QML extension: \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{Default Property}{default properties} to allow +The \l {Extending QML Functionalities using C++} reference documentation shows +other useful features that can be added to QML extensions. For example, we +could use \l{Default Property}{default properties} to allow slices to be added without using the \c slices property: \code @@ -489,7 +490,8 @@ Or randomly add and remove slices from time to time using \l{Property Value Sour \endcode -See the \l{Extending QML in C++}{reference documentation} for more information. +See the \l{Extending QML Functionalities using C++} reference documentation +for more information. */ diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index c34dc13..491f9c4 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -27,7 +27,11 @@ /*! \page qml-extending.html -\title Extending QML in C++ +\ingroup qml-features +\contentspage QML Features +\previouspage {Presenting Data with Views} +\nextpage {Using QML Bindings in C++ Applications} +\title Extending QML Functionalities using C++ 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 @@ -360,28 +364,28 @@ pointers to invalid objects. QML makes the following guarentees: \list \o An object assigned to a QObject (or QObject-derived) pointer property will be -valid at the time of assignment. +valid at the time of assignment. -Following assignment, it is the responsibility of the class to subsequently guard +Following assignment, it is the responsibility of the class to subsequently guard this pointer, either through a class specific method or the generic QPointer class. -\o An object assigned to a QVariant will be valid at the time of assignment. +\o An object assigned to a QVariant will be valid at the time of assignment. -When assigning an object to a QVariant property, QML will always use a QMetaType::QObjectStar -typed QVariant. It is the responsibility of the class to guard the pointer. A -general rule when writing a class that uses QVariant properties is to check the -type of the QVariant when it is set and if the type is not handled by your class, +When assigning an object to a QVariant property, QML will always use a QMetaType::QObjectStar +typed QVariant. It is the responsibility of the class to guard the pointer. A +general rule when writing a class that uses QVariant properties is to check the +type of the QVariant when it is set and if the type is not handled by your class, reset it to an invalid variant. -\o An object assigned to a QObject (or QObject-derived) list property will be -valid at the time of assignment. +\o An object assigned to a QObject (or QObject-derived) list property will be +valid at the time of assignment. -Following assignment, it is the responsibility of the class to subsequently guard +Following assignment, it is the responsibility of the class to subsequently guard this pointer, either through a class specific method or the generic QPointer class. \endlist Elements should assume that any QML assigned object can be deleted at any time, and -respond accordingly. If documented as such an element need not continue to work in +respond accordingly. If documented as such an element need not continue to work in this situation, but it must not crash. \section1 Signal Support @@ -429,7 +433,7 @@ on<Property-name>Changed, regardless of the name used for the NOTIFY signal in C++. We recommend using <property-name>Changed() for the NOTIFY signal in C++. -See also \l {Writing QML Components: Properties, Methods and Signals} +See also \l {Importing Reusable Components} \section1 Methods @@ -635,468 +639,4 @@ public: */ -/*! -\page qml-extending-types.html -\title Writing QML Components: Properties, Methods and Signals - -One of the key concepts in QML is the ability to define your own QML components that suit -the purposes of your application. The standard \l {QML Elements} provide the essential components -for creating a QML application; beyond these, you can write your own custom components that can -be created and reused, without the use of C++. - -Components are the building blocks of a QML project. When writing a QML application, whether -large or small, it is best to separate QML code into smaller components that perform specific -sets of operations, instead of creating mammoth QML files with large, combined functionality -that is more difficult to manage and may contain duplicated code. - - -\section1 Defining New Components - -A component is a reusable type with a well-defined interface, built entirely in QML. -Any snippet of QML code can become a component, by placing the code in a file "<Name>.qml" where -<Name> is the new component name, beginning with an uppercase letter. These QML files automatically -become available as new QML element types to other QML components and applications in the same directory. - -For example, one of the simplest and most common components you can build in QML is a -button-type component. Below, we implement this component as a \l Rectangle with a clickable -\l MouseArea, in a file named \c Button.qml: - -\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0 - -Now this component can be reused by another file within the same directory. Since the file is -named \c Button.qml, the component is referred to as \c Button: - -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0 -\o \image qml-extending-types.png -\endtable - -The root object in \c Button.qml defines the attributes that are available to users of the -\c Button component. In this case, the root object is a \l Rectangle, so any properties, methods -and signals of \l Rectangle are made available, allowing \c application.qml to -customize the \c width, \c height, \c radius and \c color properties of \c Button objects. - - -If \c Button.qml was not in the same directory, \c application.qml would need to load it as a -\l {Modules}{module} from a specific filesystem path or \l{QDeclarativeExtensionPlugin}{plugin}. -Also, note the letter case of the component file name is significant on some (notably UNIX) -filesystems. It is recommended the file name case matches the case of the QML component name -exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the -QML component will be deployed. - -To write a useful component, it is generally necessary to provide it with custom attributes that store and -communicate specific data. This is achieved by adding the following attributes to your components: - -\list -\o \bold Properties that can be accessed externally to modify an object (for example, \l Item has - \l {Item::}{width} and \l {Item::}{height} properties) and used in \l {Property Binding} -\o \bold Methods of JavaScript code can be invoked internally or externally (for example, - \l Animation has a \l {Animation::}{start()} method) -\o \bold Signals to notify other objects when an event has occurred (for example, MouseArea has a - \c clicked signal) -\endlist - -The following sections show how these attributes can be added to QML components. - - -\section1 Adding Properties - -A property is a value of a QML component that can be read and modified by other objects. For -example, a \l Rectangle component has \l {Item::}{width}, \l {Item::}{height} and \l -{Rectangle::}{color} properties. Significantly, properties be used with \l {Property Binding}, where -a property value is automatically updated using the value of another property. - -The syntax for defining a new property is: - -\code -[default] property <type> <name>[: defaultValue] -\endcode - -A \c property declaration can appear anywhere within a QML component definition, but it is customary -to place it at the top. A component cannot declare more than one property with the same name. (It is -possible to have a property name that is the same as an existing property in a type, but this is not -recommended as the existing property becomes hidden and inaccessible.) - -Below is an example. The \c ImageViewer component has defined a \c string type property named -\c currentImage, and its initial value is "default-image.png". This property is used to set the image -displayed in the child \l Image object. Another file, \c application.qml, can create -an \c ImageViewer object and read or modify the \c currentImage value: - -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/ImageViewer.qml 0 -\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/application.qml 0 -\endtable - -It is optional for a property to have a default value. The default value is a convenient shortcut, and is -behaviorally identical to doing it in two steps, like this: - -\qml -// Use default value -property int myProperty: 10 - -// Longer, but behaviorally identical -property int myProperty -myProperty: 10 -\endqml - - -\section2 Supported property types - -All QML properties are typed. The examples above show properties with \c int and \c string types; -notice that the type of the property must be declared. The type is used to determine the property -behavior, and how the property is defined in C++. - -A number of property types are supported by default. These are listed in the table below, -with their default values and the corresponding C++ type: - -\table -\header \o QML Type Name \o Default value \o C++ Type Name -\row \o int \o 0 \o int -\row \o bool \o \c false \o bool -\row \o double \o 0.0 \o double -\row \o real \o 0.0 \o double -\row \o string \o "" (empty string) \o QString -\row \o url \o "" (empty url) \o QUrl -\row \o color \o #000000 (black) \o QColor -\row \o date \o \c undefined \o QDateTime -\row \o variant \o \c undefined \o QVariant -\endtable - -QML object types can also be used as property types. This includes -\l {Defining new QML elements}{custom QML types} implemented in C++. Such properties are -defined like this: - -\qml -property Item itemProperty -property QtObject objectProperty -property MyCustomType customProperty -\endqml - -Such object-type properties default to an \c undefined value. - -\l{list}{List properties} are created with the \c list<Type> syntax, and default to an empty -list: - -\qml -property list<Item> listOfItems -\endqml - -Note that list properties cannot be modified like ordinary JavaScript -arrays. See the \l {list}{list type documentation} for details. - -For details about accessing and manipulating QML properties from C++, see \l {Using QML with C++}. - - -\section2 Property change signals - -Adding a \c property to an item automatically adds a \e {value changed} -signal handler to the item. To connect to this signal, use a \l {Signal Handlers}{signal handler} -named with the \c on<Property>Changed syntax, using upper case for the first letter of the -property name. - -For example, the following \c onMyNumberChanged signal handler is automatically called whenever the -\c myNumber property changes: - -\snippet doc/src/snippets/declarative/qml-extending-types/properties/property-signals.qml 0 - - -\section2 Default properties - -The optional \c default attribute for a property marks it as the \e {default property} -for a type. This allows other items to specify the default property's value -as child elements. For example, the \l Item element's default property is its -\l{Item::children}{children} property. This allows the children of an \l Item -to be set like this: - -\qml -Item { - Rectangle {} - Rectangle {} -} -\endqml - -If the \l{Item::children}{children} property was not the default property for -\l Item, its value would have to be set like this instead: - -\qml -Item { - children: [ - Rectangle {}, - Rectangle {} - ] -} -\endqml - -See the \l{declarative/ui-components/tabwidget}{TabWidget} example for a -demonstration of using default properties. - -Specifying a default property overrides any existing default property (for -example, any default property inherited from a parent item). Using the -\c default attribute twice in the same type block is an error. - - -\section2 Property aliases - -Property aliases are a more advanced form of property declaration. Unlike a -property definition, which allocates a new, unique storage space for the -property, a property alias connects the newly declared property (called the -aliasing property) as a direct reference to an existing property (the aliased property). Read -operations on the aliasing property act as read operations on the aliased -property, and write operations on the aliasing property as write operations on -the aliased property. - -A property alias declaration looks a lot like an ordinary property definition: -\code - [default] property alias <name>: <alias reference> -\endcode - -As the aliasing property has the same type as the aliased property, an explicit -type is omitted, and the special "alias" keyword is used. Instead of a default -value, a property alias includes a compulsory alias reference. The alias -reference is used to locate the aliased property. While similar to a property -binding, the alias reference syntax is highly restricted. - -An alias reference takes one of the following forms: -\code - <id>.<property> - <id> -\endcode - -where <id> must refer to an object id within the same component as the type -declaring the alias, and, optionally, <property> refers to a property on that object. - -For example, below is a \c Button.qml component with a \c buttonText aliased property which is -connected to the child Text object's \c text property: - -\snippet doc/src/snippets/declarative/qml-extending-types/properties/alias.qml 0 - -The following code would create a \c Button with a defined text string for the -child \l Text object: - -\qml -Button { buttonText: "This is a button" } -\endqml - -Here, modifying \c buttonText directly modifies the \c textItem.text value; it does not -change some other value that then updates \c textItem.text. - -In this case, the use of aliased properties is essential. If \c buttonText was not an alias, -changing its value would not actually change the displayed text at all, as -\l {Property Binding}{property bindings} are not bi-directional: the \c buttonText value would -change when \c textItem.text changes, but not the other way around. -Aliased properties are also useful for allowing external objects to directly modify and -access child objects in a component. For example, here is a modified version of the \c ImageViewer -component shown \l {Adding Properties}{earlier} on this page. The \c currentImage property has -been changed to an alias to the child \l Image object: - -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/ImageViewer.qml 0 -\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/application.qml 0 -\endtable - -Instead of being limited to setting the \l Image source, \c application.qml can now directly -access and modify the child \l Image object and its properties. - -Obviously, exposing child objects in this manner should be done with care, as it allows external -objects to modify them freely. However, this use of aliased properties can be quite useful in -particular situations, such as for the \l {declarative/ui-components/tabwidget}{TabWidget} -example, where new tab items are actually parented to a child object that displays the current tab. - - -\section3 Considerations for property aliases - -Aliases are only activated once the component specifying them is completed. The -most obvious consequence of this is that the component itself cannot generally -use the aliased property directly during creation. For example, this will not work: - -\code - // Does NOT work - property alias buttonText: textItem.text - buttonText: "Some text" // buttonText is not yet defined when this value is set -\endcode - -A second, much less significant, consequence of the delayed activation of -aliases is that an alias reference cannot refer to another aliasing property -declared within the same component. This will not work: - -\code - // Does NOT work - id: root - property alias buttonText: textItem.text - property alias buttonText2: root.buttonText -\endcode - -At the time the component is created, the \c buttonText value has not yet been assigned, -so \c root.buttonText would refer to an undefined value. (From outside the component, -however, aliasing properties appear as regular Qt properties and consequently can be -used in alias references.) - -It is possible for an aliased property to have the same name as an existing property. For example, -the following component has a \c color alias property, named the same as the built-in -\l {Rectangle::color} property: - -\snippet doc/src/snippets/declarative/qml-extending-types/properties/alias-override.qml 0 - -Any objects that use this component and refer to its \c color property will be -referring to the alias rather than the ordinary \l {Rectangle::color} property. Internally, -however, the rectangle can correctly set this property to "red" and refer to the actual defined -property rather than the alias. - - -\section1 Adding Methods - -A QML component can define methods of JavaScript code. These methods can be invoked -either internally or by other objects. - -The syntax for defining a method is: - -\code -function <name>([<parameter name>[, ...]]) { <body> } -\endcode - -This declaration may appear anywhere within a type body, but it is customary to -include it at the top. Attempting to declare two methods or signals with the -same name in the same type block is an error. However, a new method may reuse -the name of an existing method on the type. (This should be done with caution, -as the existing method may be hidden and become inaccessible.) - -Unlike \l{Adding Signals}{signals}, method parameter types do not have to be declared as they -default to the \c variant type. The body of the method is written in JavaScript and may access -the parameters by name. - -Here is an example of a component with a \c say() method that accepts a single \c text argument: - -\snippet doc/src/snippets/declarative/qml-extending-types/methods/app.qml 0 - -A method can be connected to a signal so that it is automatically invoked whenever the signal -is emitted. See \l {Connecting signals to methods and other signals} below. - -Also see \l {Integrating JavaScript} for more information on using JavaScript with QML. - - -\section1 Adding Signals - -Signals provide a way to notify other objects when an event has occurred. For example, the MouseArea -\c clicked signal notifies other objects that the mouse has been clicked within the area. - -The syntax for defining a new signal is: - -\code -signal <name>[([<type> <parameter name>[, ...]])] -\endcode - -This declaration may appear anywhere within a type body, but it is customary to -include it at the top. Attempting to declare two signals or methods with the -same name in the same type block is an error. However, a new signal may reuse -the name of an existing signal on the type. (This should be done with caution, -as the existing signal may be hidden and become inaccessible.) - -Here are three examples of signal declarations: - -\code -Item { - signal clicked - signal hovered() - signal performAction(string action, variant actionArgument) -} -\endcode - -If the signal has no parameters, the "()" brackets are optional. If parameters are used, the -parameter types must be declared, as for the \c string and \c variant arguments for the \c -performAction signal above; the allowed parameter types are the same as those listed in the \l -{Adding Properties} section on this page. - -Adding a signal to an item automatically adds a \l {Signal Handlers}{signal handler} as well. -The signal hander is named \c on<SignalName>, with the first letter of the signal being upper -cased. The above example item would now have the following signal handlers: - -\list -\o onClicked -\o onHovered -\o onPerformAction -\endlist - -To emit a signal, simply invoke it in the same way as a method. Below left, when the \l MouseArea is -clicked, it emits the parent \c buttonClicked signal by invoking \c rect.buttonClicked(). The -signal is received by \c application.qml through an \c onButtonClicked signal handler: - -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/basic.qml 0 -\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/no-parameters.qml 0 -\endtable - -If the signal has parameters, they are accessible by parameter name in the signal handler. -In the example below, \c buttonClicked is emitted with \c xPos and \c yPos parameters instead: - -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/Button.qml 0 -\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/parameters.qml 0 -\endtable - - -\section2 Connecting signals to methods and other signals - -Signal objects have a \c connect() method that can be used to a connect a signal to a method or -another signal. When a signal is connected to a method, the method is automatically invoked -whenever the signal is emitted. (In Qt terminology, the method is a \e slot that is connected -to the \e signal; all methods defined in QML are created as Qt slots.) This enables a signal -to be received by a method instead of a \l {Signal Handlers}{signal handler}. - -For example, the \c application.qml above could be rewritten as: - -\snippet doc/src/snippets/declarative/qml-extending-types/signals/connectslots.qml 0 - -The \c myMethod() method will be called whenever the \c buttonClicked signal is received. - -In many cases it is sufficient to receive signals through signal handlers rather than using -the \c connect() function; the above example does not provide any improvements over using a -simple \c onButtonClicked handler. However, if you are \l{Dynamic Object Management in QML}{creating objects dynamically}, -or \l {Integrating JavaScript}{integrating JavaScript code}, then you will find the -\c connect() method useful. For example, the component below creates three \c Button -objects dynamically, and connects the \c buttonClicked signal of each object to the -\c myMethod() function: - -\snippet doc/src/snippets/declarative/qml-extending-types/signals/connectdynamic.qml 0 - -In the same way, you could connect a signal to methods defined in a dynamically -created object, or \l {Receiving QML Signals in JavaScript}{connect a signal to a JavaScript method}. - -There is also a corresponding \c disconnect() method for removing connected signals. The following -code removes the connection created in \c application.qml above: - -\qml -// application.qml -Item { - ... - - function removeSignal() { - button.clicked.disconnect(item.myMethod) - } -} -\endqml - - -\section3 Forwarding signals - -The \c connect() method can also connect a signal to other signals. This has the effect -of "forwarding" a signal: it is automatically emitted whenever the relevant signal is emitted. For -example, the MouseArea \c onClicked handler in \c Button.qml above could have been replaced with -a call to \c connect(): - -\qml -MouseArea { - anchors.fill: parent - Component.onCompleted: clicked.connect(item.buttonClicked) -} -\endqml - -Whenever the \l MouseArea \c clicked signal is emitted, the \c rect.buttonClicked signal will -automatically be emitted as well. - -*/ diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc index ae72c3c..be1000e 100644 --- a/doc/src/declarative/focus.qdoc +++ b/doc/src/declarative/focus.qdoc @@ -28,11 +28,16 @@ /*! \target qmlfocus \page qdeclarativefocus.html +\ingroup qml-features +\contentspage QML Features +\previouspage {QML Text Handling and Validators}{Text Handling and Validators} +\nextpage {Importing Reusable Components} + \title Keyboard Focus in QML When a key is pressed or released, a key event is generated and delivered to the focused QML \l Item. To facilitate the construction of reusable components -and to address some of the cases unique to fluid user interfaces, the QML items add a +and to address some of the cases unique to fluid user interfaces, the QML items add aged \e scope based extension to Qt's traditional keyboard focus model. \tableofcontents diff --git a/doc/src/declarative/graphicaleffects.qdoc b/doc/src/declarative/graphicaleffects.qdoc new file mode 100644 index 0000000..b5ef601 --- /dev/null +++ b/doc/src/declarative/graphicaleffects.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmlgraphicaleffects.html +\ingroup qml-features +\contentspage QML Features +\previouspage {QML Internationalization}{Internationalization} +\nextpage {QML Features} +\title QML Graphical Effects + +*/ diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/declarative/integrating.qdoc index 7028585..caba2cd 100644 --- a/doc/src/declarative/integrating.qdoc +++ b/doc/src/declarative/integrating.qdoc @@ -27,7 +27,11 @@ /*! \page qml-integration.html -\title Integrating QML with existing Qt UI code +\ingroup qml-features +\previouspage {Using QML Bindings in C++ Applications} +\nextpage {QML Signal and Handler Event System} +\contentspage QML Features +\title Integrating QML Code with Existing Qt UI Code There are a number of ways to integrate QML into QWidget-based UI applications, depending on the characteristics of your existing UI code. @@ -37,8 +41,8 @@ depending on the characteristics of your existing UI code. If you have an existing QWidget-based UI, QML widgets can be integrated into it using QDeclarativeView. QDeclarativeView is a subclass of QWidget so you -can add it to your user interface like any other QWidget. Use -QDeclarativeView::setSource() to load a QML file into the view, then add the +can add it to your user interface like any other QWidget. Use +QDeclarativeView::setSource() to load a QML file into the view, then add the view to your UI: \code @@ -52,7 +56,7 @@ layout->addWidget(qmlView); The one drawback to this approach is that QDeclarativeView is slower to initialize and uses more memory than a QWidget, and creating large numbers of QDeclarativeView -objects may lead to performance degradation. If this is the case, it may be +objects may lead to performance degradation. If this is the case, it may be better to rewrite your widgets in QML, and load the widgets from a main QML widget instead of using QDeclarativeView. @@ -70,7 +74,7 @@ of simple and dynamic elements. If you have an existing UI based on the \l{Graphics View Framework}, you can integrate QML widgets directly into your QGraphicsScene. Use QDeclarativeComponent to create a QGraphicsObject from a QML file, and -place the graphics object into your scene using \l{QGraphicsScene::addItem()}, or +place the graphics object into your scene using \l{QGraphicsScene::addItem()}, or reparent it to an item already in the \l{QGraphicsScene}. For example: @@ -95,12 +99,13 @@ of QML UIs: \section2 Loading QGraphicsWidget objects in QML -An alternative approach is to expose your existing QGraphicsWidget objects to +An alternative approach is to expose your existing QGraphicsWidget objects to QML and construct your scene in QML instead. See the \l {declarative-cppextensions-qgraphicslayouts.html}{graphics layouts example} which shows how to expose Qt's graphics layout classes to QML in order to use QGraphicsWidget with classes like QGraphicsLinearLayout and QGraphicsGridLayout. To expose your existing QGraphicsWidget classes to QML, use \l {qmlRegisterType()}. -See \l{Extending QML in C++} for further information on using C++ types in QML. +See \l{Extending QML Functionalities using C++} for further information on +how to use C++ types in QML. */ diff --git a/doc/src/declarative/mouseevents.qdoc b/doc/src/declarative/mouseevents.qdoc new file mode 100644 index 0000000..f6512a7 --- /dev/null +++ b/doc/src/declarative/mouseevents.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page mouseevents.html +\title QML Mouse Events +\ingroup QML Features +\previouspage {Anchor-based Layout in QML}{Layouts using Anchors} +\nextpage {QML Text Handling and Validators}{Text Handling and Validators} +\contentspage QML Features + +\tableofcontents + +\section1 Introduction + +\section1 Mouse Events + +\list +\o \l{MouseArea} Element +\o \l{MouseEvent} Object +\endlist + +\section1 Mouse Event Handling +go over the slots and signals feature (without the C++) + +To learn more about QML's event system, please read the \l {QML Signal and Handler Event System} document. + +*/ diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc index a19ca6b..3348eb8 100644 --- a/doc/src/declarative/network.qdoc +++ b/doc/src/declarative/network.qdoc @@ -27,6 +27,10 @@ /*! \page qdeclarativenetwork.html +\ingroup qml-features +\previouspage {Dynamic Object Management in QML}{Dynamic Object Management} +\nextpage {QML Internationalization}{Internationalization} +\contentspage QML Features \title Network Transparency QML supports network transparency by using URLs (rather than file names) for all @@ -57,7 +61,7 @@ Network transparency is supported throughout QML, for example: Even QML types themselves can be on the network - if the \l {QML Viewer} is used to load \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 +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. diff --git a/doc/src/declarative/positioners.qdoc b/doc/src/declarative/positioners.qdoc index d97acbd..2b3ee9a 100644 --- a/doc/src/declarative/positioners.qdoc +++ b/doc/src/declarative/positioners.qdoc @@ -27,8 +27,13 @@ /*! \page qml-positioners.html +\ingroup qml-features +\previouspage Property Binding +\nextpage Anchor-based Layout in QML +\contentspage QML Features \title Using QML Positioner and Repeater Items + \section1 Introduction Positioner items are container items that manage the positions and sizes of diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 3bf85de..6f7c40a 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -27,15 +27,188 @@ /*! \page propertybinding.html +\ingroup qml-features +\contentspage QML Features +\previouspage QML Syntax +\nextpage {QML Basic Types}{Data Types} \title Property Binding +\section1 Properties + +QML property rules coincide with many of JavaScript's property rules. +Properties begin with a lowercase letter (with the exception of +\l{Attached Properties}). \l {JavaScript Reserved Words}{JavaScript reserved words} +are not valid property names. + +\section1 Property types + +QML supports properties of many types (see \l{QML Basic Types}). The basic types +include int, real, bool, string, color, and lists. + +\code +Item { + x: 10.5 // a 'real' property + ... + state: "details" // a 'string' property + focus: true // a 'bool' property +} +\endcode + +QML properties are \i type-safe. That is, properties only allow you to assign +a value that matches the property type. For example, the \c x property of item is a real, and if you try to assign +a string to it you will get an error. + +\badcode +Item { + property real value: "hello" // illegal! +} +\endcode + +\section1 The \c id Property + +Each object can be given a special unique property called an \c id. No other object within the +same QML component (see \l{QML Documents}) can have the same \c id value. Assigning an id enables the object +to be referred to by other objects and scripts. + +The first Rectangle element below has an \c id, "myRect". The second Rectangle element defines its +own width by referring to \tt myRect.width, which means it will have the same \tt width +value as the first Rectangle element. + +\code +Item { + Rectangle { + id: myRect + width: 100 + height: 100 + } + Rectangle { + width: myRect.width + height: 200 + } +} +\endcode + +Note that an \c id must begin with a lower-case letter or an underscore. The \c id cannot contain characters other than letters, numbers, underscores, and \l {JavaScript Reserved Words}{JavaScript reserved words}. + + +\section1 List properties + +List properties look like this: + +\code +Item { + children: [ + Image {}, + Text {} + ] +} +\endcode + +The list is enclosed in square brackets, with a comma separating the +list elements. In cases where you are only assigning a single item to a +list, you can omit the square brackets: + +\code +Image { + children: Rectangle {} +} +\endcode + +Items in the list can be accessed by the \c index. See the \l{list}{list type} documentation +for more details about list properties and their available operations. + + +\section1 Default Properties + +Each object type can specify one of its list or object properties as its default property. +If a property has been declared as the default property, the property tag can be omitted. + +For example this code: +\code +State { + changes: [ + PropertyChanges {}, + PropertyChanges {} + ] +} +\endcode + +can be simplified to: + +\code +State { + PropertyChanges {} + PropertyChanges {} +} +\endcode + +because \c changes is the default property of the \c State type. + +\section1 Grouped Properties +\target dot properties + +In some cases properties form a logical group and use a 'dot' or grouped notation +to show this. + +Grouped properties can be written like this: +\qml +Text { + font.pixelSize: 12 + font.bold: true +} +\endqml + +or like this: +\qml +Text { + font { pixelSize: 12; bold: true } +} +\endqml + +In the element documentation grouped properties are shown using the 'dot' notation. + +\section1 Attached Properties +\target attached-properties + +Some objects attach properties to another object. Attached Properties +are of the form \c {Type.property} where \c Type is the type of the +element that attaches \c property. + +For example: +\code +Component { + id: myDelegate + Text { + text: "Hello" + color: ListView.isCurrentItem ? "red" : "blue" + } +} +ListView { + delegate: myDelegate +} +\endcode + +The \l ListView element attaches the \c ListView.isCurrentItem property +to each delegate it creates. + +Another example of attached properties is the \l Keys element which +attaches properties for handling key presses to +any visual Item, for example: + +\code +Item { + focus: true + Keys.onSelectPressed: console.log("Selected") +} +\endcode +\section1 Property Binding Property binding is a declarative way of specifying the value of a property. Binding allows a property's value to be expressed as an JavaScript expression that defines the value relative -to other property values or data accessible in the application. The property value is +to other property values or data accessible in the application. The property value is automatically kept up to date if the other properties or data values change. -Property bindings are created implicitly in QML whenever a property is assigned an JavaScript -expression. The following QML uses two property bindings to connect the size of the rectangle +Property bindings are created implicitly in QML whenever a property is assigned a JavaScript +expression. The following QML code uses two property bindings to connect the size of the rectangle to that of \c otherItem. \code @@ -45,9 +218,9 @@ Rectangle { } \endcode -QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be +QML extends a standards compliant JavaScript engine, so any valid JavaScript expression can be used as a property binding. Bindings can access object properties, make function calls and even -use builtin JavaScript objects like \e {Date} and \e {Math}. Assigning a constant value to a +use built-in JavaScript objects like \c {Date} and \c {Math}. Assigning a constant value to a property can even be thought of as a binding - after all, a constant is a valid JavaScript expression! Here are some examples of more complex bindings: @@ -71,10 +244,10 @@ function. \section1 Changing Bindings -The \l PropertyChanges element can be used within a state change to modify the bindings on -properties. +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} +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. @@ -110,10 +283,10 @@ Rectangle { \endcode Instead of creating a property binding, this simply sets the \c width of the \l Rectangle -to the value of \c other.width at the time the JavaScript code is invoked. See +to the value of \c other.width at the time the JavaScript code is invoked. See \l {Property Assignment vs Property Binding} for more details. -Also note that assigning a value to a property that is currently bound will remove the binding. +Also note that assigning a value to a property that is currently bound will remove the previous binding. A property can only have one value at a time, and if any code explicitly sets this value, the binding is removed. The \l Rectangle in the example below will have a width of 13, regardless of the \c otherItem's width. @@ -135,7 +308,7 @@ although it is possible to set up a \l Binding object (shown below). \section1 Binding Element The implicit binding syntax shown previously is easy to use and works perfectly for most uses -of bindings. In some advanced cases, it is necessary to create bindings explicitly using the +of bindings. In some advanced cases, it is necessary to create bindings explicitly using the \l Binding element. For example, to bind a property exposed from C++ (\c system.brightness) to a value @@ -147,7 +320,5 @@ Binding { value: slider.value } \endqml - - */ diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc index 0d5fbcc..cd4ccf0 100644 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -27,6 +27,10 @@ /*! \page qdeclarativei18n.html +\ingroup qml-features +\contentspage QML Features +\previouspage {Network Transparency}{Loading Resources in QML} +\nextpage {QML Graphical Effects}{Graphical Effects} \title QML Internationalization \section1 Overview diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index 495b3bd..e1a425f 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -27,10 +27,14 @@ /*! \page qdeclarativemodels.html +\ingroup qml-features +\contentspage QML Features +\previouspage {QML Animation and Transitions}{Animation and Transitions} +\nextpage {Presenting Data with Views} \target qmlmodels \title QML Data Models -QML items such as ListView, GridView and \l Repeater require Data Models +QML items such as ListView, GridView and \l Repeater require Data Models that provide the data to be displayed. These items typically require a \e delegate component that creates an instance for each item in the model. Models may be static, or @@ -38,7 +42,7 @@ have items modified, inserted, removed or moved dynamically. Data is provided to the delegate via named data roles which the delegate may bind to. Here is a ListModel with two roles, \e type and \e age, -and a ListView with a delegate that binds to these roles to display their +and a ListView with a delegate that binds to these roles to display their values: \snippet doc/src/snippets/declarative/qml-data-models/listmodel-listview.qml document @@ -48,7 +52,7 @@ properties, the roles can be accessed with the qualified \e model name instead. For example, if a \l Text element had \e type or \e age properties, the text in the above example would display those property values instead of the \e type and \e age values from the model item. In this case, the properties could have been referenced as -\c model.type and \c model.age instead to ensure the delegate displays the +\c model.type and \c model.age instead to ensure the delegate displays the property values from the model item. A special \e index role containing the index of the item in the model @@ -68,7 +72,8 @@ QML provides several types of data models among the built-in set of QML elements. In addition, models can be created with C++ and then made available to QML components. -The views used to access data models are described in \l{Presenting Data with QML}. +The views used to access data models are described in the +\l{Presenting Data with Views} overview. The use of positioner items to arrange items from a model is covered in \l{Using QML Positioner and Repeater Items}. @@ -125,10 +130,10 @@ be used to display an RSS feed. \section2 VisualItemModel -VisualItemModel allows QML items to be provided as a model. +VisualItemModel allows QML items to be provided as a model. This model contains both the data and delegate; the child items of a -VisualItemModel provide the contents of the delegate. The model +VisualItemModel provide the contents of the delegate. The model does not provide any roles. \code @@ -165,7 +170,7 @@ models. A model may be a simple QStringList, which provides the contents of the list via the \e modelData role. -Here is a ListView with a delegate that references its model item's +Here is a ListView with a delegate that references its model item's value using the \c modelData role: \snippet examples/declarative/modelviews/stringlistmodel/view.qml 0 @@ -184,7 +189,7 @@ the model by calling QDeclarativeContext::setContextProperty() again. \section2 QList<QObject*> -A list of QObject* values can also be used as a model. A QList<QObject*> provides +A list of QObject* values can also be used as a model. A QList<QObject*> provides the properties of the objects in the list as roles. The following application creates a \c DataObject class that with @@ -205,7 +210,7 @@ the ListView delegate: \snippet examples/declarative/modelviews/objectlistmodel/view.qml 0 -Note the use of the fully qualified access to the \c color property. +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 \c modelData object. @@ -221,10 +226,10 @@ the model by calling QDeclarativeContext::setContextProperty() again. A model can be defined by subclassing QAbstractItemModel. This is the best approach if you have a more complex model that cannot be supported -by the other approaches. A QAbstractItemModel can also automatically +by the other approaches. A QAbstractItemModel can also automatically notify a QML view when the model data has changed. -The roles of a QAbstractItemModel subclass can be exposed to QML by calling +The roles of a QAbstractItemModel subclass can be exposed to QML by calling QAbstractItemModel::setRoleNames(). The default role names set by Qt are: \table @@ -244,9 +249,9 @@ that has \e type and \e size roles. It calls QAbstractItemModel::setRoleNames() role names for accessing the properties via QML: \snippet examples/declarative/modelviews/abstractitemmodel/model.h 0 -\dots +\dots \snippet examples/declarative/modelviews/abstractitemmodel/model.h 1 -\dots +\dots \snippet examples/declarative/modelviews/abstractitemmodel/model.h 2 \codeline \snippet examples/declarative/modelviews/abstractitemmodel/model.cpp 0 @@ -261,14 +266,14 @@ roles: QML views are automatically updated when the model changes. Remember the model must follow the standard rules for model changes and notify the view when -the model has changed by using QAbstractItemModel::dataChanged(), +the model has changed by using QAbstractItemModel::dataChanged(), QAbstractItemModel::beginInsertRows(), etc. See the \l {Model subclassing reference} for more information. The complete example is available in Qt's \l {declarative/modelviews/abstractitemmodel}{examples/declarative/modelviews/abstractitemmodel} directory. QAbstractItemModel presents a hierarchy of tables, but the views currently provided by QML -can only display list data. +can only display list data. In order to display child lists of a hierarchical model the VisualDataModel element provides several properties and functions for use with models of type QAbstractItemModel: @@ -283,14 +288,14 @@ with models of type QAbstractItemModel: \section2 Exposing C++ data models to QML -The above examples use QDeclarativeContext::setContextProperty() to set -model values directly in QML components. An alternative to this is to -register the C++ model class as a QML type from a QML C++ plugin using -QDeclarativeExtensionPlugin. This would allow the model classes to be +The above examples use QDeclarativeContext::setContextProperty() to set +model values directly in QML components. An alternative to this is to +register the C++ model class as a QML type from a QML C++ plugin using +QDeclarativeExtensionPlugin. This would allow the model classes to be created directly as elements within QML: \table -\row +\row \o \code @@ -299,7 +304,7 @@ class MyModelPlugin : public QDeclarativeExtensionPlugin public: void registerTypes(const char *uri) { - qmlRegisterType<MyModel>(uri, 1, 0, + qmlRegisterType<MyModel>(uri, 1, 0, "MyModel"); } } @@ -463,84 +468,3 @@ a function in the model, e.g.: updated, and that \e{value} holds the new value. */ - -/*! -\page qml-presenting-data.html -\title Presenting Data with QML - -\section1 Introduction - -Qt Quick contains a set of standard items that can be used to present data in a -number of different ways. For simple user interfaces, -\l{Using QML Positioner and Repeater Items#Repeaters}{Repeaters} can be used -in combination with -\l{Using QML Positioner and Repeater Items#Positioners}{Positioners} -to obtain pieces of data and arrange them in a user interface. However, when -large quantities of data are involved, it is often better to use models with -the standard views since these contain many built-in display and navigation -features. - -\section1 Views - -Views are scrolling containers for collections of items. They are feature-rich, -supporting many of the use cases found in typical applications, and can be -customized to meet requirements on style and behavior. - -A set of standard views are provided in the basic set of Qt Quick -graphical elements: - -\list -\o \l{#ListView}{ListView} arranges items in a horizontal or vertical list -\o \l{#GridView}{GridView} arranges items in a grid within the available space -\o \l{#PathView}{PathView} arranges items on a path -\endlist - -Unlike these items, \l WebView is not a fully-featured view item, and needs -to be combined with a \l Flickable item to create a view that performs like -a Web browser. - -\section2 ListView - -\l ListView shows a classic list of items with horizontal or vertical placing -of items. - -\div{float-right} -\inlineimage qml-listview-snippet.png -\enddiv - -The following example shows a minimal ListView displaying a sequence of -numbers (using an \l{QML Data Models#An Integer}{integer as a model}). -A simple delegate is used to define an items for each piece of data in the -model. - -\clearfloat -\snippet doc/src/snippets/declarative/listview/listview-snippet.qml document - - - -\section2 GridView - -\l GridView displays items in a grid like an file manager's icon view. - -\section2 PathView - -\l PathView displays items on a path, where the selection remains in -the same place and the items move around it. - -\section1 Decorating Views - -\section2 Headers and Footers - -\section2 Sections - -\section2 Navigation - -In traditional user interfaces, views can be scrolled using standard -controls, such as scroll bars and arrow buttons. In some situations, it -is also possible to drag the view directly by pressing and holding a -mouse button while moving the cursor. In touch-based user interfaces, -this dragging action is often complemented with a flicking action, where -scrolling continues after the user has stopped touching the view. - -\section1 Further Reading -*/ diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index b663d43..3266bae 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -27,6 +27,10 @@ /*! \page qdeclarativestates.html +\ingroup qml-features +\contentspage QML Features +\previouspage {Importing Reusable Components} +\nextpage {QML Animation and Transitions}{Animation and Transitions} \target qmlstates \title QML States @@ -36,9 +40,9 @@ User interfaces are designed to present different interface configurations in different scenarios, or to modify their appearances in response to user interaction. Often, there are a set of changes that are made concurrently, such that the interface could be seen to be internally changing from one \e state to -another. +another. -This applies generally to interface elements regardless of their complexity. +This applies generally to interface elements regardless of their complexity. A photo viewer may initially present images in a grid, and when an image is clicked, change to a "detailed" state where the individual image is expanded and the interface is changed to present new options for image editing. On the @@ -47,7 +51,7 @@ other end of the scale, when a simple button is pressed, it may change to a appearance. In QML, any object can change between different \e states to apply sets of -changes that modify the properties of relevant items. Each \e state could +changes that modify the properties of relevant items. Each \e state could present a different configuration that could, for example: \list @@ -83,10 +87,10 @@ within the MouseArea changes the state to the "moved" state, thus moving the \l Rectangle. \snippet doc/src/snippets/declarative/states.qml 0 - + The \l State item defines all the changes to be made in the new state. It -could specify additional properties to be changed, or create additional -PropertyChanges for other objects. It can also modify the properties of other +could specify additional properties to be changed, or create additional +PropertyChanges for other objects. It can also modify the properties of other objects, not just the object that owns the state. For example: \qml @@ -96,13 +100,13 @@ Rectangle { State { name: "moved" PropertyChanges { target: myRect; x: 50; y: 50; color: "blue" } - PropertyChanges { target: someOtherItem; width: 1000 } + PropertyChanges { target: someOtherItem; width: 1000 } } ] } \endqml -As a convenience, if an item only has one state, its \l {Item::}{states} +As a convenience, if an item only has one state, its \l {Item::}{states} property can be defined as a single \l State, without the square-brace list syntax: @@ -115,7 +119,7 @@ Item { } \endqml -A \l State is not limited to performing modifications on property values. It +A \l State is not limited to performing modifications on property values. It can also: \list @@ -125,8 +129,8 @@ can also: \o Modify anchor values using AnchorChanges \endlist -The \l {declarative/animation/states}{States and Transitions example} -demonstrates how to declare a basic set of states and apply animated +The \l {declarative/animation/states}{States and Transitions example} +demonstrates how to declare a basic set of states and apply animated transitions between them. @@ -136,15 +140,15 @@ Of course, the \l Rectangle in the example above could have simply been moved by setting its position to (50, 50) in the mouse area's \c onClicked handler. However, aside from enabling batched property changes, one of the features of QML states is the ability of an item to revert to its \e {default state}. -The default state contains all of an item's initial property values before +The default state contains all of an item's initial property values before they were modified in a state change. For example, suppose the \l Rectangle should move to (50,50) when the mouse is -pressed, and then move back to its original position when the mouse is +pressed, and then move back to its original position when the mouse is released. This can be achieved by using the \l {State::}{when} property, like this: -\qml +\qml Rectangle { ... @@ -158,7 +162,7 @@ Rectangle { ... } } -\endqml +\endqml The \l {State::}{when} property is set to an expression that evaluates to \c true when the item should be set to that state. When the mouse is pressed, @@ -169,7 +173,7 @@ Alternatively, an item can be explicitly set to its default state by setting its \l {Item::}{state} property to an empty string (""). For example, instead of using the \l {State::}{when} property, the above code could be changed to: -\qml +\qml Rectangle { ... @@ -184,10 +188,10 @@ Rectangle { ... } } -\endqml +\endqml Obviously it makes sense to use the \l {State::}{when} property when possible -as it provides a simpler (and a better, more declarative) solution than +as it provides a simpler (and a better, more declarative) solution than assigning the state from signal handlers. @@ -210,14 +214,14 @@ Rectangle { states: [ ... ] - + transitions: [ Transition { NumberAnimation { properties: "x,y"; duration: 500 } } ] } -\endqml +\endqml This \l Transition defines that if any \c x or \c y properties have changed during a state change within this item, their values should be animated over 500 diff --git a/doc/src/declarative/qmlevents.qdoc b/doc/src/declarative/qmlevents.qdoc new file mode 100644 index 0000000..3c1c8df --- /dev/null +++ b/doc/src/declarative/qmlevents.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qmlevents.html + \ingroup qml-features + \contentspage QML Features + \previouspage {Integrating QML Code with Existing Qt UI Code} + \nextpage {Dynamic Object Management in QML}{Dynamic Object Management} + + \title QML Signal and Handler Event System + +*/ diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc new file mode 100644 index 0000000..78865a1 --- /dev/null +++ b/doc/src/declarative/qmlreusablecomponents.qdoc @@ -0,0 +1,497 @@ +/**************************************************************************** +** +** 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmlreusablecomponents.html +\ingroup qml-features +\previouspage {Keyboard Focus in QML}{Keyboard Focus} +\nextpage {QML States}{States} +\contentspage QML Features + +\title Importing Reusable Components + +One of the key concepts in QML is the ability to define your own QML components that suit +the purposes of your application. The standard \l {QML Elements} provide the essential components +for creating a QML application; beyond these, you can write your own custom components that can +be created and reused, without the use of C++. + +Components are the building blocks of a QML project. When writing a QML application, whether +large or small, it is best to separate QML code into smaller components that perform specific +sets of operations, instead of creating mammoth QML files with large, combined functionality +that is more difficult to manage and may contain duplicated code. + + +\section1 Defining New Components + +A component is a reusable type with a well-defined interface, built entirely in QML. +Any snippet of QML code can become a component, by placing the code in a file "<Name>.qml" where +<Name> is the new component name, beginning with an uppercase letter. These QML files automatically +become available as new QML element types to other QML components and applications in the same directory. + +For example, one of the simplest and most common components you can build in QML is a +button-type component. Below, we implement this component as a \l Rectangle with a clickable +\l MouseArea, in a file named \c Button.qml: + +\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0 + +Now this component can be reused by another file within the same directory. Since the file is +named \c Button.qml, the component is referred to as \c Button: + +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0 +\o \image qml-extending-types.png +\endtable + +The root object in \c Button.qml defines the attributes that are available to users of the +\c Button component. In this case, the root object is a \l Rectangle, so any properties, methods +and signals of \l Rectangle are made available, allowing \c application.qml to +customize the \c width, \c height, \c radius and \c color properties of \c Button objects. + + +If \c Button.qml was not in the same directory, \c application.qml would need to load it as a +\l {Modules}{module} from a specific filesystem path or \l{QDeclarativeExtensionPlugin}{plugin}. +Also, note the letter case of the component file name is significant on some (notably UNIX) +filesystems. It is recommended the file name case matches the case of the QML component name +exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the +QML component will be deployed. + +To write a useful component, it is generally necessary to provide it with custom attributes that store and +communicate specific data. This is achieved by adding the following attributes to your components: + +\list +\o \bold Properties that can be accessed externally to modify an object (for example, \l Item has + \l {Item::}{width} and \l {Item::}{height} properties) and used in \l {Property Binding} +\o \bold Methods of JavaScript code can be invoked internally or externally (for example, + \l Animation has a \l {Animation::}{start()} method) +\o \bold Signals to notify other objects when an event has occurred (for example, MouseArea has a + \c clicked signal) +\endlist + +The following sections show how these attributes can be added to QML components. + + +\section1 Adding Properties + +A property is a value of a QML component that can be read and modified by other objects. For +example, a \l Rectangle component has \l {Item::}{width}, \l {Item::}{height} and \l +{Rectangle::}{color} properties. Significantly, properties be used with \l {Property Binding}, where +a property value is automatically updated using the value of another property. + +The syntax for defining a new property is: + +\code +[default] property <type> <name>[: defaultValue] +\endcode + +A \c property declaration can appear anywhere within a QML component definition, but it is customary +to place it at the top. A component cannot declare more than one property with the same name. (It is +possible to have a property name that is the same as an existing property in a type, but this is not +recommended as the existing property becomes hidden and inaccessible.) + +Below is an example. The \c ImageViewer component has defined a \c string type property named +\c currentImage, and its initial value is "default-image.png". This property is used to set the image +displayed in the child \l Image object. Another file, \c application.qml, can create +an \c ImageViewer object and read or modify the \c currentImage value: + +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/ImageViewer.qml 0 +\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/application.qml 0 +\endtable + +It is optional for a property to have a default value. The default value is a convenient shortcut, and is +behaviorally identical to doing it in two steps, like this: + +\qml +// Use default value +property int myProperty: 10 + +// Longer, but behaviorally identical +property int myProperty +myProperty: 10 +\endqml + + +\section2 Supported property types + +All QML properties are typed. The examples above show properties with \c int and \c string types; +notice that the type of the property must be declared. The type is used to determine the property +behavior, and how the property is defined in C++. + +A number of property types are supported by default. These are listed in the table below, +with their default values and the corresponding C++ type: + +\table +\header \o QML Type Name \o Default value \o C++ Type Name +\row \o int \o 0 \o int +\row \o bool \o \c false \o bool +\row \o double \o 0.0 \o double +\row \o real \o 0.0 \o double +\row \o string \o "" (empty string) \o QString +\row \o url \o "" (empty url) \o QUrl +\row \o color \o #000000 (black) \o QColor +\row \o date \o \c undefined \o QDateTime +\row \o variant \o \c undefined \o QVariant +\endtable + +QML object types can also be used as property types. This includes +\l {Defining new QML elements}{custom QML types} implemented in C++. Such properties are +defined like this: + +\qml +property Item itemProperty +property QtObject objectProperty +property MyCustomType customProperty +\endqml + +Such object-type properties default to an \c undefined value. + +\l{list}{List properties} are created with the \c list<Type> syntax, and default to an empty +list: + +\qml +property list<Item> listOfItems +\endqml + +Note that list properties cannot be modified like ordinary JavaScript +arrays. See the \l {list}{list type documentation} for details. + +For details about accessing and manipulating QML properties from C++, see \l {Using QML Bindings in C++ Applications}. + + +\section2 Property change signals + +Adding a \c property to an item automatically adds a \e {value changed} +signal handler to the item. To connect to this signal, use a \l {Signal Handlers}{signal handler} +named with the \c on<Property>Changed syntax, using upper case for the first letter of the +property name. + +For example, the following \c onMyNumberChanged signal handler is automatically called whenever the +\c myNumber property changes: + +\snippet doc/src/snippets/declarative/qml-extending-types/properties/property-signals.qml 0 + + +\section2 Default properties + +The optional \c default attribute for a property marks it as the \e {default property} +for a type. This allows other items to specify the default property's value +as child elements. For example, the \l Item element's default property is its +\l{Item::children}{children} property. This allows the children of an \l Item +to be set like this: + +\qml +Item { + Rectangle {} + Rectangle {} +} +\endqml + +If the \l{Item::children}{children} property was not the default property for +\l Item, its value would have to be set like this instead: + +\qml +Item { + children: [ + Rectangle {} + Rectangle {} + ] +} +\endqml + +See the \l{declarative/ui-components/tabwidget}{TabWidget} example for a +demonstration of using default properties. + +Specifying a default property overrides any existing default property (for +example, any default property inherited from a parent item). Using the +\c default attribute twice in the same type block is an error. + + +\section2 Property aliases + +Property aliases are a more advanced form of property declaration. Unlike a +property definition, which allocates a new, unique storage space for the +property, a property alias connects the newly declared property (called the +aliasing property) as a direct reference to an existing property (the aliased property). Read +operations on the aliasing property act as read operations on the aliased +property, and write operations on the aliasing property as write operations on +the aliased property. + +A property alias declaration looks a lot like an ordinary property definition: +\code + [default] property alias <name>: <alias reference> +\endcode + +As the aliasing property has the same type as the aliased property, an explicit +type is omitted, and the special "alias" keyword is used. Instead of a default +value, a property alias includes a compulsory alias reference. The alias +reference is used to locate the aliased property. While similar to a property +binding, the alias reference syntax is highly restricted. + +An alias reference takes one of the following forms: +\code + <id>.<property> + <id> +\endcode + +where <id> must refer to an object id within the same component as the type +declaring the alias, and, optionally, <property> refers to a property on that object. + +For example, below is a \c Button.qml component with a \c buttonText aliased property which is +connected to the child Text object's \c text property: + +\snippet doc/src/snippets/declarative/qml-extending-types/properties/alias.qml 0 + +The following code would create a \c Button with a defined text string for the +child \l Text object: + +\qml +Button { buttonText: "This is a button" } +\endqml + +Here, modifying \c buttonText directly modifies the \c textItem.text value; it does not +change some other value that then updates \c textItem.text. + +In this case, the use of aliased properties is essential. If \c buttonText was not an alias, +changing its value would not actually change the displayed text at all, as +\l {Property Binding}{property bindings} are not bi-directional: the \c buttonText value would +change when \c textItem.text changes, but not the other way around. + +Aliased properties are also useful for allowing external objects to directly modify and +access child objects in a component. For example, here is a modified version of the \c ImageViewer +component shown \l {Adding Properties}{earlier} on this page. The \c currentImage property has +been changed to an alias to the child \l Image object: + +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/ImageViewer.qml 0 +\o \snippet doc/src/snippets/declarative/qml-extending-types/properties/alias/application.qml 0 +\endtable + +Instead of being limited to setting the \l Image source, \c application.qml can now directly +access and modify the child \l Image object and its properties. + +Obviously, exposing child objects in this manner should be done with care, as it allows external +objects to modify them freely. However, this use of aliased properties can be quite useful in +particular situations, such as for the \l {declarative/ui-components/tabwidget}{TabWidget} +example, where new tab items are actually parented to a child object that displays the current tab. + + +\section3 Considerations for property aliases + +Aliases are only activated once the component specifying them is completed. The +most obvious consequence of this is that the component itself cannot generally +use the aliased property directly during creation. For example, this will not work: + +\code + // Does NOT work + property alias buttonText: textItem.text + buttonText: "Some text" // buttonText is not yet defined when this value is set +\endcode + +A second, much less significant, consequence of the delayed activation of +aliases is that an alias reference cannot refer to another aliasing property +declared within the same component. This will not work: + +\code + // Does NOT work + id: root + property alias buttonText: textItem.text + property alias buttonText2: root.buttonText +\endcode + +At the time the component is created, the \c buttonText value has not yet been assigned, +so \c root.buttonText would refer to an undefined value. (From outside the component, +however, aliasing properties appear as regular Qt properties and consequently can be +used in alias references.) + +It is possible for an aliased property to have the same name as an existing property. For example, +the following component has a \c color alias property, named the same as the built-in +\l {Rectangle::color} property: + +\snippet doc/src/snippets/declarative/qml-extending-types/properties/alias-override.qml 0 + +Any objects that use this component and refer to its \c color property will be +referring to the alias rather than the ordinary \l {Rectangle::color} property. Internally, +however, the rectangle can correctly set this property to "red" and refer to the actual defined +property rather than the alias. + + +\section1 Adding Methods + +A QML component can define methods of JavaScript code. These methods can be invoked +either internally or by other objects. + +The syntax for defining a method is: + +\code +function <name>([<parameter name>[, ...]]) { <body> } +\endcode + +This declaration may appear anywhere within a type body, but it is customary to +include it at the top. Attempting to declare two methods or signals with the +same name in the same type block is an error. However, a new method may reuse +the name of an existing method on the type. (This should be done with caution, +as the existing method may be hidden and become inaccessible.) + +Unlike \l{Adding Signals}{signals}, method parameter types do not have to be declared as they +default to the \c variant type. The body of the method is written in JavaScript and may access +the parameters by name. + +Here is an example of a component with a \c say() method that accepts a single \c text argument: + +\snippet doc/src/snippets/declarative/qml-extending-types/methods/app.qml 0 + +A method can be connected to a signal so that it is automatically invoked whenever the signal +is emitted. See \l {Connecting signals to methods and other signals} below. + +Also see \l {Integrating JavaScript} for more information on using JavaScript with QML. + + +\section1 Adding Signals + +Signals provide a way to notify other objects when an event has occurred. For example, the MouseArea +\c clicked signal notifies other objects that the mouse has been clicked within the area. + +The syntax for defining a new signal is: + +\code +signal <name>[([<type> <parameter name>[, ...]])] +\endcode + +This declaration may appear anywhere within a type body, but it is customary to +include it at the top. Attempting to declare two signals or methods with the +same name in the same type block is an error. However, a new signal may reuse +the name of an existing signal on the type. (This should be done with caution, +as the existing signal may be hidden and become inaccessible.) + +Here are three examples of signal declarations: + +\code +Item { + signal clicked + signal hovered() + signal performAction(string action, variant actionArgument) +} +\endcode + +If the signal has no parameters, the "()" brackets are optional. If parameters are used, the +parameter types must be declared, as for the \c string and \c variant arguments for the \c +performAction signal above; the allowed parameter types are the same as those listed in the \l +{Adding Properties} section on this page. + +Adding a signal to an item automatically adds a \l {Signal Handlers}{signal handler} as well. +The signal hander is named \c on<SignalName>, with the first letter of the signal being upper +cased. The above example item would now have the following signal handlers: + +\list +\o onClicked +\o onHovered +\o onPerformAction +\endlist + +To emit a signal, simply invoke it in the same way as a method. Below left, when the \l MouseArea is +clicked, it emits the parent \c buttonClicked signal by invoking \c rect.buttonClicked(). The +signal is received by \c application.qml through an \c onButtonClicked signal handler: + +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/basic.qml 0 +\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/no-parameters.qml 0 +\endtable + +If the signal has parameters, they are accessible by parameter name in the signal handler. +In the example below, \c buttonClicked is emitted with \c xPos and \c yPos parameters instead: + +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/Button.qml 0 +\o \snippet doc/src/snippets/declarative/qml-extending-types/signals/parameters.qml 0 +\endtable + + +\section2 Connecting signals to methods and other signals + +Signal objects have a \c connect() method that can be used to a connect a signal to a method or +another signal. When a signal is connected to a method, the method is automatically invoked +whenever the signal is emitted. (In Qt terminology, the method is a \e slot that is connected +to the \e signal; all methods defined in QML are created as Qt slots.) This enables a signal +to be received by a method instead of a \l {Signal Handlers}{signal handler}. + +For example, the \c application.qml above could be rewritten as: + +\snippet doc/src/snippets/declarative/qml-extending-types/signals/connectslots.qml 0 + +The \c myMethod() method will be called whenever the \c buttonClicked signal is received. + +In many cases it is sufficient to receive signals through signal handlers rather than using +the \c connect() function; the above example does not provide any improvements over using a +simple \c onButtonClicked handler. However, if you are \l{Dynamic Object Management in QML}{creating objects dynamically}, +or \l {Integrating JavaScript}{integrating JavaScript code}, then you will find the +\c connect() method useful. For example, the component below creates three \c Button +objects dynamically, and connects the \c buttonClicked signal of each object to the +\c myMethod() function: + +\snippet doc/src/snippets/declarative/qml-extending-types/signals/connectdynamic.qml 0 + +In the same way, you could connect a signal to methods defined in a dynamically +created object, or \l {Receiving QML Signals in JavaScript}{connect a signal to a JavaScript method}. + +There is also a corresponding \c disconnect() method for removing connected signals. The following +code removes the connection created in \c application.qml above: + +\qml +// application.qml +Item { + ... + + function removeSignal() { + button.clicked.disconnect(item.myMethod) + } +} +\endqml + + +\section3 Forwarding signals + +The \c connect() method can also connect a signal to other signals. This has the effect +of "forwarding" a signal: it is automatically emitted whenever the relevant signal is emitted. For +example, the MouseArea \c onClicked handler in \c Button.qml above could have been replaced with +a call to \c connect(): + +\qml +MouseArea { + anchors.fill: parent + Component.onCompleted: clicked.connect(item.buttonClicked) +} +\endqml + +Whenever the \l MouseArea \c clicked signal is emitted, the \c rect.buttonClicked signal will +automatically be emitted as well. + +*/ diff --git a/doc/src/declarative/qmlruntime.qdoc b/doc/src/declarative/qmlruntime.qdoc index dfc0ad9..7a59959 100644 --- a/doc/src/declarative/qmlruntime.qdoc +++ b/doc/src/declarative/qmlruntime.qdoc @@ -29,13 +29,13 @@ \page qmlruntime.html \title Qt Declarative UI Runtime -QML documents are loaded and executed by the QML runtime. This includes the +QML documents are loaded and executed by the QML runtime. This includes the Declarative UI engine along with the built-in QML elements and plugin modules, and it also provides access to third-party QML elements and modules. -Applications that use QML need to invoke the QML runtime in order to -execute QML documents. This can be done by creating a QDeclarativeView -or a QDeclarativeEngine, as described below. In addition, the Declarative UI +Applications that use QML need to invoke the QML runtime in order to +execute QML documents. This can be done by creating a QDeclarativeView +or a QDeclarativeEngine, as described below. In addition, the Declarative UI package includes the \QQV tool, which loads \c .qml files. This tool is useful for developing and testing QML code without the need to write a C++ application to load the QML runtime. @@ -44,7 +44,7 @@ a C++ application to load the QML runtime. \section1 Deploying QML-based applications -To deploy an application that uses QML, the QML runtime must be invoked by +To deploy an application that uses QML, the QML runtime must be invoked by the application. This is done by writing a Qt C++ application that loads the QDeclarativeEngine by either: @@ -61,12 +61,12 @@ For example, if there is a QML file, \c application.qml, like this: \qml import QtQuick 1.0 - + Rectangle { width: 100; height: 100; color: "red" } \endqml It can be loaded in a Qt application's \c main.cpp file like this: - + \code #include <QApplication> #include <QDeclarativeView> @@ -82,10 +82,10 @@ It can be loaded in a Qt application's \c main.cpp file like this: return app.exec(); } \endcode - -This creates a QWidget-based view that displays the contents of + +This creates a QWidget-based view that displays the contents of \c application.qml. - + The application's \c .pro \l{qmake Project Files}{project file} must specify the \c declarative module for the \c QT variable. For example: @@ -97,36 +97,36 @@ the \c declarative module for the \c QT variable. For example: \section2 Creating a QDeclarativeEngine directly - -If \c application.qml does not have any graphical components, or if it is + +If \c application.qml does not have any graphical components, or if it is preferred to avoid QDeclarativeView for other reasons, the QDeclarativeEngine can be constructed directly instead. In this case, \c application.qml is loaded as a QDeclarativeComponent instance rather than placed into a view: \code #include <QApplication> - #include <QDeclarativeEngine> + #include <QDeclarativeEngine> #include <QDeclarativeContext> #include <QDeclarativeComponent> int main(int argc, char *argv[]) { QApplication app(argc, argv); - + QDeclarativeEngine engine; QDeclarativeContext *objectContext = new QDeclarativeContext(engine.rootContext()); - + QDeclarativeComponent component(&engine, "application.qml"); QObject *object = component.create(objectContext); - + // ... delete object and objectContext when necessary - + return app.exec(); } \endcode -See \l {Using QML in C++ Applications} for more information about using -QDeclarativeEngine, QDeclarativeContext and QDeclarativeComponent, as well +See \l {Using QML Bindings in C++ Applications} for more information about using +QDeclarativeEngine, QDeclarativeContext and QDeclarativeComponent, as well as details on including QML files through \l{The Qt Resource System}{Qt's Resource system}. @@ -135,8 +135,8 @@ as details on including QML files through \l{The Qt Resource System}{Qt's Resour The Declarative UI package includes a QML runtime tool, the \QQV, which loads and displays QML documents. This is useful during the application development -phase for prototyping QML-based applications without writing your own C++ -applications to invoke the QML runtime. +phase for prototyping QML-based applications without writing your own C++ +applications to invoke the QML runtime. See the \l{QML Viewer} documentation for more details. diff --git a/doc/src/declarative/qmlsyntax.qdoc b/doc/src/declarative/qmlsyntax.qdoc new file mode 100644 index 0000000..908b924 --- /dev/null +++ b/doc/src/declarative/qmlsyntax.qdoc @@ -0,0 +1,157 @@ +/**************************************************************************** +** +** 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qmlsyntax.html +\title QML Syntax +\ingroup QML Features +\previouspage QML Features +\nextpage Property Binding +\contentspage QML Features + +\tableofcontents + +QML is a declarative language designed to describe the user interface of a +program: both what it looks like, and how it behaves. In QML, a user +interface is specified as a tree of objects with properties. + +JavaScript is used as a scripting language in QML, so you may want +to learn a bit more about it (\l{Javascript Guide}) before diving +deeper into QML. + +\section1 Basic QML Syntax + +QML looks like this: + +\code +import QtQuick 1.0 + +Rectangle { + width: 200 + height: 200 + color: "blue" + + Image { + source: "pics/logo.png" + anchors.centerIn: parent + } +} +\endcode + +Objects are specified by their type, followed by a pair of braces. Object +types always begin with a capital letter. In the above example, there are +two objects, a \l Rectangle, and an \l Image. Between the braces, we can specify +information about the object, such as its properties. + +Properties are specified as \c {property: value}. In the above example, we +can see the Image has a property named \c source, which has been assigned the +value \c "pics/logo.png". The property and its value are separated by a colon. + +Properties can be specified one-per-line: + +\code +Rectangle { + width: 100 + height: 100 +} +\endcode + +or you can put multiple properties on a single line: + +\code +Rectangle { width: 100; height: 100 } +\endcode + +When multiple property/value pairs are specified on a single line, they +must be separated by a semicolon. + +The \c import statement imports the \c Qt \l{QML Modules}{module}, which contains all of the +standard \l {QML Elements}. Without this import statement, the \l Rectangle +and \l Image elements would not be available. + +\section1 Expressions + +In addition to assigning values to properties, you can also assign +expressions written in JavaScript. + +\code +Rotation { + angle: 360 * 3 +} +\endcode + +These expressions can include references to other objects and properties, in which case +a \e binding is established: when the value of the expression changes, the property the +expression has been assigned to is automatically updated to that value. + +\code +Item { + Text { + id: text1 + text: "Hello World" + } + Text { + id: text2 + text: text1.text + } +} +\endcode + +In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed, +\c text2 is automatically changed to the same value. + +Note that to refer to other objects, we use their \e id values. (See below for more +information on the \e id property.) + +\section1 QML Comments + +Commenting in QML is similar to JavaScript. +\list +\o Single line comments start with // and finish at the end of the line. +\o Multiline comments start with /* and finish with *\/ +\endlist + +\snippet doc/src/snippets/declarative/comments.qml 0 + +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 +sometimes useful for tracking down problems. + +\code +Text { + text: "Hello world!" + //opacity: 0.5 +} +\endcode + +In the above example, the Text object will have normal opacity, since the +line opacity: 0.5 has been turned into a comment. + +*/ diff --git a/doc/src/declarative/qmltexthandling.qdoc b/doc/src/declarative/qmltexthandling.qdoc new file mode 100644 index 0000000..c5a6bc9 --- /dev/null +++ b/doc/src/declarative/qmltexthandling.qdoc @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page texthandling.html +\title QML Text Handling and Validators +\ingroup QML Features +\previouspage {QML Mouse Events}{Mouse Events} +\nextpage {Keyboard Focus in QML}{Keyboard Focus} +\contentspage QML Features + +\tableofcontents + +\section1 Introduction + +\section1 Text Elements + +\list +\o \l{Text} +\o \l{TextInput} +\o \l{TextEdit} +\endlist + +\section1 Validators +\list +\o \l{IntValidator} +\o \l{DoubleValidator} +\o \l{RegExpValidator} +\endlist + +*/ diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/declarative/qmlviewer.qdoc index 82f1fec..551b20c 100644 --- a/doc/src/declarative/qmlviewer.qdoc +++ b/doc/src/declarative/qmlviewer.qdoc @@ -31,34 +31,34 @@ \title QML Viewer \ingroup qttools -The Declarative UI package includes \QQV, a tool for loading QML documents that -makes it easy to quickly develop and debug QML applications. It invokes the QML -runtime to load QML documents and also includes additional features useful for +The Declarative UI package includes \QQV, a tool for loading QML documents that +makes it easy to quickly develop and debug QML applications. It invokes the QML +runtime to load QML documents and also includes additional features useful for the development of QML-based applications. -The QML Viewer is a tool for testing and developing QML applications. It is -\e not intended for use in a production environment and should not be used for the +The QML Viewer is a tool for testing and developing QML applications. It is +\e not intended for use in a production environment and should not be used for the deployment of QML applications. In those cases, the QML runtime should be invoked from a Qt application instead; see \l {Qt Declarative UI Runtime} for more information. The viewer is located at \c QTDIR/bin/qmlviewer. To load a \c .qml file -with the viewer, run the viewer and select the file to be opened, or provide the +with the viewer, run the viewer and select the file to be opened, or provide the file path on the command line: \code qmlviewer myqmlfile.qml \endcode - + On Mac OS X, the QML Viewer application is named "QMLViewer" instead. You -can launch the viewer by opening the QMLViewer application from the Finder, or +can launch the viewer by opening the QMLViewer application from the Finder, or from the command line: \code QMLViewer.app/Contents/MacOS/QMLViewer myqmlfile.qml \endcode -The QML Viewer has a number of configuration options involving features such as +The QML Viewer has a number of configuration options involving features such as fullscreen display, module import path configurations, video recording of QML animations, and OpenGL support. @@ -68,7 +68,7 @@ To see the configuration options, run \c qmlviewer with the \c -help argument. \section1 Adding module import paths Additional module import paths can be provided using the \c -I flag. -For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates +For example, the \l{declarative/cppextensions/plugins}{QML plugins example} creates a C++ plugin identified as \c com.nokia.TimeExample. Since this has a namespaced identifier, the viewer has to be run with the \c -I flag from the example's base directory: @@ -87,16 +87,16 @@ the path is explicitly added. \section1 Loading translation files -When the QML Viewer loads a QML file, it installs a translation file from a -"i18n" subdirectory relative to that initial file. This directory should contain +When the QML Viewer loads a QML file, it installs a translation file from a +"i18n" subdirectory relative to that initial file. This directory should contain translation files named "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". +"qml_fr_CA.qm". Such files can be created using \l {Qt Linguist}. -The actual translation file that is loaded depends on the system locale. +The actual translation file that is loaded depends on the system locale. Additionally, the viewer will load any translation files specified on the command line via the \c -translation option. @@ -110,7 +110,7 @@ shows how JavaScript code in QML files can be made to use translatable strings. Often, QML applications are prototyped with fake data that is later replaced by real data sources from C++ plugins. QML Viewer assists in this aspect by loading fake data into the application context: it looks for a directory named -"dummydata" in the same directory as the target QML file, and any \c .qml +"dummydata" in the same directory as the target QML file, and any \c .qml files in that directory are loaded as QML objects and bound to the root context as properties named after the files. @@ -124,7 +124,7 @@ ListView { width: 200; height: 300 model: lottoNumbers delegate: Text { text: number } -} +} \endqml If within the document's directory, there is a "dummydata" directory which @@ -146,30 +146,30 @@ Child properties are included when loaded from dummy data. The following documen refers to a \c clock.time property: \qml -import QtQuick 1.0 +import QtQuick 1.0 Text { text: clock.time } \endqml - + The text value could be filled by a \c dummydata/clock.qml file with a \c time property in the root context: \qml -import QtQuick 1.0 +import QtQuick 1.0 QtObject { property int time: 54321 } \endqml To replace this with real data, you can simply bind the real data object to the root context in C++ using QDeclarativeContext::setContextProperty(). This -is detailed in \l {Using QML in C++ Applications}. +is detailed in \l {Using QML Bindings in C++ Applications}. \section1 Using the \c runtime object QML applications that are loaded with the QML Viewer have access to a special -\c runtime property on the root context. This property provides additional +\c runtime property on the root context. This property provides additional information about the application's runtime environment through the following properties: \table -\row +\row \o \c runtime.isActiveWindow @@ -177,9 +177,9 @@ information about the application's runtime environment through the following pr window on the system. It is useful for "pausing" an application, particularly animations, when the QML Viewer loses focus or moves to the background. -For example, the following animation is only played when the QML Viewer is +For example, the following animation is only played when the QML Viewer is the active window: - + \qml Rectangle { width: 200; height: 200 @@ -197,9 +197,9 @@ Rectangle { \o \c runtime.orientation \o This property indicates the current orientation of the QML Viewer. On the -N900 platform and most S60 5.0-based or newer Symbian devices, this property -automatically updates to reflect the device's actual orientation; on other platforms, -this indicates the orientation currently selected in the QML Viewer's +N900 platform and most S60 5.0-based or newer Symbian devices, this property +automatically updates to reflect the device's actual orientation; on other platforms, +this indicates the orientation currently selected in the QML Viewer's \e {Settings -> Properties} menu. The \c orientation value can be one of the following: \list @@ -210,7 +210,7 @@ this indicates the orientation currently selected in the QML Viewer's \endlist When the viewer's orientation changes, the appearance of the loaded QML document -does not change unless it has been set to respond to changes in +does not change unless it has been set to respond to changes in \c runtime.orientation. For example, the following Rectangle changes its aspect ratio depending on the orientation of the QML Viewer: @@ -218,12 +218,12 @@ aspect ratio depending on the orientation of the QML Viewer: Rectangle { id: window width: 640; height: 480 - + states: State { name: "landscape" PropertyChanges { target: window; width: 480; height: 640 } } - state: (runtime.orientation == Orientation.Landscape + state: (runtime.orientation == Orientation.Landscape || runtime.orientation == Orientation.LandscapeInverted) ? 'landscape' : '' } \endqml diff --git a/doc/src/declarative/qmlviews.qdoc b/doc/src/declarative/qmlviews.qdoc new file mode 100644 index 0000000..3f74214 --- /dev/null +++ b/doc/src/declarative/qmlviews.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qml-views.html +\ingroup qml-features +\contentspage QML Features +\previouspage {QML Data Models}{Structuring Data with Models} +\nextpage {Extending QML Functionalities using C++} +\title Presenting Data with Views + +\section1 Introduction + +Qt Quick contains a set of standard items that can be used to present data in a +number of different ways. For simple user interfaces, +\l{Using QML Positioner and Repeater Items#Repeaters}{Repeaters} can be used +in combination with +\l{Using QML Positioner and Repeater Items#Positioners}{Positioners} +to obtain pieces of data and arrange them in a user interface. However, when +large quantities of data are involved, it is often better to use models with +the standard views since these contain many built-in display and navigation +features. + +\section1 Views + +Views are scrolling containers for collections of items. They are feature-rich, +supporting many of the use cases found in typical applications, and can be +customized to meet requirements on style and behavior. + +A set of standard views are provided in the basic set of Qt Quick +graphical elements: + +\list +\o \l{#ListView}{ListView} arranges items in a horizontal or vertical list +\o \l{#GridView}{GridView} arranges items in a grid within the available space +\o \l{#PathView}{PathView} arranges items on a path +\endlist + +Unlike these items, \l WebView is not a fully-featured view item, and needs +to be combined with a \l Flickable item to create a view that performs like +a Web browser. + +\section2 ListView + +\l ListView shows a classic list of items with horizontal or vertical placing +of items. + +\beginfloatright +\inlineimage qml-listview-snippet.png +\endfloat + +The following example shows a minimal ListView displaying a sequence of +numbers (using an \l{QML Data Models#An Integer}{integer as a model}). +A simple delegate is used to define an items for each piece of data in the +model. + +\clearfloat +\snippet doc/src/snippets/declarative/listview/listview-snippet.qml document + + + +\section2 GridView + +\l GridView displays items in a grid like an file manager's icon view. + +\section2 PathView + +\l PathView displays items on a path, where the selection remains in +the same place and the items move around it. + +\section1 Decorating Views + +\section2 Headers and Footers + +\section2 Sections + +\section2 Navigation + +In traditional user interfaces, views can be scrolled using standard +controls, such as scroll bars and arrow buttons. In some situations, it +is also possible to drag the view directly by pressing and holding a +mouse button while moving the cursor. In touch-based user interfaces, +this dragging action is often complemented with a flicking action, where +scrolling continues after the user has stopped touching the view. + +\section1 Further Reading +*/ diff --git a/doc/src/declarative/qmlwebkit.qdoc b/doc/src/declarative/qmlwebkit.qdoc new file mode 100644 index 0000000..0f4e86b --- /dev/null +++ b/doc/src/declarative/qmlwebkit.qdoc @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qmlwebkit.html + + \title QtWebKit QML Module + + Qt WebKit QML + + \section1 WebKit QML Elements + \list + \o \l WebView + \o \l FlickableWebView + \endlist + + \section1 Content + + \section1 Usage Ideas + + \section1 Other Suggestions + +*/ diff --git a/doc/src/declarative/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc index 04b8ca6..a7aacdb 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/declarative/qtbinding.qdoc @@ -27,10 +27,13 @@ /*! \page qtbinding.html -\target qtbinding -\title Using QML in C++ Applications +\ingroup qml-features +\previouspage {Extending QML Functionalities using C++} +\nextpage {Integrating QML Code with Existing Qt UI Code} +\contentspage QML Features +\title Using QML Bindings in C++ Applications -QML is designed to be easily extensible from C++. The classes in the +QML is designed to be easily extensible to and from C++. The classes in the Qt Declarative module allow QML components to be loaded and manipulated from C++, and through Qt's \l{The Meta-Object System}{meta-object system}, QML and C++ objects can easily communicate through Qt signals and slots. In addition, QML plugins can be written to create @@ -85,7 +88,7 @@ delete rectangleInstance; QML documents can also be loaded using QDeclarativeView. This class provides a convenient QWidget-based view for embedding QML components into QGraphicsView-based applications. (For other -methods of integrating QML into QWidget-based applications, see \l {Integrating QML with existing Qt +methods of integrating QML into QWidget-based applications, see \l {Integrating QML Code with existing Qt UI code}.) @@ -253,8 +256,8 @@ Note that custom C++ types do not have to inherit from QDeclarativeItem; this is a displayable item. If the item is not displayable, it can simply inherit from QObject. For more information on defining new QML elements, see the \l {Tutorial: Writing QML extensions with C++} -{Writing QML extensions with C++} tutorial and the \l {Extending QML in C++} reference -documentation. +{Writing QML extensions with C++} tutorial and the +\l {Extending QML Functionalities using C++} reference documentation. @@ -484,7 +487,8 @@ can be registered using qmlRegisterUncreatableType(). To be accessible from QML must begin with a capital letter. See the \l {Tutorial: Writing QML extensions with C++}{Writing QML extensions with C++} tutorial and -the \l {Extending QML in C++} reference documentation for more information. +the \l {Extending QML Functionalities using C++} reference documentation for +more information. \section2 Automatic type conversion from strings diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc index 0c14093..1746c31 100644 --- a/doc/src/declarative/qtprogrammers.qdoc +++ b/doc/src/declarative/qtprogrammers.qdoc @@ -48,7 +48,8 @@ QML provides direct access to the following concepts from Qt: \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}. +Qt knowledge is \e required for \l {Extending QML Functionalities using C++}, +and also for \l{Integrating QML Code with existing Qt UI code}. \section1 QML Items compared with QWidgets diff --git a/doc/src/examples/qml-examples.qdoc b/doc/src/examples/qml-examples.qdoc index 0834527..9dad84a 100644 --- a/doc/src/examples/qml-examples.qdoc +++ b/doc/src/examples/qml-examples.qdoc @@ -29,7 +29,7 @@ \title Animation: Basics Example \example declarative/animation/basics - This example shows how to create and combine \l{QML Animation}{animations} in QML. + This example shows how to create and combine \l{QML Animation and Transitions}{animations} in QML. \table \row @@ -50,16 +50,16 @@ \title Animation: Behavior Examples \example declarative/animation/behaviors - This example shows how to use QML behaviors. + This example shows how to use QML behaviors. \image qml-behaviors-example.png */ /*! - \title Animation: Easing Example + \title Animation: Easing Example \example declarative/animation/easing - This example shows the different easing modes available for \l{QML Animation}{animations}. + This example shows the different easing modes available for \l{QML Animation and Transitions}{animations}. \image qml-easing-example.png */ @@ -122,9 +122,9 @@ \page declarative-cppextensions-reference.html \title C++ Extensions: Reference examples - These examples show how QML can be extended from C++ in various ways. - - The code for these examples is used throughout the \l {Extending QML in C++} reference + These examples show how QML can be extended from C++ in various ways. + + The code for these examples is used throughout the \l {Extending QML Functionalities using C++} reference documentation, which highlights the main principles demonstrated in each example. Furthermore, here are additional pages that discuss each example in detail: @@ -160,7 +160,7 @@ \title LayoutItem Example \example declarative/cppextensions/qgraphicslayouts/layoutitem - This example show how to use the LayoutItem element to integrate QML items into an existing + This example show how to use the LayoutItem element to integrate QML items into an existing \l{Graphics View Framework}{Graphics View}-based application. \image qml-layoutitem-example.png @@ -169,7 +169,7 @@ \title QGraphicsGridLayout Example \example declarative/cppextensions/qgraphicslayouts/qgraphicsgridlayout - This example shows how to use QGraphicsGridLayout to lay out QML items. This is + This example shows how to use QGraphicsGridLayout to lay out QML items. This is useful if you need to integrate Qt \l{Graphics View Framework}{Graphics View} layouts with QML. @@ -179,10 +179,10 @@ \title QGraphicsLinearLayout Example \example declarative/cppextensions/qgraphicslayouts/qgraphicslinearlayout - This example shows how to use QGraphicsLinearLayout to lay out QML items. This is + This example shows how to use QGraphicsLinearLayout to lay out QML items. This is useful if you need to integrate Qt \l{Graphics View Framework}{Graphics View} layouts with QML. - + \image qml-qgraphicslinearlayout-example.png */ /*! @@ -198,7 +198,7 @@ \o \l{declarative/cppextensions/qgraphicslayouts/qgraphicslinearlayout}{QGraphicsLinearLayout} \endlist - Also see \l {Integrating QML with existing Qt UI code} for information on using QML + Also see \l {Integrating QML Code with Existing Qt UI Code} for information on using QML in Qt applications that use the Graphics View framework or ordinary QWidget-based views. */ @@ -215,7 +215,7 @@ \title C++ Extensions: Image Provider Example \example declarative/cppextensions/imageprovider - This examples shows how to use QDeclarativeImageProvider to serve images + This examples shows how to use QDeclarativeImageProvider to serve images to QML image elements. \image qml-imageprovider-example.png @@ -525,7 +525,7 @@ \example declarative/toys/clocks This example displays a set of clocks with different times for different cities. - Each clock is created by combining \l Image elements with \l Rotation transforms + Each clock is created by combining \l Image elements with \l Rotation transforms and \l SpringAnimation behaviors. \image qml-clocks-example.png diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc index 9bc3b1c..c02556f 100644 --- a/doc/src/external-resources.qdoc +++ b/doc/src/external-resources.qdoc @@ -453,3 +453,9 @@ \externalpage http://www.libusb.org/ \title libusb */ + +/*! + \externalpage https://developer.mozilla.org/en/JavaScript/Reference/Reserved_Words + \title JavaScript Reserved Words +*/ + diff --git a/doc/src/getting-started/gettingstartedqml.qdoc b/doc/src/getting-started/gettingstartedqml.qdoc index 11fad03..754f426 100644 --- a/doc/src/getting-started/gettingstartedqml.qdoc +++ b/doc/src/getting-started/gettingstartedqml.qdoc @@ -631,7 +631,7 @@ Now that we have our text editor layout, we may now implement the text editor functionalities in C++. Using QML with C++ enables us to create our application logic using Qt. We can create a QML context in a C++ application using the - \l {Using QML in C++ Applications}{Qt's Declarative} classes and display the QML + \l {Using QML Bindings in C++ Applications}{Qt's Declarative} classes and display the QML elements using a Graphics Scene. Alternatively, we can export our C++ code into a plugin that the \l {QML Viewer}{qmlviewer} tool can read. For our application, we shall implement the load and save functions in C++ and export it as a plugin. diff --git a/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc b/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc new file mode 100644 index 0000000..6c83c80 --- /dev/null +++ b/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc @@ -0,0 +1,94 @@ +/**************************************************************************** +** +** 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qml-best-practices-coding.html + \ingroup qml-best-practices + \contentspage QML Best Practices Guides + \previouspage QML Best Practices Guides + \startpage QML Best Practices Guides + \title QML Best Practices: Coding Conventions + + \brief QML Coding Conventions and Importing Files + + There are many different ways to code using QML. These are a set of + guidelines to help your code look better and consistent. + + \section1 Coding Conventions + + The official QML Coding Conventions may be found at + \l {QML Coding Conventions}. This is the recommended convention that will be + used throughout the QML documentation. + + In addition, Qt's official code style may be found at the \l {Qt Coding Style}. + + \section1 Importing Files into QML + + To import items such as directories, use the "import" keyword, similar to + the way the \c {import QtQuick 1.0} statement is used. + + \qml + import QtQuick 1.0 + import QtWebKit 1.0 + import "subdirectory" + import "script.js" + \endqml + + To facilitate the importation of QML components, it is best to begin the QML + file with an uppercase character. This way, the user can simply declare the + component using the file name as the component name. For example, if a QML + component is in a file named \c Button.qml, then the user may import the + component by declaring a \c {Button {}}. Note that this method only works if + the QML files are in the same directory. + + \qml + import QtQuick 1.0 + + Rectangle { + width: 50; height: 50 + + Button {} //Button is defined in Button.qml in the same directory + } + \endqml + + It is also possible to import QML files which have file names that begin in + lower case or files in a different directory by using a \c qmldir file. + + A \c qmldir file tells your QML application which QML components, plugins, + or directories to import. The \c qmldir file must reside in an imported + directory. + + \code + //A very simple qmldir file + + Button ./custom.qml //a QML component called Button in the file custom.qml + plugin FilePlugin ./plugins //a plugin called FileDialog in the plugins directory + \endcode + + By using the \c qmldir file, users may import any QML file and assign any + valid QML component name to the component. +*/ diff --git a/doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.qdoc b/doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.qdoc new file mode 100644 index 0000000..0f6d74b --- /dev/null +++ b/doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ +/*! + \page qml-best-practices-datatypes.html + \ingroup qml-best-practices + \contentspage QML Best Practices Guides + \previouspage QML Best Practices Guides + \startpage QML Best Practices Guides + \title QML Best Practices: Data Types + + \brief Using Basic Data Types and Custom Types in QML + + QML supports many basic data types, Qt data types, and custom data types. + + \section1 Basic Data Types + + \section1 Qt Data Types + + \section1 Exporting Qt Types to QML + + Programmers may create C++ data structures and expose them to QML, making + data accessible from QML. + + \section2 Using QStringLists in QML +*/ diff --git a/doc/src/overviews.qdoc b/doc/src/overviews.qdoc index a411aa2..6b24052 100644 --- a/doc/src/overviews.qdoc +++ b/doc/src/overviews.qdoc @@ -43,7 +43,7 @@ web-enabled applications for desktop, mobile, and embedded operating systems. This page contains links to articles and overviews explaining key components and techniuqes used in Qt development. - + \generatelist {related} */ @@ -112,7 +112,7 @@ \ingroup technology-apis \ingroup best-practices \ingroup qt-basic-concepts - + These pages document Qt's API's for using SQL database systems in Qt applications. @@ -133,7 +133,7 @@ \generatelist{related} */ -/*! +/*! \group licensing \title Qt Licenses and Credits @@ -146,3 +146,58 @@ \generatelist {related} */ + +/*! + \group qml-best-practices + \title QML Best Practices Guides + + \brief QML Programming Best Practices Guides + + These documents provide guidelines and best practices for using QML and Qt + to solve specific technical problems. + + \generatelist {related} +*/ +/*! + \group qml-features + \title QML Features + + \brief Features of the QML Language + + These are overviews of the many features of the QML language. + + \list + \o \l{QML Syntax} + \o \l{Property Binding} + \o \l{QML Basic Types}{Data Types} + \o \l{QML Basic Elements}{Basic Elements} + \o \l{Using QML Positioner and Repeater Items}{Component Layouts} + \o \l{Anchor-based Layout in QML}{Layouts using Anchors} + \o \l{Mouse Events} + \o \l{QML Text Handling and Validators}{Text Handling and Validators} + \o \l{Keyboard Focus in QML}{Keyboard Focus} + \o \l{Importing Reusable Components} + \o \l{QML States}{States} + \o \l{QML Animation and Transitions}{Animation and Transitions} + \o \l{QML Data Models}{Structuring Data with Models} + \o \l{Presenting Data with Views} + \o \l{Extending QML Functionalities using C++} + \o \l{Using QML Bindings in C++ Applications} + \o \l{Integrating QML Code with Existing Qt UI Code} + \o \l{QML Signal and Handler Event System}{Signal and Handler Event System} + \o \l{Dynamic Object Management in QML}{Dynamic Object Management} + \o \l{Network Transparency}{Loading Resources in QML} + \o \l{QML Internationalization}{Internationalization} + \o \l{QML Graphical Effects}{Graphical Effects} + \endlist +*/ +/*! + \group qml-architecture + \title QML Architecture + + \brief QML Architecture + + These are overviews of the architecture of QML and Qt Declarative Module. + + \generatelist {related} +*/ diff --git a/doc/src/qt-webpages.qdoc b/doc/src/qt-webpages.qdoc index 0a03157..516f2c5 100644 --- a/doc/src/qt-webpages.qdoc +++ b/doc/src/qt-webpages.qdoc @@ -244,3 +244,19 @@ \externalpage http://labs.qt.nokia.com \title Qt Labs */ + +/*! + \externalpage http://doc.qt.nokia.com/qtcreator-snapshot/index.html + \title Qt Creator Manual +*/ + +/*! + \externalpage http://doc.qt.nokia.com/qtcreator-snapshot/creator-qml-application.html + \title Developing Qt Quick Applications with Creator +*/ + +/*! + \externalpage http://qt.gitorious.org/qt/pages/QtCodingStyle + \title Qt Coding Style +*/ + |