Metodo IAccessible::accLocation (oleacc.h)

Articolo
08/25/2023

Il metodo IAccessible::accLocation recupera la posizione corrente dello schermo dell'oggetto specificato. Tutti gli oggetti visivi devono supportare questo metodo. Gli oggetti audio non supportano questo metodo.

Sintassi

HRESULT accLocation(
  [out] long    *pxLeft,
  [out] long    *pyTop,
  [out] long    *pcxWidth,
  [out] long    *pcyHeight,
  [in]  VARIANT varChild
);

Parametri

[out] pxLeft

Tipo: long*

Indirizzo, nelle coordinate dello schermo fisico, della variabile che riceve la coordinata x del limite superiore sinistro della posizione dell'oggetto.

[out] pyTop

Tipo: long*

Indirizzo, nelle coordinate dello schermo fisico, della variabile che riceve la coordinata y del limite superiore sinistro della posizione dell'oggetto.

[out] pcxWidth

Tipo: long*

Indirizzo, in pixel, della variabile che riceve la larghezza dell'oggetto.

[out] pcyHeight

Tipo: long*

Indirizzo, in pixel, della variabile che riceve l'altezza dell'oggetto.

[in] varChild

Tipo: VARIANT

Specifica se il percorso restituito dal server deve essere quello dell'oggetto o di uno degli elementi figlio dell'oggetto. Questo parametro è CHILDID_SELF (per ottenere informazioni sull'oggetto) o un ID figlio (per ottenere informazioni sull'elemento figlio dell'oggetto). Per altre informazioni sull'inizializzazione della struttura VARIANT, vedere Modalità di utilizzo degli ID figlio nei parametri.

Valore restituito

Tipo: HRESULT

Se ha esito positivo, restituisce S_OK. I client devono sempre verificare che i parametri di output contengano valori validi.

In caso contrario, restituisce uno dei valori della tabella che segue o un altro codice di errore COM standard. Per altre informazioni, vedere Controllo dei valori restituiti IAccessible.

Errore	Descrizione
DISP_E_MEMBERNOTFOUND	L'oggetto non supporta questo metodo.
E_INVALIDARG	Un argomento non è valido.

Commenti

Questo metodo recupera il rettangolo di delimitazione dell'oggetto. Se l'oggetto ha una forma non rettangolare, questo metodo restituisce il rettangolo più piccolo che comprende completamente l'intera area dell'oggetto. Per gli oggetti non rettangolari, le coordinate del rettangolo di delimitazione dell'oggetto potrebbero non riuscire se testate con IAccessible::accHitTest. Esempi di tali oggetti non rettangolari sono 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. Poiché accLocation restituisce un rettangolo di delimitazione, non tutti i punti di tale rettangolo saranno all'interno dei limiti effettivi dell'oggetto. Alcuni punti all'interno del rettangolo di delimitazione potrebbero non trovarsi nell'oggetto . Per altre informazioni, vedere Navigazione tramite hit testing e posizione dello schermo.

Nota: Questo metodo restituisce larghezza e altezza. Se si desiderano le coordinate destra e inferiore, calcolarle usando right = left + width e bottom = top + height.

Esempio di server

Nell'esempio seguente viene illustrata una possibile implementazione del metodo per una casella di riepilogo personalizzata le cui voci di elenco sono elementi figlio. Per la casella di riepilogo stessa, la chiamata viene passata all'oggetto accessibile standard, che restituisce le coordinate dello schermo della finestra.


// m_pStdAccessibleObject is the standard accessible object for the control window. 
// m_pControl is the object that represents the control. Its GetItemRect method  
//   retrieves the screen coordinates of the specified item in a zero-based collection. 
// 
HRESULT STDMETHODCALLTYPE AccServer::accLocation( 
    long *pxLeft,
    long *pyTop,
    long *pcxWidth,
    long *pcyHeight,
    VARIANT varChild)
{
    *pxLeft = 0;
    *pyTop = 0;
    *pcxWidth = 0;
    *pcyHeight = 0;
    if (varChild.vt != VT_I4)
    {
        return E_INVALIDARG;
    }
    if (varChild.lVal == CHILDID_SELF)
    {
        return m_pStdAccessibleObject->accLocation(pxLeft, pyTop, pcxWidth, pcyHeight, varChild);
    }
    else
    {
        RECT rect;
        if (m_pControl->GetItemRect(varChild.lVal - 1, &rect) == FALSE)
        {
            return E_INVALIDARG;
        }
        else
        {
            *pxLeft = rect.left;
            *pyTop = rect.top;
            *pcxWidth = rect.right - rect.left;
            *pcyHeight = rect.bottom - rect.top;
            return S_OK;        
        }
    }
};

Requisiti


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