Changeset 85681 in vbox for trunk/src/VBox/Frontends/VirtualBox

Timestamp:

Aug 11, 2020 9:36:37 AM (4 years ago)

Author:

vboxsync

Message:

DnD: Lots of documentation.

Location:

trunk/src/VBox/Frontends/VirtualBox/src/runtime

Files:

• UIDnDDataObject_win.cpp (modified) (10 diffs)
• UIDnDDataObject_win.h (modified) (1 diff)
• UIDnDDropSource_win.h (modified) (1 diff)
• UIDnDHandler.cpp (modified) (6 diffs)
• UIDnDHandler.h (modified) (1 diff)

trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIDnDDataObject_win.cpp

@@ -188 +188 @@
 }
 
-/**
- * Retrieves the data stored in this object and store the result in
- * pMedium.
- *
- * @return  IPRT status code.
- * @return  HRESULT
- * @param   pFormatEtc
- * @param   pMedium
- */
 STDMETHODIMP UIDnDDataObject::GetData(LPFORMATETC pFormatEtc, LPSTGMEDIUM pMedium)
 {
@@ -512 +503 @@
 }
 
-/**
- * Only required for IStream / IStorage interfaces.
- *
- * @return  IPRT status code.
- * @return  HRESULT
- * @param   pFormatEtc
- * @param   pMedium
- */
 STDMETHODIMP UIDnDDataObject::GetDataHere(LPFORMATETC pFormatEtc, LPSTGMEDIUM pMedium)
 {
@@ -527 +510 @@
 }
 
-/**
- * Query if this objects supports a specific format.
- *
- * @return  IPRT status code.
- * @return  HRESULT
- * @param   pFormatEtc
- */
 STDMETHODIMP UIDnDDataObject::QueryGetData(LPFORMATETC pFormatEtc)
 {
@@ -594 +570 @@
  */
 
+/**
+ * Aborts waiting for data being "dropped".
+ *
+ * @returns VBox status code.
+ */
 int UIDnDDataObject::Abort(void)
 {
@@ -601 +582 @@
 }
 
+/**
+ * Static helper function to convert a CLIPFORMAT to a string and return it.
+ *
+ * @returns Pointer to converted stringified CLIPFORMAT, or "unknown" if not found / invalid.
+ * @param   fmt                 CLIPFORMAT to return string for.
+ */
 /* static */
 const char* UIDnDDataObject::ClipboardFormatToString(CLIPFORMAT fmt)
@@ -682 +669 @@
 }
 
+/**
+ * Checks whether a given FORMATETC is supported by this data object and returns its index.
+ *
+ * @returns \c true if format is supported, \c false if not.
+ * @param   pFormatEtc          Pointer to FORMATETC to check for.
+ * @param   puIndex             Where to store the index if format is supported.
+ */
 bool UIDnDDataObject::LookupFormatEtc(LPFORMATETC pFormatEtc, ULONG *puIndex)
 {
@@ -712 +706 @@
 }
 
+/**
+ * Registers a new format with this data object.
+ *
+ * @param   pFormatEtc          Where to store the new format into.
+ * @param   clipFormat          Clipboard format to register.
+ * @param   tyMed               Format medium type to register.
+ * @param   lIndex              Format index to register.
+ * @param   dwAspect            Format aspect to register.
+ * @param   pTargetDevice       Format target device to register.
+ */
 void UIDnDDataObject::RegisterFormat(LPFORMATETC pFormatEtc, CLIPFORMAT clipFormat,
                                      TYMED tyMed, LONG lIndex, DWORD dwAspect,
@@ -728 +732 @@
 }
 
+/**
+ * Sets the current status of this data object.
+ *
+ * @param   enmStatus           New status to set.
+ */
 void UIDnDDataObject::SetStatus(DnDDataObjectStatus enmStatus)
 {
@@ -734 +743 @@
 }
 
+/**
+ * Signals that data has been "dropped".
+ *
+ ** @todo r=andy Remove?
+ */
 void UIDnDDataObject::Signal(void)
 {
@@ -739 +753 @@
 }
 
