Share via


How to: Add Data to 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 data from one application to another.

When you add data to the Clipboard, you can indicate the data format so that other applications can recognize the data if they can use that format. You can also add data to the Clipboard in multiple different formats to increase the number of other applications that can potentially use the data.

A Clipboard format is a string that identifies the format so that an application that uses that format can retrieve the associated data. The DataFormats class provides predefined format names for your use. You can also use your own format names or use the type of an object as its format.

To add data to the Clipboard in one or multiple formats, use the SetDataObject method. You can pass any object to this method, but to add data in multiple formats, you must first add the data to a separate object designed to work with multiple formats. Typically, you will add your data to a DataObject, but you can use any type that implements the IDataObject interface.

In Microsoft .NET Framework version 2.0, you can add data directly to the Clipboard by using new methods designed to make basic Clipboard tasks easier. Use these methods when you work with data in a single, common format such as text.

NoteNote

All Windows-based applications share the 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.

An object must be serializable for it to be put on the Clipboard. To make a type serializable, mark it with the SerializableAttribute attribute. If you pass a non-serializable object to a Clipboard method, the method will fail without throwing an exception. For more information about serialization, see Serialization.

To add data to the Clipboard in a single, common format

  • Use the SetAudio, SetFileDropList, SetImage, or SetText method. 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 add data to the Clipboard in a custom format

  • Use the SetData 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 add data to the Clipboard in multiple formats

  • Use the SetDataObject method and pass in a DataObject that contains your data. You must use this method to add data to 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: Retrieve Data from the Clipboard

Other Resources

Drag-and-Drop Operations and Clipboard Support