Clipboard Class

 

Provides methods to place data on and retrieve data from the system Clipboard. This class cannot be inherited.

Namespace:   System.Windows.Forms
Assembly:  System.Windows.Forms (in System.Windows.Forms.dll)

System::Object
  System.Windows.Forms::Clipboard

public ref class Clipboard sealed 

NameDescription
System_CAPS_pubmethodSystem_CAPS_staticClear()

Removes all data from the Clipboard.

System_CAPS_pubmethodSystem_CAPS_staticContainsAudio()

Indicates whether there is data on the Clipboard in the WaveAudio format.

System_CAPS_pubmethodSystem_CAPS_staticContainsData(String^)

Indicates whether there is data on the Clipboard that is in the specified format or can be converted to that format.

System_CAPS_pubmethodSystem_CAPS_staticContainsFileDropList()

Indicates whether there is data on the Clipboard that is in the FileDrop format or can be converted to that format.

System_CAPS_pubmethodSystem_CAPS_staticContainsImage()

Indicates whether there is data on the Clipboard that is in the Bitmap format or can be converted to that format.

System_CAPS_pubmethodSystem_CAPS_staticContainsText()

Indicates whether there is data on the Clipboard in the Text or UnicodeText format, depending on the operating system.

System_CAPS_pubmethodSystem_CAPS_staticContainsText(TextDataFormat)

Indicates whether there is text data on the Clipboard in the format indicated by the specified TextDataFormat value.

System_CAPS_pubmethodEquals(Object^)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_pubmethodSystem_CAPS_staticGetAudioStream()

Retrieves an audio stream from the Clipboard.

System_CAPS_pubmethodSystem_CAPS_staticGetData(String^)

Retrieves data from the Clipboard in the specified format.

System_CAPS_pubmethodSystem_CAPS_staticGetDataObject()

Retrieves the data that is currently on the system Clipboard.

System_CAPS_pubmethodSystem_CAPS_staticGetFileDropList()

Retrieves a collection of file names from the Clipboard.

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodSystem_CAPS_staticGetImage()

Retrieves an image from the Clipboard.

System_CAPS_pubmethodSystem_CAPS_staticGetText()

Retrieves text data from the Clipboard in the Text or UnicodeText format, depending on the operating system.

System_CAPS_pubmethodSystem_CAPS_staticGetText(TextDataFormat)

Retrieves text data from the Clipboard in the format indicated by the specified TextDataFormat value.

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodSystem_CAPS_staticSetAudio(array<Byte>^)

Clears the Clipboard and then adds a Byte array in the WaveAudio format after converting it to a Stream.

System_CAPS_pubmethodSystem_CAPS_staticSetAudio(Stream^)

Clears the Clipboard and then adds a Stream in the WaveAudio format.

System_CAPS_pubmethodSystem_CAPS_staticSetData(String^, Object^)

Clears the Clipboard and then adds data in the specified format.

System_CAPS_pubmethodSystem_CAPS_staticSetDataObject(Object^)

Clears the Clipboard and then places nonpersistent data on it.

System_CAPS_pubmethodSystem_CAPS_staticSetDataObject(Object^, Boolean)

Clears the Clipboard and then places data on it and specifies whether the data should remain after the application exits.

System_CAPS_pubmethodSystem_CAPS_staticSetDataObject(Object^, Boolean, Int32, Int32)

Clears the Clipboard and then attempts to place data on it the specified number of times and with the specified delay between attempts, optionally leaving the data on the Clipboard after the application exits.

System_CAPS_pubmethodSystem_CAPS_staticSetFileDropList(StringCollection^)

Clears the Clipboard and then adds a collection of file names in the FileDrop format.

System_CAPS_pubmethodSystem_CAPS_staticSetImage(Image^)

Clears the Clipboard and then adds an Image in the Bitmap format.

System_CAPS_pubmethodSystem_CAPS_staticSetText(String^)

Clears the Clipboard and then adds text data in the Text or UnicodeText format, depending on the operating system.

System_CAPS_pubmethodSystem_CAPS_staticSetText(String^, TextDataFormat)

Clears the Clipboard and then adds text data in the format indicated by the specified TextDataFormat value.

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

For a list of predefined formats to use with the Clipboard class, see the DataFormats class.

Call SetDataObject to put data on the Clipboard, replacing its current contents. To place a persistent copy of the data on the Clipboard, set the copy parameter to true.

System_CAPS_noteNote

To place data on the Clipboard in multiple formats, use the DataObject class or an IDataObject implementation. Place data on the Clipboard in multiple formats to maximize the possibility that a target application, whose format requirements you might not know, can successfully retrieve the data.

Call GetDataObject to retrieve data from the Clipboard. The data is returned as an object that implements the IDataObject interface. Use the methods specified by IDataObject and fields in DataFormats to extract the data from the object. If you do not know the format of the data you retrieved, call the GetFormats method of the IDataObject interface to get a list of all formats that data is stored in. Then call the GetData method of the IDataObject interface, and specify a format that your application can use.

In .NET Framework 2.0, the Clipboard class provides additional methods that make it easier to work with the system Clipboard. Call the Clear method to remove all data from the Clipboard. To add data of a particular format to the Clipboard, replacing the existing data, call the appropriate SetFormat method, such as SetText, or call the SetData method to specify the format. To retrieve data of a particular format from the Clipboard, first call the appropriate ContainsFormat method (such as ContainsText) method to determine whether the Clipboard contains data in that format, and then call the appropriate GetFormat method (such as GetText) to retrieve the data if the Clipboard contains it. To specify the format in these operations, call the ContainsData and GetData methods instead.

System_CAPS_noteNote

All Windows-based applications share the system Clipboard, so the contents are subject to change when you switch to another application.

An object must be serializable for it to be put on the Clipboard. If you pass a non-serializable object to a Clipboard method, the method will fail without throwing an exception. 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.

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.

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.

The following code example uses Clipboard methods to place data on and retrieve it from the system Clipboard. This code assumes button1, button2, textBox1, and textBox2 have been created and placed on the form.

The button1_Click method calls SetDataObject to take selected text from the text box and place it on the system Clipboard.

The button2_Click method calls GetDataObject to retrieve data from the system Clipboard. The code uses IDataObject and DataFormats to extract the data returned and displays the data in textBox2.

private:
   void button1_Click( Object^ /*sender*/, System::EventArgs^ /*e*/ )
   {
      // Takes the selected text from a text box and puts it on the clipboard.
      if ( !textBox1->SelectedText->Equals( "" ) )
      {
         Clipboard::SetDataObject( textBox1->SelectedText );
      }
      else
      {
         textBox2->Text = "No text selected in textBox1";
      }
   }

   void button2_Click( Object^ /*sender*/, System::EventArgs^ /*e*/ )
   {
      // Declares an IDataObject to hold the data returned from the clipboard.
      // Retrieves the data from the clipboard.
      IDataObject^ iData = Clipboard::GetDataObject();

      // Determines whether the data is in a format you can use.
      if ( iData->GetDataPresent( DataFormats::Text ) )
      {
         // Yes it is, so display it in a text box.
         textBox2->Text = (String^)(iData->GetData( DataFormats::Text ));
      }
      else
      {
         // No it is not.
         textBox2->Text = "Could not retrieve data off the clipboard.";
      }
   }

.NET Framework
Available since 1.1

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

Return to top
Show: