DataObject Class

Definition

Namespace:

System.Windows.Forms

Assembly:

System.Windows.Forms.dll

Source:

DataObject.cs

Implements a basic data transfer mechanism.

public ref class DataObject : System::Runtime::InteropServices::ComTypes::IDataObject, System::Windows::Forms::IDataObject

[System.Runtime.InteropServices.ClassInterface(System.Runtime.InteropServices.ClassInterfaceType.None)]
public class DataObject : System.Runtime.InteropServices.ComTypes.IDataObject, System.Windows.Forms.IDataObject

[<System.Runtime.InteropServices.ClassInterface(System.Runtime.InteropServices.ClassInterfaceType.None)>]
type DataObject = class
    interface IDataObject
    interface IDataObject.Interface
    interface IDataObject

Public Class DataObject
Implements IDataObject, IDataObject

Inheritance

Object

DataObject

Attributes

ClassInterfaceAttribute

Implements

IDataObject IDataObject

Examples

The following code example adds data in a DataObject. First, a new DataObject is created and a component is stored in it. Then, it checks to see if data in the appropriate type exists in the DataObject. The result is displayed in a text box. This code requires that textBox1 has been created.

private:
   void AddMyData3()
   {
      // Creates a component to store in the data object.
      Component^ myComponent = gcnew Component;
      
      // Creates a new data object.
      DataObject^ myDataObject = gcnew DataObject;
      
      // Adds the component to the DataObject.
      myDataObject->SetData( myComponent );
      
      // Prints whether data of the specified type is in the DataObject.
      Type^ myType = myComponent->GetType();
      if ( myDataObject->GetDataPresent( myType ) )
      {
         textBox1->Text = String::Concat( "Data of type ", myType,
            " is present in the DataObject" );
      }
      else
      {
         textBox1->Text = String::Concat( "Data of type ", myType,
            " is not present in the DataObject" );
      }
   }

private void AddMyData3() {
    // Creates a component to store in the data object.
    Component myComponent = new Component();
 
    // Creates a new data object.
    DataObject myDataObject = new DataObject();
 
    // Adds the component to the DataObject.
    myDataObject.SetData(myComponent);
 
    // Prints whether data of the specified type is in the DataObject.
    Type myType = myComponent.GetType();
    if(myDataObject.GetDataPresent(myType))
       textBox1.Text = "Data of type " + myType.ToString() + 
       " is present in the DataObject";
    else
       textBox1.Text = "Data of type " + myType.ToString() +
       " is not present in the DataObject";
 }

Private Sub AddMyData3()
    ' Creates a component to store in the data object.
    Dim myComponent As New Component()
    
    ' Creates a new data object.
    Dim myDataObject As New DataObject()
    
    ' Adds the component to the DataObject.
    myDataObject.SetData(myComponent)
    
    ' Prints whether data of the specified type is in the DataObject.
    Dim myType As Type = myComponent.GetType()
    If myDataObject.GetDataPresent(myType) Then
        textBox1.Text = "Data of type " & myType.ToString() & _
            " is present in the DataObject"
    Else
        textBox1.Text = "Data of type " & myType.ToString() & _
            " is not present in the DataObject"
    End If
End Sub

The next example retrieves the data stored in a DataObject. First, a new DataObject is created with text data. Then, the data is retrieved, specifying its format as a string, and displayed in a text box. The data format is automatically converted from text to string. This code requires that textBox1 has been created.

void GetMyData2()
{
   // Creates a new data object using a string and the text format.
   DataObject^ myDataObject = gcnew DataObject( DataFormats::Text,"Text to Store" );
   
   // Prints the string in a text box.
   textBox1->Text = myDataObject->GetData( DataFormats::Text )->ToString();
}

private void GetMyData2() {
    // Creates a new data object using a string and the text format.
    DataObject myDataObject = new DataObject(DataFormats.Text, "Text to Store");
 
    // Prints the string in a text box.
    textBox1.Text = myDataObject.GetData(DataFormats.Text).ToString();
 }

