Método IViewObjectEx::QueryHitPoint (ocidl.h)

Indica se um ponto está dentro de um determinado aspecto de um objeto.

Sintaxe

HRESULT QueryHitPoint(
  [in]  DWORD   dwAspect,
  [in]  LPCRECT pRectBounds,
  [in]  POINT   ptlLoc,
  [in]  LONG    lCloseHint,
  [out] DWORD   *pHitResult
);

Parâmetros

[in] dwAspect

O aspecto de desenho solicitado.

[in] pRectBounds

Um retângulo delimitador de objeto nas coordenadas do cliente da janela que contém. Esse retângulo é calculado e passado pelo contêiner para que o objeto possa interpretar significativamente o local de ocorrência.

[in] ptlLoc

O local de ocorrência nas coordenadas do cliente da janela que contém.

[in] lCloseHint

Distância sugerida em unidades HIMETRIC que o contêiner considera fechar. Esse valor é uma dica e os objetos podem interpretá-lo de maneira própria. Os objetos também podem usar essa dica para inferir aproximadamente a resolução de saída para escolher a expansão da implementação do teste de ocorrência.

[out] pHitResult

Um ponteiro para retornar informações sobre o hit expresso como valores de enumeração HITRESULT .

Retornar valor

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

Código de retorno	Descrição
E_FAIL	Esse método não é implementado para o aspecto solicitado. Em vez disso , use DVASPECT_CONTENT .

Comentários

Para dar suporte à detecção de ocorrências em objetos não retangulares, o contêiner precisa de uma maneira confiável de perguntar a um objeto se um determinado local está dentro de um de seus aspectos de desenho. Essa função é fornecida por IViewObjectEx::QueryHitPoint.

Nota Como esse método faz parte da interface IViewObjectEx , o contêiner pode descobrir se um clique do mouse está sobre um objeto sem precisar necessariamente iniciar o servidor. Se o hit estiver dentro do objeto , é provável que o objeto seja ativado in-loco e o servidor seja iniciado.

 

Normalmente, o contêiner primeiro determina rapidamente se um determinado local está dentro da extensão retangular de um objeto. Se o local estiver dentro da extensão retangular de um objeto, o contêiner chamará IViewObjectEx::QueryHitPoint para obter a confirmação de que o local está realmente dentro do objeto . O local de ocorrência é passado nas coordenadas do cliente da janela do contêiner. Como o objeto pode estar inativo quando esse método é chamado, o retângulo delimitador do objeto no mesmo sistema de coordenadas também é passado para esse método, da mesma forma que acontece em IPointerInactive::OnInactiveSetCursor.

Os valores possíveis retornados incluem:

• Do lado de fora, em uma região transparente
• Perto o suficiente para ser considerado um hit (pode ser usado por objetos pequenos ou finos)
• Atingido

IViewObjectEx::QueryHitPoint não está preocupado com os sub-objetos do objeto para o qual ele é chamado. Ele apenas indica se a ocorrência do mouse estava dentro do objeto ou não.

IViewObjectEx::QueryHitPoint pode ser chamado para qualquer um dos aspectos de desenho que um objeto dá suporte. Ele deverá falhar se não houver suporte para o aspecto de desenho solicitado.

Objetos transparentes podem querer implementar um mecanismo complexo de detecção de ocorrências em que o usuário possa selecionar o objeto transparente ou um objeto por trás dele, dependendo de onde exatamente o clique acontece dentro do objeto. Por exemplo, uma caixa de texto transparente mostrando texto grande o suficiente pode permitir que o usuário selecione o objeto atrás, por exemplo, um bitmap, quando o usuário clica entre os caracteres. Por esse motivo, as informações retornadas por IViewObjectEx::QueryHitPoint incluem indicação sobre se o hit ocorre em uma região opaca ou transparente.

Um exemplo de detecção de ocorrência não retangular e transparente é um controle de círculo transparente com um objeto atrás dele (uma linha no exemplo abaixo):

Os valores mostrados são para testes de clique no círculo; as regiões cinzas não fazem parte do controle, mas são mostradas aqui para indicar uma área ao redor da imagem considerada próxima. Cada objeto implementa sua própria definição de close, mas é assistido por uma dica fornecida pelo contêiner para que a proximidade possa ser ajustada à medida que as imagens aumentam ou são menores.

Na imagem acima, os pontos marcados como Hit, Close e Transparent seriam ocorrências de força variável no círculo, com exceção do marcado como Transparente, (mas para a linha, feche). Isso ilustra o efeito da força diferente dos hits. Como o círculo responde transparente enquanto as declarações de linha se fecham, e transparente é mais fraca do que perto, a linha leva o golpe.

Anotações aos implementadores

Um objeto que dá suporte a IViewObjectEx é necessário para implementar esse método pelo menos para o aspecto DVASPECT_CONTENT . O objeto não deve tomar nenhuma outra ação em resposta a esse método além de retornar as informações; não deve haver efeitos colaterais.

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

Confira também

HITRESULT

IPointerInactive::OnInactiveSetCursor

Iviewobjectex