Recurso de menu

Um recurso de menu define um menu de aplicativo (também conhecido como menu "opções", menu de contexto ou submenu) que pode ser inflado com MenuInflater.

Confira como usar menus em Adicionar menus.

localização do arquivo:
res/menu/filename.xml
O nome do arquivo é usado como ID de recurso.
tipo de dados do recurso compilado:
Ponteiro de recurso para um recurso Menu (ou subclasse).
referência de recurso:
Em Java: R.menu.filename
Em XML: @[package:]menu.filename
sintaxe:
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:id="@[+][package:]id/resource_name"
          android:title="string"
          android:titleCondensed="string"
          android:icon="@[package:]drawable/drawable_resource_name"
          android:onClick="method name"
          android:showAsAction=["ifRoom" | "never" | "withText" | "always" | "collapseActionView"]
          android:actionLayout="@[package:]layout/layout_resource_name"
          android:actionViewClass="class name"
          android:actionProviderClass="class name"
          android:alphabeticShortcut="string"
          android:alphabeticModifiers=["META" | "CTRL" | "ALT" | "SHIFT" | "SYM" | "FUNCTION"]
          android:numericShortcut="string"
          android:numericModifiers=["META" | "CTRL" | "ALT" | "SHIFT" | "SYM" | "FUNCTION"]
          android:checkable=["true" | "false"]
          android:visible=["true" | "false"]
          android:enabled=["true" | "false"]
          android:menuCategory=["container" | "system" | "secondary" | "alternative"]
          android:orderInCategory="integer" />
    <group android:id="@[+][package:]id/resource name"
           android:checkableBehavior=["none" | "all" | "single"]
           android:visible=["true" | "false"]
           android:enabled=["true" | "false"]
           android:menuCategory=["container" | "system" | "secondary" | "alternative"]
           android:orderInCategory="integer" >
        <item />
    </group>
    <item >
        <menu>
          <item />
        </menu>
    </item>
</menu>
elementos:
Obrigatório. Precisa ser o nó raiz. Contém elementos <item> e/ou <group>.

Atributos:

xmlns:android
Namespace XML. Obrigatório. Define o namespace XML, que precisa ser "http://schemas.android.com/apk/res/android".
<item>
Um item de menu. Pode conter um elemento <menu> (para um submenu). Precisa ser filho de um elemento <menu> ou <group>.

Atributos:

android:id
ID de recurso. Um ID de recurso exclusivo. Para criar um novo ID de recurso para este item, use o formulário: "@+id/name". O símbolo de adição indica que ele foi criado como um novo ID.
android:title
Recurso de string. O título do menu como um recurso de string ou uma string bruta.
android:titleCondensed
Recurso de string. Um título condensado como um recurso de string ou uma string bruta. Esse título é usado em situações em que o título normal é longo demais.
android:icon
Recurso drawable. Uma imagem usada como ícone do item de menu.
android:onClick
Nome do método. O método que vai ser chamado quando esse item de menu for clicado. O método precisa ser declarado na atividade como público. Ele aceita um MenuItem como único parâmetro, o que indica que o item foi clicado. Esse método tem precedência em relação ao callback para onOptionsItemSelected(). Confira o exemplo no final desta página.

Aviso: se você ofuscar seu código usando o ProGuard ou uma ferramenta semelhante, não esqueça de fazer com que o método especificado nesse atributo não seja renomeado, porque isso pode corromper a funcionalidade do código.

Introduzido no nível 11 da API.

