From a65a659eee21f451f0bad833c8498cf74158fd18 Mon Sep 17 00:00:00 2001 From: Volker Hilsheimer Date: Mon, 27 Jul 2009 21:20:21 +0200 Subject: Doc: Focus and key-event handling in QGraphicsItem. --- src/gui/graphicsview/qgraphicsitem.cpp | 45 +++++++++++++++++++--------------- src/gui/kernel/qevent.cpp | 20 +++++++++------ 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: -- cgit v0.12