Dados e objetos de dados

Os dados transferidos como parte de uma operação de arrastar e soltar são armazenados em um objeto de dados. Conceitualmente, um objeto de dados consiste em um ou mais dos seguintes pares:

• Um Object que contém os dados reais.

• Um identificador de formato de dados correspondente.

Os dados em si podem consistir em qualquer coisa que possa ser representada como uma base Object. O formato de dados correspondente é uma cadeia de caracteres ou Type que fornece uma dica sobre em qual formato os dados estão. Os objetos de dados dão suporte à hospedagem de vários pares de formato de dados/dados; isso permite que um único objeto de dados forneça dados em vários formatos.

Objetos de dados

Todos os objetos de dados devem implementar a IDataObject interface, que fornece o seguinte conjunto padrão de métodos que habilitam e facilitam a transferência de dados.

Método	Resumo
GetData	Recupera um objeto de dados em um formato de dados especificado.
GetDataPresent	Verifica se os dados estão disponíveis ou podem ser convertidos em um formato especificado.
GetFormats	Retorna uma lista de formatos nos quais os dados neste objeto de dados são armazenados ou podem ser convertidos.
SetData	Armazena os dados especificados neste objeto de dados.

O WPF fornece uma implementação básica de IDataObject na classe DataObject. A classe padrão DataObject é suficiente para muitos cenários comuns de transferência de dados.

Há vários formatos predefinidos, como bitmap, CSV, arquivo, HTML, RTF, cadeia de caracteres, texto e áudio. Para obter informações sobre os formatos de dados predefinidos fornecidos com o WPF, consulte o tópico de referência de DataFormats classe.

Os objetos de dados geralmente incluem uma instalação para converter automaticamente os dados armazenados em um formato em um formato diferente durante a extração de dados; essa instalação é conhecida como conversão automática. Ao consultar os formatos de dados disponíveis em um objeto de dados, é possível filtrar os formatos de dados automaticamente conversíveis dos formatos de dados nativos chamando o método GetFormats(Boolean) ou o método GetDataPresent(String, Boolean) e especificando o parâmetro autoConvert como false. Ao adicionar dados a um objeto de dados com o método SetData(String, Object, Boolean), a conversão automática de dados pode ser proibida definindo o parâmetro autoConvert como false.

Trabalhando com objetos de dados

Esta seção descreve técnicas comuns para criar e trabalhar com objetos de dados.

Criando novos objetos de dados

A DataObject classe fornece vários construtores sobrecarregados que facilitam o preenchimento de uma nova DataObject instância com um único par de dados/formato de dados.

O código de exemplo a seguir cria um novo objeto de dados e usa um dos construtores sobrecarregados (DataObject) para inicializar o objeto de dados com uma cadeia de caracteres DataObject(String, Object)e um formato de dados especificado. Nesse caso, o formato de dados é especificado por uma cadeia de caracteres; a DataFormats classe fornece um conjunto de cadeias de caracteres de tipo predefinidas. A conversão automática dos dados armazenados é permitida por padrão.

string stringData = "Some string data to store...";
string dataFormat = DataFormats.UnicodeText;
DataObject dataObject = new DataObject(dataFormat, stringData);

Dim stringData As String = "Some string data to store..."
Dim dataFormat As String = DataFormats.UnicodeText
Dim dataObject As New DataObject(dataFormat, stringData)

Para obter mais exemplos de código que cria um objeto de dados, consulte Criar um objeto de dados.

Armazenando dados em vários formatos

Um único objeto de dados é capaz de armazenar dados em vários formatos. O uso estratégico de vários formatos de dados em um único objeto de dados potencialmente torna o objeto de dados consumível por uma variedade maior de destinos de descarte do que se apenas um único formato de dados pudesse ser representado. Observe que, em geral, uma fonte de arrastar deve ser independente sobre os formatos de dados que são consumíveis por possíveis destinos de descarte.

O exemplo a seguir mostra como usar o SetData(String, Object) método para adicionar dados a um objeto de dados em vários formatos.

