Changeset 986 for trunk/src/gui

Timestamp:

Aug 16, 2011, 12:57:10 AM (14 years ago)

Author:

Dmitry A. Kuminov

Message:

OS/2: Add missing documentation to methods.

Location:

trunk/src/gui/kernel

Files:

• qmime_pm.cpp (modified) (27 diffs)
• qwidget_pm.cpp (modified) (1 diff)

trunk/src/gui/kernel/qmime_pm.cpp

@@ -290 +290 @@
 }
 
+/*!
+    Constructs a new default drag worker instance. The \a exclusive flag
+    defines if this worker is exclusive (see isExclusive() for details).
+*/
 QPMMime::DefaultDragWorker::DefaultDragWorker(bool exclusive)
     : d(new Data(this, exclusive))
@@ -297 +301 @@
 }
 
+/*!
+    Destroys the instance.
+*/
 QPMMime::DefaultDragWorker::~DefaultDragWorker()
 {
@@ -303 +310 @@
 }
 
+/*!
+    \reimp
+*/
 bool QPMMime::DefaultDragWorker::cleanup(bool isCancelled)
 {
@@ -341 +351 @@
 }
 
+/*!
+    \reimp
+*/
 bool QPMMime::DefaultDragWorker::isExclusive() const
 {
@@ -346 +359 @@
 }
 
+/*!
+    \reimp
+*/
 ULONG QPMMime::DefaultDragWorker::itemCount() const
 {
@@ -351 +367 @@
 }
 
+/*!
+    \reimp
+*/
 ULONG QPMMime::DefaultDragWorker::hwnd() const
 {
@@ -356 +375 @@
 }
 
+/*!
+    \reimp
+*/
 QByteArray QPMMime::DefaultDragWorker::composeFormatString()
 {
@@ -392 +414 @@
 }
 
+/*!
+    \reimp
+*/
 bool QPMMime::DefaultDragWorker::prepare(const char *drm, const char *drf,
                                           DRAGITEM *item, ULONG itemIndex)
@@ -434 +459 @@
 }
 
+/*!
+    \reimp
+*/
 void QPMMime::DefaultDragWorker::defaultFileType(QString &type,
                                                  QString &ext)
@@ -676 +704 @@
 }
 
+/*!
+    Adds \a provider that understands the \a drf format and provides \a itemCnt
+    items to the list of providers.
+
+    Returns \c true on success or \c false otherwise (e.g. on attempts to add
+    more than one a provider to the exclusive worker or to add a provider
+    supporting a different count of items compared to providers already in the
+    list).
+*/
 bool QPMMime::DefaultDragWorker::addProvider(const QByteArray &drf, Provider *provider,
                                              ULONG itemCnt /* = 1 */)
@@ -701 +738 @@
 }
 
+/*!
+    Returns \c true if the default drag worker can render using the mechanism
+    specified in \a drm.
+*/
 // static
 bool QPMMime::DefaultDragWorker::canRender(const char *drm)
@@ -748 +789 @@
 };
 
+/*!
+    Constructs a new default drop worker instance.
+*/
 QPMMime::DefaultDropWorker::DefaultDropWorker() : d(new Data(this))
 {
@@ -755 +799 @@
 }
 
+/*!
+    Destroys the instance.
+*/
 QPMMime::DefaultDropWorker::~DefaultDropWorker()
 {
@@ -760 +807 @@
 }
 
+/*!
+    \reimp
+*/
 void QPMMime::DefaultDropWorker::cleanup(bool isAccepted)
 {
@@ -776 +826 @@
 }
 
+/*!
+    \reimp
+*/
 bool QPMMime::DefaultDropWorker::isExclusive() const
 {
@@ -781 +834 @@
 }
 
+/*!
+    \reimp
+*/
 bool QPMMime::DefaultDropWorker::hasFormat(const QString &mimeType) const
 {
@@ -786 +842 @@
 }
 
+/*!
+    \reimp
+*/
 QStringList QPMMime::DefaultDropWorker::formats() const
 {
@@ -824 +883 @@
 }
 
+/*!
+    \reimp
+*/
 QVariant QPMMime::DefaultDropWorker::retrieveData(const QString &mimeType,
                                                   QVariant::Type preferredType) const
@@ -1132 +1194 @@
 }
 
