Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731

1 files changed, 131 insertions, 0 deletions

diff --git a/doc/charinput-qws.doc b/doc/charinput-qws.doc
new file mode 100644
index 00000000..96be08ec
--- /dev/null
+++ b/doc/charinput-qws.doc
@@ -0,0 +1,131 @@
+/****************************************************************************
+**
+** 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 retquirements 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.
+
+*/