Método IDropTarget::D ragOver (oleidl.h)

Artigo
03/01/2024

Fornece comentários de destino para o usuário e comunica o efeito da queda para a função DoDragDrop para que ela possa comunicar o efeito do dropback para a origem.

Sintaxe

HRESULT DragOver(
  [in]      DWORD  grfKeyState,
  [in]      POINTL pt,
  [in, out] DWORD  *pdwEffect
);

Parâmetros

[in] grfKeyState

O estado atual das teclas modificadoras de teclado no teclado. Os valores válidos podem ser uma combinação de qualquer um dos sinalizadores MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON e MK_RBUTTON.

[in] pt

Uma estrutura POINTL que contém as coordenadas atuais do cursor nas coordenadas da tela.

[in, out] pdwEffect

Na entrada, ponteiro para o valor do parâmetro pdwEffect da função DoDragDrop . No retorno, deve conter um dos sinalizadores DROPEFFECT , que indica qual seria o resultado da operação de remoção.

Retornar valor

Esse método retorna S_OK com êxito. Outros valores possíveis incluem o seguinte.

Código de retorno	Descrição
E_UNEXPECTED	Ocorreu um erro inesperado.
E_INVALIDARG	O valor pdwEffect não é válido.
E_OUTOFMEMORY	Não havia memória suficiente disponível para esta operação.

Comentários

Você não chama o DragOver diretamente. A função DoDragDrop chama esse método sempre que o usuário move o mouse por uma determinada janela de destino. O DoDragDrop sairá do loop se a operação de arrastar e soltar for cancelada, se o usuário arrastar o mouse para fora da janela de destino ou se a queda for concluída.

Ao implementar IDropTarget::D ragOver, você deve fornecer recursos semelhantes aos de IDropTarget::D ragEnter. Você deve determinar o efeito de descartar os dados no destino examinando o FORMATETC definindo os formatos e o meio do objeto de dados, juntamente com o estado das chaves modificadoras. A posição do mouse também pode desempenhar um papel na determinação do efeito de uma queda. As seguintes chaves modificadoras afetam o resultado da queda.

Combinação de teclas	Comentários User-Visible	Efeito Drop
CTRL + SHIFT	=	DROPEFFECT_LINK
CTRL	+	DROPEFFECT_COPY
Sem chaves ou SHIFT	Nenhum	DROPEFFECT_MOVE

Você comunica o efeito do drop-back para a origem por meio de DoDragDrop em pdwEffect. A função DoDragDrop chama IDropSource::GiveFeedback para que o aplicativo de origem possa exibir os comentários visuais apropriados para o usuário.

Na entrada de IDropTarget::D ragOver, o parâmetro pdwEffect deve ser definido como os efeitos permitidos passados para o parâmetro pdwOkEffect da função DoDragDrop . O método IDropTarget::D ragOver deve ser capaz de escolher um desses efeitos ou desabilitar a queda.

Após o retorno, pdwEffect é definido como um dos sinalizadores DROPEFFECT. Esse valor é então passado para o parâmetro pdwEffect de DoDragDrop. Valores razoáveis são DROPEFFECT_COPY copiar os dados arrastados para o destino, DROPEFFECT_LINK criar um link para os dados de origem ou DROPEFFECT_MOVE para permitir que os dados arrastados sejam movidos permanentemente do aplicativo de origem para o destino.

Você também pode desejar fornecer comentários visuais apropriados na janela de destino. Pode haver alguns comentários de destino já exibidos de uma chamada anterior para IDropTarget::D ragOver ou do IDropTarget::D ragEnter inicial. Se esses comentários não forem mais apropriados, você deverá removê-lo.

Por motivos de eficiência, um objeto de dados não é passado em IDropTarget::D ragOver. O objeto de dados passado na chamada mais recente para IDropTarget::D ragEnter está disponível e pode ser usado.

Quando IDropTarget::D ragOver tiver concluído sua operação, a função DoDragDrop chamará IDropSource::GiveFeedback para que o aplicativo de origem possa exibir os comentários visuais apropriados para o usuário.

Anotações aos implementadores

Essa função é chamada com frequência durante o loop DoDragDrop , portanto, faz sentido otimizar a implementação do método DragOver o máximo possível.

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	oleidl.h