+/*!
+    Adds \a provider that understands the \a mimeType format to the list of
+    providers.
+
+    Returns \c true on success or \c false otherwise (e.g. if the list already
+    contains an exclusive provider or other providers supporting the given MIME
+    type).
+*/
 bool QPMMime::DefaultDropWorker::addProvider(const QString &mimeType,
                                              Provider *provider)
@@ -1145 +1215 @@
 }
 
+/*!
+    Adds \a provider that understands the \a mimeType format to the list of
+    providers. The provider is marked as exclusive (responsive for converting
+    the whole DRAGITEM structure).
+
+    Returns \c true on success or \c false otherwise (e.g. if the list already
+    contains an exclusive provider).
+*/
 bool QPMMime::DefaultDropWorker::addExclusiveProvider(const QString &mimeType,
                                                       Provider *provider)
@@ -1158 +1236 @@
 }
 
+/*!
+    Returns \c true if the given \a item can be rendered by the default drop
+    worker can render in the \a drf rendering format.
+*/
 // static
 bool QPMMime::DefaultDropWorker::canRender(DRAGITEM *item, const char *drf)
@@ -1488 +1570 @@
     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
+    \c true and by itemCount() returning 0), 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
@@ -1504 +1586 @@
     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).
+    not implement composeFormatSting()/prepare()/defaultFileType(). And vice
+    versa, every cooperative drag worker must implement the latter three
+    functions but not the former two.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::DragWorker()
+
+    Constructs a new instance.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::~DragWorker()
+
+    Destroys the instance.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::source() const
+
+    Returns the source of the current drag operation.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::init()
+
+    Initializes the instance before the drag operation.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::cleanup(bool isCancelled)
+
+    Performs cleanup after the drag operation. If the drag operation was
+    cancelled, \a isCancelled will be \c true.
+
+    Returns \c true if the Move operation is disallowed by this worker. Note
+    that if this worker doesn't participate in a given DnD session, it should
+    return \c false to let other workers allow Move.
+
+    Must be reimplemented in subclasses.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::isExclusive() const
+
+    Returns \c true if this is an exclusive drag worker.
+
+    Must be reimplemented in subclasses.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::itemCount() const
+
+    Returns the number of DRAGITEM elements this drag worker needs to represent
+    its data. If isExclusive() is \c true and this method returns 0, this drag
+    worker will manage creation of the DRAGINFO structure on its onwn.
+
+    Must be reimplemented in subclasses.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::hwnd() const
+
+    Returns a window handle to be associated with DRAGITEM elemetns of this drag
+    worker.
+
+    Must be reimplemented in subclasses.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::createDragInfo(const QString &targetName, USHORT
+                                            supportedOps)
+
+    Creates a new DRAGINFO structure for the drag operation with the suggested
+    \a targetName and supported operations represented by \a supportedOps.
+
+    \note The created structure is owned by QPMMime and should be not freed by
+    subclasses.
+
+    Must be reimplemented in subclasses if the isExclusive() implementation
+    returns \c true and itemCount() returns 0.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::composeFormatString()
+
+    Returns a format string containing "<mechanism,format>" pairs supported by
+    this drag worker.
+
+    Must be reimplemented in subclasses if the isExclusive() implementation
+    returns \c false.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::prepare(const char *drm, const char *drf,
+                                     DRAGITEM *item, ULONG itemIndex)
+
+    Prepares this worker for the drop operation of the \a item having
+    \a itemIndex using the mechanism and format specified in \a drm and \a drf,
+    respectively.
+
+    Must be reimplemented in subclasses if the isExclusive() implementation
+    returns \c false.
+*/
+
+/*!
+    \fn QPMMime::DragWorker::defaultFileType(QString &type, QString &ext)
+
+    Returns the default file \a type (and extension \a ext) for the data
+    represented by this worker.
+
+    Must be reimplemented in subclasses if the isExclusive() implementation
+    returns \c false.
 */
 
