--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/inputpanel.qdoc Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,238 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 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.
+*/