Changeset 474 for trunk/src/gui/kernel

Timestamp:

Jan 25, 2010, 10:16:15 PM (15 years ago)

Author:

Dmitry A. Kuminov

Message:

gui: DnD: Added some documentation for important QPMMime classes and members.

File:

• trunk/src/gui/kernel/qmime_pm.cpp (modified) (8 diffs)

trunk/src/gui/kernel/qmime_pm.cpp

@@ -1425 +1425 @@
 */
 
-// @todo add DnD interfaces docs
+/*!
+    \fn DragWorker *QPMMime::dragWorkerFor(const QString &mimeType,
+                                           QMimeData *mimeData)
+
+    Returns a DragWorker instance suitable for converting \a mimeType to a set
+    of drag items for the Direct Manipulation (Drag And Drop) session. If this
+    converter does not support the given MIME type, this method should return 0.
+
+    See the QPMMime::DragWorker class description for more information.
+
+    The default implementation of this method returns 0.
+*/
+
+/*!
+    \fn DropWorker *QPMMime::dropWorkerFor(DRAGINFO *info)
+
+    Returns a DropWorker instance suitable for converting drag items represented
+    by the \a info structure to MIME data when these items are dropped on a Qt
+    widget at the end of the Direct manipulation session. If this converter does
+    not support the given set of drag items, this method should return 0.
+
+    See the QPMMime::DropWorker class description for more information.
+
+    The default implementation of this method returns 0.
+*/
+
+/*!
+    \class QPMMime::DragWorker
+
+    This class is responsible for providing the drag items for the Direct
+    Manipulation session.
+
+    Drag workers can be super exclusive (solely responsible for converting the
+    given mime type to a set of DRAGITEM structures), exclusive (cannot coexist
+    with other workers but don't manage the DRAGINFO/DRAGITEM creation), or
+    cooperative (can coexist with other drag workers and share the same set of
+    DRAGITEM structures in order to represent different mime data types). As
+    opposed to super exclusive workers (identified by isExclusive() returning
+    TRUE and by itemCount() returning zero), exclusive and cooperative workers
+    do not create DRAGINFO/DRAGITEM structures on their own, they implement a
+    subset of methods that is used by the drag manager to fill drag structures
+    it creates.
+
+    If a super exlusive or an exclusive worker is encoundered when starting the
+    drag session, it will be used only if there are no any other workers found
+    for \b other mime types of the object being dragged. If a cooperative worker
+    with the item count greater than one is encountered, it will be used only if
+    all other found workers are also cooperative and require the same number of
+    items. In both cases, if the above conditions are broken, the respective
+    workers are discarded (ignored). Instead, a special fall-back cooperative
+    worker (that requires a single DRAGITEM, supports any mime type and can
+    coexist with other one-item cooperative workers) will be used for the given
+    mime type.
+
+    \note Subclasses must NOT free the DRAGINFO structure they allocated and
+    returned by createDragInfo().
+
+    \note Every exclusive drag worker must implement createDragInfo() and must
+    not implement composeFormatSting()/canRender()/prepare()/defaultFileType().
+    And vice versa, every cooperative drag worker must implement the latter
+    three functions but not the former two.
+
+    \note The return value of cleanup() is whether the Move operation is
+    disallowed by this worker or not (if the worker doesn't participate in the
+    DND session, it should return FALSE, to let other workers allow Move).
+*/
+
+/*!
+    \class QPMMime::DefaultDragWorker
+
+    This class is a DragWorker implementation that supports standard
+    DRM_SHAREDMEM and DRM_OS2FILE and rendering mechanisms. It uses
+    QPMMime::DefaultDragWorker::Provider subclasses to map mime types of the
+    object being dragged to rendering formats and apply preprocessing of data
+    before rendering.
+*/
+
+/*!
+  \class QPMMime::DropWorker
+
+    This class is responsible for interpreting the drag items after the Direct
+    Manipulation session ends up in a drop.
+
+    Drop workers can be exclusive (solely responsible for converting the given
+    set of DRAGITEM structures) or cooperative (can coexist with other drop
+    workers in order to produce different mime data types from the same set of
+    DRAGITEM structures). If an exclusive drop worker is encountered when
+    processing the drop event, all other workers are silently ignored.
+
+    \note Subclasses must NOT free the DRAGINFO structure pointed to by info().
+
+    \note Subclasses must NOT send DM_ENDCONVERSATION to the source.
+*/
+
+/*!
+    \class QPMMime::DefaultDropWorker
+
+    This class is a DropWorker implementation that supports standard
+    DRM_SHAREDMEM and DRM_OS2FILE and rendering mechanisms. It uses
+    QPMMime::DefaultDropWorker::Provider subclasses to map various rendering
+    formats to particular mime types and apply postprocessing of data after
+    rendering.
+*/
 
 // static
@@ -1502 +1604 @@
 }
 
+
+
+
+
+
+
 QString QPMMime::formatName(ULONG format)
 {
@@ -1564 +1672 @@
 }
 
-/*! \internal
-
+/*!
     Checks that the given drag \a item supports the DRM_OS2FILE rendering
     mechanism and can be rendered by a target w/o involving the source (i.e.,
@@ -1644 +1751 @@
 }
 
-/*! \internal
-
+/*!
     Parses the given \a rmfs list (full rendering mechanism/format specification)
     and builds a \a list of mechanism branches. Each mechanism branch is also a
@@ -1769 +1875 @@
 }
 
-/*! \internal
-
+/*!
     Splits the given \a rmf (rendering mechanism/format pair) to a \a mechanism
     and a \a format string. Returns FALSE if fails to parse \a rmf.
@@ -1791 +1896 @@
 }
 
-/*! \internal */
+/*!
+    Returns the default drag worker that works in cooperative mode.
+
+    See the DefaultDragWorker class description for more information.
+ */
 // static
 QPMMime::DefaultDragWorker *QPMMime::defaultCoopDragWorker()
@@ -1799 +1908 @@
 }
 
+
+
+
+
+
 // static
-/*! \internal */
 QPMMime::DefaultDragWorker *QPMMime::defaultExclDragWorker()
 {
@@ -1807 +1920 @@
 }
 
-/*! \internal */
+/*!
+    Returns the default drop worker.
+
+    See the DefaultDropWorker class description for more information.
+ */
 // static
 QPMMime::DefaultDropWorker *QPMMime::defaultDropWorker()