From 5781f7f226137634e585197e4f4717748c8a4f76 Mon Sep 17 00:00:00 2001 From: Alan Alpert Date: Thu, 19 Jan 2012 16:03:13 +1000 Subject: Document toys examples Change-Id: I376c4169ffff19e06b55e578e57101a476500b04 Reviewed-by: Martin Jones --- doc/src/declarative/example-slideswitch.qdoc | 130 ------------------------- doc/src/declarative/example-textballoons.qdoc | 104 -------------------- doc/src/examples/example-slideswitch.qdoc | 132 ++++++++++++++++++++++++++ doc/src/examples/example-textballoons.qdoc | 104 ++++++++++++++++++++ doc/src/examples/examples-toys.qdoc | 69 ++++++++++++++ doc/src/images/qml-corkboards-example.png | Bin 0 -> 615192 bytes doc/src/images/qml-dynamicscene-example.png | Bin 0 -> 32286 bytes 7 files changed, 305 insertions(+), 234 deletions(-) delete mode 100644 doc/src/declarative/example-slideswitch.qdoc delete mode 100644 doc/src/declarative/example-textballoons.qdoc create mode 100644 doc/src/examples/example-slideswitch.qdoc create mode 100644 doc/src/examples/example-textballoons.qdoc create mode 100644 doc/src/examples/examples-toys.qdoc create mode 100644 doc/src/images/qml-corkboards-example.png create mode 100644 doc/src/images/qml-dynamicscene-example.png (limited to 'doc/src') diff --git a/doc/src/declarative/example-slideswitch.qdoc b/doc/src/declarative/example-slideswitch.qdoc deleted file mode 100644 index 87bc942c79..0000000000 --- a/doc/src/declarative/example-slideswitch.qdoc +++ /dev/null @@ -1,130 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qdeclarativeexampletoggleswitch.html -\inqmlmodule QtQuick 2 -\title QML Example - Toggle Switch - -This example shows how to create a reusable switch component in QML. - -The code for this example can be found in the \c $QTDIR/examples/declarative/ui-components/slideswitch directory. - -The elements that compose the switch are: - -\list -\o a \c on property (the interface to interact with the switch), -\o two images (the background image and the knob), -\o two mouse regions for user interation (on the background image and on the knob), -\o two states (a \i on state and a \i off state), -\o two functions or slots to react to the user interation (\c toggle() and \c dorelease()), -\o and a transition that describe how to go from one state to the other. -\endlist - -\section1 Switch.qml -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 0 - -\section1 Walkthrough - -\section2 Interface -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 1 - -This property is the interface of the switch. By default, the switch is off and this property is \c false. -It can be used to activate/disactivate the switch or to query its current state. - -In this example: - -\qml -Item { - Switch { - id: mySwitch - on: true - } - Text { - text: "The switch is on" - visible: mySwitch.on == true - } -} -\endqml - -the text will only be visible when the switch is on. - -\section2 Images and user interaction -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 4 - -First, we create the background image of the switch. -In order for the switch to toggle when the user clicks on the background, we add a \l{MouseArea} as a child item of the image. -A \c MouseArea has a \c onClicked property that is triggered when the item is clicked. For the moment we will just call a -\c toggle() function. We will see what this function does in a moment. - -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 5 - -Then, we place the image of the knob on top of the background. -The interaction here is a little more complex. We want the knob to move with the finger when it is clicked. That is what the \c drag -property of the \c MouseArea is for. We also want to toggle the switch if the knob is released between state. We handle this case -in the \c dorelease() function that is called in the \c onReleased property. - -\section2 States -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 6 - -We define the two states of the switch: -\list -\o In the \i on state the knob is on the right (\c x position is 78) and the \c on property is \c true. -\o In the \i off state the knob is on the left (\c x position is 1) and the \c on property is \c false. -\endlist - -For more information on states see \l{qmlstates}{QML States}. - -\section2 Functions - -We add two JavaScript functions to our switch: - -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 2 - -This first function is called when the background image or the knob are clicked. We simply want the switch to toggle between the two -states (\i on and \i off). - - -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 3 - -This second function is called when the knob is released and we want to make sure that the knob does not end up between states -(neither \i on nor \i off). If it is the case call the \c toggle() function otherwise we do nothing. - -For more information on scripts see \l{Integrating JavaScript}. - -\section2 Transition -\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 7 - -At this point, when the switch toggles between the two states the knob will instantly change its \c x position between 1 and 78. -In order for the the knob to move smoothly we add a transition that will animate the \c x property with an easing curve for a duration of 200ms. - -For more information on transitions see \l{QML Animation and Transitions}. - -\section1 Usage -The switch can be used in a QML file, like this: -\snippet examples/declarative/ui-components/slideswitch/slideswitch.qml 0 -*/ diff --git a/doc/src/declarative/example-textballoons.qdoc b/doc/src/declarative/example-textballoons.qdoc deleted file mode 100644 index e475cf15bd..0000000000 --- a/doc/src/declarative/example-textballoons.qdoc +++ /dev/null @@ -1,104 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 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$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \title Scenegraph Painted Item Example - \example declarative/painteditem/textballoons - - The Painted Item example shows how to use the QML Scene Graph framework to - implement custom scenegraph items using QPainter. - - \image declarative-textballoons_example.png - - The QQuickPaintedItem class is a class derived from QQuickItem for implementing - custom QML Scene Graph items using the QPainter interfaces. - - The example consists of an item class, a plugin class and a QML file - to use this plugin. The \c TextBalloon class represents the individual - text balloons extending QQuickPaintedItem, the \c TextBalloonPlugin class - represents the skeleton code for a QtQuick plugin and the - \c textballoons.qml file is used to load the plugin and display the text - balloons. - - We will focus on the \c TextBalloon class first and continue with the - \c textballoons.qml file. For an example on how to implement a QtQuick - plugin please look at \l{declarative/tutorials/extending/chapter6-plugins} - {Writing an Extension Plugin} - - \section1 TextBalloon Class Declaration - - The \c TextBalloon class inherits from QQuickPaintedItem. QQuickPaintedItem - is the base class for all QPainter based items in the QML Scene Graph - framework. - - \snippet examples/declarative/painteditem/textballoons/textballoon.h 0 - - To implement a QQuickPaintedItem you must implement QQuickPaintedIem's pure - virtual function \l {QQuickPaintedItem::}{paint()} which implements the - painting of the element. - - \section1 TextBalloon Class Definition - - We have to be sure to initialize the rightAligned property for a - TextBalloon item. - - \snippet examples/declarative/painteditem/textballoons/textballoon.cpp 0 - - Then we implement the \c paint() function which is automatically called by - the Scenegraph framework to paint the contents of the item. The function - paints the item in local coordinates. - - \snippet examples/declarative/painteditem/textballoons/textballoon.cpp 1 - - We start with setting the pen and brush on the item to define the look of - the item. After that we start drawing. Note that the \l {QQuickPaintedItem::}{boundingRect()} - item is called to draw depending on the size of the item. The rectangle - returned by the \l {QQuickPaintedItem::}{boundingRect()} function is the size - of the item as defined in the QML file. - - \section1 textballoons.qml file - - The Interface consists of two main parts. The scrollable area with the - textballoons and the controls button to add new balloons. - - \section2 BalloonView - - \snippet examples/declarative/painteditem/textballoons/textballoons.qml 0 - - The balloonModel contains two elements at application start which will be - displayed by the balloonView. The balloonView alernates the TextBalloon - delegate items between left-aligned and right-aligned. - - \section2 Controls - - \snippet examples/declarative/painteditem/textballoons/textballoons.qml 1 - - The controls part of the UI contains a rectangle with a MouseArea which - changes color when the mouse hovers over it. This control 'button' adds - a new element to the end of the model with a random width. - - */ diff --git a/doc/src/examples/example-slideswitch.qdoc b/doc/src/examples/example-slideswitch.qdoc new file mode 100644 index 0000000000..83fa568f98 --- /dev/null +++ b/doc/src/examples/example-slideswitch.qdoc @@ -0,0 +1,132 @@ +/**************************************************************************** +** +** Copyright (C) 2012 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$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page qdeclarativeexampletoggleswitch.html +\inqmlmodule QtQuick 2 +\title QML Example - Toggle Switch +\example declarative/ui-components/slideswitch +\brief A reusable switch component in QML + +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. + +The elements that compose the switch are: + +\list +\o a \c on property (the interface to interact with the switch), +\o two images (the background image and the knob), +\o two mouse regions for user interation (on the background image and on the knob), +\o two states (a \i on state and a \i off state), +\o two functions or slots to react to the user interation (\c toggle() and \c dorelease()), +\o and a transition that describe how to go from one state to the other. +\endlist + +\section1 Switch.qml +\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 0 + +\section1 Walkthrough + +\section2 Interface +\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 1 + +This property is the interface of the switch. By default, the switch is off and this property is \c false. +It can be used to activate/disactivate the switch or to query its current state. + +In this example: + +\qml +Item { + Switch { + id: mySwitch + on: true + } + Text { + text: "The switch is on" + visible: mySwitch.on == true + } +} +\endqml + +the text will only be visible when the switch is on. + +\section2 Images and user interaction +\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 4 + +First, we create the background image of the switch. +In order for the switch to toggle when the user clicks on the background, we add a \l{MouseArea} as a child item of the image. +A \c MouseArea has a \c onClicked property that is triggered when the item is clicked. For the moment we will just call a +\c toggle() function. We will see what this function does in a moment. + +\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 5 + +Then, we place the image of the knob on top of the background. +The interaction here is a little more complex. We want the knob to move with the finger when it is clicked. That is what the \c drag +property of the \c MouseArea is for. We also want to toggle the switch if the knob is released between state. We handle this case +in the \c dorelease() function that is called in the \c onReleased property. + +\section2 States +\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 6 + +We define the two states of the switch: +\list +\o In the \i on state the knob is on the right (\c x position is 78) and the \c on property is \c true. +\o In the \i off state the knob is on the left (\c x position is 1) and the \c on property is \c false. +\endlist + +For more information on states see \l{qmlstates}{QML States}. + +\section2 Functions + +We add two JavaScript functions to our switch: + +\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 2 + +This first function is called when the background image or the knob are clicked. We simply want the switch to toggle between the two +states (\i on and \i off). + + +\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 3 + +This second function is called when the knob is released and we want to make sure that the knob does not end up between states +(neither \i on nor \i off). If it is the case call the \c toggle() function otherwise we do nothing. + +For more information on scripts see \l{Integrating JavaScript}. + +\section2 Transition +\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 7 + +At this point, when the switch toggles between the two states the knob will instantly change its \c x position between 1 and 78. +In order for the the knob to move smoothly we add a transition that will animate the \c x property with an easing curve for a duration of 200ms. + +For more information on transitions see \l{QML Animation and Transitions}. + +\section1 Usage +The switch can be used in a QML file, like this: +\snippet examples/declarative/ui-components/slideswitch/slideswitch.qml 0 +*/ diff --git a/doc/src/examples/example-textballoons.qdoc b/doc/src/examples/example-textballoons.qdoc new file mode 100644 index 0000000000..e475cf15bd --- /dev/null +++ b/doc/src/examples/example-textballoons.qdoc @@ -0,0 +1,104 @@ +/**************************************************************************** +** +** Copyright (C) 2012 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$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Scenegraph Painted Item Example + \example declarative/painteditem/textballoons + + The Painted Item example shows how to use the QML Scene Graph framework to + implement custom scenegraph items using QPainter. + + \image declarative-textballoons_example.png + + The QQuickPaintedItem class is a class derived from QQuickItem for implementing + custom QML Scene Graph items using the QPainter interfaces. + + The example consists of an item class, a plugin class and a QML file + to use this plugin. The \c TextBalloon class represents the individual + text balloons extending QQuickPaintedItem, the \c TextBalloonPlugin class + represents the skeleton code for a QtQuick plugin and the + \c textballoons.qml file is used to load the plugin and display the text + balloons. + + We will focus on the \c TextBalloon class first and continue with the + \c textballoons.qml file. For an example on how to implement a QtQuick + plugin please look at \l{declarative/tutorials/extending/chapter6-plugins} + {Writing an Extension Plugin} + + \section1 TextBalloon Class Declaration + + The \c TextBalloon class inherits from QQuickPaintedItem. QQuickPaintedItem + is the base class for all QPainter based items in the QML Scene Graph + framework. + + \snippet examples/declarative/painteditem/textballoons/textballoon.h 0 + + To implement a QQuickPaintedItem you must implement QQuickPaintedIem's pure + virtual function \l {QQuickPaintedItem::}{paint()} which implements the + painting of the element. + + \section1 TextBalloon Class Definition + + We have to be sure to initialize the rightAligned property for a + TextBalloon item. + + \snippet examples/declarative/painteditem/textballoons/textballoon.cpp 0 + + Then we implement the \c paint() function which is automatically called by + the Scenegraph framework to paint the contents of the item. The function + paints the item in local coordinates. + + \snippet examples/declarative/painteditem/textballoons/textballoon.cpp 1 + + We start with setting the pen and brush on the item to define the look of + the item. After that we start drawing. Note that the \l {QQuickPaintedItem::}{boundingRect()} + item is called to draw depending on the size of the item. The rectangle + returned by the \l {QQuickPaintedItem::}{boundingRect()} function is the size + of the item as defined in the QML file. + + \section1 textballoons.qml file + + The Interface consists of two main parts. The scrollable area with the + textballoons and the controls button to add new balloons. + + \section2 BalloonView + + \snippet examples/declarative/painteditem/textballoons/textballoons.qml 0 + + The balloonModel contains two elements at application start which will be + displayed by the balloonView. The balloonView alernates the TextBalloon + delegate items between left-aligned and right-aligned. + + \section2 Controls + + \snippet examples/declarative/painteditem/textballoons/textballoons.qml 1 + + The controls part of the UI contains a rectangle with a MouseArea which + changes color when the mouse hovers over it. This control 'button' adds + a new element to the end of the model with a random width. + + */ diff --git a/doc/src/examples/examples-toys.qdoc b/doc/src/examples/examples-toys.qdoc new file mode 100644 index 0000000000..8f81155b73 --- /dev/null +++ b/doc/src/examples/examples-toys.qdoc @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** Copyright (C) 2012 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$ +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +/*! + \title QML Example - Calculator + \example declarative/calculator + \brief This is an example application written in QML. + \image qml-calculator-demo-small.png +*/ + +/*! + \title QML Example - Samegame + \example declarative/samegame + \brief This example demonstrates creating a game with javascript game logic. + \image qml-samegame-demo-small.png +*/ + +/*! + \title QML Example - Snake + \example declarative/snake + \brief This example demonstrates creating a game using javascript game logic. + \image qml-snake-demo-small.png +*/ + +/*! + \title QML Example - Corkboards + \example declarative/toys/corkboards + \brief This example demonstrates using components inside a flickable. + \image qml-corkboards-example.png +*/ + +/*! + \title QML Example - Dynamic Scene + \example declarative/toys/dynamicscene + \brief This example demonstrates creating components dynamically. + \image qml-dynamicscene-example.png +*/ + +/*! + \title QML Example - Clocks + \example declarative/toys/clocks + \brief This example demonstrates creating components and using them multiple times. + \image qml-clocks-example.png +*/ diff --git a/doc/src/images/qml-corkboards-example.png b/doc/src/images/qml-corkboards-example.png new file mode 100644 index 0000000000..657ff5cb17 Binary files /dev/null and b/doc/src/images/qml-corkboards-example.png differ diff --git a/doc/src/images/qml-dynamicscene-example.png b/doc/src/images/qml-dynamicscene-example.png new file mode 100644 index 0000000000..38260a7d3f Binary files /dev/null and b/doc/src/images/qml-dynamicscene-example.png differ -- cgit v1.2.3