summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorVolker Hilsheimer <volker.hilsheimer@nokia.com>2009-07-27 19:20:21 (GMT)
committerVolker Hilsheimer <volker.hilsheimer@nokia.com>2009-07-27 19:20:21 (GMT)
commita65a659eee21f451f0bad833c8498cf74158fd18 (patch)
tree2018ab1f01ab8c8ef37d43170457fdf5c5ba2b48
parent2ab5c57b593cb6874c035cb3abee574464ea8f30 (diff)
downloadQt-a65a659eee21f451f0bad833c8498cf74158fd18.zip
Qt-a65a659eee21f451f0bad833c8498cf74158fd18.tar.gz
Qt-a65a659eee21f451f0bad833c8498cf74158fd18.tar.bz2
Doc: Focus and key-event handling in QGraphicsItem.
-rw-r--r--src/gui/graphicsview/qgraphicsitem.cpp45
-rw-r--r--src/gui/kernel/qevent.cpp20
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: