Classe COleDataSource

Funciona como uma cache onde uma aplicação coloca os dados que irá oferecer durante operações de transferência de dados, como operações de Transferência ou arrastar e largar.

Sintaxe

class COleDataSource : public CCmdTarget

Membros

Construtores Públicos

Métodos Públicos

Observações

Podes criar fontes de dados OLE diretamente. Alternativamente, as classes COleClientItem e COleServerItem criam fontes de dados OLE em resposta às suas CopyToClipboard funções e DoDragDrop funções membros. Consulte COleServerItem::CopyToClipboard para uma breve descrição. Substitua a OnGetClipboardData função membro do seu item cliente ou classe de item servidor para adicionar formatos adicionais de Clipboard aos dados na fonte de dados OLE criada para a CopyToClipboard função membro.DoDragDrop

Sempre que quiser preparar dados para uma transferência, deve criar um objeto desta classe e preenchê-lo com os seus dados usando o método mais adequado para os seus dados. A forma como é inserido numa fonte de dados é diretamente afetada por se os dados são fornecidos imediatamente (renderização imediata) ou a pedido (renderização atrasada). Para cada formato Clipboard em que está a fornecer dados passando o formato Clipboard a ser usado (e uma estrutura opcional FORMATETC ), chame DelayRenderData.

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

Hierarquia de herança

CObject

CCmdTarget

COleDataSource

Requerimentos

Cabeçalho: afxole.h

COleDataSource::CacheData

Chame esta função para especificar um formato em que os dados são oferecidos durante as operações de transferência de dados.

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

Parâmetros

cfFormat
O formato Clipboard em que os dados serão oferecidos. Este parâmetro pode ser um dos formatos pré-definidos do Clipboard ou o valor devolvido pela função nativa Windows RegisterClipboardFormat .

lpStgMedium
Aponta para uma estrutura STGMEDIUM contendo os dados no formato especificado.

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato em que os dados serão oferecidos. Forneça um valor para este parâmetro se quiser especificar informação adicional de formato para além do formato Clipboard especificado pelo cfFormat. Se for NULL, os valores padrão são usados para os outros campos da FORMATETC estrutura.

Observações

Tens de fornecer os dados, porque esta função os fornece usando renderização imediata. Os dados são armazenados em cache até serem necessários.

Forneça os dados usando uma estrutura STGMEDIUM . Também pode usar a CacheGlobalData função membro se a quantidade de dados que está a fornecer for suficientemente pequena para ser transferida eficientemente através de um HGLOBAL.

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

Para usar a renderização atrasada, chame a função membro DelayRenderData ou DelayRenderFileData . Para mais informações sobre a renderização atrasada tal como tratada pela MFC, consulte o artigo Objetos de Dados e Fontes de Dados: Manipulação.

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

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

COleDataSource::CacheGlobalData

Chame esta função para especificar um formato em que os dados são oferecidos durante as operações de transferência de dados.

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

Parâmetros

cfFormat
O formato Clipboard em que os dados serão oferecidos. Este parâmetro pode ser um dos formatos pré-definidos do Clipboard ou o valor devolvido pela função nativa Windows RegisterClipboardFormat .

hGlobal
Handle 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 em que os dados serão oferecidos. Forneça um valor para este parâmetro se quiser especificar informação adicional de formato para além do formato Clipboard especificado pelo cfFormat. Se for NULL, os valores padrão são usados para os outros campos da FORMATETC estrutura.

Observações

Esta função fornece os dados usando renderização imediata, pelo que deve fornecer os dados ao chamar a função; Os dados são armazenados em cache até serem necessários. Use a CacheData função membro se estiver a fornecer uma grande quantidade de dados ou se precisar de um meio de armazenamento estruturado.

Para usar a renderização atrasada, chame a função membro DelayRenderData ou DelayRenderFileData . Para mais informações sobre a renderização atrasada tal como tratada pela MFC, consulte o artigo Objetos de Dados e Fontes de Dados: Manipulação.

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

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

COleDataSource::COleDataSource

Constrói um COleDataSource objeto.

COleDataSource();

COleDataSource::D elayRenderData

Chame esta função para especificar um formato em que os dados são oferecidos durante as operações de transferência de dados.

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

Parâmetros

cfFormat
O formato Clipboard em que os dados serão oferecidos. Este parâmetro pode ser um dos formatos pré-definidos do Clipboard ou o valor devolvido pela função nativa Windows RegisterClipboardFormat .

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato em que os dados serão oferecidos. Forneça um valor para este parâmetro se quiser especificar informação adicional de formato para além do formato Clipboard especificado pelo cfFormat. Se for NULL, os valores padrão são usados para os outros campos da FORMATETC estrutura.

Observações

Esta função fornece os dados através de renderização atrasada, pelo que os dados não são fornecidos imediatamente. A função membro OnRenderData ou OnRenderGlobalData é chamada para solicitar os dados.

