/****************************************************************************+
−
**+
−
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).+
−
** All rights reserved.+
−
** 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 Technology Preview License Agreement accompanying+
−
** this package.+
−
**+
−
** 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.1, included in the file LGPL_EXCEPTION.txt in this package.+
−
**+
−
** If you have questions regarding the use of this file, please contact+
−
** Nokia at qt-info@nokia.com.+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
**+
−
** $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.+
−
*/+
−