Private Sub GetMyData2()
    ' Creates a new data object using a string and the text format.
    Dim myDataObject As New DataObject(DataFormats.Text, "Text to Store")
    
    ' Prints the string in a text box.
    textBox1.Text = myDataObject.GetData(DataFormats.Text).ToString()
End Sub

Remarks

DataObject implements the IDataObject interface, whose methods provide a format-independent mechanism for data transfer.

A DataObject is typically used with the Clipboard and in drag-and-drop operations. The DataObject class provides the recommended implementation of the IDataObject interface. It is suggested that you use the DataObject class rather than implementing IDataObject yourself.

Multiple pieces of data in different formats can be stored in a DataObject. Data is retrieved from a DataObject by its associated format. Because the target application might not be known, you can increase the likelihood that the data will be in the appropriate format for an application by placing the data in a DataObject in multiple formats. See DataFormats for the predefined formats. You can implement your own format by creating an instance of the DataFormats.Format class.

To store data in a DataObject, pass the data to the constructor or call SetData. You can add data in multiple formats to the same DataObject. If you want the data you add to be retrieved in its native format only, call SetData(String, Boolean, Object) with the autoConvert parameter set to false.

Data can be retrieved from a DataObject in any format which is compatible with GetData. For example, text can be converted to Unicode. To retrieve data in the format in which it was stored, call GetData with the autoConvert parameter set to false.

To determine what formats the data is stored in, call GetFormats. To determine if a format is available, call GetDataPresent with the desired format.

In .NET Framework 2.0, the DataObject class provides additional methods that make it easier to work with data in common formats. To add data of a particular format to the DataObject, use the appropriate SetFormat method, such as SetText. To retrieve data of a particular format from the DataObject, first call the appropriate ContainsFormat method (such as ContainsText) to determine whether the DataObject contains data in that format, then call the appropriate GetFormat method (such as GetText) to retrieve the data if the DataObject contains it.

Note

Special considerations may be necessary when using the metafile format with the Clipboard. Due to a limitation in the current implementation of the DataObject class, the metafile format used by the .NET Framework may not be recognized by applications that use an older metafile format. In this case, you must interoperate with the Win32 Clipboard application programming interfaces (APIs).

An object must be serializable for it to be put on the Clipboard. See System.Runtime.Serialization for more information on serialization. If your target application requires a very specific data format, the headers added to the data in the serialization process may prevent the application from recognizing your data. To preserve your data format, add your data as a Byte array to a MemoryStream and pass the MemoryStream to the SetData method.

Constructors

DataObject()	Initializes a new instance of the DataObject class.
DataObject(Object)	Initializes a new instance of the DataObject class and adds the specified object to it.
DataObject(String, Object)	Initializes a new instance of the DataObject class and adds the specified object in the specified format.

Methods