DataObject dataObject = new DataObject();
string sourceData = "Some string data to store...";

// Encode the source string into Unicode byte arrays.
byte[] unicodeText = Encoding.Unicode.GetBytes(sourceData); // UTF-16
byte[] utf8Text = Encoding.UTF8.GetBytes(sourceData);
byte[] utf32Text = Encoding.UTF32.GetBytes(sourceData);

// The DataFormats class does not provide data format fields for denoting
// UTF-32 and UTF-8, which are seldom used in practice; the following strings
// will be used to identify these "custom" data formats.
string utf32DataFormat = "UTF-32";
string utf8DataFormat  = "UTF-8";

// Store the text in the data object, letting the data object choose
// the data format (which will be DataFormats.Text in this case).
dataObject.SetData(sourceData);
// Store the Unicode text in the data object.  Text data can be automatically
// converted to Unicode (UTF-16 / UCS-2) format on extraction from the data object;
// Therefore, explicitly converting the source text to Unicode is generally unnecessary, and
// is done here as an exercise only.
dataObject.SetData(DataFormats.UnicodeText, unicodeText);
// Store the UTF-8 text in the data object...
dataObject.SetData(utf8DataFormat, utf8Text);
// Store the UTF-32 text in the data object...
dataObject.SetData(utf32DataFormat, utf32Text);

Dim dataObject As New DataObject()
Dim sourceData As String = "Some string data to store..."

' Encode the source string into Unicode byte arrays.
Dim unicodeText() As Byte = Encoding.Unicode.GetBytes(sourceData) ' UTF-16
Dim utf8Text() As Byte = Encoding.UTF8.GetBytes(sourceData)
Dim utf32Text() As Byte = Encoding.UTF32.GetBytes(sourceData)

' The DataFormats class does not provide data format fields for denoting
' UTF-32 and UTF-8, which are seldom used in practice; the following strings 
' will be used to identify these "custom" data formats.
Dim utf32DataFormat As String = "UTF-32"
Dim utf8DataFormat As String = "UTF-8"

' Store the text in the data object, letting the data object choose
' the data format (which will be DataFormats.Text in this case).
dataObject.SetData(sourceData)
' Store the Unicode text in the data object.  Text data can be automatically
' converted to Unicode (UTF-16 / UCS-2) format on extraction from the data object; 
' Therefore, explicitly converting the source text to Unicode is generally unnecessary, and
' is done here as an exercise only.
dataObject.SetData(DataFormats.UnicodeText, unicodeText)
' Store the UTF-8 text in the data object...
dataObject.SetData(utf8DataFormat, utf8Text)
' Store the UTF-32 text in the data object...
dataObject.SetData(utf32DataFormat, utf32Text)

Consultando um objeto de dados para formatos disponíveis

Como um único objeto de dados pode conter um número arbitrário de formatos de dados, os objetos de dados incluem instalações para recuperar uma lista de formatos de dados disponíveis.

O código de exemplo a seguir usa a GetFormats sobrecarga para obter uma matriz de cadeias de caracteres que denotam todos os formatos de dados disponíveis em um objeto de dados (nativo e por conversão automática).

DataObject dataObject = new DataObject("Some string data to store...");

// Get an array of strings, each string denoting a data format
// that is available in the data object.  This overload of GetDataFormats
// returns all available data formats, native and auto-convertible.
string[] dataFormats = dataObject.GetFormats();

// Get the number of data formats present in the data object, including both
// auto-convertible and native data formats.
int numberOfDataFormats = dataFormats.Length;

// To enumerate the resulting array of data formats, and take some action when
// a particular data format is found, use a code structure similar to the following.
foreach (string dataFormat in dataFormats)
{
    if (dataFormat == DataFormats.Text)
    {
        // Take some action if/when data in the Text data format is found.
        break;
    }
    else if(dataFormat == DataFormats.StringFormat)
    {
        // Take some action if/when data in the string data format is found.
        break;
    }
}

