source: trunk/doc/src/examples/inputpanel.qdoc@ 1168

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $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