Add documentation

Copy the documentation back to the scenegraph items, and update it to
the new module syntax.

Change-Id: I5d030a231f991a209a8593ddb069e1b6cd03580e
Reviewed-on: http://codereview.qt.nokia.com/2735
Reviewed-by: Michael Brasser <michael.brasser@nokia.com>

1 files changed, 345 insertions, 8 deletions

diff --git a/src/declarative/items/qsgmousearea.cpp b/src/declarative/items/qsgmousearea.cpp
index 5bf0867cdb..0f9d0a4780 100644
--- a/src/declarative/items/qsgmousearea.cpp
+++ b/src/declarative/items/qsgmousearea.cpp
@@ -85,7 +85,7 @@ void QSGDrag::resetTarget()
 }
 
 /*!
-    \qmlproperty Item MouseArea::drag.dropItem
+    \qmlproperty Item QtQuick2::MouseArea::drag.dropItem
 
     This property holds the item an active drag will be dropped on if released
     at the current position.
@@ -115,7 +115,7 @@ void QSGDrag::setGrabItem(QSGItem *item)
 }
 
 /*!
-    \qmlproperty variant MouseArea::drag.data
+    \qmlproperty variant QtQuick2::MouseArea::drag.data
 
     This property holds the data sent to recipients of drag events generated
     by a MouseArea.
@@ -234,7 +234,7 @@ void QSGDrag::setFilterChildren(bool filter)
 }
 
 /*!
-    \qmlproperty stringlist MouseArea::drag.keys
+    \qmlproperty stringlist QtQuick2::MouseArea::drag.keys
 
     This property holds a list of keys drag recipients can use to identify the
     source or data type of a drag event.
@@ -272,7 +272,7 @@ void QSGMouseAreaPrivate::init()
     q->setFiltersChildMouseEvents(true);
 }
 
-void QSGMouseAreaPrivate::saveEvent(QGraphicsSceneMouseEvent *event) 
+void QSGMouseAreaPrivate::saveEvent(QGraphicsSceneMouseEvent *event)
 {
     lastPos = event->pos();
     lastScenePos = event->scenePos();
@@ -287,14 +287,14 @@ void QSGMouseAreaPrivate::forwardEvent(QGraphicsSceneMouseEvent* event)
     event->setPos(q->mapFromScene(event->scenePos()));
 }
 
-bool QSGMouseAreaPrivate::isPressAndHoldConnected() 
+bool QSGMouseAreaPrivate::isPressAndHoldConnected()
 {
     Q_Q(QSGMouseArea);
     static int idx = QObjectPrivate::get(q)->signalIndex("pressAndHold(QSGMouseEvent*)");
     return QObjectPrivate::get(q)->isSignalConnected(idx);
 }
 
-bool QSGMouseAreaPrivate::isDoubleClickConnected() 
+bool QSGMouseAreaPrivate::isDoubleClickConnected()
 {
     Q_Q(QSGMouseArea);
     static int idx = QObjectPrivate::get(q)->signalIndex("doubleClicked(QSGMouseEvent*)");
@@ -373,7 +373,65 @@ bool QSGMouseAreaPrivate::propagateHelper(QSGMouseEvent *ev, QSGItem *item,const
 
 }
 
-/*
+/*!
+    \qmlclass MouseArea QSGMouseArea
+    \inqmlmodule QtQuick 2
+    \ingroup qml-basic-interaction-elements
+    \brief The MouseArea item enables simple mouse handling.
+    \inherits Item
+
+    A MouseArea is an invisible item that is typically used in conjunction with
+    a visible item in order to provide mouse handling for that item.
+    By effectively acting as a proxy, the logic for mouse handling can be
+    contained within a MouseArea item.
+
+    For basic key handling, see the \l{Keys}{Keys attached property}.
+
+    The \l enabled property is used to enable and disable mouse handling for
+    the proxied item. When disabled, the mouse area becomes transparent to
+    mouse events.
+
+    The \l pressed read-only property indicates whether or not the user is
+    holding down a mouse button over the mouse area. This property is often
+    used in bindings between properties in a user interface. The containsMouse
+    read-only property indicates the presence of the mouse cursor over the
+    mouse area but, by default, only when a mouse button is held down; see below
+    for further details.
+
+    Information about the mouse position and button clicks are provided via
+    signals for which event handler properties are defined. The most commonly
+    used involved handling mouse presses and clicks: onClicked, onDoubleClicked,
+    onPressed, onReleased and onPressAndHold.
+
+    By default, MouseArea items only report mouse clicks and not changes to the
+    position of the mouse cursor. Setting the hoverEnabled property ensures that
+    handlers defined for onPositionChanged, onEntered and onExited are used and
+    that the containsMouse property is updated even when no mouse buttons are
+    pressed.
+
+    \section1 Example Usage
+
+    \div {class="float-right"}
+    \inlineimage qml-mousearea-snippet.png
+    \enddiv
+
+    The following example uses a MouseArea in a \l Rectangle that changes
+    the \l Rectangle color to red when clicked:
+
+    \snippet doc/src/snippets/declarative/mousearea/mousearea.qml import
+    \codeline
+    \snippet doc/src/snippets/declarative/mousearea/mousearea.qml intro
+
+    \clearfloat
+    Many MouseArea signals pass a \l{MouseEvent}{mouse} parameter that contains
+    additional information about the mouse event, such as the position, button,
+    and any key modifiers.
+
+    Here is an extension of the previous example that produces a different
+    color when the area is right clicked:
+
+    \snippet doc/src/snippets/declarative/mousearea/mousearea.qml intro-extended
+
   Behavioral Change in QtQuick 2.0
 
   From QtQuick 2.0, the signals clicked, doubleClicked and pressAndHold have a different interaction
@@ -385,7 +443,149 @@ bool QSGMouseAreaPrivate::propagateHelper(QSGMouseEvent *ev, QSGItem *item,const
 
   Note that to get the same behavior as a QtQuick 1.0 MouseArea{} with regard to absorbing all mouse events, you will
   now need to add empty signal handlers for these three signals.
- */
+
+    \sa MouseEvent, {declarative/touchinteraction/mousearea}{MouseArea example}
+*/
+
+/*!
+    \qmlsignal QtQuick2::MouseArea::onEntered()
+
+    This handler is called when the mouse enters the mouse area.
+
+    By default the onEntered handler is only called while a button is
+    pressed. Setting hoverEnabled to true enables handling of
+    onEntered when no mouse button is pressed.
+
+    \sa hoverEnabled
+*/
+
+/*!
+    \qmlsignal QtQuick2::MouseArea::onExited()
+
+    This handler is called when the mouse exits the mouse area.
+
+    By default the onExited handler is only called while a button is
+    pressed. Setting hoverEnabled to true enables handling of
+    onExited when no mouse button is pressed.
+
+    The example below shows a fairly typical relationship between
+    two MouseAreas, with \c mouseArea2 on top of \c mouseArea1. Moving the
+    mouse into \c mouseArea2 from \c mouseArea1 will cause \c onExited
+    to be called for \c mouseArea1.
+    \qml
+    Rectangle {
+        width: 400; height: 400
+        MouseArea {
+            id: mouseArea1
+            anchors.fill: parent
+            hoverEnabled: true
+        }
+        MouseArea {
+            id: mouseArea2
+            width: 100; height: 100
+            anchors.centerIn: parent
+            hoverEnabled: true
+        }
+    }
+    \endqml
+
+    If instead you give the two mouseAreas a parent-child relationship,
+    moving the mouse into \c mouseArea2 from \c mouseArea1 will \b not
+    cause \c onExited to be called for \c mouseArea1. Instead, they will
+    both be considered to be simultaneously hovered.
+
+    \sa hoverEnabled
+*/
+
+/*!
+    \qmlsignal QtQuick2::MouseArea::onPositionChanged(MouseEvent mouse)
+
+    This handler is called when the mouse position changes.
+
+    The \l {MouseEvent}{mouse} parameter provides information about the mouse, including the x and y
+    position, and any buttons currently pressed.
+
+    The \e accepted property of the MouseEvent parameter is ignored in this handler.
+
+    By default the onPositionChanged handler is only called while a button is
+    pressed.  Setting hoverEnabled to true enables handling of
+    onPositionChanged when no mouse button is pressed.
+*/
+
+/*!
+    \qmlsignal QtQuick2::MouseArea::onClicked(MouseEvent mouse)
+
+    This handler is called when there is a click. A click is defined as a press followed by a release,
+    both inside the MouseArea (pressing, moving outside the MouseArea, and then moving back inside and
+    releasing is also considered a click).
+
+    The \l {MouseEvent}{mouse} parameter provides information about the click, including the x and y
+    position of the release of the click, and whether the click was held.
+
+    The \e accepted property of the MouseEvent parameter is ignored in this handler.
+*/
+
+/*!
+    \qmlsignal QtQuick2::MouseArea::onPressed(MouseEvent mouse)
+
+    This handler is called when there is a press.
+    The \l {MouseEvent}{mouse} parameter provides information about the press, including the x and y
+    position and which button was pressed.
+
+    The \e accepted property of the MouseEvent parameter determines whether this MouseArea
+    will handle the press and all future mouse events until release.  The default is to accept
+    the event and not allow other MouseArea beneath this one to handle the event.  If \e accepted
+    is set to false, no further events will be sent to this MouseArea until the button is next
+    pressed.
+*/
+
+/*!
+    \qmlsignal QtQuick2::MouseArea::onReleased(MouseEvent mouse)
+
+    This handler is called when there is a release.
+    The \l {MouseEvent}{mouse} parameter provides information about the click, including the x and y
+    position of the release of the click, and whether the click was held.
+
+    The \e accepted property of the MouseEvent parameter is ignored in this handler.
+
+    \sa onCanceled
+*/
+
+/*!
+    \qmlsignal QtQuick2::MouseArea::onPressAndHold(MouseEvent mouse)
+
+    This handler is called when there is a long press (currently 800ms).
+    The \l {MouseEvent}{mouse} parameter provides information about the press, including the x and y
+    position of the press, and which button is pressed.
+
+    The \e accepted property of the MouseEvent parameter is ignored in this handler.
+*/
+
+/*!
+    \qmlsignal QtQuick2::MouseArea::onDoubleClicked(MouseEvent mouse)
+
+    This handler is called when there is a double-click (a press followed by a release followed by a press).
+    The \l {MouseEvent}{mouse} parameter provides information about the click, including the x and y
+    position of the release of the click, and whether the click was held.
+
+    If the \e accepted property of the \l {MouseEvent}{mouse} parameter is set to false
+    in the handler, the onPressed/onReleased/onClicked handlers will be called for the second
+    click; otherwise they are suppressed.  The accepted property defaults to true.
+*/
+
+/*!
+    \qmlsignal QtQuick2::MouseArea::onCanceled()
+
+    This handler is called when mouse events have been canceled, either because an event was not accepted, or
+    because another element stole the mouse event handling.
+
+    This signal is for advanced use: it is useful when there is more than one MouseArea
+    that is handling input, or when there is a MouseArea inside a \l Flickable. In the latter
+    case, if you execute some logic on the pressed signal and then start dragging, the
+    \l Flickable will steal the mouse handling from the MouseArea. In these cases, to reset
+    the logic when the MouseArea has lost the mouse handling to the \l Flickable,
+    \c onCanceled should be used in addition to onReleased.
+*/
 QSGMouseArea::QSGMouseArea(QSGItem *parent)
   : QSGItem(*(new QSGMouseAreaPrivate), parent)
 {
@@ -397,6 +597,25 @@ QSGMouseArea::~QSGMouseArea()
 {
 }
 
+/*!
+    \qmlproperty real QtQuick2::MouseArea::mouseX
+    \qmlproperty real QtQuick2::MouseArea::mouseY
+    These properties hold the coordinates of the mouse cursor.
+
+    If the hoverEnabled property is false then these properties will only be valid
+    while a button is pressed, and will remain valid as long as the button is held
+    down even if the mouse is moved outside the area.
+
+    By default, this property is false.
+
+    If hoverEnabled is true then these properties will be valid when:
+    \list
+        \i no button is pressed, but the mouse is within the MouseArea (containsMouse is true).
+        \i a button is pressed and held, even if it has since moved out of the area.
+    \endlist
+
+    The coordinates are relative to the MouseArea.
+*/
 qreal QSGMouseArea::mouseX() const
 {
     Q_D(const QSGMouseArea);
@@ -409,6 +628,12 @@ qreal QSGMouseArea::mouseY() const
     return d->lastPos.y();
 }
 
+/*!
+    \qmlproperty bool QtQuick2::MouseArea::enabled
+    This property holds whether the item accepts mouse events.
+
+    By default, this property is true.
+*/
 bool QSGMouseArea::isEnabled() const
 {
     Q_D(const QSGMouseArea);
@@ -424,6 +649,22 @@ void QSGMouseArea::setEnabled(bool a)
     }
 }
 
