source: trunk/doc/src/declarative/example-slideswitch.qdoc@ 980

Last change on this file since 980 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

File size: 5.0 KB
Line 
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
32This example shows how to create a reusable switch component in QML.
33
34The code for this example can be found in the \c $QTDIR/examples/declarative/ui-components/slideswitch directory.
35
36\section1 Overview
37
38The 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
57This property is the interface of the switch. By default, the switch is off and this property is \c false.
58It can be used to activate/disactivate the switch or to query its current state.
59
60In this example:
61
62\qml
63Switch { id: mySwitch; on: true }
64Text { text: "The switch is on"; visible: mySwitch.on == true }
65\endqml
66
67the 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
72First, we create the background image of the switch.
73In 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.
74A \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
79Then, we place the image of the knob on top of the background.
80The 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
81property of the \c MouseArea is for. We also want to toggle the switch if the knob is released between state. We handle this case
82in 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
87We 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
93For more information on states see \l{qmlstates}{QML States}.
94
95\section2 Functions
96
97We add two JavaScript functions to our switch:
98
99\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 2
100
101This first function is called when the background image or the knob are clicked. We simply want the switch to toggle between the two
102states (\e on and \e off).
103
104
105\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 3
106
107This 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
110For more information on scripts see \l{Integrating JavaScript}.
111
112\section2 Transition
113\snippet examples/declarative/ui-components/slideswitch/content/Switch.qml 7
114
115At this point, when the switch toggles between the two states the knob will instantly change its \c x position between 1 and 78.
116In 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
118For more information on transitions see \l{qdeclarativeanimation.html#transitions}{QML Transitions}.
119
120\section1 Usage
121The switch can be used in a QML file, like this:
122\snippet examples/declarative/ui-components/slideswitch/slideswitch.qml 0
123*/
Note: See TracBrowser for help on using the repository browser.