Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 120 insertions, 0 deletions

diff --git a/doc/src/declarative/mouseevents.qdoc b/doc/src/declarative/mouseevents.qdoc
new file mode 100644
index 0000000000..ade676024d
--- /dev/null
+++ b/doc/src/declarative/mouseevents.qdoc
@@ -0,0 +1,120 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of this
+** file.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page mouseevents.html
+\title QML Mouse Events
+\ingroup QML Features
+\previouspage {Anchor-based Layout in QML}{Layouts using Anchors}
+\nextpage {QML Text Handling and Validators}{Text Handling and Validators}
+\contentspage QML Features
+
+\tableofcontents
+
+\section1 Mouse Elements
+
+\list
+\o \l{MouseArea} Element
+\o \l{MouseEvent} Object
+\endlist
+
+\section1 Mouse Event Handling
+
+QML uses \l{QML Signal and Handler Event System}{signals and handlers} to
+deliver mouse interactions. Specifically, the \l MouseArea and \l MouseEvent
+elements provide QML components with signal handlers to accept mouse events
+within a defined area.
+
+\section1 Defining a Mouse Area
+
+The \l MouseArea element receives events within a defined area. One quick way
+to define this area is to anchor the \c MouseArea to its parent's area using the
+\c anchors.fill property. If the parent is a \l Rectangle (or any \l Item
+component), then the MouseArea will fill the area defined by the parent's
+dimensions. Alternatively, an area smaller or larger than the parent is
+definable.
+\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml anchor fill
+
+\section1 Receiving Events
+
+The MouseArea element provides
+\l{QML Signal and Handler Event System}{signals and handlers} to detect different
+mouse events. The \l MouseArea element documentation describes these
+gestures in greater detail:
+
+\list
+\o canceled
+\o clicked
+\o doubleClicked
+\o entered
+\o exited
+\o positionChanged
+\o pressAndHold
+\o pressed
+\o released
+\endlist
+
+These signals have signal handlers that are invoked when the signals are emitted.
+\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml mouse handlers
+
+\section1 Enabling Gestures
+Some mouse gestures and button clicks need to be enabled before they send or
+receive events. Certain \l MouseArea and \l MouseEvent properties enable these
+gestures.
+
+To listen to (or explicitly ignore) a certain mouse button, set the appropriate
+mouse button to the \l {MouseArea::acceptedButtons}{acceptedButtons} property.
+
+Naturally, the mouse events, such as button presses and mouse positions, are
+sent during a mouse click. For example, the \c containsMouse property will only
+retrieve its correct value during a mouse press. The
+\l {MouseArea::hoverEnabled}{hoverEnabled} will enable mouse events and
+positioning even when there are no mouse button presses. Setting the
+\c hoverEnabled property to \c true, in turn will enable the \c entered,
+\c exited, and \c positionChanged signal and their respective signal handlers.
+
+\snippet doc/src/snippets/declarative/mousearea/mousearea-snippet.qml enable handlers
+Additionally, to disable the whole mouse area, set the \c MouseArea
+element's \c enabled property to \c false.
+
+\section1 MouseEvent Object
+
+Signals and their handlers receive a \l MouseEvent object as a parameter. The
+\c mouse object contain information about the mouse event. For example, the
+mouse button that started the event is queried through the
+\l {MouseEvent::button}{mouse.button} property.
+
+The \c MouseEvent object can also ignore a mouse event using its \c accepted
+property.
+
+\section2 Accepting Further Signals
+Many of the signals are sent multiple times to reflect various mouse events
+such as double clicking. To facilitate the classification of mouse clicks, the
+MouseEvent object has an \c accepted property to disable the event propagation.
+
+To learn more about QML's event system, please read the \l {QML Signal and Handler Event System} document.
+*/