Share via

COleDataSource Class

  • Article

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at COleDataSource Class.

Acts as a cache into which an application places the data that it will offer during data transfer operations, such as Clipboard or drag-and-drop operations.

Syntax

class COleDataSource : public CCmdTarget

Members

Public Constructors

Name Description
COleDataSource::COleDataSource Constructs a COleDataSource object.

Public Methods

Name Description
COleDataSource::CacheData Offers data in a specified format using a STGMEDIUM structure.
COleDataSource::CacheGlobalData Offers data in a specified format using an HGLOBAL.
COleDataSource::DelayRenderData Offers data in a specified format using delayed rendering.
COleDataSource::DelayRenderFileData Offers data in a specified format in a CFile pointer.
COleDataSource::DelaySetData Called for every format that is supported in OnSetData.
COleDataSource::DoDragDrop Performs drag-and-drop operations with a data source.
COleDataSource::Empty Empties the COleDataSource object of data.
COleDataSource::FlushClipboard Renders all data to the Clipboard.
COleDataSource::GetClipboardOwner Verifies that the data placed on the Clipboard is still there.
COleDataSource::OnRenderData Retrieves data as part of delayed rendering.
COleDataSource::OnRenderFileData Retrieves data into a CFile as part of delayed rendering.
COleDataSource::OnRenderGlobalData Retrieves data into an HGLOBAL as part of delayed rendering.
COleDataSource::OnSetData Called to replace the data in the COleDataSource object.
COleDataSource::SetClipboard Places a COleDataSource object on the Clipboard.

Remarks

You can create OLE data sources directly. Alternately, the COleClientItem and COleServerItem classes create OLE data sources in response to their CopyToClipboard and DoDragDrop member functions. See COleServerItem::CopyToClipboard for a brief description. Override the OnGetClipboardData member function of your client item or server item class to add additional Clipboard formats to the data in the OLE data source created for the CopyToClipboard or DoDragDrop member function.

Whenever you want to prepare data for a transfer, you should create an object of this class and fill it with your data using the most appropriate method for your data. The way it is inserted into a data source is directly affected by whether the data is supplied immediately (immediate rendering) or on demand (delayed rendering). For every Clipboard format in which you are providing data by passing the Clipboard format to be used (and an optional FORMATETC structure), call DelayRenderData.

For more information about data sources and data transfer, see the article Data Objects and Data Sources (OLE). In addition, the article Clipboard Topics describes the OLE Clipboard mechanism.

Inheritance Hierarchy

CObject

CCmdTarget

COleDataSource

Requirements

Header: afxole.h

COleDataSource::CacheData

Call this function to specify a format in which data is offered during data transfer operations.

void CacheData(
    CLIPFORMAT cfFormat,  
    LPSTGMEDIUM lpStgMedium,  
    LPFORMATETC lpFormatEtc = NULL);

Parameters

cfFormat
The Clipboard format in which the data is to be offered. This parameter can be one of the predefined Clipboard formats or the value returned by the native Windows RegisterClipboardFormat function.

lpStgMedium
Points to a STGMEDIUM structure containing the data in the format specified.

lpFormatEtc
Points to a FORMATETC structure describing the format in which the data is to be offered. Provide a value for this parameter if you want to specify additional format information beyond the Clipboard format specified by cfFormat. If it is NULL, default values are used for the other fields in the FORMATETC structure.

Remarks

You must supply the data, because this function provides it by using immediate rendering. The data is cached until needed.

Supply the data using a STGMEDIUM structure. You can also use the CacheGlobalData member function if the amount of data you are supplying is small enough to be transferred efficiently using an HGLOBAL.

After the call to CacheData the ptd member of lpFormatEtc and the contents of lpStgMedium are owned by the data object, not by the caller.

To use delayed rendering, call the DelayRenderData or DelayRenderFileData member function. For more information on delayed rendering as handled by MFC, see the article Data Objects and Data Sources: Manipulation.

For more information, see the STGMEDIUM and FORMATETC structures in the Windows SDK*.*

For more information, see RegisterClipboardFormat in the Windows SDK.

COleDataSource::CacheGlobalData

Call this function to specify a format in which data is offered during data transfer operations.

void CacheGlobalData(
    CLIPFORMAT cfFormat,  
    HGLOBAL hGlobal,  
    LPFORMATETC lpFormatEtc = NULL);

