| C & C++ Programming | MFC Programming | Download | Site Index |


 

 

 

 

Supplementary Note for MFC Programming Module 25

 

 

 

 

 

 

What do we have in this Module?

  1. IDataObject

    1. When to Implement

    2. When to Use

    3. Methods in VTable Order

  2. COleDataSource Class

    1. Remarks

  3. COleDataSource Members

    1. Construction

    2. Operations

  4. COleDataObject Class

    1. Remarks

  5. COleDataObject Members

    1. Construction

    2. Operations

  6. CRectTracker Class

  7. CRectTracker Members

    1.     Data Members

    2.     Construction

    3.     Operations

    4.     Overridables

 

 

IDataObject

 

The IDataObject interface specifies methods that enable data transfer and notification of changes in data. Data transfer methods specify the format of the transferred data along with the medium through which the data is to be transferred. Optionally, the data can be rendered for a specific target device. In addition to methods for retrieving and storing data, the IDataObject interface specifies methods for enumerating available formats and managing connections to advisory sinks for handling change notifications.

The term "data object" is used to mean any object that supports an implementation of the IDataObject interface. Implementations vary, depending on what the data object is required to do; in some data objects, the implementation of certain methods not supported by the object could simply be the return of E_NOTIMPL. For example, some data objects do not allow callers to send them data. Other data objects do not support advisory connections and change notifications. However, for those data objects that do support change notifications, OLE provides an object called a data advise holder. An interface pointer to this holder is available through a call to the helper function CreateDataAdviseHolder(). A data object can have multiple connections, each with its own set of attributes. The OLE data advise holder simplifies the task of managing these connections and sending the appropriate notifications. This interface declared in objidl.h.

 

When to Implement

 

Implement the IDataObject interface if you are developing a container or server application that is capable of transferring data. For example, if your application allows its data to be pasted or dropped into another application, you must implement the IDataObject interface. OLE compound document object servers that support objects that can be embedded or linked must implement IDataObject. OLE provides implementations in its default object handler and its cache.

 

When to Use

 

Any object that can receive data calls the methods in the IDataObject interface. When you call the data transfer methods in the IDataObject interface, you specify a format, a medium, and, optionally, a target device for which the data should be rendered. Objects, such as containers, that want to be notified through their advise sinks when the data in the data object changes call the IDataObject advisory methods to set up an advisory connection through which notifications can be sent.

 

Methods in VTable Order

 

IUnknown Methods

Description

QueryInterface()

Returns pointers to supported interfaces.

AddRef()

Increments reference count.

Release()

Decrements reference count.

 

Table 1.

 

 

IDataObject Methods

Description

GetData()

Renders the data described in a FORMATETC structure and transfers it through the STGMEDIUM structure.

GetDataHere()

Renders the data described in a FORMATETC structure and transfers it through the STGMEDIUM structure allocated by the caller.

QueryGetData()

Determines whether the data object is capable of rendering the data described in the FORMATETC structure.

GetCanonicalFormatEtc()

Provides a potentially different but logically equivalent FORMATETC structure.

SetData()

Provides the source data object with data described by a FORMATETC structure and an STGMEDIUM structure.

EnumFormatEtc()

Creates and returns a pointer to an object to enumerate the FORMATETC supported by the data object.

DAdvise()

Creates a connection between a data object and an advise sink so the advise sink can receive notifications of changes in the data object.

DUnadvise()

Destroys a notification previously set up with the DAdvise() method.

EnumDAdvise()

Creates and returns a pointer to an object to enumerate the current advisory connections.

 

Table 2.

 

COleDataSource Class

 

class COleDataSource : public CCmdTarget

 

Remarks

 

The 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. 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. 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(). You must include the afxole.h header to use this class.

 

COleDataSource Members

 

Construction

 

COleDataSource

Constructs a COleDataSource object.

 

Table 3.

 

Operations

 

 

 

 

 

 

 

 

CacheData()

Offers data in a specified format using a STGMEDIUM structure.

CacheGlobalData()

Offers data in a specified format using an HGLOBAL.

DelayRenderData()

Offers data in a specified format using delayed rendering.

DelayRenderFileData()

Offers data in a specified format in a CFile pointer.

DelaySetData()

Called for every format that is supported in OnSetData().

DoDragDrop()

