examples/quick/ui-components/slideswitch/doc/src/example-slideswitch.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28
  29 /*!
  30 \page qmlexampletoggleswitch.html tutorial
  31 \title QML Example - Toggle Switch
  32 \brief A reusable switch component made in QML
  33  \ingroup qtquickexamples
  34
  35 This example shows how to create a reusable switch component in QML.
  36
  37 The code for this example can be found in the \c examples/quick/tutorials/ui-components/slideswitch directory.
  38
  39 The elements that compose the switch are:
  40
  41 \list
  42 \li a \c on property (the interface to interact with the switch),
  43 \li two images (the background image and the knob),
  44 \li two mouse regions for user interation (on the background image and on the knob),
  45 \li two states (an \e on state and an \e off state),
  46 \li two functions or slots to react to the user interation (\c toggle() and \c dorelease()),
  47 \li and a transition that describe how to go from one state to the other.
  48 \endlist
  49
  50 \section1 Switch.qml
  51 \snippet quick/ui-components/slideswitch/content/Switch.qml 0
  52
  53 \section1 Walkthrough
  54
  55 \section2 Interface
  56 \snippet quick/ui-components/slideswitch/content/Switch.qml 1
  57
  58 This property is the interface of the switch. By default, the switch is off and this property is \c false.
  59 It can be used to activate/disactivate the switch or to query its current state.
  60
  61 In this example:
  62
  63 \qml
  64 Item {
  65     Switch {
  66         id: mySwitch
  67         on: true
  68     }
  69     Text {
  70         text: "The switch is on"
  71         visible: mySwitch.on == true
  72     }
  73 }
  74 \endqml
  75
  76 the text will only be visible when the switch is on.
  77
  78 \section2 Images and user interaction
  79 \snippet quick/ui-components/slideswitch/content/Switch.qml 4
  80
  81 First, we create the background image of the switch.
  82 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.
  83 A \c MouseArea has a \c onClicked property that is triggered when the item is clicked. For the moment we will just call a
  84 \c toggle() function. We will see what this function does in a moment.
  85
  86 \snippet quick/ui-components/slideswitch/content/Switch.qml 5
  87
  88 Then, we place the image of the knob on top of the background.
  89 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
  90 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
  91 in the \c dorelease() function that is called in the \c onReleased property.
  92
  93 \section2 States
  94 \snippet quick/ui-components/slideswitch/content/Switch.qml 6
  95
  96 We define the two states of the switch:
  97 \list
  98 \li In the \e on state the knob is on the right (\c x position is 78) and the \c on property is \c true.
  99 \li In the \e off state the knob is on the left (\c x position is 1) and the \c on property is \c false.
 100 \endlist
 101
 102 For more information on states see \l{Qt Quick States}.
 103
 104 \section2 Functions
 105
 106 We add two JavaScript functions to our switch:
 107
 108 \snippet quick/tutorials/ui-components/slideswitch/content/Switch.qml 2
 109
 110 This first function is called when the background image or the knob are clicked. We simply want the switch to toggle between the two
 111 states (\e on and \e off).
 112
 113
 114 \snippet quick/ui-components/slideswitch/content/Switch.qml 3
 115
 116 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
 117 (neither \e on nor \e off). If it is the case call the \c toggle() function otherwise we do nothing.
 118
 119 For more information on scripts see \l{Using JavaScript Expressions in QML}.
 120
 121 \section2 Transition
 122 \snippet quick/ui-components/slideswitch/content/Switch.qml 7
 123
 124 At this point, when the switch toggles between the two states the knob will instantly change its \c x position between 1 and 78.
 125 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.
 126
 127 For more information on transitions see \l{Animation and Transitions in Qt Quick}.
 128
 129 \section1 Usage
 130 The switch can be used in a QML file, like this:
 131 \snippet quick/ui-components/slideswitch/slideswitch.qml 0
 132 */