@@ -1528 +1713 @@
 
 /*!
+  \class QPMMime::DefaultDragWorker::Provider
+
+    This class is used to map mime types of the object being dragged to
+    rendering formats and apply preprocessing of data before rendering.
+*/
+
+/*!
+    \fn QPMMime::DefaultDragWorker::Provider::format(const char *drf) const
+
+    Returns a MIME format string for the given \a drf rendering format that this
+    provider can provide. Returns a null string if the format is unsupported.
+*/
+
+/*!
+    \fn QPMMime::DefaultDragWorker::Provider::provide(const char *drf,
+                                                      const QByteArray &allData,
+                                                      ULONG itemIndex,
+                                                      QByteArray &itemData)
+
+    If the \a drf format is supported by this provider, converts \a allData to
+    it, stores the result in \a itemData and returns \c true. In case of
+    multi-item data, \a itemIndex is an index of the item in question.
+*/
+
+/*!
+    \fn QPMMime::DefaultDragWorker::Provider::fileType(const char *drf, QString
+                                                       &type, QString &ext)
+
+    If the \a drf format is supported by this provider, returns the file type in
+    \a type and the extension in \a ext for the data it provides.
+*/
+
+/*!
   \class QPMMime::DropWorker
 
@@ -1539 +1757 @@
     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.
+    \note Subclasses must \b not send \c DM_ENDCONVERSATION to the source.
+*/
+
+/*!
+    \fn QPMMime::DropWorker::DropWorker()
+
+    Constructs a new instance.
+*/
+
+/*!
+    \fn QPMMime::DropWorker::~DropWorker()
+
+    Destroys the instance.
+*/
+
+/*!
+    \fn QPMMime::DropWorker::info() const
+
+    Returns a pointer to the DRAGINFO sctructure describing the current
+    drag operation.
+
+    \note Subclasses must \b not free this DRAGINFO structure.
+*/
+
+/*!
+    \fn QPMMime::DropWorker::init()
+
+    Initializes the instance before the drop operation.
+*/
+
+/*!
+    \fn QPMMime::DropWorker::cleanup(bool isAccepted)
+
+    Performs the cleanup after the drop operation. If the drag was accepted,
+    \a isAccepted will be \c true.
+*/
+
+/*!
+    \fn QPMMime::DropWorker::isExclusive() const
+
+    Returns \c true if this is an exclusive drop worker.
+
+    Must be reimplemented in subclasses.
+*/
+
+/*!
+    \fn QPMMime::DropWorker::hasFormat(const QString &mimeType) const
+
+    Returns \c true if this drop worker supports the given \a mimeType.
+
+    Must be reimplemented in subclasses.
+*/
+
+/*!
+    \fn QPMMime::DropWorker::formats() const
+
+    Returns a list of all MIME types supported by this drop worker.
+
+    Must be reimplemented in subclasses.
+*/
+
+/*!
+    \fn QPMMime::DropWorker::retrieveData(const QString &mimeType,
+                                          QVariant::Type preferredType) const
+
+    Returns data represented by this drag worker converted to the given
+    \a mimeType. The QVariant type preferred by the caller is indicated by
+    \a preferredType.
+
+    Must be reimplemented in subclasses.
 */
 
@@ -1552 +1837 @@
     formats to particular mime types and apply postprocessing of data after
     rendering.
+*/
+
+/*!
+    \class QPMMime::DefaultDropWorker::Provider
+
+    This class is used to map rendering formats to particular mime and apply
+    preprocessing of data after rendering.
+*/
+
+/*!
+    \fn QPMMime::DefaultDropWorker::Provider::drf(const QString &mimeType) const
+
+    Returns a rendering format string for the given \a mimeType that this
+    provider can provide. Returns a null string if the MIME type is unsupported.
+*/
+
+/*!
+    \fn QPMMime::DefaultDropWorker::Provider::provide(const QString &mimeType
+                                                      ULONG itemIndex,
+                                                      const QByteArray
+                                                      &itemData, QByteArray
+                                                      &allData)
+
+    If the \a mimeType is supported by this provider, converts \a itemData to
+    it, stores the result in \a allData and returns \c true. In case of
+    multi-item data, \a itemIndex is an index of the item in question.
 */
 
@@ -1701 +2012 @@
     mechanism and can be rendered by a target w/o involving the source (i.e.,
     \c DRM_OS2FILE is the first supported format and a valid file name with full
-    path is provided). If the function returns \c TRUE, \a fullName (if not
+    path is provided). If the function returns \c true, \a fullName (if not
     \c NULL) will be assigned the item's full source file name (composed from
     \c hstrContainerName and \c hstrSourceName fields).

trunk/src/gui/kernel/qwidget_pm.cpp

@@ -239 +239 @@
     with the given region using the \a op operation (CRGN_*); otherwise they are
     directly validated on the window. The scope of relativeness is defined by
-    the \fl argument which is one or more PWO_* flags OR-ed together.
+    the \a flags argument which is one or more PWO_* flags OR-ed together.
 
     Returns the complexity of the combined region (only when \a hrgn is not