From 54c6d73c208153f9f27379ba7682fff7ef119e3e Mon Sep 17 00:00:00 2001 From: Marco Martin Date: Tue, 10 Jan 2012 13:32:41 +0100 Subject: [PATCH] document all drag and drop --- .../draganddrop/DeclarativeDragArea.h | 51 +++++++-- .../draganddrop/DeclarativeDragDropEvent.h | 101 +++++++++++++----- .../draganddrop/DeclarativeDropArea.h | 50 ++++++--- .../draganddrop/DeclarativeMimeData.h | 34 +++++- 4 files changed, 185 insertions(+), 51 deletions(-) diff --git a/declarativeimports/draganddrop/DeclarativeDragArea.h b/declarativeimports/draganddrop/DeclarativeDragArea.h index c25b96ab8..31206917c 100644 --- a/declarativeimports/draganddrop/DeclarativeDragArea.h +++ b/declarativeimports/draganddrop/DeclarativeDragArea.h @@ -31,14 +31,49 @@ class DeclarativeMimeData; class DeclarativeDragArea : public QDeclarativeItem { - Q_OBJECT - Q_PROPERTY(QDeclarativeComponent* delegate READ delegate WRITE setDelegate NOTIFY delegateChanged RESET resetDelegate) - Q_PROPERTY(QDeclarativeItem* source READ source WRITE setSource NOTIFY sourceChanged RESET resetSource) - Q_PROPERTY(QDeclarativeItem* target READ source NOTIFY targetChanged) - Q_PROPERTY(DeclarativeMimeData* mimeData READ mimeData CONSTANT) - Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled NOTIFY enabledChanged) //TODO: Should call setAcceptDrops() - Q_PROPERTY(Qt::DropActions supportedActions READ supportedActions WRITE setSupportedActions NOTIFY supportedActionsChanged) - Q_PROPERTY(Qt::DropAction defaultAction READ defaultAction WRITE setDefaultAction NOTIFY defaultActionChanged) + Q_OBJECT + + /** + * The delegate is the item that will be displayed next to the mouse cursor during the drag and drop operation. + * It usually consists of a large, semi-transparent icon representing the data being dragged. + */ + Q_PROPERTY(QDeclarativeComponent* delegate READ delegate WRITE setDelegate NOTIFY delegateChanged RESET resetDelegate) + + /** + * The QML element that is the source of the resulting drag and drop operation. This can be defined to any item, and will + * be available to the DropArea as event.data.source + */ + Q_PROPERTY(QDeclarativeItem* source READ source WRITE setSource NOTIFY sourceChanged RESET resetSource) + + //TODO: to be implemented + Q_PROPERTY(QDeclarativeItem* target READ source NOTIFY targetChanged) + + /** + * the mime data of the drag operation + * @see DeclarativeMimeData + */ + Q_PROPERTY(DeclarativeMimeData* mimeData READ mimeData CONSTANT) + + /** + * If false no drag operation will be generate + */ + Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled NOTIFY enabledChanged) //TODO: Should call setAcceptDrops() + + /** + * Supported operations, a combination of + * Qt.CopyAction + * Qt.MoveAction + * Qt.LinkAction + * Qt.ActionMask + * Qt.IgnoreAction + * Qt.TargetMoveAction + */ + Q_PROPERTY(Qt::DropActions supportedActions READ supportedActions WRITE setSupportedActions NOTIFY supportedActionsChanged) + + /** + * The default action will be performed during a drag when no modificators are pressed. + */ + Q_PROPERTY(Qt::DropAction defaultAction READ defaultAction WRITE setDefaultAction NOTIFY defaultActionChanged) public: diff --git a/declarativeimports/draganddrop/DeclarativeDragDropEvent.h b/declarativeimports/draganddrop/DeclarativeDragDropEvent.h index e84876d2b..27da31d94 100644 --- a/declarativeimports/draganddrop/DeclarativeDragDropEvent.h +++ b/declarativeimports/draganddrop/DeclarativeDragDropEvent.h @@ -30,37 +30,90 @@ class DeclarativeDragDropEvent : public QObject { - Q_OBJECT - Q_PROPERTY(int x READ x) - Q_PROPERTY(int y READ y) - Q_PROPERTY(int buttons READ buttons) - Q_PROPERTY(int modifiers READ modifiers) - Q_PROPERTY(DeclarativeMimeData* mimeData READ mimeData) - Q_PROPERTY(Qt::DropActions possibleActions READ possibleActions) - Q_PROPERTY(Qt::DropAction proposedAction READ proposedAction) + Q_OBJECT + + /** + * The mouse X position of the event relative to the view that sent the event. + */ + Q_PROPERTY(int x READ x) + + /** + * The mouse Y position of the event relative to the view that sent the event. + */ + Q_PROPERTY(int y READ y) + + /** + * The pressed mouse buttons. + * A combination of: + * Qt.NoButton The button state does not refer to any button (see QMouseEvent::button()). + * Qt.LeftButton The left button is pressed, or an event refers to the left button. (The left button may be the right button on left-handed mice.) + * Qt.RightButton The right button. + * Qt.MidButton The middle button. + * Qt.MiddleButton MidButton The middle button. + * Qt.XButton1 The first X button. + * Qt.XButton2 The second X button. + */ + Q_PROPERTY(int buttons READ buttons) + + /** + * Pressed keyboard modifiers, a combination of: + * Qt.NoModifier No modifier key is pressed. + * Qt.ShiftModifier A Shift key on the keyboard is pressed. + * Qt.ControlModifier A Ctrl key on the keyboard is pressed. + * Qt.AltModifier An Alt key on the keyboard is pressed. + * Qt.MetaModifier A Meta key on the keyboard is pressed. + * Qt.KeypadModifier A keypad button is pressed. + * Qt.GroupSwitchModifier X11 only. A Mode_switch key on the keyboard is pressed. + */ + Q_PROPERTY(int modifiers READ modifiers) + + /** + * The mime data of this operation + * @see DeclarativeMimeData + */ + Q_PROPERTY(DeclarativeMimeData* mimeData READ mimeData) + + /** + * The possible different kind of action that can be done in the drop, is a combination of: + * Qt.CopyAction 0x1 Copy the data to the target. + * Qt.MoveAction 0x2 Move the data from the source to the target. + * Qt.LinkAction 0x4 Create a link from the source to the target. + * Qt.ActionMask 0xff + * Qt.IgnoreAction 0x0 Ignore the action (do nothing with the data). + * Qt.TargetMoveAction 0x8002 On Windows, this value is used when the ownership of the D&D data should be taken over by the target application, i.e., the source application should not delete the data. + * On X11 this value is used to do a move. + * TargetMoveAction is not used on the Mac. + */ + Q_PROPERTY(Qt::DropActions possibleActions READ possibleActions) + + /** + * Default action + * @see possibleActions + */ + Q_PROPERTY(Qt::DropAction proposedAction READ proposedAction) public: - DeclarativeDragDropEvent(QGraphicsSceneDragDropEvent* e, QObject* parent = 0); + DeclarativeDragDropEvent(QGraphicsSceneDragDropEvent* e, QObject* parent = 0); - int x() const { return m_x; } - int y() const { return m_y; } - int buttons() const { return m_buttons; } - int modifiers() const { return m_modifiers; } - DeclarativeMimeData* mimeData() { return &m_data; } - Qt::DropAction proposedAction() const { return m_event->proposedAction(); } - Qt::DropActions possibleActions() const { return m_event->possibleActions(); } + int x() const { return m_x; } + int y() const { return m_y; } + int buttons() const { return m_buttons; } + int modifiers() const { return m_modifiers; } + DeclarativeMimeData* mimeData() { return &m_data; } + Qt::DropAction proposedAction() const { return m_event->proposedAction(); } + Qt::DropActions possibleActions() const { return m_event->possibleActions(); } -public slots: - void accept(int action); +public Q_SLOTS: + void accept(int action); private: - int m_x; - int m_y; - Qt::MouseButtons m_buttons; - Qt::KeyboardModifiers m_modifiers; - DeclarativeMimeData m_data; - QGraphicsSceneDragDropEvent* m_event; + int m_x; + int m_y; + Qt::MouseButtons m_buttons; + Qt::KeyboardModifiers m_modifiers; + DeclarativeMimeData m_data; + QGraphicsSceneDragDropEvent* m_event; }; #endif // DECLARATIVEDRAGDROPEVENT_H diff --git a/declarativeimports/draganddrop/DeclarativeDropArea.h b/declarativeimports/draganddrop/DeclarativeDropArea.h index 0394ecf6b..f562cff1c 100644 --- a/declarativeimports/draganddrop/DeclarativeDropArea.h +++ b/declarativeimports/draganddrop/DeclarativeDropArea.h @@ -30,27 +30,49 @@ class DeclarativeDragDropEvent; class DeclarativeDropArea : public QDeclarativeItem { - Q_OBJECT - Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled NOTIFY enabledChanged) + Q_OBJECT + + /** + * If false the area will receive no drop events + */ + Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled NOTIFY enabledChanged) public: - DeclarativeDropArea(QDeclarativeItem *parent=0); - bool isEnabled() const; - void setEnabled(bool enabled); + DeclarativeDropArea(QDeclarativeItem *parent=0); + bool isEnabled() const; + void setEnabled(bool enabled); -signals: - void dragEnter(DeclarativeDragDropEvent* event); - void dragLeave(DeclarativeDragDropEvent* event); - void drop(DeclarativeDragDropEvent* event); - void enabledChanged(); +Q_SIGNALS: + /** + * Emitted when the mouse cursor dragging something enters in the drag area + * @arg DeclarativeDragDropEvent description of the dragged content + * @see DeclarativeDragDropEvent + */ + void dragEnter(DeclarativeDragDropEvent* event); + + /** + * Emitted when the mouse cursor dragging something leaves the drag area + * @arg DeclarativeDragDropEvent description of the dragged content + * @see DeclarativeDragDropEvent + */ + void dragLeave(DeclarativeDragDropEvent* event); + + /** + * Emitted when the user drops something in the area + * @arg DeclarativeDragDropEvent description of the dragged content + * @see DeclarativeDragDropEvent + */ + void drop(DeclarativeDragDropEvent* event); + + void enabledChanged(); protected: - void dragEnterEvent(QGraphicsSceneDragDropEvent *event); - void dragLeaveEvent(QGraphicsSceneDragDropEvent *event); - void dropEvent(QGraphicsSceneDragDropEvent *event); + void dragEnterEvent(QGraphicsSceneDragDropEvent *event); + void dragLeaveEvent(QGraphicsSceneDragDropEvent *event); + void dropEvent(QGraphicsSceneDragDropEvent *event); private: - bool m_enabled; + bool m_enabled; }; #endif diff --git a/declarativeimports/draganddrop/DeclarativeMimeData.h b/declarativeimports/draganddrop/DeclarativeMimeData.h index e5c453443..7cec9aaac 100644 --- a/declarativeimports/draganddrop/DeclarativeMimeData.h +++ b/declarativeimports/draganddrop/DeclarativeMimeData.h @@ -33,12 +33,36 @@ class DeclarativeMimeData : public QMimeData { Q_OBJECT - Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged) - Q_PROPERTY(QString html READ html WRITE setHtml NOTIFY htmlChanged) - Q_PROPERTY(QUrl url READ url WRITE setUrl NOTIFY urlChanged) + /** + * A plain text (MIME type text/plain) representation of the data. + */ + Q_PROPERTY(QString text READ text WRITE setText NOTIFY textChanged) + + /** + * A string if the data stored in the object is HTML (MIME type text/html); otherwise returns an empty string. + */ + Q_PROPERTY(QString html READ html WRITE setHtml NOTIFY htmlChanged) + + /** + * Url contained in the mimedata + */ + Q_PROPERTY(QUrl url READ url WRITE setUrl NOTIFY urlChanged) + + /** + * A list of URLs contained within the MIME data object. + * URLs correspond to the MIME type text/uri-list. + */ Q_PROPERTY(QVariantList urls READ urls WRITE setUrls NOTIFY urlsChanged) - Q_PROPERTY(QColor color READ color WRITE setColor NOTIFY colorChanged) - Q_PROPERTY(QDeclarativeItem* source READ source WRITE setSource NOTIFY sourceChanged) + + /** + * A color if the data stored in the object represents a color (MIME type application/x-color); otherwise QColor(). + */ + Q_PROPERTY(QColor color READ color WRITE setColor NOTIFY colorChanged) + + /** + * The graphical item on the scene that started the drag event. It may be null. + */ + Q_PROPERTY(QDeclarativeItem* source READ source WRITE setSource NOTIFY sourceChanged) //TODO: Image property public: