Doc: Focus and key-event handling in QGraphicsItem.

1 files changed, 25 insertions, 20 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)
 {