Doc: Documentation for QTouchEventSequence

1 files changed, 102 insertions, 12 deletions

diff --git a/src/testlib/qtestcase.cpp b/src/testlib/qtestcase.cpp
index 9ac9562..e9d58f9 100644
--- a/src/testlib/qtestcase.cpp
+++ b/src/testlib/qtestcase.cpp
@@ -403,7 +403,8 @@ QT_BEGIN_NAMESPACE
 
     \overload
 
-    Simulates clicking of \a key with an optional \a modifier on a \a widget. If \a delay is larger than 0, the test will wait for \a delay milliseconds.
+    Simulates clicking of \a key with an optional \a modifier on a \a widget.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds.
 
     Example:
     \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 13
@@ -416,7 +417,8 @@ QT_BEGIN_NAMESPACE
 
 /*! \fn void QTest::keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
 
-    Simulates clicking of \a key with an optional \a modifier on a \a widget. If \a delay is larger than 0, the test will wait for \a delay milliseconds.
+    Simulates clicking of \a key with an optional \a modifier on a \a widget.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds.
 
     Examples:
     \snippet doc/src/snippets/code/src_qtestlib_qtestcase.cpp 14
@@ -431,20 +433,25 @@ QT_BEGIN_NAMESPACE
 
 /*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
 
-    Sends a Qt key event to \a widget with the given \a key and an associated \a action. Optionally, a keyboard \a modifier can be specified, as well as a \a delay (in milliseconds) of the test before sending the event.
+    Sends a Qt key event to \a widget with the given \a key and an associated \a action.
+    Optionally, a keyboard \a modifier can be specified, as well as a \a delay
+    (in milliseconds) of the test before sending the event.
 */
 
 /*! \fn void QTest::keyEvent(KeyAction action, QWidget *widget, char ascii, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
 
     \overload
 
-    Sends a Qt key event to \a widget with the given key \a ascii and an associated \a action. Optionally, a keyboard \a modifier can be specified, as well as a \a delay (in milliseconds) of the test before sending the event.
+    Sends a Qt key event to \a widget with the given key \a ascii and an associated \a action.
+    Optionally, a keyboard \a modifier can be specified, as well as a \a delay
+    (in milliseconds) of the test before sending the event.
 
 */
 
 /*! \fn void QTest::keyPress(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
 
-    Simulates pressing a \a key with an optional \a modifier on a \a widget. If \a delay is larger than 0, the test will wait for \a delay milliseconds.
+    Simulates pressing a \a key with an optional \a modifier on a \a widget. If \a delay
+    is larger than 0, the test will wait for \a delay milliseconds.
 
     \bold {Note:} At some point you should release the key using \l keyRelease().
 
@@ -455,7 +462,8 @@ QT_BEGIN_NAMESPACE
 
     \overload
 
-    Simulates pressing a \a key with an optional \a modifier on a \a widget. If \a delay is larger than 0, the test will wait for \a delay milliseconds.
+    Simulates pressing a \a key with an optional \a modifier on a \a widget.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds.
 
     \bold {Note:} At some point you should release the key using \l keyRelease().
 
@@ -464,7 +472,8 @@ QT_BEGIN_NAMESPACE
 
 /*! \fn void QTest::keyRelease(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay=-1)
 
-    Simulates releasing a \a key with an optional \a modifier on a \a widget. If \a delay is larger than 0, the test will wait for \a delay milliseconds.
+    Simulates releasing a \a key with an optional \a modifier on a \a widget.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds.
 
     \sa QTest::keyPress(), QTest::keyClick()
 */
@@ -473,7 +482,8 @@ QT_BEGIN_NAMESPACE
 
     \overload
 
-    Simulates releasing a \a key with an optional \a modifier on a \a widget. If \a delay is larger than 0, the test will wait for \a delay milliseconds.
+    Simulates releasing a \a key with an optional \a modifier on a \a widget.
+    If \a delay is larger than 0, the test will wait for \a delay milliseconds.
 
     \sa QTest::keyClick()
 */
@@ -689,6 +699,90 @@ QT_BEGIN_NAMESPACE
     \sa QTest::qSleep()
 */
 
+/*!
+    \class QTest::QTouchEventSequence
+    \inmodule QtTest
+    \since 4.6
+
+    \brief The QTouchEventSequence class is used to simulate a sequence of touch events.
+
+    To simulate a sequence of touch events on a specific device for a widget, call 
+    QTest::touchEvent to create a QTouchEventSequence instance. Add touch events to
+    the sequence by calling press(), move(), release() and stationary(), and let the
+    instance run out of scope to commit the sequence to the event system.
+*/
+
+/*!
+    \fn QTest::QTouchEventSequence::~QTouchEventSequence()
+    \since 4.6
+
+    Commits this sequence of touch events and frees allocated resources.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::press(int touchId, const QPoint &pt, QWidget *widget)
+    \since 4.6
+
+    Adds a press event for touchpoint \a touchId at position \a pt to this sequence and returns
+    a reference to this QTouchEventSequence.
+
+    The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then 
+    \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
+
+    Simulates that the user pressed the touch screen or pad with the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::move(int touchId, const QPoint &pt, QWidget *widget)
+    \since 4.6
+
+    Adds a move event for touchpoint \a touchId at position \a pt to this sequence and returns
+    a reference to this QTouchEventSequence.
+
+    The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then 
+    \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
+
+    Simulates that the user moved the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::release(int touchId, const QPoint &pt, QWidget *widget)
+    \since 4.6
+
+    Adds a release event for touchpoint \a touchId at position \a pt to this sequence and returns
+    a reference to this QTouchEventSequence.
+        
+    The position \a pt is interpreted as relative to \a widget. If \a widget is the null pointer, then 
+    \a pt is interpreted as relative to the widget provided when instantiating this QTouchEventSequence.
+
+    Simulates that the user lifted the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence &QTest::QTouchEventSequence::stationary(int touchId)
+    \since 4.6
+
+    Adds a stationary event for touchpoint \a touchId to this sequence and returns
+    a reference to this QTouchEventSequence.
+    
+    Simulates that the user did not move the finger identified by \a touchId.
+*/
+
+/*!
+    \fn QTouchEventSequence QTest::touchEvent(QWidget *widget, QTouchEvent::DeviceType deviceType)
+    \since 4.6
+
+    Creates and returns a QTouchEventSequence for the device \a deviceType to
+    simulate events for \a widget.
+
+    When adding touch events to the sequence, \a widget will also be used to translate
+    the position provided to screen coordinates, unless another widget is provided in the
+    respective calls to press(), move() etc.
+
+    The touch events are committed to the event system when the destructor of the
+    QTouchEventSequence is called (ie when the object returned runs out of scope).
+*/
+
 namespace QTest
 {
     static QObject *currentTestObject = 0;
@@ -2003,8 +2097,4 @@ bool QTest::compare_string_helper(const char *t1, const char *t2, const char *ac
     \internal
 */
 
-/*! \fn int QTest::qt_snprintf(char *str, int size, const char *format, ...)
-    \internal
-*/
-
 QT_END_NAMESPACE