Changeset 474 for trunk/src/gui/kernel


Ignore:
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:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/gui/kernel/qmime_pm.cpp

    r471 r474  
    14251425*/
    14261426
    1427 // @todo add DnD interfaces docs
     1427/*!
     1428    \fn DragWorker *QPMMime::dragWorkerFor(const QString &mimeType,
     1429                                           QMimeData *mimeData)
     1430
     1431    Returns a DragWorker instance suitable for converting \a mimeType to a set
     1432    of drag items for the Direct Manipulation (Drag And Drop) session. If this
     1433    converter does not support the given MIME type, this method should return 0.
     1434
     1435    See the QPMMime::DragWorker class description for more information.
     1436
     1437    The default implementation of this method returns 0.
     1438*/
     1439
     1440/*!
     1441    \fn DropWorker *QPMMime::dropWorkerFor(DRAGINFO *info)
     1442
     1443    Returns a DropWorker instance suitable for converting drag items represented
     1444    by the \a info structure to MIME data when these items are dropped on a Qt
     1445    widget at the end of the Direct manipulation session. If this converter does
     1446    not support the given set of drag items, this method should return 0.
     1447
     1448    See the QPMMime::DropWorker class description for more information.
     1449
     1450    The default implementation of this method returns 0.
     1451*/
     1452
     1453/*!
     1454    \class QPMMime::DragWorker
     1455
     1456    This class is responsible for providing the drag items for the Direct
     1457    Manipulation session.
     1458
     1459    Drag workers can be super exclusive (solely responsible for converting the
     1460    given mime type to a set of DRAGITEM structures), exclusive (cannot coexist
     1461    with other workers but don't manage the DRAGINFO/DRAGITEM creation), or
     1462    cooperative (can coexist with other drag workers and share the same set of
     1463    DRAGITEM structures in order to represent different mime data types). As
     1464    opposed to super exclusive workers (identified by isExclusive() returning
     1465    TRUE and by itemCount() returning zero), exclusive and cooperative workers
     1466    do not create DRAGINFO/DRAGITEM structures on their own, they implement a
     1467    subset of methods that is used by the drag manager to fill drag structures
     1468    it creates.
     1469
     1470    If a super exlusive or an exclusive worker is encoundered when starting the
     1471    drag session, it will be used only if there are no any other workers found
     1472    for \b other mime types of the object being dragged. If a cooperative worker
     1473    with the item count greater than one is encountered, it will be used only if
     1474    all other found workers are also cooperative and require the same number of
     1475    items. In both cases, if the above conditions are broken, the respective
     1476    workers are discarded (ignored). Instead, a special fall-back cooperative
     1477    worker (that requires a single DRAGITEM, supports any mime type and can
     1478    coexist with other one-item cooperative workers) will be used for the given
     1479    mime type.
     1480
     1481    \note Subclasses must NOT free the DRAGINFO structure they allocated and
     1482    returned by createDragInfo().
     1483
     1484    \note Every exclusive drag worker must implement createDragInfo() and must
     1485    not implement composeFormatSting()/canRender()/prepare()/defaultFileType().
     1486    And vice versa, every cooperative drag worker must implement the latter
     1487    three functions but not the former two.
     1488
     1489    \note The return value of cleanup() is whether the Move operation is
     1490    disallowed by this worker or not (if the worker doesn't participate in the
     1491    DND session, it should return FALSE, to let other workers allow Move).
     1492*/
     1493
     1494/*!
     1495    \class QPMMime::DefaultDragWorker
     1496
     1497    This class is a DragWorker implementation that supports standard
     1498    DRM_SHAREDMEM and DRM_OS2FILE and rendering mechanisms. It uses
     1499    QPMMime::DefaultDragWorker::Provider subclasses to map mime types of the
     1500    object being dragged to rendering formats and apply preprocessing of data
     1501    before rendering.
     1502*/
     1503
     1504/*!
     1505  \class QPMMime::DropWorker
     1506
     1507    This class is responsible for interpreting the drag items after the Direct
     1508    Manipulation session ends up in a drop.
     1509
     1510    Drop workers can be exclusive (solely responsible for converting the given
     1511    set of DRAGITEM structures) or cooperative (can coexist with other drop
     1512    workers in order to produce different mime data types from the same set of
     1513    DRAGITEM structures). If an exclusive drop worker is encountered when
     1514    processing the drop event, all other workers are silently ignored.
     1515
     1516    \note Subclasses must NOT free the DRAGINFO structure pointed to by info().
     1517
     1518    \note Subclasses must NOT send DM_ENDCONVERSATION to the source.
     1519*/
     1520
     1521/*!
     1522    \class QPMMime::DefaultDropWorker
     1523
     1524    This class is a DropWorker implementation that supports standard
     1525    DRM_SHAREDMEM and DRM_OS2FILE and rendering mechanisms. It uses
     1526    QPMMime::DefaultDropWorker::Provider subclasses to map various rendering
     1527    formats to particular mime types and apply postprocessing of data after
     1528    rendering.
     1529*/
    14281530
    14291531// static
     
    15021604}
    15031605
     1606
     1607
     1608
     1609
     1610
     1611
    15041612QString QPMMime::formatName(ULONG format)
    15051613{
     
    15641672}
    15651673
    1566 /*! \internal
    1567 
     1674/*!
    15681675    Checks that the given drag \a item supports the DRM_OS2FILE rendering
    15691676    mechanism and can be rendered by a target w/o involving the source (i.e.,
     
    16441751}
    16451752
    1646 /*! \internal
    1647 
     1753/*!
    16481754    Parses the given \a rmfs list (full rendering mechanism/format specification)
    16491755    and builds a \a list of mechanism branches. Each mechanism branch is also a
     
    17691875}
    17701876
    1771 /*! \internal
    1772 
     1877/*!
    17731878    Splits the given \a rmf (rendering mechanism/format pair) to a \a mechanism
    17741879    and a \a format string. Returns FALSE if fails to parse \a rmf.
     
    17911896}
    17921897
    1793 /*! \internal */
     1898/*!
     1899    Returns the default drag worker that works in cooperative mode.
     1900
     1901    See the DefaultDragWorker class description for more information.
     1902 */
    17941903// static
    17951904QPMMime::DefaultDragWorker *QPMMime::defaultCoopDragWorker()
     
    17991908}
    18001909
     1910
     1911
     1912
     1913
     1914
    18011915// static
    1802 /*! \internal */
    18031916QPMMime::DefaultDragWorker *QPMMime::defaultExclDragWorker()
    18041917{
     
    18071920}
    18081921
    1809 /*! \internal */
     1922/*!
     1923    Returns the default drop worker.
     1924
     1925    See the DefaultDropWorker class description for more information.
     1926 */
    18101927// static
    18111928QPMMime::DefaultDropWorker *QPMMime::defaultDropWorker()
Note: See TracChangeset for help on using the changeset viewer.