Parameters

cfFormat
The Clipboard format in which the data is to be offered. This parameter can be one of the predefined Clipboard formats or the value returned by the native Windows RegisterClipboardFormat function.

hGlobal
Handle to the global memory block containing the data in the format specified.

lpFormatEtc
Points to a FORMATETC structure describing the format in which the data is to be offered. Provide a value for this parameter if you want to specify additional format information beyond the Clipboard format specified by cfFormat. If it is NULL, default values are used for the other fields in the FORMATETC structure.

Remarks

This function provides the data using immediate rendering, so you must supply the data when calling the function; the data is cached until needed. Use the CacheData member function if you are supplying a large amount of data or if you require a structured storage medium.

To use delayed rendering, call the DelayRenderData or DelayRenderFileData member function. For more information on delayed rendering as handled by MFC, see the article Data Objects and Data Sources: Manipulation.

For more information, see the FORMATETC structure in the Windows SDK*.*

For more information, see RegisterClipboardFormat in the Windows SDK.

COleDataSource::COleDataSource

Constructs a COleDataSource object.

COleDataSource();

COleDataSource::DelayRenderData

Call this function to specify a format in which data is offered during data transfer operations.

void DelayRenderData(
    CLIPFORMAT cfFormat,  
    LPFORMATETC lpFormatEtc = NULL);

Parameters

cfFormat
The Clipboard format in which the data is to be offered. This parameter can be one of the predefined Clipboard formats or the value returned by the native Windows RegisterClipboardFormat function.

lpFormatEtc
Points to a FORMATETC structure describing the format in which the data is to be offered. Provide a value for this parameter if you want to specify additional format information beyond the Clipboard format specified by cfFormat. If it is NULL, default values are used for the other fields in the FORMATETC structure.

Remarks

This function provides the data using delayed rendering, so the data is not supplied immediately. The OnRenderData or OnRenderGlobalData member function is called to request the data.

Use this function if you are not going to supply your data through a CFile object. If you are going to supply the data through a CFile object, call the DelayRenderFileData member function. For more information on delayed rendering as handled by MFC, see the article Data Objects and Data Sources: Manipulation.

To use immediate rendering, call the CacheData or CacheGlobalData member function.

For more information, see the FORMATETC structure in the Windows SDK*.*

For more information, see RegisterClipboardFormat in the Windows SDK.

COleDataSource::DelayRenderFileData

Call this function to specify a format in which data is offered during data transfer operations.

void DelayRenderFileData(
    CLIPFORMAT cfFormat,  
    LPFORMATETC lpFormatEtc = NULL);

Parameters

cfFormat
The Clipboard format in which the data is to be offered. This parameter can be one of the predefined Clipboard formats or the value returned by the native Windows RegisterClipboardFormat function.

lpFormatEtc
Points to a FORMATETC structure describing the format in which the data is to be offered. Provide a value for this parameter if you want to specify additional format information beyond the Clipboard format specified by cfFormat. If it is NULL, default values are used for the other fields in the FORMATETC structure.

Remarks

This function provides the data using delayed rendering, so the data is not supplied immediately. The OnRenderFileData member function is called to request the data.

Use this function if you are going to use a CFile object to supply the data. If you are not going to use a CFile object, call the DelayRenderData member function. For more information on delayed rendering as handled by MFC, see the article Data Objects and Data Sources: Manipulation.

To use immediate rendering, call the CacheData or CacheGlobalData member function.

For more information, see the FORMATETC structure in the Windows SDK*.*

For more information, see RegisterClipboardFormat in the Windows SDK.

COleDataSource::DelaySetData

Call this function to support changing the contents of the data source.

void DelaySetData(
    CLIPFORMAT cfFormat,  
    LPFORMATETC lpFormatEtc = NULL);

Parameters

cfFormat
The Clipboard format in which the data is to be placed. This parameter can be one of the predefined Clipboard formats or the value returned by the native Windows RegisterClipboardFormat function.

lpFormatEtc
Points to a FORMATETC structure describing the format in which the data is to be replaced. Provide a value for this parameter if you want to specify additional format information beyond the Clipboard format specified by cfFormat. If it is NULL, default values are used for the other fields in the FORMATETC structure.

Remarks

