How to: Retrieve Data from the Clipboard

The Clipboard class provides methods that you can use to interact with the Windows operating system Clipboard feature. Many applications use the Clipboard as a temporary repository for data. For example, word processors use the Clipboard during cut-and-paste operations. The Clipboard is also useful for transferring information from one application to another.

Some applications store data on the Clipboard in multiple formats to increase the number of other applications that can potentially use the data. A Clipboard format is a string that identifies the format. An application that uses the identified format can retrieve the associated data on the Clipboard. The DataFormats class provides predefined format names for your use. You can also use your own format names or use an object's type as its format. For information about adding data to the Clipboard, see How to: Add Data to the Clipboard.

To determine whether the Clipboard contains data in a particular format, use one of the ContainsFormat methods or the GetData method. To retrieve data from the Clipboard, use one of the GetFormat methods or the GetData method. These methods are new in Microsoft .NET Framework version 2.0.

To access data from the Clipboard by using versions earlier than .NET Framework 2.0, use the GetDataObject method and call the methods of the returned IDataObject. To determine whether a particular format is available in the returned object, for example, call the GetDataPresent method.

Note
All Windows-based applications share the system Clipboard. Therefore, the contents are subject to change when you switch to another application. The Clipboard class can only be used in threads set to single thread apartment (STA) mode. To use this class, ensure that your Main method is marked with the STAThreadAttribute attribute.

To retrieve data from the Clipboard in a single, common format

• Use the GetAudioStream, GetFileDropList, GetImage, or GetText method. Optionally, use the corresponding ContainsFormat methods first to determine whether data is available in a particular format. These methods are available only in Microsoft .NET Framework version 2.0.

  ' Demonstrates SetAudio, ContainsAudio, and GetAudioStream.
  Public Function SwapClipboardAudio( _
      ByVal replacementAudioStream As System.IO.Stream) _
      As System.IO.Stream
  
      Dim returnAudioStream As System.IO.Stream = Nothing
  
      If (Clipboard.ContainsAudio()) Then
          returnAudioStream = Clipboard.GetAudioStream()
          Clipboard.SetAudio(replacementAudioStream)
      End If
  
      Return returnAudioStream
  
  End Function
  
  ' Demonstrates SetFileDropList, ContainsFileDroList, and GetFileDropList
  Public Function SwapClipboardFileDropList(ByVal replacementList _
      As System.Collections.Specialized.StringCollection) _
      As System.Collections.Specialized.StringCollection
  
      Dim returnList As System.Collections.Specialized.StringCollection _
          = Nothing
  
      If Clipboard.ContainsFileDropList() Then
  
          returnList = Clipboard.GetFileDropList()
          Clipboard.SetFileDropList(replacementList)
      End If
  
      Return returnList
  
  End Function
  
  ' Demonstrates SetImage, ContainsImage, and GetImage.
  Public Function SwapClipboardImage( _
      ByVal replacementImage As System.Drawing.Image) _
      As System.Drawing.Image
  
      Dim returnImage As System.Drawing.Image = Nothing
  
      If Clipboard.ContainsImage() Then
          returnImage = Clipboard.GetImage()
          Clipboard.SetImage(replacementImage)
      End If
  
      Return returnImage
  End Function
  
  ' Demonstrates SetText, ContainsText, and GetText.
  Public Function SwapClipboardHtmlText( _
      ByVal replacementHtmlText As String) As String
  
      Dim returnHtmlText As String = Nothing
  
      If (Clipboard.ContainsText(TextDataFormat.Html)) Then
          returnHtmlText = Clipboard.GetText(TextDataFormat.Html)
          Clipboard.SetText(replacementHtmlText, TextDataFormat.Html)
      End If
  
      Return returnHtmlText
  
  End Function
  

  // Demonstrates SetAudio, ContainsAudio, and GetAudioStream.
  public System.IO.Stream SwapClipboardAudio(
      System.IO.Stream replacementAudioStream)
  {
      System.IO.Stream returnAudioStream = null;
      if (Clipboard.ContainsAudio())
      {
          returnAudioStream = Clipboard.GetAudioStream();
          Clipboard.SetAudio(replacementAudioStream);
      }
      return returnAudioStream;
  }
  
  // Demonstrates SetFileDropList, ContainsFileDroList, and GetFileDropList
  public System.Collections.Specialized.StringCollection
      SwapClipboardFileDropList(
      System.Collections.Specialized.StringCollection replacementList)
  {
      System.Collections.Specialized.StringCollection returnList = null;
      if (Clipboard.ContainsFileDropList())
      {
          returnList = Clipboard.GetFileDropList();
          Clipboard.SetFileDropList(replacementList);
      }
      return returnList;
  }
  
  // Demonstrates SetImage, ContainsImage, and GetImage.
  public System.Drawing.Image SwapClipboardImage(
      System.Drawing.Image replacementImage)
  {
      System.Drawing.Image returnImage = null;
      if (Clipboard.ContainsImage())
      {
          returnImage = Clipboard.GetImage();
          Clipboard.SetImage(replacementImage);
      }
      return returnImage;
  }
  
  // Demonstrates SetText, ContainsText, and GetText.
  public String SwapClipboardHtmlText(String replacementHtmlText)
  {
      String returnHtmlText = null;
      if (Clipboard.ContainsText(TextDataFormat.Html))
      {
          returnHtmlText = Clipboard.GetText(TextDataFormat.Html);
          Clipboard.SetText(replacementHtmlText, TextDataFormat.Html);
      }
      return returnHtmlText;
  }
  