Performs drag-and-drop operations with a data source.

Empty()

Empties the COleDataSource object of data.

FlushClipboard()

Renders all data to the Clipboard.

GetClipboardOwner()

Verifies that the data placed on the Clipboard is still there.

OnRenderData()

Retrieves data as part of delayed rendering.

OnRenderFileData()

Retrieves data into a CFile as part of delayed rendering.

OnRenderGlobalData()

Retrieves data into an HGLOBAL as part of delayed rendering.

OnSetData()

Called to replace the data in the COleDataSource object.

SetClipboard()

Places a COleDataSource object on the Clipboard.

 

Table 4.

 

COleDataObject Class

 

class COleDataObject

 

Remarks

 

COleDataObject does not have a base class. The COleDataObject class is used in data transfers for retrieving data in various formats from the Clipboard, through drag and drop, or from an embedded OLE item. These kinds of data transfers include a source and a destination. The data source is implemented as an object of the COleDataSource class. Whenever a destination application has data dropped in it or is asked to perform a paste operation from the Clipboard, an object of the COleDataObject class must be created. This class enables you to determine whether the data exists in a specified format. You can also enumerate the available data formats or check whether a given format is available and then retrieve the data in the preferred format. Object retrieval can be accomplished in several different ways, including the use of a CFile, an HGLOBAL, or an STGMEDIUM structure. You must include afxole.h to use this class.

 

COleDataObject Members

 

Construction

 

COleDataObject

Constructs a COleDataObject object.

 

Table 5.

 

Operations

 

Attach()

Attaches the specified OLE data object to the COleDataObject.

AttachClipboard()

Attaches the data object that is on the Clipboard.

BeginEnumFormats()

Prepares for one or more subsequent GetNextFormat() calls.

Detach()

Detaches the associated IDataObject object.

GetData()

Copies data from the attached OLE data object in a specified format.

GetFileData()

Copies data from the attached OLE data object into a CFile pointer in the specified format.

GetGlobalData()

Copies data from the attached OLE data object into an HGLOBAL in the specified format.

GetNextFormat()

Returns the next data format available.

IsDataAvailable()

Checks whether data is available in a specified format.

Release()

Detaches and releases the associated IDataObject object.

 

Table 6.

 

CRectTracker Class

 

class CRectTracker

 

CRectTracker does not have a base class. The CRectTracker class allows an item to be displayed, moved, and resized in different fashions. Although the CRectTracker class is designed to allow the user to interact with OLE items by using a graphical interface, its use is not restricted to OLE-enabled applications. It can be used anywhere such a user interface is required. CRectTracker borders can be solid or dotted lines. The item can be given a hatched border or overlaid with a hatched pattern to indicate different states of the item. You can place eight resize handles on either the outside or the inside border of the item. Finally, a CRectTracker allows you to change the orientation of an item during resizing. To use CRectTracker, construct a CRectTracker object and specify which display states are initialized. You can then use this interface to give the user visual feedback on the current status of the OLE item associated with the CRectTracker object. You must include afxext.h in order to use this class.

 

CRectTracker Members

 

Data Members

 

m_nHandleSize

Determines size of resize handles.

m_nStyle

Current style(s) of the tracker.

m_rect

Current position (in pixels) of the rectangle.

m_sizeMin

Determines minimum rectangle width and height.

 

Table 7

 

Construction

 

CRectTracker

Constructs a CRectTracker object.

 

Table 8.

 

Operations

 

Draw()

Renders the rectangle.

GetTrueRect()

Returns width and height of rectangle, including resize handles.

HitTest()

Returns the current position of the cursor related to the CRectTracker object.

NormalizeHit()

Normalizes a hit-test code.

SetCursor()

Sets the cursor, depending on its position over the rectangle.

Track()

Allows the user to manipulate the rectangle.

TrackRubberBand()

Allows the user to "rubber-band" the selection.

 

Table 9.

 

Overridables

 

AdjustRect()

Called when the rectangle is resized.

DrawTrackerRect()

Called when drawing the border of a CRectTracker object.

GetHandleMask()

Called to get the mask of a CRectTracker item's resize handles.

OnChangedRect()

Called when the rectangle has been resized or moved.

 

Table 10.

 

 

 

 

 

 

 

 

 


| C & C++ Programming | MFC Programming | Download | Site Index |