1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://qt.nokia.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example tools/inputpanel
\title Input Panel Example
The Input Panel example shows how to create an input panel that
can be used to input text into widgets using only the pointer and
no keyboard.
\image inputpanel-example.png
The input fields in the main window have no function other than
to accept input. The main focus is on how the extra input panel
can be used to input text without pressing any real physical
keys.
\section1 Main Form Class Definition
Because the main window has no other function than to accept
input, it has no class definition. Instead, its whole layout is
made in Qt Designer. This emphasizes the point that no widget
specific code is needed to use input panels with Qt.
\section1 Input Panel Context Class Definition
\snippet examples/tools/inputpanel/myinputpanelcontext.h 0
The \c MyInputPanelContext class inherits QInputContext, which is
Qt's base class for handling input methods.
\c MyInputPanelContext is responsible for managing the state of
the input panel, and sending input method events to the receiving
widgets.
The \c inputPanel member is a pointer to input panel widget
itself, in other words the window that will display the buttons
used for input.
The \c identifierName(), \c language(), \c isComposing() and
\c reset() functions are there mainly to fill in the pure virtual
functions in the base class, QInputContext, but they can be
useful in other scenarios. The important functions and slots are
the following:
\list
\o \c filterEvent() is where we receive events telling us to open
or close the input panel.
\o \c sendCharacter() is a slot which is called when we want to
send a character to the focused widget.
\o \c updatePosition() is used to position the input panel
relative to the focused widget, and will be used when opening
the input panel.
\endlist
\snippet examples/tools/inputpanel/myinputpanelcontext.cpp 1
In the constructor we connect to the \c characterGenerated()
signal of the input panel, in order to receive key presses. We'll
see how it works in detail later on.
\snippet examples/tools/inputpanel/myinputpanelcontext.cpp 1
In the \c filterEvent() function, we must look for the two event
types: \c RequestSoftwareInputPanel and
\c CloseSoftwareInputPanel. The first type will be sent whenever
an input capable widget wants to ask for an input panel. Qt's
input widgets do this automatically. If we receive that type of
event, we call \c updatePosition() (we'll see later on what it
does) and then show the actual input panel widget. If we receive
the \c CloseSoftwareInputPanel event, we do the opposite, and
hide the input panel.
\snippet examples/tools/inputpanel/myinputpanelcontext.cpp 2
We implement the \c sendCharacter() function so that it sends the
supplied character to the focused widget. All QInputContext based
classes are always supposed to send events to the widget returned
by QInputContext::focusWidget(). Note the QPointer guards to make
sure that the widget does not get destroyed in between events.
Also note that we chose to use key press events in this example.
For more complex use cases with composed text it might be more
appropriate to send QInputMethodEvent type of events.
\snippet examples/tools/inputpanel/myinputpanelcontext.cpp 3
The \c updatePosition() function is implemented to position the
actual input panel window directly below the focused widget, by
getting the coordinates of the focused widget and translating
them to global coordinates.
\section1 Input Panel Class Definition
\snippet examples/tools/inputpanel/myinputpanel.h 0
The \c MyInputPanel class inherits QWidget and is used to display
the input panel widget and its buttons.
If we look at the member variables first, we see that there is
\c form, which is made with Qt Designer. That contains the layout
of buttons to click. Note that all the buttons in the layout have
been declared with the \c NoFocus focus policy, so that we can
maintain focus on the window receiving input instead of the
window containing buttons. The \c lastFocusedWidget is a helper
variable, which also aids in maintaining focus.
\c signalMapper is an instance of the QSignalMapper class and is
there to help us tell which button was clicked. Since they are
all very similar this is a better solution since we don't have to
create a separate slot for each one.
The functions that we implement in \c MyInputPanel are the
following:
\list
\o \c event() is used to intercept and manipulate focus events,
so we can maintain focus in the main window.
\o \c saveFocusWidget() is a slot which will be called whenever
focus changes, and allows us to store the newly focused widget
into \c lastFocusedWidget, so that its focus can be restored
if it loses it to the input panel.
\o \c buttonClicked() is a slot which will be called by the
\c signalMapper whenever it receives a \c clicked() signal
any of the buttons.
\endlist
\snippet examples/tools/inputpanel/myinputpanel.cpp 0
If we look at the constructor first, we have a lot of signals to
connect to! We connect the QApplication::focusChanged() signal
to the \c saveFocusWidget() signal in order to get focus updates.
Then comes the interesting part with the signal mapper. The
series of \c setMapping() calls sets the mapper up so that each
signal from one of the buttons will result in a
QSignalMapper::mapped() signal, with the given widget as a
parameter. This allows us to do general processing of clicks. The
next series of connections then connect each button's
\c clicked() signal to the signal mapper. And finally, we create
a connection from the \c mapped() signal to the
\c buttonClicked() slot, where we will handle it.
\snippet examples/tools/inputpanel/myinputpanel.cpp 3
In the \c buttonClicked() slot, we extract the value of the
"buttonValue" property. This is a custom property which was
created in Qt Designer and set to the character that we wish the
button to produce. Then we emit the \c characterGenerated()
signal, which \c MyInputPanelContext is connected to. This will
in turn cause it to send the input to the focused widget.
\snippet examples/tools/inputpanel/myinputpanel.cpp 2
In the \c saveFocusWidget() slot, we test whether the newly
focused widget is a child of the input panel or not, using the
QWidget::isAncestorOf() call. If it isn't, it means that the
widget is outside the input panel, and we store a pointer to that
widget for later.
\snippet examples/tools/inputpanel/myinputpanel.cpp 1
In the \c event() function we handle QEvent::WindowActivate
event, which occurs if the focus switches to the input panel.
Since we want avoid focus on the input panel, we immediately call
QWidget::activateWindow() on the widget that last had focus, so
that input into that widget can continue.
*/
|
