Método IAccessible::accLocation (oleacc.h)

Artigo
08/25/2023

O método IAccessible::accLocation recupera o local da tela atual do objeto especificado. Todos os objetos visuais devem dar suporte a esse método. Objetos de som não dão suporte a esse método.

Sintaxe

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

Parâmetros

[out] pxLeft

Tipo: long*

Endereço, em coordenadas de tela físicas, da variável que recebe a coordenada x do limite superior esquerdo do local do objeto.

[out] pyTop

Tipo: long*

Endereço, em coordenadas de tela físicas, da variável que recebe a coordenada y do limite superior esquerdo do local do objeto.

[out] pcxWidth

Tipo: long*

Endereço, em pixels, da variável que recebe a largura do objeto.

[out] pcyHeight

Tipo: long*

Endereço, em pixels, da variável que recebe a altura do objeto.

[in] varChild

Tipo: VARIANT

Especifica se o local retornado pelo servidor deve ser o do objeto ou o de um dos elementos filho do objeto. Esse parâmetro é CHILDID_SELF (para obter informações sobre o objeto) ou uma ID filho (para obter informações sobre o elemento filho do objeto). Para obter mais informações sobre como inicializar a estrutura VARIANT, consulte Como as IDs filho são usadas em parâmetros.

Valor retornado

Tipo: HRESULT

Se for bem-sucedido, retornará S_OK. Os clientes sempre devem marcar que os parâmetros de saída contenham valores válidos.

Se não for bem-sucedido, retornará um dos valores na tabela a seguir ou outro código de erro COM padrão. Para obter mais informações, consulte Verificando valores retornados do IAccessible.

Erro	Descrição
DISP_E_MEMBERNOTFOUND	O objeto não dá suporte a esse método.
E_INVALIDARG	Um argumento não é válido.

Comentários

Esse método recupera o retângulo delimitador do objeto. Se o objeto tiver uma forma não retangular, esse método retornará o menor retângulo que abrange completamente toda a região do objeto. Para objetos não retangulares, as coordenadas do retângulo delimitador do objeto podem falhar se testadas com IAccessible::accHitTest. Exemplos desses objetos não retangulares são itens de exibição de lista no modo de ícone grande, em que um único item tem um retângulo para o ícone e outro retângulo para o texto do ícone. Como accLocation retorna um retângulo delimitador, nem todos os pontos nesse retângulo estarão dentro dos limites reais do objeto. Alguns pontos dentro do retângulo delimitador podem não estar no objeto . Para obter mais informações, consulte Navegação por meio do teste de clique e local da tela.

Nota: Esse método retorna largura e altura. Se você quiser as coordenadas direita e inferior, calcule-as usando direita = esquerda + largura e inferior = superior + altura.

Exemplo de servidor

O exemplo a seguir mostra uma possível implementação do método para uma caixa de listagem personalizada cujos itens de lista são elementos filho. Para a caixa de listagem em si, a chamada é passada para o objeto acessível padrão, que retorna as coordenadas de tela da janela.


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

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	oleacc.h
Biblioteca	Oleacc.lib
DLL	Oleacc.dll
Redistribuível	Active Accessibility 1.3 RDK no Windows NT 4.0 com SP6 e posterior e Windows 95