Clipboard Classe

Definição

Namespace:

System.Windows.Forms

Assembly:

System.Windows.Forms.dll

Fornece métodos para colocar dados e recuperar dados da área de transferência do sistema. Essa classe não pode ser herdada.

public ref class Clipboard abstract sealed

public static class Clipboard

type Clipboard = class

Public Class Clipboard

Herança

Object

Clipboard

Exemplos

O exemplo de código a seguir usa métodos Clipboard para colocar dados e recuperá-los da Área de Transferência do sistema. Esse código pressupõe button1, button2, textBox1e textBox2 foram criados e colocados no formulário.

O button1_Click método chama SetDataObject para tirar o texto selecionado da caixa de texto e colocá-lo na Área de Transferência do sistema.

O button2_Click método chama GetDataObject para recuperar dados da Área de Transferência do sistema. O código usa IDataObject e DataFormats para extrair os dados retornados e exibe os dados em 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.";
      }
   }

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 != "")
       Clipboard.SetDataObject(textBox1.SelectedText);
    else
       textBox2.Text = "No text selected in textBox1";
 }
 
 private 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.";
    }
 }

Private Sub button1_Click(sender As Object, e As System.EventArgs)
    ' Takes the selected text from a text box and puts it on the clipboard.
    If textBox1.SelectedText <> "" Then
        Clipboard.SetDataObject(textBox1.SelectedText)
    Else
        textBox2.Text = "No text selected in textBox1"
    End If
End Sub
 
Private Sub button2_Click(sender As Object, e As System.EventArgs)
    ' Declares an IDataObject to hold the data returned from the clipboard.
    ' Retrieves the data from the clipboard.
    Dim iData As IDataObject = Clipboard.GetDataObject()
    
    ' Determines whether the data is in a format you can use.
    If iData.GetDataPresent(DataFormats.Text) Then
        ' Yes it is, so display it in a text box.
        textBox2.Text = CType(iData.GetData(DataFormats.Text), String)
    Else
        ' No it is not.
        textBox2.Text = "Could not retrieve data off the clipboard."
    End If
End Sub

Comentários

Para obter uma lista de formatos predefinidos a serem usados com a Clipboard classe , consulte a DataFormats classe .

Chame SetDataObject para colocar dados na Área de Transferência, substituindo seu conteúdo atual. Para colocar uma cópia persistente dos dados na Área de Transferência, defina o copy parâmetro como true.

Observação

Para colocar dados na Área de Transferência em vários formatos, use a DataObject classe ou uma implementação IDataObject . Coloque dados na Área de Transferência em vários formatos para maximizar a possibilidade de que um aplicativo de destino, cujos requisitos de formato talvez você não saiba, possa recuperar os dados com êxito.

Chame GetDataObject para recuperar dados da Área de Transferência. Os dados são retornados como um objeto que implementa a IDataObject interface . Use os métodos especificados por IDataObject campos e em DataFormats para extrair os dados do objeto . Se você não souber o formato dos dados recuperados, chame o GetFormats método da IDataObject interface para obter uma lista de todos os formatos nos quais os dados são armazenados. Em seguida, chame o GetData método da IDataObject interface e especifique um formato que seu aplicativo possa usar.

No .NET Framework 2.0, a Clipboard classe fornece métodos adicionais que facilitam o trabalho com a Área de Transferência do sistema. Chame o Clear método para remover todos os dados da Área de Transferência. Para adicionar dados de um formato específico à Área de Transferência, substituindo os dados existentes, chame o método Format apropriadoSet, como SetText, ou chame o SetData método para especificar o formato. Para recuperar dados de um formato específico da Área de Transferência, primeiro chame o método Format apropriado Contains (como ContainsText) para determinar se a Área de Transferência contém dados nesse formato e, em seguida, chame o método Format apropriado Get (como GetText) para recuperar os dados se a Área de Transferência os contiver. Para especificar o formato nessas operações, chame os ContainsData métodos e GetData .

Observação

Todos os aplicativos baseados no Windows compartilham a Área de Transferência do sistema, portanto, o conteúdo está sujeito a alterações quando você alterna para outro aplicativo.

