Classe COleDataSource

  • Artigo

Atua como um cache no qual um aplicativo coloca os dados que ele oferecerá durante operações de transferência de dados, como área de transferência ou operações do tipo "arrastar e soltar".

Sintaxe

class COleDataSource : public CCmdTarget

Membros

Construtores públicos

Nome Descrição
COleDataSource::COleDataSource Constrói um objeto COleDataSource.

Métodos públicos

Nome Descrição
COleDataSource::CacheData Oferece dados em um formato especificado usando uma estrutura STGMEDIUM.
COleDataSource::CacheGlobalData Oferece dados em um formato especificado usando um HGLOBAL.
COleDataSource::DelayRenderData Oferece dados em um formato especificado usando uma renderização com atraso.
COleDataSource::DelayRenderFileData Oferece dados em um formato especificado usando um ponteiro CFile.
COleDataSource::DelaySetData Chamado para cada formato com suporte em OnSetData.
COleDataSource::DoDragDrop Executa operações do tipo "arrastar e soltar" com uma fonte de dados.
COleDataSource::Empty Esvazia o objeto COleDataSource de dados.
COleDataSource::FlushClipboard Renderiza todos os dados na área de transferência.
COleDataSource::GetClipboardOwner Verifica se os dados colocados na área de transferência ainda estão lá.
COleDataSource::OnRenderData Recupera dados como parte da renderização com atraso.
COleDataSource::OnRenderFileData Recupera dados em um CFile como parte da renderização com atraso.
COleDataSource::OnRenderGlobalData Recupera dados em um HGLOBAL como parte da renderização com atraso.
COleDataSource::OnSetData Chamado para substituir os dados no objeto COleDataSource.
COleDataSource::SetClipboard Coloca um objeto COleDataSource na área de transferência.

Comentários

Você pode criar fontes de dados OLE diretamente. Como alternativa, as classes COleClientItem e COleServerItem criam fontes de dados OLE em resposta às suas funções de membro CopyToClipboard e DoDragDrop. Consulte COleServerItem::CopyToClipboard para obter uma breve descrição. Substitua a função de membro OnGetClipboardData do item do cliente ou da classe de item do servidor para adicionar formatos adicionais da área de transferência aos dados na fonte de dados OLE criada para a função de membro CopyToClipboard ou DoDragDrop.

Sempre que quiser preparar dados para uma transferência, você deverá criar um objeto dessa classe e preenchê-los com seus dados usando o método mais apropriado para seus dados. A forma como ela é inserida em uma fonte de dados é diretamente afetada por se os dados são fornecidos imediatamente (renderização imediata) ou sob demanda (renderização com atraso). Para cada formato de área de transferência no qual você está fornecendo dados passando o formato da área de transferência a ser usado (e uma estrutura FORMATETC opcional), chame DelayRenderData.

Para obter mais informações sobre fontes de dados e transferência de dados, confira o artigo Objetos de Dados e Fontes de Dados (OLE). Além disso, o artigo Tópicos da área de transferência descreve o mecanismo de área de transferência OLE.

Hierarquia de herança

CObject

CCmdTarget

COleDataSource

Requisitos

Cabeçalho: afxole.h

COleDataSource::CacheData

Chame essa função para especificar um formato no qual os dados são oferecidos durante operações de transferência de dados.

