Doc: Focus and key-event handling in QGraphicsItem.

2 files changed, 37 insertions, 28 deletions

diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp
index 2425354..c8e55e3 100644
--- a/src/gui/graphicsview/qgraphicsitem.cpp
+++ b/src/gui/graphicsview/qgraphicsitem.cpp
@@ -2465,10 +2465,10 @@ void QGraphicsItem::setHandlesChildEvents(bool enabled)
 }
 
 /*!
-    Returns true if this item has keyboard input focus; otherwise, returns
-    false.
+    Returns true if this item or its \l{focusProxy()}{focus proxy} has keyboard
+    input focus; otherwise, returns false.
 
-    \sa QGraphicsScene::focusItem(), setFocus(), QGraphicsScene::setFocusItem()
+    \sa focusItem(), setFocus(), QGraphicsScene::setFocusItem()
 */
 bool QGraphicsItem::hasFocus() const
 {
@@ -2479,8 +2479,8 @@ bool QGraphicsItem::hasFocus() const
 
 /*!
     Gives keyboard input focus to this item. The \a focusReason argument will
-    be passed into any focus event generated by this function; it is used to
-    give an explanation of what caused the item to get focus.
+    be passed into any \l{QFocusEvent}{focus event} generated by this function;
+    it is used to give an explanation of what caused the item to get focus.
 
     Only enabled items that set the ItemIsFocusable flag can accept keyboard
     focus.
@@ -2489,12 +2489,12 @@ bool QGraphicsItem::hasFocus() const
     gain immediate input focus. However, it will be registered as the preferred
     focus item for its subtree of items, should it later become visible.
 
-    As a result of calling this function, this item will receive a focus in
-    event with \a focusReason. If another item already has focus, that item
-    will first receive a focus out event indicating that it has lost input
-    focus.
+    As a result of calling this function, this item will receive a 
+    \l{focusInEvent()}{focus in event} with \a focusReason. If another item
+    already has focus, that item will first receive a \l{focusOutEvent()}
+    {focus out event} indicating that it has lost input focus.
 
-    \sa clearFocus(), hasFocus(), focusItem()
+    \sa clearFocus(), hasFocus(), focusItem(), focusProxy()
 */
 void QGraphicsItem::setFocus(Qt::FocusReason focusReason)
 {
@@ -2527,13 +2527,13 @@ void QGraphicsItem::setFocus(Qt::FocusReason focusReason)
 /*!
     Takes keyboard input focus from the item.
 
-    If it has focus, a focus out event is sent to this item to tell it that it
-    is about to lose the focus.
+    If it has focus, a \l{focusOutEvent()}{focus out event} is sent to this item
+    to tell it that it is about to lose the focus.
 
     Only items that set the ItemIsFocusable flag, or widgets that set an
     appropriate focus policy, can accept keyboard focus.
 
-    \sa setFocus(), QGraphicsWidget::focusPolicy
+    \sa setFocus(), hasFocus(), QGraphicsWidget::focusPolicy
 */
 void QGraphicsItem::clearFocus()
 {
@@ -2550,10 +2550,10 @@ void QGraphicsItem::clearFocus()
 /*!
     \since 4.6
 
-    Returns this item's focus proxy, or 0 if the item
-    does not have any focus proxy.
+    Returns this item's focus proxy, or 0 if this item has no
+    focus proxy.
 
-    \sa setFocusProxy()
+    \sa setFocusProxy(), ItemAutoDetectsFocusProxy, setFocus(), hasFocus()
 */
 QGraphicsItem *QGraphicsItem::focusProxy() const
 {
@@ -2574,7 +2574,10 @@ QGraphicsItem *QGraphicsItem::focusProxy() const
     such case, keyboard input will be handled by the outermost
     focus proxy.
 
-    \sa focusProxy()
+    The focus proxy \a item must belong to the same scene as
+    this item.
+
+    \sa focusProxy(), ItemAutoDetectsFocusProxy, setFocus(), hasFocus()
 */
 void QGraphicsItem::setFocusProxy(QGraphicsItem *item)
 {
@@ -2608,11 +2611,13 @@ void QGraphicsItem::setFocusProxy(QGraphicsItem *item)
 }
 
 /*!
+    \since 4.6
+
     If this item, a child or descendant of this item currently has input
     focus, this function will return a pointer to that item. If
     no descendant has input focus, 0 is returned.
 
-    \sa QWidget::focusWidget()
+    \sa hasFocus(), setFocus(), QWidget::focusWidget()
 */
 QGraphicsItem *QGraphicsItem::focusItem() const
 {
@@ -6102,7 +6107,7 @@ void QGraphicsItem::dropEvent(QGraphicsSceneDragDropEvent *event)
     focus in events for this item. The default implementation calls
     ensureVisible().
 
-    \sa focusOutEvent(), sceneEvent()
+    \sa focusOutEvent(), sceneEvent(), setFocus()
 */
 void QGraphicsItem::focusInEvent(QFocusEvent *event)
 {
@@ -6113,7 +6118,7 @@ void QGraphicsItem::focusInEvent(QFocusEvent *event)
     This event handler, for event \a event, can be reimplemented to receive
     focus out events for this item. The default implementation does nothing.
 
-    \sa focusInEvent(), sceneEvent()
+    \sa focusInEvent(), sceneEvent(), setFocus()
 */
 void QGraphicsItem::focusOutEvent(QFocusEvent *event)
 {
diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp
index 328ba3d..bc3633c 100644
--- a/src/gui/kernel/qevent.cpp
+++ b/src/gui/kernel/qevent.cpp
@@ -675,8 +675,9 @@ QWheelEvent::QWheelEvent(const QPoint &pos, const QPoint& globalPos, int delta,
     The QWidget::setEnable() function can be used to enable or disable
     mouse and keyboard events for a widget.
 
-    The event handlers QWidget::keyPressEvent() and
-    QWidget::keyReleaseEvent() receive key events.
+    The event handlers QWidget::keyPressEvent(), QWidget::keyReleaseEvent(),
+    QGraphicsItem::keyPressEvent() and QGraphicsItem::keyReleaseEvent()
+    receive key events.
 
     \sa QFocusEvent, QWidget::grabKeyboard()
 */
@@ -992,8 +993,9 @@ bool QKeyEvent::matches(QKeySequence::StandardKey matchKey) const
     The reason for a particular focus event is returned by reason()
     in the appropriate event handler.
 
-    The event handlers QWidget::focusInEvent() and
-    QWidget::focusOutEvent() receive focus events.
+    The event handlers QWidget::focusInEvent(),
+    QWidget::focusOutEvent(), QGraphicsItem::focusInEvent and
+    QGraphicsItem::focusOutEvent() receive focus events.
 
     \sa QWidget::setFocus(), QWidget::setFocusPolicy(), {Keyboard Focus}
 */
@@ -1611,12 +1613,14 @@ Qt::ButtonState QContextMenuEvent::state() const
     string is controlled by the widget only). The AttributeType enum
     describes the different attributes that can be set.
 
-    A class implementing QWidget::inputMethodEvent() should at least
-    understand and honor the \l TextFormat and \l Cursor attributes.
+    A class implementing QWidget::inputMethodEvent() or 
+    QGraphicsItem::inputMethodEvent() should at least understand and
+    honor the \l TextFormat and \l Cursor attributes.
 
     Since input methods need to be able to query certain properties
-    from the widget, the widget must also implement
-    QWidget::inputMethodQuery().
+    from the widget or graphics item, subclasses must also implement
+    QWidget::inputMethodQuery() and QGraphicsItem::inputMethodQuery(),
+    respectively.
 
     When receiving an input method event, the text widget has to performs the
     following steps: