doc/src/examples/example-slideswitch.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** GNU Free Documentation License
  10 ** Alternatively, this file may be used under the terms of the GNU Free
  11 ** Documentation License version 1.3 as published by the Free Software
  12 ** Foundation and appearing in the file included in the packaging of
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qdeclarativeexampletoggleswitch.html
  30 \inqmlmodule QtQuick 2
  31 \title QML Example - Toggle Switch
  32 \example declarative/ui-components/slideswitch
  33 \brief A reusable switch component in QML
  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 $QTDIR/examples/declarative/ui-components/slideswitch directory.
  38
  39 The elements that compose the switch are:
  40
  41 \list
  42 \o a \c on property (the interface to interact with the switch),
  43 \o two images (the background image and the knob),
  44 \o two mouse regions for user interation (on the background image and on the knob),
  45 \o two states (a \i on state and a \i off state),
  46 \o two functions or slots to react to the user interation (\c toggle() and \c dorelease()),
  47 \o and a transition that describe how to go from one state to the other.
  48 \endlist
  49
  50 \section1 Switch.qml
  51 \snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 0
  52
  53 \section1 Walkthrough
  54
  55 \section2 Interface
  56 \snippet examples/declarative/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 examples/declarative/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 examples/declarative/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 examples/declarative/ui-components/slideswitch/content/Switch.qml 6
  95
  96 We define the two states of the switch:
  97 \list
  98 \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.
  99 \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.
 100 \endlist
 101
 102 For more information on states see \l{qmlstates}{QML States}.
 103
 104 \section2 Functions
 105
 106 We add two JavaScript functions to our switch:
 107
 108 \snippet examples/declarative/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 (\i on and \i off).
 112
 113
 114 \snippet examples/declarative/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 \i on nor \i off). If it is the case call the \c toggle() function otherwise we do nothing.
 118
 119 For more information on scripts see \l{Integrating JavaScript}.
 120
 121 \section2 Transition
 122 \snippet examples/declarative/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{QML Animation and Transitions}.
 128
 129 \section1 Usage
 130 The switch can be used in a QML file, like this:
 131 \snippet examples/declarative/ui-components/slideswitch/slideswitch.qml 0
 132 */