+/*!
+    \qmlproperty bool QtQuick2::MouseArea::preventStealing
+    This property holds whether the mouse events may be stolen from this
+    MouseArea.
+
+    If a MouseArea is placed within an item that filters child mouse
+    events, such as Flickable, the mouse
+    events may be stolen from the MouseArea if a gesture is recognized
+    by the parent element, e.g. a flick gesture.  If preventStealing is
+    set to true, no element will steal the mouse events.
+
+    Note that setting preventStealing to true once an element has started
+    stealing events will have no effect until the next press event.
+
+    By default this property is false.
+*/
 bool QSGMouseArea::preventStealing() const
 {
     Q_D(const QSGMouseArea);
@@ -440,6 +681,23 @@ void QSGMouseArea::setPreventStealing(bool prevent)
     }
 }
 
+/*!
+    \qmlproperty MouseButtons QtQuick2::MouseArea::pressedButtons
+    This property holds the mouse buttons currently pressed.
+
+    It contains a bitwise combination of:
+    \list
+    \o Qt.LeftButton
+    \o Qt.RightButton
+    \o Qt.MiddleButton
+    \endlist
+
+    The code below displays "right" when the right mouse buttons is pressed:
+
+    \snippet doc/src/snippets/declarative/mousearea/mousearea.qml mousebuttons
+
+    \sa acceptedButtons
+*/
 Qt::MouseButtons QSGMouseArea::pressedButtons() const
 {
     Q_D(const QSGMouseArea);
@@ -832,6 +1090,17 @@ void QSGMouseArea::itemChange(ItemChange change, const ItemChangeData &value)
     QSGItem::itemChange(change, value);
 }
 
