From 415039d9c9dab219505cc082981e2175a8977b03 Mon Sep 17 00:00:00 2001 From: Denis Dzyubenko Date: Mon, 16 Mar 2009 15:55:30 +0100 Subject: More documentation fixes. --- doc/src/qnamespace.qdoc | 33 +++++++++++++- src/gui/graphicsview/qgraphicsitem.cpp | 48 +++++++++++++++++--- src/gui/graphicsview/qgraphicsitem.h | 5 ++- src/gui/graphicsview/qgraphicssceneevent.cpp | 51 +++++++++++----------- src/gui/kernel/qevent.cpp | 13 ++---- src/gui/kernel/qevent.h | 2 - src/gui/kernel/qgesture.cpp | 65 ++++++++++++++++------------ src/gui/kernel/qgesture.h | 9 ++-- src/gui/kernel/qwidget.cpp | 8 ++-- 9 files changed, 149 insertions(+), 85 deletions(-) diff --git a/doc/src/qnamespace.qdoc b/doc/src/qnamespace.qdoc index c44b41e..c30dc88 100644 --- a/doc/src/qnamespace.qdoc +++ b/doc/src/qnamespace.qdoc @@ -2676,9 +2676,17 @@ \sa QPixmapBorders, qDrawBorderPixmap() */ -/*! \typedef Qt::GestureType +/*! \enum Qt::GestureType - A string representing a type of a gesture. + This enum lists standard gestures. + + \value UnknownGesture An unknown gesture. This enum value shouldn't be used. + \value TapGesture A single tap gesture. + \value DoubleTapGesture A double tap gesture. + \value TrippleTapGesture A tripple tap gesture. + \value TapAndHoldGesture A tap-and-hold (long tap) gesture. + \value PanGesture A pan gesture. + \value PinchGesture A pinch gesture. */ /*! @@ -2691,3 +2699,24 @@ \sa QGesture */ + +/*! + \enum Qt::DirectionType + + This enum type describes directions. This could be used by the + gesture recognizers. + + \value NoDirection Non-specific direction. + \value LeftDownDirection + \value DownLeftDirection + \value DownDirection + \value RightDownDirection + \value DownRightDirection + \value LeftDirection + \value RightDirection + \value LeftUpDirection + \value UpLeftDirection + \value UpDirection + \value RightUpDirection + \value UpRightDirection +*/ diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp index cbd4834..0dc227a 100644 --- a/src/gui/graphicsview/qgraphicsitem.cpp +++ b/src/gui/graphicsview/qgraphicsitem.cpp @@ -5790,27 +5790,61 @@ QVariant QGraphicsItem::inputMethodQuery(Qt::InputMethodQuery query) const return QVariant(); } -int QGraphicsItem::grabGesture(Qt::GestureType type) +/*! + Subscribes the graphics item to the specified \a gesture type. + + Returns the id of the gesture. + + \sa releaseGesture(), setGestureEnabled() +*/ +int QGraphicsItem::grabGesture(Qt::GestureType gesture) { - return grabGesture(qt_getStandardGestureTypeName(type)); + return grabGesture(qt_getStandardGestureTypeName(gesture)); } -int QGraphicsItem::grabGesture(const QString &type) +/*! + Subscribes the graphics item to the specified \a gesture type. + + Returns the id of the gesture. + + \sa releaseGesture(), setGestureEnabled() +*/ +int QGraphicsItem::grabGesture(const QString &gesture) { - int id = qHash(type); + int id = qHash(gesture); QSet::iterator it = d_ptr->gestures.find(id); if (it != d_ptr->gestures.end()) return *it; d_ptr->gestures << id; if (d_ptr->scene) d_ptr->scene->d_func()->grabGesture(this, id); + return id; } -void QGraphicsItem::releaseGesture(int id) +/*! + Unsubscribes the graphics item from a gesture, which is specified + by the \a gestureId. + + \sa grabGesture(), setGestureEnabled() +*/ +void QGraphicsItem::releaseGesture(int gestureId) { - d_ptr->gestures.remove(id); + d_ptr->gestures.remove(gestureId); if (d_ptr->scene) - d_ptr->scene->d_func()->releaseGesture(this, id); + d_ptr->scene->d_func()->releaseGesture(this, gestureId); +} + +/*! + If \a enable is true, the gesture with the given \a gestureId is + enabled; otherwise the gesture is disabled. + + The id of the gesture is returned by the grabGesture(). + + \sa grabGesture(), releaseGesture() +*/ +void QGraphicsItem::setGestureEnabled(int gestureId, bool enable) +{ + //### } /*! diff --git a/src/gui/graphicsview/qgraphicsitem.h b/src/gui/graphicsview/qgraphicsitem.h index 4e6e96d..37d8f78 100644 --- a/src/gui/graphicsview/qgraphicsitem.h +++ b/src/gui/graphicsview/qgraphicsitem.h @@ -338,9 +338,10 @@ public: QVariant data(int key) const; void setData(int key, const QVariant &value); - int grabGesture(Qt::GestureType type); - int grabGesture(const QString &type); + int grabGesture(Qt::GestureType gesture); + int grabGesture(const QString &gesture); void releaseGesture(int gestureId); + void setGestureEnabled(int gestureId, bool enable = true); enum { Type = 1, diff --git a/src/gui/graphicsview/qgraphicssceneevent.cpp b/src/gui/graphicsview/qgraphicssceneevent.cpp index 4f24a74..c79e30b 100644 --- a/src/gui/graphicsview/qgraphicssceneevent.cpp +++ b/src/gui/graphicsview/qgraphicssceneevent.cpp @@ -1727,18 +1727,24 @@ void QGraphicsSceneMoveEvent::setNewPos(const QPointF &pos) gestures with \l{QGraphicsItem::}{grabGesture()}. */ - +/*! + Constructs a QGraphicsSceneGestureEvent. +*/ QGraphicsSceneGestureEvent::QGraphicsSceneGestureEvent() : QGraphicsSceneEvent(QEvent::GraphicsSceneGesture) { } +/*! + Destroys a QGraphicsSceneGestureEvent. +*/ QGraphicsSceneGestureEvent::~QGraphicsSceneGestureEvent() { } /*! - Checks if the gesture event contains gesture of specific \a type. + Returns true if the gesture event contains gesture of specific \a + type; returns false otherwise. */ bool QGraphicsSceneGestureEvent::contains(const QString &type) const { @@ -1746,7 +1752,8 @@ bool QGraphicsSceneGestureEvent::contains(const QString &type) const } /*! - Checks if the gesture event contains gesture of specific \a type. + Returns true if the gesture event contains gesture of specific \a + type; returns false otherwise. */ bool QGraphicsSceneGestureEvent::contains(Qt::GestureType type) const { @@ -1754,7 +1761,7 @@ bool QGraphicsSceneGestureEvent::contains(Qt::GestureType type) const } /*! - Returns a list of gesture names that the event contains. + Returns a list of gesture names that this event contains. */ QList QGraphicsSceneGestureEvent::gestureTypes() const { @@ -1778,7 +1785,7 @@ const QGesture* QGraphicsSceneGestureEvent::gesture(Qt::GestureType type) const } /*! - Returns extended information about all triggered gestures. + Returns extended information about all gestures in the event. */ QList > QGraphicsSceneGestureEvent::gestures() const { @@ -1786,7 +1793,7 @@ QList > QGraphicsSceneGestureEvent::gestures() const } /*! - Returns a set of gesture names that used to be executed, but got + Returns a set of gesture names that used to be executed, but were cancelled (i.e. they were not finished properly). */ QSet QGraphicsSceneGestureEvent::cancelledGestures() const @@ -1795,8 +1802,9 @@ QSet QGraphicsSceneGestureEvent::cancelledGestures() const } /*! - Returns a set of gesture names that used to be executed, but got - cancelled (i.e. they were not finished properly). + Sets a list of gesture names \a cancelledGestures that used to be + executed, but were cancelled (i.e. they were not finished + properly). */ void QGraphicsSceneGestureEvent::setCancelledGestures(const QSet &cancelledGestures) { @@ -1807,13 +1815,10 @@ void QGraphicsSceneGestureEvent::setCancelledGestures(const QSet &cance Maps the point \a point, which is in a view coordinate system, to scene coordinate system, and returns the mapped coordinate. - \a Point is in coordinate system of the widget that received + A \a point is in coordinate system of the widget that received gesture event. - \sa mapToScene(const QRect &rect), - mapToItem(const QPoint &point, QGraphicsItem *item), - mapToItem(const QRect &rect, QGraphicsItem *item), - {The Graphics View Coordinate System} + \sa mapToItem(), {The Graphics View Coordinate System} */ QPointF QGraphicsSceneGestureEvent::mapToScene(const QPoint &point) const { @@ -1826,13 +1831,10 @@ QPointF QGraphicsSceneGestureEvent::mapToScene(const QPoint &point) const Maps the rectangular \a rect, which is in a view coordinate system, to scene coordinate system, and returns the mapped coordinate. - \a Point is in coordinate system of the widget that received + A \a rect is in coordinate system of the widget that received gesture event. - \sa mapToScene(const QPoint &rect), - mapToItem(const QPoint &point, QGraphicsItem *item), - mapToItem(const QRect &rect, QGraphicsItem *item), - {The Graphics View Coordinate System} + \sa mapToItem(), {The Graphics View Coordinate System} */ QPolygonF QGraphicsSceneGestureEvent::mapToScene(const QRect &rect) const { @@ -1847,9 +1849,7 @@ QPolygonF QGraphicsSceneGestureEvent::mapToScene(const QRect &rect) const If \a item is 0, this function returns the same as mapToScene(). - \sa mapToScene(const QPoint &rect), mapToScene(const QRect &rect), - mapToItem(const QRect &, QGraphicsItem *item), - {The Graphics View Coordinate System} + \sa mapToScene(), {The Graphics View Coordinate System} */ QPointF QGraphicsSceneGestureEvent::mapToItem(const QPoint &point, QGraphicsItem *item) const { @@ -1863,14 +1863,12 @@ QPointF QGraphicsSceneGestureEvent::mapToItem(const QPoint &point, QGraphicsItem } /*! - Maps the point \a point, which is in a view coordinate system, to + Maps the rectangualar \a rect, which is in a view coordinate system, to item's \a item coordinate system, and returns the mapped coordinate. If \a item is 0, this function returns the same as mapToScene(). - \sa mapToScene(const QPoint &rect), mapToScene(const QRect &rect), - mapToItem(const QPoint &point, QGraphicsItem *item), - {The Graphics View Coordinate System} + \sa mapToScene(), {The Graphics View Coordinate System} */ QPolygonF QGraphicsSceneGestureEvent::mapToItem(const QRect &rect, QGraphicsItem *item) const { @@ -1883,6 +1881,9 @@ QPolygonF QGraphicsSceneGestureEvent::mapToItem(const QRect &rect, QGraphicsItem return QPolygonF(); } +/*! + Set a list of gesture objects containing extended information about \a gestures. +*/ void QGraphicsSceneGestureEvent::setGestures(const QList > &gestures) { foreach(const QSharedPointer &g, gestures) diff --git a/src/gui/kernel/qevent.cpp b/src/gui/kernel/qevent.cpp index 3ce2517..dbfe528 100644 --- a/src/gui/kernel/qevent.cpp +++ b/src/gui/kernel/qevent.cpp @@ -3540,13 +3540,6 @@ QGestureEvent::QGestureEvent(const QList &gestures, m_gestures.insert(r->gestureType(), QSharedPointer(r)); } -QGestureEvent::QGestureEvent(const QGestureEvent &event, const QPoint &offset) - : QEvent(QEvent::Gesture), m_gestures(event.m_gestures), - m_cancelledGestures(event.m_cancelledGestures) -{ - //### use offset! -} - /*! Destroys the QGestureEvent object. */ @@ -3555,7 +3548,8 @@ QGestureEvent::~QGestureEvent() } /*! - Checks if the gesture event contains gesture of specific \a type. + Returns true if the gesture event contains gesture of specific \a + type; returns false otherwise. */ bool QGestureEvent::contains(Qt::GestureType type) const { @@ -3563,7 +3557,8 @@ bool QGestureEvent::contains(Qt::GestureType type) const } /*! - Checks if the gesture event contains gesture of specific \a type. + Returns true if the gesture event contains gesture of specific \a + type; returns false otherwise. */ bool QGestureEvent::contains(const QString &type) const { diff --git a/src/gui/kernel/qevent.h b/src/gui/kernel/qevent.h index 48e420a..41005d8 100644 --- a/src/gui/kernel/qevent.h +++ b/src/gui/kernel/qevent.h @@ -719,8 +719,6 @@ class Q_GUI_EXPORT QGestureEvent : public QEvent public: QGestureEvent(const QList &gestures, const QSet &cancelledGestures = QSet()); - // internal ctor - QGestureEvent(const QGestureEvent &gestures, const QPoint &offset); ~QGestureEvent(); bool contains(Qt::GestureType type) const; diff --git a/src/gui/kernel/qgesture.cpp b/src/gui/kernel/qgesture.cpp index b2bb859..35a3e2a 100644 --- a/src/gui/kernel/qgesture.cpp +++ b/src/gui/kernel/qgesture.cpp @@ -64,13 +64,23 @@ QString qt_getStandardGestureTypeName(Qt::GestureType type); information. However, if the gesture developer wants to add a new property to the gesture object that describe coordinate (like a QPoint or QRect), it is required to subclass the QGesture and - re-implement the \l{QGesture::}{translate} function to make sure + re-implement the \l{QGesture::}{translate()} function to make sure the coordinates are translated properly when the gesture event is propagated to parent widgets. \sa QGestureEvent, QGestureRecognizer */ +/*! \fn QString QGesture::gestureType() const + + Returns the type of the gesture. +*/ + +/*! \fn Qt::GestureState QGesture::state() const + + Returns the current state of the gesture. +*/ + /*! Creates a new gesture object of type \a type in a \a state and marks it as a child of \a parent. @@ -141,7 +151,9 @@ void QGesture::translate(const QPoint &offset) } /*! - Returns a bounding rect of a gesture. + \property QGesture::rect + + \brief The bounding rect of a gesture. */ QRect QGesture::rect() const { @@ -149,7 +161,9 @@ QRect QGesture::rect() const } /*! - Returns a center point of a gesture. + \property QGesture::hotSpot + + \brief The center point of a gesture. */ QPoint QGesture::hotSpot() const { @@ -157,7 +171,9 @@ QPoint QGesture::hotSpot() const } /*! - Returns a time when the gesture has started. + \property QGesture::startTime + + \brief The time when the gesture has started. */ QDateTime QGesture::startTime() const { @@ -165,7 +181,9 @@ QDateTime QGesture::startTime() const } /*! - Returns a duration time of a gesture. + \property QGesture::duration + + \brief The duration time of a gesture. */ uint QGesture::duration() const { @@ -173,7 +191,9 @@ uint QGesture::duration() const } /*! - Returns the start position of the pointer. + \property QGesture::startPos + + \brief The start position of the pointer. */ QPoint QGesture::startPos() const { @@ -181,7 +201,9 @@ QPoint QGesture::startPos() const } /*! - Returns the last recorded position of the pointer. + \property QGesture::lastPos + + \brief The last recorded position of the pointer. */ QPoint QGesture::lastPos() const { @@ -189,7 +211,9 @@ QPoint QGesture::lastPos() const } /*! - Returns the position of the pointer. + \property QGesture::pos + + \brief The current position of the pointer. */ QPoint QGesture::pos() const { @@ -206,28 +230,11 @@ QPoint QGesture::pos() const information is also contained in the QGesture object in it's properties. */ -QPannableGesture::QPannableGesture(QObject *parent, const QPoint &startPos, - const QPoint &lastPos, const QPoint &pos, const QRect &rect, - const QPoint &hotSpot, const QDateTime &startTime, - uint duration, Qt::GestureState state) - : QGesture(*new QPannableGesturePrivate, parent, - qt_getStandardGestureTypeName(Qt::PanGesture), state) -{ - Q_D(QPannableGesture); - d->init(startPos, lastPos, pos, rect, hotSpot, startTime, duration); - setProperty("lastDirection", QVariant::fromValue(Qt::NoDirection)); - setProperty("direction", QVariant::fromValue(Qt::NoDirection)); -} /*! - Destroys the QPannableGesture object. -*/ -QPannableGesture::~QPannableGesture() -{ -} + \property QPannableGesture::lastDirection -/*! - Returns the last recorded direction of panning. + \brief The last recorded direction of panning. */ Qt::DirectionType QPannableGesture::lastDirection() const { @@ -235,7 +242,9 @@ Qt::DirectionType QPannableGesture::lastDirection() const } /*! - Returns the current direction of panning. + \property QPannableGesture::direction + + \brief The current direction of panning. */ Qt::DirectionType QPannableGesture::direction() const { diff --git a/src/gui/kernel/qgesture.h b/src/gui/kernel/qgesture.h index b2999d7..4e692be 100644 --- a/src/gui/kernel/qgesture.h +++ b/src/gui/kernel/qgesture.h @@ -107,13 +107,10 @@ class Q_GUI_EXPORT QPannableGesture : public QGesture Q_OBJECT Q_DECLARE_PRIVATE(QPannableGesture) -public: - QPannableGesture(QObject *parent, const QPoint &startPos, - const QPoint &lastPos, const QPoint &pos, const QRect &rect, - const QPoint &hotSpot, const QDateTime &startTime, - uint duration, Qt::GestureState state); - ~QPannableGesture(); + Q_PROPERTY(Qt::DirectionType lastDirection READ lastDirection) + Q_PROPERTY(Qt::DirectionType direction READ direction) +public: Qt::DirectionType lastDirection() const; Qt::DirectionType direction() const; }; diff --git a/src/gui/kernel/qwidget.cpp b/src/gui/kernel/qwidget.cpp index d37f360..9c0c404 100644 --- a/src/gui/kernel/qwidget.cpp +++ b/src/gui/kernel/qwidget.cpp @@ -11032,7 +11032,7 @@ QWindowSurface *QWidget::windowSurface() const Returns the id of the gesture. - \sa grabGesture(), releaseGesture(), setGestureEnabled() + \sa releaseGesture(), setGestureEnabled() */ int QWidget::grabGesture(const QString &gesture) { @@ -11055,7 +11055,7 @@ int QWidgetPrivate::grabGesture(int id) Returns the id of the gesture. - \sa grabGesture(), releaseGesture(), setGestureEnabled() + \sa releaseGesture(), setGestureEnabled() */ int QWidget::grabGesture(Qt::GestureType gesture) { @@ -11066,7 +11066,7 @@ int QWidget::grabGesture(Qt::GestureType gesture) Unsubscribes the widget from a gesture, which is specified by the \a gestureId. - \sa grabGesture(),setGestureEnabled() + \sa grabGesture(), setGestureEnabled() */ void QWidget::releaseGesture(int gestureId) { @@ -11087,7 +11087,7 @@ void QWidget::releaseGesture(int gestureId) \sa grabGesture(), releaseGesture() */ -void setGestureEnabled(int gestureId, bool enable) +void QWidget::setGestureEnabled(int gestureId, bool enable) { //### } -- cgit v0.12