Merge branch 'inputPanelExample' into 4.6

13 files changed, 1227 insertions, 8 deletions

diff --git a/demos/qtdemo/xml/examples.xml b/demos/qtdemo/xml/examples.xml
index 6c8ddb0..f598780 100644
--- a/demos/qtdemo/xml/examples.xml
+++ b/demos/qtdemo/xml/examples.xml
@@ -196,6 +196,7 @@
     <example filename="completer" name="Completer" />
     <example filename="customcompleter" name="Custom Completer" />
     <example filename="i18n" name="Internationalization" />
+    <example filename="inputpanel" name="Input Panel" />
     <example filename="plugandpaint" name="Plug and Paint" />
     <example filename="regexp" name="Regular Expressions" />
     <example filename="settingseditor" name="Settings Editor" />
diff --git a/doc/src/examples/inputpanel.qdoc b/doc/src/examples/inputpanel.qdoc
new file mode 100644
index 0000000..06c19ba
--- /dev/null
+++ b/doc/src/examples/inputpanel.qdoc
@@ -0,0 +1,238 @@
+/****************************************************************************
+**
+** 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 the need for a real keyboard or
+    keypad.
+
+    \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 MyInputPanelContext 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 the 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
+
+    \section1 MyInputPanelContext Class Implementation
+
+    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 0
+
+    In the \c filterEvent() function, we must look for the two event
+    types: \c RequestSoftwareInputPanel and \c CloseSoftwareInputPanel.
+
+    \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 1
+
+    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() \mdash we'll see later on what it
+    does \mdash 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 events.
+
+    The \c updatePosition() function is implemented to position the
+    actual input panel window directly below the focused widget.
+
+    \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 3
+
+    It performs the positioning by obtaining the coordinates of the
+    focused widget and translating them to global coordinates.
+
+    \section1 MyInputPanel Class Definition
+
+    The \c MyInputPanel class inherits QWidget and is used to display
+    the input panel widget and its buttons.
+
+    \snippet examples/tools/inputpanel/myinputpanel.h 0
+
+    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 than creating 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
+       in \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
+       from any of the buttons.
+    \endlist
+
+    \section1 MyInputPanel Class Implementation
+
+    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.
+
+    \snippet examples/tools/inputpanel/myinputpanel.cpp 0
+
+    The next series of connections then connect each button's
+    \c clicked() signal to the signal mapper. 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.
+
+    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.
+
+    \snippet examples/tools/inputpanel/myinputpanel.cpp 2
+
+    If it isn't, it means that the widget is outside the input panel,
+    and we store a pointer to that widget for later.
+
+    In the \c event() function we handle QEvent::WindowActivate
+    event, which occurs if the focus switches to the input panel.
+
+    \snippet examples/tools/inputpanel/myinputpanel.cpp 1
+
+    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. We ignore any other events
+    that we receive.
+
+    \section1 Setting the Input Context
+
+    The main function for the example is very similar to those for other
+    examples. The only real difference is that it creates a
+    \c MyInputPanelContext and sets it as the application-wide input
+    context.
+
+    \snippet examples/tools/inputpanel/main.cpp main
+
+    With the input context in place, we set up and show the user interface
+    made in Qt Designer before running the event loop.
+
+    \section1 Further Reading
+
+    This example shows a specific kind of input context that uses interaction
+    with a widget to provide input for another. Qt's input context system can
+    also be used to create other kinds of input methods. We recommend starting
+    with the QInputContext documentation if you want to explore further.
+*/
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
diff --git a/examples/tools/inputpanel/inputpanel.pro b/examples/tools/inputpanel/inputpanel.pro
new file mode 100644
index 0000000..3b3767f
--- /dev/null
+++ b/examples/tools/inputpanel/inputpanel.pro
@@ -0,0 +1,17 @@
+SOURCES += main.cpp \
+           myinputpanel.cpp \
+           myinputpanelcontext.cpp
+
+HEADERS += myinputpanel.h \
+           myinputpanelcontext.h
+
+FORMS   += mainform.ui \
+           myinputpanelform.ui
+
+# install
+target.path = $$[QT_INSTALL_EXAMPLES]/tools/inputpanel
+sources.files = $$SOURCES $$HEADERS $$RESOURCES $$FORMS inputpanel.pro
+sources.path = $$[QT_INSTALL_EXAMPLES]/tools/inputpanel
+INSTALLS += target sources
+
+symbian: include($$QT_SOURCE_TREE/examples/symbianpkgrules.pri)
diff --git a/examples/tools/inputpanel/main.cpp b/examples/tools/inputpanel/main.cpp
new file mode 100644
index 0000000..2e39883
--- /dev/null
+++ b/examples/tools/inputpanel/main.cpp
@@ -0,0 +1,62 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the examples 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$
+**
+****************************************************************************/
+
+#include <QtGui/QApplication>
+#include <QtGui/QWidget>
+
+//! [main]
+#include "myinputpanelcontext.h"
+#include "ui_mainform.h"
+
+int main(int argc, char **argv)
+{
+    QApplication app(argc, argv);
+
+    MyInputPanelContext *ic = new MyInputPanelContext;
+    app.setInputContext(ic);
+
+    QWidget widget;
+    Ui::MainForm form;
+    form.setupUi(&widget);
+    widget.show();
+    return app.exec();
+}
+//! [main]
diff --git a/examples/tools/inputpanel/mainform.ui b/examples/tools/inputpanel/mainform.ui
new file mode 100644
index 0000000..c16ae31
--- /dev/null
+++ b/examples/tools/inputpanel/mainform.ui
@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ui version="4.0">
+ <class>MainForm</class>
+ <widget class="QWidget" name="MainForm">
+  <property name="geometry">
+   <rect>
+    <x>0</x>
+    <y>0</y>
+    <width>140</width>
+    <height>200</height>
+   </rect>
+  </property>
+  <property name="windowTitle">
+   <string>Input Panel Example</string>
+  </property>
+  <layout class="QVBoxLayout" name="verticalLayout_2">
+   <item>
+    <widget class="QLabel" name="label">
+     <property name="text">
+      <string>My age:</string>
+     </property>
+     <property name="alignment">
+      <set>Qt::AlignBottom|Qt::AlignLeading|Qt::AlignLeft</set>
+     </property>
+     <property name="buddy">
+      <cstring>lineEdit</cstring>
+     </property>
+    </widget>
+   </item>
+   <item>
+    <widget class="QLineEdit" name="lineEdit"/>
+   </item>
+   <item>
+    <widget class="QLabel" name="label_2">
+     <property name="text">
+      <string>My phone number:</string>
+     </property>
+     <property name="alignment">
+      <set>Qt::AlignBottom|Qt::AlignLeading|Qt::AlignLeft</set>
+     </property>
+     <property name="buddy">
+      <cstring>lineEdit_2</cstring>
+     </property>
+    </widget>
+   </item>
+   <item>
+    <widget class="QLineEdit" name="lineEdit_2"/>
+   </item>
+   <item>
+    <widget class="QGroupBox" name="groupBox">
+     <property name="title">
+      <string>My gender:</string>
+     </property>
+     <layout class="QVBoxLayout" name="verticalLayout">
+      <item>
+       <widget class="QRadioButton" name="radioButton">
+        <property name="text">
+         <string>Male</string>
+        </property>
+       </widget>
+      </item>
+      <item>
+       <widget class="QRadioButton" name="radioButton_2">
+        <property name="text">
+         <string>Female</string>
+        </property>
+       </widget>
+      </item>
+     </layout>
+    </widget>
+   </item>
+  </layout>
+ </widget>
+ <resources/>
+ <connections/>
+</ui>
diff --git a/examples/tools/inputpanel/myinputpanel.cpp b/examples/tools/inputpanel/myinputpanel.cpp
new file mode 100644
index 0000000..c44ead8
--- /dev/null
+++ b/examples/tools/inputpanel/myinputpanel.cpp
@@ -0,0 +1,134 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the examples 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$
+**
+****************************************************************************/
+
+#include "myinputpanel.h"
+
+//! [0]
+
+MyInputPanel::MyInputPanel()
+    : QWidget(0, Qt::Tool | Qt::WindowStaysOnTopHint),
+      lastFocusedWidget(0)
+{
+    form.setupUi(this);
+
+    connect(qApp, SIGNAL(focusChanged(QWidget *, QWidget *)),
+            this, SLOT(saveFocusWidget(QWidget *, QWidget *)));
+
+    signalMapper.setMapping(form.panelButton_1, form.panelButton_1);
+    signalMapper.setMapping(form.panelButton_2, form.panelButton_2);
+    signalMapper.setMapping(form.panelButton_3, form.panelButton_3);
+    signalMapper.setMapping(form.panelButton_4, form.panelButton_4);
+    signalMapper.setMapping(form.panelButton_5, form.panelButton_5);
+    signalMapper.setMapping(form.panelButton_6, form.panelButton_6);
+    signalMapper.setMapping(form.panelButton_7, form.panelButton_7);
+    signalMapper.setMapping(form.panelButton_8, form.panelButton_8);
+    signalMapper.setMapping(form.panelButton_9, form.panelButton_9);
+    signalMapper.setMapping(form.panelButton_star, form.panelButton_star);
+    signalMapper.setMapping(form.panelButton_0, form.panelButton_0);
+    signalMapper.setMapping(form.panelButton_hash, form.panelButton_hash);
+
+    connect(form.panelButton_1, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_2, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_3, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_4, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_5, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_6, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_7, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_8, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_9, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_star, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_0, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+    connect(form.panelButton_hash, SIGNAL(clicked()),
+            &signalMapper, SLOT(map()));
+
+    connect(&signalMapper, SIGNAL(mapped(QWidget *)),
+            this, SLOT(buttonClicked(QWidget *)));
+}
+
+//! [0]
+
+bool MyInputPanel::event(QEvent *e)
+{
+    switch (e->type()) {
+//! [1]
+    case QEvent::WindowActivate:
+        if (lastFocusedWidget)
+            lastFocusedWidget->activateWindow();
+        break;
+//! [1]
+    default:
+        break;
+    }
+
+    return QWidget::event(e);
+}
+
+//! [2]
+
+void MyInputPanel::saveFocusWidget(QWidget * /*oldFocus*/, QWidget *newFocus)
+{
+    if (newFocus != 0 && !this->isAncestorOf(newFocus)) {
+        lastFocusedWidget = newFocus;
+    }
+}
+
+//! [2]
+
+//! [3]
+
+void MyInputPanel::buttonClicked(QWidget *w)
+{
+    QChar chr = qvariant_cast<QChar>(w->property("buttonValue"));
+    emit characterGenerated(chr);
+}
+
+//! [3]
diff --git a/examples/tools/inputpanel/myinputpanel.h b/examples/tools/inputpanel/myinputpanel.h
new file mode 100644
index 0000000..5f91c05
--- /dev/null
+++ b/examples/tools/inputpanel/myinputpanel.h
@@ -0,0 +1,77 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the examples 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$
+**
+****************************************************************************/
+
+#ifndef MYINPUTPANEL_H
+#define MYINPUTPANEL_H
+
+#include <QtGui>
+#include <QtCore>
+
+#include "ui_myinputpanelform.h"
+
+//! [0]
+
+class MyInputPanel : public QWidget
+{
+    Q_OBJECT
+
+public:
+    MyInputPanel();
+
+signals:
+    void characterGenerated(QChar character);
+
+protected:
+    bool event(QEvent *e);
+
+private slots:
+    void saveFocusWidget(QWidget *oldFocus, QWidget *newFocus);
+    void buttonClicked(QWidget *w);
+
+private:
+    Ui::MyInputPanelForm form;
+    QWidget *lastFocusedWidget;
+    QSignalMapper signalMapper;
+};
+
+//! [0]
+
+#endif // MYINPUTPANEL_H
diff --git a/examples/tools/inputpanel/myinputpanelcontext.cpp b/examples/tools/inputpanel/myinputpanelcontext.cpp
new file mode 100644
index 0000000..dc31028
--- /dev/null
+++ b/examples/tools/inputpanel/myinputpanelcontext.cpp
@@ -0,0 +1,132 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the examples 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$
+**
+****************************************************************************/
+
+#include <QtCore>
+
+#include "myinputpanelcontext.h"
+
+//! [0]
+
+MyInputPanelContext::MyInputPanelContext()
+{
+    inputPanel = new MyInputPanel;
+    connect(inputPanel, SIGNAL(characterGenerated(QChar)), SLOT(sendCharacter(QChar)));
+}
+
+//! [0]
+
+MyInputPanelContext::~MyInputPanelContext()
+{
+    delete inputPanel;
+}
+
+//! [1]
+
+bool MyInputPanelContext::filterEvent(const QEvent* event)
+{
+    if (event->type() == QEvent::RequestSoftwareInputPanel) {
+        updatePosition();
+        inputPanel->show();
+        return true;
+    } else if (event->type() == QEvent::CloseSoftwareInputPanel) {
+        inputPanel->hide();
+        return true;
+    }
+    return false;
+}
+
+//! [1]
+
+QString MyInputPanelContext::identifierName()
+{
+    return "MyInputPanelContext";
+}
+
+void MyInputPanelContext::reset()
+{
+}
+
+bool MyInputPanelContext::isComposing() const
+{
+    return false;
+}
+
+QString MyInputPanelContext::language()
+{
+    return "en_US";
+}
+
+//! [2]
+
+void MyInputPanelContext::sendCharacter(QChar character)
+{
+    QPointer<QWidget> w = focusWidget();
+
+    if (!w)
+        return;
+
+    QKeyEvent keyPress(QEvent::KeyPress, character.unicode(), Qt::NoModifier, QString(character));
+    QApplication::sendEvent(w, &keyPress);
+
+    if (!w)
+        return;
+
+    QKeyEvent keyRelease(QEvent::KeyPress, character.unicode(), Qt::NoModifier, QString());
+    QApplication::sendEvent(w, &keyRelease);
+}
+
+//! [2]
+
+//! [3]
+
+void MyInputPanelContext::updatePosition()
+{
+    QWidget *widget = focusWidget();
+    if (!widget)
+        return;
+
+    QRect widgetRect = widget->rect();
+    QPoint panelPos = QPoint(widgetRect.left(), widgetRect.bottom() + 2);
+    panelPos = widget->mapToGlobal(panelPos);
+    inputPanel->move(panelPos);
+}
+
+//! [3]
diff --git a/examples/tools/inputpanel/myinputpanelcontext.h b/examples/tools/inputpanel/myinputpanelcontext.h
new file mode 100644
index 0000000..d711800
--- /dev/null
+++ b/examples/tools/inputpanel/myinputpanelcontext.h
@@ -0,0 +1,82 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the examples 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$
+**
+****************************************************************************/
+
+#ifndef MYINPUTPANELCONTEXT_H
+#define MYINPUTPANELCONTEXT_H
+
+#include <QtGui/QInputContext>
+
+#include "myinputpanel.h"
+
+class MyInputPanel;
+
+//! [0]
+
+class MyInputPanelContext : public QInputContext
+{
+    Q_OBJECT
+
+public:
+    MyInputPanelContext();
+    ~MyInputPanelContext();
+
+    bool filterEvent(const QEvent* event);
+
+    QString identifierName();
+    QString language();
+
+    bool isComposing() const;
+
+    void reset();
+
+private slots:
+    void sendCharacter(QChar character);
+
+private:
+    void updatePosition();
+
+private:
+    MyInputPanel *inputPanel;
+};
+
+//! [0]
+
+#endif // MYINPUTPANELCONTEXT_H
diff --git a/examples/tools/inputpanel/myinputpanelform.ui b/examples/tools/inputpanel/myinputpanelform.ui
new file mode 100644
index 0000000..fe78442
--- /dev/null
+++ b/examples/tools/inputpanel/myinputpanelform.ui
@@ -0,0 +1,398 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ui version="4.0">
+ <class>MyInputPanelForm</class>
+ <widget class="QWidget" name="MyInputPanelForm">
+  <property name="geometry">
+   <rect>
+    <x>0</x>
+    <y>0</y>
+    <width>167</width>
+    <height>233</height>
+   </rect>
+  </property>
+  <property name="windowTitle">
+   <string>Input Panel</string>
+  </property>
+  <layout class="QVBoxLayout" name="verticalLayout">
+   <item>
+    <layout class="QGridLayout" name="gridLayout">
+     <item row="0" column="0">
+      <widget class="QPushButton" name="panelButton_1">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>1</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>49</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="0" column="1">
+      <widget class="QPushButton" name="panelButton_2">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>2</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>50</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="0" column="2">
+      <widget class="QPushButton" name="panelButton_3">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>3</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>51</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="1" column="0">
+      <widget class="QPushButton" name="panelButton_4">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>4</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>52</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="1" column="1">
+      <widget class="QPushButton" name="panelButton_5">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>5</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>53</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="1" column="2">
+      <widget class="QPushButton" name="panelButton_6">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>6</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>54</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="2" column="0">
+      <widget class="QPushButton" name="panelButton_7">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>7</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>55</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="2" column="1">
+      <widget class="QPushButton" name="panelButton_8">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>8</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>56</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="2" column="2">
+      <widget class="QPushButton" name="panelButton_9">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>9</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>57</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="3" column="0">
+      <widget class="QPushButton" name="panelButton_star">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>*</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>42</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="3" column="1">
+      <widget class="QPushButton" name="panelButton_0">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>0</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>48</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+     <item row="3" column="2">
+      <widget class="QPushButton" name="panelButton_hash">
+       <property name="sizePolicy">
+        <sizepolicy hsizetype="Minimum" vsizetype="Minimum">
+         <horstretch>0</horstretch>
+         <verstretch>0</verstretch>
+        </sizepolicy>
+       </property>
+       <property name="minimumSize">
+        <size>
+         <width>45</width>
+         <height>40</height>
+        </size>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>#</string>
+       </property>
+       <property name="buttonValue" stdset="0">
+        <char>
+         <unicode>35</unicode>
+        </char>
+       </property>
+      </widget>
+     </item>
+    </layout>
+   </item>
+   <item>
+    <layout class="QHBoxLayout" name="horizontalLayout">
+     <item>
+      <spacer name="horizontalSpacer">
+       <property name="orientation">
+        <enum>Qt::Horizontal</enum>
+       </property>
+       <property name="sizeHint" stdset="0">
+        <size>
+         <width>40</width>
+         <height>20</height>
+        </size>
+       </property>
+      </spacer>
+     </item>
+     <item>
+      <widget class="QPushButton" name="closeButton">
+       <property name="font">
+        <font>
+         <pointsize>8</pointsize>
+        </font>
+       </property>
+       <property name="focusPolicy">
+        <enum>Qt::NoFocus</enum>
+       </property>
+       <property name="text">
+        <string>Close</string>
+       </property>
+      </widget>
+     </item>
+    </layout>
+   </item>
+  </layout>
+ </widget>
+ <resources/>
+ <connections>
+  <connection>
+   <sender>closeButton</sender>
+   <signal>clicked()</signal>
+   <receiver>MyInputPanelForm</receiver>
+   <slot>hide()</slot>
+   <hints>
+    <hint type="sourcelabel">
+     <x>114</x>
+     <y>209</y>
+    </hint>
+    <hint type="destinationlabel">
+     <x>83</x>
+     <y>116</y>
+    </hint>
+   </hints>
+  </connection>
+ </connections>
+</ui>
diff --git a/examples/tools/tools.pro b/examples/tools/tools.pro
index 1fd71c0..08d44e3 100644
--- a/examples/tools/tools.pro
+++ b/examples/tools/tools.pro
@@ -5,6 +5,7 @@ SUBDIRS       = codecs \
                 customcompleter \
                 echoplugin \
                 i18n \
+                inputpanel \
                 contiguouscache \
                 plugandpaintplugins \
                 plugandpaint \
diff --git a/src/gui/inputmethod/qinputcontext.cpp b/src/gui/inputmethod/qinputcontext.cpp
index 27888ac..992bc78 100644
--- a/src/gui/inputmethod/qinputcontext.cpp
+++ b/src/gui/inputmethod/qinputcontext.cpp
@@ -156,16 +156,17 @@ QInputContext::~QInputContext()
 }
 
 /*!
-    \internal
     Returns the widget that has an input focus for this input
-    context. Ordinary input methods should not call this function
-    directly to keep platform independence and flexible configuration
-    possibility.
+    context.
 
     The return value may differ from holderWidget() if the input
     context is shared between several text widgets.
 
-    \sa setFocusWidget(), holderWidget()
+    \warning To ensure platform independence and support flexible
+    configuration of widgets, ordinary input methods should not call
+    this function directly.
+
+    \sa setFocusWidget()
 */
 QWidget *QInputContext::focusWidget() const
 {
@@ -175,9 +176,9 @@ QWidget *QInputContext::focusWidget() const
 
 
 /*!
-    \internal
-    Sets the widget that has an input focus for this input
-    context. Ordinary input methods must not call this function
+    Sets the widget that has an input focus for this input context.
+
+    \warning Ordinary input methods must not call this function
     directly.
 
     \sa focusWidget()