+/**
+ * Signals that data has been "dropped".
+ *
+ * @returns VBox status code.
+ * @param   strFormat           Format of data (MIME string).
+ * @param   pvData              Pointer to data.
+ * @param   cbData              Size (in bytes) of data.
+ */
 int UIDnDDataObject::Signal(const QString &strFormat,
                             const void *pvData, uint32_t cbData)

trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIDnDDataObject_win.h

@@ -95 +95 @@
     /** Internal reference count of this object. */
     LONG                    m_cRefs;
-    /** Number of native formats registered. This can be a different number than supplied with mlstFormats. */
+    /** Number of native formats registered. This can be a different number than supplied with m_lstFormats. */
     ULONG                   m_cFormats;
+    /** Array of registered FORMATETC structs. Matches m_cFormats. */
     FORMATETC              *m_pFormatEtc;
+    /** Array of registered STGMEDIUM structs. Matches m_cFormats. */
     STGMEDIUM              *m_pStgMedium;
+    /** Event semaphore used for waiting on status changes. */
     RTSEMEVENT              m_SemEvent;
+    /** List of supported formats. */
     QStringList             m_lstFormats;
+    /** Format of currently retrieved data. */
     QString                 m_strFormat;
     /** The retrieved data as a QVariant. Needed for buffering in case a second format needs the same data,

trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIDnDDropSource_win.h

@@ -56 +56 @@
     /** Pointer to parent widget. */
     QWidget         *m_pParent;
+    /** Pointer to current data object. */
     UIDnDDataObject *m_pDataObject;
     /** The current reference count. */

trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIDnDHandler.cpp

@@ -601 +601 @@
                                      QVector<uint8_t> &vecData)
 {
+    /** @todo r=andy Locking required? */
+
     if (!strMIMEType.compare("application/x-qt-mime-type-name", Qt::CaseInsensitive))
         return VINF_SUCCESS;
@@ -713 +715 @@
 }
 
+/**
+ * Sets the current DnD operation mode.
+ *
+ * Note: Only one mode (guest->host *or* host->guest) can be active at the same time.
+ *
+ * @param   enmMode             Current operation mode to set.
+ */
 void UIDnDHandler::setOpMode(DNDOPMODE enmMode)
 {
     QMutexLocker AutoWriteLock(&m_WriteLock);
+
+    /** @todo r=andy Check for old (current) mode and refuse new mode? */
+
     m_enmOpMode = enmMode;
     LogFunc(("Operation mode is now: %RU32\n", m_enmOpMode));
@@ -734 +746 @@
  */
 
+/**
+ * Static helper function to convert a Qt drop action to an internal DnD drop action.
+ *
+ * @returns Converted internal drop action.
+ * @param   action              Qt drop action to convert.
+ */
 /* static */
 KDnDAction UIDnDHandler::toVBoxDnDAction(Qt::DropAction action)
@@ -747 +765 @@
 }
 
+/**
+ * Static helper function to convert Qt drop actions to internal DnD drop actions.
+ *
+ * @returns Vector of converted internal drop actions.
+ * @param   actions             Qt drop actions to convert.
+ */
 /* static */
 QVector<KDnDAction> UIDnDHandler::toVBoxDnDActions(Qt::DropActions actions)
@@ -763 +787 @@
 }
 
+/**
+ * Static helper function to convert an internal drop action to a Qt drop action.
+ *
+ * @returns Converted Qt drop action.
+ * @param   actions             Internal drop action to convert.
+ */
 /* static */
 Qt::DropAction UIDnDHandler::toQtDnDAction(KDnDAction action)
@@ -778 +808 @@
 }
 
+/**
+ * Static helper function to convert a vector of internal drop actions to Qt drop actions.
+ *
+ * @returns Converted Qt drop actions.
+ * @param   vecActions          Internal drop actions to convert.
+ */
 /* static */
 Qt::DropActions UIDnDHandler::toQtDnDActions(const QVector<KDnDAction> &vecActions)

trunk/src/VBox/Frontends/VirtualBox/src/runtime/UIDnDHandler.h

@@ -38 +38 @@
 class UISession;
 
+/**
+ * Main class for implementing Drag'n'Drop in the frontend.
+ */
 class UIDnDHandler: public QObject
 {