Use esta função se não for fornecer os seus dados através de um CFile objeto. Se for fornecer os dados através de um CFile objeto, chame a função membro DelayRenderFileData . Para mais informações sobre a renderização atrasada tal como tratada pela MFC, consulte o artigo Objetos de Dados e Fontes de Dados: Manipulação.

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

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

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

COleDataSource::D elayRenderFileData

Chame esta função para especificar um formato em que os dados são oferecidos durante as operações de transferência de dados.

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

Parâmetros

cfFormat
O formato Clipboard em que os dados serão oferecidos. Este parâmetro pode ser um dos formatos pré-definidos do Clipboard ou o valor devolvido pela função nativa Windows RegisterClipboardFormat .

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato em que os dados serão oferecidos. Forneça um valor para este parâmetro se quiser especificar informação adicional de formato para além do formato Clipboard especificado pelo cfFormat. Se for NULL, os valores padrão são usados para os outros campos da FORMATETC estrutura.

Observações

Esta função fornece os dados através de renderização atrasada, pelo que os dados não são fornecidos imediatamente. A função membro OnRenderFileData é chamada para solicitar os dados.

Use esta função se for usar um CFile objeto para fornecer os dados. Se não for usar um CFile objeto, chame a função membro DelayRenderData . Para mais informações sobre a renderização atrasada tal como tratada pela MFC, consulte o artigo Objetos de Dados e Fontes de Dados: Manipulação.

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

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

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

COleDataSource::D elaySetData

Chame esta função para suportar a alteração do conteúdo da fonte de dados.

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

Parâmetros

cfFormat
O formato Clipboard em que os dados devem ser colocados. Este parâmetro pode ser um dos formatos pré-definidos do Clipboard ou o valor devolvido pela função nativa Windows RegisterClipboardFormat .

lpFormatEtc
Aponta para uma estrutura FORMATETC que descreve o formato em que os dados devem ser substituídos. Forneça um valor para este parâmetro se quiser especificar informação adicional de formato para além do formato Clipboard especificado pelo cfFormat. Se for NULL, os valores padrão são usados para os outros campos da FORMATETC estrutura.

Observações

O OnSetData será chamado pelo framework quando isso acontecer. Isto só é usado quando o framework devolve a fonte de dados de COleServerItem::GetDataSource. Se DelaySetData não for chamada, a sua OnSetData função nunca será chamada. DelaySetData deve ser chamado para cada Clipboard ou FORMATETC formato que suporta.

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

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

COleDataSource::D oDragDrop

Chame a DoDragDrop função membro para realizar uma operação de arrastar e largar para esta fonte de dados, normalmente num tratador CWnd::OnLButtonDown .

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

Parâmetros

dwEffects
Operações de arrastar e largar que são permitidas nesta fonte de dados. Pode ser um ou mais dos seguintes:

• DROPEFFECT_COPY Podia ser realizada uma operação de cópia.

• DROPEFFECT_MOVE Podia ser realizada uma operação de movimento.

• DROPEFFECT_LINK Podia ser estabelecida uma ligação dos dados caídos aos dados originais.

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

lpRectStartDrag
Apontador para o retângulo que define onde o arrasto realmente começa. Para mais informações, consulte a seguinte secção de Observações.

pDropSource
Aponta para uma fonte de queda. Se for NULL, então será utilizada uma implementação padrão do COleDropSource .

Valor de retorno

Efeito de largada gerado pela operação de arrastar e largar; caso contrário, DROPEFFECT_NONE se a operação nunca começar porque o utilizador largou o botão do rato antes de sair do retângulo fornecido.

Observações

A operação de arrastar e largar não começa imediatamente. Espera até que o cursor do rato saia do retângulo especificado por lpRectStartDrag ou até que tenha passado um número especificado de milissegundos. Se lpRectStartDrag for NULL, o tamanho do retângulo é de um pixel.

O tempo de atraso é especificado por uma definição de chave de registo. Pode alterar o tempo de atraso chamando CWinApp::WriteProfileString ou CWinApp::WriteProfileInt. Se não especificar o tempo de atraso, é usado um valor padrão de 200 milissegundos. O tempo de atraso do arrasto é armazenado da seguinte forma:

• O tempo de atraso 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 WIN. INI, na secção [Windows].

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

Para mais informações sobre como a informação de atraso de arrasto é armazenada no registo ou no . INI, veja WriteProfileString no SDK do Windows.

Para mais informações, consulte o artigo OLE arrastar e largar.

COleDataSource::Vazio

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

void Empty();

Observações

Tanto os formatos de renderização em cache como os de atraso são esvaziados para poderem ser reutilizados.

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

COleDataSource::FlushClipboard

Renderiza os dados que estão na Área de Transferência e depois permite-te colar dados da Área de Transferência depois de a tua aplicação desligar.

static void PASCAL FlushClipboard();

Observações

Use o SetClipboard para colocar os dados na Clipboard.

COleDataSource::GetClipboardOwner

Determina se os dados na Área de Transferência mudaram desde a última chamada da Área de Transferência e, em caso afirmativo, identifica o proprietário atual.

static COleDataSource* PASCAL GetClipboardOwner();

Valor de retorno

