Export (0) Print
Expand All

DataObject Class

Implements a basic data transfer mechanism.

Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in system.windows.forms.dll)

[ClassInterfaceAttribute(ClassInterfaceType::None)] 
public ref class DataObject : IDataObject, IDataObject
/** @attribute ClassInterfaceAttribute(ClassInterfaceType.None) */ 
public class DataObject implements IDataObject, IDataObject
ClassInterfaceAttribute(ClassInterfaceType.None) 
public class DataObject implements IDataObject, IDataObject

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 Microsoft .NET Framework version 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.

NoteNote

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). For more information, see article 323530, "Metafiles on Clipboard Are Not Visible to All Applications," in the Microsoft Knowledge Base at http://support.microsoft.com.

An object must be serializable for it to be put on the Clipboard. See 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.

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.set_Text("Data of type " + myType.ToString() 
            + " is present in the DataObject");
    }
    else {
        textBox1.set_Text("Data of type " + myType.ToString() 
            + " is not present in the DataObject");
    }
} //AddMyData3

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( "System.String" )->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.set_Text(myDataObject.GetData("System.String").ToString());
} //GetMyData2

System.Object
  System.Windows.Forms.DataObject

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0

Community Additions

ADD
Show:
© 2014 Microsoft