android:showAsAction
Palavra-chave. Quando e como esse item aparece como um item de ação na barra de apps. Um item de menu pode ser mostrado como um item de ação somente quando a atividade inclui uma barra de apps. Valores válidos:
ValorDescrição
ifRoomSó coloque este item na barra de apps se houver espaço para ele. Se não houver espaço para todos os itens marcados como "ifRoom", os itens com os menores valores orderInCategory serão mostrados como ações, e os demais no menu flutuante.
withTextInclua também o texto do título (definido por android:title) com o item de ação. Você pode incluir esse valor com um dos outros valores como um conjunto de sinalizações, separando-os com uma barra vertical |.
neverNunca coloque este item na barra de apps. Em vez disso, liste o item na barra de apps do menu flutuante.
alwaysSempre coloque este item na barra de apps. Evite usar o item, a não ser que seja essencial que ele sempre apareça na barra de ações. Definir vários itens para que sejam sempre mostrados como itens de ação pode fazer com que eles apareçam por cima de outros elementos da interface na barra de apps.
collapseActionViewA visualização de ações associadas a esse item de ação, conforme declarado por android:actionLayout ou android:actionViewClass, pode ser fechada.
Introduzido no nível 14 da API.

Consulte Adicionar a barra de apps para mais informações.

Introduzido no nível 11 da API.

android:actionLayout
Recurso de layout. Um layout para ser usado como visualização de ação.

Para mais informações, consulte Usar visualizações e provedores de ação.

Introduzido no nível 11 da API.

android:actionViewClass
Nome de classe. Um nome de classe totalmente qualificado para View usar como visualização de ação. Por exemplo, "android.widget.SearchView" para usar SearchView como uma visualização de ação.

Para mais informações, consulte Usar visualizações e provedores de ação.

Aviso: se você ofuscar seu código usando o ProGuard ou uma ferramenta semelhante, não esqueça de fazer com que a classe especificada nesse atributo não seja renomeada, porque isso pode corromper a funcionalidade do código.

Introduzido no nível 11 da API.

android:actionProviderClass
Nome de classe. Um nome de classe totalmente qualificado para o ActionProvider usar no lugar do item de ação. Por exemplo, "android.widget.ShareActionProvider" para usar ShareActionProvider.

Para mais informações, consulte Usar visualizações e provedores de ação.

Aviso: se você ofuscar seu código usando o ProGuard ou uma ferramenta semelhante, não esqueça de fazer com que a classe especificada nesse atributo não seja renomeada, porque isso pode corromper a funcionalidade do código.

Introduzido no nível 14 da API.

android:alphabeticShortcut
Char. Um caractere para a tecla de atalho alfabética.
android:numericShortcut
Número inteiro. Um número para a tecla de atalho numérico.
android:alphabeticModifiers
Palavra-chave. Um modificador para o atalho alfabético do item de menu. O valor padrão corresponde à tecla Control. Valores válidos:
ValorDescrição
META Corresponde à tecla Meta.
CTRL Corresponde à tecla Control.
ALT Corresponde à tecla Alt.
SHIFT Corresponde à tecla Shift.
SYM Corresponde à tecla Sym.
FUNCTION Corresponde à tecla Function.

Observação: você pode especificar várias palavras-chave em um atributo. Por exemplo, android:alphabeticModifiers="CTRL|SHIFT" indica que, para acionar o item de menu, o usuário precisa pressionar as teclas Control e Shift junto com o atalho.

Você pode usar o método setAlphabeticShortcut() para definir os valores de atributo de forma programática. Para mais informações sobre o atributo alphabeticModifier, consulte alphabeticModifiers.

android:numericModifiers
Palavra-chave. Um modificador para o atalho numérico do item de menu. O valor padrão corresponde à tecla Control. Valores válidos:
ValorDescrição
META Corresponde à tecla Meta.
CTRL Corresponde à tecla Control.
ALT Corresponde à tecla Alt.
SHIFT Corresponde à tecla Shift.
SYM Corresponde à tecla Sym.
FUNCTION Corresponde à tecla Function.

Observação: você pode especificar várias palavras-chave em um atributo. Por exemplo, android:numericModifiers="CTRL|SHIFT" indica que, para acionar o item de menu, o usuário precisa pressionar as teclas Control e Shift junto com o atalho.

Você pode usar o método setNumericShortcut() para definir os valores de atributo de forma programática. Para mais informações sobre o atributo numericModifier, consulte numericModifiers.