+/*!
+    \qmlproperty bool QtQuick2::MouseArea::hoverEnabled
+    This property holds whether hover events are handled.
+
+    By default, mouse events are only handled in response to a button event, or when a button is
+    pressed.  Hover enables handling of all mouse events even when no mouse button is
+    pressed.
+
+    This property affects the containsMouse property and the onEntered, onExited and
+    onPositionChanged signals.
+*/
 bool QSGMouseArea::hoverEnabled() const
 {
     return acceptHoverEvents();
@@ -847,12 +1116,24 @@ void QSGMouseArea::setHoverEnabled(bool h)
     emit hoverEnabledChanged();
 }
 
+
+/*!
+    \qmlproperty bool QtQuick2::MouseArea::containsMouse
+    This property holds whether the mouse is currently inside the mouse area.
+
+    \warning This property is not updated if the area moves under the mouse: \e containsMouse will not change.
+    In addition, if hoverEnabled is false, containsMouse will only be valid when the mouse is pressed.
+*/
 bool QSGMouseArea::hovered() const
 {
     Q_D(const QSGMouseArea);
     return d->hovered;
 }
 
+/*!
+    \qmlproperty bool QtQuick2::MouseArea::pressed
+    This property holds whether the mouse area is currently pressed.
+*/
 bool QSGMouseArea::pressed() const
 {
     Q_D(const QSGMouseArea);
@@ -868,7 +1149,26 @@ void QSGMouseArea::setHovered(bool h)
         d->hovered ? emit entered() : emit exited();
     }
 }
