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

Artigo
02/29/2024

O método IAccessible::get_accKeyboardShortcut recupera a tecla de atalho ou a chave de acesso do objeto especificado, também conhecida como mnemônica. Todos os objetos que têm uma chave de atalho ou uma chave de acesso dão suporte a essa propriedade.

Sintaxe

HRESULT get_accKeyboardShortcut(
  [in]          VARIANT varChild,
  [out, retval] BSTR    *pszKeyboardShortcut
);

Parâmetros

[in] varChild

Tipo: VARIANT

Especifica se o atalho de teclado recuperado pertence ao objeto ou a 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 VARIANT, consulte Como as IDs filho são usadas em parâmetros.

[out, retval] pszKeyboardShortcut

Tipo: BSTR*

Endereço de um BSTR que recebe uma cadeia de caracteres localizada que identifica o atalho de teclado ou NULL se nenhum atalho de teclado estiver associado ao objeto especificado.

Retornar valor

Tipo: HRESULT

Se for bem-sucedido, retornará S_OK.

Se não for bem-sucedido, retornará um dos valores na tabela a seguir ou outro código de erro COM padrão. Os servidores retornam esses valores, mas os clientes devem sempre marcar parâmetros de saída para garantir que eles contenham valores válidos. Para obter mais informações, consulte Verificando valores retornados IAccessible.

Erro	Descrição
S_FALSE	O objeto não tem um atalho de teclado associado.
E_INVALIDARG	Um argumento não é válido.
DISP_E_MEMBERNOTFOUND	O objeto não dá suporte a essa propriedade.

Comentários

Uma chave de acesso é um caractere sublinhado no texto de um menu, item de menu ou rótulo de um botão ou algum outro controle. Por exemplo, um usuário pode exibir um menu pressionando a tecla ALT enquanto também pressiona a tecla sublinhada indicada, como ALT+F para abrir o menu File. Para usar a chave de acesso de um item de menu, o menu que contém o item deve estar ativo.

Controles como botões da barra de ferramentas e itens de menu geralmente têm uma tecla de atalho associada, também conhecida como acelerador de teclado. Alguns itens de menu podem ter uma chave de acesso e uma tecla de atalho, e alguns podem ter apenas uma. Por exemplo, um item de menu chamado New tem uma chave de acesso N e uma tecla de atalho CTRL+N. O menu não precisa estar ativo para que a tecla de atalho funcione.

Observação aos desenvolvedores cliente:

Se essa propriedade retornar um único caractere, você não poderá pressupor que ela seja uma tecla de acesso ou um atalho de teclado. Com itens de menu padrão, a chave de acesso é retornada por IAccessible::get_accKeyboardShortcut e a tecla de atalho é retornada como parte do nome do item de menu retornado de IAccessible::get_accName. Em geral, as teclas de acesso tendem a ser definidas como ALT + <letra>, e os atalhos de teclado tendem a ser CTRL + <letra>.

Observação para desenvolvedores de servidores: Se o elemento de interface do usuário puder receber o foco do teclado, você deverá expor a tecla de acesso para o elemento. Se o elemento de interface do usuário não puder receber o foco do teclado (como ícones da barra de ferramentas), você deverá exibir a tecla de atalho.

Como as teclas de atalho geralmente são determinadas pelo aplicativo e não pelo próprio controle, os servidores geralmente podem retornar o valor obtido do objeto acessível padrão para a janela.

Exemplo de cliente

A função de exemplo a seguir recupera o atalho de teclado para o objeto acessível especificado ou um de seus filhos e o imprime no console.


HRESULT PrintShortcut(IAccessible* pAcc, long child)
{
    if (pAcc == NULL)
    {
        return E_INVALIDARG;
    }
    BSTR bstrShortcut;
    VARIANT varObj;
    varObj.vt = VT_I4;
    varObj.lVal = child;
    HRESULT hr = pAcc->get_accKeyboardShortcut(varObj, &bstrShortcut);
    if (hr == S_OK)
    {
        printf("Shortcut: %S\n", bstrShortcut);
        SysFreeString(bstrShortcut);
    }
    return hr;
}

Requisitos

Requisito	Valor
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