You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
132 lines
5.0 KiB
132 lines
5.0 KiB
/****************************************************************************
|
|
**
|
|
** Documentation of character input
|
|
**
|
|
** Copyright (C) 2000-2008 Trolltech ASA. All rights reserved.
|
|
**
|
|
** This file is part of the Qt GUI Toolkit.
|
|
**
|
|
** This file may be used under the terms of the GNU General
|
|
** Public License versions 2.0 or 3.0 as published by the Free
|
|
** Software Foundation and appearing in the files LICENSE.GPL2
|
|
** and LICENSE.GPL3 included in the packaging of this file.
|
|
** Alternatively you may (at your option) use any later version
|
|
** of the GNU General Public License if such license has been
|
|
** publicly approved by Trolltech ASA (or its successors, if any)
|
|
** and the KDE Free Qt Foundation.
|
|
**
|
|
** Please review the following information to ensure GNU General
|
|
** Public Licensing requirements will be met:
|
|
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
|
|
** If you are unsure which license is appropriate for your use, please
|
|
** review the following information:
|
|
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
|
|
** or contact the sales department at sales@trolltech.com.
|
|
**
|
|
** This file may be used under the terms of the Q Public License as
|
|
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
|
|
** included in the packaging of this file. Licensees holding valid Qt
|
|
** Commercial licenses may use this file in accordance with the Qt
|
|
** Commercial License Agreement provided with the Software.
|
|
**
|
|
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
|
|
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
|
|
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
|
|
** herein.
|
|
**
|
|
**********************************************************************/
|
|
|
|
/*!
|
|
\page emb-charinput.html
|
|
|
|
\title Character input in Qt/Embedded
|
|
|
|
Internally in the client/server protocol, each key press and key
|
|
release is sent as a \c{QWSKeyEvent}. A QWSKeyEvent contains the
|
|
following fields:
|
|
|
|
\table
|
|
\row \i \c{unicode}
|
|
\i Unicode value
|
|
\row \i \c{keycode}
|
|
\i Qt keycode value as defined in \c qnamespace.h
|
|
\row \i \c{modifier}
|
|
\i A bitfield consisting of some of \c Qt::ShiftButton,
|
|
\c Qt::ControlButton, and \c Qt::AltButton.
|
|
\row \i \c{is_press}
|
|
\i TRUE if this is a key press, FALSE if it is a key release.
|
|
\row \i \c{is_auto_repeat}
|
|
\i TRUE if this event is caused by auto repeat.
|
|
\endtable
|
|
|
|
When the server receives a key event it is sent to each client process
|
|
which is responsible for processing the key event and sending it to
|
|
the right window, if any. Key events may come from several different
|
|
sources.
|
|
|
|
\section1 Keyboard drivers
|
|
|
|
A keyboard driver reads data from a device and gives key events to the
|
|
server.
|
|
|
|
Keyboard drivers can be compiled into the library or loaded as
|
|
plugins. Running ./configure -help lists the available keyboard drivers.
|
|
The "tty" driver is enabled in the default configuration.
|
|
|
|
The keyboard drivers all follow the same pattern. They read keyboard
|
|
data from a device, find out which keys were pressed, and then call
|
|
the static function QWSServer::processKeyEvent() with the key information.
|
|
|
|
At present, the console keyboard driver also handles console switching
|
|
(<b>Ctrl+Alt-F1</b>...<b>Ctrl+Alt+F10</b>) and termination
|
|
(<b>Ctrl+Alt+Backspace</b>).
|
|
|
|
To add a keyboard driver for a new device, subclasses of
|
|
\c{QWSKeyboardHandler} and \c{QKbdDriverPlugin} can be
|
|
written and installed as plugins.
|
|
|
|
\section1 Key event filters (input methods)
|
|
|
|
When the server receives a key event from a keyboard driver, it first
|
|
passes it through a filter.
|
|
|
|
This can be used to implement input methods, providing input of
|
|
characters that are not on the keyboard.
|
|
|
|
To make an input method, subclass QWSServer::KeyboardFilter (in \c
|
|
src/kernel/qwindowsystem_qws.h) and implement the virtual function \c
|
|
filter(). If \c filter() returns \c FALSE, the event will be sent to
|
|
the clients (using QWSServer::sendKeyEvent()). If \c filter() returns
|
|
\c TRUE, the event will be stopped. To generate new key events, use
|
|
QWSServer::sendKeyEvent(). (Do not use processKeyEvent(), since this
|
|
will lead to infinite recursion.)
|
|
|
|
To install a keyboard event filter, use
|
|
\c{QWSServer::setKeyboardFilter()}. Currently, only one filter
|
|
can be installed at a time.
|
|
|
|
Filtering must be done in the server process.
|
|
|
|
The launcher example contains an example of a simple input method,
|
|
\c{SimpleIM} which reads a substitution table from a file.
|
|
|
|
\section1 Pen input
|
|
|
|
Key events do not need to come from a keyboard device. The server
|
|
process may call QWSServer::sendKeyEvent() at any time.
|
|
|
|
Typically, this is done by popping up a widget, and letting the user
|
|
specify characters with the pointer device.
|
|
|
|
<b>Note</b>: the key input widget should not take focus, since the
|
|
server would then just send the key events back to the input widget.
|
|
One way to make sure that the input widget never takes focus is to set
|
|
the \c{WStyle_Customize} and \c{WStyle_Tool} widget flags in
|
|
the QWidget constructor.
|
|
|
|
The \link http://www.trolltech.com/products/qtopia/ Qtopia\endlink
|
|
environment contains various input widgets such as
|
|
Handwriting Recognition and Virtual Keyboard.
|
|
|
|
*/
|