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