Méthode IAccessible ::accHitTest (oleacc.h)

Article
08/25/2023

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
S_FALSE	Le point est en dehors des limites de l’objet. Le membre vt de pvarID est VT_EMPTY.
DISP_E_MEMBERNOTFOUND	L’objet ne prend pas en charge cette méthode.
E_INVALIDARG	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