To retrieve data from the Clipboard in a custom format

• Use the GetData method with a custom format name. This method is available only in Microsoft .NET Framework version 2.0.

  You can also use predefined format names with the SetData method. For more information, see DataFormats.

      ' Demonstrates SetData, ContainsData, and GetData
      ' using a custom format name and a business object.
      Public ReadOnly Property TestCustomFormat() As Customer
          Get
              Clipboard.SetData("CustomerFormat", New Customer("Customer Name"))
  
              If Clipboard.ContainsData("CustomerFormat") Then
                  Return CType(Clipboard.GetData("CustomerFormat"), Customer)
              End If
  
              Return Nothing
          End Get
      End Property
  
  ...
      <Serializable()> Public Class Customer
  
          Private nameValue As String = String.Empty
  
          Public Sub New(ByVal name As String)
              nameValue = name
          End Sub
  
          Public Property Name() As String
              Get
                  Return nameValue
              End Get
              Set(ByVal value As String)
                  nameValue = value
              End Set
          End Property
  
      End Class
  

      // Demonstrates SetData, ContainsData, and GetData
      // using a custom format name and a business object.
      public Customer TestCustomFormat
      {
          get
          {
              Clipboard.SetData("CustomerFormat", new Customer("Customer Name"));
              if (Clipboard.ContainsData("CustomerFormat")) 
              {
                  return Clipboard.GetData("CustomerFormat") as Customer;
              }
              return null;
          }
      }
  
  ...
      [Serializable]
      public class Customer
      {
          private string nameValue = string.Empty;
          public Customer(String name)
          {
              nameValue = name;
          }
          public string Name
          {
              get { return nameValue; }
              set { nameValue = value; }
          }
      }
  

To retrieve data from the Clipboard in multiple formats

• Use the GetDataObject method. You must use this method to retrieve data from the Clipboard on versions earlier than .NET Framework 2.0.

      ' Demonstrates how to use a DataObject to add
      ' data to the Clipboard in multiple formats.
      Public Sub TestClipboardMultipleFormats()
  
          Dim data As New DataObject()
  
          ' Add a Customer object using the type as the format.
          data.SetData(New Customer("Customer as Customer object"))
  
          ' Add a ListViewItem object using a custom format name.
          data.SetData("CustomFormat", _
              New ListViewItem("Customer as ListViewItem"))
  
          Clipboard.SetDataObject(data)
          Dim retrievedData As DataObject = _
              CType(Clipboard.GetDataObject(), DataObject)
  
          If (retrievedData.GetDataPresent("CustomFormat")) Then
  
              Dim item As ListViewItem = _
                  TryCast(retrievedData.GetData("CustomFormat"), ListViewItem)
  
              If item IsNot Nothing Then
                  MessageBox.Show(item.Text)
              End If
  
          End If
  
          If retrievedData.GetDataPresent(GetType(Customer)) Then
  
              Dim customer As Customer = _
                  CType(retrievedData.GetData(GetType(Customer)), Customer)
  
              If customer IsNot Nothing Then
  
                  MessageBox.Show(customer.Name)
              End If
  
          End If
  
      End Sub
  
  ...
      <Serializable()> Public Class Customer
  
          Private nameValue As String = String.Empty
  
          Public Sub New(ByVal name As String)
              nameValue = name
          End Sub
  
          Public Property Name() As String
              Get
                  Return nameValue
              End Get
              Set(ByVal value As String)
                  nameValue = value
              End Set
          End Property
  
      End Class
  

      // Demonstrates how to use a DataObject to add
      // data to the Clipboard in multiple formats.
      public void TestClipboardMultipleFormats()
      {
          DataObject data = new DataObject();
  
          // Add a Customer object using the type as the format.
          data.SetData(new Customer("Customer as Customer object"));
  
          // Add a ListViewItem object using a custom format name.
          data.SetData("CustomFormat", 
              new ListViewItem("Customer as ListViewItem"));
  
          Clipboard.SetDataObject(data);
          DataObject retrievedData = (DataObject)Clipboard.GetDataObject();
  
          if (retrievedData.GetDataPresent("CustomFormat"))
          {
              ListViewItem item = 
                  retrievedData.GetData("CustomFormat") as ListViewItem;
              if (item != null)
              {
                  MessageBox.Show(item.Text);
              }
          }
  
          if (retrievedData.GetDataPresent(typeof(Customer)))
          {
              Customer customer = 
                  retrievedData.GetData(typeof(Customer)) as Customer;
              if (customer != null)
              {
                  MessageBox.Show(customer.Name);
              }
          }
      }
  
  ...
      [Serializable]
      public class Customer
      {
          private string nameValue = string.Empty;
          public Customer(String name)
          {
              nameValue = name;
          }
          public string Name
          {
              get { return nameValue; }
              set { nameValue = value; }
          }
      }
  

See Also

Tasks

How to: Add Data to the Clipboard

Other Resources

Drag-and-Drop Operations and Clipboard Support