VirtualBox

Changeset 85681 in vbox for trunk/src/VBox/Additions/WINNT


Ignore:
Timestamp:
Aug 11, 2020 9:36:37 AM (5 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
139817
Message:

DnD: Lots of documentation.

Location:
trunk/src/VBox/Additions/WINNT/VBoxTray
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Additions/WINNT/VBoxTray/VBoxDnD.h

    r85371 r85681  
    2929class VBoxDnDWnd;
    3030
     31/**
     32 * Class for implementing IDataObject for VBoxTray's DnD support.
     33 */
    3134class VBoxDnDDataObject : public IDataObject
    3235{
    … …  
    8083                        LONG lindex = -1, DWORD dwAspect = DVASPECT_CONTENT, DVTARGETDEVICE *pTargetDevice = NULL);
    8184
     85    /** Current drag and drop status. */
    8286    Status      mStatus;
     87    /** Internal reference count of this object. */
    8388    LONG        mRefCount;
     89    /** Number of native formats registered. This can be a different number than supplied with m_lstFormats. */
    8490    ULONG       mcFormats;
     91    /** Array of registered FORMATETC structs. Matches m_cFormats. */
    8592    LPFORMATETC mpFormatEtc;
     93    /** Array of registered STGMEDIUM structs. Matches m_cFormats. */
    8694    LPSTGMEDIUM mpStgMedium;
     95    /** Event semaphore used for waiting on status changes. */
    8796    RTSEMEVENT  mEventDropped;
     97    /** Format of currently retrieved data. */
    8898    RTCString   mstrFormat;
     99    /** The retrieved data as a raw buffer. */
    89100    void       *mpvData;
     101    /** Raw buffer size (in bytes). */
    90102    size_t      mcbData;
    91103};
    92104
     105/**
     106 * Class for implementing IDropSource for VBoxTray's DnD support.
     107 */
    93108class VBoxDnDDropSource : public IDropSource
    94109{
    … …  
    125140};
    126141
     142/**
     143 * Class for implementing IDropTarget for VBoxTray's DnD support.
     144 */
    127145class VBoxDnDDropTarget : public IDropTarget
    128146{
    … …  
    153171public:
    154172
     173    /** Returns the data as mutable raw. Use with caution! */
    155174    void *DataMutableRaw(void) const { return mpvData; }
     175
     176    /** Returns the data size (in bytes). */
    156177    size_t DataSize(void) const { return mcbData; }
     178
    157179    RTCString Formats(void) const;
    158180    int WaitForDrop(RTMSINTERVAL msTimeout);
    … …  
    181203};
    182204
     205/**
     206 * Class for implementing IEnumFORMATETC for VBoxTray's DnD support.
     207 */
    183208class VBoxDnDEnumFormatEtc : public IEnumFORMATETC
    184209{
    … …  
    206231private:
    207232
     233    /** Reference count of this object. */
    208234    LONG        m_lRefCount;
     235    /** Current index for format iteration. */
    209236    ULONG       m_nIndex;
     237    /** Number of format this object contains. */
    210238    ULONG       m_nNumFormats;
     239    /** Array of FORMATETC formats this object contains. Matches m_nNumFormats. */
    211240    LPFORMATETC m_pFormatEtc;
    212241};
    … …  
    215244class VBoxDnDWnd;
    216245
    217 /*
     246/**
    218247 * A drag'n drop event from the host.
    219248 */
    … …  
    371400     *  window messages. */
    372401    RTTHREAD                   hThread;
     402    /** Critical section to serialize access. */
    373403    RTCRITSECT                 mCritSect;
     404    /** Event semaphore to wait for new DnD events. */
    374405    RTSEMEVENT                 mEventSem;
    375406#ifdef RT_OS_WINDOWS
    … …  
    393424    bool                       mfMouseButtonDown;
    394425# ifdef VBOX_WITH_DRAG_AND_DROP_GH
    395     /** IDropTarget implementation for guest -> host
    396      *  support. */
     426    /** Pointer to IDropTarget implementation for
     427     *  guest -> host support. */
    397428    VBoxDnDDropTarget         *pDropTarget;
    398429# endif /* VBOX_WITH_DRAG_AND_DROP_GH */

  • trunk/src/VBox/Additions/WINNT/VBoxTray/VBoxDnDDataObject.cpp

    r85371 r85681  
    173173}
    174174
    175 /**
    176  * Retrieves the data stored in this object and store the result in
    177  * pMedium.
    178  *
    179  * @return  IPRT status code.
    180  * @return  HRESULT
    181  * @param   pFormatEtc
    182  * @param   pMedium
    183  */
    184175STDMETHODIMP VBoxDnDDataObject::GetData(LPFORMATETC pFormatEtc, LPSTGMEDIUM pMedium)
    185176{
    … …  
    416407}
    417408
    418 /**
    419  * Only required for IStream / IStorage interfaces.
    420  *
    421  * @return  IPRT status code.
    422  * @return  HRESULT
    423  * @param   pFormatEtc
    424  * @param   pMedium
    425  */
    426409STDMETHODIMP VBoxDnDDataObject::GetDataHere(LPFORMATETC pFormatEtc, LPSTGMEDIUM pMedium)
    427410{
    … …  
    431414}
    432415
    433 /**
    434  * Query if this objects supports a specific format.
    435  *
    436  * @return  IPRT status code.
    437  * @return  HRESULT
    438  * @param   pFormatEtc
    439  */
    440416STDMETHODIMP VBoxDnDDataObject::QueryGetData(LPFORMATETC pFormatEtc)
    441417{
    … …  
    496472 */
    497473
     474/**
     475 * Aborts waiting for data being "dropped".
     476 *
     477 * @returns VBox status code.
     478 */
    498479int VBoxDnDDataObject::Abort(void)
    499480{
    … …  
    503484}
    504485
     486/**
     487 * Static helper function to convert a CLIPFORMAT to a string and return it.
     488 *
     489 * @returns Pointer to converted stringified CLIPFORMAT, or "unknown" if not found / invalid.
     490 * @param   fmt                 CLIPFORMAT to return string for.
     491 */
    505492/* static */
    506493const char* VBoxDnDDataObject::ClipboardFormatToString(CLIPFORMAT fmt)
    … …  
    586573}
    587574
     575/**
     576 * Checks whether a given FORMATETC is supported by this data object and returns its index.
     577 *
     578 * @returns \c true if format is supported, \c false if not.
     579 * @param   pFormatEtc          Pointer to FORMATETC to check for.
     580 * @param   puIndex             Where to store the index if format is supported.
     581 */
    588582bool VBoxDnDDataObject::LookupFormatEtc(LPFORMATETC pFormatEtc, ULONG *puIndex)
    589583{
    … …  
    632626}
    633627
     628/**
     629 * Registers a new format with this data object.
     630 *
     631 * @param   pFormatEtc          Where to store the new format into.
     632 * @param   clipFormat          Clipboard format to register.
     633 * @param   tyMed               Format medium type to register.
     634 * @param   lIndex              Format index to register.
     635 * @param   dwAspect            Format aspect to register.
     636 * @param   pTargetDevice       Format target device to register.
     637 */
    634638void VBoxDnDDataObject::RegisterFormat(LPFORMATETC pFormatEtc, CLIPFORMAT clipFormat,
    635639                                       TYMED tyMed, LONG lIndex, DWORD dwAspect,
    … …  
    648652}
    649653
     654/**
     655 * Sets the current status of this data object.
     656 *
     657 * @param   status              New status to set.
     658 */
    650659void VBoxDnDDataObject::SetStatus(Status status)
    651660{
    … …  
    654663}
    655664
     665/**
     666 * Signals that data has been "dropped".
     667 *
     668 * @returns VBox status code.
     669 * @param   strFormat           Format of data (MIME string).
     670 * @param   pvData              Pointer to data.
     671 * @param   cbData              Size (in bytes) of data.
     672 */
    656673int VBoxDnDDataObject::Signal(const RTCString &strFormat,
    657674                              const void *pvData, size_t cbData)

  • trunk/src/VBox/Additions/WINNT/VBoxTray/VBoxDnDDropTarget.cpp

    r85520 r85681  
    9494}
    9595
     96/**
     97 * Static helper function to dump supported formats of a data object.
     98 *
     99 * @param   pDataObject         Pointer to data object to dump formats for.
     100 */
    96101/* static */
    97102void VBoxDnDDropTarget::DumpFormats(IDataObject *pDataObject)
    … …  
    559564}
    560565
     566/**
     567 * Static helper function to return a drop effect for a given key state and allowed effects.
     568 *
     569 * @returns Resolved drop effect.
     570 * @param   grfKeyState         Key state to determine drop effect for.
     571 * @param   dwAllowedEffects    Allowed drop effects to determine drop effect for.
     572 */
    561573/* static */
    562574DWORD VBoxDnDDropTarget::GetDropEffect(DWORD grfKeyState, DWORD dwAllowedEffects)
    … …  
    588600}
    589601
     602/**
     603 * Resets a drop target object.
     604 */
    590605void VBoxDnDDropTarget::reset(void)
    591606{
    … …  
    604619}
    605620
     621/**
     622 * Returns the currently supported formats of a drop target.
     623 *
     624 * @returns Supported formats.
     625 */
    606626RTCString VBoxDnDDropTarget::Formats(void) const
    607627{
    … …  
    609629}
    610630
     631/**
     632 * Waits for a drop event to happen.
     633 *
     634 * @returns VBox status code.
     635 * @param   msTimeout           Timeout (in ms) to wait for drop event.
     636 */
    611637int VBoxDnDDropTarget::WaitForDrop(RTMSINTERVAL msTimeout)
    612638{
Note: See TracChangeset for help on using the changeset viewer.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette