Added an example documenting how to make a software input panel.

RevBy:    David Boddie

David's fixes are in the next two commits.

2 files changed, 205 insertions, 0 deletions

diff --git a/doc/src/examples/inputpanel.qdoc b/doc/src/examples/inputpanel.qdoc
new file mode 100644
index 0000000..61fe9ca
--- /dev/null
+++ b/doc/src/examples/inputpanel.qdoc
@@ -0,0 +1,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.
+*/
+
diff --git a/doc/src/images/inputpanel-example.png b/doc/src/images/inputpanel-example.png
new file mode 100644
index 0000000..0dd9325
--- /dev/null
+++ b/doc/src/images/inputpanel-example.png