Partager via

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

  • Article

Indique si un point se trouve dans un aspect donné d’un objet.

Syntaxe

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

Paramètres

[in] dwAspect

Aspect de dessin demandé.

[in] pRectBounds

Rectangle englobant d’objet dans les coordonnées clientes de la fenêtre contenante. Ce rectangle est calculé et transmis par le conteneur afin que l’objet puisse interpréter de manière significative l’emplacement d’accès.

[in] ptlLoc

Emplacement d’accès dans les coordonnées client de la fenêtre contenante.

[in] lCloseHint

Distance suggérée en unités HIMETRIC que le conteneur considère comme proches. Cette valeur est un indicateur et les objets peuvent l’interpréter à leur manière. Les objets peuvent également utiliser cet indicateur pour déduire approximativement la résolution de sortie afin de choisir l’étendue de l’implémentation des tests d’accès.

[out] pHitResult

Pointeur vers les informations retournées sur l’accès exprimé en tant que valeurs d’énumération HITRESULT .

Valeur retournée

Cette méthode retourne S_OK en cas de réussite. Les autres valeurs de retour possibles sont les suivantes.

Code de retour Description
E_FAIL
 Cette méthode n’est pas implémentée pour l’aspect demandé. Utilisez DVASPECT_CONTENT à la place.

Remarques

Pour prendre en charge la détection d’accès sur des objets non rectangulaires, le conteneur a besoin d’un moyen fiable de demander à un objet si un emplacement donné se trouve à l’intérieur de l’un de ses aspects de dessin. Cette fonction est fournie par IViewObjectEx ::QueryHitPoint.

Note Étant donné que cette méthode fait partie de l’interface IViewObjectEx , le conteneur peut déterminer si un coup de souris est sur un objet sans avoir à nécessairement lancer le serveur. Si l’accès se trouve à l’intérieur de l’objet, il est probable que l’objet sera activé sur place et le serveur démarré.
 
En règle générale, le conteneur détermine rapidement si un emplacement donné se trouve dans l’étendue rectangulaire d’un objet. Si l’emplacement se trouve dans l’étendue rectangulaire d’un objet, le conteneur appelle IViewObjectEx ::QueryHitPoint pour obtenir la confirmation que l’emplacement se trouve réellement à l’intérieur de l’objet. L’emplacement d’accès est passé dans les coordonnées du client de la fenêtre de conteneur. Étant donné que l’objet peut être inactif quand cette méthode est appelée, le rectangle englobant de l’objet dans le même système de coordonnées est également passé à cette méthode, comme dans IPointerInactive ::OnInactiveSetCursor.

Les valeurs retournées possibles sont les suivantes :

  • À l’extérieur, sur une région transparente
  • Assez proche pour être considéré comme un hit (peut être utilisé par des objets de petite taille ou minces)
  • Frapper
IViewObjectEx ::QueryHitPoint n’est pas concerné par les sous-objets de l’objet pour lequel il est appelé. Il indique simplement si l’accès de la souris se trouvait dans l’objet ou non.

IViewObjectEx ::QueryHitPoint peut être appelé pour tous les aspects de dessin pris en charge par un objet. Elle doit échouer si elle n’est pas prise en charge pour l’aspect de dessin demandé.

Les objets transparents peuvent souhaiter implémenter un mécanisme de détection d’accès complexe dans lequel l’utilisateur peut sélectionner l’objet transparent ou un objet derrière celui-ci, en fonction de l’emplacement exact où le clic se produit à l’intérieur de l’objet. Par exemple, une zone de texte transparente affichant un texte suffisamment volumineux peut permettre à l’utilisateur de sélectionner l’objet derrière, par exemple une bitmap, lorsque l’utilisateur clique entre les caractères. Pour cette raison, les informations retournées par IViewObjectEx ::QueryHitPoint indiquent si l’accès se produit sur une région opaque ou transparente.

Un exemple de détection d’accès non rectangulaire et transparent est un contrôle de cercle transparent avec un objet derrière lui (une ligne dans l’exemple ci-dessous) :

Diagramme d’un cercle avec une ligne diagonale à travers celui-ci, montrant les valeurs de détection d’accès pour les zones à l’intérieur et à l’extérieur du cercle et près de la ligne.

Les valeurs affichées sont pour les tests de succès sur le cercle ; les régions grises ne font pas partie du contrôle, mais sont affichées ici pour indiquer une zone autour de l’image considérée comme proche. Chaque objet implémente sa propre définition de close, mais est assisté par un indicateur fourni par le conteneur afin que la proximité puisse être ajustée à mesure que les images zooment plus ou moins.

Dans l’image ci-dessus, les points marqués Hit, Close et Transparent sont tous des coups de force variable sur le cercle, à l’exception de celui marqué Transparent, (mais pour la ligne, close). Cela illustre l’effet de la force différente des coups. Étant donné que le cercle répond transparent alors que la ligne se ferme et que transparent est plus faible que près, la ligne prend le coup.

Notes aux implémenteurs

Un objet prenant en charge IViewObjectEx est nécessaire pour implémenter cette méthode au moins pour l’aspect DVASPECT_CONTENT . L’objet ne doit pas effectuer d’autre action en réponse à cette méthode que pour retourner les informations ; il ne devrait pas y avoir d’effets secondaires.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête ocidl.h

Voir aussi

HITRESULT

IPointerInactive ::OnInactiveSetCursor

IViewObjectEx