Document QPlatformInputContext

Change-Id: I8f7599ed1f03d29a11713c7a11ed5b61a17e3dfe
Reviewed-by: Joona Petrell <joona.t.petrell@nokia.com>

1 files changed, 84 insertions, 0 deletions

diff --git a/src/gui/kernel/qplatforminputcontext_qpa.cpp b/src/gui/kernel/qplatforminputcontext_qpa.cpp
index 55b60279b8..21f1219742 100644
--- a/src/gui/kernel/qplatforminputcontext_qpa.cpp
+++ b/src/gui/kernel/qplatforminputcontext_qpa.cpp
@@ -45,19 +45,57 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \class QPlatformInputContext
+    \brief The QPlatformInputContext class abstracts the input method dependent data and composing state.
+
+    An input method is responsible for inputting complex text that cannot
+    be inputted via simple keymap. It converts a sequence of input
+    events (typically key events) into a text string through the input
+    method specific converting process. The class of the processes are
+    widely ranging from simple finite state machine to complex text
+    translator that pools a whole paragraph of a text with text
+    editing capability to perform grammar and semantic analysis.
+
+    To abstract such different input method specific intermediate
+    information, Qt offers the QPlatformInputContext as base class. The
+    concept is well known as 'input context' in the input method
+    domain. An input context is created for a text widget in response
+    to a demand. It is ensured that an input context is prepared for
+    an input method before input to a text widget.
+
+    QPlatformInputContext provides an interface the actual input methods
+    can derive from by reimplementing methods.
+
+    \sa QInputPanel
+*/
+
+/*!
+    \internal
+ */
 QPlatformInputContext::QPlatformInputContext()
 {
 }
 
+/*!
+    \internal
+ */
 QPlatformInputContext::~QPlatformInputContext()
 {
 }
 
+/*!
+    Returns input context validity. Deriving implementations should return true.
+ */
 bool QPlatformInputContext::isValid() const
 {
     return false;
 }
 
+/*!
+    Method to be called when input method needs to be reset. Called by QInputPanel::reset().
+    No further QInputMethodEvents should be sent as response.
+ */
 void QPlatformInputContext::reset()
 {
 }
@@ -66,10 +104,18 @@ void QPlatformInputContext::commit()
 {
 }
 
+/*!
+    Notification on editor updates. Called by QInputPanel::update().
+ */
 void QPlatformInputContext::update(Qt::InputMethodQueries)
 {
 }
 
+/*!
+    Called when when the word currently being composed in input item is tapped by
+    the user. Input methods often use this information to offer more word
+    suggestions to the user.
+ */
 void QPlatformInputContext::invokeAction(QInputPanel::Action action, int cursorPosition)
 {
     Q_UNUSED(cursorPosition)
@@ -79,45 +125,83 @@ void QPlatformInputContext::invokeAction(QInputPanel::Action action, int cursorP
         reset();
 }
 
+/*!
+    This function can be reimplemented to filter input events.
+    Return true if the event has been consumed. Otherwise, the unfiltered event will
+    be forwarded to widgets as ordinary way. Although the input events have accept()
+    and ignore() methods, leave it untouched.
+*/
 bool QPlatformInputContext::filterEvent(const QEvent *event)
 {
     Q_UNUSED(event)
     return false;
 }
 
+/*!
+    This function can be reimplemented to return virtual keyboard rectangle in currently active
+    window coordinates. Default implementation returns invalid rectangle.
+ */
 QRectF QPlatformInputContext::keyboardRect() const
 {
     return QRectF();
 }
 
+/*!
+    Active QPlatformInputContext is responsible for providing keyboardRectangle property to QInputPanel.
+    In addition of providing the value in keyboardRect function, it also needs to call this emit
+    function whenever the property changes.
+ */
 void QPlatformInputContext::emitKeyboardRectChanged()
 {
     emit qApp->inputPanel()->keyboardRectangleChanged();
 }
 
+/*!
+    This function can be reimplemented to return true whenever input panel is animating
+    shown or hidden. Default implementation returns false.
+ */
 bool QPlatformInputContext::isAnimating() const
 {
     return false;
 }
 
+/*!
+    Active QPlatformInputContext is responsible for providing animating property to QInputPanel.
+    In addition of providing the value in isAnimation function, it also needs to call this emit
+    function whenever the property changes.
+ */
 void QPlatformInputContext::emitAnimatingChanged()
 {
     emit qApp->inputPanel()->animatingChanged();
 }
 
+/*!
+    Request to show input panel.
+ */
 void QPlatformInputContext::showInputPanel()
 {
 }
 
+/*!
+    Request to hide input panel.
+ */
 void QPlatformInputContext::hideInputPanel()
 {
 }
 
+/*!
+    Returns input panel visibility status. Default implementation returns false.
+ */
 bool QPlatformInputContext::isInputPanelVisible() const
 {
     return false;
 }
 
+/*!
+    Active QPlatformInputContext is responsible for providing visible property to QInputPanel.
+    In addition of providing the value in isInputPanelVisible function, it also needs to call this emit
+    function whenever the property changes.
+ */
 void QPlatformInputContext::emitInputPanelVisibleChanged()
 {
     emit qApp->inputPanel()->visibleChanged();