QQuickItem: document which events are accepted by default

Change-Id: I64a2ab811b48d2a231e18c493fb1f6087fd02905
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

2 files changed, 51 insertions, 1 deletions

diff --git a/src/quick/doc/src/includes/item.qdocinc b/src/quick/doc/src/includes/item.qdocinc
index 12472cb928..4cb2652bbf 100644
--- a/src/quick/doc/src/includes/item.qdocinc
+++ b/src/quick/doc/src/includes/item.qdocinc
@@ -4,3 +4,12 @@ The following properties of the item are used in the mapping:
 \l x, \l y, \l scale, \l rotation, \l transformOrigin, and \l [QML]{Item::}{transform}.
 
 //! [mapping]
+
+
+//! [accepting-events]
+
+The event is accepted by default, so it is not necessary to explicitly
+accept the event if you reimplement this function. If you don't accept the
+event, call \c event->ignore().
+
+//! [accepting-events]
diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index 132c0617f3..154e3241b1 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -3952,6 +3952,8 @@ void QQuickItemPrivate::updateOrRemoveGeometryChangeListener(QQuickItemChangeLis
     This event handler can be reimplemented in a subclass to receive key
     press events for an item. The event information is provided by the
     \a event parameter.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::keyPressEvent(QKeyEvent *event)
 {
@@ -3962,6 +3964,8 @@ void QQuickItem::keyPressEvent(QKeyEvent *event)
     This event handler can be reimplemented in a subclass to receive key
     release events for an item. The event information is provided by the
     \a event parameter.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::keyReleaseEvent(QKeyEvent *event)
 {
@@ -3973,6 +3977,8 @@ void QQuickItem::keyReleaseEvent(QKeyEvent *event)
     This event handler can be reimplemented in a subclass to receive input
     method events for an item. The event information is provided by the
     \a event parameter.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::inputMethodEvent(QInputMethodEvent *event)
 {
@@ -3984,6 +3990,11 @@ void QQuickItem::inputMethodEvent(QInputMethodEvent *event)
     This event handler can be reimplemented in a subclass to receive focus-in
     events for an item. The event information is provided by the \c event
     parameter.
+
+    \input item.qdocinc accepting-events
+
+    If you do reimplement this function, you should call the base class
+    implementation.
   */
 void QQuickItem::focusInEvent(QFocusEvent * /*event*/)
 {
@@ -4001,6 +4012,8 @@ void QQuickItem::focusInEvent(QFocusEvent * /*event*/)
     This event handler can be reimplemented in a subclass to receive focus-out
     events for an item. The event information is provided by the \c event
     parameter.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::focusOutEvent(QFocusEvent * /*event*/)
 {
@@ -4010,6 +4023,8 @@ void QQuickItem::focusOutEvent(QFocusEvent * /*event*/)
     This event handler can be reimplemented in a subclass to receive mouse
     press events for an item. The event information is provided by the
     \a event parameter.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::mousePressEvent(QMouseEvent *event)
 {
@@ -4020,6 +4035,8 @@ void QQuickItem::mousePressEvent(QMouseEvent *event)
     This event handler can be reimplemented in a subclass to receive mouse
     move events for an item. The event information is provided by the
     \a event parameter.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::mouseMoveEvent(QMouseEvent *event)
 {
@@ -4030,6 +4047,8 @@ void QQuickItem::mouseMoveEvent(QMouseEvent *event)
     This event handler can be reimplemented in a subclass to receive mouse
     release events for an item. The event information is provided by the
     \a event parameter.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::mouseReleaseEvent(QMouseEvent *event)
 {
@@ -4040,6 +4059,8 @@ void QQuickItem::mouseReleaseEvent(QMouseEvent *event)
     This event handler can be reimplemented in a subclass to receive mouse
     double-click events for an item. The event information is provided by the
     \a event parameter.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::mouseDoubleClickEvent(QMouseEvent *)
 {
@@ -4049,7 +4070,7 @@ void QQuickItem::mouseDoubleClickEvent(QMouseEvent *)
     This event handler can be reimplemented in a subclass to be notified
     when a mouse ungrab event has occurred on this item.
 
-    \sa ungrabMouse()
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::mouseUngrabEvent()
 {
@@ -4059,6 +4080,8 @@ void QQuickItem::mouseUngrabEvent()
 /*!
     This event handler can be reimplemented in a subclass to be notified
     when a touch ungrab event has occurred on this item.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::touchUngrabEvent()
 {
@@ -4070,6 +4093,8 @@ void QQuickItem::touchUngrabEvent()
     This event handler can be reimplemented in a subclass to receive
     wheel events for an item. The event information is provided by the
     \a event parameter.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::wheelEvent(QWheelEvent *event)
 {
@@ -4081,6 +4106,8 @@ void QQuickItem::wheelEvent(QWheelEvent *event)
     This event handler can be reimplemented in a subclass to receive touch
     events for an item. The event information is provided by the
     \a event parameter.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::touchEvent(QTouchEvent *event)
 {
@@ -4093,6 +4120,8 @@ void QQuickItem::touchEvent(QTouchEvent *event)
     \a event parameter.
 
     Hover events are only provided if acceptHoverEvents() is true.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::hoverEnterEvent(QHoverEvent *event)
 {
@@ -4105,6 +4134,8 @@ void QQuickItem::hoverEnterEvent(QHoverEvent *event)
     \a event parameter.
 
     Hover events are only provided if acceptHoverEvents() is true.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::hoverMoveEvent(QHoverEvent *event)
 {
@@ -4117,6 +4148,8 @@ void QQuickItem::hoverMoveEvent(QHoverEvent *event)
     \a event parameter.
 
     Hover events are only provided if acceptHoverEvents() is true.
+
+    \input item.qdocinc accepting-events
   */
 void QQuickItem::hoverLeaveEvent(QHoverEvent *event)
 {
@@ -4132,6 +4165,8 @@ void QQuickItem::hoverLeaveEvent(QHoverEvent *event)
     Drag and drop events are only provided if the ItemAcceptsDrops flag
     has been set for this item.
 
+    \input item.qdocinc accepting-events
+
     \sa Drag, {Drag and Drop}
   */
 void QQuickItem::dragEnterEvent(QDragEnterEvent *event)
@@ -4147,6 +4182,8 @@ void QQuickItem::dragEnterEvent(QDragEnterEvent *event)
     Drag and drop events are only provided if the ItemAcceptsDrops flag
     has been set for this item.
 
+    \input item.qdocinc accepting-events
+
     \sa Drag, {Drag and Drop}
   */
 void QQuickItem::dragMoveEvent(QDragMoveEvent *event)
@@ -4162,6 +4199,8 @@ void QQuickItem::dragMoveEvent(QDragMoveEvent *event)
     Drag and drop events are only provided if the ItemAcceptsDrops flag
     has been set for this item.
 
+    \input item.qdocinc accepting-events
+
     \sa Drag, {Drag and Drop}
   */
 void QQuickItem::dragLeaveEvent(QDragLeaveEvent *event)
@@ -4177,6 +4216,8 @@ void QQuickItem::dragLeaveEvent(QDragLeaveEvent *event)
     Drag and drop events are only provided if the ItemAcceptsDrops flag
     has been set for this item.
 
+    \input item.qdocinc accepting-events
+
     \sa Drag, {Drag and Drop}
   */
 void QQuickItem::dropEvent(QDropEvent *event)