From 177d6865c65719c7c6ffdb6c8fd1e7c3e049e1e1 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Mon, 13 Dec 2010 16:03:20 +0100 Subject: Added \ingroup for the overview pages and \group page. --- doc/src/declarative/anchor-layout.qdoc | 5 +- doc/src/declarative/animation.qdoc | 34 ++++---- doc/src/declarative/basictypes.qdoc | 18 ++-- doc/src/declarative/declarativeui.qdoc | 124 ++++++++++++++-------------- doc/src/declarative/dynamicobjects.qdoc | 24 +++--- doc/src/declarative/extending.qdoc | 25 +++--- doc/src/declarative/focus.qdoc | 2 + doc/src/declarative/integrating.qdoc | 11 +-- doc/src/declarative/network.qdoc | 3 +- doc/src/declarative/positioners.qdoc | 5 ++ doc/src/declarative/propertybinding.qdoc | 30 ++++--- doc/src/declarative/qdeclarativei18n.qdoc | 1 + doc/src/declarative/qdeclarativemodels.qdoc | 44 +++++----- doc/src/declarative/qdeclarativestates.qdoc | 42 +++++----- doc/src/declarative/qtbinding.qdoc | 1 + doc/src/overviews.qdoc | 28 ++++++- 16 files changed, 229 insertions(+), 168 deletions(-) diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc index b77ce36..2435e4e 100644 --- a/doc/src/declarative/anchor-layout.qdoc +++ b/doc/src/declarative/anchor-layout.qdoc @@ -28,13 +28,16 @@ /*! \page qml-anchor-layout.html \target anchor-layout +\contentspage QML Features +\previouspage Using QML Positioner and Repeater Items +\nextpage Using QML Positioner and Repeater Items \title Anchor-based Layout in QML In addition to the more traditional \l Grid, \l Row, and \l Column, QML also provides a way to layout items using the concept of \e anchors. Each item can be thought of as having a set of 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..708f412 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -27,6 +27,8 @@ /*! \page qdeclarativeanimation.html +\ingroup qml-features +\contentspage QML Features \title QML Animation @@ -80,7 +82,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 +94,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 +143,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 +158,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 +189,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 +233,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 +253,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/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 034b7d1..0277ccb 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -27,12 +27,14 @@ /*! \page qdeclarativebasictypes.html + \ingroup qml-features + \contentspage QML Features \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 + 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 list of types that can be used for \c property values. @@ -43,7 +45,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 +119,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 +200,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 +239,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 +275,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 +294,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 +495,7 @@ \qml Text { horizontalAlignment: "AlignRight" } \endqml - + or as \c {.}: \qml Text { horizontalAlignment: Text.AlignRight } diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 41b9952..b17d178 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,64 +55,62 @@ 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{Introduction to the QML language}{Introduction to the QML Language} +\o \l{QML for Qt Programmers}{QML Programming for Qt Programmers} \o \l{Getting Started Programming with QML} -\o \l{Intro to Qt Quick} +\o \l{What's new in Qt Quick}{What's New in the Qt Quick Release} \endlist -\list -\o \l{QML Tutorial}{Tutorial: "Hello World"} -\o \l{QML Advanced Tutorial}{Tutorial: "Same Game"} -\o \l{QML Examples and Demos} -\endlist - -\section1 QML Concepts +\section1 QML Features \list -\o \l{QML Documents} \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{Using QML Positioner and Repeater Items}{Component Layouts} +\o \l{Anchor-based Layout in QML}{Anchor Layout} +\o \l{Writing QML Components: Properties, Methods and Signals}{Reusable Components} +\o \l{Text Handling} +\o \l{Keyboard Focus in QML}{Keyboard Focus} +\o \l{Mouse Events} +\o \l{QML States} {States} +\o \l{QML Animation}{Animation and Transitions} +\o \l{QML Basic Types}{QML Basic Data Types} +\o \l{QML Data Models}{Structuring Data with Models} +\o \l{Presenting Data with QML}{Presenting Data with Views} +\o \l{Affine Transformations} +\o \l{Dynamic Object Management in QML}{Dynamic Object Management} +\o \l{Network Transparency}{Resource Loading} +\o \l{Extending QML in C++}{Extending QML Functionalities using C++} +\o \l{Using QML in C++ Applications} +\o \l{Integrating QML with existing Qt UI code}{Integrating QML Code with Existing Qt UI Code} +\o \l{Signals and Slots Event System} +\o \l{QML Internationalization}{Internationalization} +\o \l{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{Qt WebKit} +\o \l{Mobility QML bindings} \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{QML Viewer} +\o \l{QML Performance} +\o \l{Developing Qt Quick Applications}{Developing with Qt Creator} \endlist \section1 Architecture @@ -120,39 +118,45 @@ Module. \list \o \l{Qt Declarative UI Runtime} \o \l{Integrating JavaScript} -\o \l{Dynamic Object Management in QML} -\endlist - -\section1 Using QML with C++ - -\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++} +\o \l{QML Scope} +\o \l{QML Modules} +\o \l{QML Documents} +\o \l{QML Global Object} +\o \l{QML Security} +\o \l{Qt Declarative Module} \endlist \section1 Reference \list \o \l{QML Elements} -\o \l{QML Basic Types} -\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 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 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{Geir's screen size document} +\endlist */ diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index fcc9fd4..1e43166 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -27,11 +27,13 @@ /*! \page qdeclarativedynamicobjects.html +\ingroup qml-features +\contentspage {QML Features} \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}). @@ -45,20 +47,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 +90,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 +158,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 +190,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.qdoc b/doc/src/declarative/extending.qdoc index e23ca91..e61447a 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -27,6 +27,8 @@ /*! \page qml-extending.html +\ingroup qml-features +\contentspage QML Features \title Extending QML in C++ The QML syntax declaratively describes how to construct an in-memory object @@ -360,28 +362,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 @@ -637,6 +639,7 @@ public: /*! \page qml-extending-types.html +\ingroup qml-features \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 diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc index ae72c3c..3da60f1 100644 --- a/doc/src/declarative/focus.qdoc +++ b/doc/src/declarative/focus.qdoc @@ -28,6 +28,8 @@ /*! \target qmlfocus \page qdeclarativefocus.html +\ingroup qml-features +\contentspage QML Features \title Keyboard Focus in QML When a key is pressed or released, a key event is generated and delivered to the diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/declarative/integrating.qdoc index 7028585..23235d7 100644 --- a/doc/src/declarative/integrating.qdoc +++ b/doc/src/declarative/integrating.qdoc @@ -27,6 +27,7 @@ /*! \page qml-integration.html +\ingroup qml-features \title Integrating QML with existing Qt UI code There are a number of ways to integrate QML into QWidget-based UI applications, @@ -37,8 +38,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 +53,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 +71,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,7 +96,7 @@ 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. diff --git a/doc/src/declarative/network.qdoc b/doc/src/declarative/network.qdoc index a19ca6b..4354f9d 100644 --- a/doc/src/declarative/network.qdoc +++ b/doc/src/declarative/network.qdoc @@ -27,6 +27,7 @@ /*! \page qdeclarativenetwork.html +\ingroup qml-features \title Network Transparency QML supports network transparency by using URLs (rather than file names) for all @@ -57,7 +58,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 9265732..7faac03 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..92cf874 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -27,15 +27,21 @@ /*! \page propertybinding.html +\ingroup qml-features +\contentspage QML Features +\previouspage QML Features +\nextpage Using QML Positioner and Repeater Items \title Property Binding + +\section1 Introduction 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 +51,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 +77,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. @@ -97,7 +103,7 @@ Rectangle { \section1 Effects of Property Assignment in JavaScript -Assigning a property value from JavaScript does \e not create a property binding. +Assigning a property value from JavaScript does \i not create a property binding. For example: \code @@ -110,10 +116,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 +141,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 diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc index 0d5fbcc..fac1e55 100644 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -27,6 +27,7 @@ /*! \page qdeclarativei18n.html +\ingroup qml-features \title QML Internationalization \section1 Overview diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index e11cd56..fdae0bb 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -27,10 +27,12 @@ /*! \page qdeclarativemodels.html +\ingroup qml-features +\contentspage QML Features \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 +40,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 +50,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 @@ -125,10 +127,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 +167,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 +186,7 @@ the model by calling QDeclarativeContext::setContextProperty() again. \section2 QList -A list of QObject* values can also be used as a model. A QList provides +A list of QObject* values can also be used as a model. A QList provides the properties of the objects in the list as roles. The following application creates a \c DataObject class that with @@ -205,7 +207,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 +223,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 +246,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 +263,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 +285,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 +301,7 @@ class MyModelPlugin : public QDeclarativeExtensionPlugin public: void registerTypes(const char *uri) { - qmlRegisterType(uri, 1, 0, + qmlRegisterType(uri, 1, 0, "MyModel"); } } @@ -466,6 +468,8 @@ updated, and that \e{value} holds the new value. /*! \page qml-presenting-data.html +\ingroup qml-features +\contentspage QML Features \title Presenting Data with QML \section1 Introduction diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index b663d43..f378ce6 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -27,6 +27,8 @@ /*! \page qdeclarativestates.html +\ingroup qml-features +\contentspage QML Features \target qmlstates \title QML States @@ -36,9 +38,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 +49,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 +85,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 +98,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 +117,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 +127,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 +138,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 +160,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 +171,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 +186,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 +212,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/qtbinding.qdoc b/doc/src/declarative/qtbinding.qdoc index 71f41bc..347fd94 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/declarative/qtbinding.qdoc @@ -27,6 +27,7 @@ /*! \page qtbinding.html +\ingroup qml-features \target qtbinding \title Using QML in C++ Applications diff --git a/doc/src/overviews.qdoc b/doc/src/overviews.qdoc index b9bd3b4..3bb7aec 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,25 @@ \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. + + \generatelist {related} +*/ -- cgit v0.12 From d108279da20ad84e0d662a905bc12e00c1011d50 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Mon, 13 Dec 2010 18:24:10 +0100 Subject: Added JavaScript Reserved Word link into resource file. Task-number: QTBUG-16071 --- doc/src/external-resources.qdoc | 6 ++++++ 1 file changed, 6 insertions(+) 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 +*/ + -- cgit v0.12 From 7b608475fb40c790fba5c618be51a92fd9d5ca92 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Tue, 14 Dec 2010 15:39:53 +0100 Subject: Doc: Added QML Syntax overview page. Modified landing page. QML Syntax is to provide essential QML and JavaScript language info. Task-number:#QTBUG-16071 --- doc/src/declarative/declarativeui.qdoc | 29 +++--- doc/src/declarative/qmlsyntax.qdoc | 158 +++++++++++++++++++++++++++++++++ 2 files changed, 174 insertions(+), 13 deletions(-) create mode 100644 doc/src/declarative/qmlsyntax.qdoc diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index b17d178..771a421 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -65,15 +65,17 @@ QML and the Qt Declarative Module separate the frontend UI logic from the backen \list \o \l{Intro to Qt Quick}{Introduction to Qt Quick} -\o \l{Introduction to the QML language}{Introduction to the QML Language} \o \l{QML for Qt Programmers}{QML Programming for Qt Programmers} \o \l{Getting Started Programming with QML} + \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 Features \list +\o \l{QML Syntax} \o \l{Property Binding} \o \l{Using QML Positioner and Repeater Items}{Component Layouts} \o \l{Anchor-based Layout in QML}{Anchor Layout} @@ -113,6 +115,19 @@ QML and the Qt Declarative Module separate the frontend UI logic from the backen \o \l{Developing Qt Quick Applications}{Developing with Qt Creator} \endlist +\section1 Reference + +\list +\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 Architecture \list @@ -126,18 +141,6 @@ QML and the Qt Declarative Module separate the frontend UI logic from the backen \o \l{Qt Declarative Module} \endlist -\section1 Reference - -\list -\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 Examples \list diff --git a/doc/src/declarative/qmlsyntax.qdoc b/doc/src/declarative/qmlsyntax.qdoc new file mode 100644 index 0000000..4ff2437 --- /dev/null +++ b/doc/src/declarative/qmlsyntax.qdoc @@ -0,0 +1,158 @@ +/**************************************************************************** +** +** 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 +\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. + +This introduction is meant for those with little or no programming +experience. 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. It's also helpful to have a basic understanding of other web +technologies like HTML and CSS, but it's not required. + +\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. + +*/ -- cgit v0.12 From 380a85758b673563b2912b413bbcfce49fc564b7 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Tue, 14 Dec 2010 15:56:30 +0100 Subject: Added an entry for QML Architecture in the overviews page. This is for adding architecture information in the documentation. Task-number: QTBUG-16071 --- doc/src/overviews.qdoc | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/src/overviews.qdoc b/doc/src/overviews.qdoc index 3bb7aec..5c48a33 100644 --- a/doc/src/overviews.qdoc +++ b/doc/src/overviews.qdoc @@ -168,3 +168,13 @@ \generatelist {related} */ +/*! + \group qml-architecture + \title QML Architecture + + \brief QML Architecture + + These are overviews of the architecture of QML and Qt Declarative Module. + + \generatelist {related} +*/ -- cgit v0.12 From 401e43aa33a3c1a914f4280190a9d514a6fe0918 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Mon, 20 Dec 2010 16:15:25 +0100 Subject: Adding two QML Best Practice guides. Task-number: QTBUG-15757 --- .../qmlbestpractices/qmlbestpractices-coding.qdoc | 94 ++++++++++++++++++++++ .../qmlbestpractices-datatypes.qdoc | 49 +++++++++++ 2 files changed, 143 insertions(+) create mode 100644 doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc create mode 100644 doc/src/howtos/qmlbestpractices/qmlbestpractices-datatypes.qdoc 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 +*/ -- cgit v0.12 From 9b0ad342cc888bd4291c84f63fe485bfbfdc3ce0 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Mon, 20 Dec 2010 17:29:06 +0100 Subject: Re-organized the Qt Quick page. Changed titles and links. Task-number: QTBUG-16071 --- doc/src/declarative/anchor-layout.qdoc | 4 +- doc/src/declarative/animation.qdoc | 4 +- doc/src/declarative/basicelements.qdoc | 37 ++ doc/src/declarative/basictypes.qdoc | 4 +- doc/src/declarative/declarativeui.qdoc | 40 +- doc/src/declarative/dynamicobjects.qdoc | 4 +- doc/src/declarative/extending-tutorial.qdoc | 48 +- doc/src/declarative/extending.qdoc | 472 +------------------ doc/src/declarative/focus.qdoc | 5 +- doc/src/declarative/graphicaleffects.qdoc | 36 ++ doc/src/declarative/integrating.qdoc | 8 +- doc/src/declarative/mouseevents.qdoc | 52 +++ doc/src/declarative/network.qdoc | 3 + doc/src/declarative/propertybinding.qdoc | 177 +++++++- doc/src/declarative/qdeclarativei18n.qdoc | 3 + doc/src/declarative/qdeclarativemodels.qdoc | 88 +--- doc/src/declarative/qdeclarativestates.qdoc | 2 + doc/src/declarative/qmlevents.qdoc | 37 ++ doc/src/declarative/qmlreusablecomponents.qdoc | 497 +++++++++++++++++++++ doc/src/declarative/qmlruntime.qdoc | 42 +- doc/src/declarative/qmlsyntax.qdoc | 7 +- doc/src/declarative/qmltexthandling.qdoc | 55 +++ doc/src/declarative/qmlviewer.qdoc | 60 +-- doc/src/declarative/qmlviews.qdoc | 111 +++++ doc/src/declarative/qmlwebkit.qdoc | 47 ++ doc/src/declarative/qtbinding.qdoc | 17 +- doc/src/declarative/qtprogrammers.qdoc | 3 +- doc/src/examples/qml-examples.qdoc | 28 +- doc/src/getting-started/gettingstartedqml.qdoc | 2 +- doc/src/overviews.qdoc | 29 +- doc/src/qt-webpages.qdoc | 16 + .../ui-components/tabwidget/TabWidget.qml | 2 +- .../graphicsitems/qdeclarativeflipable.cpp | 14 +- src/declarative/qml/qdeclarativecomponent.cpp | 52 +-- src/declarative/qml/qdeclarativecontext.cpp | 46 +- src/declarative/util/qdeclarativeanimation.cpp | 170 +++---- src/declarative/util/qdeclarativebehavior.cpp | 6 +- .../util/qdeclarativesmoothedanimation.cpp | 12 +- .../util/qdeclarativespringanimation.cpp | 20 +- src/declarative/util/qdeclarativetransition.cpp | 24 +- src/declarative/util/qdeclarativeview.cpp | 12 +- 41 files changed, 1428 insertions(+), 868 deletions(-) create mode 100644 doc/src/declarative/basicelements.qdoc create mode 100644 doc/src/declarative/graphicaleffects.qdoc create mode 100644 doc/src/declarative/mouseevents.qdoc create mode 100644 doc/src/declarative/qmlevents.qdoc create mode 100644 doc/src/declarative/qmlreusablecomponents.qdoc create mode 100644 doc/src/declarative/qmltexthandling.qdoc create mode 100644 doc/src/declarative/qmlviews.qdoc create mode 100644 doc/src/declarative/qmlwebkit.qdoc diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc index 4953b22..11acbad 100644 --- a/doc/src/declarative/anchor-layout.qdoc +++ b/doc/src/declarative/anchor-layout.qdoc @@ -29,8 +29,8 @@ \page qml-anchor-layout.html \target anchor-layout \contentspage QML Features -\previouspage Using QML Positioner and Repeater Items -\nextpage Using QML Positioner and Repeater Items +\previouspage {Using QML Positioner and Repeater Items}{Component Layouts} +\nextpage {QML Mouse Events}{Mouse Events} \title Anchor-based Layout in QML \section1 Overview diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 708f412..099f02d 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -29,7 +29,9 @@ \page qdeclarativeanimation.html \ingroup qml-features \contentspage QML Features -\title QML Animation +\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 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 0277ccb..59772c5 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -29,13 +29,15 @@ \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 + \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 diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 771a421..473cbdd 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -77,42 +77,41 @@ QML and the Qt Declarative Module separate the frontend UI logic from the backen \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}{Anchor Layout} -\o \l{Writing QML Components: Properties, Methods and Signals}{Reusable Components} -\o \l{Text Handling} -\o \l{Keyboard Focus in QML}{Keyboard Focus} +\o \l{Anchor-based Layout in QML}{Layouts using Anchors} \o \l{Mouse Events} -\o \l{QML States} {States} -\o \l{QML Animation}{Animation and Transitions} -\o \l{QML Basic Types}{QML Basic Data Types} +\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 QML}{Presenting Data with Views} -\o \l{Affine Transformations} +\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}{Resource Loading} -\o \l{Extending QML in C++}{Extending QML Functionalities using C++} -\o \l{Using QML in C++ Applications} -\o \l{Integrating QML with existing Qt UI code}{Integrating QML Code with Existing Qt UI Code} -\o \l{Signals and Slots Event System} +\o \l{Network Transparency}{Loading Resources in QML} \o \l{QML Internationalization}{Internationalization} -\o \l{Graphical Effects} +\o \l{QML Graphical Effects}{Graphical Effects} \endlist \section1 QML Add-Ons \list -\o \l{Qt WebKit} -\o \l{Mobility QML bindings} +\o \l{QtWebKit QML Module} +\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} \endlist \section1 Qt Quick Tools \list \o \l{Debugging QML} +\o \l{Developing Qt Quick Applications with Creator}{Developing with Qt Creator} \o \l{QML Viewer} -\o \l{QML Performance} -\o \l{Developing Qt Quick Applications}{Developing with Qt Creator} \endlist \section1 Reference @@ -160,6 +159,9 @@ examples for porting} \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 1e43166..e5077ba 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -29,13 +29,15 @@ \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. 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 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 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 51b52b0..d3f1521 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -29,7 +29,9 @@ \page qml-extending.html \ingroup qml-features \contentspage QML Features -\title Extending QML in C++ +\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 @@ -431,7 +433,7 @@ onChanged, regardless of the name used for the NOTIFY signal in C++. We recommend using 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 @@ -637,469 +639,3 @@ public: */ -/*! -\page qml-extending-types.html -\ingroup qml-features -\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 ".qml" where - 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 [: 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 syntax, and default to an empty -list: - -\qml -property list 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 onChanged 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 : -\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 - . - -\endcode - -where must refer to an object id within the same component as the type -declaring the alias, and, optionally, 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 ([[, ...]]) { } -\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 [([ [, ...]])] -\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, 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 3da60f1..be1000e 100644 --- a/doc/src/declarative/focus.qdoc +++ b/doc/src/declarative/focus.qdoc @@ -30,11 +30,14 @@ \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 23235d7..caba2cd 100644 --- a/doc/src/declarative/integrating.qdoc +++ b/doc/src/declarative/integrating.qdoc @@ -28,7 +28,10 @@ /*! \page qml-integration.html \ingroup qml-features -\title Integrating QML with existing Qt UI code +\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. @@ -102,6 +105,7 @@ 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 4354f9d..3348eb8 100644 --- a/doc/src/declarative/network.qdoc +++ b/doc/src/declarative/network.qdoc @@ -28,6 +28,9 @@ /*! \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 diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 92cf874..6f7c40a 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -29,12 +29,179 @@ \page propertybinding.html \ingroup qml-features \contentspage QML Features -\previouspage QML Features -\nextpage Using QML Positioner and Repeater Items +\previouspage QML Syntax +\nextpage {QML Basic Types}{Data Types} \title Property Binding +\section1 Properties -\section1 Introduction +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 @@ -103,7 +270,7 @@ Rectangle { \section1 Effects of Property Assignment in JavaScript -Assigning a property value from JavaScript does \i not create a property binding. +Assigning a property value from JavaScript does \e not create a property binding. For example: \code @@ -153,7 +320,5 @@ Binding { value: slider.value } \endqml - - */ diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc index fac1e55..cd4ccf0 100644 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -28,6 +28,9 @@ /*! \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 0be29e1..e1a425f 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -29,6 +29,8 @@ \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 @@ -70,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}. @@ -465,86 +468,3 @@ a function in the model, e.g.: updated, and that \e{value} holds the new value. */ - -/*! -\page qml-presenting-data.html -\ingroup qml-features -\contentspage QML Features -\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 f378ce6..3266bae 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -29,6 +29,8 @@ \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 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 ".qml" where + 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 [: 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 syntax, and default to an empty +list: + +\qml +property list 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 onChanged 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 : +\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 + . + +\endcode + +where must refer to an object id within the same component as the type +declaring the alias, and, optionally, 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 ([[, ...]]) { } +\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 [([ [, ...]])] +\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, 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 #include @@ -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 - #include + #include #include #include 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 index 4ff2437..908b924 100644 --- a/doc/src/declarative/qmlsyntax.qdoc +++ b/doc/src/declarative/qmlsyntax.qdoc @@ -30,6 +30,7 @@ \title QML Syntax \ingroup QML Features \previouspage QML Features +\nextpage Property Binding \contentspage QML Features \tableofcontents @@ -38,11 +39,9 @@ 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. -This introduction is meant for those with little or no programming -experience. JavaScript is used as a scripting language in QML, so you may want +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. It's also helpful to have a basic understanding of other web -technologies like HTML and CSS, but it's not required. +deeper into QML. \section1 Basic QML Syntax 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_.qm", where 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 0a66226..a7aacdb 100644 --- a/doc/src/declarative/qtbinding.qdoc +++ b/doc/src/declarative/qtbinding.qdoc @@ -28,10 +28,12 @@ /*! \page qtbinding.html \ingroup qml-features -\target qtbinding -\title Using QML in C++ Applications +\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 @@ -86,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}.) @@ -254,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. @@ -485,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/getting-started/gettingstartedqml.qdoc b/doc/src/getting-started/gettingstartedqml.qdoc index e3977bb..d2fc4ea 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/overviews.qdoc b/doc/src/overviews.qdoc index 5c48a33..96805d0 100644 --- a/doc/src/overviews.qdoc +++ b/doc/src/overviews.qdoc @@ -164,9 +164,32 @@ \brief Features of the QML Language - These are overviews of the many features of the QML Language. - - \generatelist {related} + 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 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 +*/ + diff --git a/examples/declarative/ui-components/tabwidget/TabWidget.qml b/examples/declarative/ui-components/tabwidget/TabWidget.qml index 2a74c46..c8f5711 100644 --- a/examples/declarative/ui-components/tabwidget/TabWidget.qml +++ b/examples/declarative/ui-components/tabwidget/TabWidget.qml @@ -45,7 +45,7 @@ Item { // Setting the default property to stack.children means any child items // of the TabWidget are actually added to the 'stack' item's children. - // See the "Writing QML Components: Properties, Methods and Signals" + // See the "Property Binding" // documentation for details on default properties. default property alias content: stack.children diff --git a/src/declarative/graphicsitems/qdeclarativeflipable.cpp b/src/declarative/graphicsitems/qdeclarativeflipable.cpp index f118a85..48b6ba0 100644 --- a/src/declarative/graphicsitems/qdeclarativeflipable.cpp +++ b/src/declarative/graphicsitems/qdeclarativeflipable.cpp @@ -86,13 +86,13 @@ public: The following example shows a Flipable item that flips whenever it is clicked, rotating about the y-axis. - This flipable item has a \c flipped boolean property that is toggled - whenever the MouseArea within the flipable is clicked. When - \c flipped is true, the item changes to the "back" state; in this + This flipable item has a \c flipped boolean property that is toggled + whenever the MouseArea within the flipable is clicked. When + \c flipped is true, the item changes to the "back" state; in this state, the \c angle of the \l Rotation item is changed to 180 degrees to produce the flipping effect. When \c flipped is false, the - item reverts to the default state, in which the \c angle value is 0. - + item reverts to the default state, in which the \c angle value is 0. + \snippet doc/src/snippets/declarative/flipable/flipable.qml 0 \image flipable.gif @@ -103,8 +103,8 @@ public: its old and new values. See \l {QML States} for details on state changes and the default - state, and \l {QML Animation} for more information on how animations - work within transitions. + state, and \l {QML Animation and Transitions} for more information on how + animations work within transitions. \sa {declarative/ui-components/flipable}{Flipable example} */ diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp index 77fc925..edc7b2a 100644 --- a/src/declarative/qml/qdeclarativecomponent.cpp +++ b/src/declarative/qml/qdeclarativecomponent.cpp @@ -135,7 +135,7 @@ class QByteArray; } \endcode - \sa {Using QML in C++ Applications}, {Integrating QML with existing Qt UI code} + \sa {Using QML Bindings in C++ Applications}, {Integrating QML Code with Existing Qt UI Code} */ /*! @@ -157,7 +157,7 @@ class QByteArray; \snippet doc/src/snippets/declarative/component.qml 0 - Notice that while a \l Rectangle by itself would be automatically + Notice that while a \l Rectangle by itself would be automatically rendered and displayed, this is not the case for the above rectangle because it is defined inside a \c Component. The component encapsulates the QML elements within, as if they were defined in a separate QML @@ -227,7 +227,7 @@ class QByteArray; /*! \enum QDeclarativeComponent::Status - + Specifies the loading status of the QDeclarativeComponent. \value Null This QDeclarativeComponent has no data. Call loadUrl() or setData() to add QML content. @@ -279,8 +279,8 @@ void QDeclarativeComponentPrivate::clear() typeData->release(); typeData = 0; } - - if (cc) { + + if (cc) { cc->release(); cc = 0; } @@ -436,12 +436,12 @@ QDeclarativeComponent::QDeclarativeComponent(QDeclarativeEngine *engine, const Q } /*! - Create a QDeclarativeComponent from the given \a fileName and give it the specified + Create a QDeclarativeComponent from the given \a fileName and give it the specified \a parent and \a engine. \sa loadUrl() */ -QDeclarativeComponent::QDeclarativeComponent(QDeclarativeEngine *engine, const QString &fileName, +QDeclarativeComponent::QDeclarativeComponent(QDeclarativeEngine *engine, const QString &fileName, QObject *parent) : QObject(*(new QDeclarativeComponentPrivate), parent) { @@ -480,7 +480,7 @@ void QDeclarativeComponent::setData(const QByteArray &data, const QUrl &url) d->url = url; QDeclarativeTypeData *typeData = QDeclarativeEnginePrivate::get(d->engine)->typeLoader.get(data, url); - + if (typeData->isCompleteOrError()) { d->fromTypeData(typeData); } else { @@ -615,7 +615,7 @@ QDeclarativeComponent::QDeclarativeComponent(QDeclarativeComponentPrivate &dd, Q /*! \qmlmethod object Component::createObject(Item parent) - Creates and returns an object instance of this component that will have the given + Creates and returns an object instance of this component that will have the given \a parent. Returns null if object creation fails. The object will be created in the same context as the one in which the component @@ -623,8 +623,8 @@ QDeclarativeComponent::QDeclarativeComponent(QDeclarativeComponentPrivate &dd, Q which were not created in QML. If you wish to create an object without setting a parent, specify \c null for - the \a parent value. Note that if the returned object is to be displayed, you - must provide a valid \a parent value or set the returned object's \l{Item::parent}{parent} + the \a parent value. Note that if the returned object is to be displayed, you + must provide a valid \a parent value or set the returned object's \l{Item::parent}{parent} property, or else the object will not be visible. Dynamically created instances can be deleted with the \c destroy() method. @@ -669,7 +669,7 @@ QScriptValue QDeclarativeComponent::createObject(QObject* parent) } } - if (needParent) + if (needParent) qWarning("QDeclarativeComponent: Created graphical object was not placed in the graphics scene."); } completeCreate(); @@ -682,7 +682,7 @@ QScriptValue QDeclarativeComponent::createObject(QObject* parent) /*! Create an object instance from this component. Returns 0 if creation failed. \a context specifies the context within which to create the object - instance. + instance. If \a context is 0 (the default), it will create the instance in the engine' s \l {QDeclarativeEngine::rootContext()}{root context}. @@ -699,7 +699,7 @@ QObject *QDeclarativeComponent::create(QDeclarativeContext *context) return rv; } -QObject *QDeclarativeComponentPrivate::create(QDeclarativeContextData *context, +QObject *QDeclarativeComponentPrivate::create(QDeclarativeContextData *context, const QBitField &bindings) { if (!context) @@ -712,21 +712,21 @@ QObject *QDeclarativeComponentPrivate::create(QDeclarativeContextData *context, /*! This method provides more advanced control over component instance creation. - In general, programmers should use QDeclarativeComponent::create() to create a + In general, programmers should use QDeclarativeComponent::create() to create a component. Create an object instance from this component. Returns 0 if creation failed. \a context specifies the context within which to create the object - instance. + instance. When QDeclarativeComponent constructs an instance, it occurs in three steps: \list 1 \i The object hierarchy is created, and constant values are assigned. \i Property bindings are evaluated for the the first time. \i If applicable, QDeclarativeParserStatus::componentComplete() is called on objects. - \endlist + \endlist QDeclarativeComponent::beginCreate() differs from QDeclarativeComponent::create() in that it - only performs step 1. QDeclarativeComponent::completeCreate() must be called to + only performs step 1. QDeclarativeComponent::completeCreate() must be called to complete steps 2 and 3. This breaking point is sometimes useful when using attached properties to @@ -777,7 +777,7 @@ QDeclarativeComponentPrivate::beginCreate(QDeclarativeContextData *context, cons return begin(context, creationContext, cc, start, count, &state, 0, bindings); } -QObject * QDeclarativeComponentPrivate::begin(QDeclarativeContextData *parentContext, +QObject * QDeclarativeComponentPrivate::begin(QDeclarativeContextData *parentContext, QDeclarativeContextData *componentCreationContext, QDeclarativeCompiledData *component, int start, int count, ConstructionState *state, QList *errors, @@ -789,7 +789,7 @@ QObject * QDeclarativeComponentPrivate::begin(QDeclarativeContextData *parentCon Q_ASSERT(!isRoot || state); // Either this isn't a root component, or a state data must be provided Q_ASSERT((state != 0) ^ (errors != 0)); // One of state or errors (but not both) must be provided - if (isRoot) + if (isRoot) QDeclarativeDebugTrace::startRange(QDeclarativeDebugTrace::Creating); QDeclarativeContextData *ctxt = new QDeclarativeContextData; @@ -798,7 +798,7 @@ QObject * QDeclarativeComponentPrivate::begin(QDeclarativeContextData *parentCon ctxt->imports = component->importCache; // Nested global imports - if (componentCreationContext && start != -1) + if (componentCreationContext && start != -1) ctxt->importedScripts = componentCreationContext->importedScripts; component->importCache->addref(); @@ -850,7 +850,7 @@ void QDeclarativeComponentPrivate::beginDeferred(QDeclarativeEnginePrivate *engi QDeclarativeVME vme; vme.runDeferred(object); - if (vme.isError()) + if (vme.isError()) state->errors = vme.errors(); if (isRoot) { @@ -877,13 +877,13 @@ void QDeclarativeComponentPrivate::complete(QDeclarativeEnginePrivate *enginePri if (state->completePending) { for (int ii = 0; ii < state->bindValues.count(); ++ii) { - QDeclarativeEnginePrivate::SimpleList bv = + QDeclarativeEnginePrivate::SimpleList bv = state->bindValues.at(ii); for (int jj = 0; jj < bv.count; ++jj) { if(bv.at(jj)) { // XXX akennedy bv.at(jj)->m_mePtr = 0; - bv.at(jj)->setEnabled(true, QDeclarativePropertyPrivate::BypassInterceptor | + bv.at(jj)->setEnabled(true, QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding); } } @@ -891,7 +891,7 @@ void QDeclarativeComponentPrivate::complete(QDeclarativeEnginePrivate *enginePri } for (int ii = 0; ii < state->parserStatus.count(); ++ii) { - QDeclarativeEnginePrivate::SimpleList ps = + QDeclarativeEnginePrivate::SimpleList ps = state->parserStatus.at(ii); for (int jj = ps.count - 1; jj >= 0; --jj) { @@ -942,7 +942,7 @@ void QDeclarativeComponentPrivate::complete(QDeclarativeEnginePrivate *enginePri /*! This method provides more advanced control over component instance creation. - In general, programmers should use QDeclarativeComponent::create() to create a + In general, programmers should use QDeclarativeComponent::create() to create a component. Complete a component creation begin with QDeclarativeComponent::beginCreate(). diff --git a/src/declarative/qml/qdeclarativecontext.cpp b/src/declarative/qml/qdeclarativecontext.cpp index 3ee0e6f..dff90b4 100644 --- a/src/declarative/qml/qdeclarativecontext.cpp +++ b/src/declarative/qml/qdeclarativecontext.cpp @@ -72,10 +72,10 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() Contexts allow data to be exposed to the QML components instantiated by the QML engine. - Each QDeclarativeContext contains a set of properties, distinct from its QObject - properties, that allow data to be explicitly bound to a context by name. The - context properties are defined and updated by calling - QDeclarativeContext::setContextProperty(). The following example shows a Qt model + Each QDeclarativeContext contains a set of properties, distinct from its QObject + properties, that allow data to be explicitly bound to a context by name. The + context properties are defined and updated by calling + QDeclarativeContext::setContextProperty(). The following example shows a Qt model being bound to a context and then accessed from a QML file. \code @@ -97,8 +97,8 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() To simplify binding and maintaining larger data sets, a context object can be set on a QDeclarativeContext. All the properties of the context object are available by name in the context, as though they were all individually added through calls - to QDeclarativeContext::setContextProperty(). Changes to the property's values are - detected through the property's notify signal. Setting a context object is both + to QDeclarativeContext::setContextProperty(). Changes to the property's values are + detected through the property's notify signal. Setting a context object is both faster and easier than manually adding and maintaing context property values. The following example has the same effect as the previous one, but it uses a context @@ -121,7 +121,7 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() component.create(context); \endcode - All properties added explicitly by QDeclarativeContext::setContextProperty() take + All properties added explicitly by QDeclarativeContext::setContextProperty() take precedence over the context object's properties. \section2 The Context Hierarchy @@ -147,8 +147,8 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() context2->setContextProperty("b", 15); \endcode - While QML objects instantiated in a context are not strictly owned by that - context, their bindings are. If a context is destroyed, the property bindings of + While QML objects instantiated in a context are not strictly owned by that + context, their bindings are. If a context is destroyed, the property bindings of outstanding QML objects will stop evaluating. \warning Setting the context object or adding new context properties after an object @@ -156,7 +156,7 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate() to reevaluate). Thus whenever possible you should complete "setup" of the context before using it to create any objects. - \sa {Using QML in C++ Applications} + \sa {Using QML Bindings in C++ Applications} */ /*! \internal */ @@ -223,7 +223,7 @@ QDeclarativeContext::~QDeclarativeContext() /*! Returns whether the context is valid. - To be valid, a context must have a engine, and it's contextObject(), if any, + To be valid, a context must have a engine, and it's contextObject(), if any, must not have been deleted. */ bool QDeclarativeContext::isValid() const @@ -384,7 +384,7 @@ QVariant QDeclarativeContext::contextProperty(const QString &name) const if (data->contextObject) { QObject *obj = data->contextObject; QDeclarativePropertyCache::Data local; - QDeclarativePropertyCache::Data *property = + QDeclarativePropertyCache::Data *property = QDeclarativePropertyCache::property(data->engine, obj, name, local); if (property) value = obj->metaObject()->property(property->coreIndex).read(obj); @@ -461,7 +461,7 @@ QUrl QDeclarativeContext::baseUrl() const { Q_D(const QDeclarativeContext); const QDeclarativeContextData* data = d->data; - while (data && data->url.isEmpty()) + while (data && data->url.isEmpty()) data = data->parent; if (data) @@ -515,7 +515,7 @@ QDeclarativeContextData::QDeclarativeContextData(QDeclarativeContext *ctxt) void QDeclarativeContextData::invalidate() { - while (childContexts) + while (childContexts) childContexts->invalidate(); while (componentAttached) { @@ -570,7 +570,7 @@ void QDeclarativeContextData::clearContext() void QDeclarativeContextData::destroy() { - if (linkedContext) + if (linkedContext) linkedContext->destroy(); if (engine) invalidate(); @@ -626,9 +626,9 @@ void QDeclarativeContextData::setParent(QDeclarativeContextData *p) } } -/* -Refreshes all expressions that could possibly depend on this context. Refreshing flushes all -context-tree dependent caches in the expressions, and should occur every time the context tree +/* +Refreshes all expressions that could possibly depend on this context. Refreshing flushes all +context-tree dependent caches in the expressions, and should occur every time the context tree *structure* (not values) changes. */ void QDeclarativeContextData::refreshExpressions() @@ -656,7 +656,7 @@ void QDeclarativeContextData::addObject(QObject *o) data->outerContext = this; data->nextContextObject = contextObjects; - if (data->nextContextObject) + if (data->nextContextObject) data->nextContextObject->prevContextObject = &data->nextContextObject; data->prevContextObject = &contextObjects; contextObjects = data; @@ -664,7 +664,7 @@ void QDeclarativeContextData::addObject(QObject *o) void QDeclarativeContextData::addImportedScript(const QDeclarativeParser::Object::ScriptBlock &script) { - if (!engine) + if (!engine) return; QDeclarativeEnginePrivate *enginePriv = QDeclarativeEnginePrivate::get(engine); @@ -684,7 +684,7 @@ void QDeclarativeContextData::addImportedScript(const QDeclarativeParser::Object scriptContext->pushScope(enginePriv->contextClass->newUrlContext(url)); scriptContext->pushScope(enginePriv->globalClass->staticGlobalObject()); - + QScriptValue scope = QScriptDeclarativeClass::newStaticScopeObject(scriptEngine); scriptContext->pushScope(scope); @@ -752,7 +752,7 @@ QString QDeclarativeContextData::findObjectId(const QObject *obj) const for (int i=0; ifindId(i); - } + } if (linkedContext) return linkedContext->findObjectId(obj); @@ -761,7 +761,7 @@ QString QDeclarativeContextData::findObjectId(const QObject *obj) const QDeclarativeContext *QDeclarativeContextData::asQDeclarativeContext() { - if (!publicContext) + if (!publicContext) publicContext = new QDeclarativeContext(this); return publicContext; } diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp index dd7e5fd..8c3d3da 100644 --- a/src/declarative/util/qdeclarativeanimation.cpp +++ b/src/declarative/util/qdeclarativeanimation.cpp @@ -569,7 +569,7 @@ void QDeclarativeAbstractAnimation::timelineComplete() } \endcode - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativePauseAnimation::QDeclarativePauseAnimation(QObject *parent) : QDeclarativeAbstractAnimation(*(new QDeclarativePauseAnimationPrivate), parent) @@ -628,27 +628,27 @@ QAbstractAnimation *QDeclarativePauseAnimation::qtAnimation() \inherits PropertyAnimation \brief The ColorAnimation element animates changes in color values. - ColorAnimation is a specialized PropertyAnimation that defines an + ColorAnimation is a specialized PropertyAnimation that defines an animation to be applied when a color value changes. - Here is a ColorAnimation applied to the \c color property of a \l Rectangle - as a property value source. It animates the \c color property's value from + Here is a ColorAnimation applied to the \c color property of a \l Rectangle + as a property value source. It animates the \c color property's value from its current value to a value of "red", over 1000 milliseconds: \snippet doc/src/snippets/declarative/coloranimation.qml 0 Like any other animation element, a ColorAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. - - For convenience, when a ColorAnimation is used in a \l Transition, it will - animate any \c color properties that have been modified during the state - change. If a \l{PropertyAnimation::}{property} or - \l{PropertyAnimation::}{properties} are explicitly set for the animation, + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. + + For convenience, when a ColorAnimation is used in a \l Transition, it will + animate any \c color properties that have been modified during the state + change. If a \l{PropertyAnimation::}{property} or + \l{PropertyAnimation::}{properties} are explicitly set for the animation, then those are used instead. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeColorAnimation::QDeclarativeColorAnimation(QObject *parent) : QDeclarativePropertyAnimation(parent) @@ -682,10 +682,10 @@ QDeclarativeColorAnimation::~QDeclarativeColorAnimation() If the ColorAnimation is defined within a \l Transition or \l Behavior, this value defaults to the value defined in the starting state of the - \l Transition, or the current value of the property at the moment the + \l Transition, or the current value of the property at the moment the \l Behavior is triggered. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QColor QDeclarativeColorAnimation::from() const { @@ -708,7 +708,7 @@ void QDeclarativeColorAnimation::setFrom(const QColor &f) \l Transition, or the value of the property change that triggered the \l Behavior. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QColor QDeclarativeColorAnimation::to() const { @@ -875,7 +875,7 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation() \inherits Animation \brief The PropertyAction element allows immediate property changes during animation. - PropertyAction is used to specify an immediate property change during an + PropertyAction is used to specify an immediate property change during an animation. The property change is not animated. It is useful for setting non-animated property values during an animation. @@ -886,9 +886,9 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation() \snippet doc/src/snippets/declarative/propertyaction.qml standalone - PropertyAction is also useful for setting the exact point at which a property - change should occur during a \l Transition. For example, if PropertyChanges - was used in a \l State to rotate an item around a particular + PropertyAction is also useful for setting the exact point at which a property + change should occur during a \l Transition. For example, if PropertyChanges + was used in a \l State to rotate an item around a particular \l {Item::}{transformOrigin}, it might be implemented like this: \snippet doc/src/snippets/declarative/propertyaction.qml transition @@ -896,7 +896,7 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation() However, with this code, the \c transformOrigin is not set until \e after the animation, as a \l State is taken to define the values at the \e end of a transition. The animation would rotate at the default \c transformOrigin, - then jump to \c Item.BottomRight. To fix this, insert a PropertyChanges + then jump to \c Item.BottomRight. To fix this, insert a PropertyChanges before the RotationAnimation begins: \qml @@ -907,13 +907,13 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation() } } \endqml - + This immediately sets the \c transformOrigin property to the value defined - in the end state of the \l Transition (i.e. the value defined in the + in the end state of the \l Transition (i.e. the value defined in the PropertyChanges object) so that the rotation animation begins with the correct transform origin. - \sa {QML Animation}, QtDeclarative + \sa {QML Animation and Transitions}, QtDeclarative */ QDeclarativePropertyAction::QDeclarativePropertyAction(QObject *parent) : QDeclarativeAbstractAnimation(*(new QDeclarativePropertyActionPrivate), parent) @@ -1143,25 +1143,25 @@ void QDeclarativePropertyAction::transition(QDeclarativeStateActions &actions, \inherits PropertyAnimation \brief The NumberAnimation element animates changes in qreal-type values. - NumberAnimation is a specialized PropertyAnimation that defines an + NumberAnimation is a specialized PropertyAnimation that defines an animation to be applied when a numerical value changes. - Here is a NumberAnimation applied to the \c x property of a \l Rectangle - as a property value source. It animates the \c x value from its current + Here is a NumberAnimation applied to the \c x property of a \l Rectangle + as a property value source. It animates the \c x value from its current value to a value of 50, over 1000 milliseconds: \snippet doc/src/snippets/declarative/numberanimation.qml 0 Like any other animation element, a NumberAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. Note that NumberAnimation may not animate smoothly if there are irregular changes in the number value that it is tracking. If this is the case, use SmoothedAnimation instead. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeNumberAnimation::QDeclarativeNumberAnimation(QObject *parent) : QDeclarativePropertyAnimation(parent) @@ -1205,10 +1205,10 @@ void QDeclarativeNumberAnimation::init() If the NumberAnimation is defined within a \l Transition or \l Behavior, this value defaults to the value defined in the starting state of the - \l Transition, or the current value of the property at the moment the + \l Transition, or the current value of the property at the moment the \l Behavior is triggered. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ qreal QDeclarativeNumberAnimation::from() const @@ -1231,7 +1231,7 @@ void QDeclarativeNumberAnimation::setFrom(qreal f) \l Transition, or the value of the property change that triggered the \l Behavior. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ qreal QDeclarativeNumberAnimation::to() const { @@ -1253,15 +1253,15 @@ void QDeclarativeNumberAnimation::setTo(qreal t) \inherits PropertyAnimation \brief The Vector3dAnimation element animates changes in QVector3d values. - Vector3dAnimation is a specialized PropertyAnimation that defines an + Vector3dAnimation is a specialized PropertyAnimation that defines an animation to be applied when a Vector3d value changes. Like any other animation element, a Vector3dAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeVector3dAnimation::QDeclarativeVector3dAnimation(QObject *parent) : QDeclarativePropertyAnimation(parent) @@ -1282,10 +1282,10 @@ QDeclarativeVector3dAnimation::~QDeclarativeVector3dAnimation() If the Vector3dAnimation is defined within a \l Transition or \l Behavior, this value defaults to the value defined in the starting state of the - \l Transition, or the current value of the property at the moment the + \l Transition, or the current value of the property at the moment the \l Behavior is triggered. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QVector3D QDeclarativeVector3dAnimation::from() const { @@ -1307,7 +1307,7 @@ void QDeclarativeVector3dAnimation::setFrom(QVector3D f) \l Transition, or the value of the property change that triggered the \l Behavior. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QVector3D QDeclarativeVector3dAnimation::to() const { @@ -1330,7 +1330,7 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t) \brief The RotationAnimation element animates changes in rotation values. RotationAnimation is a specialized PropertyAnimation that gives control - over the direction of rotation during an animation. + over the direction of rotation during an animation. By default, it rotates in the direction of the numerical change; a rotation from 0 to 240 will rotate 240 degrees @@ -1346,7 +1346,7 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t) Notice the RotationAnimation did not need to set a \l target value. As a convenience, when used in a transition, RotationAnimation will rotate all properties named "rotation" or "angle". You can override this by providing - your own properties via \l {PropertyAnimation::properties}{properties} or + your own properties via \l {PropertyAnimation::properties}{properties} or \l {PropertyAnimation::property}{property}. Also, note the \l Rectangle will be rotated around its default @@ -1356,11 +1356,11 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t) PropertyAction documentation for more details. Like any other animation element, a RotationAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QVariant _q_interpolateShortestRotation(qreal &f, qreal &t, qreal progress) { @@ -1431,10 +1431,10 @@ QDeclarativeRotationAnimation::~QDeclarativeRotationAnimation() If the RotationAnimation is defined within a \l Transition or \l Behavior, this value defaults to the value defined in the starting state of the - \l Transition, or the current value of the property at the moment the + \l Transition, or the current value of the property at the moment the \l Behavior is triggered. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ qreal QDeclarativeRotationAnimation::from() const { @@ -1456,7 +1456,7 @@ void QDeclarativeRotationAnimation::setFrom(qreal f) \l Transition, or the value of the property change that triggered the \l Behavior. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ qreal QDeclarativeRotationAnimation::to() const { @@ -1582,15 +1582,15 @@ QDeclarativeListProperty QDeclarativeAnimationGro if this is the preferred behavior. Like any other animation element, a SequentialAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \note Once an animation has been grouped into a SequentialAnimation or + \note Once an animation has been grouped into a SequentialAnimation or ParallelAnimation, it cannot be individually started and stopped; the SequentialAnimation or ParallelAnimation must be started and stopped as a group. - - \sa ParallelAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example} + + \sa ParallelAnimation, {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeSequentialAnimation::QDeclarativeSequentialAnimation(QObject *parent) : @@ -1652,15 +1652,15 @@ void QDeclarativeSequentialAnimation::transition(QDeclarativeStateActions &actio \snippet doc/src/snippets/declarative/parallelanimation.qml 0 Like any other animation element, a ParallelAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \note Once an animation has been grouped into a SequentialAnimation or + \note Once an animation has been grouped into a SequentialAnimation or ParallelAnimation, it cannot be individually started and stopped; the SequentialAnimation or ParallelAnimation must be started and stopped as a group. - \sa SequentialAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa SequentialAnimation, {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeParallelAnimation::QDeclarativeParallelAnimation(QObject *parent) : QDeclarativeAnimationGroup(parent) @@ -1755,14 +1755,14 @@ void QDeclarativePropertyAnimationPrivate::convertVariant(QVariant &variant, int \inherits Animation \brief The PropertyAnimation element animates changes in property values. - PropertyAnimation provides a way to animate changes to a property's value. + PropertyAnimation provides a way to animate changes to a property's value. It can be used to define animations in a number of ways: - + \list \o In a \l Transition - For example, to animate any objects that have changed their \c x or \c y properties + For example, to animate any objects that have changed their \c x or \c y properties as a result of a state change, using an \c InOutQuad easing curve: \snippet doc/src/snippets/declarative/propertyanimation.qml transition @@ -1802,12 +1802,12 @@ void QDeclarativePropertyAnimationPrivate::convertVariant(QVariant &variant, int Depending on how the animation is used, the set of properties normally used will be different. For more information see the individual property documentation, as well - as the \l{QML Animation} introduction. + as the \l{QML Animation and Transitions} introduction. Note that PropertyAnimation inherits the abstract \l Animation element. This includes additional properties and methods for controlling the animation. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativePropertyAnimation::QDeclarativePropertyAnimation(QObject *parent) @@ -1867,10 +1867,10 @@ void QDeclarativePropertyAnimation::setDuration(int duration) If the PropertyAnimation is defined within a \l Transition or \l Behavior, this value defaults to the value defined in the starting state of the - \l Transition, or the current value of the property at the moment the + \l Transition, or the current value of the property at the moment the \l Behavior is triggered. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QVariant QDeclarativePropertyAnimation::from() const { @@ -1897,7 +1897,7 @@ void QDeclarativePropertyAnimation::setFrom(const QVariant &f) \l Transition, or the value of the property change that triggered the \l Behavior. - \sa {QML Animation} + \sa {QML Animation and Transitions} */ QVariant QDeclarativePropertyAnimation::to() const { @@ -2264,7 +2264,7 @@ void QDeclarativePropertyAnimation::setProperties(const QString &prop) As seen in the above example, properties is specified as a comma-separated string of property names to animate. - \sa exclude, {QML Animation} + \sa exclude, {QML Animation and Transitions} */ QDeclarativeListProperty QDeclarativePropertyAnimation::targets() { @@ -2447,7 +2447,7 @@ void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions ParentAnimation is used to animate a parent change for an \l Item. For example, the following ParentChange changes \c blueRect to become - a child of \c redRect when it is clicked. The inclusion of the + a child of \c redRect when it is clicked. The inclusion of the ParentAnimation, which defines a NumberAnimation to be applied during the transition, ensures the item animates smoothly as it moves to its new parent: @@ -2462,17 +2462,17 @@ void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions to animate the parent change via another item that does not have clipping enabled. Such an item can be set using the \l via property. - For convenience, when a ParentAnimation is used in a \l Transition, it will - animate any ParentChange that has occurred during the state change. + For convenience, when a ParentAnimation is used in a \l Transition, it will + animate any ParentChange that has occurred during the state change. This can be overridden by setting a specific target item using the \l target property. Like any other animation element, a ParentAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeParentAnimation::QDeclarativeParentAnimation(QObject *parent) : QDeclarativeAnimationGroup(*(new QDeclarativeParentAnimationPrivate), parent) @@ -2803,23 +2803,23 @@ QAbstractAnimation *QDeclarativeParentAnimation::qtAnimation() \inherits Animation \brief The AnchorAnimation element animates changes in anchor values. - AnchorAnimation is used to animate an anchor change. + AnchorAnimation is used to animate an anchor change. In the following snippet we animate the addition of a right anchor to a \l Rectangle: \snippet doc/src/snippets/declarative/anchoranimation.qml 0 - For convenience, when an AnchorAnimation is used in a \l Transition, it will - animate any AnchorChanges that have occurred during the state change. + For convenience, when an AnchorAnimation is used in a \l Transition, it will + animate any AnchorChanges that have occurred during the state change. This can be overridden by setting a specific target item using the \l target property. Like any other animation element, an AnchorAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa {QML Animation}, AnchorChanges + \sa {QML Animation and Transitions}, AnchorChanges */ QDeclarativeAnchorAnimation::QDeclarativeAnchorAnimation(QObject *parent) diff --git a/src/declarative/util/qdeclarativebehavior.cpp b/src/declarative/util/qdeclarativebehavior.cpp index f1b6f9a..45257de 100644 --- a/src/declarative/util/qdeclarativebehavior.cpp +++ b/src/declarative/util/qdeclarativebehavior.cpp @@ -76,7 +76,7 @@ public: \since 4.7 \brief The Behavior element allows you to specify a default animation for a property change. - A Behavior defines the default animation to be applied whenever a + A Behavior defines the default animation to be applied whenever a particular property value changes. For example, the following Behavior defines a NumberAnimation to be run @@ -93,7 +93,7 @@ public: Behavior, the \l Transition animation overrides the Behavior for that state change. - \sa {QML Animation}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative + \sa {QML Animation and Transitions}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative */ @@ -205,7 +205,7 @@ void QDeclarativeBehavior::write(const QVariant &value) d->animation->qtAnimation()->start(); d->blockRunningChanged = false; if (!after.contains(d->property)) - QDeclarativePropertyPrivate::write(d->property, value, QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding); + QDeclarativePropertyPrivate::write(d->property, value, QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding); } void QDeclarativeBehavior::setTarget(const QDeclarativeProperty &property) diff --git a/src/declarative/util/qdeclarativesmoothedanimation.cpp b/src/declarative/util/qdeclarativesmoothedanimation.cpp index ca83c52..da4c707 100644 --- a/src/declarative/util/qdeclarativesmoothedanimation.cpp +++ b/src/declarative/util/qdeclarativesmoothedanimation.cpp @@ -257,8 +257,8 @@ void QSmoothedAnimation::init() A SmoothedAnimation animates a property's value to a set target value using an ease in/out quad easing curve. When the target value changes, - the easing curves used to animate between the old and new target values - are smoothly spliced together to create a smooth movement to the new + the easing curves used to animate between the old and new target values + are smoothly spliced together to create a smooth movement to the new target value that maintains the current velocity. The follow example shows one \l Rectangle tracking the position of another @@ -288,11 +288,11 @@ void QSmoothedAnimation::init() of 0.5 will take 2000 ms to complete. Like any other animation element, a SmoothedAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa SpringAnimation, NumberAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example} + \sa SpringAnimation, NumberAnimation, {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} */ QDeclarativeSmoothedAnimation::QDeclarativeSmoothedAnimation(QObject *parent) diff --git a/src/declarative/util/qdeclarativespringanimation.cpp b/src/declarative/util/qdeclarativespringanimation.cpp index e0fc45d..ccebe82 100644 --- a/src/declarative/util/qdeclarativespringanimation.cpp +++ b/src/declarative/util/qdeclarativespringanimation.cpp @@ -246,19 +246,19 @@ void QDeclarativeSpringAnimationPrivate::updateMode() You can also limit the maximum \l velocity of the animation. - The following \l Rectangle moves to the position of the mouse using a + The following \l Rectangle moves to the position of the mouse using a SpringAnimation when the mouse is clicked. The use of the \l Behavior - on the \c x and \c y values indicates that whenever these values are + on the \c x and \c y values indicates that whenever these values are changed, a SpringAnimation should be applied. \snippet doc/src/snippets/declarative/springanimation.qml 0 Like any other animation element, a SpringAnimation can be applied in a - number of ways, including transitions, behaviors and property value - sources. The \l {QML Animation} documentation shows a variety of methods - for creating animations. + number of ways, including transitions, behaviors and property value + sources. The \l {QML Animation and Transitions} documentation shows a + variety of methods for creating animations. - \sa SmoothedAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example}, {declarative/toys/clocks}{Clocks example} + \sa SmoothedAnimation, {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}, {declarative/toys/clocks}{Clocks example} */ QDeclarativeSpringAnimation::QDeclarativeSpringAnimation(QObject *parent) @@ -299,7 +299,7 @@ void QDeclarativeSpringAnimation::setVelocity(qreal velocity) This property describes how strongly the target is pulled towards the source. The default value is 0 (that is, the spring-like motion is disabled). - + The useful value range is 0 - 5.0. When this property is set and the \l velocity value is greater than 0, @@ -394,9 +394,9 @@ void QDeclarativeSpringAnimation::setModulus(qreal modulus) \qmlproperty real SpringAnimation::mass This property holds the "mass" of the property being moved. - The value is 1.0 by default. - - A greater mass causes slower movement and a greater spring-like + The value is 1.0 by default. + + A greater mass causes slower movement and a greater spring-like motion when an item comes to rest. */ qreal QDeclarativeSpringAnimation::mass() const diff --git a/src/declarative/util/qdeclarativetransition.cpp b/src/declarative/util/qdeclarativetransition.cpp index c8bc7b3..49f0000 100644 --- a/src/declarative/util/qdeclarativetransition.cpp +++ b/src/declarative/util/qdeclarativetransition.cpp @@ -60,24 +60,24 @@ QT_BEGIN_NAMESPACE A Transition defines the animations to be applied when a \l State change occurs. For example, the following \l Rectangle has two states: the default state, and - an added "moved" state. In the "moved state, the rectangle's position changes + an added "moved" state. In the "moved state, the rectangle's position changes to (50, 50). The added Transition specifies that when the rectangle changes between the default and the "moved" state, any changes to the \c x and \c y properties should be animated, using an \c Easing.InOutQuad. \snippet doc/src/snippets/declarative/transition.qml 0 - Notice the example does not require \l{PropertyAnimation::}{to} and + Notice the example does not require \l{PropertyAnimation::}{to} and \l{PropertyAnimation::}{from} values for the NumberAnimation. As a convenience, these properties are automatically set to the values of \c x and \c y before and after the state change; the \c from values are provided by the current values of \c x and \c y, and the \c to values are provided by - the PropertyChanges object. If you wish, you can provide \l{PropertyAnimation::}{to} and + the PropertyChanges object. If you wish, you can provide \l{PropertyAnimation::}{to} and \l{PropertyAnimation::}{from} values anyway to override the default values. - By default, a Transition's animations are applied for any state change in the - parent item. The Transition \l {Transition::}{from} and \l {Transition::}{to} - values can be set to restrict the animations to only be applied when changing + By default, a Transition's animations are applied for any state change in the + parent item. The Transition \l {Transition::}{from} and \l {Transition::}{to} + values can be set to restrict the animations to only be applied when changing from one particular state to another. To define multiple transitions, specify \l Item::transitions as a list: @@ -100,7 +100,7 @@ QT_BEGIN_NAMESPACE \l Behavior, the Transition animation overrides the \l Behavior for that state change. - \sa {QML Animation}, {declarative/animation/states}{states example}, {qmlstates}{States}, {QtDeclarative} + \sa {QML Animation and Transitions}, {declarative/animation/states}{states example}, {qmlstates}{States}, {QtDeclarative} */ //ParallelAnimationWrapper allows us to do a "callback" when the animation finishes, rather than connecting @@ -119,8 +119,8 @@ class QDeclarativeTransitionPrivate : public QObjectPrivate { Q_DECLARE_PUBLIC(QDeclarativeTransition) public: - QDeclarativeTransitionPrivate() - : fromState(QLatin1String("*")), toState(QLatin1String("*")), + QDeclarativeTransitionPrivate() + : fromState(QLatin1String("*")), toState(QLatin1String("*")), reversed(false), reversible(false), endState(0) { group.trans = this; @@ -223,7 +223,7 @@ void QDeclarativeTransition::prepare(QDeclarativeStateOperation::ActionList &act If the transition was changed to this: \qml - transitions: Transition { + transitions: Transition { to: "brighter" ColorAnimation { duration: 1000 } } @@ -263,7 +263,7 @@ void QDeclarativeTransition::setFromState(const QString &f) is reversed, and it is not necessary to set this property to reverse the transition. - However, if a SequentialAnimation is used, or if the \l from or \l to + However, if a SequentialAnimation is used, or if the \l from or \l to properties have been set, this property will need to be set to reverse a transition when a state change is reverted. For example, the following transition applies a sequential animation when the mouse is pressed, @@ -271,7 +271,7 @@ void QDeclarativeTransition::setFromState(const QString &f) \snippet doc/src/snippets/declarative/transition-reversible.qml 0 - If the transition did not set the \c to and \c reversible values, then + If the transition did not set the \c to and \c reversible values, then on the mouse release, the transition would play the PropertyAnimation before the ColorAnimation instead of reversing the sequence. */ diff --git a/src/declarative/util/qdeclarativeview.cpp b/src/declarative/util/qdeclarativeview.cpp index c22f200..e1cf6d7 100644 --- a/src/declarative/util/qdeclarativeview.cpp +++ b/src/declarative/util/qdeclarativeview.cpp @@ -195,9 +195,9 @@ void QDeclarativeViewPrivate::itemGeometryChanged(QDeclarativeItem *resizeItem, \since 4.7 \brief The QDeclarativeView class provides a widget for displaying a Qt Declarative user interface. - QDeclarativeItem objects can be placed on a standard QGraphicsScene and - displayed with QGraphicsView. QDeclarativeView is a QGraphicsView subclass - provided as a convenience for displaying QML files, and connecting between + QDeclarativeItem objects can be placed on a standard QGraphicsScene and + displayed with QGraphicsView. QDeclarativeView is a QGraphicsView subclass + provided as a convenience for displaying QML files, and connecting between QML and C++ Qt objects. QDeclarativeView provides: @@ -234,7 +234,7 @@ void QDeclarativeViewPrivate::itemGeometryChanged(QDeclarativeItem *resizeItem, you can connect to the statusChanged() signal and monitor for QDeclarativeView::Error. The errors are available via QDeclarativeView::errors(). - \sa {Integrating QML with existing Qt UI code}, {Using QML in C++ Applications} + \sa {Integrating QML Code with Existing Qt UI Code}, {Using QML Bindings in C++ Applications} */ @@ -248,7 +248,7 @@ void QDeclarativeViewPrivate::itemGeometryChanged(QDeclarativeItem *resizeItem, /*! \fn QDeclarativeView::QDeclarativeView(QWidget *parent) - + Constructs a QDeclarativeView with the given \a parent. */ QDeclarativeView::QDeclarativeView(QWidget *parent) @@ -695,7 +695,7 @@ void QDeclarativeView::paintEvent(QPaintEvent *event) QDeclarativeDebugTrace::startRange(QDeclarativeDebugTrace::Painting); int time = 0; - if (frameRateDebug()) + if (frameRateDebug()) time = d->frameTimer.restart(); #ifdef Q_WS_MAC -- cgit v0.12 From c196394ce305a7343cc5f51f166b76746f9d9903 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Wed, 5 Jan 2011 11:47:12 +0100 Subject: Fixed merge conflict --- doc/src/declarative/anchor-layout.qdoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc index 70381de..11acbad 100644 --- a/doc/src/declarative/anchor-layout.qdoc +++ b/doc/src/declarative/anchor-layout.qdoc @@ -28,14 +28,10 @@ /*! \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 -- cgit v0.12 From 6374bc9790310b85299aab251d817aa2e5360d55 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 6 Jan 2011 15:17:49 +0100 Subject: Re-organized the elements page. Fixed misplaced elements. Task-number: QTBUG-16071 --- doc/src/declarative/elements.qdoc | 269 ++++++++++++++++++++++---------------- 1 file changed, 156 insertions(+), 113 deletions(-) diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index eaa6a82..7b1ca94 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -29,118 +29,161 @@ \page qdeclarativeelements.html \target elements \title QML Elements - \brief A dictionary of standard QML elements. - - This is a dictionary of all standard QML elements made available - in the Qt Declarative module. - - To see the QML elements listed by functional area, see the - \l{Groups Of Related QML Elements} page. - - \table - \header \o {2,1} \bold {Basic Visual Items} - \row \o \l {Item} \o Basic item element inherited by all visual items in QML - \row \o \l {Rectangle} \o Basic visual rectangle element - \row \o \l {Gradient} \o Defines a gradient between two or more colors - \row \o \l {GradientStop} \o Defines a color used in a \l {Gradient} - \row \o \l {Image} \o Allows the use of bitmaps to a scene - \row \o \l {BorderImage} (Item-specific) \o Defines an image as a border - \row \o \l {AnimatedImage} \o For playing animations stored as a series of frames - \row \o \l {Text} \o Allows the use of formatted text in a scene - \row \o \l {TextInput} \o Displays an editable line of text - \row \o \l {IntValidator} \o Validator for integer values - \row \o \l {DoubleValidator} \o Validator for non-integer values - \row \o \l {RegExpValidator} \o Validator for string regular expressions - \row \o \l {TextEdit} \o Displays multiple lines of editable formatted text - - \header \o {2,1} \bold {Basic Interaction Items} - \row \o \l {MouseArea} \o Handles mouse interactions - \row \o \l {FocusScope} \o For keyboard focus handling - \row \o \l {Flickable} \o Provides a surface that can be "flicked" - \row \o \l {Flipable} \o Provides a surface that produces flipping effects - \row \o \l {GestureArea} (experimental) \o Enables simple gesture handling - - \header \o {2,1} \bold {States} - \row \o \l {State} \o Defines sets of configurations of objects and properties - \row \o \l {PropertyChanges} \o Describes property changes within a state - \row \o \l {StateGroup} \o Contains a set of states and state transitions - \row \o \l {StateChangeScript} \o Allows script binding in a state - \row \o \l {ParentChange} (Item-specific) \o Re-parent an Item in a state change - \row \o \l {AnchorChanges} \o Change the anchors of an item in a state - - \header \o {2,1} \bold {Animation and Transitions} - \row \o \l {Behavior} \o Specifies a default animation for property changes - \row \o \l {SequentialAnimation} \o Runs animations sequentially - \row \o \l {ParallelAnimation} \o Runs animations in parallel - \row \o \l {PropertyAnimation} \o Animates property changes - \row \o \l {NumberAnimation} \o Animates properties of type qreal - \row \o \l {Vector3dAnimation} \o Animates properties of type QVector3d - \row \o \l {ColorAnimation} \o Animates color changes - \row \o \l {RotationAnimation} \o Animates rotations - \row \o \l {ParentAnimation} \o Animates parent changes - \row \o \l {AnchorAnimation} \o Animates anchor changes - \row \o \l {PauseAnimation} \o Pauses an animation - \row \o \l {SmoothedAnimation} \o Allows a property to smoothly track a value - \row \o \l {SpringAnimation} \o Allows a property to track a value in a spring-like motion - \row \o \l {PropertyAction} \o Sets immediate property changes during animation - \row \o \l {ScriptAction} \o Runs scripts during an animation - \row \o \l {Transition} \o Animates transitions during state changes - - \header \o {2,1} \bold {Working with Data} - \row \o \l {Binding} \o Binds any value to any property - \row \o \l {ListModel} \o Defines a list of data - \row \o \l {ListElement} \o Defines a data item in a \l {ListModel} - \row \o \l {VisualItemModel} \o Contains items that already defines its own visual delegate - \row \o \l {VisualDataModel} \o Encapsulates a model and a delegate - \row \o \l {Package} \o Collection that enables sharing of items within different views - \row \o \l {XmlListModel} \o Specifies a model using XPath expressions - \row \o \l {XmlRole} \o Specifies a role for an \l {XmlListModel} - - \header \o {2,1} \bold {Views} - \row \o \l {ListView} \o Provides a list visualization of a model - \row \o \l {GridView} \o Provides a grid visualization of a model - \row \o \l {PathView} \o Visualizes a model's contents along a path - \row \o \l {Path} \o Defines a path used by \l {PathView} - \row \o \l {PathLine} \o Defines a line in \l {Path} - \row \o \l {PathQuad} \o Defines a quadratic Bezier curve in a \l {Path} - \row \o \l {PathCubic} \o Defines a cubic Bezier curve in a \l {Path} - \row \o \l {PathAttribute} \o Allows the setting of attributes along a \l {Path} - \row \o \l {PathPercent} \o Modifies the item distribution along a \l {Path} - \row \o \l {WebView} \o Allows the addition of web content to a canvas - - \header \o {2,1} \bold {Positioners} - \row \o \l {Column} \o Arranges its children vertically - \row \o \l {Row} \o Arranges its children horizontally - \row \o \l {Grid} \o Positions its children in a grid - \row \o \l {Flow} \o Positions its children with wrapping support - - \header \o {2,1} \bold {Utility} - \row \o \l {Connections} \o Explicitly connects signals and signal handlers - \row \o \l {Component} \o Encapsulate QML items as a component - \row \o \l {Timer} \o Provides timed triggers - \row \o \l {QML:QtObject} {QtObject} \o Basic element containing only the objectName property - \row \o \l {QML:Qt} {Qt} \o The QML global Qt object provides useful enums and functions from Qt. - \row \o \l {WorkerScript} \o Enables the use of threads in QML - \row \o \l {Loader} \o Controls the loading of items or components - \row \o \l {Repeater} \o Uses a model to create multiples of components - \row \o \l {SystemPalette} \o Provides access to the Qt palettes - \row \o \l {FontLoader} \o Loads fonts by name or URL - \row \o \l {LayoutItem} \o Allows declarative UI elements inside Qt's Graphics View layouts - - \header \o {2,1} \bold {Transforms} - \row \o \l {Scale} \o Assigns item scaling behaviors - \row \o \l {Rotation} \o Assigns item rotation behaviors - \row \o \l {Translate} \o Assigns item translation behaviors - - \header \o {2,1} \bold {Effects} - \row \o \l {Particles} (experimental) \o Generates and animates particles - \row \o \l {ParticleMotionLinear} \o Adds linear motion behavior to \l {Particles} - \row \o \l {ParticleMotionGravity} \o Adds gravitational motion to \l {Particles} - \row \o \l {ParticleMotionWander} \o Adds varied motions to \l {Particles} - \endtable - - - + \brief A listing of standard QML elements. + +These are the functionally grouped lists of QML elements. + +Elements are declared with the their name and two curly braces. Elements may +be nested in elements, thereby creating a parent-child relationship between the +two elements. + +To see the QML elements listed by functional area, see the +\l{Groups Of Related QML Elements} page. + +\section1 Basic QML Elements +\list +\o \l {Item} - Basic item element inherited by QML elements +\o \l {Component} - Encapsulates QML elements during importing +\o \l {QML:QtObject} {QtObject} - Basic element containing only the objectName property +\endlist + +\section1 Graphical Elements +\list +\o \l {Rectangle} - A rectangle element +\o \l {Image} - For incorporating bitmaps into a scene +\o \l {BorderImage} - Allows the use of images as borders +\o \l {AnimatedImage} - For playing animations stored in a series of frames +\o \l {Gradient} - For defining a color gradient +\o \l {GradientStop} - Used to define a color within a \l {Gradient} +\o \l {SystemPalette} - Provides access to the Qt palettes +\endlist + +\section1 Text Handling Elements +\list +\o \l {Text} - For inserting formatted text into a scene +\o \l {TextInput} - Captures user key input +\o \l {TextEdit} - Displays multiple lines of editable formatted text +\o \l {IntValidator} - Validates values as integers +\o \l {DoubleValidator} - Validates real values +\o \l {RegExpValidator} - Validator for string regular expressions +\o \l {FontLoader} - Loads fonts by name or URL +\endlist + +\section1 Mouse and Interaction Area Elements +\list +\o \l {MouseArea} - Sets up an area for mouse interaction +\o \l {FocusScope} - Element that mediate keyboard focus changes +\o \l {Flickable} - Provides a surface that can be "flicked" +\o \l {Flipable} - Provides a surface that produces "flipping" effects +\o \l {GestureArea} - Enables simple gesture handling +\endlist + +\section1 Positioners and Repeater Elements +\list +\o \l {Column} - Arranges its children vertically +\o \l {Row} - Arranges its children horizontally +\o \l {Grid} - Positions its children in a grid +\o \l {Flow} - Positions its children with wrapping support +\o \l {Repeater} - Uses a model to create multiples of components +\endlist + +\section1 Transformation Elements +\list +\o \l {Scale} - Assigns item scaling behaviors +\o \l {Rotation} - Assigns item rotation behaviors +\o \l {Translate} - Assigns item translation behaviors +\endlist + +\section1 States +\list +\o \l {State} - Defines sets of configurations of objects and properties +\o \l {PropertyChanges} - Describes property changes within a state +\o \l {StateGroup} - Contains a set of states and state transitions +\o \l {StateChangeScript} - Allows script binding in a state +\o \l {ParentChange} - Re-parent an Item in a state change +\o \l {AnchorChanges} - Change the anchors of an item in a state +\endlist + +\section1 Animation and Transitions +\list +\o \l {Transition} - Animates transitions during state changes +\o \l {SequentialAnimation} - Runs animations sequentially +\o \l {ParallelAnimation} - Runs animations in parallel +\o \l {Behavior} - Specifies a default animation for property changes +\o \l {PropertyAction} - Sets immediate property changes during animation +\o \l {PauseAnimation} - Introduces a pause in an animation +\o \l {SmoothedAnimation} - Allows a property to smoothly track a value +\o \l {SpringAnimation} - Allows a property to track a value in a spring-like motion +\o \l {ScriptAction} - Runs scripts during an animation +\endlist + +Elements that animate properties based on data types +\list +\o \l {PropertyAnimation} - Animates property changes +\o \l {NumberAnimation} - Animates properties of type qreal +\o \l {Vector3dAnimation} - Animates properties of type QVector3d +\o \l {ColorAnimation} - Animates color changes +\o \l {RotationAnimation} - Animates rotations +\o \l {ParentAnimation} - Animates parent changes +\o \l {AnchorAnimation} - Animates anchor changes +\endlist + +\section1 Models and Data Handling +\list +\o \l {ListModel} - Defines a list of data +\o \l {ListElement} - Defines a data item in a \l {ListModel} +\o \l {VisualItemModel} - Contains items that already defines its own visual delegate +\o \l {VisualDataModel} - Encapsulates a model and a delegate +\o \l {XmlListModel} - Specifies a model using XPath expressions +\o \l {XmlRole} - Specifies a role for an \l {XmlListModel} +\o \l {Binding} - Binds any value to any property +\o \l {Package} - Collection that enables sharing of items within different views +\endlist + +\section1 Views +\list +\o \l {ListView} - Provides a list visualization of a model +\o \l {GridView} - Provides a grid visualization of a model +\o \l {WebView} - Allows the addition of web content to a canvas +\o \l {PathView} - Visualizes a model's contents along a path. See \l {Path Definition}{Path Elements} for more information. +\endlist + +\section1 Add-On Elements +These elements are not included in QML by default. Their respective QML bindings +should first be obtained. +\list +\o \l{QtWebKit QML Module} +\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} +\endlist + +\section1 Path Definition +\list +\o \l {Path} - Defines a path used by \l {PathView} +\o \l {PathLine} - Defines a line in \l {Path} +\o \l {PathQuad} - Defines a quadratic Bezier curve in a \l {Path} +\o \l {PathCubic} - Defines a cubic Bezier curve in a \l {Path} +\o \l {PathAttribute} - Allows the setting of attributes along a \l {Path} +\o \l {PathPercent} - Modifies the item distribution along a \l {Path} +\endlist + +\section1 Utility +\list +\o \l {Connections} - Explicitly connects signals and signal handlers +\o \l {Timer} - Provides timed triggers +\o \l {QML:Qt} {Qt} - The QML global Qt object provides useful enums and functions from Qt. +\o \l {WorkerScript} - Enables the use of threads in QML +\o \l {Loader} - Controls the loading of items or components +\o \l {LayoutItem} - Allows declarative UI elements inside Qt's Graphics View layouts +\endlist + +\section1 Graphical Effects +\list +\o \l {Particles} - Generates and animates particles +\o \l {ParticleMotionLinear} - Adds linear motion behavior to \l {Particles} +\o \l {ParticleMotionGravity} - Adds gravitational motion to \l {Particles} +\o \l {ParticleMotionWander} - Adds varied motions to \l {Particles} +\endlist + */ @@ -148,7 +191,7 @@ \group qml-groups \title Groups Of Related QML Elements - \brief If you know what kind of QML element you want (Basic Visual, + \brief If you know what kind of QML element you want (Basic Visual, Interaction, Animation, etc), look here. This is a list of functional groups of QML elements. -- cgit v0.12 From e4d86f23f4c1b9a5f960c0cb912256375e1c771d Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Fri, 7 Jan 2011 15:00:39 +0100 Subject: Added content and snippet code to Basic Elements overview page. Task-number: QTBUG-16071 --- doc/src/declarative/basicelements.qdoc | 97 ++++++++++++++++++++-- .../declarative/focus/focusscopewidget.qml | 2 + .../declarative/focus/myfocusscopewidget.qml | 4 +- doc/src/snippets/declarative/focus/mywidget.qml | 2 +- 4 files changed, 97 insertions(+), 8 deletions(-) diff --git a/doc/src/declarative/basicelements.qdoc b/doc/src/declarative/basicelements.qdoc index d0c16b6..4253e4c 100644 --- a/doc/src/declarative/basicelements.qdoc +++ b/doc/src/declarative/basicelements.qdoc @@ -26,12 +26,97 @@ ****************************************************************************/ /*! - \page qmlbasicelements.html - \ingroup qml-features - \contentspage QML Features - \previouspage {QML Basic Types}{Data Types} - \nextpage {Using QML Positioner and Repeater Items}{Component Layouts} +\page qmlbasicelements.html +\ingroup qml-features +\contentspage QML Features +\previouspage QML Syntax +\nextpage {QML Basic Types}{Data Types} - \title QML Basic Elements +\title QML Basic Elements +QML's basic elements allow the easy inclusion of objects into the +scene. + +\section1 Basic Elements +This is a list of some of the elements readily available for users. +\list +\o \l {Item} +\o \l {Rectangle} +\o \l {Image} +\o \l {Text} +\o \l {TextInput} +\o \l {TextEdit} +\o \l {FocusScope} +\o \l {Component} +\o \l {MouseArea} +\endlist + +For a complete list of QML elements, please visit the \l {QML Elements} page. + +\section1 Properties and Qt Declarative Module + +When using QML elements, keep in mind that elements may possess properties that +other elements also possess. This is because QML and its underlying engine is +implemented in C++ using Qt. More importantly, the chain of property inheritance +is directly due to QML's use of the \l {Qt Declarative Module} and Qt's +\l {Meta-Object System}{meta-object} and \l {The Property System}{property} systems. For example, visual elements that have C++ implementation are sublcasses of +\l {QDeclarativeItem}. As a result, elements such as \l {Rectangle} and +\l {Text} elements inherit properties such as \c clip and \c smooth. + +\section1 Item Element + +Many QML elements inherit \l Item properties. \c Item possesses important properties +such as \c focus, \c children, and dimension properties such as \c width and +\c height. Although \c Item has physical properties, it is not a visual element. +Using \c Item as the top-level QML element (as the screen) will not produce a +visual result, use the \l {Rectangle} element instead. Use the \c Item to create +opacity effects, such as when creating an invisible container to hold other +components. + +\section1 Rectangle Element + +The \l Rectangle element is the basic visual element, for displaying different +types of items onto the screen. The \c Rectangle is customizable and utilizes +other elements such as \l Gradient and \l BorderImage for displaying advanced +customized graphics. + +\section1 Image Element + +To insert an image into a QML scene, merely declare an \l Image element. The +\c Image element can load images in formats supported by Qt. + +\section1 Text Elements + +The \l Text and \l TextEdit elements display formatted text onto the screen. +\c TextEdit features multi-line editing while the \l TextInput element is for +single line text input. + +\section1 Using Elements as the Top-Level Component + +For creating components (or displaying a simple scene), there are different +elements that could be used as the top-level component. To display a simple scene, +a \l Rectangle as the top-level component may suffice. \l Rectangle, +\l FocusScope, \l Component, \l {QML:QtObject} {QtObject}, \l Item, are some of +the commonly used elements as the top-level component. + +When importing components, the top-level component is important because the +top-level component's properties are the only properties exposed to the parent. + +For example, a \c Button component may be implemented using different elements as +its top-level component. When this component is loaded into another QML scene, +the component will retain the top-level component's properties. If a non-visual +component is the top-level component, the visual properties should be aliased to +the top-level to display the component properly. + +A component implemented using a \c Rectangle as the top-level component: +\snippet doc/src/snippets/declarative/focus/mywidget.qml document + +A component that uses a \c FocusScope as the top-level component: +\snippet doc/src/snippets/declarative/focus/myfocusscopewidget.qml document +Note that the visual properties need to be passed to the parent. The +\l {Keyboard Focus in QML}{focus} article provides more details about the +\c FocusScope element. + +For more information on how to build upon QML elements, see the +\l{Importing Reusable Components} document. */ diff --git a/doc/src/snippets/declarative/focus/focusscopewidget.qml b/doc/src/snippets/declarative/focus/focusscopewidget.qml index 48e5750..3e35ec5 100644 --- a/doc/src/snippets/declarative/focus/focusscopewidget.qml +++ b/doc/src/snippets/declarative/focus/focusscopewidget.qml @@ -37,6 +37,7 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ +//! [document] import QtQuick 1.0 //! [focusscope window] @@ -59,3 +60,4 @@ Rectangle { } //! [focusscope window] +//! [document] diff --git a/doc/src/snippets/declarative/focus/myfocusscopewidget.qml b/doc/src/snippets/declarative/focus/myfocusscopewidget.qml index 231ae3a..cec4462 100644 --- a/doc/src/snippets/declarative/focus/myfocusscopewidget.qml +++ b/doc/src/snippets/declarative/focus/myfocusscopewidget.qml @@ -37,12 +37,13 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ +//! [document] import QtQuick 1.0 //! [widget in focusscope] FocusScope { - //FocusScope needs to bind to visual properties of the children + //FocusScope needs to bind to visual properties of the Rectangle property alias color: rectangle.color x: rectangle.x; y: rectangle.y width: rectangle.width; height: rectangle.height @@ -64,3 +65,4 @@ FocusScope { } } //! [widget in focusscope] +//! [document] diff --git a/doc/src/snippets/declarative/focus/mywidget.qml b/doc/src/snippets/declarative/focus/mywidget.qml index bea723d..e0b22a1 100644 --- a/doc/src/snippets/declarative/focus/mywidget.qml +++ b/doc/src/snippets/declarative/focus/mywidget.qml @@ -37,10 +37,10 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ +//! [document] import QtQuick 1.0 //! [mywidget] -//MyWidget code Rectangle { id: widget color: "lightsteelblue"; width: 175; height: 25; radius: 10; smooth: true -- cgit v0.12 From b5d34f3daafc843c9f9cb63cf8e2733900f0be69 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 13 Jan 2011 15:53:57 +0100 Subject: Rewrote QML Property Binding document. Added snippet code. Task-number: QTBUG-16071 --- doc/src/declarative/propertybinding.qdoc | 502 ++++++++++++++-------------- doc/src/snippets/declarative/Button.qml | 67 ++++ doc/src/snippets/declarative/properties.qml | 315 +++++++++++++++++ 3 files changed, 630 insertions(+), 254 deletions(-) create mode 100644 doc/src/snippets/declarative/Button.qml create mode 100644 doc/src/snippets/declarative/properties.qml diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 6f7c40a..7328b4c 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -29,296 +29,290 @@ \page propertybinding.html \ingroup qml-features \contentspage QML Features -\previouspage QML Syntax -\nextpage {QML Basic Types}{Data Types} +\previouspage {QML Basic Types}{Data Types} +\nextpage {Using QML Positioner and Repeater Items}{Component Layouts} \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. +A property is a value of a QML component that can be read and modified by other objects. +In QML, properties serve many purpose. Their main function is to bind to values. +Values may be a \l{QML Basic Types}{basic type}, or other QML elements. -\section1 Property types +Elements already possess useful properties but, to create custom properties, +precede the property name with the keyword \c property. -QML supports properties of many types (see \l{QML Basic Types}). The basic types -include int, real, bool, string, color, and lists. +\snippet doc/src/snippets/declarative/properties.qml parent begin +\snippet doc/src/snippets/declarative/properties.qml inherited properties +\snippet doc/src/snippets/declarative/properties.qml custom properties +\snippet doc/src/snippets/declarative/properties.qml parent end -\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: +QML property rules coincide with many of JavaScript's property rules, for example, +properti names must begin with a lowercase letter. +\l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property +names. -\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 +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 a JavaScript -expression. The following QML code uses two property bindings to connect the size of the rectangle -to that of \c otherItem. - -\code -Rectangle { - width: otherItem.width - height: otherItem.height -} -\endcode +Property bindings are created in QML using the colon "\c {:}" before the value: +\snippet doc/src/snippets/declarative/properties.qml property binding +The property binding causes the width of the \c Rectangle to update whenever the +\c {parent}'s width changes. 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 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: - -\code -Rectangle { - function calculateMyHeight() { - return Math.max(otherItem.height, thirdItem.height); - } - - anchors.centerIn: parent - width: Math.min(otherItem.width, 10) - height: calculateMyHeight() - color: { if (width > 10) "blue"; else "red" } -} -\endcode +used as a property binding. Bindings can access object properties, make function calls and even +use built-in JavaScript objects such as \c {Date} and \c {Math}. +\snippet doc/src/snippets/declarative/properties.qml JavaScript sample While syntactically bindings can be of arbitrary complexity, if a binding starts to become overly complex - such as involving multiple lines, or imperative loops - it may be better to refactor the component entirely, or at least factor the binding out into a separate function. -\section1 Changing Bindings +\section1 Property Assignment versus Property Binding -The \l PropertyChanges element can be used within a state change to modify the bindings on -properties. +When working with both QML and JavaScript, it is important to differentiate between +QML property binding and JavaScript value assignment. In QML, a property +binding is created using the colon "\c {:}". +\snippet doc/src/snippets/declarative/properties.qml property binding +The property binding causes the width of the \c Rectangle to update whenever the +\c {parent}'s width changes. -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. +Assigning a property value (using the equals sign "\c {=}") does not create a +property binding. +\snippet doc/src/snippets/declarative/properties.qml property assignment -\code -Rectangle { - id: rectangle - width: otherItem.width - height: otherItem.height - - states: State { - name: "square" - PropertyChanges { - target: rectangle - width: otherItem.height - } - } -} -\endcode +Instead of creating a property binding, the assignment simply sets the \c Rectangle +\c width value to a number when the \c Component.onCompleted code is invoked. +Assigning a value to a property that is already bound will remove the previous binding. +A property can only have one value at a time (a list of property is one value), +and if any code explicitly re-sets this value, the property binding is removed. -\section1 Effects of Property Assignment in JavaScript +There is no way to create a property binding directly from imperative JavaScript code, +although it is possible to use the \l {Using the Binding Element}{Binding} element. -Assigning a property value from JavaScript does \e not create a property binding. -For example: +\section1 Types of Properties +Properties may bind to different types, but they are are \e type-safe. That is, +properties only allow you to assign a value that matches the property type. For +example, if a property is a real, and if you try to assign a string to it you +will get an error. +\qml + property real volume: "four" //generates an error +\endqml -\code -Rectangle { +Certain properties bind to more complex types such as other elements and objects. + +\section2 Basic Property Types + +Basic types such as \l int, \l real, and other Qt structures may be bound to +properties. For a list of types, visit the \l {QML Basic Types} document. + +\keyword qml-id-property +\section2 The \c id Property + +Each QML object may 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. QML objects may then access an object using the \c id +property. +\snippet doc/src/snippets/declarative/properties.qml id property +A component may readily access its parent's properties by using the \c parent +property. + +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}. + +\section2 Elements and Objects as Property Values + +Many properties bind to objects. For example, the \l Item element has a +\c states property that can bind to \l State elements. This type of property +binding allows elements to carry additional non-children elements. \c Item's +\c transitions property behaves in a similar way; it can bind to \l Transition +elements. + +Care must be taken when referring to the parent of an object property binding. +Elements and components that are bound to properties are not necessarily set +as children of the properties' component. + +\snippet doc/src/snippets/declarative/properties.qml object binding +The code snippet has a \l Gradient element that attempts to print its parent's +\c width value. However, the \c Gradient element is bound to the \c gradient +property, not the \c children property of the \c Rectangle. As a result, the +\c Gradient does not have the \c Rectangle as its parent. Printing the value +of \c{parent.width} generates an error. Printing the \c Rectangle object's +first child's \c name will print \c {childrectangle} because the second +\c Rectangle is bound to the \c children property. + +For more information about the \c children property, please read the +\l {Default Properties} section. + +\keyword attached-properties +\section2 Attached Properties + +Certain objects provide additional properties by \e attaching properties to other +objects. For example, the \l Keys element have properties that can \e attach to other QML +objects to provide keyboard handling. + +\snippet doc/src/snippets/declarative/properties.qml list attached property +The element \l ListView provides the delegate, \c listdelegate, the property +\c isCurrentItem as an attached property. The \c ListView.isCurrentItem +\e{attached property} provides highlight information to the delegate. +Effectively, the \l ListView element attaches the \c ListView.isCurrentItem +property to each delegate it creates. + +\keyword attached-signalhandlers +\section2 Attached Signal Handlers + +\e {Attached signal handlers} are similar +to \l{Attached Properties}{attached properties} in that they attach to objects +to provide additional functionality to objects. Two prominent elements, +\l Component and \l Keys element provide +\l{QML Signal and Handler Event System}{signal handlers} as attached signal +handlers. +\snippet doc/src/snippets/declarative/properties.qml attached signal handler + +Read the \l{QML Signal and Handler Event System} and the \l{Keyboard Focus in QML} +articles for more information. + +\section2 List properties + +Some properties may accept a binding to a list property, where more than one +component can bind to the property. List properties allow multiple +\l {State}{States}, \l {Gradient}{Gradients}, and other components to bind to a +single property. +\snippet doc/src/snippets/declarative/properties.qml list property +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 may omit the square brackets. +\snippet doc/src/snippets/declarative/properties.qml single property - Component.onCompleted: { - width = otherItem.width; - } -} -\endcode +To access the list, use the \c index property. +\snippet doc/src/snippets/declarative/properties.qml print list property +The snippet code simply prints the name of the first state, \c FETCH. -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 -\l {Property Assignment vs Property Binding} for more details. + See the \l{list}{list type} documentation +for more details about list properties and their available operations. -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. +\section2 Grouped Properties +\target dot properties -\code -Rectangle { - width: otherItem.width +In some cases properties form a logical group and use either the \e dot notation +or \e group notation. - Component.onCompleted: { - width = 13; - } -} -\endcode +Grouped properties may be written both ways: +\snippet doc/src/snippets/declarative/properties.qml grouped properties -There is no way to create a property binding directly from imperative JavaScript code, -although it is possible to set up a \l Binding object (shown below). +In the element documentation grouped properties are shown using the dot notation. +\section2 Property Aliases -\section1 Binding Element +Unlike a property definition, which allocates a new, unique storage space for +the property, a property alias connects the newly declared property, called the +\e{aliasing property} as a direct reference to an existing property, the +\e{aliased property}. Read or write operations on the aliasing property results +in a read or write operations on the aliased property, respectively. -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 -\l Binding element. +A property alias declaration is similar to an ordinary property definition: +\code + [default] property alias : +\endcode + +As the aliasing property has the same type as the aliased property, an explicit +type is omitted, and the special \c alias keyword is before the property name. +Instead of a default value, a property alias has a compulsory alias reference. +Accessing the aliasing property is similar to accessing a regular property. In +addition, the optional \c default keyword indicates that the aliasing property +is a \l{Default Properties}{default property}. + +\snippet doc/src/snippets/declarative/Button.qml property alias +When importing the component as a \c Button, the \c buttonlabel is directly +accessible through the \c label property. +\snippet doc/src/snippets/declarative/properties.qml alias usage +In addition, the \c id property may also be aliased and referred outside the +component. +\snippet doc/src/snippets/declarative/Button.qml parent begin +\snippet doc/src/snippets/declarative/Button.qml id alias +\snippet doc/src/snippets/declarative/Button.qml parent end +The \c imagebutton component has the ability to modify the child \l Image object + and its properties. +\snippet doc/src/snippets/declarative/properties.qml image alias + +Using aliases, properties may be exposed to the +\l{qml-top-level-component}{top level component}. Exposing properties to the +top-level component allows components to have interfaces similar to Qt widgets. + +\section3 Considerations for property aliases + +Aliases are only activated once the component +\l{Component::onCompleted}{completes} its initialization. An error is generated +when an uninitialized alias is referenced. Likewise, aliasing an aliasing +property will also result in an error. + +\snippet doc/src/snippets/declarative/properties.qml alias complete + +When importing the component, however, aliasing properties appear as regular Qt +properties and consequently can be used in alias references. + +It is possible for an aliasing property to have the same name as an existing +property, effectively overwriting the 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/properties.qml alias overwrite + +Any object 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 \c coloredrectangle can correctly set its \c color +property and refer to the actual defined property rather than the alias. + +The \l{declarative/ui-components/tabwidget}{TabWidget} example uses +aliases to reassign children to the \l ListView, creating a tab effect. + +\keyword default-properties +\section2 Default Properties + +When imported, QML components will bind declared children to their designated +\e{default properties}. The optional \c default attribute specifies a property +as the \e {default property}. For example, the State element's default property +is its \l{State::changes}{changes} property. \l PropertyChanges elements +may simply be placed as the \c{State}'s children and they will be bound to the +\c changes property. +\snippet doc/src/snippets/declarative/properties.qml state default + +Similarly, the \l Item element's default property is its +\l{Item::data}{data} property. The \c data property manages Item's +\c children and \c resources properties. This way, different data types may be +placed as direct children of the \c Item. +\snippet doc/src/snippets/declarative/properties.qml default property + +Reassigning a default property is useful when a component is reused. For +example, the \l{declarative/ui-components/tabwidget}{TabWidget} example uses +the \c default attribute to reassign children to the \l ListView, creating +a tab effect. + +\section1 Using the Binding Element + +In some advanced cases, it may be necessary to create bindings explicitly with +the\l Binding element. + +For example, to bind a property exposed from C++ (\c system.brightness) to a +value written in QML (\c slider.value), you could use the \l Binding element as +follows: +\snippet doc/src/snippets/declarative/properties.qml binding element + +\section1 Changing Property Values in States + +The \l PropertyChanges element is for setting property bindings within a +\l State element to set a property binding. + +\snippet doc/src/snippets/declarative/properties.qml PropertyChanges element +The rectangle's \c color property will bind to the \c warning component's +\c color property when its \c state is set to the \c WARNING state. -For example, to bind a property exposed from C++ (\c system.brightness) to a value -coming from QML (\c slider.value), you could use the Binding element as follows: -\qml -Binding { - target: system - property: "brightness" - value: slider.value -} -\endqml */ diff --git a/doc/src/snippets/declarative/Button.qml b/doc/src/snippets/declarative/Button.qml new file mode 100644 index 0000000..214dfea --- /dev/null +++ b/doc/src/snippets/declarative/Button.qml @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import QtQuick 1.0 + +//! [parent begin] +Rectangle { +//! [parent begin] + +//! [property alias] +property alias buttonLabel: label.text +Text { + id: label + text: "empty label" +} + //! [property alias] + +//! [id alias] + property alias buttonImage: image + + Image {id: image} +//! [id alias] +//! [parent end] +} +//! [parent end] + +//! [document] + + diff --git a/doc/src/snippets/declarative/properties.qml b/doc/src/snippets/declarative/properties.qml new file mode 100644 index 0000000..330d1cf --- /dev/null +++ b/doc/src/snippets/declarative/properties.qml @@ -0,0 +1,315 @@ +/**************************************************************************** +** +** 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import QtQuick 1.0 + +//! [parent begin] +Rectangle { +//! [parent begin] + + //! [inherited properties] + width: 320; height: 240 + color: "lightblue" + focus: true + //! [inherited properties] + + //! [custom properties] + property int counter + property real area: 100.45 + //! [custom properties] + + //! [property types] + property int number + property real volume: 100.45 + property date today: "2011-01-01" + property color background: "yellow" + //! [property types] + + +//! [grouped properties] +Text { + //dot notation + font.pixelSize: 12 + font.bold: true +} + +Text { + //group notation + font {pixelSize: 12; bold: true} +} +//! [grouped properties] + + +//! [property binding] +Rectangle { + width: parent.width +} +//! [property binding] + +//! [property assignment] +Rectangle { + Component.onCompleted: { + width = 150 + } +} +//! [property assignment] + +Rectangle { + //placeholder slider + id: slider + property real value +} +Rectangle { + //placeholder system + id: system + property real brightness +} +//! [binding element] +Binding { + target: system + property: "brightness" + value: slider.value +} +//! [binding element] + +Rectangle { + //placeholder warning + id: warning + color: "red" +} +//! [PropertyChanges element] +Rectangle { + id: rectangle + + states: State { + name: "WARNING" + PropertyChanges { + target: rectangle + color: warning.color + } + } +} +//! [PropertyChanges element] + +//! [list property] +Item { + id: multistate + states: [ + State {name: "FETCH"}, + State {name: "DECODE"}, + State {name: "EXECUTE"} + ] +} +//! [list property] +//! [single property] +Item { + id: monostate + states: State {name: "RUNNING"} +} +//! [single property] + +Item { + id: printstate +//! [print list property] + Component.onCompleted: console.log (multistate.states[0].name) +//! [print list property] +} + +//! [JavaScript sample] +function calculateArea(width, height) { + return (width * height) * 0.5 +} + +Rectangle { + width: 150; height: 75 + property real area: calculateArea(width, height) + property real parentArea: calculateArea(parent.width,parent.height) + color: { if (area > parentArea) "blue"; else "red" } +} +//! [JavaScript sample] + +//! [id property] +Rectangle { + id: container + width: 100; height: 100 + Rectangle { + width: parent.width; height: parent.height + } +} +Rectangle { + width: container.width; height: container.height +} +//! [id property] + +//! [default property] +Item { + Text {} + Rectangle {} + Timer {} +} + +Item { + //without default property + children: [ + Text {}, + Rectangle {} + ] + resources: [ + Timer {} + ] +} +//! [default property] + +//! [state default] +State { + changes: [ + PropertyChanges {}, + PropertyChanges {} + ] +} + +State { + PropertyChanges {} + PropertyChanges {} +} +//! [state default] + +//! [object binding] +Rectangle { + + id: parentrectangle + gradient: + Gradient { //not a child of parentrectangle + + //generates a TypeError + //Component.onCompleted: console.log(parent.width) + } + + //child of parentrectangle + Rectangle {property string name: "childrectangle"} + + //prints "childrectangle" + Component.onCompleted: console.log(children[0].name) +} +//! [object binding] + +//! [list attached property] +Component { + id: listdelegate + Text { + text: "Hello" + color: ListView.isCurrentItem ? "red" : "blue" + } +} +ListView { + delegate: listdelegate +} +//! [list attached property] + +//! [attached signal handler] +Item { + Keys.onPressed: console.log("Key Press Detected") + Component.onCompleted: console.log("Completed initialization") +} +//! [attached signal handler] + +//! [alias usage] +Button { + id: textbutton + buttonLabel: "Click Me!" +} +//! [alias usage] + +//! [image alias] +Button { + id: imagebutton + buttonImage.source: "http://qt.nokia.com/logo.png" + buttonLabel: buttonImage.source +} +//! [image alias] + +Item { +id: widget + +//! [alias complete] +property alias widgetLabel: label + +//will generate an error +//widgetLabel.text: "Initial text" + +//will generate an error +//property alias widgetLabelText: widgetLabel.text + +Component.onCompleted: widgetLabel.text = "Alias completed Initialization" +//! [alias complete] + + Text {id: label} +} + +//![alias overwrite] +Rectangle { + id: coloredrectangle + property alias color: bluerectangle.color + color: "red" + + Rectangle { + id: bluerectangle + color: "#1234ff" + } + + Component.onCompleted: { + console.log (coloredrectangle.color) //prints "#1234ff" + setInternalColor() + console.log (coloredrectangle.color) //prints "#111111" + coloredrectangle.color = "#884646" + console.log (coloredrectangle.color) //prints #884646 + } + + //internal function that has access to internal properties + function setInternalColor() { + color = "#111111" + } +} +//![alias overwrite] +//! [parent end] +} +//! [parent end] +//! [document] -- cgit v0.12 From cad9d7f7ba1932944082811eb0525f05280e47d4 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Fri, 4 Feb 2011 16:40:22 +0100 Subject: Re-wrote QML Animation documentation and cleaned snippet code Removed unneeded snippets and added new snippet code. Task-number: QTBUG-16071 Reviewed-by: David Boddie --- doc/src/declarative/animation.qdoc | 376 ++++++++------------- .../snippets/declarative/animation-behavioral.qml | 61 ---- doc/src/snippets/declarative/animation-easing.qml | 51 --- .../snippets/declarative/animation-elements.qml | 66 ---- doc/src/snippets/declarative/animation-groups.qml | 104 ------ .../declarative/animation-propertyvaluesource.qml | 51 --- .../declarative/animation-signalhandler.qml | 55 --- .../snippets/declarative/animation-standalone.qml | 63 ---- .../snippets/declarative/animation-transitions.qml | 62 ---- doc/src/snippets/declarative/animation.qml | 227 +++++++++++++ 10 files changed, 367 insertions(+), 749 deletions(-) delete mode 100644 doc/src/snippets/declarative/animation-behavioral.qml delete mode 100644 doc/src/snippets/declarative/animation-easing.qml delete mode 100644 doc/src/snippets/declarative/animation-elements.qml delete mode 100644 doc/src/snippets/declarative/animation-groups.qml delete mode 100644 doc/src/snippets/declarative/animation-propertyvaluesource.qml delete mode 100644 doc/src/snippets/declarative/animation-signalhandler.qml delete mode 100644 doc/src/snippets/declarative/animation-standalone.qml delete mode 100644 doc/src/snippets/declarative/animation-transitions.qml create mode 100644 doc/src/snippets/declarative/animation.qml diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 26545ad..77900ee 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -33,227 +33,187 @@ \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 -values to gradually change them over time. Animation objects are created from -the built-in set of animation elements, which can be used to animate various -types of property values. In addition, animation objects can be applied in -different ways depending on the context in which they are required. - -To create an animation, use an appropriate animation element for the type of -the property that is to be animated, and apply the animation depending on the -type of behavior that is required. This page describes the \l {Types of -Animations} that can be created and the \l {Animation Elements} that are used -to create these animations. - - -\section1 Types of Animations - -An animation is created in different ways depending on the context in which it -is required. Suppose a \l Rectangle's movement - that is, changes in its \c x -or \c y property values - should be animated. The semantics of the animation -differ depending on whether you want to create: - +\keyword qml-animation-elements +\section1 Animation and Transitions Elements \list -\o An animation that moves the \l Rectangle as soon as it is created, to a -known position -\o An animation that only triggers when the \l Rectangle is moved by external -sources - for example, when the mouse is clicked, animate the movement to the -mouse position -\o An animation that triggers when a particular signal is received -\o A standalone animation that is not bound to the \l Rectangle's movement, but -instead can be started and stopped from script as required -\o An animation that only triggers during \l{QML States}{state changes} +\o \l {Transition} - Animates transitions during state changes +\o \l {SequentialAnimation} - Runs animations sequentially +\o \l {ParallelAnimation} - Runs animations in parallel +\o \l {Behavior} - Specifies a default animation for property changes +\o \l {PropertyAction} - Sets immediate property changes during animation +\o \l {PauseAnimation} - Introduces a pause in an animation +\o \l {SmoothedAnimation} - Allows a property to smoothly track a value +\o \l {SpringAnimation} - Allows a property to track a value in a spring-like motion +\o \l {ScriptAction} - Runs scripts during an animation \endlist -To support these different types of animation methods, QML provides several -methods for defining an animation. These are: - +\keyword qml-property-animation-elements +Elements that animate properties based on data types \list -\o Creating an \l{Animations as Property Value Sources}{animation using -property value sources}, to immediately animate a specific property -\o Using \l{Behavioral Animations}{behavioral animations}, which are triggered -when a property changes value -\o \l{Animations in a Signal Handler}{Within a signal handler}, to be triggered -when a signal is received -\o As a \l{Standalone Animation}{standalone animation}, that can be -started/stopped from script and can be rebound to different objects -\o Using \l{Transitions}{transitions}, to provide animations between \l{QML -States}{state changes} +\o \l {PropertyAnimation} - Animates property changes +\o \l {NumberAnimation} - Animates properties of type qreal +\o \l {Vector3dAnimation} - Animates properties of type QVector3d +\o \l {ColorAnimation} - Animates color changes +\o \l {RotationAnimation} - Animates rotations +\o \l {ParentAnimation} - Animates parent changes +\o \l {AnchorAnimation} - Animates anchor changes \endlist -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 -details. - - +\section1 Overview -\section2 Animations as Property Value Sources +In QML, animations are created by applying animation elements to property +values. Animation elements will interpolate property values to create smooth +transitions. As well, state transitions may assign animations to state changes. -An animation is applied as a \l{QDeclarativePropertyValueSource}{property value -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 -specific values rather than the current \c x and \c y values, set the -PropertyAnimation's \l {PropertyAnimation::}{from} property. - -Specifying an animation as a property value source is useful for animating a -property to a particular value as soon as the object is loaded. +To create an animation, use an appropriate animation element for the type of +the property that is to be animated, and apply the animation depending on the +type of behavior that is required. +\keyword qml-triggering-animations +\section1 Triggering Animations -\section2 Behavioral Animations +There are several ways of setting animation to an object. -Often an animation should be applied whenever a particular property value -changes. In these cases, a \l Behavior can be used to specify a default -animation for a property change. Here is an example: +\keyword qml-direct-animation +\section2 Direct Property Animation -\snippet doc/src/snippets/declarative/animation-behavioral.qml 0 +To create an immediate movement or animated movement, set the property value +directly. This may be done in signal handlers or attached properties. -This \l Rectangle has \l Behavior objects applied to its \c x and \c y -properties. Whenever these properties change (in this case, when the mouse is -clicked within the parent \l Item), the PropertyAnimation objects defined -within the behaviors will be applied to these properties, thus animating the \l -Rectangle's movement to its new position. Unlike the method of \l {Animations -as Property Value Sources}{defining an animation as a property value source}, -which creates a one-time animation that animates a property to a known value, a -behavioral animation is an animation that is triggered \e {in response to} a -value change. +\snippet doc/src/snippets/declarative/animation.qml direct property change -Any changes to these properties will trigger their animations. If \c x or \c y -were bound to other properties, and those properties changed, the animation -would be triggered. The \l{Behavior::}{enabled} property can be used to force a -\l Behavior to only apply under certain circumstances. +However, to create more control, \e {property animations} apply smooth movements +by interpolating values between property value changes. Property animations +provide timing controls and allows different interpolations through +\l{qml-easing-animation}{easing curves}. -Notice that unlike for property value source animations, the -PropertyAnimation's \l {PropertyAnimation::}{from} and \l -{PropertyAnimation::}{to} properties do not need to be defined because these -values are already provided, respectively, by the \l Rectangle's current values -and the new values set in the \c onClicked handler. If these properties were -defined anyway, they would override the default values. +\snippet doc/src/snippets/declarative/animation.qml property animation -See the \l {declarative/animation/behaviors}{Behaviors example} for a -demonstration of behavioral animations. +Specialized \l{qml-property-animation-elements}{property animation elements} +have more efficient implementations than the \l{PropertyAnimation} element. They +are for setting animations to different QML types such as \c int, \c color, and +rotations. Similarly, the \l{ParentAnimation} can animate parent changes. +See the \l {qml-controlling-animations}{Controlling Animations} section for more +information about the different animation properties. -\section2 Animations in a Signal Handler +\keyword qml-transition-animations +\section2 Transitions during State Changes -An animation can be created within a signal handler to be triggered when the -signal is received. For example: +\l{QML States}{States} are property configurations where a property may have different values to reflect different states. State changes introduce +abrupt property changes; animations smooth transitions to produce visually +appealing state changes. -\snippet doc/src/snippets/declarative/animation-signalhandler.qml 0 +The \l{Transition} element can contain +\l{qml-animation-elements}{animation elements} to interpolate property changes +caused by state changes. To assign the transition to an object, bind it to the +\c transitions property. -The PropertyAnimation is triggered when the MouseArea is clicked, animating the -\c x and \c y properties to a value of 50 over 1000 milliseconds. Since the -animation is not bound to a particular object or property, it must define the -\l {PropertyAnimation::}{target} and \l {PropertyAnimation::}{property} (or \l -{PropertyAnimation::}{targets} and \l{PropertyAnimation::}{properties}) values. -The \l {PropertyAnimation::}{to} property is also required to specify the new -\c x and \c y values. +A button might have two states, the \c pressed state when the user clicks on the +button and a \c released state when the user releases the button. We can assign +different property configurations for each state. A transition would animate the +change from the \c pressed state to the \c released state. Likewise, there would +be an animation during the change from the \c released state to the \c pressed +state. +\snippet doc/src/snippets/declarative/animation.qml transition animation -\section2 Standalone Animations +Binding the \c to and \c from properties to the state's name will assign that +particular transition to the state change. For simple or symmetric transitions, +setting the to \c to property to the wild card symbol, "\c{*}", denotes +that the transition applies to any state change. -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 -\l Rectangle is clicked: +\snippet doc/src/snippets/declarative/animation.qml wildcard animation -\snippet doc/src/snippets/declarative/animation-standalone.qml 0 +\section2 Default Animation as Behaviors -A standalone animation object is not running by default and must be started explicitly -using the \l {Animation::}{running} property or \l {Animation::}{start()} and -\l {Animation::}{stop()} methods. Since the animation is not bound to a -particular object or property, it must define the \l -{PropertyAnimation::}{target} and \l {PropertyAnimation::}{property} (or \l -{PropertyAnimation::}{targets} and \l{PropertyAnimation::}{properties}) values. -The \l {PropertyAnimation::}{to} property is also required to specify the new -\c x and \c y values. (The \l {PropertyAnimation::}{from} value can optionally -be provided.) +Default property animations are set using \e {behavior animations}. Animations +declared in \l {Behavior} elements apply to the property and animates any +property value changes. However, Behavior elements have an +\c enabled property to purposely enable or disable the behavior animations. -Standalone animations are useful when an animation is not targeted towards a -single object property and the animation should be explicitly started and -stopped. +A ball component might have a behavior animation assigned to its \c x, \c y, and +\c color properties. The behavior animation could be set up to simulate an +elastic effect. In effect, this behavior animation would apply the elastic +effect to the properties whenever the ball moves. +\snippet doc/src/snippets/declarative/animation.qml behavior animation -\section2 Transitions +There are several methods of assigning behavior animations to properties. The +\c{Behavior on } declaration is a convenient way of assigning a +behavior animation onto a property. -Transitions are used to describe the animations to be applied when a \l {QML -States}{state change} occurs. To create a transition, define a \l Transition -object and add it to an item's \l {Item::}{transitions} property. An example: +See the \l {declarative/animation/behaviors}{Behaviors example} for a +demonstration of behavioral animations. -\snippet doc/src/snippets/declarative/animation-transitions.qml 0 +\section1 Playing Animations in Parallel or in Sequence -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 -\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 -change. +Animations can run \e {in parallel} or \e {in sequence}. Parallel animations +will play a group of animations at the same time while sequential animations +play a group of animations in order: one after the other. Grouping animations in +\l{SequentialAnimation} and \{ParallelAnimation} will play the animations in +sequence or in parallel. -Notice the example does not set any \l {PropertyAnimation::}{from} and \l -{PropertyAnimation::}{to} values for the PropertyAnimation. As a convenience, -these properties are automatically set to the values of \c x and \c y before -and after the state change, respectively. However, they can be explicitly set -if these values should be overrided. +A banner component may have several icons or slogans to display, one after the +other. The \c opacity property could transform to \c 1.0 denoting an opaque +object. Using the \l{SequentialAnimation} element, the opacity animations will +play after the preceding animation finishes. The \l{ParallelAnimation} element +will play the animations at the same time. -Also notice the PropertyAnimation does not need to specify a \l -{PropertyAnimation::}{target} object; any \c x or \c y value of any object that -has changed during the state change will be animated. However, the target can -be set if the animation should be restricted to certain objects. +\snippet doc/src/snippets/declarative/animation.qml sequential animation -The top-level animations in a \l Transition are run in parallel. To run them -one after the other, use a SequentialAnimation, as shown below in \l {Grouping -Animations}. +Once individual animations are placed into a SequentialAnimation or +ParallelAnimation, they can no longer be started and stopped independently. The +sequential or parallel animation must be started and stopped as a group. -See the \l Transition documentation for more information. +The \l SequentialAnimation element is also useful for playing +\l{qml-transition-animations}{transition animations} because animations are +played in parallel inside transitions. +See the \l {declarative/animation/basics}{Animation basics example} for a +demonstration of creating and combining multiple animations in QML. -\section1 Animation Elements +\keyword qml-controlling-animations +\section1 Controlling Animations -To create an animation, choose from one of the built-in QML animation elements. -While the above examples are demonstrated using PropertyAnimation, they could -have used other elements depending on the type of the property to be animated -and whether a single or multiple animations are required. +There are different methods to control animations. -All animation elements inherit from the \l Animation element. It is not +\section2 Animation Playback +All \l{qml-animation-elements}{animation elements} inherit from the \l Animation element. It is not possible to create \l Animation objects; instead, this element provides the -essential properties and methods for animation elements. For example, it allows -animations to be started and stopped through the \l {Animation::}{running} -property and the \l{Animation::}{start()} and \l{Animation::}{stop()} methods. -It can also define the number of \l {Animation::}{loops} for an animation. - +essential properties and methods for animation elements. Animation elements have +\c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and +\c{complete()} -- all of these methods control the execution of animations. -\section2 Property Animation Elements +\keyword qml-easing-animation +\section2 Easing -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. +Easing curves define how the animation will interpolate between the start value +and the end value. Different easing curves might go beyond the defined range of +interpolation. The easing curves simplify the creation of animation effects such +as bounce effects, acceleration, deceleration, and cyclical animations. -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: +A QML object may have different easing curve for each property animation. There +are also different parameters to control the curve, some of which are exclusive +to a particular curve. For more information about the easing curves, visit the +\l {PropertyAnimation::easing.type}{easing} documentation. -\snippet doc/src/snippets/declarative/animation-elements.qml color +The \l{declarative/animation/easing}{easing example} visually demonstrates each +of the different easing types. -RotationAnimation allows a rotation's direction to be specified. The following -animates the rectangle's \l {Item::rotation} property: +\section2 Other Animation Elements -\snippet doc/src/snippets/declarative/animation-elements.qml rotation +In addition, QML provides several other elements useful for animation: -In addition, the following specialized animation elements are available: +\list +\o PauseAnimation: enables pauses during animations +\o ScriptAction: allows JavaScript to be executed during an animation, and can +be used together with StateChangeScript to reused existing scripts +\o PropertyAction: changes a property \e immediately during an animation, +without animating the property change +\endlist +These are specialized animation elements that animate different property types \list \o SmoothedAnimation: a specialized NumberAnimation that provides smooth changes in animation when the target value changes @@ -264,75 +224,19 @@ attributes such as \l {SpringAnimation::}{mass}, \o AnchorAnimation: used for animating an anchor change (see AnchorChanges) \endlist -See their respective documentation pages for more details. - - -\section3 Easing - -Any PropertyAnimation-based animations can specify \l -{PropertyAnimation::easing.type}{easing attributes} to control the -easing curve applied when a property value is animated. These control the -effect of the animation on the property value, to provide visual effects like -bounce, acceleration and deceleration. - -For example, this modified version of an \l {Animations as Property Value -Sources}{earlier example} uses \c Easing.OutBounce to create a bouncing effect -when the animation reaches its target value: - -\snippet doc/src/snippets/declarative/animation-easing.qml 0 - -The \l{declarative/animation/easing}{easing example} visually demonstrates each -of the different easing types. +*/ -\section2 Grouping Animations -Multiple animations can be combined into a single animation using one of the -animation group elements: ParallelAnimation or SequentialAnimation. As their -names suggest, animations in a ParallelAnimation are run at the same time, -while animations in a SequentialAnimation are run one after the other. -To run multiple animations, define the animations within an animation group. -The following example creates a SequentialAnimation that runs three animations -one after the other: a NumberAnimation, a PauseAnimation and another -NumberAnimation. The SequentialAnimation is applied as a \l{Animations as -Property Value Sources}{property value source animation} on the image's \c y -property, so that the animation starts as soon as the image is loaded, moving -the image up and down: +\snippet doc/src/snippets/declarative/animation-elements.qml color +\snippet doc/src/snippets/declarative/animation-propertyvaluesource.qml 0 +\snippet doc/src/snippets/declarative/animation-signalhandler.qml 0 +\snippet doc/src/snippets/declarative/animation-standalone.qml 0 +\snippet doc/src/snippets/declarative/animation-transitions.qml 0 \snippet doc/src/snippets/declarative/animation-groups.qml 0 -\image propanim.gif - -Since the SequentialAnimation is applied to the \c y property, the individual -animations within the group are automatically applied to the \c y property as -well; it is not required to set their \l{PropertyAnimation::}{properties} -values to a particular property. - -Animation groups can be nested. Here is a rather complex animation making use -of both sequential and parallel animations: \snippet doc/src/snippets/declarative/animation-groups.qml 1 +\snippet doc/src/snippets/declarative/animation-groups.qml 0 +\image propanim.gif -Once individual animations are placed into a SequentialAnimation or -ParallelAnimation, they can no longer be started and stopped independently. The -sequential or parallel animation must be started and stopped as a group. - -See the \l {declarative/animation/basics}{Animation basics example} for a -demonstration of creating and combining multiple animations in QML. - - - -\section2 Other Animation Elements - -In addition, QML provides several other elements useful for animation: - -\list -\o PauseAnimation: enables pauses during animations -\o ScriptAction: allows JavaScript to be executed during an animation, and can -be used together with StateChangeScript to reused existing scripts -\o PropertyAction: changes a property \e immediately during an animation, -without animating the property change -\endlist - -See their respective documentation pages for more details. - -*/ diff --git a/doc/src/snippets/declarative/animation-behavioral.qml b/doc/src/snippets/declarative/animation-behavioral.qml deleted file mode 100644 index 93cf2fa..0000000 --- a/doc/src/snippets/declarative/animation-behavioral.qml +++ /dev/null @@ -1,61 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -import QtQuick 1.0 - -Item { - width: 100; height: 100 - - Rectangle { - id: rect - width: 100; height: 100 - color: "red" - - Behavior on x { PropertyAnimation { duration: 500 } } - Behavior on y { PropertyAnimation { duration: 500 } } - } - - MouseArea { - anchors.fill: parent - onClicked: { rect.x = mouse.x; rect.y = mouse.y } - } -} -//![0] - diff --git a/doc/src/snippets/declarative/animation-easing.qml b/doc/src/snippets/declarative/animation-easing.qml deleted file mode 100644 index 64ba44c..0000000 --- a/doc/src/snippets/declarative/animation-easing.qml +++ /dev/null @@ -1,51 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -import QtQuick 1.0 - -Rectangle { - width: 100; height: 100 - color: "red" - - PropertyAnimation on x { to: 50; duration: 1000; easing.type: Easing.OutBounce } - PropertyAnimation on y { to: 50; duration: 1000; easing.type: Easing.OutBounce } -} -//![0] - diff --git a/doc/src/snippets/declarative/animation-elements.qml b/doc/src/snippets/declarative/animation-elements.qml deleted file mode 100644 index d9bfc28..0000000 --- a/doc/src/snippets/declarative/animation-elements.qml +++ /dev/null @@ -1,66 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -import QtQuick 1.0 - -Row { - -//![color] -Rectangle { - width: 100; height: 100 - - ColorAnimation on color { from: "red"; to: "yellow"; duration: 1000 } -} -//![color] - -//![rotation] -Item { - width: 300; height: 300 - - Rectangle { - width: 100; height: 100; anchors.centerIn: parent - color: "red" - - RotationAnimation on rotation { to: 90; direction: RotationAnimation.Clockwise } - } -} -//![rotation] - -} diff --git a/doc/src/snippets/declarative/animation-groups.qml b/doc/src/snippets/declarative/animation-groups.qml deleted file mode 100644 index f29ea48..0000000 --- a/doc/src/snippets/declarative/animation-groups.qml +++ /dev/null @@ -1,104 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -import QtQuick 1.0 - -Row { - -//![0] -Rectangle { - id: rect - width: 120; height: 200 - - Image { - id: img - source: "pics/qt.png" - anchors.horizontalCenter: parent.horizontalCenter - y: 0 - - SequentialAnimation on y { - loops: Animation.Infinite - NumberAnimation { to: rect.height - img.height; easing.type: Easing.OutBounce; duration: 2000 } - PauseAnimation { duration: 1000 } - NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 } - } - } -} -//![0] - -//![1] -Rectangle { - id: redRect - width: 100; height: 100 - color: "red" - - MouseArea { id: mouseArea; anchors.fill: parent } - - states: State { - name: "pressed"; when: mouseArea.pressed - PropertyChanges { target: redRect; color: "blue"; y: mouseArea.mouseY; width: mouseArea.mouseX } - } - - transitions: Transition { - - SequentialAnimation { - ColorAnimation { duration: 200 } - PauseAnimation { duration: 100 } - - ParallelAnimation { - NumberAnimation { - duration: 500 - easing.type: Easing.OutBounce - targets: redRect - properties: "y" - } - - NumberAnimation { - duration: 800 - easing.type: Easing.InOutQuad - targets: redRect - properties: "width" - } - } - } - } -} -//![1] - -} diff --git a/doc/src/snippets/declarative/animation-propertyvaluesource.qml b/doc/src/snippets/declarative/animation-propertyvaluesource.qml deleted file mode 100644 index 6f93967..0000000 --- a/doc/src/snippets/declarative/animation-propertyvaluesource.qml +++ /dev/null @@ -1,51 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -import QtQuick 1.0 - -Rectangle { - width: 100; height: 100 - color: "red" - - PropertyAnimation on x { to: 50; duration: 1000; loops: Animation.Infinite } - PropertyAnimation on y { to: 50; duration: 1000; loops: Animation.Infinite } -} -//![0] - diff --git a/doc/src/snippets/declarative/animation-signalhandler.qml b/doc/src/snippets/declarative/animation-signalhandler.qml deleted file mode 100644 index 416417f..0000000 --- a/doc/src/snippets/declarative/animation-signalhandler.qml +++ /dev/null @@ -1,55 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -import QtQuick 1.0 - -Rectangle { - id: rect - width: 100; height: 100 - color: "red" - - MouseArea { - anchors.fill: parent - onClicked: PropertyAnimation { target: rect; properties: "x,y"; to: 50; duration: 1000 } - } -} - -//![0] - diff --git a/doc/src/snippets/declarative/animation-standalone.qml b/doc/src/snippets/declarative/animation-standalone.qml deleted file mode 100644 index 0bf3020..0000000 --- a/doc/src/snippets/declarative/animation-standalone.qml +++ /dev/null @@ -1,63 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -import QtQuick 1.0 - -Rectangle { - id: rect - width: 100; height: 100 - color: "red" - - PropertyAnimation { - id: animation - target: rect - properties: "x,y" - duration: 1000 - } - - MouseArea { - anchors.fill: parent - onClicked: { - animation.to = 50; - animation.running = true; - } - } -} -//![0] diff --git a/doc/src/snippets/declarative/animation-transitions.qml b/doc/src/snippets/declarative/animation-transitions.qml deleted file mode 100644 index 62bef23..0000000 --- a/doc/src/snippets/declarative/animation-transitions.qml +++ /dev/null @@ -1,62 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ -//![0] -import QtQuick 1.0 - -Rectangle { - id: rect - width: 100; height: 100 - color: "red" - - MouseArea { - anchors.fill: parent - onClicked: rect.state = "moved" - } - - states: State { - name: "moved" - PropertyChanges { target: rect; x: 50; y: 50 } - } - - transitions: Transition { - PropertyAnimation { properties: "x,y"; duration: 1000 } - } -} -//![0] diff --git a/doc/src/snippets/declarative/animation.qml b/doc/src/snippets/declarative/animation.qml new file mode 100644 index 0000000..739d009 --- /dev/null +++ b/doc/src/snippets/declarative/animation.qml @@ -0,0 +1,227 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +import QtQuick 1.0 + + +//! [parent begin] +Rectangle { +//! [parent begin] + width: 200; height: 600 + id: screen + +Column { + spacing: 12 +//! [direct property change] +Rectangle { + id: blob + width: 75; height: 75 + color: "blue" + + MouseArea { + anchors.fill: parent + onClicked: blob.color = "green" + } +} +//! [direct property change] + +//! [property animation] +Rectangle { + id: flashingblob + width: 75; height: 75 + color: "blue" + opacity: 1.0 + + MouseArea { + anchors.fill: parent + onClicked: { + animateColor.start() + animateOpacity.start() + } + } + + PropertyAnimation {id: animateColor; target: flashingblob; properties: "color"; to: "green"; duration: 100} + + NumberAnimation { + id: animateOpacity + target: flashingblob + properties: "opacity" + from: 0.99 + to: 1.0 + loops: Animation.Infinite + easing {type: Easing.OutBack; overshoot: 500} + } +} +//! [property animation] + +//! [transition animation] +Rectangle { + width: 75; height: 75 + id: button + state: "RELEASED" + + MouseArea { + anchors.fill: parent + onPressed: button.state = "PRESSED" + onReleased: button.state = "RELEASED" + } + + states: [ + State { + name: "PRESSED" + PropertyChanges { target: button; color: "lightblue"} + }, + State { + name: "RELEASED" + PropertyChanges { target: button; color: "lightsteelblue"} + } + ] + + transitions: [ + Transition { + from: "PRESSED" + to: "RELEASED" + ColorAnimation { target: button; duration: 100} + }, + Transition { + from: "RELEASED" + to: "PRESSED" + ColorAnimation { target: button; duration: 100} + } + ] +} +//! [transition animation] + +Rectangle { + width: 75; height: 75 + id: wildcard + color: "green" +//! [wildcard animation] + transitions: + Transition { + to: "*" + ColorAnimation { target: button; duration: 100} + } +//! [wildcard animation] + + MouseArea { + anchors.fill: parent + onPressed: { + ball.x = 10 + ball.color = "red" + } + onReleased: { + ball.x = screen.width / 2 + ball.color = "salmon" + } + } +} + +//! [behavior animation] +Rectangle { + width: 75; height: 75; radius: width + id: ball + color: "salmon" + + Behavior on x { + NumberAnimation { + id: bouncebehavior + easing { + type: Easing.OutElastic + amplitude: 1.0 + period: 0.5 + } + } + } + Behavior on y { + animation: bouncebehavior + } + Behavior { + ColorAnimation { target: ball; duration: 100 } + } +} +//! [behavior animation] + +//! [sequential animation] +Rectangle { + id: banner + width: 150; height: 100; border.color: "black" + + Column { + anchors.centerIn: parent + Text { + id: code + text: "Code less." + opacity: 0.01 + } + Text { + id: create + text: "Create more." + opacity: 0.01 + } + Text { + id: deploy + text: "Deploy everywhere." + opacity: 0.01 + } + } + + MouseArea { + anchors.fill: parent + onPressed: playbanner.start() + } + + SequentialAnimation { + id: playbanner + running: false + NumberAnimation { target: code; property: "opacity"; to: 1.0; duration: 200} + NumberAnimation { target: create; property: "opacity"; to: 1.0; duration: 200} + NumberAnimation { target: deploy; property: "opacity"; to: 1.0; duration: 200} + } +} +//! [sequential animation] + +}//end of col +//! [parent end] +} +//! [parent end] + +//! [document] + -- cgit v0.12 From b7aa20e56b3ed45cf00d8a57696e6d8ac803f9b4 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Fri, 4 Feb 2011 16:42:30 +0100 Subject: Replaced old Qt logo with the new Qt logo. Reviewed-by: David Boddie --- doc/src/snippets/declarative/pics/qt.png | Bin 514 -> 2991 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/doc/src/snippets/declarative/pics/qt.png b/doc/src/snippets/declarative/pics/qt.png index cbed1a9..4f68e16 100644 Binary files a/doc/src/snippets/declarative/pics/qt.png and b/doc/src/snippets/declarative/pics/qt.png differ -- cgit v0.12 From c9b5d8708f0c703122669938573eb575f03d6b78 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Mon, 7 Feb 2011 18:35:00 +0100 Subject: Rewrote Qt Quick documentation. Task number: QTBUG-16071 --- doc/src/declarative/animation.qdoc | 2 +- doc/src/declarative/basicelements.qdoc | 1 + doc/src/declarative/basictypes.qdoc | 4 +- doc/src/declarative/declarativeui.qdoc | 2 +- doc/src/declarative/mouseevents.qdoc | 76 ++++- doc/src/declarative/propertybinding.qdoc | 14 +- doc/src/declarative/qdeclarativedocument.qdoc | 50 +-- doc/src/declarative/qdeclarativemodels.qdoc | 3 +- doc/src/declarative/qdeclarativestates.qdoc | 229 ++++--------- doc/src/declarative/qmlevents.qdoc | 110 +++++- doc/src/declarative/qmlreusablecomponents.qdoc | 441 +------------------------ doc/src/declarative/qmlsyntax.qdoc | 2 +- doc/src/declarative/qmltexthandling.qdoc | 23 +- doc/src/declarative/qmlviews.qdoc | 27 +- 14 files changed, 335 insertions(+), 649 deletions(-) diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 77900ee..bd6813c 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -151,7 +151,7 @@ demonstration of behavioral animations. Animations can run \e {in parallel} or \e {in sequence}. Parallel animations will play a group of animations at the same time while sequential animations play a group of animations in order: one after the other. Grouping animations in -\l{SequentialAnimation} and \{ParallelAnimation} will play the animations in +\l{SequentialAnimation} and \l{ParallelAnimation} will play the animations in sequence or in parallel. A banner component may have several icons or slogans to display, one after the diff --git a/doc/src/declarative/basicelements.qdoc b/doc/src/declarative/basicelements.qdoc index 4253e4c..5997998 100644 --- a/doc/src/declarative/basicelements.qdoc +++ b/doc/src/declarative/basicelements.qdoc @@ -91,6 +91,7 @@ The \l Text and \l TextEdit elements display formatted text onto the screen. \c TextEdit features multi-line editing while the \l TextInput element is for single line text input. +\keyword qml-top-level-component \section1 Using Elements as the Top-Level Component For creating components (or displaying a simple scene), there are different diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 948bdef..1be648e 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -29,8 +29,8 @@ \page qdeclarativebasictypes.html \ingroup qml-features \contentspage QML Features - \previouspage {Property Binding} - \nextpage {QML Basic Elements}{Basic Elements} + \previouspage {QML Basic Elements} + \nextpage Property Binding \title QML Basic Types QML has a set of primitive types, as listed below, that are used throughout diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index ae11559..aa4006b 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -81,7 +81,7 @@ QML and the Qt Declarative Module separate the frontend UI logic from the backen \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 Mouse Events}{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} diff --git a/doc/src/declarative/mouseevents.qdoc b/doc/src/declarative/mouseevents.qdoc index f6512a7..eed3a3a 100644 --- a/doc/src/declarative/mouseevents.qdoc +++ b/doc/src/declarative/mouseevents.qdoc @@ -35,9 +35,7 @@ \tableofcontents -\section1 Introduction - -\section1 Mouse Events +\section1 Mouse Elements \list \o \l{MouseArea} Element @@ -45,7 +43,77 @@ \endlist \section1 Mouse Event Handling -go over the slots and signals feature (without the C++) + +QML uses \l{QML Signal and Handler Event System}{signals and handlers} to +deliver mouse interactions. Specifically, the \l MouseArea and \l MouseEvent +elements provide QML components with signal handlers to accept mouse events +within a defined area. + +\section1 Defining a Mouse Area + +The \l MouseArea element receives events within a defined area. One quick way +to define this area is to anchor the \c MouseArea to its parent's area using the +\c anchors.fill property. If the parent is a \l Rectangle (or any \l Item +component), then the MouseArea will fill the area defined by the parent's +dimensions. Alternatively, an area smaller or larger than the parent is +definable. +\snippet doc/src/snippets/declarative/mouse.qml anchor fill + +\section1 Receiving Events + +The MouseArea element provides +\l{QML Signal and Handler Event System}{signals and handlers} to detect different +mouse events. The \l MouseArea element documentation describes these +gestures in greater detail. + +\list Mouse Gestures +\o canceled +\o clicked +\o doubleClicked +\o entered +\o exited +\o positionChanged +\o pressAndHold +\o pressed +\o released +\endlist + +These signals have signal handlers that are invoked when the signals are emitted. +\snippet doc/src/snippets/declarative/mouse.qml mouse handlers + +\section1 Enabling Gestures +Some mouse gestures and button clicks need to be enabled before they send or +receive events. Certain \l MouseArea and \l MouseEvent properties enable these +gestures. + +To listen to (or explicitly ignore) a certain mouse button, set the appropriate +mouse button to the \l {MouseArea::acceptedButtons}{acceptedButtons} property. + +Naturally, the mouse events, such as button presses and mouse positions, are +sent during a mouse click. For example, the \c containsMouse property will only +retrieve its correct value during a mouse press. The +\l {MouseArea::hoverEnabled}{hoverEnabled} will enable mouse events and +positioning even when there are no mouse button presses. Setting the +\c hoverEnabled property to \c true, in turn will enable the \c entered, +\c exited, and \c positionChanged signal and their respective signal handlers. + +Additionally, to disable the whole mouse area, set the \c MouseArea +element's \c enabled property to \c false. + +\section1 MouseEvent Object + +Signals and their handlers receive a \l MouseEvent object as a parameter. The +\c mouse object contain information about the mouse event. For example, the +mouse button that started the event is queried through the +\l {MouseEvent::button}{mouse.button} property. + +The \c MouseEvent object can also ignore a mouse event using its \c accepted +property. + +\section2 Accepting Further Signals +Many of the signals are sent multiple times to reflect various mouse events +such as double clicking. To facilitate the classification of mouse clicks, the +MouseEvent object has an \c accepted property to disable the event propagation. 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/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 27653bd..00ff650 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -35,9 +35,14 @@ \section1 Properties -A property is a value of a QML component that can be read and modified by other objects. -In QML, properties serve many purpose. Their main function is to bind to values. -Values may be a \l{QML Basic Types}{basic type}, or other QML elements. +QML components have \e properties that can be read and modified by other objects. +In QML, properties serve many purposes but their main function is to bind to +values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements. + +The syntax for properties is: +\qml + [default] property [: defaultValue] +\endqml Elements already possess useful properties but, to create custom properties, precede the property name with the keyword \c property. @@ -48,7 +53,7 @@ precede the property name with the keyword \c property. \snippet doc/src/snippets/declarative/properties.qml parent end QML property rules coincide with many of JavaScript's property rules, for example, -properti names must begin with a lowercase letter. +property names must begin with a lowercase letter. \l {JavaScript Reserved Words}{JavaScript reserved words} are not valid property names. @@ -229,7 +234,6 @@ Accessing the aliasing property is similar to accessing a regular property. In addition, the optional \c default keyword indicates that the aliasing property is a \l{Default Properties}{default property}. -<<<<<<< HEAD \snippet doc/src/snippets/declarative/Button.qml property alias When importing the component as a \c Button, the \c buttonlabel is directly accessible through the \c label property. diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc index b94e32e..f2147de 100644 --- a/doc/src/declarative/qdeclarativedocument.qdoc +++ b/doc/src/declarative/qdeclarativedocument.qdoc @@ -42,17 +42,17 @@ Here is a simple QML document: QML documents are always encoded in UTF-8 format. -A QML document always begins with one or more import statements. To prevent elements -introduced in later versions from affecting existing QML programs, the element types -available within a document are controlled by the imported QML \l {Modules}. That is, +A QML document always begins with one or more import statements. To prevent elements +introduced in later versions from affecting existing QML programs, the element types +available within a document are controlled by the imported QML \l {Modules}. That is, QML is a \e versioned language. -Syntactically a QML document is self contained; QML does \e not have a preprocessor that -modifies the document prior to presentation to the QML runtime. \c import statements -do not "include" code in the document, but instead instruct the QML runtime on how to -resolve type references found in the document. Any type reference present in a QML -document - such as \c Rectangle and \c ListView - including those made within an -\l {Inline JavaScript}{JavaScript block} or \l {Property Binding}s, are \e resolved based exclusively on the +Syntactically a QML document is self contained; QML does \e not have a preprocessor that +modifies the document prior to presentation to the QML runtime. \c import statements +do not "include" code in the document, but instead instruct the QML runtime on how to +resolve type references found in the document. Any type reference present in a QML +document - such as \c Rectangle and \c ListView - including those made within an +\l {Inline JavaScript}{JavaScript block} or \l {Property Binding}s, are \e resolved based exclusively on the import statements. QML does not import any modules by default, so at least one \c import statement must be present or no elements will be available! @@ -63,12 +63,12 @@ resolved according to the document scope. \section1 Documents as Component Definitions -A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}. A QML component -is a template that is interpreted by the QML runtime to create an object with some predefined -behaviour. As it is a template, a single QML component can be "run" multiple times to -produce several objects, each of which are said to be \e instances of the component. +A QML document defines a single, top-level \l {QDeclarativeComponent}{QML component}. A QML component +is a template that is interpreted by the QML runtime to create an object with some predefined +behaviour. As it is a template, a single QML component can be "run" multiple times to +produce several objects, each of which are said to be \e instances of the component. -Once created, instances are not dependent on the component that created them, so they can +Once created, instances are not dependent on the component that created them, so they can operate on independent data. Here is an example of a simple "Button" component (defined in a \c Button.qml file) that is instantiated four times by \c application.qml. Each instance is created with a different value for its \c text property: @@ -80,7 +80,7 @@ Each instance is created with a different value for its \c text property: \row \o \snippet doc/src/snippets/declarative/qml-documents/qmldocuments.qml document -\o +\o \qml import QtQuick 1.0 @@ -112,23 +112,23 @@ to other QML components and applications in the same directory. \section1 Inline Components In addition to the top-level component that all QML documents define, and any reusable -components placed in separate files, documents may also -include \e inline components. Inline components are declared using the -\l Component element, as can be seen in the first example above. Inline components share +components placed in separate files, documents may also +include \e inline components. Inline components are declared using the +\l Component element, as can be seen in the first example above. Inline components share all the characteristics of regular top-level components and use the same \c import list as their -containing QML document. Components are one of the most basic building blocks in QML, and are +containing QML document. Components are one of the most basic building blocks in QML, and are frequently used as "factories" by other elements. For example, the \l ListView element uses the \c delegate component as the template for instantiating list items - each list item is just a new instance of the component with the item specific data set appropriately. -Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a +Like other \l {QML Elements}, the \l Component element is an object and must be assigned to a property. \l Component objects may also have an object id. In the first example on this page, -the inline component is added to the \l Rectangle's \c resources list, and then -\l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate +the inline component is added to the \l Rectangle's \c resources list, and then +\l {Property Binding} is used to assign the \l Component to the \l ListView's \c delegate property. While using property binding allows the \l Component object to be shared (for example, -if the QML document contained multiple \l ListView's with the same delegate), in this case the -\l Component could have been assigned directly to the \l ListView's \c delegate. The QML -language even contains a syntactic optimization when assigning directly to a component property +if the QML document contained multiple \l ListView's with the same delegate), in this case the +\l Component could have been assigned directly to the \l ListView's \c delegate. The QML +language even contains a syntactic optimization when assigning directly to a component property for this case where it will automatically insert the \l Component tag. These final two examples are behaviorally identical to the original document. diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc index 70228b1..2f9d418 100644 --- a/doc/src/declarative/qdeclarativemodels.qdoc +++ b/doc/src/declarative/qdeclarativemodels.qdoc @@ -78,6 +78,7 @@ The use of positioner items to arrange items from a model is covered in \l{Using QML Positioner and Repeater Items}. +\keyword qml-data-models \section1 QML Data Models \section2 ListModel @@ -154,7 +155,7 @@ Note that in the above example there is no delegate required. The items of the model itself provide the visual elements that will be positioned by the view. - +\keyword qml-c++-models \section1 C++ Data Models Models can be defined in C++ and then made available to QML. This is useful diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index 4089609..3f05c9b 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -34,194 +34,105 @@ \target qmlstates \title QML States -\section1 Overview +\section1 States Elements +\list +\o \l State +\o \l PropertyChanges +\o \l StateGroup +\o \l StateChangeScript +\o \l ParentChange +\o \l AnchorChanges +\endlist -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. +\section1 Overview -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 -other end of the scale, when a simple button is pressed, it may change to a -"pressed" state in which its color and position is modified to give a pressed -appearance. +Many user interface designs are \e state driven; interfaces have configurations +that differ depending on the current state. For example, a traffic signal will +configure its flags or lights depending on its state. While in the signal's +\c stop state, a red light will turn on while the yellow and the green lights +will turn off. In the \c caution state, the yellow light is on while the other +lights are turned off. -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 -present a different configuration that could, for example: +In QML, \e states are a set of property configurations defined in a \l State +element. Different configurations could, for example: \list \o Show some UI elements and hide others \o Present different available actions to the user -\o Start, stop or pause animations +\o Start, stop, or pause animations \o Execute some script required in the new state \o Change a property value for a particular item -\o Show a different view or "screen" +\o Show a different view or screen \endlist -Changes between states can be animated using \l {Transitions}{transitions}, as -discussed further below. - -All \l {Item}-based objects have a \e {default state}, and can specify additional -states by adding new \l State objects to the item's \l {Item::}{states} -property. Each state has a \e name that is unique for all states within that -item; the default state's name is an empty string. To change the current state +All \l {Item}-based objects have a \c state property, and can specify additional +states by adding new \c State objects to the item's \l {Item::}{states} +property. Each state within a component has a unique \c name, an empty string +being the default. To change the current state of an item, set the \l {Item::}{state} property to the name of the state. -Non-Item objects can use states through the StateGroup element. - +Non-Item objects may use states through the \l StateGroup element. \section1 Creating States To create a state, add a \l State object to the item's \l {Item::}{states} property, which holds a list of states for that item. -Following is an example. Here, the \l Rectangle is initially placed in the -default (0, 0) position. It has defined an additional state named "moved", in -which a PropertyChanges object repositions the rectangle to (50, 50). Clicking -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 -objects, not just the object that owns the state. For example: - -\qml -Rectangle { - // ... - states: [ - State { - name: "moved" - PropertyChanges { target: myRect; x: 50; y: 50; color: "blue" } - PropertyChanges { target: someOtherItem; width: 1000 } - } - ] -} -\endqml - -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: - -\snippet doc/src/snippets/declarative/propertyanimation.qml single state - -A \l State is not limited to performing modifications on property values. It -can also: - +A warning \c signal component may have two states, the \c NORMAL and the +\c CRITICAL state. Suppose that in the \c NORMAL state, the \c color of the +signal should be \c green and the warning \c flag is down. Meanwhile, in the +\c CRITICAL state, the \c color should be \c red and the flag is \c up. We may +model the states using the \c State element and the color and flag +configurations with the \c PropertyChanges element. +\snippet doc/src/snippets/declarative/states.qml signal states +The \l PropertyChanges element will change the values of object properties. +Objects are referenced through their \l {qml-id-property}{id}. Objects outside +the component are also referenced using the \c id property, exemplified by the +property change to the external \c flag object. + +Further, the state may change by assigning the \c state property with the +appropriate signal state. A state switch could be in a \l MouseArea element, +assigning a different state whenever the signal receives a mouse click. +\snippet doc/src/snippets/declarative/states.qml switch states + +The State element is not limited to performing modifications on property values. +It can also: \list -\o Run some script using StateChangeScript -\o Override an existing signal handler for an object using PropertyChanges -\o Re-parent an \l Item using ParentChanges -\o Modify anchor values using AnchorChanges +\o Run some script using \l StateChangeScript +\o Override an existing signal handler for an object using \l PropertyChanges +\o Re-parent an \l Item using \l ParentChange +\o Modify anchor values using \l AnchorChanges \endlist -The \l {declarative/animation/states}{States and Transitions example} -demonstrates how to declare a basic set of states and apply animated -transitions between them. - - \section1 The Default State -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 -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 -released. This can be achieved by using the \l {State::}{when} property, -like this: - -\qml -Rectangle { - // ... - - MouseArea { - id: mouseArea - anchors.fill: parent - } - - states: State { - name: "moved" - when: mouseArea.pressed - // ... - } -} -\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, -the state is changed to \e moved. When it is released, the item reverts to its -\e default state, which defines all of the item's original property values. - -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 -Rectangle { - // ... - - MouseArea { - anchors.fill: parent - onPressed: myRect.state = 'moved'; - onReleased: myRect.state = ''; - } - - states: State { - name: "moved" - // ... - } -} -\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 -assigning the state from signal handlers. - - -\section1 Animating State Changes - +Every \l Item based component has a \c state property and a \e{default state}. +The default state is the empty string (\c{""}) and contains all of an item's +initial property values. The default state is useful for managing property +values before state changes. Setting the \c state property to an empty string +will load the default state. -State changes can be easily animated through \l {Transitions}{transitions}. A -\l Transition defines the animations that should be applied when an item -changes from one state to another. +\section1 The \c when Property -If the above example was modified to include the following \l Transition, the -movement of the \l Rectangle would be animated: +For convenience, the \l State element has a \c when property that can bind to +expressions to change the state whenever the bound expression evaluates to +\c true. The \c when property will revert the state back to the +\l {The Default State}{default state} when the expression evaluates to false. -\qml -Rectangle { - // ... +\snippet doc/src/snippets/declarative/states.qml when property +The \c bell component will change to the \c RINGING state whenever the +\c signal.state is \c CRITICAL. - MouseArea { - // Handle mouse events... - } - - states: [ - // States are defined here... - ] +\section1 Animating State Changes - transitions: [ - Transition { - NumberAnimation { properties: "x,y"; duration: 500 } - } - ] - } -\endqml +State changes induce abrupt value changes. The \l Transitions element allow +smoother changes during state changes. In transitions, animations and +interpolation behaviors are definable. The +\l {QML Animation and Transitions}{Animation and Transitions} article has more +information about creating state animations. -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 -milliseconds. +The \l {declarative/animation/states}{States and Transitions example} +demonstrates how to declare a basic set of states and apply animated +transitions between them. -See the \l Transitions documentation for more information. */ diff --git a/doc/src/declarative/qmlevents.qdoc b/doc/src/declarative/qmlevents.qdoc index 3c1c8df..8c2147a 100644 --- a/doc/src/declarative/qmlevents.qdoc +++ b/doc/src/declarative/qmlevents.qdoc @@ -1,6 +1,10 @@ /**************************************************************************** ** +<<<<<<< HEAD +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +======= ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). +>>>>>>> d7a91cfe8683309883694fbbf508e5fc42d44165 ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** @@ -26,12 +30,106 @@ ****************************************************************************/ /*! - \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} +\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 +\title QML Signal and Handler Event System + +\section1 Overview, structural information + +QML utilizes Qt's \l{The Meta-Object System}{meta-object} and +\l{Signals & Slots}{signals} systems. Signals and slots created using Qt in C++ +are inheritely valid in QML. + +\keyword qml-signals-and-handlers +\section1 Signals and Handlers + +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: + +\qml +signal [([ [, ...]])] +\endqml + +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 various examples of signal declarations: +\snippet doc/src/snippets/declarative/events.qml parent begin +\snippet doc/src/snippets/declarative/events.qml signal declaration +\snippet doc/src/snippets/declarative/events.qml parent end + +If the signal has no parameters, the "\c{()}" brackets are optional. If +parameters are used, the parameter types must be declared, as for the \c string +and \c variant arguments of the \c perform signal. + +Adding a signal to an item automatically adds a \e{signal handler} as well. The +signal hander is named \c on, with the first letter of the signal in +uppercase. The previous signals have the following signal handlers: +\snippet doc/src/snippets/declarative/events.qml signal handler declaration + +Further, each QML properties have a \c{Changed} signal and its +corresponding \c{onChanged} signal handler. As a result, property +changes may notify other components for any changes. +\snippet doc/src/snippets/declarative/events.qml automatic signals + +To emit a signal, invoke it as a method. The signal handler binding is similar +to a property binding and it is invoked when the signal is emitted. Use the +defined argument names to access the respective arguments. +\snippet doc/src/snippets/declarative/events.qml signal emit +Note that the \c Component.onCompleted is an +\l{attached-signalhandlers}{attached signal handler}; it is invoked when the +\l Component initialization is complete. + +\keyword qml-connect-signals-to-method +\section2 Connecting Signals to Methods and Signals + +Signal objects have a \c connect() method to a connect a signal either 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 \l{Signals & Slots}{Qt slots}.) This enables a signal +to be received by a method instead of a \l {Signal Handlers}{signal handler}. + +\snippet doc/src/snippets/declarative/events.qml connect method +The \c {connect()} method is appropriate when connecting a JavaScript method, +such as the \c {callee}'s\c answer method, to QML signals. + +The corresponding \c disconnect() method is for removing connected +signals. The following code removes the connection created in \c application.qml above: +\snippet doc/src/snippets/declarative/events.qml disconnect method + +\section3 Signal to Signal Connect + +By connecting signals to other signals, the \c connect() method can form different +signal chains. +\snippet doc/src/snippets/declarative/events.qml parent begin +\snippet doc/src/snippets/declarative/events.qml forward signal +\snippet doc/src/snippets/declarative/events.qml parent end + +Whenever the \l MouseArea \c clicked signal is emitted, the \c widgetClicked +signal will automatically be emitted as well. + +\code +output: + MouseArea clicked + Widget clicked +\endcode + +\section1 C++ additions + +Because QML uses Qt, a signal defined in C++ also works as a QML signal. The +signal may be emitted in QML code or called as a method. In addition, the QML +runtime automatically creates signal handlers for the C++ signals. For more +signal control, the \c connect() method and the \l Connect element may connect a +C++ to another signal or method. */ diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc index 78865a1..0d02f4d 100644 --- a/doc/src/declarative/qmlreusablecomponents.qdoc +++ b/doc/src/declarative/qmlreusablecomponents.qdoc @@ -34,23 +34,24 @@ \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. +A \e component is an instantiable QML definition, typically contained in a +\c .qml file. For instance, a Button \e component may be defined in +\c Button.qml. The QML runtime may instantiate this Button component to create +Button \e objects. Alternatively, a component may be defined inside a +\l Component element. +Moreover, the Button definition may also contain other components. A Button +component could use a Text element for its label and other components to +implement its functions. Compounding components to form new components +(and effectively new interfaces) is the emphasis in QML. \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 ".qml" where - 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. +Any snippet of QML code may become a component, by placing the code in a QML +file (extension is \c .qml). An inline component definition may also reside in a +\l Component element. + +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml document 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 @@ -80,418 +81,6 @@ filesystems. It is recommended the file name case matches the case of the QML co 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 [: 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 syntax, and default to an empty -list: - -\qml -property list 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 onChanged 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 : -\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 - . - -\endcode - -where must refer to an object id within the same component as the type -declaring the alias, and, optionally, 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 ([[, ...]]) { } -\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 [([ [, ...]])] -\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, 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. +\section1 Loading a Component */ diff --git a/doc/src/declarative/qmlsyntax.qdoc b/doc/src/declarative/qmlsyntax.qdoc index 908b924..67d282a 100644 --- a/doc/src/declarative/qmlsyntax.qdoc +++ b/doc/src/declarative/qmlsyntax.qdoc @@ -30,7 +30,7 @@ \title QML Syntax \ingroup QML Features \previouspage QML Features -\nextpage Property Binding +\nextpage QML Basic Elements \contentspage QML Features \tableofcontents diff --git a/doc/src/declarative/qmltexthandling.qdoc b/doc/src/declarative/qmltexthandling.qdoc index c5a6bc9..e0d9b0f 100644 --- a/doc/src/declarative/qmltexthandling.qdoc +++ b/doc/src/declarative/qmltexthandling.qdoc @@ -35,8 +35,6 @@ \tableofcontents -\section1 Introduction - \section1 Text Elements \list @@ -52,4 +50,25 @@ \o \l{RegExpValidator} \endlist +\section1 Displaying Text in QML +QML provides several elements to display text onto the screen. The \l Text +element will display formatted text onto the screen, the \l TextEdit element +will place a multiline line edit onto the screen, and the \l TextInput will +place a single editable line field onto the screen. + +To learn more about their specific features and properties, visit their +respective element documentation. + +\section1 Validating Input Text +The \l {Validators}{validator} elements enforce the type and format of +\l TextInput objects. + +\snippet doc/src/snippets/declarative/texthandling.qml int validator +The validator elements bind to \c {TextInput}'s \c validator property. + +\snippet doc/src/snippets/declarative/texthandling.qml regexp validator +The regular expression in the snippet will only allow the inputted text to be +\c {fruit basket}. The \l {QRegExp} class has more information about Qt's +regular expressions. + */ diff --git a/doc/src/declarative/qmlviews.qdoc b/doc/src/declarative/qmlviews.qdoc index 3f74214..c207d9a 100644 --- a/doc/src/declarative/qmlviews.qdoc +++ b/doc/src/declarative/qmlviews.qdoc @@ -35,21 +35,8 @@ \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. +Views are containers for collections of items. They are feature-rich and can be +customizable to meet style or behavior requirements. A set of standard views are provided in the basic set of Qt Quick graphical elements: @@ -58,13 +45,21 @@ graphical elements: \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 +\o \l{WebView}{WebView} - available from the Qt WebKit module. + \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 +\section1 Models + +Views display a \l{qml-data-models}{models} onto the screen. A model could be a simple list of \l{QML Data Models#An Integer}{integer} or a \l{qml-c++-models}{C++ models}. + +To assign a model to a view, bind the view's \c model property to a model. + +\section1 ListView \l ListView shows a classic list of items with horizontal or vertical placing of items. -- cgit v0.12 From 3e6d65fb2180c2a85db01d541c39f491ae63479d Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Mon, 7 Feb 2011 18:36:33 +0100 Subject: Fixed merge conflict in Copyright date. --- doc/src/declarative/qmlevents.qdoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/src/declarative/qmlevents.qdoc b/doc/src/declarative/qmlevents.qdoc index 8c2147a..277d811 100644 --- a/doc/src/declarative/qmlevents.qdoc +++ b/doc/src/declarative/qmlevents.qdoc @@ -1,10 +1,6 @@ /**************************************************************************** ** -<<<<<<< HEAD ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). -======= -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). ->>>>>>> d7a91cfe8683309883694fbbf508e5fc42d44165 ** All rights reserved. ** Contact: Nokia Corporation (qt-info@nokia.com) ** -- cgit v0.12 From abd7455260d90120a11615526b483600774831b9 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Mon, 7 Feb 2011 19:17:18 +0100 Subject: Added the commit template to this repository --- .commit-template | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.commit-template b/.commit-template index 6e0e3a4..589ca89 100644 --- a/.commit-template +++ b/.commit-template @@ -5,6 +5,6 @@ # ---[ Fields ]-----------------[ uncomment and edit as applicable ]---| #Task-number: -Reviewed-by: pending +#Reviewed-by: # ==================================[ please wrap at 72 characters ]===| -- cgit v0.12 From 8f38531acc8139bcbee158458086ab012cb200b6 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Mon, 7 Feb 2011 19:19:14 +0100 Subject: Adding validator snippet. Task-number: QTBUG-16071 --- doc/src/snippets/declarative/texthandling.qml | 89 +++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 doc/src/snippets/declarative/texthandling.qml diff --git a/doc/src/snippets/declarative/texthandling.qml b/doc/src/snippets/declarative/texthandling.qml new file mode 100644 index 0000000..377bb8b --- /dev/null +++ b/doc/src/snippets/declarative/texthandling.qml @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +import QtQuick 1.0 + + +//! [parent begin] +Rectangle { +//! [parent begin] + width: 300; height: 300 + id: screen + +Column { + anchors.centerIn:parent + +//! [int validator] +Column { + spacing: 10 + + Text { + text: "Enter a value from 0 to 2000" + } + TextInput { + focus: true + validator: IntValidator { bottom:0; top: 2000} + } +} +//! [int validator] + +//! [regexp validator] +Column { + spacing: 10 + + Text { + text: "Which basket?" + } + TextInput { + focus: true + validator: RegExpValidator { regExp: /fruit basket/ } + } +} +//! [regexp validator] + +//end of column +} + +//! [parent end] +} +//! [parent end] + +//! [document] + -- cgit v0.12 From b18e040ecb0ce6dea9c0d18f1c8a5542cd0e2881 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Tue, 8 Feb 2011 09:55:32 +0100 Subject: Changed states.qml snippet code Task-number: QTBUG-16071 --- doc/src/snippets/declarative/states.qml | 85 ++++++++++++++++++++++++++++----- 1 file changed, 73 insertions(+), 12 deletions(-) diff --git a/doc/src/snippets/declarative/states.qml b/doc/src/snippets/declarative/states.qml index c3b7197..ab6b8d0 100644 --- a/doc/src/snippets/declarative/states.qml +++ b/doc/src/snippets/declarative/states.qml @@ -37,24 +37,85 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ -//![0] +//![document] import QtQuick 1.0 - + +//![parent begin] Rectangle { - id: myRect - width: 200; height: 200 - color: "red" +//![parent begin] + + id: screen + width: 400; height: 500 - MouseArea { - anchors.fill: parent - onClicked: myRect.state = 'moved' - } + +Rectangle { + id: flag +} +Column { + spacing: 15 +//![signal states] +Rectangle { + id: signal + width: 200; height: 200 + state: "NORMAL" states: [ State { - name: "moved" - PropertyChanges { target: myRect; x: 50; y: 50 } + name: "NORMAL" + PropertyChanges { target: signal; color: "green"} + PropertyChanges { target: flag; state: "FLAG_DOWN"} + }, + State { + name: "CRITICAL" + PropertyChanges { target: signal; color: "red"} + PropertyChanges { target: flag; state: "FLAG_UP"} } ] } -//![0] +//![signal states] + +//![switch states] +Rectangle { + id: signalswitch + width: 75; height: 75 + color: "blue" + + MouseArea { + anchors.fill: parent + onClicked: { + if (signal.state == "NORMAL") + signal.state = "CRITICAL" + else + signal.state = "NORMAL" + } + } +} +//![switch states] + +//![when property] +Rectangle { + id: bell + width: 75; height: 75 + color: "yellow" + + states: State { + name: "RINGING" + when: (signal.state == "CRITICAL") + PropertyChanges {target: speaker; play: "RING!"} + } +} +//![when property] + +Text { + id: speaker + property alias play: speaker.text + text: "NORMAL" +} + +} // end of row + +//![parent end] +} +//![parent end] + +//![document] -- cgit v0.12 From 21158b42fda8a144eb50381f62369e3b3558c83f Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Tue, 8 Feb 2011 12:39:36 +0100 Subject: Changed snippet code and edited event overview Task-number: QTBUG-16071 --- doc/src/declarative/qmlevents.qdoc | 22 ++--- doc/src/snippets/declarative/events.qml | 141 ++++++++++++++++++++++++++++++++ 2 files changed, 150 insertions(+), 13 deletions(-) create mode 100644 doc/src/snippets/declarative/events.qml diff --git a/doc/src/declarative/qmlevents.qdoc b/doc/src/declarative/qmlevents.qdoc index 277d811..7d5e962 100644 --- a/doc/src/declarative/qmlevents.qdoc +++ b/doc/src/declarative/qmlevents.qdoc @@ -54,9 +54,7 @@ signal [([ [, ...]])] \endqml 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.) +block generates 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 various examples of signal declarations: \snippet doc/src/snippets/declarative/events.qml parent begin @@ -96,31 +94,29 @@ QML are created as \l{Signals & Slots}{Qt slots}.) This enables a signal to be received by a method instead of a \l {Signal Handlers}{signal handler}. \snippet doc/src/snippets/declarative/events.qml connect method -The \c {connect()} method is appropriate when connecting a JavaScript method, -such as the \c {callee}'s\c answer method, to QML signals. +The \c {connect()} method is appropriate when connecting a JavaScript method to +a signal. -The corresponding \c disconnect() method is for removing connected -signals. The following code removes the connection created in \c application.qml above: -\snippet doc/src/snippets/declarative/events.qml disconnect method +There is a corresponding \c disconnect() method for removing connected +signals. \section3 Signal to Signal Connect By connecting signals to other signals, the \c connect() method can form different signal chains. -\snippet doc/src/snippets/declarative/events.qml parent begin \snippet doc/src/snippets/declarative/events.qml forward signal -\snippet doc/src/snippets/declarative/events.qml parent end -Whenever the \l MouseArea \c clicked signal is emitted, the \c widgetClicked + +Whenever the \l MouseArea \c clicked signal is emitted, the \c send signal will automatically be emitted as well. \code output: MouseArea clicked - Widget clicked + Send clicked \endcode -\section1 C++ additions +\section1 C++ Additions Because QML uses Qt, a signal defined in C++ also works as a QML signal. The signal may be emitted in QML code or called as a method. In addition, the QML diff --git a/doc/src/snippets/declarative/events.qml b/doc/src/snippets/declarative/events.qml new file mode 100644 index 0000000..52fc2bc --- /dev/null +++ b/doc/src/snippets/declarative/events.qml @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//![document] +import QtQuick 1.0 + +//![parent begin] +Rectangle { +//![parent begin] + + id: screen + width: 400; height: 500 + +//! [signal declaration] + signal trigger + signal send (string notice) + signal perform (string task, variant object) +//! [signal declaration] + +//! [signal handler declaration] +onTrigger: console.log("trigger signal emitted") + +onSend: { + console.log("send signal emitted with notice: " + notice) +} + +onPerform: console.log("perform signal emitted") +//! [signal handler declaration] + +//! [automatic signals] +Rectangle { + id: sprite + width: 25; height: 25 + x: 50; y: 15 + + onXChanged: console.log("x property changed, emitted xChanged signal") + onYChanged: console.log("y property changed, emitted yChanged signal") +} +//! [automatic signals] + +//! [signal emit] +Rectangle { + id: messenger + + signal send( string person, string notice) + + onSend: { + console.log("For " + person + ", the notice is: " + notice) + } + + Component.onCompleted: messenger.send("Tom", "the door is ajar.") +} +//! [signal emit] + +//! [connect method] +Rectangle { + id: relay + + signal send( string person, string notice) + onSend: console.log("Send signal to: " + person + ", " + notice) + + Component.onCompleted: { + relay.send.connect(sendToPost) + relay.send.connect(sendToTelegraph) + relay.send.connect(sendToEmail) + relay.send("Tom", "Happy Birthday") + } + + function sendToPost(person, notice) { + console.log("Sending to post: " + person + ", " + notice) + } + function sendToTelegraph(person, notice) { + console.log("Sending to telegraph: " + person + ", " + notice) + } + function sendToEmail(person, notice) { + console.log("Sending to email: " + person + ", " + notice) + } +} +//! [connect method] + +//! [forward signal] +Rectangle { + id: forwarder + width: 100; height: 100 + + signal send() + onSend: console.log("Send clicked") + + MouseArea { + id: mousearea + anchors.fill: parent + onClicked: console.log("MouseArea clicked") + } + Component.onCompleted: { + mousearea.clicked.connect(send) + } +} +//! [forward signal] + +//! [connect method] +//![parent end] +} +//![parent end] + +//![document] -- cgit v0.12 From 1ca36f6539ffeb8581d38d677d1972ca4db58bf4 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Tue, 8 Feb 2011 16:15:17 +0100 Subject: Rewrote "Importing Reusable Components" documentation. Added snippet code, and replaced the text. Task-number: QTBUG-16071 --- doc/src/declarative/qmlreusablecomponents.qdoc | 74 ++++++++++++++++----- .../declarative/reusablecomponents/Button.qml | 71 ++++++++++++++++++++ .../declarative/reusablecomponents/application.qml | 55 ++++++++++++++++ .../declarative/reusablecomponents/component.qml | 77 ++++++++++++++++++++++ .../snippets/declarative/reusablecomponents/qmldir | 4 ++ 5 files changed, 264 insertions(+), 17 deletions(-) create mode 100644 doc/src/snippets/declarative/reusablecomponents/Button.qml create mode 100644 doc/src/snippets/declarative/reusablecomponents/application.qml create mode 100644 doc/src/snippets/declarative/reusablecomponents/component.qml create mode 100644 doc/src/snippets/declarative/reusablecomponents/qmldir diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc index 0d02f4d..0fd5515 100644 --- a/doc/src/declarative/qmlreusablecomponents.qdoc +++ b/doc/src/declarative/qmlreusablecomponents.qdoc @@ -45,35 +45,71 @@ component could use a Text element for its label and other components to implement its functions. Compounding components to form new components (and effectively new interfaces) is the emphasis in QML. +\keyword qml-define-components \section1 Defining New Components Any snippet of QML code may become a component, by placing the code in a QML -file (extension is \c .qml). An inline component definition may also reside in a -\l Component element. - +file (extension is \c .qml). A complete Button component that responds to user +input may be in a Button.qml file. \snippet doc/src/snippets/declarative/reusablecomponents/Button.qml document -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: +Alternatively, a \l Component element may encapsulate a QML object to form a +component. +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent begin +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml parent end -\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0 +\keyword qml-loading-components +\section1 Loading a Component -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: +The initialization of inline components is different from loading a component +from a \c .qml file. -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0 -\o \image qml-extending-types.png -\endtable +\section2 Importing a Component + +A component defined in a \c .qml file is directly usable by declaring the name +of the component. For example, a button defined in \c Button.qml is created by +declaring a \c Button. The button is defined in the +\l {qml-define-components}{Defining New Components} section. +\snippet doc/src/snippets/declarative/reusablecomponents/application.qml document + +Note that the component name, \c Button, matches the QML filename, \c Button.qml. +Specifically, the first character is in upper case. Matching the names allow +components in the same directory to be in the direct import path of the +application. + +For flexibility, a \c qmldir file is for dictating which additional components, +plugins, or directories should be imported. By using a \c qmldir file, +component names do not need to match the filenames. The \c qmldir file should, +however, in an imported path. +\snippet doc/src/snippets/declarative/reusablecomponents/qmldir document + +\section2 Loading an Inline Component + +A consequence of inline components is that initialization may be deferred or +delayed. A component may be created during a MouseArea event or by using a +\l Loader element. The component can create an object, which is addressable in a +similar way as an \l {qml-id-propert}{id property}. Thus, the created object may +have its bindings set and read like a normal QML object. +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component +\snippet doc/src/snippets/declarative/reusablecomponents/component.qml create inline component + +\keyword qml-component-properties +\section1 Component Properties + +Initializing a component, either from a .qml file or initializing an inline +component, have several properties to facilitate component execution. +Specifically, there are \l{attached-properties}{attached properties} and +\l{attached-signalhandlers}{attached signal handlers} for setting properties +during the lifetime of a component. + +*/ 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) @@ -81,6 +117,10 @@ filesystems. It is recommended the file name case matches the case of the QML co exactly - for example, \c Box.qml and not \c BoX.qml - regardless of the platform to which the QML component will be deployed. -\section1 Loading a Component +\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0 +\table +\row +\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0 +\o \image qml-extending-types.png +\endtable -*/ diff --git a/doc/src/snippets/declarative/reusablecomponents/Button.qml b/doc/src/snippets/declarative/reusablecomponents/Button.qml new file mode 100644 index 0000000..955e73a --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/Button.qml @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +//contents of Button.qml +import QtQuick 1.0 + +Rectangle { + width: 145; height: 60 + color: "blue" + smooth: true; radius: 9 + property alias text: label.text + + border {color: "#B9C5D0"; width: 1} + + gradient: Gradient { + GradientStop {color: "#CFF7FF"; position: 0.0} + GradientStop {color: "#99C0E5"; position: 0.57} + GradientStop {color: "#719FCB"; position: 0.9} + } + + Text { + id: label + anchors.centerIn: parent + text: "Click Me!" + font.pointSize: 12 + color: "blue" + } + + MouseArea { + anchors.fill: parent + onClicked: console.log(text + " clicked") + } +} +//! [document] diff --git a/doc/src/snippets/declarative/reusablecomponents/application.qml b/doc/src/snippets/declarative/reusablecomponents/application.qml new file mode 100644 index 0000000..094134f --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/application.qml @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +import QtQuick 1.0 + +Rectangle { + width: 175; height: 350 + color: "lightgrey" + + Column { + anchors.centerIn: parent + spacing: 15 + Button {} + Button {text: "Click Me Too!"} + Button {text: "Click Me Three!"} + } +} +//! [document] diff --git a/doc/src/snippets/declarative/reusablecomponents/component.qml b/doc/src/snippets/declarative/reusablecomponents/component.qml new file mode 100644 index 0000000..88fc9b1 --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/component.qml @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +import QtQuick 1.0 + +//! [parent begin] +Rectangle { +//! [parent begin] + id: screen + width: 175; height: 175 + color: "lightgrey" + +//! [define inline component] + Component { + id: inlinecomponent + Rectangle { + id: display + width: 50; height: 50 + color: "blue" + } + } +//! [define inline component] +//! [create inline component] + MouseArea { + anchors.fill: parent + onClicked: { + inlinecomponent.createObject(screen) + + var second = inlinecomponent.createObject(screen) + + var third = inlinecomponent.createObject(screen) + third.x = second.width + 10 + third.color = "red" + } + } +//! [create inline component] +//! [parent end] +} +//! [parent end] +//! [document] diff --git a/doc/src/snippets/declarative/reusablecomponents/qmldir b/doc/src/snippets/declarative/reusablecomponents/qmldir new file mode 100644 index 0000000..93b53f9 --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/qmldir @@ -0,0 +1,4 @@ +//! [document] +Button ./Button.qml 1.0 +SimpleButton ./simplebutton.qml +//! [document] -- cgit v0.12 From 69500fc302cd52033a058c601bdbad3a31ed2971 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 10 Feb 2011 11:47:35 +0100 Subject: Added keyword to the QML property binding documentation. Task-number: QTBUG-16071 --- doc/src/declarative/propertybinding.qdoc | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 00ff650..2bce0c5 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -112,6 +112,7 @@ will get an error. Certain properties bind to more complex types such as other elements and objects. +\keyword qml-basic-property-types \section2 Basic Property Types Basic types such as \l int, \l real, and other Qt structures may be bound to -- cgit v0.12 From 208715da3f06a862081f86548348518f9bc63177 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 10 Feb 2011 11:50:17 +0100 Subject: Re-wrote QML Reusable Components documentation Task-number: QTBUG-16071 --- doc/src/declarative/basicelements.qdoc | 9 -- doc/src/declarative/qmlreusablecomponents.qdoc | 40 ++++++++- .../declarative/reusablecomponents/Button.qml | 15 +++- .../declarative/reusablecomponents/application.qml | 8 +- .../declarative/reusablecomponents/component.qml | 6 +- .../declarative/reusablecomponents/focusbutton.qml | 98 ++++++++++++++++++++++ .../snippets/declarative/reusablecomponents/qmldir | 4 +- 7 files changed, 159 insertions(+), 21 deletions(-) create mode 100644 doc/src/snippets/declarative/reusablecomponents/focusbutton.qml diff --git a/doc/src/declarative/basicelements.qdoc b/doc/src/declarative/basicelements.qdoc index 5997998..ad53ea4 100644 --- a/doc/src/declarative/basicelements.qdoc +++ b/doc/src/declarative/basicelements.qdoc @@ -109,15 +109,6 @@ the component will retain the top-level component's properties. If a non-visual component is the top-level component, the visual properties should be aliased to the top-level to display the component properly. -A component implemented using a \c Rectangle as the top-level component: -\snippet doc/src/snippets/declarative/focus/mywidget.qml document - -A component that uses a \c FocusScope as the top-level component: -\snippet doc/src/snippets/declarative/focus/myfocusscopewidget.qml document -Note that the visual properties need to be passed to the parent. The -\l {Keyboard Focus in QML}{focus} article provides more details about the -\c FocusScope element. - For more information on how to build upon QML elements, see the \l{Importing Reusable Components} document. */ diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc index 0fd5515..956fa24 100644 --- a/doc/src/declarative/qmlreusablecomponents.qdoc +++ b/doc/src/declarative/qmlreusablecomponents.qdoc @@ -74,14 +74,14 @@ declaring a \c Button. The button is defined in the \snippet doc/src/snippets/declarative/reusablecomponents/application.qml document Note that the component name, \c Button, matches the QML filename, \c Button.qml. -Specifically, the first character is in upper case. Matching the names allow +Also, the first character is in upper case. Matching the names allow components in the same directory to be in the direct import path of the application. For flexibility, a \c qmldir file is for dictating which additional components, plugins, or directories should be imported. By using a \c qmldir file, component names do not need to match the filenames. The \c qmldir file should, -however, in an imported path. +however, be in an imported path. \snippet doc/src/snippets/declarative/reusablecomponents/qmldir document \section2 Loading an Inline Component @@ -103,6 +103,42 @@ Specifically, there are \l{attached-properties}{attached properties} and \l{attached-signalhandlers}{attached signal handlers} for setting properties during the lifetime of a component. +The \c{Component.onCompleted} attached signal handler is called when the +component completes initialization. It is useful for executing any commands +after component initialization. Similarly, the \c{Component.onDestruction} +signal handler executes when the component finishes destruction. + +\keyword qml-top-level +\section1 Top-Level Component + +Choosing the \e{top-level} or the \e{root} object of components is an important +design aspect because the top-level object dictates which properties are +accessible outside the component. Some elements are not visual elements and +will not have visual properties exposed outside the component. Likewise, some +elements add functionality that are not available to visual elements. + +Consider the Button component from the +\l{qml-define-components}{Defining New Components} section; it's top-level +object is a \l Rectangle. When imported, the Button component will possess the +Rectangle's properties, methods, signals, and any custom properties. + +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent begin +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml properties +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml ellipses +\snippet doc/src/snippets/declarative/reusablecomponents/Button.qml parent end + +The Button's \c text alias is accessible from outside the component as well as +the Rectangle's visual properties and signals such as \c x, \c y, \c anchors, +and \c states. + +Alternatively, we may choose a \l {Keyboard Focus in QML}{FocusScope} as our +top-level object. The \l FocusScope element manage keyboard focus for its +children which is beneficial for certain types of interfaces. However, since +\c FocusScopes are not visual elements, the visual properties of its child need +to be exposed. + +\snippet doc/src/snippets/declarative/reusablecomponents/focusbutton.qml document */ The root object in \c Button.qml defines the attributes that are available to users of the diff --git a/doc/src/snippets/declarative/reusablecomponents/Button.qml b/doc/src/snippets/declarative/reusablecomponents/Button.qml index 955e73a..3b97e00 100644 --- a/doc/src/snippets/declarative/reusablecomponents/Button.qml +++ b/doc/src/snippets/declarative/reusablecomponents/Button.qml @@ -41,12 +41,16 @@ //contents of Button.qml import QtQuick 1.0 +//! [parent begin] Rectangle { +//! [parent begin] + id: button +//! [properties] width: 145; height: 60 color: "blue" smooth: true; radius: 9 property alias text: label.text - +//! [properties] border {color: "#B9C5D0"; width: 1} gradient: Gradient { @@ -67,5 +71,14 @@ Rectangle { anchors.fill: parent onClicked: console.log(text + " clicked") } +//! [parent end] } +//! [parent end] + //! [document] + +//! [ellipses] + //... +//! [ellipses] + + diff --git a/doc/src/snippets/declarative/reusablecomponents/application.qml b/doc/src/snippets/declarative/reusablecomponents/application.qml index 094134f..a09b276 100644 --- a/doc/src/snippets/declarative/reusablecomponents/application.qml +++ b/doc/src/snippets/declarative/reusablecomponents/application.qml @@ -45,11 +45,11 @@ Rectangle { color: "lightgrey" Column { - anchors.centerIn: parent - spacing: 15 + anchors.centerIn: parent + spacing: 15 Button {} - Button {text: "Click Me Too!"} - Button {text: "Click Me Three!"} + Button {text: "Me Too!"} + Button {text: "Me Three!"} } } //! [document] diff --git a/doc/src/snippets/declarative/reusablecomponents/component.qml b/doc/src/snippets/declarative/reusablecomponents/component.qml index 88fc9b1..8660c50 100644 --- a/doc/src/snippets/declarative/reusablecomponents/component.qml +++ b/doc/src/snippets/declarative/reusablecomponents/component.qml @@ -61,11 +61,11 @@ Rectangle { MouseArea { anchors.fill: parent onClicked: { - inlinecomponent.createObject(screen) + inlinecomponent.createObject(parent) - var second = inlinecomponent.createObject(screen) + var second = inlinecomponent.createObject(parent) - var third = inlinecomponent.createObject(screen) + var third = inlinecomponent.createObject(parent) third.x = second.width + 10 third.color = "red" } diff --git a/doc/src/snippets/declarative/reusablecomponents/focusbutton.qml b/doc/src/snippets/declarative/reusablecomponents/focusbutton.qml new file mode 100644 index 0000000..2522a98 --- /dev/null +++ b/doc/src/snippets/declarative/reusablecomponents/focusbutton.qml @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +//contents of focusbutton.qml +import QtQuick 1.0 + +//! [parent begin] +FocusScope { +//! [parent begin] + + //! [expose visuals] + //FocusScope needs to bind to visual properties of the children + property alias color: button.color + x: button.x; y: button.y + width: button.width; height: button.height + //! [expose visuals] + + //! [rectangle begin] + Rectangle { + //! [rectangle begin] + id: button + //! [properties] + width: 145; height: 60 + color: "blue" + smooth: true; radius: 9 + property alias text: label.text + //! [properties] + border {color: "#B9C5D0"; width: 1} + + gradient: Gradient { + GradientStop {color: "#CFF7FF"; position: 0.0} + GradientStop {color: "#99C0E5"; position: 0.57} + GradientStop {color: "#719FCB"; position: 0.9} + } + + Text { + id: label + anchors.centerIn: parent + text: "Click Me!" + font.pointSize: 12 + color: "blue" + } + + MouseArea { + anchors.fill: parent + onClicked: console.log(text + " clicked") + } + //! [rectangle end] + } + //! [rectangle end] +//! [parent end] +} +//! [parent end] + +//! [document] + +//! [ellipses] + //... +//! [ellipses] + + diff --git a/doc/src/snippets/declarative/reusablecomponents/qmldir b/doc/src/snippets/declarative/reusablecomponents/qmldir index 93b53f9..253732d 100644 --- a/doc/src/snippets/declarative/reusablecomponents/qmldir +++ b/doc/src/snippets/declarative/reusablecomponents/qmldir @@ -1,4 +1,4 @@ //! [document] -Button ./Button.qml 1.0 -SimpleButton ./simplebutton.qml +Button ./Button.qml +FocusButton ./focusbutton.qml //! [document] -- cgit v0.12 From 4ed49df2e4182cf078c1fac3cd739bd8f15412b1 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 10 Feb 2011 11:51:21 +0100 Subject: Fixed link in QML overview page. Task-number: QTBUG-16071 --- doc/src/overviews.qdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/overviews.qdoc b/doc/src/overviews.qdoc index f257045..b1fdad1 100644 --- a/doc/src/overviews.qdoc +++ b/doc/src/overviews.qdoc @@ -173,7 +173,7 @@ \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 Mouse Events}{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} -- cgit v0.12 From e61abd249d4148c05b6c24ff787ff98978bbc2f9 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 10 Feb 2011 11:53:00 +0100 Subject: Noted that QML uses JavaScript based regexp Task-number: QTBUG-16071 --- doc/src/declarative/qmltexthandling.qdoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/src/declarative/qmltexthandling.qdoc b/doc/src/declarative/qmltexthandling.qdoc index e0d9b0f..7906193 100644 --- a/doc/src/declarative/qmltexthandling.qdoc +++ b/doc/src/declarative/qmltexthandling.qdoc @@ -68,7 +68,9 @@ The validator elements bind to \c {TextInput}'s \c validator property. \snippet doc/src/snippets/declarative/texthandling.qml regexp validator The regular expression in the snippet will only allow the inputted text to be -\c {fruit basket}. The \l {QRegExp} class has more information about Qt's -regular expressions. +\c {fruit basket}. + +Note that QML parses JavaScript regular expressions, while Qt's +\l {QRegExp} class' regular expressions are based on Perl regular expressions. */ -- cgit v0.12 From 43e661faa5d27d694d5fc769a4fe4a24a650cc2d Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Tue, 15 Feb 2011 13:27:41 +0100 Subject: Removed unused snippet code. Changed reference to snippet. Task-number: QTBUG-16071 --- doc/src/declarative/positioners.qdoc | 2 +- doc/src/snippets/declarative/grid-spacing.qml | 60 ++++++++++++++++++++++ doc/src/snippets/declarative/grid/grid-items.qml | 58 --------------------- .../snippets/declarative/grid/grid-no-spacing.qml | 57 -------------------- doc/src/snippets/declarative/grid/grid-spacing.qml | 60 ---------------------- doc/src/snippets/declarative/grid/grid.qml | 53 ------------------- 6 files changed, 61 insertions(+), 229 deletions(-) create mode 100644 doc/src/snippets/declarative/grid-spacing.qml delete mode 100644 doc/src/snippets/declarative/grid/grid-items.qml delete mode 100644 doc/src/snippets/declarative/grid/grid-no-spacing.qml delete mode 100644 doc/src/snippets/declarative/grid/grid-spacing.qml delete mode 100644 doc/src/snippets/declarative/grid/grid.qml diff --git a/doc/src/declarative/positioners.qdoc b/doc/src/declarative/positioners.qdoc index 66d2973..c91ed9a 100644 --- a/doc/src/declarative/positioners.qdoc +++ b/doc/src/declarative/positioners.qdoc @@ -102,7 +102,7 @@ in a 2-by-2 grid. As with the other positioners, the spacing between items can be specified using the \l{Grid::spacing}{spacing} property. \clearfloat -\snippet doc/src/snippets/declarative/grid/grid-spacing.qml document +\snippet doc/src/snippets/declarative/grid-spacing.qml document There is no difference between horizontal and vertical spacing inserted between items, so any additional space must be added within the items diff --git a/doc/src/snippets/declarative/grid-spacing.qml b/doc/src/snippets/declarative/grid-spacing.qml new file mode 100644 index 0000000..8914ce3 --- /dev/null +++ b/doc/src/snippets/declarative/grid-spacing.qml @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import QtQuick 1.0 + +Rectangle { + width: 112; height: 112 + color: "#303030" + + Grid { + anchors.horizontalCenter: parent.horizontalCenter + anchors.verticalCenter: parent.verticalCenter + columns: 2 + spacing: 6 + + Rectangle { color: "#aa6666"; width: 50; height: 50 } + Rectangle { color: "#aaaa66"; width: 50; height: 50 } + Rectangle { color: "#9999aa"; width: 50; height: 50 } + Rectangle { color: "#6666aa"; width: 50; height: 50 } + } +} +//! [document] diff --git a/doc/src/snippets/declarative/grid/grid-items.qml b/doc/src/snippets/declarative/grid/grid-items.qml deleted file mode 100644 index 3c60d12..0000000 --- a/doc/src/snippets/declarative/grid/grid-items.qml +++ /dev/null @@ -1,58 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - width: 112; height: 112 - color: "#303030" - - Grid { - anchors.horizontalCenter: parent.horizontalCenter - anchors.verticalCenter: parent.verticalCenter - columns: 2 - spacing: 6 - - Rectangle { color: "#aa6666"; width: 50; height: 50 } - Rectangle { color: "#aaaa66"; width: 50; height: 50 } - Rectangle { color: "#9999aa"; width: 50; height: 50 } - Rectangle { color: "#6666aa"; width: 50; height: 50 } - } -} diff --git a/doc/src/snippets/declarative/grid/grid-no-spacing.qml b/doc/src/snippets/declarative/grid/grid-no-spacing.qml deleted file mode 100644 index 7c8b0f8..0000000 --- a/doc/src/snippets/declarative/grid/grid-no-spacing.qml +++ /dev/null @@ -1,57 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - width: 112; height: 112 - color: "#303030" - - Grid { - anchors.horizontalCenter: parent.horizontalCenter - anchors.verticalCenter: parent.verticalCenter - columns: 2 - - Rectangle { color: "#aa6666"; width: 50; height: 50 } - Rectangle { color: "#aaaa66"; width: 50; height: 50 } - Rectangle { color: "#9999aa"; width: 50; height: 50 } - Rectangle { color: "#6666aa"; width: 50; height: 50 } - } -} diff --git a/doc/src/snippets/declarative/grid/grid-spacing.qml b/doc/src/snippets/declarative/grid/grid-spacing.qml deleted file mode 100644 index 8914ce3..0000000 --- a/doc/src/snippets/declarative/grid/grid-spacing.qml +++ /dev/null @@ -1,60 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - width: 112; height: 112 - color: "#303030" - - Grid { - anchors.horizontalCenter: parent.horizontalCenter - anchors.verticalCenter: parent.verticalCenter - columns: 2 - spacing: 6 - - Rectangle { color: "#aa6666"; width: 50; height: 50 } - Rectangle { color: "#aaaa66"; width: 50; height: 50 } - Rectangle { color: "#9999aa"; width: 50; height: 50 } - Rectangle { color: "#6666aa"; width: 50; height: 50 } - } -} -//! [document] diff --git a/doc/src/snippets/declarative/grid/grid.qml b/doc/src/snippets/declarative/grid/grid.qml deleted file mode 100644 index 758edde..0000000 --- a/doc/src/snippets/declarative/grid/grid.qml +++ /dev/null @@ -1,53 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Grid { - columns: 3 - spacing: 2 - Rectangle { color: "red"; width: 50; height: 50 } - Rectangle { color: "green"; width: 20; height: 50 } - Rectangle { color: "blue"; width: 50; height: 20 } - Rectangle { color: "cyan"; width: 50; height: 50 } - Rectangle { color: "magenta"; width: 10; height: 10 } -} -//! [document] -- cgit v0.12 From 878a204b24a69f989b6fec96c7c3b232868be8d5 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Tue, 15 Feb 2011 13:56:32 +0100 Subject: Shuffled navigation and modified next/previous links. Task-number: QTBUG-16071 --- doc/src/declarative/basicelements.qdoc | 2 +- doc/src/declarative/declarativeui.qdoc | 8 ++--- doc/src/declarative/dynamicobjects.qdoc | 14 ++++---- doc/src/declarative/focus.qdoc | 2 +- doc/src/declarative/integrating.qdoc | 2 +- doc/src/declarative/qdeclarativei18n.qdoc | 2 +- doc/src/declarative/qmlreusablecomponents.qdoc | 21 +---------- doc/src/declarative/qmlsyntax.qdoc | 8 ++--- doc/src/overviews.qdoc | 50 +++++++++++++------------- 9 files changed, 42 insertions(+), 67 deletions(-) diff --git a/doc/src/declarative/basicelements.qdoc b/doc/src/declarative/basicelements.qdoc index ad53ea4..c0df307 100644 --- a/doc/src/declarative/basicelements.qdoc +++ b/doc/src/declarative/basicelements.qdoc @@ -29,7 +29,7 @@ \page qmlbasicelements.html \ingroup qml-features \contentspage QML Features -\previouspage QML Syntax +\previouspage QML Features \nextpage {QML Basic Types}{Data Types} \title QML Basic Elements diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index aa4006b..53c7da3 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -75,15 +75,15 @@ QML and the Qt Declarative Module separate the frontend UI logic from the backen \section1 QML Features \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{QML Basic Types}{Data Types} +\o \l{Property Binding} \o \l{Using QML Positioner and Repeater Items}{Component Layouts} \o \l{Anchor-based Layout in QML}{Layouts using Anchors} \o \l{QML Mouse Events}{Mouse Events} \o \l{QML Text Handling and Validators}{Text Handling and Validators} \o \l{Keyboard Focus in QML}{Keyboard Focus} +\o \l{QML Signal and Handler Event System}{Signal and Handler Event System} \o \l{Importing Reusable Components} \o \l{QML States}{States} \o \l{QML Animation and Transitions}{Animation and Transitions} @@ -92,11 +92,9 @@ QML and the Qt Declarative Module separate the frontend UI logic from the backen \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 QML Add-Ons diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index 055f437..a8339e0 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -29,7 +29,7 @@ \page qdeclarativedynamicobjects.html \ingroup qml-features \contentspage {QML Features} -\previouspage {QML Signal and Handler Event System}{Signal and Handler Event System} +\previouspage {Integrating QML Code with Existing Qt UI Code} \nextpage {Network Transparency}{Loading Resources in QML} \title Dynamic Object Management in QML @@ -66,14 +66,14 @@ To dynamically load a component defined in a QML file, call the This function takes the URL of the QML file as its only argument and creates a \l Component object from this URL. -Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of +Once you have a \l Component, you can call its \l {Component::createObject()}{createObject()} method to create an instance of the component. This function can take one or two arguments: \list -\o The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is - recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to - this function. -\o The second is optional and is a script which assigns values to the item's properties during creation. This avoids warnings - when certain properties have been bound to before they have been set by the code. Additionally, there are small performance +\o The first is the parent for the new item. Since graphical items will not appear on the scene without a parent, it is + recommended that you set the parent this way. However, if you wish to set the parent later you can safely pass \c null to + this function. +\o The second is optional and is a script which assigns values to the item's properties during creation. This avoids warnings + when certain properties have been bound to before they have been set by the code. Additionally, there are small performance benefits when instantiating objects in this way. \endlist diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc index 9a11491..940f864 100644 --- a/doc/src/declarative/focus.qdoc +++ b/doc/src/declarative/focus.qdoc @@ -31,7 +31,7 @@ \ingroup qml-features \contentspage QML Features \previouspage {QML Text Handling and Validators}{Text Handling and Validators} -\nextpage {Importing Reusable Components} +\nextpage {QML Signal and Handler Event System}{Signal and Handler Event System} \title Keyboard Focus in QML diff --git a/doc/src/declarative/integrating.qdoc b/doc/src/declarative/integrating.qdoc index 649088d..c2f55f5 100644 --- a/doc/src/declarative/integrating.qdoc +++ b/doc/src/declarative/integrating.qdoc @@ -29,7 +29,7 @@ \page qml-integration.html \ingroup qml-features \previouspage {Using QML Bindings in C++ Applications} -\nextpage {QML Signal and Handler Event System} +\nextpage {Dynamic Object Management in QML}{Dynamic Object Management} \contentspage QML Features \title Integrating QML Code with Existing Qt UI Code diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc index 756ef4b..3d97113 100644 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -30,7 +30,7 @@ \ingroup qml-features \contentspage QML Features \previouspage {Network Transparency}{Loading Resources in QML} -\nextpage {QML Graphical Effects}{Graphical Effects} +\nextpage {QML Features} \title QML Internationalization \section1 Overview diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc index 956fa24..e6c3ec9 100644 --- a/doc/src/declarative/qmlreusablecomponents.qdoc +++ b/doc/src/declarative/qmlreusablecomponents.qdoc @@ -28,7 +28,7 @@ /*! \page qmlreusablecomponents.html \ingroup qml-features -\previouspage {Keyboard Focus in QML}{Keyboard Focus} +\previouspage {QML Signal and Handler Event System}{Signal and Handler Event System} \nextpage {QML States}{States} \contentspage QML Features @@ -141,22 +141,3 @@ to be exposed. \snippet doc/src/snippets/declarative/reusablecomponents/focusbutton.qml document */ -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. - -\snippet doc/src/snippets/declarative/qml-extending-types/components/Button.qml 0 -\table -\row -\o \snippet doc/src/snippets/declarative/qml-extending-types/components/application.qml 0 -\o \image qml-extending-types.png -\endtable - diff --git a/doc/src/declarative/qmlsyntax.qdoc b/doc/src/declarative/qmlsyntax.qdoc index 67d282a..fc25bce 100644 --- a/doc/src/declarative/qmlsyntax.qdoc +++ b/doc/src/declarative/qmlsyntax.qdoc @@ -28,10 +28,8 @@ /*! \page qmlsyntax.html \title QML Syntax -\ingroup QML Features -\previouspage QML Features -\nextpage QML Basic Elements -\contentspage QML Features +\ingroup QML Reference +\contentspage QML Reference \tableofcontents @@ -67,7 +65,7 @@ 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 +Properties are specified as \c {propertyname: 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. diff --git a/doc/src/overviews.qdoc b/doc/src/overviews.qdoc index b1fdad1..6835e17 100644 --- a/doc/src/overviews.qdoc +++ b/doc/src/overviews.qdoc @@ -164,32 +164,30 @@ \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{QML Mouse Events}{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 +These are overviews of the many features of the QML language and \l{Qt Quick}. + +\list +\o \l{QML Basic Elements}{Basic Elements} +\o \l{QML Basic Types}{Data Types} +\o \l{Property Binding} +\o \l{Using QML Positioner and Repeater Items}{Component Layouts} +\o \l{Anchor-based Layout in QML}{Layouts using Anchors} +\o \l{QML Mouse Events}{Mouse Events} +\o \l{QML Text Handling and Validators}{Text Handling and Validators} +\o \l{Keyboard Focus in QML}{Keyboard Focus} +\o \l{QML Signal and Handler Event System}{Signal and Handler Event System} +\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{Dynamic Object Management in QML}{Dynamic Object Management} +\o \l{Network Transparency}{Loading Resources in QML} +\o \l{QML Internationalization}{Internationalization} +\endlist */ /*! \group qml-architecture -- cgit v0.12 From 448e5c7d787382d47efe786a5a85cce8bdcd61a4 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Tue, 15 Feb 2011 13:58:14 +0100 Subject: Edited section titles and added links to relevant sections. Task-number: QTBUG-16071 --- doc/src/declarative/basictypes.qdoc | 7 +++---- doc/src/declarative/qmlevents.qdoc | 9 +++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 1be648e..453af08 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -36,11 +36,10 @@ 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{Importing Reusable Components} for the - list of types that can be used for \c property values. - \annotatedlist qmlbasictypes + + To create additional types, such as data types created in C++, read the + \l{Extending QML Functionalities using C++} article. */ /*! diff --git a/doc/src/declarative/qmlevents.qdoc b/doc/src/declarative/qmlevents.qdoc index 7d5e962..7dfb1f9 100644 --- a/doc/src/declarative/qmlevents.qdoc +++ b/doc/src/declarative/qmlevents.qdoc @@ -29,13 +29,11 @@ \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} +\previouspage {Keyboard Focus in QML}{Keyboard Focus} +\nextpage Importing Reusable Components \title QML Signal and Handler Event System -\section1 Overview, structural information - QML utilizes Qt's \l{The Meta-Object System}{meta-object} and \l{Signals & Slots}{signals} systems. Signals and slots created using Qt in C++ are inheritely valid in QML. @@ -124,4 +122,7 @@ runtime automatically creates signal handlers for the C++ signals. For more signal control, the \c connect() method and the \l Connect element may connect a C++ to another signal or method. +For complete information on how to call C++ functions in QML, read the \l {Extending QML - Signal Support Example}. + + */ -- cgit v0.12 From 57e4e8b9b8ee3e489c3f0900010eb194e174f623 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Tue, 15 Feb 2011 16:47:59 +0100 Subject: Re-wrote Qt Quick intro. Deleted unused snippets and images. Task-number: QTBUG-16071 --- doc/src/declarative/declarativeui.qdoc | 16 - doc/src/declarative/qml-intro.qdoc | 616 --------------------- doc/src/declarative/qtquick-intro.qdoc | 110 ++++ doc/src/images/qml-dial.png | Bin 43754 -> 0 bytes doc/src/images/qml-intro-anchors1.png | Bin 15198 -> 0 bytes doc/src/images/qml-intro-anchors2.png | Bin 15343 -> 0 bytes doc/src/images/qml-intro-anchors3.png | Bin 16745 -> 0 bytes doc/src/images/qml-intro-helloa.png | Bin 18246 -> 0 bytes doc/src/images/qmldesigner-visual-editor.png | Bin 0 -> 111632 bytes doc/src/images/qtcreator-target-selector.png | Bin 0 -> 36463 bytes .../snippets/declarative/qml-intro/anchors1.qml | 56 -- .../snippets/declarative/qml-intro/anchors2.qml | 58 -- .../snippets/declarative/qml-intro/anchors3.qml | 65 --- .../declarative/qml-intro/hello-world1.qml | 53 -- .../declarative/qml-intro/hello-world2.qml | 56 -- .../declarative/qml-intro/hello-world3.qml | 57 -- .../declarative/qml-intro/hello-world4.qml | 61 -- .../declarative/qml-intro/hello-world5.qml | 65 --- .../declarative/qml-intro/images/qt-logo.svg | 104 ---- .../declarative/qml-intro/number-animation1.qml | 64 --- .../declarative/qml-intro/number-animation2.qml | 66 --- .../snippets/declarative/qml-intro/rectangle.qml | 50 -- .../qml-intro/sequential-animation1.qml | 65 --- .../qml-intro/sequential-animation2.qml | 73 --- .../qml-intro/sequential-animation3.qml | 92 --- doc/src/snippets/declarative/qml-intro/states1.qml | 94 ---- .../declarative/qml-intro/transformations1.qml | 80 --- 27 files changed, 110 insertions(+), 1791 deletions(-) delete mode 100644 doc/src/declarative/qml-intro.qdoc create mode 100644 doc/src/declarative/qtquick-intro.qdoc delete mode 100644 doc/src/images/qml-dial.png delete mode 100644 doc/src/images/qml-intro-anchors1.png delete mode 100644 doc/src/images/qml-intro-anchors2.png delete mode 100644 doc/src/images/qml-intro-anchors3.png delete mode 100644 doc/src/images/qml-intro-helloa.png create mode 100644 doc/src/images/qmldesigner-visual-editor.png create mode 100644 doc/src/images/qtcreator-target-selector.png delete mode 100644 doc/src/snippets/declarative/qml-intro/anchors1.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/anchors2.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/anchors3.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/hello-world1.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/hello-world2.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/hello-world3.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/hello-world4.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/hello-world5.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/images/qt-logo.svg delete mode 100644 doc/src/snippets/declarative/qml-intro/number-animation1.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/number-animation2.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/rectangle.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/sequential-animation1.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/sequential-animation2.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/sequential-animation3.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/states1.qml delete mode 100644 doc/src/snippets/declarative/qml-intro/transformations1.qml diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 53c7da3..277903f 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -45,22 +45,6 @@ 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 - -User interfaces and their behavior are described using QML, an extension to -\l{About JavaScript}{JavaScript} that lets developers and designers -use a declarative syntax to specify each user interface in terms of -\l{QML Elements}{QML elements}. These elements are a sophisticated set of -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. - -\section2 Qt Declarative Module - -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. - -QML and the Qt Declarative Module separate the frontend UI logic from the backend logic. - \section1 Getting Started \list diff --git a/doc/src/declarative/qml-intro.qdoc b/doc/src/declarative/qml-intro.qdoc deleted file mode 100644 index 3f3e0e4..0000000 --- a/doc/src/declarative/qml-intro.qdoc +++ /dev/null @@ -1,616 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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-intro.html -\title Intro to Qt Quick - -\section1 Overview - -QML is a high level, scripted language. Its commands, more correctly \e elements, -leverage the power and efficiency of the Qt libraries to make easy to use -commands that perform intuitive functions. Draw a rectangle, display an image at -a position and so on. Behind these elements are complex C++ libraries that -efficiently perform the action. As with any graphical application, always -consider that this ability to easily build graphically rich applications means -that some care may be needed to prevent performance problems. - -The language also allows more flexibility of these commands by using -Javascript rather than C++ to add new layers of logic to your application. -Javascript is easier to learn than C++ and can be embedded into the QML -files or imported from a separate file. - -\bold{In QML the types of various 'objects' are referred to as \l {QML -Elements}{elements}}. - -An element usually has various \e properties that help define the element. For -example, if we created an element called Circle then the radius of the circle -would be a property. - - -\section1 A First Look - -The basic syntax of an \l{QML Elements}{element} is - -\qml -SomeElement { - id: myObject - // ... some other things here ... -} -\endqml - -Here we are defining a new object. We specify its 'type' first as SomeElement. -Then within matching braces { ... } we specify the various parts of our -element. - -The \c id is a unique identifier for the element, it must start with a lower -case letter and only contain letters, numbers and underscores. It is this -particular object's name. If this SomeElement \l {QML Elements}{element} was -a Rectangle instead and it was one of many then the \e optional unique id -would allow us to manipulate each element individually. - -Each visual element is ultimately based on, or inherits from, an element -called \l Item. \l Item has certain properties and actions that may be -useful. The properties have default values so you need only specify the -ones you will need. - -Take a simple element such as a \l Rectangle. It has an \c id, we will call -it \e myRectangle, it has a \c width and a \c height. Imagine that we -want a rectangle that is 500 pixels by 400 pixels in the x and y directions -(horizontal by vertical). - -We can implement this \l Rectangle with these properties this way - -\snippet doc/src/snippets/declarative/qml-intro/rectangle.qml document - -This is a valid QML script. To run it, copy it and save it to a file, say -myexample.qml, and on the command line run the following command: - -\code -qmlviewer myexample.qml -\endcode - -On Mac OS X, open the "QMLViewer" application instead and open the -\c myexample.qml file, or run it from the command line: - -\code -QMLViewer.app/Contents/MacOS/QMLViewer myexample.qml -\endcode - -It will create a very boring rectangle in its own window. - - -\section1 Hello World! - -We can now add some color and text to make a Hello World QML program. - -\l Rectangle has the property \l{Rectangle::color}{color} to produce a -background color. - -Text is handled by a different element called \l Text. We need to create a -\l Text object inside the \l Rectangle and set its \l{Text::}{text} -property to "Hello World!". So to set the text to "Hello world" and the -background colour to light gray, - -\snippet doc/src/snippets/declarative/qml-intro/hello-world1.qml document - - -\section1 Hello World Again - -From now on we will not always show the import statement for Qt but it -should still be there when you create your QML scripts. - -To make our Hello World example a little nicer set the position of the text -to be at pixel position x = 100, y = 100 within the displayed window. This -position belongs to the \l Text element so we set the position inside its -definition. Note that we separate different QML statements on the same line -with a semi-colon, or we could have simply put each statement on a new line - -\snippet doc/src/snippets/declarative/qml-intro/hello-world2.qml updated text - -Not only did we reposition the text, but the text was altered by adding -HTML tags to change the font size. The text color was also changed from the -default black to dark green by using a standard string for the color's SVG -name. - -We could also have used a hexadecimal string for the RGB (red-green-blue, as -#rrggbb) values of the color similar to the method used in HTML. For -example, mostly blue with a green tint, - -\snippet doc/src/snippets/declarative/qml-intro/hello-world3.qml updated text - -All of these changes occurred within the \l Text object which is the scope -of these property changes. - -Other objects may use the information but it belongs to the element where -the property has been defined. - - -\section1 Images - -To add an image to our little application we use the \l Image element. An -\l Image uses a path to an image file, and has properties to control -the aspect ratio, the image size, to tile the area amongst others. The -source of the image, the path to the file, is a URL. Therefore the file can -be local: \e {mydir/myimage1.png}. Or it can be remote: -\e {"http://www.example.com/images/myimage1.png"}. - -\snippet doc/src/snippets/declarative/qml-intro/hello-world4.qml added an image - -This displays the image, as we would expect, at the top left of the window. -The position of the default x = 0, y = 0 coordinate. The example here uses -a PNG file, but it could have been one of various supported formats, -including JPG and GIF. - -Let us reposition the image and enlarge it. Place it at the same 'x' offset -as the "Hello world again" text, but put it another 50 pixels below the -text, also make it 150 by 150 pixels in size, - -\snippet doc/src/snippets/declarative/qml-intro/hello-world5.qml positioning the image - -Adding the Hello World example, with the text and the image example we can -write a simple piece of QML that starts to look a bit better. - -\snippet doc/src/snippets/declarative/qml-intro/hello-world5.qml document - -The result is still quite simple - -\image qml-intro-helloa.png - - -\section1 Anchors: Aligning Elements - -Using absolute positioning, such as saying x = 100 and y = 150, works well -until the user or developer stretches or increases the size of the window. -Then the positions need to be recalculated. What would be nice would be a -relative means of positioning of objects in a window or rectangle. For -example, we want to place an image at the bottom of a rectangle, we would -like to specify the image's location as the 'bottom of the window', not a -specific coordinate. We can do this with the anchors property, which -objects inherit from Item. - -The anchors property is really a property group. It is a collection of -related properties. It has properties within it which can be used by means -of the dot notation. - -The dot notation uses object \c{id}s and property names to use a particular -object or property. Say I have a rectangle r1, which contains a rectangle -r2, which contains an Item item1, which has an 'x' property I want to -change. I just use the dot notation to identify it: r1.r2.item1.x - -If we want to position an image at the bottom of the rectangle it is -inside. I have to specify that the bottom of the image is also at the -bottom of the rectangle - -\snippet doc/src/snippets/declarative/qml-intro/anchors1.qml document - -This places the logo at the bottom left of the window. - -\image qml-intro-anchors1.png "A simple anchor" - -We would like it centered and not touching the bottom of the window, for -aesthetic reasons. For the centering we use the horizontalCenter property, -and to prevent the touching of the image to the bottom of the rectangle, -the bottomMargin property is used. So the new actions for the script are - - \list - \o set the bottom of the image (anchors.bottom) to be the bottom of the window - \o move the image to be in the horizontal center of the window - \o set a margin of 10 pixels so that the image does not touch the bottom window border - \endlist - -Encoded into QML the script becomes - -\snippet doc/src/snippets/declarative/qml-intro/anchors2.qml document - -Run this and resize the window. You will see that now the position of the -image adjusts during the resize. - -\image qml-intro-anchors2.png "Image Centered at the Bottom" - -You can also add another object say a block of descriptive text and place -it above or below the image or to the side. This code places some text just -above the image - -\snippet doc/src/snippets/declarative/qml-intro/anchors3.qml adding some text - -\image qml-intro-anchors3.png - -\note \e anchors is a property group, to be used within the object. When -referencing these properties from another object we use the property -directly, instead of saying: - -\qml -Item { - anchors.bottom: myRectangle.anchors.top // Wrong -} -\endqml - -we use - -\qml -Item { - anchors.bottom: myRectangle.top // Correct -} -\endqml - - -\section1 Transformations - -We can transform a graphical object to get additional effects. Rotate a -piece of text by 180 degrees to display upside-down text. Rotate an image -by 90 degrees to lay it on its side. These transformations require -additional information. - -For rotation, the additional information includes: the origin relative to -the object being rotated, the axis of rotation, and the angle in degrees to -rotate the image through in a clockwise direction. The axis does not have -to be the z-axis, the line between your eyes and the image, it could be -along the vertical y-axis or the horizontal x-axis. We have three -dimensions to play with. For simplicity in this example we will rotate -about the z-axis by 90 degrees in a negative direction, anti-clockwise. - -Rotation of text was also suggested. It could also be useful to scale the -text. We can do both. The \l {Item::transform}{transform} property is a -\e list of \l Transform elements, so using the list syntax -\c{myList: [ listElement1, listElement2, ... } ]} -we can produce a list of transformations. - -The text will be rotated by 45 degrees anti-clockwise and scaled -vertically by a factor of 1.5 and by 1.2 horizontally. - -Using the example above as the basis for this we have, - -\snippet doc/src/snippets/declarative/qml-intro/transformations1.qml document - -The code block in \c image1 starting with \c transform specifies that the -\l {Item::transform}{transform} property will be a Rotation through -90 -degrees, which is anti-clockwise, about the z-axis running through the -center of the image at (75,75), since the image is 150 x 150 pixels. - -The other transformation available is \l Translate. This produces a change -in position of the item. - -\note In a list of transformations the order of the transformations is -important. In the above example try swapping around the Scale transform with -the Rotation transform, remember to remove or add the comma. The results are -acceptable for our little test but not the same. - - -\section1 Animations - -Animation in QML is done by animating properties of objects. Properties -that are numbers, colors, Rectangles, points and directions. In QML these -are \l {QML Basic Types} named as real, int, color, rect, point, size, and -vector3d. There are a number of different ways to do animation. Here we -will look at a few of them. - -\section2 Number Animation - -Previously we have used a rotation transformation to change the orientation -of an image. We could easily animate this rotation so that instead of a -straight rotation counter-clockwise of 90 degrees we could rotate the image -through a full 360 degrees in an animation. The axis of rotation wont -change, the position of the center of the image will not change, only the -angle will change. Therefore, a NumberAnimation of a rotation's angle should -be enough for the task. If we wish for a simple rotation about the center -of the image then we can use the \c rotation property that is inherited -from \l Item. The rotation property is a real number that specifies the -angle in a clockwise direction for the rotation of the object. Here is the -code for our animated rotating image. - -\snippet doc/src/snippets/declarative/qml-intro/number-animation1.qml document - -The \c {transformOrigin: Item.Center} is redundant since this is the default -axis of rotation anyway. But if you change \c Center to \c BottomRight you -will see an interesting variation. - -Also if instead the \l Rotation transformation had been used then we would have -more control over the various parameters. We could vary the axis, to be not -just a different offset from the z-axis but along the y-axis, x-axis or -combination. For example, if the task had been to animate the rotation -about the y-axis passing through the center of the image then the following -code would do it. - -\snippet doc/src/snippets/declarative/qml-intro/number-animation2.qml document - -Here there is a rectangle 600 by 400 pixels. Placed within that rectangle -is an image 100 by 100 pixels. It is rotated about the center of the image -about the y-axis so that it looks as if it is rotating about an invisible -vertical string holding it up. The time it takes to complete the rotation is 3 -seconds (3,000 milliseconds). The NumberAnimation is applied to the angle -taking it from 0 (no change) to 360 degrees, back where it started. -Strictly speaking it isn't necessary to go from 0 to 360 since the same -location is duplicated, but it makes it easier to read in this example and -it has no visible effect on the animation. The number of loops that the -animation will execute is set to \c {Animation.Infinite} which means that the -animation is in an endless loop. - -To see an interesting variation. Change the axis to \c {axis { x:1; y:1; z:1 -}}. This is a line coming from the center of the image downwards to the -right and out of the screen. Although the change is simple the rotation -seems complex. - -\section2 Sequential Animation - -For a more complex animation we will need two images. The first image will -be placed at the center of a window (Rectangle) and the second image will -be at the upper left of the window. The animation will move the second -image from the top left of the window to the bottom right. In doing so we -will be animating the position and the size of the image. - -First create two images - -\snippet doc/src/snippets/declarative/qml-intro/sequential-animation1.qml document - -We will add to 'image1' a SequentialAnimation from x = 20 to the target of -x = 450. The 'from' values will be used because we will be repeating the -animation, so the object needs to know where the original position is, both -x and y. The SequentialAnimation of x will set it to repeat by indicating -that the number of animation loops is infinite, meaning that the 'loop' -counter will be set to a value Animation.Infinite that indicates an endless -cycle. Also there will be a NumberAnimation to vary the numeric property -between the x values and over a given duration. After the NumberAnimation -there will be a PauseAnimation that will pause the animation for 500 -milliseconds (half a second) simply for the visual effect. - -\snippet doc/src/snippets/declarative/qml-intro/sequential-animation2.qml adding a sequential animation - -A similar block of code is written for the animation of the 'y' value of -the position. - -We will also animate the scale of the object, so as it goes from top left -to bottom right of the window it will become smaller until about midway, -and then become larger. To complete the animation we will set the 'z' -values of the images. 'z' is the stacking order, the z-axis effectively -points out from the screen to your eyes with the default value of 'z' being -0. So if we set the Rectangle to have z with value zero, just to be sure, -and image1 to 1 and image2 to 2 then image2 will be in the foreground and -image1 in the background. When image1 passes image2 it will pass behind it. -The completed code looks like - -\snippet doc/src/snippets/declarative/qml-intro/sequential-animation3.qml document - -The \c {easing.type} has many options, expressed as a string. It specifies the -kind of equation that describes the acceleration of the property value, not -necessarily position, over time. - -For example, \e InOutQuad means that at the start and the end of the animation the -'velocity' is low but the acceleration or deceleration is high. Much like a car -accelerating from stop, and decelerating to stop at the end of a journey, -with the maximum speed being in the middle. Examine the \l {PropertyAnimation::easing.type} -{easing} documentation and the various graphs that show the effect. The horizontal -axis, 'progress', can be thought of as time. The vertical axis is the value -of the particular property. - -In discussing animation we need to describe three objects: State, MouseArea -and Signals. Although independent of the animation elements, animation -delivers some of the best examples that illustrate these new elements. - - - -\section2 Animation Summary - -\table - \header - \o Name - \o Description - \row - \o PropertyAnimation - \o a property value on a target object is varied to a specified value over a given time. - - \row - \o NumberAnimation - \o animate a numeric property from one value to another over a given time. - - \row - \o PauseAnimation - \o results in the task waiting for the specified duration, in milliseconds. - - \row - \o SequentialAnimation - \o allows us to list in order the animation events we want to occur, first A then B then C and so on. - - \row - \o ParallelAnimation - \o enables us to run different animations at the same time instead of sequentially. - -\endtable - - -\section1 Using States - -A state is a defined set of values in the configuration of an object and -often depends on the previous state. For example, a glass could be in a -state we call 'HalfFull' if it is being filled with a liquid and has -reached half of its total capacity. We could also have a state called -HalfEmpty which is the state that occurs when the amount of liquid drops to -half of the glass's capacity. Both states represent the same amount of -liquid, but we consider them different. Likewise, states in a program -represent not just values but may include how the current values were -reached. - -When a state changes a \e transition occurs. This is an opportunity to make -changes or take actions that depend on the movement to the new state. For -example, if we had a scene in the country where the state variable has two -states "daylight" and "night". Then when the state changes to "night" at -this transition the sky would be made dark, stars would be shown, the -countryside would be darkened. And when the state changes to "daylight" the -opposite changes would be made: the sky is now blue, the scenery is green, -there is a sun in the sky. - -Here is a simple QML program that shows the change of state in the above -example. We have two rectangles, the top one is the 'sky' and the bottom -one is the 'ground'. We will animate the change from daylight to night. -There will be two states, but we only need to define one since 'daylight' -will be the default state. We will just go to 'night' by clicking and -holding the left mouse button down, releasing the mouse button will reverse -the process - -\snippet doc/src/snippets/declarative/qml-intro/states1.qml document - -Several new things appear in this sample. Firstly, we use a \l MouseArea -element to detect mouse clicks in the \e mainRectangle. Secondly, we use -the list notation [ thing1 , thing2, ... ] to build a list of states and a -list of transitions. - -\l MouseArea defines a region that will respond to mouse clicks. In this case -we are only concerned with when the mouse is pressed or not pressed, not -the particular button or other details. The area of the MouseArea is the -entire main window, mainRectangle, so that clicking anywhere in this region -will start the animation. Since we are using the 'pressed' mouse state, -then the animation will move from 'daylight' to 'night' only while the mouse -button remains pressed. - -When the button is released the 'daylight' state is entered and the -transition from 'night' to 'daylight' is triggered causing the animation to -run. The transition specifies the duration in milliseconds of the -ColorAnimation, while the state specifies the color of the new state. - -The PropertyChanges command is the way that we nominate which properties -will change in a change of state, and what new value the property will -take. Since, for example, we want the 'sky' region to turn to dark blue and -the 'ground' region to turn to black for the 'night' state, then the -rectangles for those regions are the 'target' and the property in the target -is 'color'. - - -\section1 Signals - -Signals are simply events that can be hooked up to actions we want performed. -In QML they are usually preceded by the word 'on', for example in the animation -using a MouseArea the signal was \l {MouseArea::onPressed}{onPressed}. If -you look at the C++ documentation you will see a lot of talk about -\l {Signals & Slots}{Signals and Slots}. Signals are connected to Slots. The -signal represents an event and the Slot is the function that does something -based on that event. You can also have Signals connected to other Signals, so -that one Signal (event) triggers another Signal (event), and so forth. It is -nice to know this is what happens beneath the QML layer but not essential for -using QML. - -Most elements do not have Signals associated with them. However, a few like -the \l Audio element have many signals. Some of the \l Audio signals are -used to represent events such as when the audio is stopped, play is pressed, -paused, and reaching the end of the media. They allow the developer to connect, - for example, the press of a user interface button (perhaps a MouseArea) to - some QML that will handle this event. - - -\section1 Analyzing An Example: Dial Control - -In the Qt \e {examples/declarative/ui-components} folder you will find a folder -\e {dialcontrol} which contains the \e dialcontrol example. - -\image qml-dial.png "QML Dial example with Slider" - -In essence this small application has a sliding bar that you can slide using -a mouse, and a graphical dial that responds to the position of the slider. - -The code for the example is in two parts: Dial.qml and dialcontrol.qml. - -\e {Dial.qml} can be found in the \e content sub-directory. It defines a \c Dial -component similar to an odometer. Eventually, the example will hook up a slider -component so that moving the slider will change the position of a needle on the -dial. - -The code for the \c Dial, identified by the name of the file, contains four images -in overlapping order: the background (numbers and divisions), the shadow of the -needle, the needle itself, and finally the 'glass' overlay (containing -transparent layers). - -The \c needle_shadow.png image has a \l Rotation assigned to the \e transform -attribute of the \l Image. The rotation is set to match the angle of the needle -image angle value \e {needleRotation.angle}. Both the needle and the -needle_shadow have the same default \e x and \e y values but the rotation origin -for the needle is slightly different so that a shadow will be evident as the -needle moves. - -\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml needle_shadow - -And the needle - -\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml needle - -The final image is the overlay which simply has a position defined. - -\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml overlay - -\e {dialcontrol.qml} in the \e {examples/declarative/ui-components/dialcontrol} directory is the -main file of the example. It defines the visual environment that the Dial -will fit into. Because the \e Dial component and the images live in the \e -content sub-directory we will have to import this into \e dialcontrol.qml. So the -start of the file looks like - -\snippet examples/declarative/ui-components/dialcontrol/dialcontrol.qml imports - -The visual space is bound by a 300 by 300 pixel \l Rectangle which is given -a gray color. Inside this rectangle is our component \e Dial and a \l Rectangle. -Inside the rectangle called 'container' is another rectangle with the -interesting name 'slider'. - -\snippet examples/declarative/ui-components/dialcontrol/dialcontrol.qml 0 - -The Dial component, named 'dial, is \e anchored to the center of the main -rectangle. The \c value attribute of 'dial' is set to a value based on the -'slider' horizontal position and the 'container' width. So changes to the -'slider' position will change the Dial \c value which is used in Dial to compute -the rotation of the needle image. Notice this piece of code in Dial where -the change in \c value modifies the position of the needle. - -\snippet examples/declarative/ui-components/dialcontrol/content/Dial.qml needle angle - -This is part of the \c needleRotation that rotates the needle and causes the -rotation of its shadow. \l SpringAnimation is an element that modifies the value -of that rotation \e angle and mimics the oscillatory behavior of a spring, -with the appropriate \e spring constant to control the acceleration and the \e -damping to control how quickly the effect dies away. - -The 'container' is light gray with a color gradient defined using -\l GradientStop. The gradient is applied vertically. If you need a horizontal -gradient then you could apply the vertical gradient and then rotate the item -by 90 degrees. - -The 'slider' is dark gray and also has a vertical color gradient. The most -important thing about the 'slider' is that it has a MouseArea defined, which -specifies a \c {drag.target} on itself along the X-axis. With minimum -and maximum values on the X-axis defined. So we can click on the 'slider' and -drag it left and right within the confines of the 'container'. The motion of -the 'slider' will then change the \c value attribute in \e Dial as discussed -already. - -Also notice the use of a \c radius value for a rectangle. This produces rounded -corners. That is how the 'container' and 'slider' are displayed with a -pleasant rounded look. - - - -*/ - - - diff --git a/doc/src/declarative/qtquick-intro.qdoc b/doc/src/declarative/qtquick-intro.qdoc new file mode 100644 index 0000000..c5a9ca4 --- /dev/null +++ b/doc/src/declarative/qtquick-intro.qdoc @@ -0,0 +1,110 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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-intro.html +\title Intro to Qt Quick + +Qt Quick is a collection of technologies that are designed to help developers create the kind of intuitive, modern, and fluid user interfaces that are increasingly used on mobile phones, media players, set-top boxes, and other portable devices. Qt Quick consists of a rich set of user interface \l{QML Elements}{elements}, a \l{QML Syntax}{declarative} language for describing user interfaces, and a language \l{QtDeclarative Module}{runtime}. A collection of C++ APIs is used to integrate these high level features with classic Qt applications. Version 2.1 of the Qt Creator integrated development environment (IDE) introduces tools for developing Qt Quick applications. + +\image qml-clocks-example.png + +\section1 The QML Language + +QML is a high level, scripted language. Its commands, more correctly \e elements, +leverage the power and efficiency of the Qt libraries to make easy to use +commands that perform intuitive functions. Drawing a rectangle, displaying an +image, and application events -- all are possible with declarative programming. + +The language also allows more flexibility of these commands by using +\l{About JavaScript}{JavaScript} to implement the high level user interface +logic. + +A QML element usually has various \e properties that help define the element. For +example, if we created an element called Circle then the radius of the circle +would be a property. Building user interfaces by importing these elements is one +of the great feature of QML and Qt Quick. +\image qml-texteditor5_newfile.png + +\section1 QtDeclarative Module + +To make Qt Quick possible, Qt introduces the \l {QtDeclarative} module. The +module creates a JavaScript runtime that QML runs under with a Qt based backend. +Because QtDeclarative and QML are built upon Qt, they inherit many of Qt's +technology, namely the \l{Signals and Slots}{signals and slots} mechanism and the \l{The Meta-Object System}{meta-object} system. Data created using C++ are +directly accessible from QML and QML objects are also accessible from C++ code. + +In conjunction with the QML language, the QtDeclarative module separates the +interface logic in QML from the application logic in C++. + +\section1 Creator Tools + +Qt Creator is a complete integrated development environment (IDE) for creating applications with Qt Quick and the Qt application framework. + +\image qmldesigner-visual-editor.png + +The main goal for Qt Creator is meeting the development needs of Qt Quick +developers who are looking for simplicity, usability, productivity, +extendibility and openness, while aiming to lower the barrier of entry for +newcomers to Qt Quick and Qt. The key features of Qt Creator allow UI designers +and developers to accomplish the following tasks: +\list +\o Get started with Qt Quick application development quickly and easily with +examples, tutorials, and project wizards. +\o Design application user interface with the integrated editor, Qt Quick +Designer, or use graphics software to design the user interface and use scripts +to export the design to Qt Quick Designer. +\o Develop applications with the advanced code editor that provides new powerful +features for completing code snippets, refactoring code, and viewing the element +hierarchy of QML files. +\o Build and deploy Qt Quick applications that target multiple desktop and +mobile platforms, such as Microsoft Windows, Mac OS X, Linux, Symbian, and +Maemo. +\o Debug JavaScript functions and execute JavaScript expressions in the current +context, and inspect QML at runtime to explore the object structure, debug +animations, and inspect colors. +\o Deploy applications to mobile devices and create application installation +packages for Symbian and Maemo devices that can be published in the Ovi Store +and other channels. +\o Easily access information with the integrated context-sensitive Qt Help +system. +\endlist + +\image qtcreator-target-selector.png + +\section1 Where to Go from Here + +The \l {Qt Quick} page has links to various Qt Quick topics such as QML features, +addons, and tools. + +The \l {QML Examples and Demos} page has a gallery of QML applications. +*/ + + + diff --git a/doc/src/images/qml-dial.png b/doc/src/images/qml-dial.png deleted file mode 100644 index da5c031..0000000 Binary files a/doc/src/images/qml-dial.png and /dev/null differ diff --git a/doc/src/images/qml-intro-anchors1.png b/doc/src/images/qml-intro-anchors1.png deleted file mode 100644 index fdb301e..0000000 Binary files a/doc/src/images/qml-intro-anchors1.png and /dev/null differ diff --git a/doc/src/images/qml-intro-anchors2.png b/doc/src/images/qml-intro-anchors2.png deleted file mode 100644 index 84f43bd..0000000 Binary files a/doc/src/images/qml-intro-anchors2.png and /dev/null differ diff --git a/doc/src/images/qml-intro-anchors3.png b/doc/src/images/qml-intro-anchors3.png deleted file mode 100644 index 21ae97b..0000000 Binary files a/doc/src/images/qml-intro-anchors3.png and /dev/null differ diff --git a/doc/src/images/qml-intro-helloa.png b/doc/src/images/qml-intro-helloa.png deleted file mode 100644 index 00b34b0..0000000 Binary files a/doc/src/images/qml-intro-helloa.png and /dev/null differ diff --git a/doc/src/images/qmldesigner-visual-editor.png b/doc/src/images/qmldesigner-visual-editor.png new file mode 100644 index 0000000..55763e0 Binary files /dev/null and b/doc/src/images/qmldesigner-visual-editor.png differ diff --git a/doc/src/images/qtcreator-target-selector.png b/doc/src/images/qtcreator-target-selector.png new file mode 100644 index 0000000..1f26138 Binary files /dev/null and b/doc/src/images/qtcreator-target-selector.png differ diff --git a/doc/src/snippets/declarative/qml-intro/anchors1.qml b/doc/src/snippets/declarative/qml-intro/anchors1.qml deleted file mode 100644 index b958138..0000000 --- a/doc/src/snippets/declarative/qml-intro/anchors1.qml +++ /dev/null @@ -1,56 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: myWin - width: 500 - height: 400 - - Image { - id: image1 - source: "images/qt-logo.svg" - width: 150; height: 150 - anchors.bottom: myWin.bottom - } -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/anchors2.qml b/doc/src/snippets/declarative/qml-intro/anchors2.qml deleted file mode 100644 index 2c4ce11..0000000 --- a/doc/src/snippets/declarative/qml-intro/anchors2.qml +++ /dev/null @@ -1,58 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: myWin - width: 500 - height: 400 - - Image { - id: image1 - source: "images/qt-logo.svg" - width: 150; height: 150 - anchors.bottom: myWin.bottom - anchors.horizontalCenter: myWin.horizontalCenter - anchors.bottomMargin: 10 - } -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/anchors3.qml b/doc/src/snippets/declarative/qml-intro/anchors3.qml deleted file mode 100644 index 24851af..0000000 --- a/doc/src/snippets/declarative/qml-intro/anchors3.qml +++ /dev/null @@ -1,65 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - id: myWin - width: 500 - height: 400 - - Image { - id: image1 - source: "images/qt-logo.svg" - width: 150; height: 150 - anchors.bottom: myWin.bottom - anchors.horizontalCenter: myWin.horizontalCenter - anchors.bottomMargin: 10 - } - -//! [adding some text] - Text { - text: "

The Qt Logo

" - anchors.bottom: image1.top - anchors.horizontalCenter: myWin.horizontalCenter - anchors.bottomMargin: 15 - } -//! [adding some text] -} diff --git a/doc/src/snippets/declarative/qml-intro/hello-world1.qml b/doc/src/snippets/declarative/qml-intro/hello-world1.qml deleted file mode 100644 index 81ad333..0000000 --- a/doc/src/snippets/declarative/qml-intro/hello-world1.qml +++ /dev/null @@ -1,53 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: myRectangle - width: 500 - height: 400 - - Text { text: "Hello World!" } - - color: "lightgray" -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/hello-world2.qml b/doc/src/snippets/declarative/qml-intro/hello-world2.qml deleted file mode 100644 index 2564e25..0000000 --- a/doc/src/snippets/declarative/qml-intro/hello-world2.qml +++ /dev/null @@ -1,56 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - id: myRectangle - width: 500 - height: 400 - -//! [updated text] - Text { - text: "

Hello World

"; color: "darkgreen" - x: 100; y:100 - } -//! [updated text] - - color: "lightgray" -} diff --git a/doc/src/snippets/declarative/qml-intro/hello-world3.qml b/doc/src/snippets/declarative/qml-intro/hello-world3.qml deleted file mode 100644 index 03358d0..0000000 --- a/doc/src/snippets/declarative/qml-intro/hello-world3.qml +++ /dev/null @@ -1,57 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - id: myRectangle - width: 500 - height: 400 - -//! [updated text] - Text { - text: "

Hello world again

" - color: "#002288" - x: 100; y: 100 - } -//! [updated text] - - color: "lightgray" -} diff --git a/doc/src/snippets/declarative/qml-intro/hello-world4.qml b/doc/src/snippets/declarative/qml-intro/hello-world4.qml deleted file mode 100644 index 832e37d..0000000 --- a/doc/src/snippets/declarative/qml-intro/hello-world4.qml +++ /dev/null @@ -1,61 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - id: myRectangle - width: 500 - height: 400 - - Text { - text: "

Hello world again

" - color: "#002288" - x: 100; y: 100 - } - -//! [added an image] - Image { - source: "images/qt-logo.svg" - } -//! [added an image] - - color: "lightgray" -} diff --git a/doc/src/snippets/declarative/qml-intro/hello-world5.qml b/doc/src/snippets/declarative/qml-intro/hello-world5.qml deleted file mode 100644 index 7357282..0000000 --- a/doc/src/snippets/declarative/qml-intro/hello-world5.qml +++ /dev/null @@ -1,65 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: myRectangle - width: 500 - height: 400 - - Text { - text: "

Hello world again

" - color: "#002288" - x: 100; y: 100 - } - -//! [positioning the image] - Image { - source: "images/qt-logo.svg" - x: 100; y: 150 - width: 150; height: 150 - } -//! [positioning the image] - - color: "lightgray" -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/images/qt-logo.svg b/doc/src/snippets/declarative/qml-intro/images/qt-logo.svg deleted file mode 100644 index 8c018be..0000000 --- a/doc/src/snippets/declarative/qml-intro/images/qt-logo.svg +++ /dev/null @@ -1,104 +0,0 @@ - - - - - - image/svg+xml - - - - - - SVG generated by Lineform - - - - - - - - - - - - - - - diff --git a/doc/src/snippets/declarative/qml-intro/number-animation1.qml b/doc/src/snippets/declarative/qml-intro/number-animation1.qml deleted file mode 100644 index ccf2d36..0000000 --- a/doc/src/snippets/declarative/qml-intro/number-animation1.qml +++ /dev/null @@ -1,64 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: mainRec - width: 600 - height: 400 - - Image { - id: image1 - source: "images/qt-logo.svg" - x: 200; y: 100 - width: 100; height: 100 - - // Animate a rotation - transformOrigin: Item.Center - NumberAnimation on rotation { - from: 0; to: 360 - duration: 2000 - loops: Animation.Infinite - } - } -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/number-animation2.qml b/doc/src/snippets/declarative/qml-intro/number-animation2.qml deleted file mode 100644 index 7be22b5..0000000 --- a/doc/src/snippets/declarative/qml-intro/number-animation2.qml +++ /dev/null @@ -1,66 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: mainRec - width: 600 - height: 400 - - Image { - id: image1 - source: "images/qt-logo.svg" - x: 200; y: 100 - width: 100; height: 100 - - // Animate a rotation - transform: Rotation { - origin.x: 50; origin.y: 50; axis {x:0; y:1; z:0} angle:0 - NumberAnimation on angle { - from: 0; to: 360; - duration: 3000; - loops: Animation.Infinite - } - } - } -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/rectangle.qml b/doc/src/snippets/declarative/qml-intro/rectangle.qml deleted file mode 100644 index b25accc..0000000 --- a/doc/src/snippets/declarative/qml-intro/rectangle.qml +++ /dev/null @@ -1,50 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -// This is a comment. And below myRectangle is defined. -Rectangle { - id: myRectangle - width: 500 - height: 400 -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/sequential-animation1.qml b/doc/src/snippets/declarative/qml-intro/sequential-animation1.qml deleted file mode 100644 index c789bbe..0000000 --- a/doc/src/snippets/declarative/qml-intro/sequential-animation1.qml +++ /dev/null @@ -1,65 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: mainRec - width: 600 - height: 400 - z: 0 - - Image { - id: image1 - source: "images/qt-logo.svg" - x: 20; y: 20 ; z: 1 - width: 100; height: 100 - } - - Image { - id: image2 - source: "images/qt-logo.svg" - width: 100; height: 100 - x: (mainRec.width - 100)/2; y: (mainRec.height - 100)/2 - z: 2 - } -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/sequential-animation2.qml b/doc/src/snippets/declarative/qml-intro/sequential-animation2.qml deleted file mode 100644 index b2b1a57..0000000 --- a/doc/src/snippets/declarative/qml-intro/sequential-animation2.qml +++ /dev/null @@ -1,73 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -Rectangle { - id: mainRec - width: 600 - height: 400 - z: 0 - -//! [adding a sequential animation] - Image { - id: image1 - source: "images/qt-logo.svg" - width: 100; height: 100 - - SequentialAnimation on x { - loops: Animation.Infinite - NumberAnimation { - from: 20; to: 450; easing.type: "InOutQuad"; - duration: 2000 - } - PauseAnimation { duration: 500 } - } - } -//! [adding a sequential animation] - - Image { - id: image2 - source: "images/qt-logo.svg" - width: 100; height: 100 - x: (mainRec.width - 100)/2; y: (mainRec.height - 100)/2 - z: 2 - } -} diff --git a/doc/src/snippets/declarative/qml-intro/sequential-animation3.qml b/doc/src/snippets/declarative/qml-intro/sequential-animation3.qml deleted file mode 100644 index d840575..0000000 --- a/doc/src/snippets/declarative/qml-intro/sequential-animation3.qml +++ /dev/null @@ -1,92 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: mainRec - width: 600 - height: 400 - z: 0 - - Image { - id: image2 - source: "images/qt-logo.svg" - width: 100; height: 100 - x: (mainRec.width - 100)/2; y: (mainRec.height - 100)/2 - z: 2 - } - - Image { - id: image1 - source: "images/qt-logo.svg" - x: 20; y: 20 ; z: 1 - width: 100; height: 100 - - SequentialAnimation on x { - loops: Animation.Infinite - NumberAnimation { - from: 20; to: 450 - easing.type: "InOutQuad"; duration: 2000 - } - PauseAnimation { duration: 500 } - } - - SequentialAnimation on y { - loops: Animation.Infinite - NumberAnimation { - from: 20; to: 250 - easing.type: "InOutQuad"; duration: 2000 - } - PauseAnimation { duration: 500 } - } - - SequentialAnimation on scale { - loops: Animation.Infinite - NumberAnimation { from: 1; to: 0.5; duration: 1000 } - NumberAnimation { from: 0.5; to: 1; duration: 1000 } - PauseAnimation { duration: 500 } - } - } -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/states1.qml b/doc/src/snippets/declarative/qml-intro/states1.qml deleted file mode 100644 index 270d6c3..0000000 --- a/doc/src/snippets/declarative/qml-intro/states1.qml +++ /dev/null @@ -1,94 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: mainRectangle - width: 600 - height: 400 - color: "black" - - Rectangle { - id: sky - width: 600 - height: 200 - y: 0 - color: "lightblue" - } - - Rectangle { - id: ground - width: 600; height: 200 - y: 200 - color: "green" - } - - MouseArea { - id: mousearea - anchors.fill: mainRectangle - } - - states: [ State { - name: "night" - when: mousearea.pressed == true - PropertyChanges { target: sky; color: "darkblue" } - PropertyChanges { target: ground; color: "black" } - }, - State { - name: "daylight" - when: mousearea.pressed == false - PropertyChanges { target: sky; color: "lightblue" } - PropertyChanges { target: ground; color: "green" } - } - ] - - transitions: [ Transition { - from: "daylight"; to: "night" - ColorAnimation { duration: 1000 } - }, - Transition { - from: "night"; to: "daylight" - ColorAnimation { duration: 500 } - } - ] -} -//! [document] diff --git a/doc/src/snippets/declarative/qml-intro/transformations1.qml b/doc/src/snippets/declarative/qml-intro/transformations1.qml deleted file mode 100644 index 7be79c8..0000000 --- a/doc/src/snippets/declarative/qml-intro/transformations1.qml +++ /dev/null @@ -1,80 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -Rectangle { - id: myWin - width: 500 - height: 400 - - Image { - id: image1 - source: "images/qt-logo.svg" - width: 150; height: 150 - anchors.bottom: myWin.bottom - anchors.horizontalCenter: myWin.horizontalCenter - anchors.bottomMargin: 10 - - transform: Rotation { - origin.x: 75; origin.y: 75 - axis{ x: 0; y: 0; z:1 } angle: -90 - } - - } - - Text { - text: "

The Qt Logo -- taking it easy

" - anchors.bottom: image1.top - anchors.horizontalCenter: myWin.horizontalCenter - anchors.bottomMargin: 15 - - transform: [ - Scale { xScale: 1.5; yScale: 1.2 } , - - Rotation { - origin.x: 75; origin.y: 75 - axis{ x: 0; y: 0; z:1 } angle: -45 - } - ] - } -} -//! [document] -- cgit v0.12 From e0eb3469302831481483d85d7535dfb1fd796de2 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Wed, 16 Feb 2011 11:59:26 +0100 Subject: Resized image and took out extra lines. Task-number: QTBUG-16071 --- doc/src/declarative/qtquick-intro.qdoc | 2 -- doc/src/images/qmldesigner-visual-editor.png | Bin 111632 -> 102238 bytes 2 files changed, 2 deletions(-) diff --git a/doc/src/declarative/qtquick-intro.qdoc b/doc/src/declarative/qtquick-intro.qdoc index c5a9ca4..2315030 100644 --- a/doc/src/declarative/qtquick-intro.qdoc +++ b/doc/src/declarative/qtquick-intro.qdoc @@ -25,8 +25,6 @@ ** ****************************************************************************/ - - /*! \page qml-intro.html \title Intro to Qt Quick diff --git a/doc/src/images/qmldesigner-visual-editor.png b/doc/src/images/qmldesigner-visual-editor.png index 55763e0..9cd4b8b 100644 Binary files a/doc/src/images/qmldesigner-visual-editor.png and b/doc/src/images/qmldesigner-visual-editor.png differ -- cgit v0.12 From e2ae6a38ce2739cee52b7cae9198ca45e315c0cd Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Wed, 16 Feb 2011 13:10:29 +0100 Subject: Added new snippet code. Task-number: QTBUG-16071 --- doc/src/declarative/mouseevents.qdoc | 5 +- .../declarative/mousearea/mousearea-snippet.qml | 55 ++++++++++++++++++++-- 2 files changed, 54 insertions(+), 6 deletions(-) diff --git a/doc/src/declarative/mouseevents.qdoc b/doc/src/declarative/mouseevents.qdoc index eed3a3a..533f64b 100644 --- a/doc/src/declarative/mouseevents.qdoc +++ b/doc/src/declarative/mouseevents.qdoc @@ -57,7 +57,7 @@ to define this area is to anchor the \c MouseArea to its parent's area using the component), then the MouseArea will fill the area defined by the parent's dimensions. Alternatively, an area smaller or larger than the parent is definable. -\snippet doc/src/snippets/declarative/mouse.qml anchor fill +\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml anchor fill \section1 Receiving Events @@ -79,7 +79,7 @@ gestures in greater detail. \endlist These signals have signal handlers that are invoked when the signals are emitted. -\snippet doc/src/snippets/declarative/mouse.qml mouse handlers +\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml mouse handlers \section1 Enabling Gestures Some mouse gestures and button clicks need to be enabled before they send or @@ -97,6 +97,7 @@ positioning even when there are no mouse button presses. Setting the \c hoverEnabled property to \c true, in turn will enable the \c entered, \c exited, and \c positionChanged signal and their respective signal handlers. +\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml enable handlers Additionally, to disable the whole mouse area, set the \c MouseArea element's \c enabled property to \c false. diff --git a/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml b/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml index 3c2e143..99cdc8b 100644 --- a/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml +++ b/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml @@ -41,13 +41,60 @@ //! [document] import QtQuick 1.0 -Rectangle { - width: 100; height: 100 +//! [parent begin] +Rectangle { +//! [parent begin] + width: 500; height: 500 color: "green" - MouseArea { +Column { +//! [anchor fill] +Rectangle { + id: button + width: 100; height: 100 + + MouseArea { anchors.fill: parent - onClicked: { parent.color = 'red' } + onClicked: console.log("button clicked") + } + MouseArea { + width:150; height: 75 + onClicked: console.log("irregular area clicked") + } +} +//! [anchor fill] + +Rectangle { + id: button + width: 100; height: 100 + +//! [enable handlers] + MouseArea { + hoverEnabled: true + acceptedButtons: Qt.LeftButton | Qt.RightButton + onEntered: console.log("mouse entered the area") + onExited: console.log("mouse left the area") } +//! [enable handlers] +} + +Rectangle { + id: button + width: 100; height: 100 + +//! [mouse handlers] + MouseArea { + anchors.fill: parent + onClicked: console.log("area clicked") + onDoubleClicked: console.log("area double clicked") + onEntered: console.log("mouse entered the area") + onExited: console.log("mouse left the area") + } +//! [mouse handlers] +} + +} //end of column +//! [parent end] } +//! [parent end] //! [document] -- cgit v0.12 From fe4e96dc0976467eb014c6c5a24a13cf90b9a84e Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Wed, 16 Feb 2011 16:54:44 +0100 Subject: Re-wrote QML Views overview page. Created new snippets and images. Task-number: QTBUG-16071 --- doc/src/declarative/qmlviews.qdoc | 104 ++++++++++--------- doc/src/images/listview-decorations.png | Bin 0 -> 12131 bytes doc/src/images/listview-section.png | Bin 0 -> 11053 bytes doc/src/images/listview-setup.png | Bin 0 -> 7117 bytes doc/src/images/qml-listview-snippet.png | Bin 2048 -> 0 bytes .../snippets/declarative/listview-decorations.qml | 111 +++++++++++++++++++++ doc/src/snippets/declarative/listview-sections.qml | 101 +++++++++++++++++++ doc/src/snippets/declarative/listview.qml | 87 ++++++++++++++++ .../declarative/listview/listview-snippet.qml | 52 ---------- 9 files changed, 355 insertions(+), 100 deletions(-) create mode 100644 doc/src/images/listview-decorations.png create mode 100644 doc/src/images/listview-section.png create mode 100644 doc/src/images/listview-setup.png delete mode 100644 doc/src/images/qml-listview-snippet.png create mode 100644 doc/src/snippets/declarative/listview-decorations.qml create mode 100644 doc/src/snippets/declarative/listview-sections.qml create mode 100644 doc/src/snippets/declarative/listview.qml delete mode 100644 doc/src/snippets/declarative/listview/listview-snippet.qml diff --git a/doc/src/declarative/qmlviews.qdoc b/doc/src/declarative/qmlviews.qdoc index c207d9a..8b2ca96 100644 --- a/doc/src/declarative/qmlviews.qdoc +++ b/doc/src/declarative/qmlviews.qdoc @@ -33,74 +33,82 @@ \nextpage {Extending QML Functionalities using C++} \title Presenting Data with Views -\section1 Introduction - Views are containers for collections of items. They are feature-rich and can be customizable to meet style or behavior requirements. +\keyword qml-view-elements 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 -\o \l{WebView}{WebView} - available from the Qt WebKit module. - +\o \l{ListView} arranges items in a horizontal or vertical list +\o \l{GridView} arranges items in a grid within the available space +\o \l{PathView} arranges items on a path +\o \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}. \endlist - -Unlike these items, \l WebView is not a fully-featured view item, and needs +Unlike other views, \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. +These elements have properties and behaviors exclusive to each element. Visit +their respective documentation for more information. + \section1 Models -Views display a \l{qml-data-models}{models} onto the screen. A model could be a simple list of \l{QML Data Models#An Integer}{integer} or a \l{qml-c++-models}{C++ models}. +Views display \l{qml-data-models}{models} onto the screen. A model could be a simple list of \l{QML Data Models#An Integer}{integer} or a \l{qml-c++-models}{C++ model}. To assign a model to a view, bind the view's \c model property to a model. +\snippet doc/src/snippets/declarative/listview.qml model +\snippet doc/src/snippets/declarative/listview.qml model -\section1 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 +For more information, consult the \l {QML Data Models} article. +\keyword qml-view-delegate +\section1 View Delegates - -\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. +Views need a \e delegate to visually represent an item in a list. A view will +visual each item list according to the template defined by the delegate. +Properties of the model are accessible as well as an \c index property. +\snippet doc/src/snippets/declarative/listview.qml delegate +\image listview-setup.png \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. +Views allow visual customization through \e decoration properties such as the \c header, \c footer, and \c section properties. By binding an object, usually +another visual object, to these properties, the views are decoratable. A footer +may include a \l Rectangle element showcasing borders or a header that displays +a logo on top of the list. + +Suppose that a specific club wants to decorate its members list with its brand +colors. A member list is in a \c model and the \c delegate will display the +model's content. +\snippet doc/src/snippets/declarative/listview-decorations.qml model +\snippet doc/src/snippets/declarative/listview-decorations.qml delegate + +The club may decorate the members list by binding visual objects to the +\c header and \c footer properties. The visual object may be defined inline, in another file, or in a +\l {Component} element. +\snippet doc/src/snippets/declarative/listview-decorations.qml decorations +\image listview-decorations.png + +\section1 ListView Sections + +\l {ListView} contents may be grouped into \e sections, where related list items +are labelled according to their sections. Further, the sections may be decorated +with \l{qml-view-delegate}{delegates}. + +A list may contain a list indicating people's names and the team on which team +the person belongs. +\snippet doc/src/snippets/declarative/listview-sections.qml model +\snippet doc/src/snippets/declarative/listview-sections.qml delegate + +The ListView element has the \c section +\l{qml-attached-properties}{attached property} that can combine adjacent +and related elements into a section. The section's \c property property is for +selecting which list element property to use as sections. The \c criteria +can dictate how the section names are displayed and the \c delegate is similar +to the views' \l {qml-view-delegate}{delegate} property. +\snippet doc/src/snippets/declarative/listview-sections.qml section +\image listview-section.png -\section1 Further Reading */ diff --git a/doc/src/images/listview-decorations.png b/doc/src/images/listview-decorations.png new file mode 100644 index 0000000..445c648 Binary files /dev/null and b/doc/src/images/listview-decorations.png differ diff --git a/doc/src/images/listview-section.png b/doc/src/images/listview-section.png new file mode 100644 index 0000000..a3664fc Binary files /dev/null and b/doc/src/images/listview-section.png differ diff --git a/doc/src/images/listview-setup.png b/doc/src/images/listview-setup.png new file mode 100644 index 0000000..5293d05 Binary files /dev/null and b/doc/src/images/listview-setup.png differ diff --git a/doc/src/images/qml-listview-snippet.png b/doc/src/images/qml-listview-snippet.png deleted file mode 100644 index 0ee0ffc..0000000 Binary files a/doc/src/images/qml-listview-snippet.png and /dev/null differ diff --git a/doc/src/snippets/declarative/listview-decorations.qml b/doc/src/snippets/declarative/listview-decorations.qml new file mode 100644 index 0000000..6b6d950 --- /dev/null +++ b/doc/src/snippets/declarative/listview-decorations.qml @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import QtQuick 1.0 + +//! [parent begin] +Rectangle { +//! [parent begin] + width: 550; height: 220; color: "white" + +//! [model] +ListModel { + id: nameModel + ListElement { name: "Alice" } + ListElement { name: "Bob" } + ListElement { name: "Jane" } + ListElement { name: "Harry" } + ListElement { name: "Wendy" } +} +//! [model] + +//! [delegate] +Component { + id: nameDelegate + Text { + text: name; + font.pixelSize: 24 + } +} +//! [delegate] + +//! [decorations] +ListView { + anchors.fill: parent + clip: true + model: nameModel + delegate: nameDelegate + header: bannercomponent + footer: Rectangle { + width: parent.width; height: 30; + gradient: clubcolors + } + highlight: Rectangle { + width: parent.width + color: "lightgray" + } +} + +Component { //instantiated when header is processed + id: bannercomponent + Rectangle { + id: banner + width: parent.width; height: 50 + gradient: clubcolors + border {color: "#9EDDF2"; width: 2} + Text { + anchors.centerIn: parent + text: "Club Members" + font.pixelSize: 32 + } + } +} +Gradient { + id: clubcolors + GradientStop { position: 0.0; color: "#8EE2FE"} + GradientStop { position: 0.66; color: "#7ED2EE"} +} +//! [decorations] + +//! [parent end] +} +//! [parent end] +//! [document] diff --git a/doc/src/snippets/declarative/listview-sections.qml b/doc/src/snippets/declarative/listview-sections.qml new file mode 100644 index 0000000..a573059 --- /dev/null +++ b/doc/src/snippets/declarative/listview-sections.qml @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +//! [document] +import QtQuick 1.0 + +//! [parent begin] +Rectangle { +//! [parent begin] + width: 150; height: 300; color: "white" + +//! [model] +ListModel { + id: nameModel + ListElement { name: "Alice"; team: "Crypto" } + ListElement { name: "Bob"; team: "Crypto" } + ListElement { name: "Jane"; team: "QA" } + ListElement { name: "Victor"; team: "QA" } + ListElement { name: "Wendy"; team: "Graphics" } +} +//! [model] + +//! [delegate] +Component { + id: nameDelegate + Text { + text: name; + font.pixelSize: 24 + anchors.left: parent.left + anchors.leftMargin: 2 + } +} +//! [delegate] + +//! [section] +ListView { + anchors.fill: parent + model: nameModel + delegate: nameDelegate + focus: true + highlight: Rectangle { + color: "lightblue" + width: parent.width + } + section { + property: "team" + criteria: ViewSection.FullString + delegate: Rectangle { + color: "#b0dfb0" + width: parent.width + height: childrenRect.height + 4 + Text { anchors.horizontalCenter: parent.horizontalCenter + font.pixelSize: 16 + font.bold: true + text: section + } + } + } +} +//! [section] + +//! [parent end] +} +//! [parent end] +//! [document] diff --git a/doc/src/snippets/declarative/listview.qml b/doc/src/snippets/declarative/listview.qml new file mode 100644 index 0000000..4bb48bc --- /dev/null +++ b/doc/src/snippets/declarative/listview.qml @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import QtQuick 1.0 + +//! [parent begin] +Rectangle { +//! [parent begin] + width: 175; height: 175; color: "white" + +//! [model] +ListModel { + id: petlist + ListElement { type: "Cat" } + ListElement { type: "Dog" } + ListElement { type: "Mouse" } + ListElement { type: "Rabbit" } + ListElement { type: "Horse" } +} +//! [model] + +//! [delegate] +Component { + id: petdelegate + Text { + id: label + font.pixelSize: 24 + text: if (index == 0) + label.text = type + " (default)" + else + text: type + } +} +//! [delegate] + +//! [view] +ListView { + id: view + anchors.fill: parent + + model: petlist + delegate: petdelegate +} +//! [view] + +//! [parent end] +} +//! [parent end] +//! [document] diff --git a/doc/src/snippets/declarative/listview/listview-snippet.qml b/doc/src/snippets/declarative/listview/listview-snippet.qml deleted file mode 100644 index f73dec9..0000000 --- a/doc/src/snippets/declarative/listview/listview-snippet.qml +++ /dev/null @@ -1,52 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2011 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:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor -** the names of its contributors may be used to endorse or promote -** products derived from this software without specific prior written -** permission. -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [document] -import QtQuick 1.0 - -ListView { - width: 50; height: 200 - model: 4 - delegate: Text { - text: index; - font.pixelSize: 40 - } -} -//! [document] -- cgit v0.12 From 8f7bef6afecd53ed07e07618caad02066e5b2d05 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Wed, 16 Feb 2011 16:57:18 +0100 Subject: Removed links to unfinished documentation. Task-number: QTBUG-16071 --- doc/src/declarative/declarativeui.qdoc | 4 ---- 1 file changed, 4 deletions(-) diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 277903f..580541a 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -139,11 +139,7 @@ examples for porting} \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 */ -- cgit v0.12 From e91a42b7dfe9805e4025467f81af9ec713e0904b Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Wed, 16 Feb 2011 18:54:09 +0100 Subject: Added a qdoc keyword --- doc/src/declarative/propertybinding.qdoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/declarative/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 2bce0c5..22d14a8 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -204,8 +204,8 @@ The snippet code simply prints the name of the first state, \c FETCH. See the \l{list}{list type} documentation for more details about list properties and their available operations. +\keyword qml-grouped-properties \section2 Grouped Properties -\target dot properties In some cases properties form a logical group and use either the \e dot notation or \e group notation. -- cgit v0.12 From 9c080688f49c19c362d3f69f7d1762521efc045f Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 17 Feb 2011 10:28:49 +0100 Subject: Removed section names and added a link to Qt Quick page. Task-number: QTBUG-16071 --- doc/src/declarative/anchor-layout.qdoc | 2 - doc/src/declarative/animation.qdoc | 2 - doc/src/declarative/declarativeui.qdoc | 2 - doc/src/declarative/elements.qdoc | 5 +- doc/src/declarative/example-slideswitch.qdoc | 2 - doc/src/declarative/positioners.qdoc | 2 - doc/src/declarative/qdeclarativedocument.qdoc | 2 - doc/src/declarative/qdeclarativei18n.qdoc | 1 - doc/src/declarative/qdeclarativestates.qdoc | 2 - doc/src/declarative/qtprogrammers.qdoc | 2 - doc/src/declarative/qtquick-intro.qdoc | 37 +++++--- doc/src/declarative/scope.qdoc | 122 +++++++++++--------------- 12 files changed, 76 insertions(+), 105 deletions(-) diff --git a/doc/src/declarative/anchor-layout.qdoc b/doc/src/declarative/anchor-layout.qdoc index 7fc16d8..4dd5eb9 100644 --- a/doc/src/declarative/anchor-layout.qdoc +++ b/doc/src/declarative/anchor-layout.qdoc @@ -33,8 +33,6 @@ \nextpage {QML Mouse Events}{Mouse Events} \title Anchor-based Layout in QML -\section1 Overview - 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": diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index bd6813c..7247e73 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -59,8 +59,6 @@ Elements that animate properties based on data types \o \l {AnchorAnimation} - Animates anchor changes \endlist -\section1 Overview - In QML, animations are created by applying animation elements to property values. Animation elements will interpolate property values to create smooth transitions. As well, state transitions may assign animations to state changes. diff --git a/doc/src/declarative/declarativeui.qdoc b/doc/src/declarative/declarativeui.qdoc index 580541a..ff38ac6 100644 --- a/doc/src/declarative/declarativeui.qdoc +++ b/doc/src/declarative/declarativeui.qdoc @@ -33,8 +33,6 @@ \brief Qt Quick provides a declarative framework for building highly dynamic user interfaces. -\section1 Introduction - Qt Quick is a collection of technologies that are designed to help developers create the kind of intuitive, modern, fluid user interfaces that are increasingly used on mobile phones, media players, diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index 466b940..c087f17 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -31,7 +31,8 @@ \title QML Elements \brief A listing of standard QML elements. -These are the functionally grouped lists of QML elements. +These are the functionally grouped lists of QML elements as part of +\l{Qt Quick}. Elements are declared with the their name and two curly braces. Elements may be nested in elements, thereby creating a parent-child relationship between the @@ -44,7 +45,7 @@ To see the QML elements listed by functional area, see the \list \o \l {Item} - Basic item element inherited by QML elements \o \l {Component} - Encapsulates QML elements during importing -\o \l {QML:QtObject} {QtObject} - Basic element containing only the objectName property +\o \l {QML:QtObject} {QtObject} - Basic element containing only the \c {objectName} property \endlist \section1 Graphics diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc index 9f84ee6..54ee2c7 100644 --- a/doc/src/declarative/example-slideswitch.qdoc +++ b/doc/src/declarative/example-slideswitch.qdoc @@ -33,8 +33,6 @@ This example shows how to create a reusable switch component in QML. The code for this example can be found in the \c $QTDIR/examples/declarative/ui-components/slideswitch directory. -\section1 Overview - The elements that composed the switch are: \list diff --git a/doc/src/declarative/positioners.qdoc b/doc/src/declarative/positioners.qdoc index c91ed9a..0ac6a2b 100644 --- a/doc/src/declarative/positioners.qdoc +++ b/doc/src/declarative/positioners.qdoc @@ -34,8 +34,6 @@ \title Using QML Positioner and Repeater Items -\section1 Introduction - Positioner items are container items that manage the positions and sizes of items in a declarative user interface. Positioners behave in a similar way to the \l{Widgets and Layouts}{layout managers} used with standard Qt widgets, diff --git a/doc/src/declarative/qdeclarativedocument.qdoc b/doc/src/declarative/qdeclarativedocument.qdoc index f2147de..423d77c 100644 --- a/doc/src/declarative/qdeclarativedocument.qdoc +++ b/doc/src/declarative/qdeclarativedocument.qdoc @@ -30,8 +30,6 @@ \title QML Documents \brief A description of QML documents and the kind of content they contain. -\section1 Introduction - A QML document is a block of QML source code. QML documents generally correspond to files stored on a disk or at a location on a network, but they can also be constructed directly from text data. diff --git a/doc/src/declarative/qdeclarativei18n.qdoc b/doc/src/declarative/qdeclarativei18n.qdoc index 3d97113..bbee37c 100644 --- a/doc/src/declarative/qdeclarativei18n.qdoc +++ b/doc/src/declarative/qdeclarativei18n.qdoc @@ -33,7 +33,6 @@ \nextpage {QML Features} \title QML Internationalization -\section1 Overview Strings in QML can be marked for translation using the qsTr(), qsTranslate(), QT_TR_NOOP(), and QT_TRANSLATE_NOOP() functions. diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index 3f05c9b..b1a97d7 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -44,8 +44,6 @@ \o \l AnchorChanges \endlist -\section1 Overview - Many user interface designs are \e state driven; interfaces have configurations that differ depending on the current state. For example, a traffic signal will configure its flags or lights depending on its state. While in the signal's diff --git a/doc/src/declarative/qtprogrammers.qdoc b/doc/src/declarative/qtprogrammers.qdoc index 97caf80..e48dc9a 100644 --- a/doc/src/declarative/qtprogrammers.qdoc +++ b/doc/src/declarative/qtprogrammers.qdoc @@ -30,8 +30,6 @@ \target qtprogrammers \title QML for Qt Programmers -\section1 Overview - While QML does not require Qt knowledge to use, if you \e are already familiar with Qt, much of your knowledge is directly relevant to learning and using QML. Of course, an application with a UI defined in QML also uses Qt for all the non-UI logic. diff --git a/doc/src/declarative/qtquick-intro.qdoc b/doc/src/declarative/qtquick-intro.qdoc index 2315030..1bbae8f 100644 --- a/doc/src/declarative/qtquick-intro.qdoc +++ b/doc/src/declarative/qtquick-intro.qdoc @@ -29,25 +29,34 @@ \page qml-intro.html \title Intro to Qt Quick -Qt Quick is a collection of technologies that are designed to help developers create the kind of intuitive, modern, and fluid user interfaces that are increasingly used on mobile phones, media players, set-top boxes, and other portable devices. Qt Quick consists of a rich set of user interface \l{QML Elements}{elements}, a \l{QML Syntax}{declarative} language for describing user interfaces, and a language \l{QtDeclarative Module}{runtime}. A collection of C++ APIs is used to integrate these high level features with classic Qt applications. Version 2.1 of the Qt Creator integrated development environment (IDE) introduces tools for developing Qt Quick applications. +Qt Quick is a collection of technologies that are designed to help developers +create the kind of intuitive, modern, and fluid user interfaces that are +increasingly used on mobile phones, media players, set-top boxes, and other +portable devices. Qt Quick consists of a rich set of user interface +\l{QML Elements}{elements}, a \l{QML Syntax}{declarative} language for +describing user interfaces, and a language \l{QtDeclarative Module}{runtime}. A +collection of C++ APIs is used to integrate these high level features with +classic Qt applications. Version 2.1 of the Qt Creator integrated development +environment (IDE) introduces tools for developing Qt Quick applications. \image qml-clocks-example.png \section1 The QML Language -QML is a high level, scripted language. Its commands, more correctly \e elements, -leverage the power and efficiency of the Qt libraries to make easy to use -commands that perform intuitive functions. Drawing a rectangle, displaying an -image, and application events -- all are possible with declarative programming. +QML is a high level, scripted language. Its commands, more correctly +\e elements, leverage the power and efficiency of the Qt libraries to make easy +to use commands that perform intuitive functions. Drawing a rectangle, +displaying an image, and application events -- all are possible with declarative +programming. The language also allows more flexibility of these commands by using \l{About JavaScript}{JavaScript} to implement the high level user interface logic. -A QML element usually has various \e properties that help define the element. For -example, if we created an element called Circle then the radius of the circle -would be a property. Building user interfaces by importing these elements is one -of the great feature of QML and Qt Quick. +A QML element usually has various \e properties that help define the element. +For example, if we created an element called Circle then the radius of the +circle would be a property. Building user interfaces by importing these elements +is one of the great feature of QML and Qt Quick. \image qml-texteditor5_newfile.png \section1 QtDeclarative Module @@ -55,7 +64,8 @@ of the great feature of QML and Qt Quick. To make Qt Quick possible, Qt introduces the \l {QtDeclarative} module. The module creates a JavaScript runtime that QML runs under with a Qt based backend. Because QtDeclarative and QML are built upon Qt, they inherit many of Qt's -technology, namely the \l{Signals and Slots}{signals and slots} mechanism and the \l{The Meta-Object System}{meta-object} system. Data created using C++ are +technology, namely the \l{Signals and Slots}{signals and slots} mechanism and +the \l{The Meta-Object System}{meta-object} system. Data created using C++ are directly accessible from QML and QML objects are also accessible from C++ code. In conjunction with the QML language, the QtDeclarative module separates the @@ -63,7 +73,8 @@ interface logic in QML from the application logic in C++. \section1 Creator Tools -Qt Creator is a complete integrated development environment (IDE) for creating applications with Qt Quick and the Qt application framework. +Qt Creator is a complete integrated development environment (IDE) for creating +applications with Qt Quick and the Qt application framework. \image qmldesigner-visual-editor.png @@ -98,8 +109,8 @@ system. \section1 Where to Go from Here -The \l {Qt Quick} page has links to various Qt Quick topics such as QML features, -addons, and tools. +The \l {Qt Quick} page has links to various Qt Quick topics such as QML +features, addons, and tools. The \l {QML Examples and Demos} page has a gallery of QML applications. */ diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc index 3317037..9a9934a 100644 --- a/doc/src/declarative/scope.qdoc +++ b/doc/src/declarative/scope.qdoc @@ -24,41 +24,17 @@ ** $QT_END_LICENSE$ ** ****************************************************************************/ - -/* - - - -and requires extension to -fit naturally with QML. - - -JavaScript has only b -JavaScript has a very simple built in scope is very simple - -script, and the precede d - -and \l {Integrating JavaScript}{JavaScript} are executed in a scope chain -automatically established by QML when a component instance is constructed. QML is a \e {dynamically scoped} -language. Different object instances instantiated from the same component can exist in -different scope chains. - -\image qml-scope.png - - -*/ - /*! \page qdeclarativescope.html \title QML Scope \tableofcontents -QML property bindings, inline functions and imported JavaScript files all -run in a JavaScript scope. Scope controls which variables an expression can +QML property bindings, inline functions and imported JavaScript files all +run in a JavaScript scope. Scope controls which variables an expression can access, and which variable takes precedence when two or more names conflict. -As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit +As JavaScript's built-in scope mechanism is very simple, QML enhances it to fit more naturally with the QML language extensions. \section1 JavaScript Scope @@ -67,8 +43,8 @@ QML's scope extensions do not interfere with JavaScript's natural scoping. JavaScript programmers can reuse their existing knowledge when programming functions, property bindings or imported JavaScript files in QML. -In the following example, the \c {addConstant()} method will add 13 to the -parameter passed just as the programmer would expect irrespective of the +In the following example, the \c {addConstant()} method will add 13 to the +parameter passed just as the programmer would expect irrespective of the value of the QML object's \c a and \c b properties. \code @@ -83,8 +59,8 @@ QtObject { } \endcode -That QML respects JavaScript's normal scoping rules even applies in bindings. -This totally evil, abomination of a binding will assign 12 to the QML object's +That QML respects JavaScript's normal scoping rules even applies in bindings. +This totally evil, abomination of a binding will assign 12 to the QML object's \c a property. \code @@ -101,13 +77,13 @@ with local variables declared in another. \section1 Element Names and Imported JavaScript Files -\l {QML Document}s include import statements that define the element names -and JavaScript files visible to the document. In addition to their use in the -QML declaration itself, element names are used by JavaScript code when accessing -\l {Attached Properties} and enumeration values. +\l {QML Document}s include import statements that define the element names +and JavaScript files visible to the document. In addition to their use in the +QML declaration itself, element names are used by JavaScript code when accessing +\l {Attached Properties} and enumeration values. -The effect of an import applies to every property binding, and JavaScript -function in the QML document, even those in nested inline components. The +The effect of an import applies to every property binding, and JavaScript +function in the QML document, even those in nested inline components. The following example shows a simple QML file that accesses some enumeration values and calls an imported JavaScript function. @@ -130,10 +106,10 @@ ListView { \section1 Binding Scope Object -Property bindings are the most common use of JavaScript in QML. Property +Property bindings are the most common use of JavaScript in QML. Property bindings associate the result of a JavaScript expression with a property of an -object. The object to which the bound property belongs is known as the binding's -scope object. In this QML simple declaration the \l Item object is the +object. The object to which the bound property belongs is known as the binding's +scope object. In this QML simple declaration the \l Item object is the binding's scope object. \code @@ -144,21 +120,21 @@ Item { Bindings have access to the scope object's properties without qualification. In the previous example, the binding accesses the \l Item's \c parent property -directly, without needing any form of object prefix. QML introduces a more -structured, object-oriented approach to JavaScript, and consequently does not +directly, without needing any form of object prefix. QML introduces a more +structured, object-oriented approach to JavaScript, and consequently does not require the use of the JavaScript \c this property. Care must be used when accessing \l {Attached Properties} from bindings due to their interaction with the scope object. Conceptually attached properties exist on \e all objects, even if they only have an effect on a subset of those. -Consequently unqualified attached property reads will always resolve to an -attached property on the scope object, which is not always what the programmer +Consequently unqualified attached property reads will always resolve to an +attached property on the scope object, which is not always what the programmer intended. -For example, the \l PathView element attaches interpolated value properties to +For example, the \l PathView element attaches interpolated value properties to its delegates depending on their position in the path. As PathView only -meaningfully attaches these properties to the root element in the delegate, any -sub-element that accesses them must explicitly qualify the root object, as shown +meaningfully attaches these properties to the root element in the delegate, any +sub-element that accesses them must explicitly qualify the root object, as shown below. \code @@ -181,7 +157,7 @@ the unset \c {PathView.scale} attached property on itself. Each QML component in a QML document defines a logical scope. Each document has at least one root component, but can also have other inline sub-components. -The component scope is the union of the object ids within the component and the +The component scope is the union of the object ids within the component and the component's root element's properties. \code @@ -195,7 +171,7 @@ Item { anchors.top: parent.top } - Text { + Text { text: titleElement.text font.pixelSize: 18 anchors.bottom: parent.bottom @@ -203,7 +179,7 @@ Item { } \endcode -The example above shows a simple QML component that displays a rich text title +The example above shows a simple QML component that displays a rich text title string at the top, and a smaller copy of the same text at the bottom. The first \c Text element directly accesses the component's \c title property when forming the text to display. That the root element's properties are directly @@ -211,18 +187,18 @@ accessible makes it trivial to distribute data throughout the component. The second \c Text element uses an id to access the first's text directly. IDs are specified explicitly by the QML programmer so they always take precedence -over other property names (except for those in the \l {JavaScript Scope}). For -example, in the unlikely event that the binding's \l {Binding Scope Object}{scope -object} had a \c titleElement property in the previous example, the \c titleElement +over other property names (except for those in the \l {JavaScript Scope}). For +example, in the unlikely event that the binding's \l {Binding Scope Object}{scope +object} had a \c titleElement property in the previous example, the \c titleElement id would still take precedence. \section1 Component Instance Hierarchy -In QML, component instances connect their component scopes together to form a -scope hierarchy. Component instances can directly access the component scopes of +In QML, component instances connect their component scopes together to form a +scope hierarchy. Component instances can directly access the component scopes of their ancestors. -The easiest way to demonstrate this is with inline sub-components whose component +The easiest way to demonstrate this is with inline sub-components whose component scopes are implicitly scoped as children of the outer component. \code @@ -239,16 +215,16 @@ Item { } \endcode -The component instance hierarchy allows instances of the delegate component +The component instance hierarchy allows instances of the delegate component to access the \c defaultColor property of the \c Item element. Of course, -had the delegate component had a property called \c defaultColor that would -have taken precedence. +had the delegate component had a property called \c defaultColor that would +have taken precedence. The component instance scope hierarchy extends to out-of-line components, too. -In the following example, the \c TitlePage.qml component creates two -\c TitleText instances. Even though the \c TitleText element is in a separate -file, it still has access to the \c title property when it is used from within -the \c TitlePage. QML is a dynamically scoped language - depending on where it +In the following example, the \c TitlePage.qml component creates two +\c TitleText instances. Even though the \c TitleText element is in a separate +file, it still has access to the \c title property when it is used from within +the \c TitlePage. QML is a dynamically scoped language - depending on where it is used, the \c title property may resolve differently. \code @@ -256,13 +232,13 @@ is used, the \c title property may resolve differently. import QtQuick 1.0 Item { property string title - - TitleText { + + TitleText { size: 22 anchors.top: parent.top } - TitleText { + TitleText { size: 18 anchors.bottom: parent.bottom } @@ -277,10 +253,10 @@ Text { } \endcode -Dynamic scoping is very powerful, but it must be used cautiously to prevent +Dynamic scoping is very powerful, but it must be used cautiously to prevent the behavior of QML code from becoming difficult to predict. In general it -should only be used in cases where the two components are already tightly -coupled in another way. When building reusable components, it is preferable +should only be used in cases where the two components are already tightly +coupled in another way. When building reusable components, it is preferable to use property interfaces, like this: \code @@ -289,14 +265,14 @@ import QtQuick 1.0 Item { id: root property string title - - TitleText { + + TitleText { title: root.title size: 22 anchors.top: parent.top } - TitleText { + TitleText { title: root.title size: 18 anchors.bottom: parent.bottom @@ -322,7 +298,7 @@ QML specific tasks a little easier. These extensions are described in the \l {QML Global Object} documentation. QML disallows element, id and property names that conflict with the properties -on the global object to prevent any confusion. Programmers can be confident +on the global object to prevent any confusion. Programmers can be confident that \c Math.min(10, 9) will always work as expected! */ -- cgit v0.12 From fe1a74289a32381d58fc045f9895a159b011d58b Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 17 Feb 2011 10:33:52 +0100 Subject: Wrote an overview for the WebKit QML module. Task-number: QTBUG-16071 --- doc/src/declarative/qmlwebkit.qdoc | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/doc/src/declarative/qmlwebkit.qdoc b/doc/src/declarative/qmlwebkit.qdoc index 0f4e86b..354e60a 100644 --- a/doc/src/declarative/qmlwebkit.qdoc +++ b/doc/src/declarative/qmlwebkit.qdoc @@ -26,22 +26,30 @@ ****************************************************************************/ /*! - \page qmlwebkit.html +\page qmlwebkit.html - \title QtWebKit QML Module +\title QtWebKit QML Module - Qt WebKit QML +Qt WebKit QML - \section1 WebKit QML Elements - \list - \o \l WebView - \o \l FlickableWebView - \endlist +\section1 WebKit QML Elements +\list +\o \l WebView +\endlist - \section1 Content +\section1 QtWebKit Module +The QtWebKit Module has a QML element, \l{WebView} for displaying web content +from a \c URL. - \section1 Usage Ideas +Import the QtWebKit module before declaring a \c WebView element: +\qml +import QtWebKit 1.0 +\endqml - \section1 Other Suggestions +\section1 Simple Usage +\snippet doc/src/snippets/declarative/webview/webview.qml document +\image webview.png + +\sa {Models and Views: WebView Example}{WebView Example}, {QML Web Browser} */ -- cgit v0.12 From 6ff22762df68d60288cdc95b9359ca2544bd7bbe Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Thu, 17 Feb 2011 15:39:48 +0100 Subject: Adding snippet code to coding article. Task-number: QTBUG-16071 --- doc/src/declarative/graphicaleffects.qdoc | 36 ------- .../qmlbestpractices/qmlbestpractices-coding.qdoc | 105 +++++++++++---------- .../snippets/declarative/bestpractices/group.qml | 75 +++++++++++++++ 3 files changed, 132 insertions(+), 84 deletions(-) delete mode 100644 doc/src/declarative/graphicaleffects.qdoc create mode 100644 doc/src/snippets/declarative/bestpractices/group.qml diff --git a/doc/src/declarative/graphicaleffects.qdoc b/doc/src/declarative/graphicaleffects.qdoc deleted file mode 100644 index b5ef601..0000000 --- a/doc/src/declarative/graphicaleffects.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). -** All rights reserved. -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE: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/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc b/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc index 6c83c80..e33ee13 100644 --- a/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc +++ b/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc @@ -26,69 +26,78 @@ ****************************************************************************/ /*! - \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 +\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 +\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. +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 +\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. +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}. +In addition, Qt's official code style may be found at the \l {Qt Coding Style}. - \section1 Importing Files into QML +\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. +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 +\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. +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 +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. - Rectangle { - width: 50; height: 50 +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. By using the \c qmldir file, users may import any QML file and assign any +valid QML component name to the component. - Button {} //Button is defined in Button.qml in the same directory - } - \endqml +For more information, read the section on +\l{qml-loading-components}{Loading a Component}. - 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. +\section1 Commenting Code - 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. +Commenting code allows others to read the source code better. As well, comments +allow the programmer to think about his or her code; a confusing comment may +mean the code is confusing. - \code - //A very simple qmldir file +Similar to JavaScript or C++, there are two ways of commenting QML code: +\list +\o Single line comments start with \c{//} and finish at the end of the line +\o Multiline comments start with \c{/*} and finish with *\/ +\endlist - 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 +\section1 Group Properties + +Many QML properties are \l{attached-properties}{attached} or +\l {qml-grouped-properties}{group} properties. For convenience, you may treat +them as another element when dealing with multiple properties belonging to the +same group. + +\snippet doc/src/snippets/declarative/bestpractices/group.qml not grouped +Treating groups of properties as a block can ease confusion and help relate the +properties with other properties. +\snippet doc/src/snippets/declarative/bestpractices/group.qml grouped - 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/snippets/declarative/bestpractices/group.qml b/doc/src/snippets/declarative/bestpractices/group.qml new file mode 100644 index 0000000..07243dc --- /dev/null +++ b/doc/src/snippets/declarative/bestpractices/group.qml @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import QtQuick 1.0 + +//! [parent begin] +Rectangle { +//! [parent begin] + width: 175; height: 175; color: "white" + +Rectangle{ +width: 170; height: 170 +//! [not grouped] +border.width: 1 +border.color: "red" +anchors.bottom: parent.bottom +anchors.left: parent.left +//! [not grouped] +} +Rectangle { + width: 100; height: 100 + +//! [grouped] +border { + width: 1; + color: "red" +} +anchors { + bottom: parent.bottom; + left: parent.left +} +//! [grouped] +} +//! [parent end] +} +//! [parent end] +//! [document] -- cgit v0.12 From 5e1927288d1bcdf4fa597985f1c15655a9922a4d Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 17 Feb 2011 19:02:44 +0100 Subject: Doc: Clarified the -1 return value of QIODevice::readData(). --- src/corelib/io/qiodevice.cpp | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/corelib/io/qiodevice.cpp b/src/corelib/io/qiodevice.cpp index 43e0f0d..7134ae9 100644 --- a/src/corelib/io/qiodevice.cpp +++ b/src/corelib/io/qiodevice.cpp @@ -1628,10 +1628,11 @@ QString QIODevice::errorString() const \fn qint64 QIODevice::readData(char *data, qint64 maxSize) Reads up to \a maxSize bytes from the device into \a data, and - returns the number of bytes read or -1 if an error occurred. If - there are no bytes to be read, this function should return -1 if - there can never be more bytes available (for example: socket - closed, pipe closed, sub-process finished). + returns the number of bytes read or -1 if an error occurred. + + If there are no bytes to be read and there can never be more bytes + available (examples include socket closed, pipe closed, sub-process + finished), this function returns -1. This function is called by QIODevice. Reimplement this function when creating a subclass of QIODevice. -- cgit v0.12 From f7c20e9b9133b841c32f0ac8770b92473c50a2c0 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 17 Feb 2011 19:11:04 +0100 Subject: Doc: Fixed broken links. --- doc/src/development/qmake-manual.qdoc | 193 +++++++++++++++++++--------------- doc/src/external-resources.qdoc | 20 ++++ 2 files changed, 131 insertions(+), 82 deletions(-) diff --git a/doc/src/development/qmake-manual.qdoc b/doc/src/development/qmake-manual.qdoc index da105e6..6cfe356 100644 --- a/doc/src/development/qmake-manual.qdoc +++ b/doc/src/development/qmake-manual.qdoc @@ -908,13 +908,13 @@ {deployment guide for Windows}. - \section1 Symbian platform + \section1 Symbian Platform Features specific to this platform include handling of static data, capabilities, stack and heap size, compiler specific options, and unique identifiers for the application or library. - \section2 Handling of static data + \section2 Handling of Static Data If the application uses any static data, the build system needs to be informed about it. This is because Symbian tries to save memory if no @@ -926,7 +926,7 @@ The default value is zero. - \section2 Stack and heap size + \section2 Stack and Heap Size The Symbian platform uses predefined sizes for stacks and heaps. If an application exceeds either limit, it may crash or fail to complete its @@ -941,10 +941,10 @@ \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 130 The default values depend on the version of the Symbian SDK you're using, - however, the Qt toolchain sets this to the maximum possible value and this - should not be changed. + however, the Qt toolchain sets this to the maximum possible value and this + should not be changed. - \section2 Compiler specific options + \section2 Compiler-Specific Options General compiler options can as usual be set using \c QMAKE_CFLAGS and \c QMAKE_CXXFLAGS. In order to set specific compiler options, \c QMAKE_CFLAGS. and @@ -956,7 +956,7 @@ \snippet doc/src/snippets/code/doc_src_qmake-manual.pro 131 - \section2 Unique identifiers + \section2 Unique Identifiers Symbian applications may have unique identifiers attached to them. Here is how to define them in a project file: @@ -969,19 +969,22 @@ If \c SID is not specified, it defaults to the same value as \c UID3. If \c UID3 is not specified, qmake will automatically generate a \c UID3 suitable for development and debugging. This value should be manually - specified for applications that are to be released. In order to obtain - an official UID, please contact \l{Symbian}{http:\\www.symbiansigned.com}. - Both \c SID and \c VID default to empty values. + specified for applications that are to be released. See the + \l{Symbian Signed} Web site for information about obtaining an official + UID. + + Both \c SID and \c VID default to empty values. There exists one UID1 too, but this should not be touched by any application. - - The UID2 has a specific value for different types of files - e.g. apps/exes - are always 0x100039CE. The toolchain will set this for value for the most common file types like, - EXE/APP and shared library DLL. - - For more information about unique identifiers and their meaning for Symbian applications, - please refer to the \l{Symbian SDK documentation}{http://developer.symbian.org/main/documentation/reference/s3/pdk/GUID-380A8C4F-3EB6-5E1C-BCFB-ED5B866136D9.html} - + + The UID2 has a specific value for different types of files - e.g. apps/exes + are always 0x100039CE. The toolchain will set this for value for the most common file types like, + EXE/APP and shared library DLL. + + For more information about unique identifiers and their meaning for + Symbian applications, please refer to the \l{UID Q&As (Symbian Signed)} + page in the \l{Forum Nokia Wiki} for more information. + \section2 Capabilities Capabilities define extra privileges for the application, such as the @@ -3122,8 +3125,34 @@ \e {This is only used on the Symbian platform.} - Specifies which platform capabilities the application should have. For more - information, please refer to the Symbian SDK documentation. + Specifies which platform capabilities the application should have. These + include the following basic capabilities, but others are also available + for signed applications. + + \table + \header \o Capability \o Description + \row \o LocalServices \o The ability to use local services running on the + phone or device, including those which provide + local connectivity to other devices. + \row \o Location \o Access to the service that provides information + about the user's location, from GPS, phone + network, or other sources. + \row \o NetworkServices \o Use of services that access the phone network, + such as dialling a phone number, sending an SMS, + or other operations that result in network + traffic. + \row \o ReadUserData \o Access to the user's private data, such as + contact information. + \row \o UserEnvironment \o The ability to use services that provide from the + user's physical environment, such as the camera or + microphone. + \row \o WriteUserData \o The ability to write or modify the user's private + data. + \endtable + + For more information, and a comprehensive list of capabilities, please refer + to the Symbian SDK documentation or the \l{Symbian Capabilities} page of + the \l{Forum Nokia Wiki}. \target TARGET.EPOCALLOWDLLDATA \section1 TARGET.EPOCALLOWDLLDATA @@ -4004,65 +4033,65 @@ \table \header - \o Member - \o Description - \row - \o commands - \o The commands used for for generating the output from the input. - \row - \o CONFIG - \o Specific configuration options for the custom compiler. See the CONFIG table for details. - \row - \o depend_command - \o Specifies a command used to generate the list of dependencies for the output. - \row - \o dependency_type - \o Specifies the type of file the output is, if it is a known type (such as TYPE_C, - TYPE_UI, TYPE_QRC) then it is handled as one of those type of files. - \row - \o depends - \o Specifies the dependencies of the output file. - \row - \o input - \o The variable that contains the files that should be processed with the custom compiler. - \row - \o name - \o A description of what the custom compiler is doing. This is only used in some backends. - \row - \o output - \o The filename that is created from the custom compiler. - \row - \o output_function - \o Specifies a custom qmake function that is used to specify the filename to be created. - \row - \o variables - \o Indicates that the variables specified here are replaced with $(QMAKE_COMP_VARNAME) when refered to - in the pro file as $(VARNAME). - \row - \o variable_out - \o The variable that the files created from the output should be added to. - \endtable - - List of members specific to the CONFIG option: - - \table - \header - \o Member - \o Description - \row - \o combine - \o Indicates that all of the input files are combined into a single output file. - \row - \o target_predeps - \o Indicates that the output should be added to the list of PRE_TARGETDEPS. - \row - \o explicit_dependencies - \o The dependencies for the output only get generated from the depends member and from - nowhere else. - \row - \o no_link - \o Indicates that the output should not be added to the list of objects to be linked in. - \endtable + \o Member + \o Description + \row + \o commands + \o The commands used for for generating the output from the input. + \row + \o CONFIG + \o Specific configuration options for the custom compiler. See the CONFIG table for details. + \row + \o depend_command + \o Specifies a command used to generate the list of dependencies for the output. + \row + \o dependency_type + \o Specifies the type of file the output is, if it is a known type (such as TYPE_C, + TYPE_UI, TYPE_QRC) then it is handled as one of those type of files. + \row + \o depends + \o Specifies the dependencies of the output file. + \row + \o input + \o The variable that contains the files that should be processed with the custom compiler. + \row + \o name + \o A description of what the custom compiler is doing. This is only used in some backends. + \row + \o output + \o The filename that is created from the custom compiler. + \row + \o output_function + \o Specifies a custom qmake function that is used to specify the filename to be created. + \row + \o variables + \o Indicates that the variables specified here are replaced with $(QMAKE_COMP_VARNAME) when refered to + in the pro file as $(VARNAME). + \row + \o variable_out + \o The variable that the files created from the output should be added to. + \endtable + + List of members specific to the CONFIG option: + + \table + \header + \o Member + \o Description + \row + \o combine + \o Indicates that all of the input files are combined into a single output file. + \row + \o target_predeps + \o Indicates that the output should be added to the list of PRE_TARGETDEPS. + \row + \o explicit_dependencies + \o The dependencies for the output only get generated from the depends member and from + nowhere else. + \row + \o no_link + \o Indicates that the output should not be added to the list of objects to be linked in. + \endtable \note Symbian platform specific: Generating objects to be linked in is not supported on the Symbian platform, so either the \c CONFIG option @@ -4202,10 +4231,10 @@ Generally, the \c : operator behaves like a logical AND operator, joining together a number of conditions, and requiring all of them to be true. - There is also the \c | operator to act like a logical OR operator, joining - together a number of conditions, and requiring only one of them to be true. + There is also the \c | operator to act like a logical OR operator, joining + together a number of conditions, and requiring only one of them to be true. - \snippet doc/src/snippets/qmake/scopes.pro 4 + \snippet doc/src/snippets/qmake/scopes.pro 4 You can also provide alternative declarations to those within a scope by using an \c else scope. Each \c else scope is processed if the conditions diff --git a/doc/src/external-resources.qdoc b/doc/src/external-resources.qdoc index ada3cf7..1abeae9 100644 --- a/doc/src/external-resources.qdoc +++ b/doc/src/external-resources.qdoc @@ -463,3 +463,23 @@ \externalpage http://publicsuffix.org/ \title publicsuffix.org */ + +/*! + \externalpage http://wiki.forum.nokia.com/index.php/Capabilities + \title Symbian Capabilities +*/ + +/*! + \externalpage http://wiki.forum.nokia.com/ + \title Forum Nokia Wiki +*/ + +/*! + \externalpage http://wiki.forum.nokia.com/index.php/UID_Q&As_(Symbian_Signed) + \title UID Q&As (Symbian Signed) +*/ + +/*! + \externalpage http://www.symbiansigned.com + \title Symbian Signed +*/ -- cgit v0.12 From 0ec19822ab56c885921a25d169b9bdc03d09f3d2 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 17 Feb 2011 19:21:05 +0100 Subject: Added a build rule for the qdoc3 manual. --- tools/qdoc3/qdoc3.pro | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/tools/qdoc3/qdoc3.pro b/tools/qdoc3/qdoc3.pro index 2fedc0f..6f31c60 100644 --- a/tools/qdoc3/qdoc3.pro +++ b/tools/qdoc3/qdoc3.pro @@ -93,10 +93,24 @@ include($$QT_SOURCE_TREE/src/declarative/qml/parser/parser.pri) ### Documentation for qdoc3 ### qtPrepareTool(QDOC, qdoc3) +qtPrepareTool(QHELPGENERATOR, qhelpgenerator) -html-docs.commands = cd \"$$PWD/doc\" && $$QDOC qdoc-manual.qdocconf +$$unixstyle { + QDOC = QT_BUILD_TREE=$$QT_BUILD_TREE QT_SOURCE_TREE=$$QT_SOURCE_TREE $$QDOC +} else { + QDOC = set QT_BUILD_TREE=$$QT_BUILD_TREE&& set QT_SOURCE_TREE=$$QT_SOURCE_TREE&& $$QDOC + QDOC = $$replace(QDOC, "/", "\\") +} + +html-docs.commands = cd \"$$QT_BUILD_TREE/doc\" && $$QDOC $$QT_SOURCE_TREE/tools/qdoc3/doc/config/qdoc.qdocconf +html-docs.files = $$QT_BUILD_TREE/doc/html + +qch-docs.commands = cd \"$$QT_BUILD_TREE/doc\" && $$QHELPGENERATOR $$QT_BUILD_TREE/tools/qdoc3/doc/html/qdoc.qhp -o $$QT_BUILD_TREE/tools/qdoc3/doc/qch/qdoc.qch +qch-docs.files = $$QT_BUILD_TREE/tools/qdoc3/doc/qch +qch-docs.path = $$[QT_INSTALL_DOCS] +qch-docs.CONFIG += no_check_exist directory -QMAKE_EXTRA_TARGETS += html-docs +QMAKE_EXTRA_TARGETS += html-docs qch-docs target.path = $$[QT_INSTALL_BINS] -INSTALLS += target +INSTALLS += target qch-docs -- cgit v0.12 From b2d8291a63fdb2c73247fb44bec3cf55c647e993 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 17 Feb 2011 19:45:15 +0100 Subject: Doc: Removed non-ASCII (and non-UTF8 encoded) characters. --- doc/src/getting-started/installation.qdoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/src/getting-started/installation.qdoc b/doc/src/getting-started/installation.qdoc index 4e646e1..5dfea21 100644 --- a/doc/src/getting-started/installation.qdoc +++ b/doc/src/getting-started/installation.qdoc @@ -1189,7 +1189,7 @@ We hope you will enjoy using Qt. \list \o Development environment: \list - \o Microsoft Visual Studio 2005 (Standard Edition) or higher + \o Microsoft Visual Studio 2005 (Standard Edition) or higher \o ActivePerl \endlist \o Footprint @@ -1204,8 +1204,8 @@ We hope you will enjoy using Qt. \endlist \o Hardware Platform \list - \o Supported on ARM, x86 - \o (Compiles on SH4 and MIPS) + \o Supported on ARM, x86 + \o (Compiles on SH4 and MIPS) \endlist \endlist -- cgit v0.12 From c29e44e1b41ba0a3553f6848afc276f892cefa8a Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 17 Feb 2011 19:46:09 +0100 Subject: Doc: Fixed whitespace and title order. --- doc/src/platforms/supported-platforms.qdoc | 1120 ++++++++++++++-------------- 1 file changed, 558 insertions(+), 562 deletions(-) diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc index da9a32e..f071845 100644 --- a/doc/src/platforms/supported-platforms.qdoc +++ b/doc/src/platforms/supported-platforms.qdoc @@ -30,336 +30,334 @@ \title Support for Windows \brief Platform support for Windows. \ingroup platform-specific - \ingroup platform-details - - \section2 Qt on Windows - - Qt is a comprehensive application and UI framework for developing Windows - applications that can also be deployed across many other desktop and - embedded operating systems without rewriting the source code. Use the - code from one single code-base and rebuild for all - \l{Supported Platforms}{supported Windows versions and other platforms}. - - \section1 Getting Started on Windows - - \list - \o \l{Supported Platforms}{Supported Windows platforms} - Qt - supports a wide range of Windows platforms. - \o \l{Qt for Windows Requirements}{Qt for Windows Requirements} - - Requirements for developing with Qt on Windows. - \o \l{Installing Qt for Windows}{Installing Qt for Windows} - - Build Qt for Windows development. - \o \l{Platform and Compiler Notes - Windows}{Platform and Compiler Notes - Windows} - - Windows platform specific notes. + \ingroup platform-details + + \section1 Qt on Windows + + Qt is a comprehensive application and UI framework for developing Windows + applications that can also be deployed across many other desktop and + embedded operating systems without rewriting the source code. Use the + code from one single code-base and rebuild for all + \l{Supported Platforms}{supported Windows versions and other platforms}. + + \section1 Getting Started on Windows + + \list + \o \l{Supported Platforms}{Supported Windows platforms} - Qt + supports a wide range of Windows platforms. + \o \l{Qt for Windows Requirements}{Qt for Windows Requirements} + - Requirements for developing with Qt on Windows. + \o \l{Installing Qt for Windows}{Installing Qt for Windows} + - Build Qt for Windows development. + \o \l{Platform and Compiler Notes - Windows}{Platform and Compiler Notes - Windows} + - Windows platform specific notes. \o \l{Getting Started Guides}{Getting started} - Getting started developing for Windows - \endlist - - \section1 Key Features for Windows Development - - \section2 Rich Class Library - - The Qt class library includes all the functionality needed to build - advanced GUI applications. - - \list - \o Complete set of customizable \l{UI Design with Qt}{UI - controls/widgets} - \o 3D graphics support with \l{QtOpenGL Module}{OpenGL} - or Direct3D - \o Powerful \l{Thread Support in Qt}{multi-threading} features - \o \l{Graphics View Framework}{2D graphics canvas} capable of - handling millions of items - \o Integrated \l{Phonon multimedia framework}{Phonon multimedia - framework} - \o \l{WebKit in Qt}{WebKit} integration - \o \l{Network programming with Qt}{Networking}, \l{QtXml Module} - {XML} and \l{SQL in Qt}{database} functionality - \o \l{ECMAScript Reference}{ECMA standard} scripting engine - \endlist - - \section2 Integrated Development Tools - - Qt includes a set of integrated development tools to speed - development on the Windows platform. - - \list - \o \l{Qt Designer Manual}{Qt Designer} provides a drag and drop - visual GUI builder. - \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization - and translation features. - \o \l{Qt Assistant Manual}{Qt Assistant} is a customizable HTML help - file reader providing the complete Qt documentation offline. - \endlist - - \section2 Cross-platform development using Qt Creator - - \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is - a complete Cross-platform IDE included in the Qt SDK. The IDE allows - programmers to create, build, debug and run Qt applications accross all - supported platforms. - - \section2 Visual Studio Add-in. - - The Qt Visual Studio Add-in allows programmers to create, build, debug - and run Qt applications from within Microsoft Visual Studio 2005, 2008 - and 2010. The add-in contains project wizards, Qt project import/export - support, integrated Qt resource manager and automated build setup for - the Qt Meta-Object Compiler, User Interface Compiler, and Resource - Compiler. - - Additional \l{Cross-Platform and Platform-Specific Development - }{Cross-Platform and Platform-Specific Development} information. - - + \endlist + + \section1 Key Features for Windows Development + + \section2 Rich Class Library + + The Qt class library includes all the functionality needed to build + advanced GUI applications. + + \list + \o Complete set of customizable \l{UI Design with Qt}{UI + controls/widgets} + \o 3D graphics support with \l{QtOpenGL Module}{OpenGL} + or Direct3D + \o Powerful \l{Thread Support in Qt}{multi-threading} features + \o \l{Graphics View Framework}{2D graphics canvas} capable of + handling millions of items + \o Integrated \l{Phonon multimedia framework}{Phonon multimedia + framework} + \o \l{WebKit in Qt}{WebKit} integration + \o \l{Network programming with Qt}{Networking}, \l{QtXml Module} + {XML} and \l{SQL in Qt}{database} functionality + \o \l{ECMAScript Reference}{ECMA standard} scripting engine + \endlist + + \section2 Integrated Development Tools + + Qt includes a set of integrated development tools to speed + development on the Windows platform. + + \list + \o \l{Qt Designer Manual}{Qt Designer} provides a drag and drop + visual GUI builder. + \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization + and translation features. + \o \l{Qt Assistant Manual}{Qt Assistant} is a customizable HTML help + file reader providing the complete Qt documentation offline. + \endlist + + \section2 Cross-platform development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + + \section2 Visual Studio Add-in. + + The Qt Visual Studio Add-in allows programmers to create, build, debug + and run Qt applications from within Microsoft Visual Studio 2005, 2008 + and 2010. The add-in contains project wizards, Qt project import/export + support, integrated Qt resource manager and automated build setup for + the Qt Meta-Object Compiler, User Interface Compiler, and Resource + Compiler. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. */ /*! \page linuxX11-support.html - \title Support for Linux/X11 + \title Support for Linux/X11 \brief Platform support for Linux/X11. \ingroup platform-specific - \ingroup platform-details - - \section2 Qt on Linux/X11 - - Qt is a comprehensive application and UI framework for developing - Linux/X11 applications that can also be deployed across many other - desktop and embedded operating systems without rewriting the source code. - Use the code from one single code-base and rebuild for all - \l{Supported Platforms}{supported X11 versions and other platforms}. - - \section1 Getting Started on Linux/X11 - - \list - \o \l{Supported Platforms}{Supported Linux/X11 platforms} - Qt - supports a wide range of Linux/X11 platforms. - \o \l{Qt for X11 Requirements}{Qt for X11 Requirements} - - Software required to run Qt on Linux/X11. - \o \l{Installing Qt for X11 Platforms}{Installing Qt for X11 Platforms} - - Build Qt for Linux/X11 development. - \o \l{Platform and Compiler Notes - X11}{Platform and Compiler Notes - X11} - - Platform specific notes. + \ingroup platform-details + + \section1 Qt on Linux/X11 + + Qt is a comprehensive application and UI framework for developing + Linux/X11 applications that can also be deployed across many other + desktop and embedded operating systems without rewriting the source code. + Use the code from one single code-base and rebuild for all + \l{Supported Platforms}{supported X11 versions and other platforms}. + + \section1 Getting Started on Linux/X11 + + \list + \o \l{Supported Platforms}{Supported Linux/X11 platforms} - Qt + supports a wide range of Linux/X11 platforms. + \o \l{Qt for X11 Requirements}{Qt for X11 Requirements} + - Software required to run Qt on Linux/X11. + \o \l{Installing Qt for X11 Platforms}{Installing Qt for X11 Platforms} + - Build Qt for Linux/X11 development. + \o \l{Platform and Compiler Notes - X11}{Platform and Compiler Notes - X11} + - Platform specific notes. \o \l{Getting Started Guides}{Getting started} - \endlist - - \section1 Key Features for Linux/X11 Development - - \section2 Integrated Development Tools - - Qt includes a set of integrated development tools to speed development - on X11 platforms. - - \list - \o \l{Qt Designer Manual}{Qt Designer} provides a drag and drop - visual GUI builder. - \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization - and translation features. - \o \l{Qt Assistant Manual}{Qt Assistant} is a customizable HTML help - file reader providing the complete Qt documentation offline. - \o Integration with - \l{http://doc.qt.nokia.com/qt-eclipse-1.6/index.html}{Eclipse} - and KDevelop IDEs are also available. - \endlist - - \section2 Cross-platform development using Qt Creator - - \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is - a complete Cross-platform IDE included in the Qt SDK. The IDE allows - programmers to create, build, debug and run Qt applications accross all - supported platforms. - - \section2 Rich Class Library - - The Qt class library includes all the functionality needed to build - advanced GUI applications. - - \list - \o Complete set of customizable \l{UI Design with Qt}{UI - controls/widgets} - \o 3D graphics support with \l{QtOpenGL Module}{OpenGL - integration} - \o Powerful \l{Thread Support in Qt}{multi-threading} features - \o \l{Graphics View Framework}{2D graphics canvas} capable of - handling millions of items - \o Integrated \l{Phonon multimedia framework}{Phonon multimedia - framework} - \o \l{WebKit in Qt}{WebKit} integration - \o \l{Network programming with Qt}{Networking}, \l{QtXml Module} - {XML} and \l{SQL in Qt}{database} functionality - \o \l{ECMAScript Reference}{ECMA standard} scripting engine - \endlist - - \section2 Qt is the Foundation of KDE - - Qt is best known in the Linux community as the basis for the KDE - desktop environment. Almost everything in KDE is based on Qt, and - Qt forms the foundation for thousands of open source KDE applications - developed by community members worldwide. - - Additional \l{Cross-Platform and Platform-Specific Development - }{Cross-Platform and Platform-Specific Development} information. + \endlist + + \section1 Key Features for Linux/X11 Development + + \section2 Integrated Development Tools + + Qt includes a set of integrated development tools to speed development + on X11 platforms. + + \list + \o \l{Qt Designer Manual}{Qt Designer} provides a drag and drop + visual GUI builder. + \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization + and translation features. + \o \l{Qt Assistant Manual}{Qt Assistant} is a customizable HTML help + file reader providing the complete Qt documentation offline. + \o Integration with + \l{http://doc.qt.nokia.com/qt-eclipse-1.6/index.html}{Eclipse} + and KDevelop IDEs are also available. + \endlist + + \section2 Cross-platform development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + + \section2 Rich Class Library + + The Qt class library includes all the functionality needed to build + advanced GUI applications. + + \list + \o Complete set of customizable \l{UI Design with Qt}{UI + controls/widgets} + \o 3D graphics support with \l{QtOpenGL Module}{OpenGL + integration} + \o Powerful \l{Thread Support in Qt}{multi-threading} features + \o \l{Graphics View Framework}{2D graphics canvas} capable of + handling millions of items + \o Integrated \l{Phonon multimedia framework}{Phonon multimedia + framework} + \o \l{WebKit in Qt}{WebKit} integration + \o \l{Network programming with Qt}{Networking}, \l{QtXml Module} + {XML} and \l{SQL in Qt}{database} functionality + \o \l{ECMAScript Reference}{ECMA standard} scripting engine + \endlist + + \section2 Qt is the Foundation of KDE + + Qt is best known in the Linux community as the basis for the KDE + desktop environment. Almost everything in KDE is based on Qt, and + Qt forms the foundation for thousands of open source KDE applications + developed by community members worldwide. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. */ /*! \page mac-support.html - \title Support for Mac - \brief Platform support for Mac. + \title Support for Mac OS X + \brief Platform support for Mac OS X. \ingroup platform-specific - \ingroup platform-details - - \section2 Qt on Mac - - Qt is a comprehensive application and UI framework for developing Mac - applications that can also be deployed across many other desktop and - embedded operating systems without rewriting the source code. Use the - code from one single code-base and rebuild for all - \l{Supported Platforms}{supported Windows versions and other platforms}. - - \section1 Getting Started on Mac - - \list - \o \l{Supported Platforms}{Supported Mac OS X platforms} - Qt supports - a wide range of Mac platform variants. - \o \l{Qt for Mac OS X Requirements}{Qt for Mac OS X Requirements} - - Software required to run Qt on Mac OS X. - \o \l{Installing Qt for X11 Platforms}{Installing Qt for X11 Platforms} - - Build Qt for Mac OS X development. - \o \l{Platform and Compiler Notes - Mac OS X}{Platform and Compiler Notes - Mac OS X} - - Platform specific notes. + \ingroup platform-details + + \section1 Qt on Mac OS X + + Qt is a comprehensive application and UI framework for developing Mac + applications that can also be deployed across many other desktop and + embedded operating systems without rewriting the source code. Use the + code from one single code-base and rebuild for all + \l{Supported Platforms}{supported Windows versions and other platforms}. + + \section1 Getting Started on Mac + + \list + \o \l{Supported Platforms}{Supported Mac OS X platforms} - Qt supports + a wide range of Mac platform variants. + \o \l{Qt for Mac OS X Requirements}{Qt for Mac OS X Requirements} + - Software required to run Qt on Mac OS X. + \o \l{Installing Qt for X11 Platforms}{Installing Qt for X11 Platforms} + - Build Qt for Mac OS X development. + \o \l{Platform and Compiler Notes - Mac OS X}{Platform and Compiler Notes - Mac OS X} + - Platform specific notes. \o \l{Getting Started Guides}{Getting started} - \endlist - - \section1 Key Features for Mac OS X Development - - \section2 Integrated Development Tools - - Qt includes a set of integrated development tools to speed development - on the Mac platform. - - \list - \o \l{Qt Designer Manual}{Qt Designer} provides a drag and drop - visual GUI builder. - \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization - and translation features. - \o \l{Qt Assistant Manual}{Qt Assistant} is a customizable HTML help - file reader providing the complete Qt documentation offline. - \endlist - - \section2 Cross-platform development using Qt Creator - - \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is - a complete Cross-platform IDE included in the Qt SDK. The IDE allows - programmers to create, build, debug and run Qt applications accross all - supported platforms. - - \section2 Rich Class Library - - The Qt class library includes all the functionality needed to build - advanced GUI applications. - - \list - \o Complete set of customizable \l{UI Design with Qt}{UI - controls/widgets} - \o 3D graphics support with \l{QtOpenGL Module}{OpenGL - integration} - \o Powerful \l{Thread Support in Qt}{multi-threading} features - \o \l{Graphics View Framework}{2D graphics canvas} capable of - handling millions of items - \o Integrated \l{Phonon multimedia framework}{Phonon multimedia - framework} - \o \l{WebKit in Qt}{WebKit} integration - \o \l{Network programming with Qt}{Networking}, \l{QtXml Module} - {XML} and \l{SQL in Qt}{database} functionality - \o \l{ECMAScript Reference}{ECMA standard} scripting engine - \endlist - - \section3 Supports Intel Hardware and Universal Binaries - - Qt is written without making assumptions about the number representation, - endianness or architecture of the underlying processor. To support Intel - hardware on the Apple platforms, Qt customers simply need to recompile - their apps. - - Additional \l{Cross-Platform and Platform-Specific Development - }{Cross-Platform and Platform-Specific Development} information. - - \note Qt also provides support for 64-bit applications on top of Cocoa APIs. + \endlist + + \section1 Key Features for Mac OS X Development + + \section2 Integrated Development Tools + + Qt includes a set of integrated development tools to speed development + on the Mac platform. + + \list + \o \l{Qt Designer Manual}{Qt Designer} provides a drag and drop + visual GUI builder. + \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization + and translation features. + \o \l{Qt Assistant Manual}{Qt Assistant} is a customizable HTML help + file reader providing the complete Qt documentation offline. + \endlist + + \section2 Cross-platform development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + + \section2 Rich Class Library + + The Qt class library includes all the functionality needed to build + advanced GUI applications. + + \list + \o Complete set of customizable \l{UI Design with Qt}{UI + controls/widgets} + \o 3D graphics support with \l{QtOpenGL Module}{OpenGL + integration} + \o Powerful \l{Thread Support in Qt}{multi-threading} features + \o \l{Graphics View Framework}{2D graphics canvas} capable of + handling millions of items + \o Integrated \l{Phonon multimedia framework}{Phonon multimedia + framework} + \o \l{WebKit in Qt}{WebKit} integration + \o \l{Network programming with Qt}{Networking}, \l{QtXml Module} + {XML} and \l{SQL in Qt}{database} functionality + \o \l{ECMAScript Reference}{ECMA standard} scripting engine + \endlist + + \section3 Supports Intel Hardware and Universal Binaries + + Qt is written without making assumptions about the number representation, + endianness or architecture of the underlying processor. To support Intel + hardware on the Apple platforms, Qt customers simply need to recompile + their apps. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. + + \note Qt also provides support for 64-bit applications on top of Cocoa APIs. */ /*! \page windowsCE-Mobile-support.html \title Support for Windows CE and Windows Mobile \brief Platform support for Windows CE and Windows Mobile. \ingroup platform-specific - \ingroup platform-details - - \section2 Qt on Windows CE and Windows Mobile - - Qt is a C++ application and UI framework. You can use Qt to write - rich and high performance applications using an intuitive API - available for a wide range of devices. Use the code from one single - code-base and rebuild for all \l{Supported Platforms}{supported - Windows CE/Mobile versions as well as other other platforms}. - - Supporting most existing Windows CE configurations and with minimal - hardware dependencies, Qt is easy to build even for custom hardware - configurations. Unused components and features can even be compiled out. - - \section1 Getting Started on Windows CE/Mobile - - \list - \o \l{Supported Platforms}{Supported Windows CE/Mobile platforms} - - Qt supports a wide range of Windows CE/Mobile platform variants. - \o \l{Qt for Windows CE Requirements}{Qt for Windows CE/Mobile - Requirements} - Software required to run Qt on Windows CE/Mobile. - \o \l{Installing Qt for Windows CE Platforms}{Installing Qt for - Windows CE/Mobile Platforms} - Build Qt for Windows CE/Mobile - development. - \o \l{Platform and Compiler Notes - Windows CE}{Platform and - Compiler Notes - Windows CE/Mobile} - Platform specific notes. + \ingroup platform-details + + \section1 Qt on Windows CE and Windows Mobile + + Qt is a C++ application and UI framework. You can use Qt to write + rich and high performance applications using an intuitive API + available for a wide range of devices. Use the code from one single + code-base and rebuild for all \l{Supported Platforms}{supported + Windows CE/Mobile versions as well as other other platforms}. + + Supporting most existing Windows CE configurations and with minimal + hardware dependencies, Qt is easy to build even for custom hardware + configurations. Unused components and features can even be compiled out. + + \section1 Getting Started on Windows CE/Mobile + + \list + \o \l{Supported Platforms}{Supported Windows CE/Mobile platforms} + - Qt supports a wide range of Windows CE/Mobile platform variants. + \o \l{Qt for Windows CE Requirements}{Qt for Windows CE/Mobile + Requirements} - Software required to run Qt on Windows CE/Mobile. + \o \l{Installing Qt for Windows CE}{Installing Qt for + Windows CE/Mobile Platforms} - Build Qt for Windows CE/Mobile + development. + \o \l{Platform and Compiler Notes - Windows CE}{Platform and + Compiler Notes - Windows CE/Mobile} - Platform specific notes. \o \l{Getting Started Guides}{Getting started} - \endlist - - \section1 Key Features for Windows CE/Mobile Development - - On top of all the tools and API and class libraries that Qt offers, - Qt for Windows CE provides you with added functionality for an - optimized embedded development environment. - - \section2 Native and Customizable Look and Feel - - Windows Mobile and Windows CE styles are available with Qt. At runtime, - Qt applications will detect which style to use. The look and feel of - your applications can also be easily customized in a fraction of - the time and lines of code required for traditional UI styling with - Qt Style Sheets. - - \section2 Advanced Text Layout Engine - - Qt for Windows CE supports TrueType and raster fonts. Qt also has - extended Unicode support and right-to-left languages. Qts rich text - engine adds capabilities for complex text layouts including tables, - path tracing and text which flows around shapes. - - \section2 Qt for Windows CE/Mobile also provide support for: - - \list - \o Graphics Acceleration using \l{Qt for Windows CE and OpenGL - ES}{OpenGL ES} - \o \l{Graphics View Framework}{2D graphics canvas} capable of - handling millions of items. - \o \l{Qt Designer Manual}{Qt Designer} for GUI layout and - forms builder. - \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization - and translation features. - \endlist - - Applications created with Qt for Windows CE/Mobile can be ported to - Symbian, Maemo and any other OS that Qt supports. - - Additional \l{Cross-Platform and Platform-Specific Development - }{Cross-Platform and Platform-Specific Development} information. - + \endlist + + \section1 Key Features for Windows CE/Mobile Development + + On top of all the tools and API and class libraries that Qt offers, + Qt for Windows CE provides you with added functionality for an + optimized embedded development environment. + + \section2 Native and Customizable Look and Feel + + Windows Mobile and Windows CE styles are available with Qt. At runtime, + Qt applications will detect which style to use. The look and feel of + your applications can also be easily customized in a fraction of + the time and lines of code required for traditional UI styling with + Qt Style Sheets. + + \section2 Advanced Text Layout Engine + + Qt for Windows CE supports TrueType and raster fonts. Qt also has + extended Unicode support and right-to-left languages. Qts rich text + engine adds capabilities for complex text layouts including tables, + path tracing and text which flows around shapes. + + \section2 Qt for Windows CE/Mobile also provide support for: + + \list + \o Graphics Acceleration using \l{Qt for Windows CE and OpenGL + ES}{OpenGL ES} + \o \l{Graphics View Framework}{2D graphics canvas} capable of + handling millions of items. + \o \l{Qt Designer Manual}{Qt Designer} for GUI layout and + forms builder. + \o \l{Qt Linguist Manual}{Qt Linguist} provides internationalization + and translation features. + \endlist + + Applications created with Qt for Windows CE/Mobile can be ported to + Symbian, Maemo and any other OS that Qt supports. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. + */ /*! @@ -367,279 +365,277 @@ \title Support for Embedded Linux \brief Platform support for Embedded Linux. \ingroup platform-specific - \ingroup platform-details - - \section2 Qt on Embedded Linux - - Qt is the leading application and UI framework for devices powered - by embedded Linux. You can use Qt to create highly memory efficient - devices and applications that have completely unique user experiences. - - Qt runs anywhere Linux runs. Qts intuitive API means fewer lines of - code and higher level functionality in less time. Use the code from - one single code-base and rebuild for all \l{Supported Platforms} - {supported platforms}. - - \section1 Getting Started on Embedded Linux - - \list - \o \l{Supported Platforms}{Supported Linux platforms} - - Qt supports a wide range of Linux platform variants. - \o \l{Qt for Embedded Linux Requirements}{Qt for Embedded Linux - Requirements} - Software required to run Qt on Embedded Linux. - \o \l{Installing Qt for Embedded Linux}{Installing Qt for Embedded - Linux} - Build Qt for development on Embedded Linux. - \o \l{Platform and Compiler Notes - Embedded Linux}{Platform and - Compiler Notes - Embedded Linux} - Platform specific notes. + \ingroup platform-details + + \section1 Qt on Embedded Linux + + Qt is the leading application and UI framework for devices powered + by embedded Linux. You can use Qt to create highly memory efficient + devices and applications that have completely unique user experiences. + + Qt runs anywhere Linux runs. Qts intuitive API means fewer lines of + code and higher level functionality in less time. Use the code from + one single code-base and rebuild for all \l{Supported Platforms} + {supported platforms}. + + \section1 Getting Started on Embedded Linux + + \list + \o \l{Supported Platforms}{Supported Linux platforms} + - Qt supports a wide range of Linux platform variants. + \o \l{Qt for Embedded Linux Requirements}{Qt for Embedded Linux + Requirements} - Software required to run Qt on Embedded Linux. + \o \l{Installing Qt for Embedded Linux}{Installing Qt for Embedded + Linux} - Build Qt for development on Embedded Linux. + \o \l{Platform and Compiler Notes - Embedded Linux}{Platform and + Compiler Notes - Embedded Linux} - Platform specific notes. \o \l{Getting Started Guides}{Getting started} - \endlist - - \section1 Key Features for Embedded Linux Development - - On top of all the tools and API and class libraries that Qt offers, - such as WebKit, Qt for Embedded Linux provides you with key components - for an optimized embedded development environment. - - \section2 Compact and Efficient Windowing System \l{Qt for Embedded Linux Classes}{QWS} - - Qt builds on the standard API for embedded Linux devices with its own - compact window system. Qt-based applications write directly to the - Linux framebuffer, eliminating the need for the X11 windowing system. - - \section2 Virtual Frame Buffer (QVFb) - - Qt for Embedded Linux provides a \l{The Virtual Framebuffer}{virtual - frame buffer} that will match the physical device display, pixel for - pixel. This gives the developer a realistic testing infrastructure - testing on the desktop where the frame buffer simulates the physical - device displays width, height and color depth. - - \section2 Inter-Process Communication (IPC) - - IPC allows for creation of rich multi-application user experiences. - Two main concepts define inter-process communication: channels and - messages. - - \section2 Extended Font Format - - Qt supports a wide range of font formats on embedded Linux including: - TrueType, Postscript Type1 and Qt pre-rendered fonts. Qt has - extended Unicode support including automatic data extraction at build - time and automatic update at runtime. - - Plug-ins for custom font formats are also available allowing new font - engines to be easily added at runtime. Font sharing capabilities - between applications allow for increased memory efficiency. - - Applications created with Qt for Embedded Linux can be ported to - Windows CE and any other OS that Qt supports. - - Additional \l{Cross-Platform and Platform-Specific Development - }{Cross-Platform and Platform-Specific Development} information. - + \endlist + + \section1 Key Features for Embedded Linux Development + + On top of all the tools and API and class libraries that Qt offers, + such as WebKit, Qt for Embedded Linux provides you with key components + for an optimized embedded development environment. + + \section2 Compact and Efficient Windowing System \l{Qt for Embedded Linux Classes}{QWS} + + Qt builds on the standard API for embedded Linux devices with its own + compact window system. Qt-based applications write directly to the + Linux framebuffer, eliminating the need for the X11 windowing system. + + \section2 Virtual Frame Buffer (QVFb) + + Qt for Embedded Linux provides a \l{The Virtual Framebuffer}{virtual + frame buffer} that will match the physical device display, pixel for + pixel. This gives the developer a realistic testing infrastructure + testing on the desktop where the frame buffer simulates the physical + device displays width, height and color depth. + + \section2 Inter-Process Communication (IPC) + + IPC allows for creation of rich multi-application user experiences. + Two main concepts define inter-process communication: channels and + messages. + + \section2 Extended Font Format + + Qt supports a wide range of font formats on embedded Linux including: + TrueType, Postscript Type1 and Qt pre-rendered fonts. Qt has + extended Unicode support including automatic data extraction at build + time and automatic update at runtime. + + Plug-ins for custom font formats are also available allowing new font + engines to be easily added at runtime. Font sharing capabilities + between applications allow for increased memory efficiency. + + Applications created with Qt for Embedded Linux can be ported to + Windows CE and any other OS that Qt supports. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. + */ /*! \page symbian-support.html \title Support for Symbian \brief Platform support for Symbian. \ingroup platform-specific - \ingroup platform-details - - \section2 Qt on Symbian - - Qt provides support for the Symbian platform with integration - to the S60 framework. If you are developing apps for the Symbian, - Maemo or MeeGo platforms in most cases, you can use Qt under the - free LGPL licensing option. Qt is cross-platform, and that means - that you can use the code from one single code-base and rebuild - for all \l{Supported Platforms}{supported platforms}. - - \section1 Getting Started on Symbian - - \list - \o \l{Supported Platforms}{Supported platform} - - Details on the Qt support for Symbian. - \o \l{Qt for the Symbian platform Requirements}{Qt for the - Symbian platform Requirements} - Software required to run Qt - on Symbian. - \o \l{Installing Qt for the Symbian platform}{Installing Qt - for the Symbian platform} - Build Qt for Symbian development. - \o \l{Platform Notes - Symbian}{Platform Notes - Symbian} - - Platform specific notes. + \ingroup platform-details + + \section1 Qt on Symbian + + Qt provides support for the Symbian platform with integration + to the S60 framework. If you are developing apps for the Symbian, + Maemo or MeeGo platforms in most cases, you can use Qt under the + free LGPL licensing option. Qt is cross-platform, and that means + that you can use the code from one single code-base and rebuild + for all \l{Supported Platforms}{supported platforms}. + + \section1 Getting Started on Symbian + + \list + \o \l{Supported Platforms}{Supported platform} + - Details on the Qt support for Symbian. + \o \l{Qt for the Symbian platform Requirements}{Qt for the + Symbian platform Requirements} - Software required to run Qt + on Symbian. + \o \l{Installing Qt for the Symbian platform}{Installing Qt + for the Symbian platform} - Build Qt for Symbian development. + \o \l{Platform and Compiler Notes - Symbian}{Platform Notes - Symbian} + - Platform specific notes. \o \l{Getting Started Guides}{Getting started} - \endlist - - \section1 Key Features for Symbian Development - - On top of all the tools and the API and class libraries that Qt - offers, Qt provides you with added functionality for an optimized - Symbian development experience. - - \section2 Native Look and Feel - - Qt will detect which theme the phone is running and applies the - style at runtime to your Qt application. The look and feel of your - applications can also be easily customized in a fraction of the - time and lines of code required for traditional UI styling with - Qt Style Sheets. - - \section2 Graphics Features - - Qt for Symbian contains a powerful paint engine that provides - features such as anti, aliasing, gradients, curves and transparency. - It also has animation support with timelines and easing curves. It - is already targeting future device technology by supporting hardware - acceleration using OpenVG. - - \section2 Device Configurations - - Using Qt for Symbian all supported Symbian devices provides automatic - support for swiching between landscape and portrait mode, different - screen resolutions as well as touch screen and key pad input. - - \section2 Cross-platform development using Qt Creator - - \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is - a complete Cross-platform IDE included in the Qt SDK. The IDE allows - programmers to create, build, debug and run Qt applications accross all - supported platforms. - + \endlist + + \section1 Key Features for Symbian Development + + On top of all the tools and the API and class libraries that Qt + offers, Qt provides you with added functionality for an optimized + Symbian development experience. + + \section2 Native Look and Feel + + Qt will detect which theme the phone is running and applies the + style at runtime to your Qt application. The look and feel of your + applications can also be easily customized in a fraction of the + time and lines of code required for traditional UI styling with + Qt Style Sheets. + + \section2 Graphics Features + + Qt for Symbian contains a powerful paint engine that provides + features such as anti, aliasing, gradients, curves and transparency. + It also has animation support with timelines and easing curves. It + is already targeting future device technology by supporting hardware + acceleration using OpenVG. + + \section2 Device Configurations + + Using Qt for Symbian all supported Symbian devices provides automatic + support for swiching between landscape and portrait mode, different + screen resolutions as well as touch screen and key pad input. + + \section2 Cross-platform development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + \omit - - \section3 Licensing - - Qt for Symbian is available under the Qt Commercial License, the LGPL - v. 2.1 "LGPL") and the GPL v. 3.0. Symbian currently licenses their - software products under either the Symbian Foundation License or the - Eclipse Public License ("EPL"). While the LGPL and the EPL are not - compatible and may not be combined on a file-by-file basis, they may - be used in a common environment provided that the interaction between - Qt and Symbian is limited to: dynamic linking, inter-process - communication and data exchange. Therefore, most Symbian developers - can use Qt for Symbian under the LGPL. - + + \section3 Licensing + + Qt for Symbian is available under the Qt Commercial License, the LGPL + v. 2.1 "LGPL") and the GPL v. 3.0. Symbian currently licenses their + software products under either the Symbian Foundation License or the + Eclipse Public License ("EPL"). While the LGPL and the EPL are not + compatible and may not be combined on a file-by-file basis, they may + be used in a common environment provided that the interaction between + Qt and Symbian is limited to: dynamic linking, inter-process + communication and data exchange. Therefore, most Symbian developers + can use Qt for Symbian under the LGPL. + \endomit - Additional \l{Cross-Platform and Platform-Specific Development - }{Cross-Platform and Platform-Specific Development} information. + Additional \l{Cross-Platform and Platform-Specific Development} + information. */ /*! - \omit \page maemo-support.html \title Support for Maemo/MeeGo \brief Platform support for Maemo/MeeGo. \ingroup platform-specific - \ingroup platform-details - - \section2 Qt on Maemo/MeeGo - - Qt is a comprehensive application and UI framework for developing - Maemo and MeeGo applications that can also be deployed across major - device and desktop operating systems without rewriting the source code. - If you are developing apps for the Symbian, Mameo or MeeGo platforms - in most cases, you can use Qt under the free LGPL licensing option. - Qt is cross-platform, and that means that you can use the code from - one single code-base and rebuild for all \l{Supported Platforms} - {supported platforms}. - - \section1 Getting Started on Maemo/MeeGo - - \list - \o \l{Supported Platforms}{Supported Maemo/MeeGo platforms} - - Qt support for Maemo/MeeGo versions. - \o \l{Qt for Maemo Requirements}{Qt for Maemo/MeeGo - Requirements} - Software required to run Qt on Maemo/MeeGo. - \o \l{Installing Qt for Maemo}{Installing Qt for - Maemo/MeeGo} - Build Qt for Maemo/MeeGo development. - \o \l{Platform and Compiler Notes - Maemo}{Platform and - Compiler Notes - Maemo/MeeGo} - Platform specific notes. + \ingroup platform-details + + \section1 Qt on Maemo/MeeGo + + Qt is a comprehensive application and UI framework for developing + Maemo and MeeGo applications that can also be deployed across major + device and desktop operating systems without rewriting the source code. + If you are developing apps for the Symbian, Mameo or MeeGo platforms + in most cases, you can use Qt under the free LGPL licensing option. + Qt is cross-platform, and that means that you can use the code from + one single code-base and rebuild for all \l{Supported Platforms} + {supported platforms}. + + \section1 Getting Started on Maemo/MeeGo + + \list + \o \l{Supported Platforms}{Supported Maemo/MeeGo platforms} + - Qt support for Maemo/MeeGo versions. + \o \l{Qt for Maemo Requirements}{Qt for Maemo/MeeGo + Requirements} - Software required to run Qt on Maemo/MeeGo. + \o \l{Installing Qt for Maemo}{Installing Qt for + Maemo/MeeGo} - Build Qt for Maemo/MeeGo development. + \o \l{Platform and Compiler Notes - Maemo}{Platform and + Compiler Notes - Maemo/MeeGo} - Platform specific notes. \o \l{Getting Started Guides}{Getting started} - \endlist - - \section1 Key Features for Maemo/MeeGo Development - - \section2 Native Look and Feel - - Qt will detect which theme the device is running and applies the - style at runtime to your Qt application. Widgets are optimized - for touch screen usage. - - \section2 Graphics Features - - Qt for Maemo/MeeGo provides a powerful paint engine that cotain - features such as anti aliasing, gradients, curves and transparency. - It also has animation support with timelines and easing curves. Qt - for Maemo/MeeGo also supports hardware acceleration using ARM NEON - and OpenGL ES 2.0. - - \section2 Device Configurations - - Applications developed with Qt for Maemo/MeeGo will across all - supported Maemo/MeeGo devices provide automatic support for switching - between landscape and portrait mode. They will support input methods, - including predictive text input and on-screen keyboard. The - applications will also have support for one finger touch events and - gestures, and have configurable kinetic scrolling. - - \section2 Maemo - Linux/X11 - - Qt supports a wide range of X11 platform variants, such as: Solaris, - AIX, HP-UX, Maemo 5 and MeeGo. Qt for Maemo contains all Qt modules - and features the same functionality as the Qt on X11 version. - - \section2 Cross-platform development using Qt Creator - - \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is - a complete Cross-platform IDE included in the Qt SDK. The IDE allows - programmers to create, build, debug and run Qt applications accross all - supported platforms. - - Additional \l{Cross-Platform and Platform-Specific Development - }{Cross-Platform and Platform-Specific Development} information. - - \endomit - + \endlist + + \section1 Key Features for Maemo/MeeGo Development + + \section2 Native Look and Feel + + Qt will detect which theme the device is running and applies the + style at runtime to your Qt application. Widgets are optimized + for touch screen usage. + + \section2 Graphics Features + + Qt for Maemo/MeeGo provides a powerful paint engine that cotain + features such as anti aliasing, gradients, curves and transparency. + It also has animation support with timelines and easing curves. Qt + for Maemo/MeeGo also supports hardware acceleration using ARM NEON + and OpenGL ES 2.0. + + \section2 Device Configurations + + Applications developed with Qt for Maemo/MeeGo will across all + supported Maemo/MeeGo devices provide automatic support for switching + between landscape and portrait mode. They will support input methods, + including predictive text input and on-screen keyboard. The + applications will also have support for one finger touch events and + gestures, and have configurable kinetic scrolling. + + \section2 Maemo - Linux/X11 + + Qt supports a wide range of X11 platform variants, such as: Solaris, + AIX, HP-UX, Maemo 5 and MeeGo. Qt for Maemo contains all Qt modules + and features the same functionality as the Qt on X11 version. + + \section2 Cross-platform development using Qt Creator + + \l{http://doc.qt.nokia.com/qtcreator-snapshot/index.html}{Qt Creator} is + a complete Cross-platform IDE included in the Qt SDK. The IDE allows + programmers to create, build, debug and run Qt applications accross all + supported platforms. + + Additional \l{Cross-Platform and Platform-Specific Development} + information. + + \endomit */ - + /*! \page supported-platforms.html \title Supported Platforms \brief The platforms supported by Nokia for Qt. \ingroup platform-specific - \group platform-details - - Qt is a cross-platform application and UI framework. Using Qt, - you can write web-enabled applications once and deploy them - across desktop, mobile and embedded operating systems without - rewriting the source code. - - \section1 Qt is available for the following platforms: - - \table - \header - \o {2,1} Qt Cross Platform Support - \header - \o {1,1} Desktop - \o {1,1} Mobile/Embedded - \row - \o \l{Support for Windows}{Windows} - \o \l{Support for Windows CE and Windows Mobile.}{Windows CE and Windows Mobile.} - \row - \o \l{Support for Linux/X11}{Linux/X11} - \o \l{Support for Embedded Linux}{Embedded Linux} - \row - \o \l{Support for Mac}{Mac OS X} - \o \l{Support for Symbian}{Symbian} - \row - \o - \omit - \o\l{Support for Maemo/MeeGo}{Maemo/MeeGo} - \endomit - \endtable - - \section1 Supported platform details + \group platform-details + + Qt is a cross-platform application and UI framework. Using Qt, + you can write web-enabled applications once and deploy them + across desktop, mobile and embedded operating systems without + rewriting the source code. + + \section1 Qt is available for the following platforms: + + \table + \header + \o {2,1} Qt Cross Platform Support + \header + \o {1,1} Desktop + \o {1,1} Mobile/Embedded + \row + \o \l{Support for Windows}{Windows} + \o \l{Support for Windows CE and Windows Mobile.}{Windows CE and Windows Mobile.} + \row + \o \l{Support for Linux/X11}{Linux/X11} + \o \l{Support for Embedded Linux}{Embedded Linux} + \row + \o \l{Support for Mac}{Mac OS X} + \o \l{Support for Symbian}{Symbian} + \row + \o + \omit + \o\l{Support for Maemo/MeeGo}{Maemo/MeeGo} + \endomit + \endtable + + \section1 Supported platform details The Qt team strives to provide support for the platforms most frequently used by Qt users. We have designed our internal testing procedure to @@ -680,7 +676,7 @@ \o MSVC 2008 \row \o Microsoft Windows 7 \o MSVC 2008 - \row \o Apple Mac OS X 10.6 "Snow Leopard" + \row \o Apple Mac OS X 10.6 "Snow Leopard" \o As provided by Apple \row \o Apple Mac OS X 10.5 "Leopard" x86_64 (Cocoa 32 and 64bit) \o As provided by Apple @@ -695,9 +691,9 @@ \section1 Tier 2 Platforms Tier 2 platforms are subject to ad hoc and internal testing. However, Qt users - should note that errors may be present in released product versions for Tier 2 - platforms and, subject to resource availability, known errors in Tier 2 platforms - may or may not be corrected prior to new version releases. + should note that errors may be present in released product versions for Tier 2 + platforms and, subject to resource availability, known errors in Tier 2 platforms + may or may not be corrected prior to new version releases. \table \header \o Platform @@ -732,8 +728,8 @@ \o RVCT 2.2 [build 686 or later], WINSCW 3.2.5 [build 482 or later], GCCE (for applications) \endtable - \note The PPC architecture on Mac has been downgraded from tier 1 to tier 2 for 4.7. - + \note The PPC architecture on Mac has been downgraded from tier 1 to tier 2 for 4.7. + \section1 Tier 3 Platforms (Not supported by Nokia) All platforms not specifically listed above are not supported by Nokia. Nokia does @@ -757,7 +753,7 @@ warranties and conditions, either express or implied, including, but not limited to, implied warranties of merchantability, fitness for a particular purpose, title and non-infringement with regard to the Licensed Software. - + \section1 Planned Changes for Qt 4.8 The following changes to the list of supported platforms are at time of publishing -- cgit v0.12 From 3d41e0101c04625669dda6d1059b8dba53129a13 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 17 Feb 2011 19:46:46 +0100 Subject: Doc: Added a missing snippet. --- doc/src/snippets/declarative/grid/grid.qml | 53 ++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 doc/src/snippets/declarative/grid/grid.qml diff --git a/doc/src/snippets/declarative/grid/grid.qml b/doc/src/snippets/declarative/grid/grid.qml new file mode 100644 index 0000000..758edde --- /dev/null +++ b/doc/src/snippets/declarative/grid/grid.qml @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [document] +import QtQuick 1.0 + +Grid { + columns: 3 + spacing: 2 + Rectangle { color: "red"; width: 50; height: 50 } + Rectangle { color: "green"; width: 20; height: 50 } + Rectangle { color: "blue"; width: 50; height: 20 } + Rectangle { color: "cyan"; width: 50; height: 50 } + Rectangle { color: "magenta"; width: 10; height: 10 } +} +//! [document] -- cgit v0.12 From c164a5be25cb8bd70235571169b66af2fc6a8cbd Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 17 Feb 2011 21:37:06 +0100 Subject: Doc: Fixed links and whitespace. --- doc/src/declarative/animation.qdoc | 2 +- doc/src/declarative/basicelements.qdoc | 2 +- doc/src/declarative/basictypes.qdoc | 2 +- doc/src/declarative/dynamicobjects.qdoc | 12 ++++++------ doc/src/declarative/elements.qdoc | 4 ++-- doc/src/declarative/example-slideswitch.qdoc | 2 +- doc/src/declarative/extending-tutorial.qdoc | 6 +++--- doc/src/declarative/extending.qdoc | 5 +++-- doc/src/declarative/javascriptblocks.qdoc | 3 ++- doc/src/declarative/mouseevents.qdoc | 5 ++--- doc/src/declarative/propertybinding.qdoc | 25 ++++++++++++------------- doc/src/declarative/qdeclarativestates.qdoc | 2 +- doc/src/declarative/qmlevents.qdoc | 11 +++++------ doc/src/declarative/qmlreusablecomponents.qdoc | 6 +++--- doc/src/declarative/qmlviews.qdoc | 13 ++++++------- doc/src/declarative/qtquick-intro.qdoc | 2 +- doc/src/declarative/tutorial.qdoc | 2 +- 17 files changed, 51 insertions(+), 53 deletions(-) diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc index 7247e73..129fa34 100644 --- a/doc/src/declarative/animation.qdoc +++ b/doc/src/declarative/animation.qdoc @@ -155,7 +155,7 @@ sequence or in parallel. A banner component may have several icons or slogans to display, one after the other. The \c opacity property could transform to \c 1.0 denoting an opaque object. Using the \l{SequentialAnimation} element, the opacity animations will -play after the preceding animation finishes. The \l{ParallelAnimation} element +play after the preceding animation finishes. The \l{ParallelAnimation} element will play the animations at the same time. \snippet doc/src/snippets/declarative/animation.qml sequential animation diff --git a/doc/src/declarative/basicelements.qdoc b/doc/src/declarative/basicelements.qdoc index c0df307..0146591 100644 --- a/doc/src/declarative/basicelements.qdoc +++ b/doc/src/declarative/basicelements.qdoc @@ -51,7 +51,7 @@ This is a list of some of the elements readily available for users. \o \l {MouseArea} \endlist -For a complete list of QML elements, please visit the \l {QML Elements} page. +For a complete list of QML elements, please visit the \l {QML Elements} page. \section1 Properties and Qt Declarative Module diff --git a/doc/src/declarative/basictypes.qdoc b/doc/src/declarative/basictypes.qdoc index 453af08..1d9e28c 100644 --- a/doc/src/declarative/basictypes.qdoc +++ b/doc/src/declarative/basictypes.qdoc @@ -402,7 +402,7 @@ \c child1, \c child2 and \c child3 will be added to the children list in the order in which they appear. - List \l {Adding Properties}{properties} can be created as a + List \l {Property Binding}{properties} can be created as a \c variant type, or as a \c list type, where \c Type is the type of the object in the list: diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc index a8339e0..7c10760 100644 --- a/doc/src/declarative/dynamicobjects.qdoc +++ b/doc/src/declarative/dynamicobjects.qdoc @@ -59,7 +59,7 @@ creating an item from a string of QML is useful when the item QML itself is gene at runtime. -\section2 Creating a Component dynamically +\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}. @@ -112,11 +112,13 @@ Notice in both instances, \l {Component::createObject()}{createObject()} is call When using files with relative paths, the path should be relative to the file where \l {QML:Qt::createComponent()}{Qt.createComponent()} is executed. -To connect signals to (or receive signals from) dynamically created objects, use the signal -\c connect() method. See \l {Connecting signals to methods and other signals} for more information. +To connect signals to (or receive signals from) dynamically created objects, +use the signal \c connect() method. See +\l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} +{Connecting Signals to Methods and Signals} for more information. -\section2 Creating an object from a string of QML +\section2 Creating an Object from a String of QML If the QML is not defined until runtime, you can create a QML item from a string of QML using the \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()} function, as in the following example: @@ -208,6 +210,4 @@ can similarly be destroyed using \c destroy(): \snippet doc/src/snippets/declarative/createQmlObject.qml 0 \snippet doc/src/snippets/declarative/createQmlObject.qml destroy - */ - diff --git a/doc/src/declarative/elements.qdoc b/doc/src/declarative/elements.qdoc index c087f17..ff8e201 100644 --- a/doc/src/declarative/elements.qdoc +++ b/doc/src/declarative/elements.qdoc @@ -55,7 +55,7 @@ To see the QML elements listed by functional area, see the \o \l {BorderImage} - Allows the use of images as borders \o \l {AnimatedImage} - For playing animations stored in a series of frames \o \l {Gradient} - For defining a color gradient -\o \l {GradientStop} - Used to define a color within a \l {Gradient} +\o \l {GradientStop} - Used to define a color within a \l {Gradient} \o \l {SystemPalette} - Provides access to the Qt palettes \endlist @@ -75,7 +75,7 @@ To see the QML elements listed by functional area, see the \o \l {MouseArea} - Sets up an area for mouse interaction \o \l {Keys} - Provides components with attached properties to handle key input. \o \l {FocusScope} - Element that mediate keyboard focus changes -\o \l {Flickable} - Provides a surface that can be "flicked" +\o \l {Flickable} - Provides a surface that can be "flicked" \o \l {Flipable} - Provides a surface that produces "flipping" effects \o \l {GestureArea} - Enables simple gesture handling \endlist diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc index 54ee2c7..482a292 100644 --- a/doc/src/declarative/example-slideswitch.qdoc +++ b/doc/src/declarative/example-slideswitch.qdoc @@ -121,7 +121,7 @@ For more information on scripts see \l{Integrating JavaScript}. At this point, when the switch toggles between the two states the knob will instantly change its \c x position between 1 and 78. In order for the the knob to move smoothly we add a transition that will animate the \c x property with an easing curve for a duration of 200ms. -For more information on transitions see \l{qdeclarativeanimation.html#transitions}{QML Transitions}. +For more information on transitions see \l{QML Animation and Transitions}. \section1 Usage The switch can be used in a QML file, like this: diff --git a/doc/src/declarative/extending-tutorial.qdoc b/doc/src/declarative/extending-tutorial.qdoc index 09a8ad9..0ddc430 100644 --- a/doc/src/declarative/extending-tutorial.qdoc +++ b/doc/src/declarative/extending-tutorial.qdoc @@ -27,7 +27,7 @@ /*! \page qml-extending-tutorial-index.html -\title Tutorial: Writing QML extensions with C++ +\title Tutorial: Writing QML Extensions with C++ 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 @@ -45,7 +45,7 @@ Tutorial chapters: \list 1 \o \l{declarative/tutorials/extending/chapter1-basics}{Creating a New Type} \o \l{declarative/tutorials/extending/chapter2-methods}{Connecting to C++ Methods and Signals} -\o \l{declarative/tutorials/extending/chapter3-bindings}{Adding Property Bindings} +\o \l{declarative/tutorials/extending/chapter3-bindings}{Property Binding} \o \l{declarative/tutorials/extending/chapter4-customPropertyTypes}{Using Custom Property Types} \o \l{declarative/tutorials/extending/chapter5-listproperties}{Using List Property Types} \o \l{declarative/tutorials/extending/chapter6-plugins}{Writing an Extension Plugin} @@ -286,7 +286,7 @@ int-type property to store an identifier for each chart: \endcode We can also use various other property types. QML has built-in support for the types -listed in the \l{Adding Properties} documentation, which includes the following: +listed in the \l{QML Basic Types} documentation, which includes the following: \list \o bool, unsigned int, int, float, double, qreal diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc index 95f54ff..0f69bdb 100644 --- a/doc/src/declarative/extending.qdoc +++ b/doc/src/declarative/extending.qdoc @@ -86,7 +86,7 @@ Types can be registered by libraries, application code, or by plugins Once registered, all \l {Qt's Property System}{properties} of the supported types are available in QML. QML has intrinsic support for -properties of the types listed in the \l{Adding Properties} +properties of the types listed in the \l{QML Basic Types} document, which includes the following: \list @@ -481,7 +481,7 @@ but different parameters cannot be distinguished. Signal parameters become accessible by name to the assigned script. An unnamed parameter cannot be accessed, so care should be taken to name all the signal parameters in the C++ class declaration. The intrinsic types -listed in \l {Adding Types}, as well registered object types are permitted as +listed in \l{Adding Types}, as well registered object types are permitted as signal parameter types. Using other types is not an error, but the parameter value will not be accessible from script. @@ -705,3 +705,4 @@ public: } }; \endcode +*/ diff --git a/doc/src/declarative/javascriptblocks.qdoc b/doc/src/declarative/javascriptblocks.qdoc index 65877f9..7ef7f9a 100644 --- a/doc/src/declarative/javascriptblocks.qdoc +++ b/doc/src/declarative/javascriptblocks.qdoc @@ -224,7 +224,8 @@ in \c script.js: The \c jsFunction() will now be called whenever MouseArea's \c clicked signal is emitted. -See \l {Connecting signals to methods and other signals} for more information. +See \l{QML Signal and Handler Event System#Connecting Signals to Methods and Signals} +{Connecting Signals to Methods and Signals} for more information. \section1 QML JavaScript Restrictions diff --git a/doc/src/declarative/mouseevents.qdoc b/doc/src/declarative/mouseevents.qdoc index 533f64b..ade6760 100644 --- a/doc/src/declarative/mouseevents.qdoc +++ b/doc/src/declarative/mouseevents.qdoc @@ -64,9 +64,9 @@ definable. The MouseArea element provides \l{QML Signal and Handler Event System}{signals and handlers} to detect different mouse events. The \l MouseArea element documentation describes these -gestures in greater detail. +gestures in greater detail: -\list Mouse Gestures +\list \o canceled \o clicked \o doubleClicked @@ -117,5 +117,4 @@ such as double clicking. To facilitate the classification of mouse clicks, the MouseEvent object has an \c accepted property to disable the event propagation. 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/propertybinding.qdoc b/doc/src/declarative/propertybinding.qdoc index 22d14a8..afbbe4f 100644 --- a/doc/src/declarative/propertybinding.qdoc +++ b/doc/src/declarative/propertybinding.qdoc @@ -40,9 +40,8 @@ In QML, properties serve many purposes but their main function is to bind to values. Values may be a \l{QML Basic Types}{basic type}, or other QML elements. The syntax for properties is: -\qml - [default] property [: defaultValue] -\endqml + +\tt{[default] property [: defaultValue]} Elements already possess useful properties but, to create custom properties, precede the property name with the keyword \c property. @@ -58,6 +57,7 @@ property names must begin with a lowercase letter. names. \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 @@ -87,7 +87,7 @@ binding is created using the colon "\c {:}". The property binding causes the width of the \c Rectangle to update whenever the \c {parent}'s width changes. -Assigning a property value (using the equals sign "\c {=}") does not create a +Assigning a property value (using the equals sign "\c {=}") does not create a property binding. \snippet doc/src/snippets/declarative/properties.qml property assignment @@ -102,13 +102,15 @@ There is no way to create a property binding directly from imperative JavaScript although it is possible to use the \l {Using the Binding Element}{Binding} element. \section1 Types of Properties + Properties may bind to different types, but they are are \e type-safe. That is, properties only allow you to assign a value that matches the property type. For example, if a property is a real, and if you try to assign a string to it you will get an error. -\qml - property real volume: "four" //generates an error -\endqml + +\badcode +property real volume: "four" //generates an error +\endcode Certain properties bind to more complex types such as other elements and objects. @@ -150,7 +152,7 @@ The code snippet has a \l Gradient element that attempts to print its parent's \c width value. However, the \c Gradient element is bound to the \c gradient property, not the \c children property of the \c Rectangle. As a result, the \c Gradient does not have the \c Rectangle as its parent. Printing the value -of \c{parent.width} generates an error. Printing the \c Rectangle object's +of \c{parent.width} generates an error. Printing the \c Rectangle object's first child's \c name will print \c {childrectangle} because the second \c Rectangle is bound to the \c children property. @@ -224,9 +226,8 @@ the property, a property alias connects the newly declared property, called the in a read or write operations on the aliased property, respectively. A property alias declaration is similar to an ordinary property definition: -\code - [default] property alias : -\endcode + +\tt{[default] property alias : } As the aliasing property has the same type as the aliased property, an explicit type is omitted, and the special \c alias keyword is before the property name. @@ -319,6 +320,4 @@ The \l PropertyChanges element is for setting property bindings within a \snippet doc/src/snippets/declarative/properties.qml PropertyChanges element The rectangle's \c color property will bind to the \c warning component's \c color property when its \c state is set to the \c WARNING state. - */ - diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc index b1a97d7..655b647 100644 --- a/doc/src/declarative/qdeclarativestates.qdoc +++ b/doc/src/declarative/qdeclarativestates.qdoc @@ -123,7 +123,7 @@ The \c bell component will change to the \c RINGING state whenever the \section1 Animating State Changes -State changes induce abrupt value changes. The \l Transitions element allow +State changes induce abrupt value changes. The \l Transition element allow smoother changes during state changes. In transitions, animations and interpolation behaviors are definable. The \l {QML Animation and Transitions}{Animation and Transitions} article has more diff --git a/doc/src/declarative/qmlevents.qdoc b/doc/src/declarative/qmlevents.qdoc index 7dfb1f9..566f71c 100644 --- a/doc/src/declarative/qmlevents.qdoc +++ b/doc/src/declarative/qmlevents.qdoc @@ -47,9 +47,7 @@ has been clicked within the area. The syntax for defining a new signal is: -\qml -signal [([ [, ...]])] -\endqml +\tt{signal [([ [, ...]])]} Attempting to declare two signals or methods with the same name in the same type block generates 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.) @@ -119,10 +117,11 @@ output: Because QML uses Qt, a signal defined in C++ also works as a QML signal. The signal may be emitted in QML code or called as a method. In addition, the QML runtime automatically creates signal handlers for the C++ signals. For more -signal control, the \c connect() method and the \l Connect element may connect a -C++ to another signal or method. +signal control, the \c connect() method and the \l Connections element may connect +a C++ signal to another signal or method. -For complete information on how to call C++ functions in QML, read the \l {Extending QML - Signal Support Example}. +For complete information on how to call C++ functions in QML, read the +\l{Extending QML - Signal Support Example}. */ diff --git a/doc/src/declarative/qmlreusablecomponents.qdoc b/doc/src/declarative/qmlreusablecomponents.qdoc index e6c3ec9..ee360eb 100644 --- a/doc/src/declarative/qmlreusablecomponents.qdoc +++ b/doc/src/declarative/qmlreusablecomponents.qdoc @@ -29,7 +29,7 @@ \page qmlreusablecomponents.html \ingroup qml-features \previouspage {QML Signal and Handler Event System}{Signal and Handler Event System} -\nextpage {QML States}{States} +\nextpage {QML States}{States} \contentspage QML Features \title Importing Reusable Components @@ -89,7 +89,7 @@ however, be in an imported path. A consequence of inline components is that initialization may be deferred or delayed. A component may be created during a MouseArea event or by using a \l Loader element. The component can create an object, which is addressable in a -similar way as an \l {qml-id-propert}{id property}. Thus, the created object may +similar way as an \l {qml-id-property}{id property}. Thus, the created object may have its bindings set and read like a normal QML object. \snippet doc/src/snippets/declarative/reusablecomponents/component.qml define inline component \snippet doc/src/snippets/declarative/reusablecomponents/component.qml create inline component @@ -103,7 +103,7 @@ Specifically, there are \l{attached-properties}{attached properties} and \l{attached-signalhandlers}{attached signal handlers} for setting properties during the lifetime of a component. -The \c{Component.onCompleted} attached signal handler is called when the +The \c{Component.onCompleted} attached signal handler is called when the component completes initialization. It is useful for executing any commands after component initialization. Similarly, the \c{Component.onDestruction} signal handler executes when the component finishes destruction. diff --git a/doc/src/declarative/qmlviews.qdoc b/doc/src/declarative/qmlviews.qdoc index 8b2ca96..4071d5d 100644 --- a/doc/src/declarative/qmlviews.qdoc +++ b/doc/src/declarative/qmlviews.qdoc @@ -44,7 +44,7 @@ graphical elements: \o \l{ListView} arranges items in a horizontal or vertical list \o \l{GridView} arranges items in a grid within the available space \o \l{PathView} arranges items on a path -\o \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}. +\o \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}. \endlist Unlike other views, \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 @@ -103,12 +103,11 @@ the person belongs. \snippet doc/src/snippets/declarative/listview-sections.qml delegate The ListView element has the \c section -\l{qml-attached-properties}{attached property} that can combine adjacent -and related elements into a section. The section's \c property property is for -selecting which list element property to use as sections. The \c criteria -can dictate how the section names are displayed and the \c delegate is similar -to the views' \l {qml-view-delegate}{delegate} property. +\l{Property Binding#Attached Properties}{attached property} that can combine +adjacent and related elements into a section. The section's \c property +property is for selecting which list element property to use as sections. +The \c criteria can dictate how the section names are displayed and the +\c delegate is similar to the views' \l {qml-view-delegate}{delegate} property. \snippet doc/src/snippets/declarative/listview-sections.qml section \image listview-section.png - */ diff --git a/doc/src/declarative/qtquick-intro.qdoc b/doc/src/declarative/qtquick-intro.qdoc index 1bbae8f..02b2c44 100644 --- a/doc/src/declarative/qtquick-intro.qdoc +++ b/doc/src/declarative/qtquick-intro.qdoc @@ -109,7 +109,7 @@ system. \section1 Where to Go from Here -The \l {Qt Quick} page has links to various Qt Quick topics such as QML +The \l {Qt Quick} page has links to various Qt Quick topics such as QML features, addons, and tools. The \l {QML Examples and Demos} page has a gallery of QML applications. diff --git a/doc/src/declarative/tutorial.qdoc b/doc/src/declarative/tutorial.qdoc index 1ee5e61..dc08ba0 100644 --- a/doc/src/declarative/tutorial.qdoc +++ b/doc/src/declarative/tutorial.qdoc @@ -144,7 +144,7 @@ An \l Item is the most basic visual element in QML and is often used as a contai We declare a \c cellColor property. This property is accessible from \e outside our component, this allows us to instantiate the cells with different colors. -This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Adding Properties}). +This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Property Binding}). \snippet examples/declarative/tutorials/helloworld/Cell.qml 5 -- cgit v0.12 From e1b85d70420001f2be698d08e62b7e784a13a134 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Thu, 17 Feb 2011 21:38:27 +0100 Subject: Doc: Fixed links and whitespace. --- .../qmlbestpractices/qmlbestpractices-coding.qdoc | 4 ++-- doc/src/snippets/declarative/animation.qml | 5 ++--- doc/src/snippets/declarative/events.qml | 14 +++++++------- .../declarative/mousearea/mousearea-snippet.qml | 10 +++++----- src/declarative/graphicsitems/qdeclarativeitem.cpp | 2 +- src/declarative/qml/qdeclarativecomponent.cpp | 2 +- src/declarative/qml/qdeclarativetypeloader.cpp | 17 +++++++++++++++-- src/declarative/util/qdeclarativeanimation.cpp | 2 +- src/declarative/util/qdeclarativepropertychanges.cpp | 13 +++++++------ src/declarative/util/qdeclarativestate.cpp | 4 ++-- src/declarative/util/qdeclarativestategroup.cpp | 6 +++--- src/declarative/util/qdeclarativeview.cpp | 2 +- 12 files changed, 47 insertions(+), 34 deletions(-) diff --git a/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc b/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc index e33ee13..ac3669d 100644 --- a/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc +++ b/doc/src/howtos/qmlbestpractices/qmlbestpractices-coding.qdoc @@ -90,8 +90,8 @@ Similar to JavaScript or C++, there are two ways of commenting QML code: \section1 Group Properties -Many QML properties are \l{attached-properties}{attached} or -\l {qml-grouped-properties}{group} properties. For convenience, you may treat +Many QML properties are \l{attached-properties}{attached} or +\l {qml-grouped-properties}{group} properties. For convenience, you may treat them as another element when dealing with multiple properties belonging to the same group. diff --git a/doc/src/snippets/declarative/animation.qml b/doc/src/snippets/declarative/animation.qml index 739d009..ae6142d 100644 --- a/doc/src/snippets/declarative/animation.qml +++ b/doc/src/snippets/declarative/animation.qml @@ -179,7 +179,7 @@ Rectangle { } //! [behavior animation] -//! [sequential animation] +//! [sequential animation] Rectangle { id: banner width: 150; height: 100; border.color: "black" @@ -216,7 +216,7 @@ Rectangle { NumberAnimation { target: deploy; property: "opacity"; to: 1.0; duration: 200} } } -//! [sequential animation] +//! [sequential animation] }//end of col //! [parent end] @@ -224,4 +224,3 @@ Rectangle { //! [parent end] //! [document] - diff --git a/doc/src/snippets/declarative/events.qml b/doc/src/snippets/declarative/events.qml index 52fc2bc..3dc44f2 100644 --- a/doc/src/snippets/declarative/events.qml +++ b/doc/src/snippets/declarative/events.qml @@ -63,7 +63,7 @@ onSend: { onPerform: console.log("perform signal emitted") //! [signal handler declaration] -//! [automatic signals] +//! [automatic signals] Rectangle { id: sprite width: 25; height: 25 @@ -72,7 +72,7 @@ Rectangle { onXChanged: console.log("x property changed, emitted xChanged signal") onYChanged: console.log("y property changed, emitted yChanged signal") } -//! [automatic signals] +//! [automatic signals] //! [signal emit] Rectangle { @@ -88,7 +88,7 @@ Rectangle { } //! [signal emit] -//! [connect method] +//! [connect method] Rectangle { id: relay @@ -112,9 +112,9 @@ Rectangle { console.log("Sending to email: " + person + ", " + notice) } } -//! [connect method] +//! [connect method] -//! [forward signal] +//! [forward signal] Rectangle { id: forwarder width: 100; height: 100 @@ -131,9 +131,9 @@ Rectangle { mousearea.clicked.connect(send) } } -//! [forward signal] +//! [forward signal] -//! [connect method] +//! [connect method] //![parent end] } //![parent end] diff --git a/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml b/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml index 99cdc8b..03473ba 100644 --- a/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml +++ b/doc/src/snippets/declarative/mousearea/mousearea-snippet.qml @@ -47,7 +47,7 @@ Rectangle { width: 500; height: 500 color: "green" -Column { +Column { //! [anchor fill] Rectangle { id: button @@ -68,21 +68,21 @@ Rectangle { id: button width: 100; height: 100 -//! [enable handlers] +//! [enable handlers] MouseArea { hoverEnabled: true acceptedButtons: Qt.LeftButton | Qt.RightButton onEntered: console.log("mouse entered the area") onExited: console.log("mouse left the area") } -//! [enable handlers] +//! [enable handlers] } Rectangle { id: button width: 100; height: 100 -//! [mouse handlers] +//! [mouse handlers] MouseArea { anchors.fill: parent onClicked: console.log("area clicked") @@ -90,7 +90,7 @@ Rectangle { onEntered: console.log("mouse entered the area") onExited: console.log("mouse left the area") } -//! [mouse handlers] +//! [mouse handlers] } } //end of column diff --git a/src/declarative/graphicsitems/qdeclarativeitem.cpp b/src/declarative/graphicsitems/qdeclarativeitem.cpp index ffef61b..35de629 100644 --- a/src/declarative/graphicsitems/qdeclarativeitem.cpp +++ b/src/declarative/graphicsitems/qdeclarativeitem.cpp @@ -2561,7 +2561,7 @@ QDeclarativeListProperty QDeclarativeItemPrivate::states() } \endqml - \sa {qdeclarativeanimation.html#transitions}{QML Transitions} + \sa {QML Animation and Transitions}{Transitions} */ diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp index 5840f70..2568240 100644 --- a/src/declarative/qml/qdeclarativecomponent.cpp +++ b/src/declarative/qml/qdeclarativecomponent.cpp @@ -137,7 +137,7 @@ class QByteArray; } \endcode - \sa {Using QML in C++ Applications}, {Integrating QML with existing Qt UI code} + \sa {Using QML Bindings in C++ Applications}, {Integrating QML Code with Existing Qt UI Code} */ /*! diff --git a/src/declarative/qml/qdeclarativetypeloader.cpp b/src/declarative/qml/qdeclarativetypeloader.cpp index 36cdde9..26f3996 100644 --- a/src/declarative/qml/qdeclarativetypeloader.cpp +++ b/src/declarative/qml/qdeclarativetypeloader.cpp @@ -629,7 +629,18 @@ QDeclarativeTypeLoader::~QDeclarativeTypeLoader() } /*! -Return a QDeclarativeTypeData for \a url. The QDeclarativeTypeData may be cached. +\enum QDeclarativeTypeLoader::Option + +This enum defines the options that control the way type data is handled. + +\value None The default value, indicating that no other options + are enabled. +\value PreserveParser The parser used to handle the type data is preserved + after the data has been parsed. +*/ + +/*! +Returns a QDeclarativeTypeData for the specified \a url. The QDeclarativeTypeData may be cached. */ QDeclarativeTypeData *QDeclarativeTypeLoader::get(const QUrl &url) { @@ -650,8 +661,10 @@ QDeclarativeTypeData *QDeclarativeTypeLoader::get(const QUrl &url) } /*! -Return a QDeclarativeTypeData for \a data with the provided base \a url. The +Returns a QDeclarativeTypeData for the given \a data with the provided base \a url. The QDeclarativeTypeData will not be cached. + +The specified \a options control how the loader handles type data. */ QDeclarativeTypeData *QDeclarativeTypeLoader::get(const QByteArray &data, const QUrl &url, Options options) { diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp index a9a639b..e383d1e 100644 --- a/src/declarative/util/qdeclarativeanimation.cpp +++ b/src/declarative/util/qdeclarativeanimation.cpp @@ -74,7 +74,7 @@ QT_BEGIN_NAMESPACE /*! \qmlclass Animation QDeclarativeAbstractAnimation - \ingroup qml-animation-transition + \ingroup qml-animation-transition \since 4.7 \brief The Animation element is the base of all QML animations. diff --git a/src/declarative/util/qdeclarativepropertychanges.cpp b/src/declarative/util/qdeclarativepropertychanges.cpp index ccd122e..abbe4e2 100644 --- a/src/declarative/util/qdeclarativepropertychanges.cpp +++ b/src/declarative/util/qdeclarativepropertychanges.cpp @@ -118,12 +118,13 @@ QT_BEGIN_NAMESPACE \section2 Immediate property changes in transitions - When \l Transitions are used to animate state changes, they animate - properties from their values in the current state to those defined in the - new state (as defined by PropertyChanges objects). However, - it is sometimes desirable to set a property value \e immediately during a - \l Transition, without animation; in these cases, the PropertyAction - element can be used to force an immediate property change. + When \l{QML Animation and Transitions}{Transitions} are used to animate + state changes, they animate properties from their values in the current + state to those defined in the new state (as defined by PropertyChanges + objects). However, it is sometimes desirable to set a property value + \e immediately during a \l Transition, without animation; in these cases, + the PropertyAction element can be used to force an immediate property + change. See the PropertyAction documentation for more details. diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp index 5a4e2b1..5718e29 100644 --- a/src/declarative/util/qdeclarativestate.cpp +++ b/src/declarative/util/qdeclarativestate.cpp @@ -152,14 +152,14 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje Notice the default state is referred to using an empty string (""). - States are commonly used together with \l {Transitions} to provide + States are commonly used together with \l{QML Animation and Transitions}{Transitions} to provide animations when state changes occur. \note Setting the state of an object from within another state of the same object is not allowed. \sa {declarative/animation/states}{states example}, {qmlstates}{States}, - {qdeclarativeanimation.html#transitions}{QML Transitions}, QtDeclarative + {QML Animation and Transitions}{Transitions}, QtDeclarative */ QDeclarativeState::QDeclarativeState(QObject *parent) : QObject(*(new QDeclarativeStatePrivate), parent) diff --git a/src/declarative/util/qdeclarativestategroup.cpp b/src/declarative/util/qdeclarativestategroup.cpp index f1d0997..6459bf9 100644 --- a/src/declarative/util/qdeclarativestategroup.cpp +++ b/src/declarative/util/qdeclarativestategroup.cpp @@ -88,7 +88,7 @@ public: /*! \qmlclass StateGroup QDeclarativeStateGroup - \ingroup qml-state-elements + \ingroup qml-state-elements \since 4.7 \brief The StateGroup element provides state support for non-Item elements. @@ -113,7 +113,7 @@ public: } \endqml - \sa {qmlstate}{States} {Transitions}, {QtDeclarative} + \sa {qmlstate}{States} {QML Animation and Transitions}{Transitions}, {QtDeclarative} */ QDeclarativeStateGroup::QDeclarativeStateGroup(QObject *parent) @@ -213,7 +213,7 @@ void QDeclarativeStateGroupPrivate::clear_states(QDeclarativeListProperty QDeclarativeStateGroup::transitionsProperty() { diff --git a/src/declarative/util/qdeclarativeview.cpp b/src/declarative/util/qdeclarativeview.cpp index bfa2454..de61169 100644 --- a/src/declarative/util/qdeclarativeview.cpp +++ b/src/declarative/util/qdeclarativeview.cpp @@ -236,7 +236,7 @@ void QDeclarativeViewPrivate::itemGeometryChanged(QDeclarativeItem *resizeItem, If you're using your own QGraphicsScene-based scene with QDeclarativeView, remember to enable scene's sticky focus mode and to set itemIndexMethod to QGraphicsScene::NoIndex. - \sa {Integrating QML with existing Qt UI code}, {Using QML in C++ Applications} + \sa {Integrating QML Code with Existing Qt UI Code}, {Using QML Bindings in C++ Applications} */ -- cgit v0.12 From b26f28dbdf994496089b9f398afa4ed1b91ccab2 Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Fri, 18 Feb 2011 19:01:56 +0100 Subject: Adding revised landing page with style and image changes. --- doc/src/images/mobile.png | Bin 0 -> 31620 bytes doc/src/images/qml.png | Bin 0 -> 8662 bytes doc/src/index.qdoc | 185 +++++++++++++++++--------------- doc/src/mainpage.qdoc | 224 +++++++++++++++++++++++++++++++++++++++ doc/src/template/style/style.css | 15 ++- 5 files changed, 339 insertions(+), 85 deletions(-) create mode 100644 doc/src/images/mobile.png create mode 100644 doc/src/images/qml.png create mode 100644 doc/src/mainpage.qdoc diff --git a/doc/src/images/mobile.png b/doc/src/images/mobile.png new file mode 100644 index 0000000..af460e2 Binary files /dev/null and b/doc/src/images/mobile.png differ diff --git a/doc/src/images/qml.png b/doc/src/images/qml.png new file mode 100644 index 0000000..b1e4ab6 Binary files /dev/null and b/doc/src/images/qml.png differ diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index 98d571b..6e745f0 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -26,94 +26,113 @@ ****************************************************************************/ /*! - \page index.html - \keyword Qt Reference Documentation +\page index.html +\keyword Qt Reference Documentation - \div {indexbox guide} +\div {indexbox guide} + \div {heading} + Qt Developer Guide + \enddiv +\enddiv +\div {indexbox tools} + \div {indexboxcont indexboxbar } + \div {sectionlist normallist} \div {heading} - Qt Developer Guide - \enddiv - \div {indexboxcont indexboxbar} - \div {section indexIcon} \emptyspan - \enddiv - \div {section} - Qt is a cross-platform application and UI - framework. Using Qt, you can write web-enabled - applications once and deploy them across desktop, - mobile and embedded operating systems without - rewriting the source code. - \enddiv - \div {section sectionlist} - \list - \o \l{Getting Started Guides}{Getting started} - \o \l{Installation}{Installation} - \o \l{how-to-learn-qt.html}{How to learn Qt} - \o \l{Supported Platforms}{Platform Support} - \o \l{tutorials.html}{Tutorials} and \l{Qt Examples}{Examples} - \o \l{qt4-7-intro.html}{What's new in Qt 4.7} - \endlist - \enddiv + \l What is Qt \enddiv - \enddiv - \div {indexbox api} + \image qt-logo.png + \list + \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/index.html}{Nokia Qt SDK} + \o \l{What's New in Qt 4.7} - latest release + \endlist + \list + \o \l{http://developer.qt.nokia.com/wiki/QtWhitepaper}{Qt C++ Framework} + \o \l{http://developer.qt.nokia.com/wiki/QtCreatorWhitepaper}{Qt Creator} + \o \l{Qt Quick} + \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility} + \o \l{http://doc.qt.nokia.com/qtsimulator-1.1/index.html}{Qt Simulator} + \o \l{Supported Platforms}{Platform Support} + \o \l{http://qt.nokia.com/products}{see more} + \endlist + \enddiv + \div {sectionlist normallist} \div {heading} - Qt API - \enddiv - \div {indexboxcont indexboxbar } - \div {sectionlist tricol} - \list - \o \l{All Classes}{All Classes} - \o \l{All Functions}{All Functions} - \o \l{All Modules}{All Modules} - \o \l{All Namespaces}{All Namespaces} - \o \l{Global Qt Declarations}{Global Declarations} - \o \l{Qt Licenses and Credits}{Licenses and Credits} - \endlist - \enddiv - \div {sectionlist tricol} - \list - \o \l{Programming with Qt} - \o \l{UI Design with Qt} - \o \l{Cross-Platform and Platform-Specific Development} - \o \l{Qt and Key Technologies} - \o \l{Best Practice Guides} - \endlist - \enddiv - \div {sectionlist} - \list - \o \l{qtquick.html}{Qt Quick} - \o \l{qdeclarativeintroduction.html}{Introduction to QML} - \o \l{qdeclarativeelements.html}{QML Elements} - \o \l{qdeclarativeexamples.html}{QML Examples and Demos} - \endlist - \enddiv + \l Develop with Qt \enddiv - \enddiv - \div {indexbox tools} + \image qml.png + \list + \o \l{Develop with Qt}{Steps to Programming Qt Applications} + \o \l{qt-creator-configure-target}{Configure Qt and Creator for Platforms} + \o \l{qt-technologies}{Qt Features and Technologies} + \o \l{qt-ui-creation}{Create UI with Qt} + \o \l{qt-utilities}{Utilities and Testing} + \o \l{qt-deployment}{Deploying Applications and Publish to Ovi Store} + \endlist + + \list + \o \l Kevin's ABC + \endlist + + \enddiv + \div {sectionlist normallist} + \div {heading} + \l See Qt + \enddiv + \image mobile.png + \list + \o \l{Qt Demonstrations}{Application Gallery} + \o \l{Tutorials} + \o \l{Qt Examples}{Examples} + \o \l{QML Examples and Demos} + \endlist + \enddiv + \enddiv +\enddiv +\div {indexbox tools} + \div {heading} + Reference + \enddiv + \div {indexboxcont indexboxbar} + \div {sectionlist normallist} + \div {heading} + Qt API + \enddiv + \list + \o \l{All Classes}{All Classes} + \o \l{All Functions}{All Functions} + \o \l{All Modules}{All Modules} + \o \l{All Namespaces}{All Namespaces} + \o \l{Global Qt Declarations}{Global Declarations} + \o \l{Qt Licenses and Credits}{Licenses and Credits} + \endlist + \enddiv + \div {sectionlist normallist} + \div {heading} + Qt Quick and Mobility + \enddiv + \list + \o \l{Intro to Qt Quick}{Introduction to Qt Quick} + \o \l{QML Elements} + \o \l{QML Examples and Demos} + \o \l{Qt Quick}{see more} + \endlist + \list + \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility APIs} + \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-plugins.html}{Mobility QML Plugins} + \endlist + \enddiv + \div {sectionlist normallist} \div {heading} - Qt Tools - \enddiv - \div {indexboxcont} - \div {section indexIcon} \emptyspan - \enddiv - \div {section} - Qt offers a selection of development tools for - different tasks. Use Qt Creator for project and code - management as well as building powerfull UIs. - \enddiv - \div {section sectionlist} - \list - \o \l{http://doc.qt.nokia.com/qtcreator-2.0/index.html}{Qt Creator} - \o \l{designer-manual.html}{Qt Designer} - \o \l{linguist-manual.html}{Qt Linguist} - \o \l{assistant-manual.html}{Qt Assistant} - \o \l{qmake-manual.html}{Qt qmake} - \o \l{http://doc.qt.nokia.com/qtsimulator-1.0/index.html}{Qt Simulator} - \o \l{http://qt.nokia.com/developer/eclipse-integration}{Eclipse Integration} - \o \l{http://qt.nokia.com/products/appdev}{Add-On Products and Services} - \o \l{qvfb.html}{Virtual Framebuffer} - \endlist - \enddiv + Qt Tools \enddiv - \enddiv + \list + \o \l{http://doc.qt.nokia.com/qtcreator-2.0/index.html}{Qt Creator} + \o \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator} + \o \l{linguist-manual.html}{Qt Linguist} + \o \l{assistant-manual.html}{Qt Assistant} + \o \l{http://qt.nokia.com/products/appdev}{Add-On Products and Services} + \endlist + \enddiv + \enddiv +\enddiv */ diff --git a/doc/src/mainpage.qdoc b/doc/src/mainpage.qdoc new file mode 100644 index 0000000..a8ab995 --- /dev/null +++ b/doc/src/mainpage.qdoc @@ -0,0 +1,224 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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 gettingstarted-develop.html + \title Develop with Qt + \ingroup gettingstarted + +\div {indexboxcont indexboxbar} +Developing a Qt application involves many different steps and stages. From +configuring Creator to distributing binaries to different platforms, Qt provides +many options along the way. +\image quick_screens.png +\enddiv + +\div {indexboxcont indexboxbar normallist} +\keyword qt-creator-configure-target +\section1 Configuring Qt and Creator Targets +Qt and Creator are configurable to compile applications on many platform targets +and multiple platforms. + +\section2 Configuring Creator for Qt Development: +Creator is the integrated development environment for developing Qt applications. +Creator encompasses every step of application development from interface design +to application testing and deployment. +\list +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-project-managing.html}{Creating Qt Projects} +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-building-running.html}{Building and Running Applications} + \list + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-running-targets.html}{Targets} - edit and set compiler targets + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-build-settings.html}{Build Settings} - edit and set build configurations + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-run-settings.html}{Run Settings} - edit and set application run settings + \endlist +\endlist +\section2 Qt Platform Support +Alternatively, Qt may be installed on its own without the Nokia Qt SDK. + +Information regarding Qt Support on Different Platforms: +\list +\o \l{Installing Qt for the Symbian platform}{Symbian and Mobile Development} +\o \l{Support for Windows}{Microsoft Windows} +\o \l{Support for Windows CE and Windows Mobile}{Microsoft Windows CE} +\o \l{Support for Mac}{Apple Mac OS X} +\o \l{Support for Linux/X11}{Linux and X11 Platforms} +\o \l{Support for Embedded Linux}{Qt for Embedded Linux} +\endlist +For more information about the platforms supported +and their installation pages, view the \l {Supported Platforms} and the +\l {Cross-Platform and Platform-Specific Development} pages. +\enddiv + +\div {indexboxcont indexboxbar normallist} +\keyword qt-technologies +\section1 Qt Technologies + +Qt introduces an innovative alternative for inter-object communication, called +“signals and slots”, that replaces the old and unsafe callback technique used in +many legacy frameworks. Qt also provides a conventional event model for handling +mouse clicks, key presses, and other user input. Qt’s cross-platform GUI +applications can support all the user interface functionality required by modern +applications, such as menus, context menus, drag and drop, and dockable +toolbars. Desktop integration features provided by Qt can be used to extend +applications into the surrounding desktop environment, taking advantage of some +of the services provided on each platform. + +The \l{All Modules}{Qt Modules} page has a listing of the technology modules offered by Qt. + +\keyword qt-desktop-meta-object-system +\section2 Qt's Meta-Object System +Qt offers a unique event system based on meta-objects, signals and slots, and property systems. +\list +\o \l{The Meta-Object System}{Qt's Meta-Object System} - Qt's mechanism for signals and slots, inter-object communication, run-time type information, and dynamic property system +\o \l{The Event System}{Event System} - event handling and delivery +\o \l{The Property System}{Property System} - dynamic object properties +\endlist + +\keyword qt-ui-creation +\section2 UI Creation +Qt offers several options with regards to user interface creation: widget based +applications using layouts and Qt Quick interfaces with QML. +\list +\o \l{Qt Quick} - create UIs using QML + \list + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-visual-editor.html}{Creator's QML Design Mode} - design Qt Quick interfaces using Creator's design mode + \endlist +\o \l{Widgets and Layouts} - primary elements for C++ based interfaces + \list + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-using-qt-designer.html}{Creator's Designer} - design interfaces using Qt Designer. + \endlist +\o \l{UI Design with Qt} - covers many Qt features for UI creation +\endlist + +\section2 Inter-Process Communication, Threading, and Networking +In addition to \l{qt-desktop-meta-object-system}{Qt's Meta-Object System}, Qt has several technologies +that deal with inter-process communication. +\list +\o \l{Inter-Process Communication in Qt}{Inter-Process Communication} - various overviews of protocols implemented in Qt +\o \l{Network programming with Qt}{Network Programming} - various overviews to network APIs +\o \l{D-Bus} - D-Bus implementation in Qt +\o \l{Thread Support in Qt}{Thread Support} - overview of threading APIs and concurrent programming topics +\endlist + +\section2 Rendering and Paint System +Qt has various support for different rendering and painting methods. +\list +\o \l{Coordinate System} - Information about the coordinate system used by the paint system +\o \l{Graphics View Framework} - manages a large number of 2D items and visualizes the items +\o \l{Paint System} - A system for painting on the screen or on print devices using the same API +\o \l{QtSvg Module} - module for displaying and creating SVG files +\o Rendering APIs: + \list + \o \l{QtOpenGL Module} - module for rendering with the OpenGL API + \o \l{OpenVG Rendering in Qt}{QtOpenVG Module} - provides support for OpenVG painting + \endlist +\o \l{Printing with Qt} - A guide to producing printed output with Qt's paint system and widgets. +\endlist + +\keyword qt-webkit +\section2 QtWebKit Module +Web applications are increasing in importance and abundance and Qt has +\l{http://www.webkit.org/}{WebKit} support. +\list +\o \l{WebKit in Qt} - WebKit Module +\endlist + +\keyword qt-utilities +\section2 Utilities +Qt supports many utilities that work on multiple platforms. +\list +\o \l{Container Classes}{Containers} - Qt's implementation of various data structures such as linked lists and hash maps +\o \l{Rich Text Processing} - for manipulating structured rich text documents +\o \l{XML Processing} - high level manipulation of XML data using different interfaces +\o \l{Making Applications Scriptable} - provides Qt applications with ECMAScript processor. +\o \l{Qt Linguist Manual}{Qt Linguist} - for translating applications into local languages. +\endlist +For more information, visit the \l{Qt's Tools}{Qt Tools} page. +\section1 Testing Qt Applications +Testing and debugging are part of the development process and Qt offers the +developer multiple methods of testing their code. +\list +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-debugging.html} {Debugging Applications in Creator} - various debugging options in Creator +\o \l {http://doc.qt.nokia.com/qtsimulator/index.html}{Simulator} - testing mobile applications by simulating a mobile environment +\o \l {QML Viewer} - an executable that is able to run QML files +\o \l{QTestLib Manual}{QTestLib} - a unit testing framework built into Qt +\endlist +\enddiv + +\div {indexboxcont indexboxbar normallist} +\keyword qt-deployment +\section1 Deployment +Symbian phones, Maemo devices, desktop environments, embedded Linux devices -- Qt applications are deployable to many environments. +To deploy Qt applications onto multiple platforms, there are special +considerations that each platform introduce. +\list +\o \l{Deploying Qt Applications}{Deploying Qt Libraries} - compares static versus shared libraries and deploying Qt libraries +\o \l{Deploying Qt Applications#licensing}{Deploying Third Party Libraries} - deployment of libraries that are not under Qt's dual-license model. +\o Platform-Specific Deployment: + \list + \o \l{Deploying an Application on X11 Platforms}{X11} - deploying Qt applications on X11 platforms + \o \l{Deploying an Application on Windows}{Windows} - deploying Qt applications on Windows operating systems + \o \l{Deploying an Application on Mac OS X}{Mac OS X} - deploying Qt applications on Mac OS X + \o \l{Deploying Qt for Embedded Linux Applications}{Embedded Linux} - deploying Qt applications on embedded Linux + \o \l{Deploying an Application on the Symbian Platform}{Symbian} - deploying Qt applications on the Symbian platform + \endlist +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-deployment-symbian.html}{Symbian Deployment in Creator} - Symbian application deployment built into Creator +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-deployment-maemo.html}{ Deploying Qt Applications on Maemo Devices} +\endlist + +\section1 Ovi Store Publishing +Creator can publish applications to Ovi Store directly. +\list +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-publish-ovi.html}{Publishing Qt Applications to Ovi Store} +\endlist +For additional information, visit the \l{Cross-Platform and Platform-Specific Development} +and the \l {Supported Platforms} page. + +\enddiv +\div {indexboxcont indexboxbar normallist} +\section1 Where to Go from Here + +Qt Demos and Examples +\list +\o \l{Qt Demonstrations}{Application Gallery} +\o \l{Tutorials} +\o \l {Qt Examples} +\o \l {QML Examples and Demos} +\endlist + +Qt Information +\list +\o \l{Programming with Qt} +\o \l{UI Design with Qt} +\o \l{Cross-platform and Platform-specific Development} +\o \l{Qt and Key Technologies} +\o \l{Best Practice Guides} +\endlist +\enddiv +*/ + + diff --git a/doc/src/template/style/style.css b/doc/src/template/style/style.css index 6c63360..4cb8fef 100755 --- a/doc/src/template/style/style.css +++ b/doc/src/template/style/style.css @@ -146,13 +146,13 @@ } th { - padding: 5px 15px 5px 15px; + padding: 5px 15px 5px 10px; background-color: #E1E1E1; border-left: 1px solid #E6E6E6; } td { - padding: 3px 15px 3px 20px; + padding: 3px 15px 3px 10px; } tr.odd td:hover, tr.even td:hover {} @@ -1382,6 +1382,10 @@ font: normal bold 13px/1 Verdana; } + .content .normallist li + { + font: normal 13px/1 Verdana; + } .indexbox a:hover, .indexbox a:visited:hover { color: #4c0033; @@ -1418,6 +1422,13 @@ background: url(../images/sprites-combined.png) no-repeat -111px -376px; padding: 0; } + .indexbox.tools .indexIcon2 + { + width: 115px; + height: 137px; + background: url(../images/sprites-combined.png) no-repeat -111px -376px; + padding: 0; + } .indexboxcont:after { content: "."; -- cgit v0.12 From da4547fa8728bf54c9ae88874d21f4992ca7ee2b Mon Sep 17 00:00:00 2001 From: David Boddie Date: Mon, 21 Feb 2011 16:49:34 +0100 Subject: Doc: Added copyright header. --- doc/src/howtos/scalabilityintro.qdoc | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/doc/src/howtos/scalabilityintro.qdoc b/doc/src/howtos/scalabilityintro.qdoc index 96337c9..256a1d8 100644 --- a/doc/src/howtos/scalabilityintro.qdoc +++ b/doc/src/howtos/scalabilityintro.qdoc @@ -1,3 +1,29 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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$ +** +****************************************************************************/ /*! \title Scalability -- cgit v0.12 From fc8913c5f9f81818bbbdaf837a4e4c3f600ea3fd Mon Sep 17 00:00:00 2001 From: David Boddie Date: Mon, 21 Feb 2011 16:52:43 +0100 Subject: Doc: Fixed headings to conform to conventions. --- doc/src/platforms/supported-platforms.qdoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/src/platforms/supported-platforms.qdoc b/doc/src/platforms/supported-platforms.qdoc index 283b403..443c8b8 100644 --- a/doc/src/platforms/supported-platforms.qdoc +++ b/doc/src/platforms/supported-platforms.qdoc @@ -684,7 +684,7 @@ across desktop, mobile and embedded operating systems without rewriting the source code. - \section1 Qt is available for the following platforms: + \section1 Qt is Available for the Following Platforms \table \header @@ -707,7 +707,7 @@ \o\l{Support for Maemo}{Maemo} \endtable - \section1 Supported platform details + \section1 Supported Platform Details The Qt team strives to provide support for the platforms most frequently used by Qt users. We have designed our internal testing procedure to @@ -804,7 +804,7 @@ \note The PPC architecture on Mac has been downgraded from tier 1 to tier 2 for 4.7. - \section1 Tier 3 Platforms (Not supported by Nokia) + \section1 Tier 3 Platforms (Not Supported by Nokia) All platforms not specifically listed above are not supported by Nokia. Nokia does not run its unit test suite or perform any other internal tests on platforms not -- cgit v0.12 From 7fa231362631ad1d6a29b045ab943c689d565943 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Mon, 21 Feb 2011 16:53:57 +0100 Subject: Doc: Removed placeholders. --- doc/src/index.qdoc | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index 6e745f0..45f142d 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -38,7 +38,7 @@ \div {indexboxcont indexboxbar } \div {sectionlist normallist} \div {heading} - \l What is Qt + \bold{What is Qt} \enddiv \image qt-logo.png \list @@ -57,7 +57,7 @@ \enddiv \div {sectionlist normallist} \div {heading} - \l Develop with Qt + \bold{Develop with Qt} \enddiv \image qml.png \list @@ -69,14 +69,10 @@ \o \l{qt-deployment}{Deploying Applications and Publish to Ovi Store} \endlist - \list - \o \l Kevin's ABC - \endlist - \enddiv \div {sectionlist normallist} \div {heading} - \l See Qt + \bold{See Qt} \enddiv \image mobile.png \list -- cgit v0.12 From c0b4e11278e1e326e1e5235dd103bc9daca5f364 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Mon, 21 Feb 2011 16:54:27 +0100 Subject: Doc: Fixed whitespace. --- doc/src/mainpage.qdoc | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/src/mainpage.qdoc b/doc/src/mainpage.qdoc index a8ab995..60f4dd6 100644 --- a/doc/src/mainpage.qdoc +++ b/doc/src/mainpage.qdoc @@ -26,9 +26,9 @@ ****************************************************************************/ /*! - \page gettingstarted-develop.html - \title Develop with Qt - \ingroup gettingstarted +\page gettingstarted-develop.html +\title Develop with Qt +\ingroup gettingstarted \div {indexboxcont indexboxbar} Developing a Qt application involves many different steps and stages. From @@ -64,13 +64,13 @@ Information regarding Qt Support on Different Platforms: \o \l{Installing Qt for the Symbian platform}{Symbian and Mobile Development} \o \l{Support for Windows}{Microsoft Windows} \o \l{Support for Windows CE and Windows Mobile}{Microsoft Windows CE} -\o \l{Support for Mac}{Apple Mac OS X} +\o \l{Support for Mac OS X}{Apple Mac OS X} \o \l{Support for Linux/X11}{Linux and X11 Platforms} \o \l{Support for Embedded Linux}{Qt for Embedded Linux} \endlist For more information about the platforms supported and their installation pages, view the \l {Supported Platforms} and the -\l {Cross-Platform and Platform-Specific Development} pages. +\l {Cross-Platform and Platform-Specific Development} pages. \enddiv \div {indexboxcont indexboxbar normallist} @@ -78,9 +78,9 @@ and their installation pages, view the \l {Supported Platforms} and the \section1 Qt Technologies Qt introduces an innovative alternative for inter-object communication, called -“signals and slots”, that replaces the old and unsafe callback technique used in +"signals and slots", that replaces the old and unsafe callback technique used in many legacy frameworks. Qt also provides a conventional event model for handling -mouse clicks, key presses, and other user input. Qt’s cross-platform GUI +mouse clicks, key presses, and other user input. Qt's cross-platform GUI applications can support all the user interface functionality required by modern applications, such as menus, context menus, drag and drop, and dockable toolbars. Desktop integration features provided by Qt can be used to extend @@ -154,15 +154,15 @@ Qt supports many utilities that work on multiple platforms. \o \l{Container Classes}{Containers} - Qt's implementation of various data structures such as linked lists and hash maps \o \l{Rich Text Processing} - for manipulating structured rich text documents \o \l{XML Processing} - high level manipulation of XML data using different interfaces -\o \l{Making Applications Scriptable} - provides Qt applications with ECMAScript processor. +\o \l{Making Applications Scriptable} - provides Qt applications with ECMAScript processor. \o \l{Qt Linguist Manual}{Qt Linguist} - for translating applications into local languages. \endlist -For more information, visit the \l{Qt's Tools}{Qt Tools} page. +For more information, visit the \l{Qt's Tools}{Qt Tools} page. \section1 Testing Qt Applications Testing and debugging are part of the development process and Qt offers the developer multiple methods of testing their code. \list -\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-debugging.html} {Debugging Applications in Creator} - various debugging options in Creator +\o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-debugging.html} {Debugging Applications in Creator} - various debugging options in Creator \o \l {http://doc.qt.nokia.com/qtsimulator/index.html}{Simulator} - testing mobile applications by simulating a mobile environment \o \l {QML Viewer} - an executable that is able to run QML files \o \l{QTestLib Manual}{QTestLib} - a unit testing framework built into Qt -- cgit v0.12 From 8cc0e2327eaffb14c135f229d49386f61f1e1cae Mon Sep 17 00:00:00 2001 From: Jerome Pasion Date: Mon, 21 Feb 2011 17:35:41 +0100 Subject: New landing page with new images. Reviewed-by: David Boddie --- doc/src/howtos/developmentsteps.qdoc | 186 +++++++++++++++++++++++++++++++++++ doc/src/images/guide.png | Bin 0 -> 7376 bytes doc/src/images/qt-logo_large.png | Bin 0 -> 11801 bytes doc/src/images/tools.png | Bin 0 -> 9684 bytes doc/src/index.qdoc | 85 +++++++++++----- doc/src/mainpage.qdoc | 9 ++ 6 files changed, 253 insertions(+), 27 deletions(-) create mode 100644 doc/src/howtos/developmentsteps.qdoc create mode 100644 doc/src/images/guide.png create mode 100644 doc/src/images/qt-logo_large.png create mode 100644 doc/src/images/tools.png diff --git a/doc/src/howtos/developmentsteps.qdoc b/doc/src/howtos/developmentsteps.qdoc new file mode 100644 index 0000000..e898bf5 --- /dev/null +++ b/doc/src/howtos/developmentsteps.qdoc @@ -0,0 +1,186 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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 qtdevelopment-steps.html +\title Qt Development: The Steps from Challenge to Achievement + +\section1 The Challenge + +One day, your boss runs into your cubicle and exclaims to you, "The board blew +millions on a new enterprise HelloWorld application. The new one does not work +and we need a solution quickly before this disaster brings down the company! I'm +putting you in charge of the whole project while I go on vacation -- see you in +2 weeks." + +\section1 Brainstorming Ideas - It is time to play! + +Never one to shy away from a challenge (especially when your job might be on the +line), you first set out try come up with an idea about what your options are. + +You ask around a bit and discover that the broken application was intended to +replace one that has been living on a dusty mainframe for the past 25 years. The +machine is nearing end of life and, rather than invest in replacement hardware +to run a legacy HelloWorld program, the board decided to invest in new software +that could be run on desktops, web, mobile devices and embedded into the +company's main product line -- a pocket size device with a small LCD screen, +which flashes the message "Hello World" every full moon. + +The vendor that was chosen to handle this task was a well known multinational +company that specialized in enterprise CRM/ERP systems. The project missed +several delivery deadlines over a 2 year period, and was 500% over budget. There +was not going to be much margin for error trying to fix the problem, and there +would likely be no budget either. + +You begin researching dozens of possible possible approaches to the problem. One +of the biggest challenges is that there are very few options that will allow you +to create native applications that use the same framework for targeting +\l{qt-creator-configure-target}{multiple platforms}. + +Some years ago you had coded a small desktop application using the Qt framework, +without realizing that it also can be used for targeting the web, mobile devices +and embedded devices. Since that time, Qt has added a new feature called \l{Qt +Quick}, which provides the ability to easily design applications with intuitive, +modern-looking, fluid user interfaces. + +\section1 Creating an Objective + +You quickly realize that you might need two, three, or more interfaces for your +application -- one for each of the target platforms you are aiming for. +Thankfully Qt has options well suited for each of them. + +For your mobile application the choice seems obvious enough. The new Qt Quick +technology looks very promising, but you do not know QML; the declarative +language that helps define the interface in a Qt Quick program. You still want +to give it a try, but worry that you might not have something complete before +your boss returns from vacation in two weeks. You also wonder if Qt Quick is +applicable to desktop and embedded targets -- and then of course there is the +need for something targeting the web. You decide to give Qt Quick a try first +and \l{QML Examples and Demos}{see where it takes you}. + +\section1 Developing Plans + +One thing you realize after reading up on \l{Qt Quick} is that things are very +different from the desktop when designing an interface. Qt Quick doesn't contain +ready made UI 'chrome'; the widgets and other design elements that define the +application interface. A new technology, called Qt Quick Components, looks like +a promising solution, but the components will only be available at a later date. +For now you'll have to come up with something on your own -- but you are keen to +give your design skills a work out, and learning to use Qt Quick seems to be a +great way to do it. + +Not knowing a better place to start, you begin by taking a cue from web design +and plan a wireframe, which helps +\l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-visual-editor.html}{define the application layout}, +content and user interaction. You decide on breaking the field of the screen +space into three roughly equal size parts. There will be one section across the +top, which will span the width of the screen, and two sections in the lower +have, which will be approximately as tall as the top section is wide (when in +portrait mode). + +The top section will be a simple text representation of the phrase "Hello World" +in English. In the lower left you would like to place some kind of audio +playback feature that repeats back the phrase in the top section of the screen. +Finally, in the lower right hand side of the screen will be four links to +similar views for additional languages -- Mandarin Chinese, Brazilian +Portuguese, Arabic, and Russian. When the user clicks one of the links the text +at the top is then translated, and the playback corresponds to the appropriate +language. + +While the wireframe is effective in dealing with one part of the design +challenge, it does not cover visual aspects other than layout and content. This +means that you still need to define colours, white space, and typography (among +other things). This is where a style guide would come in handy, if your company +already had one that is. In the absence of one you decide to again get some +inspiration from the web, and you mimic some of the company's website design +into your application -- a sans-serif font for white text on a blue field across +the top, black text on white for the bottom two sections, and a small company +logo to the left of the "Hello World" message. + + +\section1 Execution: The Coding Begins! + +At long last you sit down to \l{qt-technologies}{implement} your plans and +designs. The first few steps go according to plan, and creating the basic layout +and text goes fairly smoothly -- but you run into a few challenges quite +quickly: + +Devising a user friendly interface to audio playback is not as intuitive as you +first thought. Since there exist a ready made component for +\l{http://doc.qt.nokia.com/qtmobility-1.1.0/qml-multimedia.html}{multimedia}, +you remove the bottom left field and now have the screen split in two. You add +textual links for each of the five target languages, and when the user clicks +one of them the message text changes and the appropriate audio plays back. It is +a small sacrifice to make for now, and you are sure there is a solution to be +found once you have become more proficient with QML. + +The next challenge you run into is that \l{qt-deployment}{deploying} the +application to a Symbian phone is not as clearly understood as you expected. +Again you are sure there is something you are missing, but for the time being +you manually copy the .sis file to the "Installs" directory on the phone +(connected to the development machine by USB) and then install it through the +Application Manager. + +When you finally manage to install the application on the device you notice +something that looks rather peculiar, and something you had not thought of. When +the phone is turned into landscape mode, your text remains at the same absolute +coordinates as when it was in portrait mode. You had not realized you needed to +anchor it in order to achieve the centering you wanted. There was an +\l{qt-testing}{easy fix} for this, but you were glad you saw this earlier rather +than later. + + +\section1 Innovating + +After the ups and downs of learning to develop a basic application +using Qt Quick, you start to see greater possibilities for using Qt technologies +for your current and future projects: + +\list +\o Extending HTML5 based applications that tie Javascript to a Qt C++ back end +using \l{Qt WebKit} +\o An \l{qt-rendering-painting-system}{OpenGL} based UI for embedded platforms +\o \l{Gestures Programming}{Touch} screen support +\o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/location-overview.html}{Location} based applications +\o \l{qt-technologies}{Much, much more} +\endlist + + +\section1 The Achievement + +After your boss returned from vacation you presented him with the finished Qt +Quick application, demonstrating it on both a mobile device as well as desktop +(it happened to work well on both with little modification). You also provided +him a presentation that detailed your road map for taking things to the next +level -- targeting other platforms, such as the web, as well as improving on the +existing application you just completed. + +Even though the final product did not turn out the way you originally planned, +your boss was still sufficiently impressed. Not only was the go ahead given for +future projects, but ramping up a small team of developers and designers was +also suggested to help support your efforts. + +*/ diff --git a/doc/src/images/guide.png b/doc/src/images/guide.png new file mode 100644 index 0000000..f4b0df1 Binary files /dev/null and b/doc/src/images/guide.png differ diff --git a/doc/src/images/qt-logo_large.png b/doc/src/images/qt-logo_large.png new file mode 100644 index 0000000..4e230bd Binary files /dev/null and b/doc/src/images/qt-logo_large.png differ diff --git a/doc/src/images/tools.png b/doc/src/images/tools.png new file mode 100644 index 0000000..4d717b5 Binary files /dev/null and b/doc/src/images/tools.png differ diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc index 6e745f0..3984574 100644 --- a/doc/src/index.qdoc +++ b/doc/src/index.qdoc @@ -37,53 +37,90 @@ \div {indexbox tools} \div {indexboxcont indexboxbar } \div {sectionlist normallist} + \div {heading} + \l What is Qt + \enddiv + \image qt-logo_large.png + Qt is a cross-platform application and UI framework. Using Qt, you can + write applications once and deploy them across desktop, mobile, and + embedded operating systems without rewriting the source code. + \enddiv + \div {sectionlist normallist} \div {heading} - \l What is Qt + \emptyspan \enddiv - \image qt-logo.png \list - \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/index.html}{Nokia Qt SDK} - \o \l{What's New in Qt 4.7} - latest release + \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/index.html}{Qt SDK} + \o \l{http://developer.qt.nokia.com/wiki/QtCreatorWhitepaper}{Qt Creator} + \o \l{http://doc.qt.nokia.com/qtsimulator-1.1/index.html}{Qt Simulator} \endlist \list \o \l{http://developer.qt.nokia.com/wiki/QtWhitepaper}{Qt C++ Framework} - \o \l{http://developer.qt.nokia.com/wiki/QtCreatorWhitepaper}{Qt Creator} \o \l{Qt Quick} \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility} - \o \l{http://doc.qt.nokia.com/qtsimulator-1.1/index.html}{Qt Simulator} + \o \l{Qt WebKit} + \endlist + \list \o \l{Supported Platforms}{Platform Support} - \o \l{http://qt.nokia.com/products}{see more} + \o \l{What's New in Qt 4.7} - latest release \endlist \enddiv \div {sectionlist normallist} \div {heading} + \l See Qt + \enddiv + \image mobile.png + \list + \o \l{Qt Demonstrations}{Application Gallery} + \o \l{Tutorials} + \o \l{Qt Examples}{Examples} + \o \l{QML Examples and Demos} + \endlist + \enddiv + \enddiv +\enddiv +\div {indexbox tools} + \div {indexboxcont indexboxbar } + \div {sectionlist normallist} + \div {heading} \l Develop with Qt \enddiv - \image qml.png + \image tools.png \list \o \l{Develop with Qt}{Steps to Programming Qt Applications} \o \l{qt-creator-configure-target}{Configure Qt and Creator for Platforms} \o \l{qt-technologies}{Qt Features and Technologies} - \o \l{qt-ui-creation}{Create UI with Qt} \o \l{qt-utilities}{Utilities and Testing} \o \l{qt-deployment}{Deploying Applications and Publish to Ovi Store} \endlist - + \enddiv + \div {sectionlist normallist} + \div {heading} + \l Featured Articles + \enddiv + \image guide.png \list - \o \l Kevin's ABC + \o \l{Scalability}{How to Create Scalable Applications} + \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-symbian.html}{Setting Up Development Environment for Symbian} + \o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-maemo.html}{Setting Up Development Environment for Maemo} + \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-publish-ovi.html}{Publishing Qt Applications to Ovi Store} + \endlist + \list + \o \l{Qt Development: The Steps from Challenge to Achievement}{The Steps from Challenge to Achievement} + A case analysis of a business development problem and a search for +innovative solutions using Qt. \endlist - \enddiv \div {sectionlist normallist} \div {heading} - \l See Qt + \l UI Creation with Qt \enddiv - \image mobile.png + \image qml.png \list - \o \l{Qt Demonstrations}{Application Gallery} - \o \l{Tutorials} - \o \l{Qt Examples}{Examples} - \o \l{QML Examples and Demos} + \o \l{qt-ui-creation}{Create UI with Qt} + \o \l{qt-rendering-painting-system}{Qt's Rendering and Painting Systems} + \o \l{Qt Quick} - develop fluid UIs with QML + \o \l{Widgets and Layouts} - elements for C++ interfaces \endlist \enddiv \enddiv @@ -103,18 +140,13 @@ \o \l{All Modules}{All Modules} \o \l{All Namespaces}{All Namespaces} \o \l{Global Qt Declarations}{Global Declarations} - \o \l{Qt Licenses and Credits}{Licenses and Credits} + \endlist \enddiv \div {sectionlist normallist} - \div {heading} - Qt Quick and Mobility - \enddiv \list - \o \l{Intro to Qt Quick}{Introduction to Qt Quick} + \o \l{Qt Quick} \o \l{QML Elements} - \o \l{QML Examples and Demos} - \o \l{Qt Quick}{see more} \endlist \list \o \l{http://doc.qt.nokia.com/qtmobility-1.1.0/index.html}{Qt Mobility APIs} @@ -123,14 +155,13 @@ \enddiv \div {sectionlist normallist} \div {heading} - Qt Tools + Qt Manuals \enddiv \list \o \l{http://doc.qt.nokia.com/qtcreator-2.0/index.html}{Qt Creator} \o \l{http://doc.qt.nokia.com/qtsimulator/index.html}{Qt Simulator} \o \l{linguist-manual.html}{Qt Linguist} \o \l{assistant-manual.html}{Qt Assistant} - \o \l{http://qt.nokia.com/products/appdev}{Add-On Products and Services} \endlist \enddiv \enddiv diff --git a/doc/src/mainpage.qdoc b/doc/src/mainpage.qdoc index a8ab995..bcd4cda 100644 --- a/doc/src/mainpage.qdoc +++ b/doc/src/mainpage.qdoc @@ -55,7 +55,11 @@ to application testing and deployment. \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-build-settings.html}{Build Settings} - edit and set build configurations \o \l{http://doc.qt.nokia.com/qtcreator-snapshot/creator-run-settings.html}{Run Settings} - edit and set application run settings \endlist +\o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-symbian.html}{Setting Up Development Environment for Symbian} +\o \l{http://doc.qt.nokia.com/nokia-qtsdk-1.0/creator-developing-maemo.html}{Setting Up Development Environment for Maemo} \endlist + +\keyword qt-platform-support \section2 Qt Platform Support Alternatively, Qt may be installed on its own without the Nokia Qt SDK. @@ -124,6 +128,7 @@ that deal with inter-process communication. \o \l{Thread Support in Qt}{Thread Support} - overview of threading APIs and concurrent programming topics \endlist +\keyword qt-rendering-painting-system \section2 Rendering and Paint System Qt has various support for different rendering and painting methods. \list @@ -158,6 +163,9 @@ Qt supports many utilities that work on multiple platforms. \o \l{Qt Linguist Manual}{Qt Linguist} - for translating applications into local languages. \endlist For more information, visit the \l{Qt's Tools}{Qt Tools} page. +\enddiv +\div {indexboxcont indexboxbar normallist} +\keyword qt-testing \section1 Testing Qt Applications Testing and debugging are part of the development process and Qt offers the developer multiple methods of testing their code. @@ -217,6 +225,7 @@ Qt Information \o \l{Cross-platform and Platform-specific Development} \o \l{Qt and Key Technologies} \o \l{Best Practice Guides} +\o \l{Qt Licenses and Credits}{Licenses and Credits} \endlist \enddiv */ -- cgit v0.12