Méthode IAccessible ::accHitTest (oleacc.h)
La méthode IAccessible ::accHitTest récupère l’élément enfant ou l’objet enfant affiché à un point spécifique de l’écran. Tous les objets visuels prennent en charge cette méthode, mais pas les objets sonores. Les applications clientes appellent rarement cette méthode directement ; pour obtenir l’objet accessible affiché à un point, utilisez la fonction AccessibleObjectFromPoint , qui appelle cette méthode en interne.
Syntaxe
HRESULT accHitTest(
[in] long xLeft,
[in] long yTop,
[out, retval] VARIANT *pvarChild
);
Paramètres
[in] xLeft
Type : long
Spécifie les coordonnées d’écran du point testé. Les coordonnées x augmentent de gauche à droite. Notez que lorsque des coordonnées d’écran sont utilisées, l’origine est le coin supérieur gauche de l’écran.
[in] yTop
Type : long
Spécifie les coordonnées d’écran du point testé. Les coordonnées y augmentent de haut en bas. Notez que lorsque des coordonnées d’écran sont utilisées, l’origine est le coin supérieur gauche de l’écran.
[out, retval] pvarChild
Type : VARIANT*
[out, retval] Adresse d’un VARIANT qui identifie l’objet affiché au point spécifié par xLeft et yTop. Les informations retournées dans pvarID dépendent de l’emplacement du point spécifié par rapport à l’objet dont la méthode accHitTest est appelée.
| Emplacement du point | membre vt | Membre value |
|---|---|---|
| En dehors des limites de l’objet, et à l’intérieur ou à l’extérieur du rectangle englobant de l’objet. | VT_EMPTY | Aucun. |
| Dans l’objet, mais pas dans un élément enfant ou un objet enfant. | VT_I4 | lVal est CHILDID_SELF. |
| Dans un élément enfant. | VT_I4 | lVal contient l’ID enfant. |
| Dans un objet enfant. | VT_DISPATCH | pdispVal est défini sur le pointeur d’interface IDispatch de l’objet enfant |
Valeur retournée
Type : HRESULT
En cas de réussite, retourne S_OK.
En cas d’erreur, retourne l’une des valeurs de la table qui suit ou un autre code d’erreur COM standard. Les serveurs retournent ces valeurs, mais les clients doivent toujours case activée paramètres de sortie pour s’assurer qu’ils contiennent des valeurs valides. Pour plus d’informations, consultez Vérification des valeurs de retour IAccessible.
| Erreur | Description |
|---|---|
|
Le point est en dehors des limites de l’objet. Le membre vt de pvarID est VT_EMPTY. |
|
L’objet ne prend pas en charge cette méthode. |
|
Un argument n’est pas valide. |
Remarque pour les développeurs clients : Bien que les serveurs retournent S_FALSE si le membre vt de pvarID est VT_EMPTY, les clients doivent également gérer le cas où pvarID-vt> est VT_EMPTY et la valeur de retour est S_OK.
Remarques
Si le point testé se trouve sur l’un des enfants de l’objet et que cet enfant prend en charge l’interface IAccessible elle-même, cette méthode doit retourner un pointeur d’interface IAccessible . Toutefois, les clients doivent être prêts à gérer un pointeur d’interface IAccessible ou un ID enfant. Pour plus d’informations, consultez Utilisation des ID enfants dans les paramètres.
Étant donné que accLocation retourne un rectangle englobant, tous les points de ce rectangle ne se trouvent pas dans les limites réelles de l’objet. Certains points du rectangle englobant peuvent ne pas se trouver sur l’objet . Pour les objets non rectangulaires, tels que les éléments d’affichage de liste en mode icône volumineuse où un seul élément a un rectangle pour l’icône et un autre rectangle pour le texte de l’icône, les coordonnées du rectangle englobant de l’objet récupérées par IAccessible ::accLocation peuvent échouer si elles sont testées avec accHitTest .
Comme avec d’autres méthodes et fonctions IAccessible , les clients peuvent recevoir des erreurs pour les pointeurs d’interface IAccessible en raison d’une action de l’utilisateur. Pour plus d’informations, consultez Réception d’erreurs pour les pointeurs d’interface IAccessible.
Lorsque cette méthode est utilisée dans certaines situations, des notes d’utilisation supplémentaires s’appliquent. Pour plus d’informations, consultez Navigation Through Hit Testing et Emplacement de l’écran.
Exemple de serveur
L’exemple de code suivant montre une implémentation possible pour une zone de liste personnalisée.
// m_pControl is the control that returns this accessible object.
// m_hwnd is the HWND of the control window.
//
HRESULT STDMETHODCALLTYPE AccServer::accHitTest(
long xLeft,
long yTop,
VARIANT *pvarChild)
{
POINT pt;
pt.x = xLeft;
pt.y = yTop;
// Not in our window.
if (WindowFromPoint(pt) != m_hwnd)
{
pvarChild->vt = VT_EMPTY;
return S_FALSE;
}
else // In our window; return list item, or self if in blank space.
{
pvarChild->vt = VT_I4;
ScreenToClient(m_hwnd, &pt);
// IndexFromY returns the 0-based index of the item at that point,
// or -1 if the point is not on any item.
int index = m_pControl->IndexFromY(pt.y);
if (index >= 0)
{
// Increment, because the child array is 1-based.
pvarChild->lVal = index + 1;
}
else
{
pvarChild->lVal = CHILDID_SELF;
}
return S_OK;
}
};
Exemple de client
L’exemple de fonction suivant sélectionne l’élément à un point spécifié à l’écran dans la liste représentée par pAcc. Il est supposé qu’une seule sélection est souhaitée.
HRESULT SelectItemAtPoint(IAccessible* pAcc, POINT point)
{
if (pAcc == NULL)
{
return E_INVALIDARG;
}
VARIANT varChild;
HRESULT hr = pAcc->accHitTest(point.x, point.y, &varChild);
if ((hr == S_OK) && (varChild.lVal != CHILDID_SELF))
{
return pAcc->accSelect((SELFLAG_TAKEFOCUS | SELFLAG_TAKESELECTION), varChild);
}
return S_FALSE;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | oleacc.h |
| Bibliothèque | Oleacc.lib |
| DLL | Oleacc.dll |
| Composant redistribuable | Active Accessibility 1.3 RDK sur Windows NT 4.0 avec SP6 et versions ultérieures et Windows 95 |
Voir aussi
Accessibilité active et mise à l’échelle de l’écran Windows Vista