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 @@
 }
 
+
+
+
+
 QPMMime::DefaultDragWorker::DefaultDragWorker(bool exclusive)
     : d(new Data(this, exclusive))
@@ -297 +301 @@
 }
 
+
+
+
 QPMMime::DefaultDragWorker::~DefaultDragWorker()
 {
@@ -303 +310 @@
 }
 
+
+
+
 bool QPMMime::DefaultDragWorker::cleanup(bool isCancelled)
 {
@@ -341 +351 @@
 }
 
+
+
+
 bool QPMMime::DefaultDragWorker::isExclusive() const
 {
@@ -346 +359 @@
 }
 
+
+
+
 ULONG QPMMime::DefaultDragWorker::itemCount() const
 {
@@ -351 +367 @@
 }
 
+
+
+
 ULONG QPMMime::DefaultDragWorker::hwnd() const
 {
@@ -356 +375 @@
 }
 
+
+
+
 QByteArray QPMMime::DefaultDragWorker::composeFormatString()
 {
@@ -392 +414 @@
 }
 
+
+
+
 bool QPMMime::DefaultDragWorker::prepare(const char *drm, const char *drf,
                                           DRAGITEM *item, ULONG itemIndex)
@@ -434 +459 @@
 }
 
+
+
+
 void QPMMime::DefaultDragWorker::defaultFileType(QString &type,
                                                  QString &ext)
@@ -676 +704 @@
 }
 
+
+
+
+
+
+
+
+
+
 bool QPMMime::DefaultDragWorker::addProvider(const QByteArray &drf, Provider *provider,
                                              ULONG itemCnt /* = 1 */)
@@ -701 +738 @@
 }
 
+
+
+
+
 // static
 bool QPMMime::DefaultDragWorker::canRender(const char *drm)
@@ -748 +789 @@
 };
 
+
+
+
 QPMMime::DefaultDropWorker::DefaultDropWorker() : d(new Data(this))
 {
@@ -755 +799 @@
 }
 
+
+
+
 QPMMime::DefaultDropWorker::~DefaultDropWorker()
 {
@@ -760 +807 @@
 }
 
+
+
+
 void QPMMime::DefaultDropWorker::cleanup(bool isAccepted)
 {
@@ -776 +826 @@
 }
 
+
+
+
 bool QPMMime::DefaultDropWorker::isExclusive() const
 {
@@ -781 +834 @@
 }
 
+
+
+
 bool QPMMime::DefaultDropWorker::hasFormat(const QString &mimeType) const
 {
@@ -786 +842 @@
 }
 
+
+
+
 QStringList QPMMime::DefaultDropWorker::formats() const
 {
@@ -824 +883 @@
 }
 
+
+
+
 QVariant QPMMime::DefaultDropWorker::retrieveData(const QString &mimeType,
                                                   QVariant::Type preferredType) const
@@ -1132 +1194 @@
 }
 
+
+
+
+
+
+
+
+
 bool QPMMime::DefaultDropWorker::addProvider(const QString &mimeType,
                                              Provider *provider)
@@ -1145 +1215 @@
 }
 
+
+
+
+
+
+
+
+
 bool QPMMime::DefaultDropWorker::addExclusiveProvider(const QString &mimeType,
                                                       Provider *provider)
@@ -1158 +1236 @@
 }
 
+
+
+
+
 // 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
+    ), 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::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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 */
 
@@ -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 , \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 \ argument which is one or more PWO_* flags OR-ed together.
 
     Returns the complexity of the combined region (only when \a hrgn is not