A fonte de dados atualmente 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 for propriedade da aplicação que chama.

COleDataSource::OnRenderData

Chamado pelo framework para recuperar dados no formato especificado.

virtual BOOL OnRenderData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium);

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC que especifica o formato em que a informação é solicitada.

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

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

O formato especificado é aquele previamente colocado no COleDataSource objeto usando a função membro DelayRenderData ou DelayRenderFileData para renderização atrasada. A implementação padrão desta função chamará OnRenderFileData ou OnRenderGlobalData se o meio de armazenamento fornecido for um ficheiro ou memória, respetivamente. Se nenhum destes formatos for fornecido, então a implementação padrão devolverá 0 e nada fará nada. Para mais informações sobre a renderização atrasada tal como tratada pela MFC, consulte o artigo Objetos de Dados e Fontes de Dados: Manipulação.

Se o lpStgMedium-tymed> for TYMED_NULL, oSTGMEDIUM deve ser alocado e preenchido conforme especificado por lpFormatEtc-tymed>. Se não for TYMED_NULL, deve STGMEDIUM ser preenchido no local com os dados.

Isto é um ultrapassível avançado. Sobreescreva esta função para fornecer os seus dados no formato e suporte solicitados. Dependendo dos seus dados, pode querer sobrepor uma das outras versões desta função. Se os teus dados forem pequenos e fixos em tamanho, substitui OnRenderGlobalData. Se os seus dados estiverem num ficheiro, ou forem de tamanho variável, substitua OnRenderFileData.

Para 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 pelo framework para recuperar dados no formato especificado quando o meio de armazenamento especificado é um ficheiro.

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

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC que especifica o formato em que a informação é solicitada.

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

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

O formato especificado é aquele previamente colocado no COleDataSource objeto usando a função membro DelayRenderData para renderização atrasada. A implementação padrão desta função simplesmente devolve FALSE.

Isto é um ultrapassível avançado. Sobreescreva esta função para fornecer os seus dados no formato e suporte solicitados. Dependendo dos teus dados, podes querer sobrepor uma das outras versões desta função. Se quiseres gerir múltiplos suportes de armazenamento, sobrepõe o OnRenderData. Se os seus dados estiverem num ficheiro, ou forem de tamanho variável, substitua OnRenderFileData. Para mais informações sobre a renderização atrasada tal como tratada pela MFC, consulte o artigo Objetos de Dados e Fontes de Dados: Manipulação.

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

COleDataSource::OnRenderGlobalData

Chamado pelo framework para recuperar dados no formato especificado quando o meio de armazenamento especificado é memória global.

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

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC que especifica o formato em que a informação é solicitada.

phGlobal
Aponta para um handle para a memória global onde os dados devem ser devolvidos. Se ainda não tiver sido atribuído, este parâmetro pode ser NULL.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

O formato especificado é aquele previamente colocado no COleDataSource objeto usando a função membro DelayRenderData para renderização atrasada. A implementação padrão desta função simplesmente devolve FALSE.

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

Isto é um ultrapassível avançado. Sobreescreva esta função para fornecer os seus dados no formato e suporte solicitados. Dependendo dos seus dados, pode querer sobrepor uma das outras versões desta função. Se quiseres gerir múltiplos suportes de armazenamento, sobrepõe o OnRenderData. Se os seus dados estiverem num ficheiro, ou forem de tamanho variável, substitua o OnRenderFileData. Para mais informações sobre a renderização atrasada tal como tratada pela MFC, consulte o artigo Objetos de Dados e Fontes de Dados: Manipulação.

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

COleDataSource::OnSetData

Chamado pelo framework para definir ou substituir os dados no COleDataSource objeto no formato especificado.

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

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC que especifica o formato em que os dados estão a ser substituídos.

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

bLançamento
Indica quem detém a propriedade do meio de armazenamento após completar a chamada de função. O chamador decide quem é responsável por libertar os recursos alocados em nome do meio de armazenamento. O chamador faz isto definindo bRelease. Se o bRelease for diferente de zero, a fonte de dados assume a propriedade, libertando o meio quando este termina de o usar. Quando o bRelease é 0, o chamador mantém a propriedade e a fonte de dados pode usar o meio de armazenamento apenas durante a duração da chamada.

Valor de retorno

Não nulo se for bem-sucedido; caso contrário, 0.

Observações

A fonte de dados não assume a posse dos dados até os ter obtido com sucesso. Ou seja, não assume a propriedade se OnSetData devolver 0. Se a fonte de dados assumir a responsabilidade, liberta o meio de armazenamento ao chamar a função ReleaseStgMedium .

A implementação padrão não faz nada. Substitua esta função para substituir os dados no formato especificado. Isto é um ultrapassível avançado.

Para 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 COleDataSource objeto na Área de Transferência após chamar uma das seguintes funções: CacheData, CacheGlobalData, DelayRenderData ou DelayRenderFileData.

void SetClipboard();

Consulte também

Exemplo MFC HIERSVR
Exemplo MFC OCLIENT
Classe CCmdTarget
Gráfico de Hierarquia
Classe COleDataObject