android:checkable
Booleano. Verdadeiro se o item puder ser selecionado.
android:checked
Booleano. Verdadeiro se o item estiver marcado por padrão.
android:visible
Booleano. Verdadeiro se o item estiver visível por padrão.
android:enabled
Booleano. Verdadeiro se o item estiver ativado por padrão.
android:menuCategory
Palavra-chave. Valor correspondente às constantes Menu CATEGORY_*, que definem a prioridade do item. Valores válidos:
ValorDescrição
containerPara itens que fazem parte de um contêiner.
systemPara itens fornecidos pelo sistema.
secondaryPara itens que são opções secundárias (raramente usadas) fornecidas pelo usuário.
alternativePara itens que são ações alternativas nos dados exibidos.
android:orderInCategory
Número inteiro. A ordem de importância do item em um grupo.
<group>
Um grupo de menus para criar um conjunto de itens que compartilham características, por exemplo, se são visíveis, ativados ou selecionáveis. Contém um ou mais elementos <item>. Precisa ser um filho de um elemento <menu>.

Atributos:

android:id
ID de recurso. Um ID de recurso exclusivo. Para criar um novo ID de recurso para este item, use o formulário: "@+id/name". O símbolo de adição indica que ele foi criado como um novo ID.
android:checkableBehavior
Palavra-chave. O tipo de comportamento que pode ser selecionado para o grupo. Valores válidos:
ValorDescrição
noneNão selecionável.
allTodos os itens podem ser selecionados (use caixas de seleção).
singleSomente um item pode ser selecionado (use botões de opção).
android:visible
Booleano. Verdadeiro se o grupo estiver visível.
android:enabled
Booleano. Verdadeiro se o grupo estiver ativado.
android:menuCategory
Palavra-chave. Valor correspondente às constantes Menu CATEGORY_*, que definem a prioridade do grupo. Valores válidos:
ValorDescrição
containerPara grupos que fazem parte de um contêiner.
systemPara grupos fornecidos pelo sistema.
secondaryPara grupos que são opções secundárias fornecidas pelo usuário (usadas com pouca frequência).
alternativePara grupos que são ações alternativas nos dados exibidos.
android:orderInCategory
Número inteiro. A ordem padrão dos itens na categoria.
Exemplo:
Arquivo XML salvo em res/menu/example_menu.xml:
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
    <item android:id="@+id/item1"
          android:title="@string/item1"
          android:icon="@drawable/group_item1_icon"
          app:showAsAction="ifRoom|withText"/>
    <group android:id="@+id/group">
        <item android:id="@+id/group_item1"
              android:onClick="onGroupItemClick"
              android:title="@string/group_item1"
              android:icon="@drawable/group_item1_icon" />
        <item android:id="@+id/group_item2"
              android:onClick="onGroupItemClick"
              android:title="@string/group_item2"
              android:icon="@drawable/group_item2_icon" />
    </group>
    <item android:id="@+id/submenu"
          android:title="@string/submenu_title"
          app:showAsAction="ifRoom|withText" >
        <menu>
            <item android:id="@+id/submenu_item1"
                  android:title="@string/submenu_item1" />
        </menu>
    </item>
</menu>

O código do aplicativo abaixo infla o menu no callback de onCreateOptionsMenu(Menu) e também declara o callback no clique para dois dos itens:

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    menuInflater.inflate(R.menu.example_menu, menu)
    return true
}

fun onGroupItemClick(item: MenuItem) {
    // One of the group items (using the onClick attribute) was clicked.
    // The item parameter passed here indicates which item it is.
    // All other menu item clicks are handled by Activity.onOptionsItemSelected.
}

Java

public boolean onCreateOptionsMenu(Menu menu) {
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.example_menu, menu);
    return true;
}

public void onGroupItemClick(MenuItem item) {
    // One of the group items (using the onClick attribute) was clicked.
    // The item parameter passed here indicates which item it is.
    // All other menu item clicks are handled by Activity.onOptionsItemSelected.
}