From b1015e8d7ac12d365c4b738fbee4ce12ecbaa58e Mon Sep 17 00:00:00 2001 From: axis Date: Fri, 17 Apr 2009 17:11:44 +0200 Subject: Added an example documenting how to make a software input panel. RevBy: David Boddie David's fixes are in the next two commits. --- doc/src/examples/inputpanel.qdoc | 205 +++++++++++ doc/src/images/inputpanel-example.png | Bin 0 -> 7899 bytes examples/tools/inputpanel/inputpanel.pro | 9 + examples/tools/inputpanel/main.cpp | 59 ++++ examples/tools/inputpanel/mainform.ui | 76 +++++ examples/tools/inputpanel/myinputpanel.cpp | 134 ++++++++ examples/tools/inputpanel/myinputpanel.h | 77 +++++ examples/tools/inputpanel/myinputpanelcontext.cpp | 132 +++++++ examples/tools/inputpanel/myinputpanelcontext.h | 82 +++++ examples/tools/inputpanel/myinputpanelform.ui | 398 ++++++++++++++++++++++ 10 files changed, 1172 insertions(+) create mode 100644 doc/src/examples/inputpanel.qdoc create mode 100644 doc/src/images/inputpanel-example.png create mode 100644 examples/tools/inputpanel/inputpanel.pro create mode 100644 examples/tools/inputpanel/main.cpp create mode 100644 examples/tools/inputpanel/mainform.ui create mode 100644 examples/tools/inputpanel/myinputpanel.cpp create mode 100644 examples/tools/inputpanel/myinputpanel.h create mode 100644 examples/tools/inputpanel/myinputpanelcontext.cpp create mode 100644 examples/tools/inputpanel/myinputpanelcontext.h create mode 100644 examples/tools/inputpanel/myinputpanelform.ui 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 Binary files /dev/null and b/doc/src/images/inputpanel-example.png differ diff --git a/examples/tools/inputpanel/inputpanel.pro b/examples/tools/inputpanel/inputpanel.pro new file mode 100644 index 0000000..683808b --- /dev/null +++ b/examples/tools/inputpanel/inputpanel.pro @@ -0,0 +1,9 @@ +SOURCES += main.cpp \ + myinputpanel.cpp \ + myinputpanelcontext.cpp + +HEADERS += myinputpanel.h \ + myinputpanelcontext.h + +FORMS += mainform.ui \ + myinputpanelform.ui diff --git a/examples/tools/inputpanel/main.cpp b/examples/tools/inputpanel/main.cpp new file mode 100644 index 0000000..03831c9 --- /dev/null +++ b/examples/tools/inputpanel/main.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** 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 +#include + +#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(); +} 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 @@ + + + MainForm + + + + 0 + 0 + 140 + 200 + + + + Input Panel Example + + + + + + My age: + + + Qt::AlignBottom|Qt::AlignLeading|Qt::AlignLeft + + + lineEdit + + + + + + + + + + My phone number: + + + Qt::AlignBottom|Qt::AlignLeading|Qt::AlignLeft + + + lineEdit_2 + + + + + + + + + + My gender: + + + + + + Male + + + + + + + Female + + + + + + + + + + + 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(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 +#include + +#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 + +#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 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 + +#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 @@ + + + MyInputPanelForm + + + + 0 + 0 + 167 + 233 + + + + Input Panel + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + 1 + + + + 49 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + 2 + + + + 50 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + 3 + + + + 51 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + 4 + + + + 52 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + 5 + + + + 53 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + 6 + + + + 54 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + 7 + + + + 55 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + 8 + + + + 56 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + 9 + + + + 57 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + * + + + + 42 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + 0 + + + + 48 + + + + + + + + + 0 + 0 + + + + + 45 + 40 + + + + Qt::NoFocus + + + # + + + + 35 + + + + + + + + + + + + Qt::Horizontal + + + + 40 + 20 + + + + + + + + + 8 + + + + Qt::NoFocus + + + Close + + + + + + + + + + + closeButton + clicked() + MyInputPanelForm + hide() + + + 114 + 209 + + + 83 + 116 + + + + + -- cgit v0.12 From 6842d3385e98e9af33ee079b31ca26f12a2087d9 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Wed, 26 Aug 2009 19:44:15 +0200 Subject: Doc: First review of the input panel example. --- doc/src/examples/inputpanel.qdoc | 115 ++++++++++++++++++++++------------ examples/tools/inputpanel/main.cpp | 5 +- src/gui/inputmethod/qinputcontext.cpp | 17 ++--- 3 files changed, 87 insertions(+), 50 deletions(-) diff --git a/doc/src/examples/inputpanel.qdoc b/doc/src/examples/inputpanel.qdoc index 61fe9ca..9a4d7f9 100644 --- a/doc/src/examples/inputpanel.qdoc +++ b/doc/src/examples/inputpanel.qdoc @@ -51,8 +51,8 @@ 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. + can be used to input text without the need for a real keyboard or + keypad. \section1 Main Form Class Definition @@ -61,18 +61,18 @@ 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 + \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 + 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 + itself; in other words, the window that will display the buttons used for input. The \c identifierName(), \c language(), \c isComposing() and @@ -91,21 +91,24 @@ the input panel. \endlist - \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 1 + \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 1 + \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. The first type will be sent whenever + 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() (we'll see later on what it - does) and then show the actual input panel widget. If we receive + 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. @@ -119,33 +122,37 @@ 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 + appropriate to send QInputMethodEvent events. 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. + actual input panel window directly below the focused widget. - \section1 Input Panel Class Definition + \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 3 - \snippet examples/tools/inputpanel/myinputpanel.h 0 + 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 + \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 + 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. + 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. + 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: @@ -155,25 +162,30 @@ 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 + 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 - any of the buttons. + from any of the buttons. \endlist - \snippet examples/tools/inputpanel/myinputpanel.cpp 0 + \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 + 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 + 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 + 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. @@ -186,20 +198,41 @@ 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. + QWidget::isAncestorOf() call. - \snippet examples/tools/inputpanel/myinputpanel.cpp 1 + \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 0 + 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. -*/ + 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 shows 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/examples/tools/inputpanel/main.cpp b/examples/tools/inputpanel/main.cpp index 03831c9..2e39883 100644 --- a/examples/tools/inputpanel/main.cpp +++ b/examples/tools/inputpanel/main.cpp @@ -42,10 +42,12 @@ #include #include +//! [main] #include "myinputpanelcontext.h" #include "ui_mainform.h" -int main(int argc, char **argv) { +int main(int argc, char **argv) +{ QApplication app(argc, argv); MyInputPanelContext *ic = new MyInputPanelContext; @@ -57,3 +59,4 @@ int main(int argc, char **argv) { widget.show(); return app.exec(); } +//! [main] diff --git a/src/gui/inputmethod/qinputcontext.cpp b/src/gui/inputmethod/qinputcontext.cpp index 35f1b65..393a3f4 100644 --- a/src/gui/inputmethod/qinputcontext.cpp +++ b/src/gui/inputmethod/qinputcontext.cpp @@ -154,16 +154,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 { @@ -173,9 +174,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() -- cgit v0.12 From 397cbd5c9c0afee65258ff91bc6ca29c548c85cd Mon Sep 17 00:00:00 2001 From: David Boddie Date: Wed, 26 Aug 2009 19:46:46 +0200 Subject: Doc: Updated project files and Qt Demo XML to include the example. --- demos/qtdemo/xml/examples.xml | 1 + examples/tools/inputpanel/inputpanel.pro | 8 ++++++++ examples/tools/tools.pro | 1 + 3 files changed, 10 insertions(+) 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 @@ + diff --git a/examples/tools/inputpanel/inputpanel.pro b/examples/tools/inputpanel/inputpanel.pro index 683808b..3b3767f 100644 --- a/examples/tools/inputpanel/inputpanel.pro +++ b/examples/tools/inputpanel/inputpanel.pro @@ -7,3 +7,11 @@ HEADERS += myinputpanel.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/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 \ -- cgit v0.12 From 813b040339b965ce31a0e7115fdee50d1d9e7ffd Mon Sep 17 00:00:00 2001 From: axis Date: Fri, 28 Aug 2009 09:01:09 +0200 Subject: Corrected a few spelling mistakes and a misplaced code section. RevBy: Trust me --- doc/src/examples/inputpanel.qdoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/src/examples/inputpanel.qdoc b/doc/src/examples/inputpanel.qdoc index 9a4d7f9..06c19ba 100644 --- a/doc/src/examples/inputpanel.qdoc +++ b/doc/src/examples/inputpanel.qdoc @@ -71,7 +71,7 @@ the input panel and sending input method events to the receiving widgets. - The \c inputPanel member is a pointer to input panel widget + 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. @@ -210,7 +210,7 @@ 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 0 + \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 @@ -226,7 +226,7 @@ \snippet examples/tools/inputpanel/main.cpp main - With the input context in place, we set up and shows the user interface + 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 -- cgit v0.12