void CacheData(
    CLIPFORMAT cfFormat,
    LPSTGMEDIUM lpStgMedium,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

cfFormat
O formato de área de transferência no qual os dados devem ser oferecidos. Esse parâmetro pode ser um dos formatos predefinidos da área de transferência ou o valor retornado pela função nativa RegisterClipboardFormat do Windows.

lpStgMedium
Aponta para uma estrutura STGMEDIUM que contém os dados no formato especificado.

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato no qual os dados devem ser oferecidos. Forneça um valor para esse parâmetro se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado pelo cfFormat. Se for NULL, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Comentários

Você deve fornecer os dados, pois essa função os fornece usando renderização imediata. Os dados são armazenados em cache até que seja necessário.

Forneça os dados usando uma estrutura STGMEDIUM. Você também poderá usar a função de membro CacheGlobalData se a quantidade de dados que você está fornecendo for pequena o suficiente para ser transferida com eficiência usando um HGLOBAL.

Após a chamada para CacheData, o membro ptd de lpFormatEtc e o conteúdo do lpStgMedium são de propriedade do objeto de dados, não do chamador.

Para usar a renderização com atraso, chame a função de membro DelayRenderData ou DelayRenderFileData. Para obter mais informações sobre renderização com atraso conforme tratado pelo MFC, confira o artigo Objetos de dados e fontes de dados: manipulação.

Para obter mais informações, confira as estruturas STGMEDIUM e FORMATETC no SDK do Windows.

Para obter mais informações, confira RegisterClipboardFormat no SDK do Windows.

COleDataSource::CacheGlobalData

Chame essa função para especificar um formato no qual os dados são oferecidos durante operações de transferência de dados.

void CacheGlobalData(
    CLIPFORMAT cfFormat,
    HGLOBAL hGlobal,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

cfFormat
O formato de área de transferência no qual os dados devem ser oferecidos. Esse parâmetro pode ser um dos formatos predefinidos da área de transferência ou o valor retornado pela função nativa RegisterClipboardFormat do Windows.

hGlobal
Manipule para o bloco de memória global que contém os dados no formato especificado.

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato no qual os dados devem ser oferecidos. Forneça um valor para esse parâmetro se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado pelo cfFormat. Se for NULL, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Comentários

Essa função fornece os dados usando a renderização imediata, portanto, você deve fornecer os dados ao chamar a função. Os dados são armazenados em cache até que seja necessário. Use a função de membro CacheData se você estiver fornecendo uma grande quantidade de dados ou se precisar de um meio de armazenamento estruturado.

Para usar a renderização com atraso, chame a função de membro DelayRenderData ou DelayRenderFileData. Para obter mais informações sobre renderização com atraso conforme tratado pelo MFC, confira o artigo Objetos de dados e fontes de dados: manipulação.

Para obter mais informações, confira a estrutura FORMATETC no SDK do Windows.

Para obter mais informações, confira RegisterClipboardFormat no SDK do Windows.

COleDataSource::COleDataSource

Constrói um objeto COleDataSource.

COleDataSource();

COleDataSource::DelayRenderData

Chame essa função para especificar um formato no qual os dados são oferecidos durante operações de transferência de dados.

void DelayRenderData(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

cfFormat
O formato de área de transferência no qual os dados devem ser oferecidos. Esse parâmetro pode ser um dos formatos predefinidos da área de transferência ou o valor retornado pela função nativa RegisterClipboardFormat do Windows.

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato no qual os dados devem ser oferecidos. Forneça um valor para esse parâmetro se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado pelo cfFormat. Se for NULL, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Comentários

Essa função fornece os dados usando a renderização com atraso para que os dados não sejam fornecidos imediatamente. A função de membro OnRenderData ou OnRenderGlobalData é chamada para solicitar os dados.

Use essa função se você não fornecer seus dados por meio de um objeto CFile. Se você for fornecer os dados por meio de um objeto CFile, chame a função de membro DelayRenderFileData. Para obter mais informações sobre renderização com atraso conforme tratado pelo MFC, confira o artigo Objetos de dados e fontes de dados: manipulação.

Para usar a renderização imediata, chame a função de membro CacheData ou CacheGlobalData.

Para obter mais informações, confira a estrutura FORMATETC no SDK do Windows.

Para obter mais informações, confira RegisterClipboardFormat no SDK do Windows.

COleDataSource::DelayRenderFileData

Chame essa função para especificar um formato no qual os dados são oferecidos durante operações de transferência de dados.

void DelayRenderFileData(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

cfFormat
O formato de área de transferência no qual os dados devem ser oferecidos. Esse parâmetro pode ser um dos formatos predefinidos da área de transferência ou o valor retornado pela função nativa RegisterClipboardFormat do Windows.

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato no qual os dados devem ser oferecidos. Forneça um valor para esse parâmetro se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado pelo cfFormat. Se for NULL, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Comentários

Essa função fornece os dados usando a renderização com atraso para que os dados não sejam fornecidos imediatamente. A função de membro OnRenderFileData é chamada para solicitar os dados.

Use essa função se você usar um objeto CFile para fornecer os dados. Se você não usar um objeto CFile, chame a função de membro DelayRenderData. Para obter mais informações sobre renderização com atraso conforme tratado pelo MFC, confira o artigo Objetos de dados e fontes de dados: manipulação.

Para usar a renderização imediata, chame a função de membro CacheData ou CacheGlobalData.

Para obter mais informações, confira a estrutura FORMATETC no SDK do Windows.

Para obter mais informações, confira RegisterClipboardFormat no SDK do Windows.

COleDataSource::DelaySetData

Chame essa função para dar suporte à alteração do conteúdo da fonte de dados.

void DelaySetData(
    CLIPFORMAT cfFormat,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

cfFormat
O formato de área de transferência no qual os dados devem ser colocados. Esse parâmetro pode ser um dos formatos predefinidos da área de transferência ou o valor retornado pela função nativa RegisterClipboardFormat do Windows.

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato no qual os dados devem ser substituídos. Forneça um valor para esse parâmetro se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado pelo cfFormat. Se for NULL, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Comentários

OnSetData será chamado pela estrutura quando isso acontecer. Isso só é usado quando a estrutura retorna a fonte de dados de COleServerItem::GetDataSource. Se DelaySetData não for chamado, sua função OnSetData nunca será chamada. DelaySetData deve ser chamado para cada área de transferência ou formato FORMATETC com suporte.

Para obter mais informações, confira a estrutura FORMATETC no SDK do Windows.

Para obter mais informações, confira RegisterClipboardFormat no SDK do Windows.

COleDataSource::DoDragDrop

Chame a DoDragDrop função membro para executar uma operação de arrastar e soltar para essa fonte de dados, normalmente em um manipulador CWnd::OnLButtonDown .

DROPEFFECT DoDragDrop(
    DWORD dwEffects = DROPEFFECT_COPY|DROPEFFECT_MOVE|DROPEFFECT_LINK,
    LPCRECT lpRectStartDrag = NULL,
    COleDropSource* pDropSource = NULL);

Parâmetros

dwEffects
As operações do tipo "arrastar e soltar" que são permitidas nesta fonte de dados. Pode ser um ou mais dos seguintes:

  • DROPEFFECT_COPY Uma operação de cópia pode ser executada.

  • DROPEFFECT_MOVE Uma operação de movimentação pode ser executada.

  • DROPEFFECT_LINK Um link dos dados descartados para os dados originais pode ser estabelecido.

  • DROPEFFECT_SCROLL Indica que uma operação de rolagem de arrastar pode ocorrer.

lpRectStartDrag
O ponteiro para o retângulo que define onde a ação de arrastar realmente começa. Para obter mais informações, consulte a seção Comentários a seguir.

pDropSource
Aponta para uma fonte suspensa. Se NULL, uma implementação padrão de COleDropSource será usada.

Valor de retorno

Efeito de soltar gerado pela operação do tipo "arrastar e soltar". Caso contrário, DROPEFFECT_NONE se a operação nunca começar porque o usuário soltou o botão do mouse antes de deixar o retângulo.

Comentários

A operação do tipo "arrastar e soltar" não é iniciada imediatamente. Ela aguarda até que o cursor do mouse deixe o retângulo especificado por lpRectStartDrag ou até que um número específico de milissegundos tenha passado. Se lpRectStartDrag for NULL, o tamanho do retângulo será de um pixel.

O tempo de atraso é especificado por uma configuração de chave do Registro. Você pode alterar o tempo de atraso chamando CWinApp::WriteProfileString ou CWinApp::WriteProfileInt. Se você não especificar o tempo de atraso, um valor padrão de 200 milissegundos será usado. O tempo de atraso de arrastar é armazenado da seguinte maneira:

  • O tempo de atraso de arrastar do Windows NT é armazenado em HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\NT\CurrentVersion\IniFileMapping\win.ini\Windows\DragDelay.

  • O tempo de atraso de arrastar do Windows 3.x é armazenado no arquivo WIN.INI, na seção [Windows}.

  • O tempo de atraso de arrastar do Windows 95/98 é armazenado em uma versão armazenada em cache do WIN.INI.

Para obter mais informações sobre como as informações de atraso de arrastar são armazenadas no Registro ou no arquivo .INI, confira WriteProfileString no SDK do Windows.

Para obter mais informações, confira o artigo Ação do tipo "arrastar e soltar" OLE.

COleDataSource::Empty

Chame essa função para esvaziar o objeto COleDataSource de dados.

void Empty();

Comentários

Os formatos de renderização armazenados em cache e com atraso são esvaziados para que possam ser reutilizados.

Para obter mais informações, confira ReleaseStgMedium no SDK do Windows.

COleDataSource::FlushClipboard

Renderiza os dados que estão na área de transferência e, em seguida, permite colar dados da área de transferência depois que seu aplicativo é desligado.

static void PASCAL FlushClipboard();

Comentários

Use SetClipboard para colocar dados na área de transferência.

COleDataSource::GetClipboardOwner

Determina se os dados na área de transferência foram alterados desde que SetClipboard foi chamado pela última vez e, em caso afirmativo, identifica o proprietário atual.

static COleDataSource* PASCAL GetClipboardOwner();

Valor de retorno

Atualmente, a fonte de dados na área de transferência, ou NULL se não houver nada na área de transferência ou se a área de transferência não pertencer ao aplicativo de chamada.

COleDataSource::OnRenderData

Chamado pela estrutura para recuperar dados no formato especificado.

virtual BOOL OnRenderData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium);

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC especificando o formato no qual as informações são solicitadas.

lpStgMedium
Aponta para uma estrutura STGMEDIUM na qual os dados devem ser retornados.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

O formato especificado é um colocado anteriormente no objeto COleDataSource usando a função de membro DelayRenderData ou DelayRenderFileData para renderização com atraso. A implementação padrão dessa função chamará OnRenderFileData ou OnRenderGlobalData se o meio de armazenamento fornecido for um arquivo ou memória, respectivamente. Se nenhum desses formatos for fornecido, a implementação padrão retornará 0 e não fará nada. Para obter mais informações sobre renderização com atraso conforme tratado pelo MFC, confira o artigo Objetos de dados e fontes de dados: manipulação.

Se lpStgMedium->tymed for TYMED_NULL, o STGMEDIUM deverá ser alocado e preenchido conforme especificado por lpFormatEtc->tymed. Se não for TYMED_NULL, o STGMEDIUM deverá ser preenchido localmente com os dados.

Essa é uma substituição avançada. Substitua essa função para fornecer seus dados no formato e no meio solicitados. Dependendo dos dados, talvez você queira substituir uma das outras versões dessa função. Se os dados forem pequenos e fixos em tamanho, substitua OnRenderGlobalData. Se os dados estiverem em um arquivo ou forem de tamanho variável, substitua OnRenderFileData.

Para obter mais informações, consulte as estruturas STGMEDIUM e FORMATETC, o tipo de enumeração TYMED e IDataObject::GetData no SDK do Windows.

COleDataSource::OnRenderFileData

Chamado pela estrutura para recuperar dados no formato especificado quando o meio de armazenamento especificado for um arquivo.

virtual BOOL OnRenderFileData(
    LPFORMATETC lpFormatEtc,
    CFile* pFile);

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC especificando o formato no qual as informações são solicitadas.

pFile
Aponta para um objeto CFile no qual os dados devem ser renderizados.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

O formato especificado é um colocado anteriormente no objeto COleDataSource usando a função de membro DelayRenderData para renderização com atraso. A implementação padrão dessa função simplesmente retorna FALSE.

Essa é uma substituição avançada. Substitua essa função para fornecer seus dados no formato e no meio solicitados. Dependendo dos dados, talvez você queira substituir uma das outras versões dessa função. Se você quiser manipular várias mídias de armazenamento, substitua OnRenderData. Se os dados estiverem em um arquivo ou forem de tamanho variável, substitua OnRenderFileData. Para obter mais informações sobre renderização com atraso conforme tratado pelo MFC, confira o artigo Objetos de dados e fontes de dados: manipulação.

Para obter mais informações, confira a estrutura FORMATETC e IDataObject::GetData no SDK do Windows.

COleDataSource::OnRenderGlobalData

Chamado pela estrutura para recuperar dados no formato especificado quando o meio de armazenamento especificado for uma memória global.

virtual BOOL OnRenderGlobalData(
    LPFORMATETC lpFormatEtc,
    HGLOBAL* phGlobal);

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC especificando o formato no qual as informações são solicitadas.

phGlobal
Aponta para um identificador para a memória global na qual os dados devem ser retornados. Se ainda não tiver sido alocado, esse parâmetro poderá ser NULL.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

O formato especificado é um colocado anteriormente no objeto COleDataSource usando a função de membro DelayRenderData para renderização com atraso. A implementação padrão dessa função simplesmente retorna FALSE.

Se phGlobal for NULL, um novo HGLOBAL deverá ser alocado e retornado em phGlobal. Caso contrário, o HGLOBAL especificado pelo phGlobal deverá ser preenchido com os dados. A quantidade de dados colocados no HGLOBAL não pode exceder o tamanho atual do bloco de memória. Além disso, o bloco não pode ser realocado para um tamanho maior.

Essa é uma substituição avançada. Substitua essa função para fornecer seus dados no formato e no meio solicitados. Dependendo dos dados, talvez você queira substituir uma das outras versões dessa função. Se você quiser manipular várias mídias de armazenamento, substitua OnRenderData. Se os dados estiverem em um arquivo ou forem de tamanho variável, substitua OnRenderFileData. Para obter mais informações sobre renderização com atraso conforme tratado pelo MFC, confira o artigo Objetos de dados e fontes de dados: manipulação.

Para obter mais informações, confira a estrutura FORMATETC e IDataObject::GetData no SDK do Windows.

COleDataSource::OnSetData

Chamado pela estrutura para definir ou substituir os dados no objeto COleDataSource no formato especificado.

virtual BOOL OnSetData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium,
    BOOL bRelease);

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC especificando o formato no qual os dados são substituídos.

lpStgMedium
Aponta para a estrutura STGMEDIUM que contém os dados que substituirão o conteúdo atual do objeto COleDataSource.

bRelease
Indica quem tem a propriedade do meio de armazenamento depois de concluir a chamada de função. O chamador decide quem é responsável por liberar os recursos alocados em nome do meio de armazenamento. O chamador faz isso definindo bRelease. Se bRelease não for zero, a fonte de dados assumirá a propriedade, liberando o meio quando terminar de usá-lo. Quando bRelease for 0, o chamador manterá a propriedade, e a fonte de dados poderá usar o meio de armazenamento somente durante a chamada.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

A fonte de dados não assume a propriedade dos dados até que a tenha obtido com êxito. Ou seja, ela não assumirá a propriedade se OnSetData retornar 0. Se a fonte de dados assumir a propriedade, ela liberará o meio de armazenamento chamando a função ReleaseStgMedium.

A implementação padrão não tem ação. Substitua essa função para substituir os dados no formato especificado. Essa é uma substituição avançada.

Para obter mais informações, consulte as estruturas STGMEDIUM e FORMATETC e as funções ReleaseStgMedium e IDataObject::GetData no SDK do Windows.

COleDataSource::SetClipboard

Coloca os dados contidos no objeto COleDataSource na área de transferência depois de chamar uma das seguintes funções: CacheData, CacheGlobalData, DelayRenderData ou DelayRenderFileData.

void SetClipboard();

Confira também

HIERSVR de exemplo do MFC
OCLIENT de exemplo do MFC
Classe CCmdTarget
Gráfico da hierarquia
Classe COleDataObject