ContainsAudio()	Indicates whether the data object contains data in the WaveAudio format.
ContainsFileDropList()	Indicates whether the data object contains data that is in the FileDrop format or can be converted to that format.
ContainsImage()	Indicates whether the data object contains data that is in the Bitmap format or can be converted to that format.
ContainsText()	Indicates whether the data object contains data in the UnicodeText format.
ContainsText(TextDataFormat)	Indicates whether the data object contains text data in the format indicated by the specified TextDataFormat value.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetAudioStream()	Retrieves an audio stream from the data object.
GetData(String, Boolean)	Returns the data associated with the specified data format, using an automated conversion parameter to determine whether to convert the data to the format.
GetData(String)	Returns the data associated with the specified data format.
GetData(Type)	Returns the data associated with the specified class type format.
GetDataPresent(String, Boolean)	Determines whether this DataObject contains data in the specified format or, optionally, contains data that can be converted to the specified format.
GetDataPresent(String)	Determines whether data stored in this DataObject is associated with, or can be converted to, the specified format.
GetDataPresent(Type)	Determines whether data stored in this DataObject is associated with, or can be converted to, the specified format.
GetFileDropList()	Retrieves a collection of file names from the data object.
GetFormats()	Returns a list of all formats that data stored in this DataObject is associated with or can be converted to.
GetFormats(Boolean)	Returns a list of all formats that data stored in this DataObject is associated with or can be converted to, using an automatic conversion parameter to determine whether to retrieve only native data formats or all formats that the data can be converted to.
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetImage()	Retrieves an image from the data object.
GetText()	Retrieves text data from the data object in the UnicodeText format.
GetText(TextDataFormat)	Retrieves text data from the data object in the format indicated by the specified TextDataFormat value.
GetType()	Gets the Type of the current instance. (Inherited from Object)
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
SetAudio(Byte[])	Adds a Byte array to the data object in the WaveAudio format after converting it to a Stream.
SetAudio(Stream)	Adds a Stream to the data object in the WaveAudio format.
SetData(Object)	Adds the specified object to the DataObject using the object type as the data format.
SetData(String, Boolean, Object)	Adds the specified object to the DataObject using the specified format and indicating whether the data can be converted to another format.
SetData(String, Object)	Adds the specified object to the DataObject using the specified format.
SetData(Type, Object)	Adds the specified object to the DataObject using the specified type as the format.
SetFileDropList(StringCollection)	Adds a collection of file names to the data object in the FileDrop format.
SetImage(Image)	Adds an Image to the data object in the Bitmap format.
SetText(String, TextDataFormat)	Adds text data to the data object in the format indicated by the specified TextDataFormat value.
SetText(String)	Adds text data to the data object in the UnicodeText format.
ToString()	Returns a string that represents the current object. (Inherited from Object)

Explicit Interface Implementations

IDataObject.DAdvise(FORMATETC, ADVF, IAdviseSink, Int32)	Creates a connection between a data object and an advisory sink. This method is called by an object that supports an advisory sink and enables the advisory sink to be notified of changes in the object's data.
IDataObject.DUnadvise(Int32)	Destroys a notification connection that had been previously established.
IDataObject.EnumDAdvise(IEnumSTATDATA)	Creates an object that can be used to enumerate the current advisory connections.
IDataObject.EnumFormatEtc(DATADIR)	Creates an object for enumerating the FORMATETC structures for a data object. These structures are used in calls to GetData(FORMATETC, STGMEDIUM) or SetData(FORMATETC, STGMEDIUM, Boolean).
IDataObject.GetCanonicalFormatEtc(FORMATETC, FORMATETC)	Provides a standard FORMATETC structure that is logically equivalent to a more complex structure. Use this method to determine whether two different FORMATETC structures would return the same data, removing the need for duplicate rendering.
IDataObject.GetData(FORMATETC, STGMEDIUM)	Obtains data from a source data object. The GetData(FORMATETC, STGMEDIUM) method, which is called by a data consumer, renders the data described in the specified FORMATETC structure and transfers it through the specified STGMEDIUM structure. The caller then assumes responsibility for releasing the STGMEDIUM structure.
IDataObject.GetDataHere(FORMATETC, STGMEDIUM)	Obtains data from a source data object. This method, which is called by a data consumer, differs from the GetData(FORMATETC, STGMEDIUM) method in that the caller must allocate and free the specified storage medium.
IDataObject.QueryGetData(FORMATETC)	Determines whether the data object is capable of rendering the data described in the FORMATETC structure. Objects attempting a paste or drop operation can call this method before calling GetData(FORMATETC, STGMEDIUM) to get an indication of whether the operation may be successful.
IDataObject.SetData(FORMATETC, STGMEDIUM, Boolean)	Transfers data to the object that implements this method. This method is called by an object that contains a data source.

See also

• Clipboard
• IDataObject
• DataFormats