Função OleUIPasteSpecialA (oledlg.h)

  • Artigo

Invoca a caixa de diálogo Padrão Colar Especial , permitindo que o usuário selecione o formato do objeto da área de transferência a ser colado ou vinculado à colagem.

Sintaxe

UINT OleUIPasteSpecialA(
  [in] LPOLEUIPASTESPECIALA unnamedParam1
);

Parâmetros

[in] unnamedParam1

Um ponteiro para uma estrutura OLEUIPASTESPECIAL .

Retornar valor

Definições padrão de êxito/erro

Código de retorno Descrição
OLEUI_FALSE
 Falha desconhecida (não utilizado).
OLEUI_OK
 O usuário pressionou o botão OK.
OLEUI_SUCCESS
 Nenhum erro, o mesmo que OLEUI_OK.
OLEUI_CANCEL
 O usuário pressionou o botão Cancelar.
 

Erros de validação de campo padrão

Código de retorno Descrição
OLEUI_ERR_STANDARDMIN
 Erros comuns a todas as caixas de diálogo estão no intervalo OLEUI_ERR_STANDARDMIN a OLEUI_ERR_STANDARDMAX. Esse valor permite que o aplicativo teste mensagens padrão para exibir mensagens de erro para o usuário.
OLEUI_ERR_STRUCTURENULL
 O ponteiro para uma estrutura OLEUIXXX passada para a função era NULL.
OLEUI_ERR_STRUCTUREINVALID
 Permissões insuficientes para acesso de leitura ou gravação a uma estrutura OLEUIXXX.
OLEUI_ERR_CBSTRUCTINCORRECT
 O valor de cbstruct está incorreto.
OLEUI_ERR_HWNDOWNERINVALID
 O valor hWndOwner é inválido.
OLEUI_ERR_LPSZCAPTIONINVALID
 O valor lpszCaption é inválido.
OLEUI_ERR_LPFNHOOKINVALID
 O valor lpfnHook é inválido.
OLEUI_ERR_HINSTANCEINVALID
 O valor hInstance é inválido.
OLEUI_ERR_LPSZTEMPLATEINVALID
 O valor lpszTemplate é inválido.
OLEUI_ERR_HRESOURCEINVALID
 O valor hResource é inválido.
 

Erros de inicialização

Código de retorno Descrição
OLEUI_ERR_FINDTEMPLATEFAILURE
 Não é possível localizar o modelo da caixa de diálogo.
OLEUI_ERR_LOADTEMPLATEFAILURE
 Não é possível carregar o modelo da caixa de diálogo.
OLEUI_ERR_DIALOGFAILURE
 Falha na inicialização da caixa de diálogo.
OLEUI_ERR_LOCALMEMALLOC
 Uma chamada para LocalAlloc ou o alocador IMalloc padrão falhou.
OLEUI_ERR_GLOBALMEMALLOC
 Uma chamada para GlobalAlloc ou o alocador IMalloc padrão falhou.
OLEUI_ERR_LOADSTRING
 Não é possível chamar LoadString para obter recursos localizados da biblioteca.
OLEUI_ERR_OLEMEMALLOC
 Falha em uma chamada para o alocador IMalloc padrão.
 

Erros específicos da função

Código de retorno Descrição
OLEUI_ERR_STANDARDMAX
 Erros comuns a todas as caixas de diálogo estão no intervalo OLEUI_ERR_STANDARDMIN a OLEUI_ERR_STANDARDMAX. Esse valor permite que o aplicativo teste mensagens padrão para exibir mensagens de erro para o usuário.
OLEUI_IOERR_SRCDATAOBJECTINVALID
 O membro lpSrcDataObject de OLEUIPASTESPECIAL é inválido.
OLEUI_IOERR_ARRPASTEENTRIESINVALID
O membro arrPasteEntries de OLEUIPASTESPECIAL é inválido.
OLEUI_IOERR_ARRLINKTYPESINVALID
 O membro arrLinkTypes de OLEUIPASTESPECIAL é inválido.
OLEUI_PSERR_CLIPBOARDCHANGED
 O conteúdo da área de transferência foi alterado enquanto a caixa de diálogo era exibida.
OLEUI_PSERR_GETCLIPBOAARDFAILED

 O membro lpSrcDataObj está incorreto.

Comentários

O design da caixa de diálogo Colar Especial pressupõe que, se você estiver disposto a permitir que um usuário se vincule a um objeto, também estará disposto a permitir que o usuário insira esse objeto. Por esse motivo, se qualquer um dos sinalizadores de OLEUIPASTE_LINKTYPE associados à enumeração OLEUIPASTEFLAG estiver definido, o sinalizador OLEUIPASTE_PASTE também deverá ser definido para que os formatos de dados apareçam na caixa de diálogo Colar Especial .

O texto exibido no campo Origem da caixa de diálogo Especial de Colagem padrão, que é implementada em Oledlg32.dll, é a cadeia de caracteres terminada em nulo cujo deslocamento em bytes é especificado no membro dwSrcofCopy da estrutura OBJECTDESCRIPTOR para o objeto a ser colado. Se uma estrutura OBJECTDESCRIPTOR não estiver disponível para esse objeto, a caixa de diálogo exibirá qualquer texto que possa estar associado a CF_LINKSOURCEDESCRIPTOR. Se nenhuma estrutura estiver disponível, a caixa de diálogo procurará CF_FILENAME. Se CF_FILENAME não for encontrado, a caixa de diálogo exibirá a cadeia de caracteres "Fonte Desconhecida".

Para liberar um HMETAFILEPICT retornado da caixa de diálogo Inserir Objeto ou Colar Especial , exclua o metarquivo anexado no identificador, da seguinte maneira.

void FreeHmetafilepict(HMETAFILEPICT hmfp)
{
    if (hmfp != NULL)
    {
        LPMETAFILEPICT pmfp = GlobalLock(hmfp);
 
        DeleteMetaFile(pmfp->hMF);
        GlobalUnlock(hmfp);
        GlobalFree(hmfp);
    }
    else
    {
        // Handle null pointers here.
        exit(0);
    }
}

Observação

O cabeçalho oledlg.h define OLEUIPASTESPECIAL como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho oledlg.h
Biblioteca OleDlg.lib
DLL OleDlg.dll

Confira também

OLEUIPASTEFLAG