source: trunk/doc/src/examples/lineedits.qdoc@ 523

Last change on this file since 523 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 7.2 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information (qt-info@nokia.com)
5**
6** This file is part of the documentation of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at qt-sales@nokia.com.
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \example widgets/lineedits
44 \title Line Edits Example
45
46 The Line Edits example demonstrates the many ways that QLineEdit can be used, and
47 shows the effects of various properties and validators on the input and output
48 supplied by the user.
49
50 \image lineedits-example.png
51
52 The example consists of a single \c Window class, containing a selection of
53 line edits with different input constraints and display properties that can be
54 changed by selecting items from comboboxes. Presenting these together helps
55 developers choose suitable properties to use with line edits, and makes it easy
56 to compare the effects of each validator on user input.
57
58 \section1 Window Class Definition
59
60 The \c Window class inherits QWidget and contains a constructor and several
61 slots:
62
63 \snippet examples/widgets/lineedits/window.h 0
64
65 The slots are used to update the type of validator used for a given line edit when
66 a new validator has been selected in the associated combobox. The line edits
67 are stored in the window for use in these slots.
68
69 \section1 Window Class Implementation
70
71 The \c Window constructor is used to set up the line edits, validators,
72 and comboboxes, connect signals from the comboboxes to slots in the \c Window
73 class, and arrange the child widgets in layouts.
74
75 We begin by constructing a \l{QGroupBox}{group box} to hold a label, combobox,
76 and line edit so that we can demonstrate the QLineEdit::echoMode property:
77
78 \snippet examples/widgets/lineedits/window.cpp 0
79
80 At this point, none of these widgets have been arranged in layouts. Eventually,
81 the \c echoLabel, \c echoComboBox, and \c echoLineEdit will be placed in a
82 vertical layout inside the \c echoGroup group box.
83
84 Similarly, we construct group boxes and collections of widgets to show the
85 effects of QIntValidator and QDoubleValidator on a line edit's contents:
86
87 \snippet examples/widgets/lineedits/window.cpp 1
88
89 Text alignment is demonstrated by another group of widgets:
90
91 \snippet examples/widgets/lineedits/window.cpp 2
92
93 QLineEdit supports the use of \l{QLineEdit::inputMask}{input masks}.
94 These only allow the user to type characters into the line edit that
95 follow a simple specification. We construct a group of widgets to
96 demonstrate a selection of predefined masks:
97
98 \snippet examples/widgets/lineedits/window.cpp 3
99
100 Another useful feature of QLineEdit is its ability to make its contents
101 read-only. This property is used to control access to a line edit in the
102 following group of widgets:
103
104 \snippet examples/widgets/lineedits/window.cpp 4
105
106 Now that all the child widgets have been constructed, we connect signals
107 from the comboboxes to slots in the \c Window object:
108
109 \snippet examples/widgets/lineedits/window.cpp 5
110
111 Each of these connections use the QComboBox::activated() signal that
112 supplies an integer to the slot. This will be used to efficiently
113 make changes to the appropriate line edit in each slot.
114
115 We place each combobox, line edit, and label in a layout for each group
116 box, beginning with the layout for the \c echoGroup group box:
117
118 \snippet examples/widgets/lineedits/window.cpp 6
119
120 The other layouts are constructed in the same way:
121
122 \snippet examples/widgets/lineedits/window.cpp 7
123
124 Finally, we place each group box in a grid layout for the \c Window object
125 and set the window title:
126
127 \snippet examples/widgets/lineedits/window.cpp 8
128
129 The slots respond to signals emitted when the comboboxes are changed by the
130 user.
131
132 When the combobox for the \gui{Echo} group box is changed, the \c echoChanged()
133 slot is called:
134
135 \snippet examples/widgets/lineedits/window.cpp 9
136
137 The slot updates the line edit in the same group box to use an echo mode that
138 corresponds to the entry described in the combobox.
139
140 When the combobox for the \gui{Validator} group box is changed, the
141 \c validatorChanged() slot is called:
142
143 \snippet examples/widgets/lineedits/window.cpp 10
144
145 The slot either creates a new validator for the line edit to use, or it removes
146 the validator in use by calling QLineEdit::setValidator() with a zero pointer.
147 We clear the line edit in this case to ensure that the new validator is
148 initially given valid input to work with.
149
150 When the combobox for the \gui{Alignment} group box is changed, the
151 \c alignmentChanged() slot is called:
152
153 \snippet examples/widgets/lineedits/window.cpp 11
154
155 This changes the way that text is displayed in the line edit to correspond with
156 the description selected in the combobox.
157
158 The \c inputMaskChanged() slot handles changes to the combobox in the
159 \gui{Input Mask} group box:
160
161 \snippet examples/widgets/lineedits/window.cpp 12
162
163 Each entry in the relevant combobox is associated with an input mask. We set
164 a new mask by calling the QLineEdit::setMask() function with a suitable string;
165 the mask is disabled if an empty string is used.
166
167 The \c accessChanged() slot handles changes to the combobox in the
168 \gui{Access} group box:
169
170 \snippet examples/widgets/lineedits/window.cpp 13
171
172 Here, we simply associate the \gui{False} and \gui{True} entries in the combobox
173 with \c false and \c true values to be passed to QLineEdit::setReadOnly(). This
174 allows the user to enable and disable input to the line edit.
175*/
Note: See TracBrowser for help on using the repository browser.