src/gui/kernel/qplatforminputcontext.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtGui module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qplatforminputcontext.h"
  43 #include <qguiapplication.h>
  44 #include <QRect>
  45 #include "private/qkeymapper_p.h"
  46 #include <qpa/qplatforminputcontext_p.h>
  47
  48 QT_BEGIN_NAMESPACE
  49
  50 /*!
  51     \class QPlatformInputContext
  52     \since 5.0
  53     \internal
  54     \preliminary
  55     \ingroup qpa
  56     \brief The QPlatformInputContext class abstracts the input method dependent data and composing state.
  57
  58     An input method is responsible for inputting complex text that cannot
  59     be inputted via simple keymap. It converts a sequence of input
  60     events (typically key events) into a text string through the input
  61     method specific converting process. The class of the processes are
  62     widely ranging from simple finite state machine to complex text
  63     translator that pools a whole paragraph of a text with text
  64     editing capability to perform grammar and semantic analysis.
  65
  66     To abstract such different input method specific intermediate
  67     information, Qt offers the QPlatformInputContext as base class. The
  68     concept is well known as 'input context' in the input method
  69     domain. An input context is created for a text widget in response
  70     to a demand. It is ensured that an input context is prepared for
  71     an input method before input to a text widget.
  72
  73     QPlatformInputContext provides an interface the actual input methods
  74     can derive from by reimplementing methods.
  75
  76     \sa QInputMethod
  77 */
  78
  79 /*!
  80     \internal
  81  */
  82 QPlatformInputContext::QPlatformInputContext()
  83     : QObject(*(new QPlatformInputContextPrivate))
  84 {
  85 }
  86
  87 /*!
  88     \internal
  89  */
  90 QPlatformInputContext::~QPlatformInputContext()
  91 {
  92 }
  93
  94 /*!
  95     Returns input context validity. Deriving implementations should return true.
  96  */
  97 bool QPlatformInputContext::isValid() const
  98 {
  99     return false;
 100 }
 101
 102 /*!
 103     Method to be called when input method needs to be reset. Called by QInputMethod::reset().
 104     No further QInputMethodEvents should be sent as response.
 105  */
 106 void QPlatformInputContext::reset()
 107 {
 108 }
 109
 110 void QPlatformInputContext::commit()
 111 {
 112 }
 113
 114 /*!
 115     Notification on editor updates. Called by QInputMethod::update().
 116  */
 117 void QPlatformInputContext::update(Qt::InputMethodQueries)
 118 {
 119 }
 120
 121 /*!
 122     Called when when the word currently being composed in input item is tapped by
 123     the user. Input methods often use this information to offer more word
 124     suggestions to the user.
 125  */
 126 void QPlatformInputContext::invokeAction(QInputMethod::Action action, int cursorPosition)
 127 {
 128     Q_UNUSED(cursorPosition)
 129     // Default behavior for simple ephemeral input contexts. Some
 130     // complex input contexts should not be reset here.
 131     if (action == QInputMethod::Click)
 132         reset();
 133 }
 134
 135 /*!
 136     This function can be reimplemented to filter input events.
 137     Return true if the event has been consumed. Otherwise, the unfiltered event will
 138     be forwarded to widgets as ordinary way. Although the input events have accept()
 139     and ignore() methods, leave it untouched.
 140 */
 141 bool QPlatformInputContext::filterEvent(const QEvent *event)
 142 {
 143     Q_UNUSED(event)
 144     return false;
 145 }
 146
 147 /*!
 148     This function can be reimplemented to return virtual keyboard rectangle in currently active
 149     window coordinates. Default implementation returns invalid rectangle.
 150  */
 151 QRectF QPlatformInputContext::keyboardRect() const
 152 {
 153     return QRectF();
 154 }
 155
 156 /*!
 157     Active QPlatformInputContext is responsible for providing keyboardRectangle property to QInputMethod.
 158     In addition of providing the value in keyboardRect function, it also needs to call this emit
 159     function whenever the property changes.
 160  */
 161 void QPlatformInputContext::emitKeyboardRectChanged()
 162 {
 163     emit qApp->inputMethod()->keyboardRectangleChanged();
 164 }
 165
 166 /*!
 167     This function can be reimplemented to return true whenever input method is animating
 168     shown or hidden. Default implementation returns false.
 169  */
 170 bool QPlatformInputContext::isAnimating() const
 171 {
 172     return false;
 173 }
 174
 175 /*!
 176     Active QPlatformInputContext is responsible for providing animating property to QInputMethod.
 177     In addition of providing the value in isAnimation function, it also needs to call this emit
 178     function whenever the property changes.
 179  */
 180 void QPlatformInputContext::emitAnimatingChanged()
 181 {
 182     emit qApp->inputMethod()->animatingChanged();
 183 }
 184
 185 /*!
 186     Request to show input panel.
 187  */
 188 void QPlatformInputContext::showInputPanel()
 189 {
 190 }
 191
 192 /*!
 193     Request to hide input panel.
 194  */
 195 void QPlatformInputContext::hideInputPanel()
 196 {
 197 }
 198
 199 /*!
 200     Returns input panel visibility status. Default implementation returns false.
 201  */
 202 bool QPlatformInputContext::isInputPanelVisible() const
 203 {
 204     return false;
 205 }
 206
 207 /*!
 208     Active QPlatformInputContext is responsible for providing visible property to QInputMethod.
 209     In addition of providing the value in isInputPanelVisible function, it also needs to call this emit
 210     function whenever the property changes.
 211  */
 212 void QPlatformInputContext::emitInputPanelVisibleChanged()
 213 {
 214     emit qApp->inputMethod()->visibleChanged();
 215 }
 216
 217 QLocale QPlatformInputContext::locale() const
 218 {
 219     return qt_keymapper_private()->keyboardInputLocale;
 220 }
 221
 222 void QPlatformInputContext::emitLocaleChanged()
 223 {
 224     emit qApp->inputMethod()->localeChanged();
 225 }
 226
 227 Qt::LayoutDirection QPlatformInputContext::inputDirection() const
 228 {
 229     return qt_keymapper_private()->keyboardInputDirection;
 230 }
 231
 232 void QPlatformInputContext::emitInputDirectionChanged(Qt::LayoutDirection newDirection)
 233 {
 234     emit qApp->inputMethod()->inputDirectionChanged(newDirection);
 235 }
 236
 237 /*!
 238     This virtual method gets called to notify updated focus to \a object.
 239     \warning Input methods must not call this function directly.
 240  */
 241 void QPlatformInputContext::setFocusObject(QObject *object)
 242 {
 243     Q_UNUSED(object)
 244 }
 245
 246 /*!
 247     Returns true if current focus object supports input method events.
 248  */
 249 bool QPlatformInputContext::inputMethodAccepted() const
 250 {
 251     return QPlatformInputContextPrivate::s_inputMethodAccepted;
 252 }
 253
 254 bool QPlatformInputContextPrivate::s_inputMethodAccepted = false;
 255
 256 void QPlatformInputContextPrivate::setInputMethodAccepted(bool accepted)
 257 {
 258     QPlatformInputContextPrivate::s_inputMethodAccepted = accepted;
 259 }
 260
 261
 262 QT_END_NAMESPACE