Metodo IAccess::accHitTest (oleacc.h)

Articolo
02/29/2024

Il metodo IAccess::accHitTest recupera l'elemento figlio o l'oggetto figlio visualizzato in un punto specifico sullo schermo. Tutti gli oggetti visivi supportano questo metodo, ma gli oggetti audio non sono. Le applicazioni client chiamano raramente questo metodo direttamente; per ottenere l'oggetto accessibile visualizzato a un punto, usare la funzione AccessibleObjectFromPoint , che chiama internamente questo metodo.

Sintassi

HRESULT accHitTest(
  [in]          long    xLeft,
  [in]          long    yTop,
  [out, retval] VARIANT *pvarChild
);

Parametri

[in] xLeft

Tipo: long

Specifica le coordinate dello schermo del punto raggiunto. Le coordinate x aumentano da sinistra a destra. Si noti che quando vengono usate le coordinate dello schermo, l'origine è l'angolo superiore sinistro dello schermo.

[in] yTop

Tipo: long

Specifica le coordinate dello schermo del punto raggiunto. Le coordinate y aumentano dall'alto verso il basso. Si noti che quando vengono usate le coordinate dello schermo, l'origine è l'angolo superiore sinistro dello schermo.

[out, retval] pvarChild

Tipo: VARIANT*

[out, retval] Indirizzo di un valore VARIANT che identifica l'oggetto visualizzato nel punto specificato da xLeft e yTop. Le informazioni restituite in pvarID dipendono dalla posizione del punto specificato in relazione all'oggetto il cui metodo accHitTest viene chiamato.

Posizione punto	membro vt	Membro valore
Al di fuori dei limiti dell'oggetto e all'interno o all'esterno del rettangolo di selezione dell'oggetto.	VT_EMPTY	Nessuno.
All'interno dell'oggetto ma non all'interno di un elemento figlio o di un oggetto figlio.	VT_I4	lVal è CHILDID_SELF.
All'interno di un elemento figlio.	VT_I4	lVal contiene l'ID figlio.
All'interno di un oggetto figlio.	VT_DISPATCH	pdispVal è impostato sul puntatore dell'interfaccia IDispatch dell'oggetto figlio

Valore restituito

Tipo: HRESULT

Se ha esito positivo, restituisce S_OK.

In caso contrario, restituisce uno dei valori della tabella che segue o un altro codice di errore COM standard. I server restituiscono questi valori, ma i client devono sempre controllare i parametri di output per assicurarsi che contengano valori validi. Per altre informazioni, vedere Controllo dei valori restituiti IAccessibile.

Errore	Descrizione
S_FALSE	Il punto non rientra nei limiti dell'oggetto. Il membro vt di pvarID è VT_EMPTY.
DISP_E_MEMBERNOTFOUND	L'oggetto non supporta questo metodo.
E_INVALIDARG	Un argomento non è valido.

Nota per gli sviluppatori client: Anche se i server restituiscono S_FALSE se il membro vt di pvarID è VT_EMPTY, i client devono gestire anche il caso in cui pvarID-vt> è VT_EMPTY e il valore restituito è S_OK.

Commenti

Se il punto testato si trova in uno degli elementi figlio dell'oggetto e questo figlio supporta l'interfaccia IAccess , questo metodo deve restituire un puntatore dell'interfaccia IAccessibile . Tuttavia, i client devono essere preparati per gestire un puntatore dell'interfaccia IAccessibile o un ID figlio. Per altre informazioni, vedere Come vengono usati gli ID figlio nei parametri.

Poiché accLocation restituisce un rettangolo di delimitazione, non tutti i punti di tale rettangolo saranno inclusi nei limiti effettivi dell'oggetto. Alcuni punti all'interno del rettangolo di delimitazione potrebbero non trovarsi nell'oggetto . Per gli oggetti non rettangolari, ad esempio gli elementi della visualizzazione elenco in modalità icona di grandi dimensioni in cui un singolo elemento ha un rettangolo per l'icona e un altro rettangolo per il testo dell'icona, le coordinate del rettangolo di delimitazione dell'oggetto recuperate da IAccess::accLocation potrebbe non riuscire se testato con accHitTest .

Come per altri metodi e funzioni IAccessi , i client potrebbero ricevere errori per i puntatori di interfaccia IAccessi a causa di un'azione utente. Per altre informazioni, vedere Ricezione di errori per i puntatori dell'interfaccia IAccessibile.

Quando questo metodo viene usato in determinate situazioni, si applicano note aggiuntive sull'utilizzo. Per altre informazioni, vedere Navigazione tramite hit testing e posizione dello schermo.

Esempio di server

Il codice di esempio seguente mostra un'implementazione possibile per una casella di riepilogo personalizzata.


// 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;
    }
};

Esempio client

La funzione di esempio seguente seleziona l'elemento in un punto specificato nella schermata all'interno dell'elenco rappresentato da pAcc. Si presuppone che una singola selezione sia desiderata.


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;
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	oleacc.h
Libreria	Oleacc.lib
DLL	Oleacc.dll
Componente ridistribuibile	Accessibilità attiva 1.3 RDK in Windows NT 4.0 con SP6 e versioni successive e Windows 95