Um objeto deve ser serializável para que seja colocado na Área de Transferência. Se você passar um objeto não serializável para um método de Área de Transferência, o método falhará sem lançar uma exceção. Consulte System.Runtime.Serialization para obter mais informações sobre serialização. Se o aplicativo de destino exigir um formato de dados muito específico, os cabeçalhos adicionados aos dados no processo de serialização poderão impedir que o aplicativo reconheça seus dados. Para preservar o formato de dados, adicione seus dados como uma Byte matriz a um MemoryStream e passe o MemoryStream para o SetData método .

A Clipboard classe só pode ser usada em threads definidos como modo STA (single thread apartment). Para usar essa classe, verifique se o Main método está marcado com o STAThreadAttribute atributo .

Considerações especiais podem ser necessárias ao usar o formato de metafile com a Área de Transferência. Devido a uma limitação na implementação atual da DataObject classe, o formato de metafile usado pelo .NET Framework pode não ser reconhecido por aplicativos que usam um formato de metafile mais antigo. Nesse caso, você deve interoperar com as APIs (interfaces de programação de aplicativo) da Área de Transferência win32.

Métodos

Clear()	Remove todos os dados da área de transferência.
ContainsAudio()	Indica se há dados na Área de Transferência no formato WaveAudio.
ContainsData(String)	Indica se há dados na área de transferência que estão no formato especificado ou que podem ser convertidos nesse formato.
ContainsFileDropList()	Indica se há dados na Área de Transferência que estão no formato FileDrop ou que podem ser convertidos nesse formato.
ContainsImage()	Indica se há dados na Área de Transferência que estão no formato Bitmap ou que podem ser convertidos nesse formato.
ContainsText()	Indica se há dados na Área de Transferência no formato Text ou UnicodeText, dependendo do sistema operacional.
ContainsText(TextDataFormat)	Indica se há dados de texto da Área de Transferência no formato indicado pelo valor TextDataFormat especificado.
GetAudioStream()	Recupera um fluxo de áudio da área de transferência.
GetData(String)	Recupera dados da Área de Transferência no formato especificado.
GetDataObject()	Recupera os dados que atualmente estão na Área de Transferência do sistema.
GetFileDropList()	Recupera uma coleção de nomes de arquivo da Área de Transferência.
GetImage()	Recupera uma imagem da área de transferência.
GetText()	Recupera dados de texto da Área de Transferência no formato Text ou UnicodeText, dependendo do sistema operacional.
GetText(TextDataFormat)	Recupera os dados de texto da Área de Transferência no formato indicado pelo valor TextDataFormat especificado.
SetAudio(Byte[])	Limpa a Área de Transferência e adiciona uma matriz de Byte no formato WaveAudio após convertê-la para um Stream.
SetAudio(Stream)	Limpa a Área de Transferência e adiciona um Stream no formato WaveAudio.
SetData(String, Object)	Limpa a Área de Transferência e adiciona dados no formato especificado.
SetDataObject(Object)	Limpa a Área de Transferência e, em seguida, coloca os dados não persistentes nela.
SetDataObject(Object, Boolean)	Limpa a área de transferência e, em seguida, coloca os dados nela e especifica se eles devem permanecer após o encerramento do aplicativo.
SetDataObject(Object, Boolean, Int32, Int32)	Limpa a Área de Transferência e, em seguida, tenta colocar os dados nela pelo número especificado de vezes e com o atraso especificado entre as tentativas, opcionalmente, deixando os dados na Área de Transferência depois de sair do aplicativo.
SetFileDropList(StringCollection)	Limpa a Área de Transferência e, em seguida, adiciona uma coleção de nomes de arquivos no formato FileDrop.
SetImage(Image)	Limpa a Área de Transferência e adiciona um Image no formato Bitmap.
SetText(String)	Limpa a área de transferência e, em seguida, adiciona dados de texto no formato Text ou UnicodeText, dependendo do sistema operacional.
SetText(String, TextDataFormat)	Limpa a Área de Transferência e adiciona dados de texto no formato indicado pelo valor TextDataFormat especificado.

Confira também

• DataObject
• DataFormats
• IDataObject
• Considerações adicionais sobre Segurança do Windows Forms