Dim dataObject As New DataObject("Some string data to store...")

' Get an array of strings, each string denoting a data format
' that is available in the data object.  This overload of GetDataFormats
' returns all available data formats, native and auto-convertible.
Dim dataFormats() As String = dataObject.GetFormats()

' Get the number of data formats present in the data object, including both
' auto-convertible and native data formats.
Dim numberOfDataFormats As Integer = dataFormats.Length

' To enumerate the resulting array of data formats, and take some action when
' a particular data format is found, use a code structure similar to the following.
For Each dataFormat As String In dataFormats
    If dataFormat = System.Windows.DataFormats.Text Then
        ' Take some action if/when data in the Text data format is found.
        Exit For
    ElseIf dataFormat = System.Windows.DataFormats.StringFormat Then
        ' Take some action if/when data in the string data format is found.
        Exit For
    End If
Next dataFormat

Para obter mais exemplos de código que consulta um objeto de dados para formatos de dados disponíveis, consulte Listar os Formatos de Dados em um Objeto de Dados. Para obter exemplos de consulta de um objeto de dados para a presença de um formato de dados específico, consulte Determine se um formato de dados está presente em um objeto de dados.

Recuperando dados de um objeto de dados

Recuperar dados de um objeto de dados em um formato específico simplesmente envolve chamar um dos GetData métodos e especificar o formato de dados desejado. Um dos GetDataPresent métodos pode ser usado para verificar a presença de um formato de dados específico. GetData retorna os dados em um Object; dependendo do formato de dados, esse objeto pode ser convertido em um contêiner específico do tipo.

O código de exemplo a seguir usa a GetDataPresent(String) sobrecarga para verificar se um formato de dados especificado está disponível (nativo ou por conversão automática). Se o formato especificado estiver disponível, o exemplo recuperará os dados usando o GetData(String) método.

DataObject dataObject = new DataObject("Some string data to store...");

string desiredFormat = DataFormats.UnicodeText;
byte[] data = null;

// Use the GetDataPresent method to check for the presence of a desired data format.
// This particular overload of GetDataPresent looks for both native and auto-convertible
// data formats.
if (dataObject.GetDataPresent(desiredFormat))
{
    // If the desired data format is present, use one of the GetData methods to retrieve the
    // data from the data object.
    data = dataObject.GetData(desiredFormat) as byte[];
}

Dim dataObject As New DataObject("Some string data to store...")

Dim desiredFormat As String = DataFormats.UnicodeText
Dim data() As Byte = Nothing

' Use the GetDataPresent method to check for the presence of a desired data format.
' This particular overload of GetDataPresent looks for both native and auto-convertible 
' data formats.
If dataObject.GetDataPresent(desiredFormat) Then
    ' If the desired data format is present, use one of the GetData methods to retrieve the
    ' data from the data object.
    data = TryCast(dataObject.GetData(desiredFormat), Byte())
End If

Para obter mais exemplos de código que recupera dados de um objeto de dados, consulte Recuperar Dados em um formato de dados específico.

Removendo dados de um objeto de dados

Os dados não podem ser removidos diretamente de um objeto de dados. Para remover efetivamente os dados de um objeto de dados, siga estas etapas:

1. Crie um novo objeto de dados que conterá apenas os dados que você deseja reter.

2. "Copie" os dados desejados do objeto de dados antigo para o novo objeto de dados. Para copiar os dados, use um dos GetData métodos para recuperar um Object que contenha os dados brutos e use um dos SetData métodos para adicionar os dados ao novo objeto de dados.

3. Substitua o objeto de dados antigo pelo novo.

Observação

Os SetData métodos só adicionam dados a um objeto de dados; eles não substituem dados, mesmo que os dados e o formato de dados sejam exatamente iguais a uma chamada anterior. Chamar SetData duas vezes para os mesmos dados e formato de dados resultará na presença desses dados/formato de dados duas vezes no objeto de dados.