+/*!
+    \qmlproperty QtQuick2::Qt::MouseButtons MouseArea::acceptedButtons
+    This property holds the mouse buttons that the mouse area reacts to.
+
+    The available buttons are:
+    \list
+    \o Qt.LeftButton
+    \o Qt.RightButton
+    \o Qt.MiddleButton
+    \endlist
 
+    To accept more than one button the flags can be combined with the
+    "|" (or) operator:
+
+    \code
+    MouseArea { acceptedButtons: Qt.LeftButton | Qt.RightButton }
+    \endcode
+
+    The default value is \c Qt.LeftButton.
+*/
 Qt::MouseButtons QSGMouseArea::acceptedButtons() const
 {
     return acceptedMouseButtons();
@@ -916,6 +1216,43 @@ bool QSGMouseArea::setPressed(bool p)
     return false;
 }
 
+/*!
+    \qmlproperty Item QtQuick2::MouseArea::drag.target
+    \qmlproperty bool QtQuick2::MouseArea::drag.active
+    \qmlproperty enumeration QtQuick2::MouseArea::drag.axis
+    \qmlproperty real QtQuick2::MouseArea::drag.minimumX
+    \qmlproperty real QtQuick2::MouseArea::drag.maximumX
+    \qmlproperty real QtQuick2::MouseArea::drag.minimumY
+    \qmlproperty real QtQuick2::MouseArea::drag.maximumY
+    \qmlproperty bool QtQuick2::MouseArea::drag.filterChildren
+
+    \c drag provides a convenient way to make an item draggable.
+
+    \list
+    \i \c drag.target specifies the id of the item to drag.
+    \i \c drag.active specifies if the target item is currently being dragged.
+    \i \c drag.axis specifies whether dragging can be done horizontally (\c Drag.XAxis), vertically (\c Drag.YAxis), or both (\c Drag.XandYAxis)
+    \i \c drag.minimum and \c drag.maximum limit how far the target can be dragged along the corresponding axes.
+    \endlist
+
+    The following example displays a \l Rectangle that can be dragged along the X-axis. The opacity
+    of the rectangle is reduced when it is dragged to the right.
+
+    \snippet doc/src/snippets/declarative/mousearea/mousearea.qml drag
+
+    \note Items cannot be dragged if they are anchored for the requested
+    \c drag.axis. For example, if \c anchors.left or \c anchors.right was set
+    for \c rect in the above example, it cannot be dragged along the X-axis.
+    This can be avoided by settng the anchor value to \c undefined in
+    an \l onPressed handler.
+
+    If \c drag.filterChildren is set to true, a drag can override descendant MouseAreas.  This
+    enables a parent MouseArea to handle drags, for example, while descendants handle clicks:
+
+    \snippet doc/src/snippets/declarative/mousearea/mouseareadragfilter.qml dragfilter
+
+*/
+
 QSGDrag *QSGMouseArea::drag()
 {
     Q_D(QSGMouseArea);