diff options
author | Alan Alpert <alan.alpert@nokia.com> | 2011-08-08 18:03:31 +1000 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2011-08-09 10:11:27 +0200 |
commit | 1a84b190bd1a2781d03f13fa43ab92bf34809041 (patch) | |
tree | be4523371df6d2d07041d95c070a22f4724cf031 /src/declarative/items/qsgmousearea.cpp | |
parent | 955c2b0f29dc709a5cc7e563c21f0f2cf2370336 (diff) |
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>
Diffstat (limited to 'src/declarative/items/qsgmousearea.cpp')
-rw-r--r-- | src/declarative/items/qsgmousearea.cpp | 353 |
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); |