diff options
author | Joona Petrell <joona.t.petrell@nokia.com> | 2011-11-10 16:42:50 +0200 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2011-11-11 15:19:16 +0100 |
commit | c92d6130fe9df1dc6b42b9d66627cc905e13519b (patch) | |
tree | f27c347ebc74d09798a7c1543f6858aeda3f3c91 /src | |
parent | 6a25a86d375b03805686e82dbe9e9974f92bf5dd (diff) |
Document QInputPanel API
Change-Id: Ie64215529139e18a0a575e149289b6fa9a699a69
Reviewed-by: Pekka Vuorela <pekka.ta.vuorela@nokia.com>
Reviewed-by: Lars Knoll <lars.knoll@nokia.com>
Diffstat (limited to 'src')
-rw-r--r-- | src/gui/kernel/qinputpanel.cpp | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/src/gui/kernel/qinputpanel.cpp b/src/gui/kernel/qinputpanel.cpp index a7978c6aff..510e2d1038 100644 --- a/src/gui/kernel/qinputpanel.cpp +++ b/src/gui/kernel/qinputpanel.cpp @@ -44,15 +44,44 @@ QT_BEGIN_NAMESPACE +/*! + \internal +*/ QInputPanel::QInputPanel() : QObject(*new QInputPanelPrivate) { } +/*! + \internal +*/ QInputPanel::~QInputPanel() { } +/*! + \class QInputPanel + \brief The QInputPanel class provides access to the active text input method. + + QInputPanel is used by the text editors for integrating to the platform text input + methods and more commonly by application views for querying various text input method-related + information like virtual keyboard visibility and keyboard dimensions. + + Qt Quick also provides access to QInputPanel in QML through \l{QmlGlobalQtObject}{Qt global object} + as \c Qt.application.inputPanel property. +*/ + +/*! + \property QInputPanel::inputItem + \brief Focused item that accepts text input + + Input item is set and unset by the focused window. In QML Scene Graph this is done by + QQuickCanvas and the input item is either TextInput or TextEdit element. Any QObject can + behave as an input item as long as it responds to QInputMethodQueryEvent and QInputMethodEvent + events sent by the input methods. + + \sa inputItemTransform, inputWindow, QInputMethodQueryEvent, QInputMethodEvent +*/ QObject *QInputPanel::inputItem() const { Q_D(const QInputPanel); @@ -70,17 +99,28 @@ void QInputPanel::setInputItem(QObject *inputItem) emit inputItemChanged(); } +/*! + Returns the currently focused window containing the input item. +*/ QWindow *QInputPanel::inputWindow() const { return qApp->activeWindow(); } +/*! + Returns the transformation from input item coordinates to the window coordinates. +*/ QTransform QInputPanel::inputItemTransform() const { Q_D(const QInputPanel); return d->inputItemTransform; } +/*! + Sets the transformation from input item coordinates to the window coordinates. + Item transform needs to be updated by the focused window like QQuickCanvas whenever + item is moved inside the scene. +*/ void QInputPanel::setInputItemTransform(const QTransform &transform) { Q_D(QInputPanel); @@ -91,6 +131,13 @@ void QInputPanel::setInputItemTransform(const QTransform &transform) emit cursorRectangleChanged(); } +/*! + \property QInputPanel::cursorRectangle + \brief Input item's cursor rectangle in window coordinates. + + Cursor rectangle is often used by various text editing controls + like text prediction popups for following the text being typed. +*/ QRectF QInputPanel::cursorRectangle() const { Q_D(const QInputPanel); @@ -107,6 +154,10 @@ QRectF QInputPanel::cursorRectangle() const return d->inputItemTransform.mapRect(r); } +/*! + \property QInputPanel::keyboardRectangle + \brief Virtual keyboard's geometry in window coordinates. +*/ QRectF QInputPanel::keyboardRectangle() { Q_D(QInputPanel); @@ -116,6 +167,15 @@ QRectF QInputPanel::keyboardRectangle() return QRectF(); } +/*! + Requests virtual keyboard to open. If the platform + doesn't provide virtual keyboard the visibility + remains false. + + Normally applications should not need to call this + function, keyboard should automatically open when + the text editor gains focus. +*/ void QInputPanel::show() { Q_D(QInputPanel); @@ -128,6 +188,13 @@ void QInputPanel::show() } } +/*! + Requests virtual keyboard to close. + + Normally applications should not need to call this function, + keyboard should automatically close when the text editor loses + focus, for example when the parent view is closed. +*/ void QInputPanel::hide() { Q_D(QInputPanel); @@ -140,6 +207,15 @@ void QInputPanel::hide() } } +/*! + \property QInputPanel::visible + \brief Virtual keyboard's visibility on the screen + + Input panel visibility remains false for devices + with no virtual keyboards. + + \sa show(), hide() +*/ bool QInputPanel::visible() const { Q_D(const QInputPanel); @@ -151,11 +227,27 @@ bool QInputPanel::visible() const return false; } +/*! + Controls the keyboard visibility. Equivalent + to calling show() and hide() functions. + + \sa show(), hide() +*/ void QInputPanel::setVisible(bool visible) { visible ? show() : hide(); } +/*! + \property QInputPanel::animating + \brief True when the virtual keyboard is being opened or closed. + + Animating is false when keyboard is fully open or closed. + When \c animating is \c true and \c visibility is \c true keyboard + is being opened. When \c animating is \c true and \c visibility is + false keyboard is being closed. +*/ + bool QInputPanel::isAnimating() const { Q_D(const QInputPanel); @@ -165,6 +257,17 @@ bool QInputPanel::isAnimating() const return false; } +/*! + Called by the input item to inform the platform input methods when there has been + state changes in editor's input method query attributes. When calling the function + \a queries parameter has to be used to tell what has changes, which input method + can use to make queries for attributes it's interested with QInputMethodQueryEvent. + + In particular calling update whenever the cursor position changes is important as + that often causes other query attributes like surrounding text and text selection + to change as well. The attributes that often change together with cursor position + have been grouped in Qt::ImQueryInput value for convenience. +*/ void QInputPanel::update(Qt::InputMethodQueries queries) { Q_D(QInputPanel); @@ -180,6 +283,12 @@ void QInputPanel::update(Qt::InputMethodQueries queries) emit cursorRectangleChanged(); } +/*! + Resets the input method state. For example, a text editor normally calls + this method before inserting a text to make widget ready to accept a text. + + Input method resets automatically when the focused editor changes. +*/ void QInputPanel::reset() { Q_D(QInputPanel); @@ -188,6 +297,14 @@ void QInputPanel::reset() ic->reset(); } +/*! + Commits the word user is currently composing to the editor. The function is + mostly needed by the input methods with text prediction features and by the + methods where the script used for typing characters is different from the + script that actually gets appended to the editor. Any kind of action that + interrupts the text composing needs to flush the composing state by calling the + commit() function, for example when the cursor is moved elsewhere. +*/ void QInputPanel::commit() { Q_D(QInputPanel); @@ -196,6 +313,11 @@ void QInputPanel::commit() ic->commit(); } +/*! + Called by the input item when the word currently being composed is tapped by + the user. Input methods often use this information to offer more word + suggestions to the user. +*/ void QInputPanel::invokeAction(Action a, int cursorPosition) { Q_D(QInputPanel); |