.NET 2.0+

Using the Clipboard to Transfer Text

by Richard Carr, published at http://www.blackwasp.co.uk/ClipboardText.aspx

The Windows clipboard is a useful temporary storage area for information that users can use when copying and pasting information within a single application or between programs. The contents of the clipboard can be manipulated from .NET software.

The Clipboard

Most Windows users are familiar with the use of the clipboard, which holds information that you have cut or copied from a program. You can later paste the information from the clipboard into the same software that it generated it, or into a compatible program. This makes it easy to transfer information between applications, or to reorganise or duplicate information within a single program. For example, whilst word processing you might cut a paragraph of text from a document and paste it into a different position.

When you are developing applications using .NET, you can read and manipulate clipboard information easily. Many standard controls include clipboard functionality automatically. For example, text boxes support it using the keyboard combinations Ctrl-X, Ctrl-C and Ctrl-V for cut, copy and paste respectively. You can also right-click a text box and choose these operations from a context-sensitive menu.

Sometimes you will want to perform more complex operations or provide clipboard functionality for controls that do not normally support it. For example, you may create a form that permits the user to enter a number of details about a product. You may wish to add a Copy button to such a form that, when clicked, copies all of the entered information as a single unit. You can create this type of functionality using members of the Clipboard class, which is found in the System.Windows.Forms namespace.

The Clipboard class allows you to programmatically read and modify the clipboard's contents using various types of information, including plain or formatted text, audio clips, images and serialized object data. In this article we'll examine the basic operations relating to cutting, copying and pasting text. We'll also see how to clear the contents of the clipboard entirely.

Creating the Example Project

To begin, start Visual Studio and create a new Windows Forms Application project. Once the project is initialised, we need to add five controls to the form. These are detailed below:

If you decide to download the sample project using the link at the start of this article you'll see the form arranged as shown below:

Reading the Clipboard

Let's start with the Paste button. When working with the Clipboard class the concepts of cut, copy and paste don't apply. Instead, you simply read data from, or write data to, the clipboard. To paste means reading the clipboard's contents and applying them within your software.

In the sample, we'll read the clipboard and set the Text property of the text box accordingly. We do this using the static GetText method. The method has two overloads. The parameterless version reads any text information from the clipboard and returns it in a string. If the clipboard is empty or contains information that cannot be represented as text, the returned string is empty. The second overload requires an argument that contains a value from the TextDataFormat enumeration. This defines the type of data that's expected. If the clipboard does not contain the specified type of text the return value is empty.

The available options provided by the TextDataFormat enumeration are:

• CommaSeparatedValue. Comma-separated values (CSV). This format is often used to transfer tabular data or spread sheet information.
• Html. Use this option to specify that you wish to retrieve HTML from the clipboard.
• Rtf. Indicates the requirement for rich text file data. This is text with complex formatting options.
• Text. Use the Text option when you wish to retrieve basic ANSI-encoded text.
• UnicodeText. This option indicates that you expect plain text that is encoded using Unicode.

Double-click the Paste button in the window designer and add the following event code to create the simplest possible paste option for text.

private void PasteButton_Click(object sender, EventArgs e)
{
    DemoText.Text = Clipboard.GetText();
}

As mentioned above, if the clipboard is empty or contains information that is not compatible with the GetText method used, the return value is an empty string. If you wish to check the compatibility of the contents of the clipboard before reading text, you can do so using the ContainsText method. To check if text of a specific format is present, pass the format as a TextDataFormat value. If you don't care about the format, use no parameters.

To demonstrate, modify the Paste button's code as shown below. This detects when the clipboard data is incompatible and shows a standard message. Try running the program and pasting information copied from Notepad to see the results.

private void PasteButton_Click(object sender, EventArgs e)
{
    if (Clipboard.ContainsText())
        DemoText.Text = Clipboard.GetText();
    else
        DemoText.Text = "Clipboard empty or incompatible";
}

NB: You should not rely on ContainsText completely. In the short time between checking if the clipboard contains suitable data and reading the information, it is possible that another thread or application will clear or modify the clipboard's content.