OnSetData will be called by the framework when this happens. This is only used when the framework returns the data source from COleServerItem::GetDataSource. If DelaySetData is not called, your OnSetData function will never be called. DelaySetData should be called for each Clipboard or FORMATETC format you support.

For more information, see the FORMATETC structure in the Windows SDK*.*

For more information, see RegisterClipboardFormat in the Windows SDK.

COleDataSource::DoDragDrop

Call the DoDragDrop member function to perform a drag-and-drop operation for this data source, typically in an CWnd::OnLButtonDown handler.

DROPEFFECT DoDragDrop(
    DWORD dwEffects = DROPEFFECT_COPY|DROPEFFECT_MOVE|DROPEFFECT_LINK,  
    LPCRECT lpRectStartDrag = NULL,  
    COleDropSource* pDropSource = NULL);

Parameters

dwEffects
Drag-and-drop operations that are allowed on this data source. Can be one or more of the following:

  • DROPEFFECT_COPY A copy operation could be performed.

  • DROPEFFECT_MOVE A move operation could be performed.

  • DROPEFFECT_LINK A link from the dropped data to the original data could be established.

  • DROPEFFECT_SCROLL Indicates that a drag scroll operation could occur.

lpRectStartDrag
Pointer to the rectangle that defines where the drag actually starts. For more information, see the following Remarks section.

pDropSource
Points to a drop source. If NULL then a default implementation of COleDropSource will be used.

Return Value

Drop effect generated by the drag-and-drop operation; otherwise DROPEFFECT_NONE if the operation never begins because the user released the mouse button before leaving the supplied rectangle.

Remarks

The drag-and-drop operation does not start immediately. It waits until the mouse cursor leaves the rectangle specified by lpRectStartDrag or until a specified number of milliseconds have passed. If lpRectStartDrag is NULL, the size of the rectangle is one pixel.

The delay time is specified by a registry key setting. You can change the delay time by calling CWinApp::WriteProfileString or CWinApp::WriteProfileInt. If you do not specify the delay time, a default value of 200 milliseconds is used. Drag delay time is stored as follows:

  • Windows NT Drag delay time is stored in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\NT\CurrentVersion\IniFileMapping\win.ini\Windows\DragDelay.

  • Windows 3.x Drag delay time is stored in the WIN.INI file, under the [Windows} section.

  • Windows 95/98 Drag delay time is stored in a cached version of WIN.INI.

For more information about how drag delay information is stored in either the registry or the .INI file, see WriteProfileString in the Windows SDK.

For more information, see the article Drag and Drop: Implementing a Drop Source.

COleDataSource::Empty

Call this function to empty the COleDataSource object of data.

void Empty();

Remarks

Both cached and delay render formats are emptied so they can be reused.

For more information, see ReleaseStgMedium in the Windows SDK.

COleDataSource::FlushClipboard

Renders data that is on the Clipboard, and then lets you paste data from the Clipboard after your application shuts down.

static void PASCAL FlushClipboard();

Remarks

Use SetClipboard to put data on the Clipboard.

COleDataSource::GetClipboardOwner

Determines whether the data on the Clipboard has changed since SetClipboard was last called and, if so, identifies the current owner.

static COleDataSource* PASCAL GetClipboardOwner();

Return Value

The data source currently on the Clipboard, or NULL if there is nothing on the Clipboard or if the Clipboard is not owned by the calling application.

COleDataSource::OnRenderData

Called by the framework to retrieve data in the specified format.

virtual BOOL OnRenderData(
    LPFORMATETC lpFormatEtc,  
    LPSTGMEDIUM lpStgMedium);

Parameters

lpFormatEtc
Points to the FORMATETC structure specifying the format in which information is requested.

lpStgMedium
Points to a STGMEDIUM structure in which the data is to be returned.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The specified format is one previously placed in the COleDataSource object using the DelayRenderData or DelayRenderFileData member function for delayed rendering. The default implementation of this function will call OnRenderFileData or OnRenderGlobalData if the supplied storage medium is either a file or memory, respectively. If neither of these formats are supplied, then the default implementation will return 0 and do nothing. For more information on delayed rendering as handled by MFC, see the article Data Objects and Data Sources: Manipulation.

If lpStgMedium-> tymed is TYMED_NULL, the STGMEDIUM should be allocated and filled as specified by lpFormatEtc->tymed. If it is not TYMED_NULL, the STGMEDIUM should be filled in place with the data.

This is an advanced overridable. Override this function to supply your data in the requested format and medium. Depending on your data, you may want to override one of the other versions of this function instead. If your data is small and fixed in size, override OnRenderGlobalData. If your data is in a file, or is of variable size, override OnRenderFileData.

For more information, see the STGMEDIUM and FORMATETC structures, the TYMED enumeration type, and IDataObject::GetData in the Windows SDK*.*

COleDataSource::OnRenderFileData

Called by the framework to retrieve data in the specified format when the specified storage medium is a file.

virtual BOOL OnRenderFileData(
    LPFORMATETC lpFormatEtc,  
    CFile* pFile);

Parameters

lpFormatEtc
Points to the FORMATETC structure specifying the format in which information is requested.

pFile
Points to a CFile object in which the data is to be rendered.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The specified format is one previously placed in the COleDataSource object using the DelayRenderData member function for delayed rendering. The default implementation of this function simply returns FALSE.

This is an advanced overridable. Override this function to supply your data in the requested format and medium. Depending on your data, you might want to override one of the other versions of this function instead. If you want to handle multiple storage media, override OnRenderData. If your data is in a file, or is of variable size, override OnRenderFileData. For more information on delayed rendering as handled by MFC, see the article Data Objects and Data Sources: Manipulation.

For more information, see the FORMATETC structure and IDataObject::GetData in the Windows SDK*.*

COleDataSource::OnRenderGlobalData

Called by the framework to retrieve data in the specified format when the specified storage medium is global memory.

virtual BOOL OnRenderGlobalData(
    LPFORMATETC lpFormatEtc,  
    HGLOBAL* phGlobal);

Parameters

lpFormatEtc
Points to the FORMATETC structure specifying the format in which information is requested.

phGlobal
Points to a handle to global memory in which the data is to be returned. If one has not yet been allocated, this parameter can be NULL.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The specified format is one previously placed in the COleDataSource object using the DelayRenderData member function for delayed rendering. The default implementation of this function simply returns FALSE.

If phGlobal is NULL, then a new HGLOBAL should be allocated and returned in phGlobal. Otherwise, the HGLOBAL specified by phGlobal should be filled with the data. The amount of data placed in the HGLOBAL must not exceed the current size of the memory block. Also, the block cannot be reallocated to a larger size.

This is an advanced overridable. Override this function to supply your data in the requested format and medium. Depending on your data, you may want to override one of the other versions of this function instead. If you want to handle multiple storage media, override OnRenderData. If your data is in a file, or is of variable size, override OnRenderFileData. For more information on delayed rendering as handled by MFC, see the article Data Objects and Data Sources: Manipulation.

For more information, see the FORMATETC structure and IDataObject::GetData in the Windows SDK*.*

COleDataSource::OnSetData

Called by the framework to set or replace the data in the COleDataSource object in the specified format.

virtual BOOL OnSetData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium,
    BOOL bRelease);

Parameters

lpFormatEtc
Points to the FORMATETC structure specifying the format in which data is being replaced.

lpStgMedium
Points to the STGMEDIUM structure containing the data that will replace the current contents of the COleDataSource object.

bRelease
Indicates who has ownership of the storage medium after completing the function call. The caller decides who is responsible for releasing the resources allocated on behalf of the storage medium. The caller does this by setting bRelease. If bRelease is nonzero, the data source takes ownership, freeing the medium when it has finished using it. When bRelease is 0, the caller retains ownership and the data source can use the storage medium only for the duration of the call.

Return Value

Nonzero if successful; otherwise 0.

Remarks

The data source does not take ownership of the data until it has successfully obtained it. That is, it does not take ownership if OnSetData returns 0. If the data source takes ownership, it frees the storage medium by calling the ReleaseStgMedium function.

The default implementation does nothing. Override this function to replace the data in the specified format. This is an advanced overridable.

For more information, see the STGMEDIUM and FORMATETC structures and the ReleaseStgMedium and IDataObject::GetData functions in the Windows SDK*.*

COleDataSource::SetClipboard

Puts the data contained in the COleDataSource object on the Clipboard after calling one of the following functions: CacheData, CacheGlobalData, DelayRenderData, or DelayRenderFileData.

void SetClipboard();

See Also

MFC Sample HIERSVR
MFC Sample OCLIENT
CCmdTarget Class
Hierarchy Chart
COleDataObject Class