Adicionar menus

Experimente trabalhar com o Compose
O Jetpack Compose é o kit de ferramentas de UI recomendado para Android. Saiba como adicionar componentes no Compose.
Menus →

Menus são componentes comuns da interface do usuário em diversos tipos de apps. Para oferecer uma experiência do usuário familiar e consistente, use as APIs Menu para apresentar ações do usuário e outras opções nas suas atividades.

Uma imagem mostrando um exemplo de menu flutuante
Figura 1. Um menu acionado ao tocar em um ícone, que aparece abaixo do ícone do menu flutuante.

Este documento mostra como criar os três tipos fundamentais de menus ou apresentações de ação em todas as versões do Android:

Menu "opções" e barra de apps
O menu "opções" é a coleção principal de itens de menu para uma atividade. É onde você coloca ações que têm um impacto global no app, como "Pesquisar", "Escrever e-mail" e "Configurações".

Consulte a seção Criar um menu "opções".

Modo de ação contextual e menu de contexto
Um menu de contexto é um menu flutuante que aparece quando o usuário toca e mantém pressionado um elemento. Ele fornece ações que afetam o conteúdo selecionado ou o frame do contexto.

O modo de ação contextual mostra itens de ação que afetam o conteúdo selecionado em uma barra na parte de cima da tela e permite que o usuário selecione vários itens.

Consulte a seção Criar um menu contextual.

Menu pop-up
Um menu pop-up mostra uma lista vertical de itens ancorada à visualização que invoca o menu. É bom para fornecer ações adicionais relacionadas a conteúdo específico ou opções para a segunda parte de um comando. As ações em um menu pop-up não afetam diretamente o conteúdo correspondente. É para isso que servem as ações contextuais. Preferivelmente, o menu pop-up serve para ações estendidas que relacionam as regiões de conteúdo na atividade.

Consulte a seção Criar um menu pop-up.

Definir um menu em XML

Para todos os tipos de menu, o Android fornece um formato XML padrão para definir os itens de menu. Em vez de criar um menu no código da atividade, defina um menu e todos os itens dele em um recurso de menu XML. É possível inflar o recurso de menu, carregando-o como um objeto Menu, na atividade ou no fragmento.

Usar um recurso de menu é uma boa prática pelos seguintes motivos:

  • É mais fácil para visualizar a estrutura do menu em XML.
  • Ele separa o conteúdo do menu do código comportamental do app.
  • Ele permite criar configurações alternativas de menu para diferentes versões de plataforma, tamanhos de tela e outras configurações aproveitando a estrutura de recursos do app.

Para definir um menu, crie um arquivo XML dentro do diretório res/menu/ do projeto e crie o menu com os seguintes elementos:

<menu>
Define um Menu, que é um contêiner para os itens de menu. Um elemento <menu> precisa ser o nó raiz do arquivo e pode conter um ou mais elementos <item> e <group>.
<item>
Cria um MenuItem, que representa um único item em um menu. Esse elemento pode conter um elemento <menu> aninhado para criar um submenu.
<group>
Um contêiner invisível e opcional para os elementos <item>. Ele permite categorizar itens de menu para que eles compartilhem propriedades, como estado ativo e visibilidade. Para mais informações, consulte a seção Criar um grupo de menu.

Veja um exemplo de menu chamado game_menu.xml:

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:id="@+id/new_game"
          android:icon="@drawable/ic_new_game"
          android:title="@string/new_game"
          app:showAsAction="ifRoom"/>
    <item android:id="@+id/help"
          android:icon="@drawable/ic_help"
          android:title="@string/help" />
</menu>

O elemento <item> é compatível com vários atributos que você pode usar para definir a aparência e o comportamento de um item. Os itens no menu acima incluem os seguintes atributos:

android:id
É um ID de recurso exclusivo do item. Ele permite que o app reconheça o item quando o usuário o seleciona.
android:icon
Uma referência a um drawable para usar como o ícone do item.
android:title
É uma referência a uma string para usar como o título do item.
android:showAsAction
A especificação de quando e como esse item aparece como um item de ação na barra de apps.

Esses são os atributos mais importantes que você usa, mas há vários outros disponíveis. Para informações sobre todos os atributos compatíveis, consulte a documentação do Recurso de menu.

É possível adicionar um submenu a um item em qualquer menu adicionando um elemento <menu> como filho de um <item>. Os submenus são úteis quando o app tem muitas funções que podem ser organizadas em tópicos, como itens em uma barra de menu de um app para PC, como Arquivo, Editar e Visualizar. Confira este exemplo:

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:id="@+id/file"
          android:title="@string/file" >
        <!-- "file" submenu -->
        <menu>
            <item android:id="@+id/create_new"
                  android:title="@string/create_new" />
            <item android:id="@+id/open"
                  android:title="@string/open" />
        </menu>
    </item>
</menu>

Para usar o menu na sua atividade, _infle_ o recurso de menu, convertendo o recurso XML em um objeto programável usando MenuInflater.inflate(). As seções a seguir mostram como inflar um menu para cada tipo de menu.

Criar um menu "opções"

O menu de opções, como o mostrado na figura 1, é onde você inclui ações e outras opções relevantes para o contexto de atividade atual, como "Pesquisar", "Escrever e-mail" e "Configurações".

Imagem mostrando a barra de apps do Google Planilhas
Figura 2. O app Planilhas Google, mostrando vários botões, incluindo o botão flutuante de ação.

É possível declarar itens para o menu de opções da subclasse Activity ou de uma subclasse Fragment. Se a sua atividade e os seus fragmentos declararem itens para o menu "opções", os itens serão combinados na interface. Os itens da atividade aparecem primeiro, seguidos de cada um desses fragmentos na ordem em que são adicionados à atividade. Se necessário, é possível reorganizar os itens do menu com o atributo android:orderInCategory em cada <item> que você precisar mover.

Para especificar o menu "opções" de uma Activity, substitua onCreateOptionsMenu(). Os fragmentos fornecem o próprio callback onCreateOptionsMenu(). Nesse método, é possível inflar o recurso de menu, definido em XML, no Menu fornecido no retorno de chamada. Isso é mostrado neste exemplo:

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    val inflater: MenuInflater = menuInflater
    inflater.inflate(R.menu.game_menu, menu)
    return true
}

Java

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

Também é possível adicionar itens de menu usando add() e recuperar itens com findItem() para revisar as propriedades com APIs de MenuItem.

Processar eventos de clique

Quando o usuário seleciona um item no menu "opções", incluindo itens de ação na barra de apps, o sistema chama o método onOptionsItemSelected() da atividade. Esse método transmite o MenuItem selecionado. É possível identificar o item chamando getItemId(), que retorna o ID exclusivo do item de menu, definido pelo atributo android:id no recurso de menu ou com um número inteiro fornecido ao método add(). É possível combinar esse ID com itens de menu conhecidos para realizar a ação adequada.

Kotlin

override fun onOptionsItemSelected(item: MenuItem): Boolean {
    // Handle item selection.
    return when (item.itemId) {
        R.id.new_game -> {
            newGame()
            true
        }
        R.id.help -> {
            showHelp()
            true
        }
        else -> super.onOptionsItemSelected(item)
    }
}

Java

@Override
public boolean onOptionsItemSelected(MenuItem item) {
    // Handle item selection.
    switch (item.getItemId()) {
        case R.id.new_game:
            newGame();
            return true;
        case R.id.help:
            showHelp();
            return true;
        default:
            return super.onOptionsItemSelected(item);
    }
}

Quando processar um item de menu corretamente, retorne true. Se você não processar o item de menu, chame a implementação de superclasse de onOptionsItemSelected(). A implementação padrão retorna false.

Se a atividade incluir fragmentos, o sistema vai chamar primeiro onOptionsItemSelected() para a atividade e, em seguida, para cada fragmento na ordem em que eles são adicionados, até que um retorne true ou todos os fragmentos sejam chamados.

Mudar itens de menu no momento da execução

Depois que o sistema chamar onCreateOptionsMenu(), ele vai reter uma instância do Menu que você preencher e não vai chamar onCreateOptionsMenu() novamente, a não ser que o menu seja invalidado. No entanto, use onCreateOptionsMenu() somente para criar o estado inicial do menu e não para fazer mudanças durante o ciclo de vida da atividade.

Se quiser modificar o menu "opções" com base em eventos que ocorrem durante o ciclo de vida da atividade, é possível fazer isso no método onPrepareOptionsMenu(). Esse método transmite a você o objeto Menu como ele existe atualmente para que seja possível modificá-lo, como com adição, remoção ou desativação de itens. Os fragmentos também fornecem um callback onPrepareOptionsMenu().

O menu "opções" é considerado sempre aberto quando os itens de menu são apresentados na barra de apps. Quando um evento ocorre e você quer realizar uma atualização de menu, chame invalidateOptionsMenu() para pedir que o sistema chame onPrepareOptionsMenu().

Criar um menu contextual

Imagem mostrando um menu de contexto flutuante
Figura 3. Um menu de contexto flutuante.

Um menu contextual oferece ações que afetam um item ou frame de contexto específico na interface. É possível fornecer um menu de contexto para qualquer visualização, mas ele é geralmente usado para itens em uma RecylerView ou em outras coleções de visualizações em que o usuário pode realizar ações diretas em cada item.

Há duas formas de fornecer ações contextuais:

  • Em um menu de contexto flutuante. Um menu aparece como uma lista flutuante de itens de menu, semelhante a uma caixa de diálogo, quando o usuário toca e mantém pressionada uma visualização que declara suporte para um menu de contexto. Os usuários podem realizar uma ação contextual em um item por vez.
  • No modo de ação contextual. Esse modo é uma implementação de sistema de ActionMode que exibe uma barra de ação contextual, ou CAB, na parte de cima da tela com itens de ação que afetam os itens selecionados. Quando esse modo está ativo, os usuários podem realizar uma ação em vários itens por vez, se o app permitir.

Observação:o menu de contexto não é compatível com atalhos e ícones de itens.

Criar um menu de contexto flutuante

Para fornecer um menu de contexto flutuante, faça o seguinte:

  1. Registre a View a que o menu de contexto está associado chamando registerForContextMenu() e transmitindo a View.

    Se a atividade usar uma RecyclerView e você quiser que cada item forneça o mesmo menu de contexto, registre todos os itens para um menu de contexto transmitindo a RecyclerView para registerForContextMenu().

  2. Implemente o método onCreateContextMenu() na sua Activity ou Fragment.

    Quando a visualização registrada recebe um evento de tocar e manter pressionado, o sistema chama o método onCreateContextMenu(). É aqui que você define os itens de menu, geralmente inflando um recurso de menu, como no exemplo a seguir:

    Kotlin

        override fun onCreateContextMenu(menu: ContextMenu, v: View,
                            menuInfo: ContextMenu.ContextMenuInfo) {
        super.onCreateContextMenu(menu, v, menuInfo)
        val inflater: MenuInflater = menuInflater
        inflater.inflate(R.menu.context_menu, menu)
    }

    Java

        @Override
    public void onCreateContextMenu(ContextMenu menu, View v,
                                    ContextMenuInfo menuInfo) {
        super.onCreateContextMenu(menu, v, menuInfo);
        MenuInflater inflater = getMenuInflater();
        inflater.inflate(R.menu.context_menu, menu);
    }

    MenuInflater permite inflar o menu de contexto de um recurso de menu. Os parâmetros do método de callback incluem a View que o usuário seleciona e um objeto ContextMenu.ContextMenuInfo que fornece informações adicionais sobre o item selecionado. Se sua atividade tiver várias visualizações, em que cada uma forneça um menu de contexto diferente, você precisará usar esses parâmetros para determinar qual menu de contexto será inflado.

  3. Implemente onContextItemSelected(), conforme mostrado no exemplo a seguir. Quando o usuário seleciona um item de menu, o sistema chama esse método para que você possa realizar a ação adequada.

    Kotlin

        override fun onContextItemSelected(item: MenuItem): Boolean {
        val info = item.menuInfo as AdapterView.AdapterContextMenuInfo
        return when (item.itemId) {
            R.id.edit -> {
                editNote(info.id)
                true
            }
            R.id.delete -> {
                deleteNote(info.id)
                true
            }
            else -> super.onContextItemSelected(item)
        }
    }

    Java

        @Override
    public boolean onContextItemSelected(MenuItem item) {
        AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo();
        switch (item.getItemId()) {
            case R.id.edit:
                editNote(info.id);
                return true;
            case R.id.delete:
                deleteNote(info.id);
                return true;
            default:
                return super.onContextItemSelected(item);
        }
    }

    O método getItemId() consulta o ID do item de menu selecionado, que você atribui a cada item de menu em XML usando o atributo android:id, conforme mostrado em Definir um menu em XML.

    Quando processar um item de menu corretamente, retorne true. Se você não processar o item de menu, transmita-o para a implementação de superclasse. Se a atividade incluir fragmentos, ela vai receber esse callback primeiro. Ao chamar a superclasse quando não processada, o sistema transmite o evento para o respectivo método de callback em cada fragmento, um por vez, na ordem em que cada fragmento é adicionado, até o retorno de true ou false. As implementações padrão para Activity e android.app.Fragment retornam false. Portanto, sempre chame a superclasse quando não processada.

Usar o modo de ação contextual

O modo de ação contextual é uma implementação de sistema de ActionMode que direciona a interação do usuário a efetuar ações contextuais. Quando um usuário ativa esse modo selecionando um item, uma barra de ação contextual aparece na parte de cima da tela para apresentar ações que o usuário pode realizar nos itens selecionados. Enquanto esse modo estiver ativado, o usuário poderá selecionar vários itens, se o app permitir, e desmarcar itens e continuar navegando na atividade. O modo de ação é desativado e a barra de ação contextual desaparece quando o usuário desmarca todos os itens, toca no botão "Voltar" ou na ação Concluído na lateral esquerda da barra.

Para oferecer visualizações que fornecem ações contextuais, você geralmente invoca o modo de ação contextual quando um ou ambos destes eventos ocorrem:

  • O usuário toca e mantém pressionada a visualização.
  • O usuário seleciona uma caixa de seleção ou um componente de IU semelhante dentro da visualização.

Como o app invoca o modo de ação contextual e define o comportamento para cada ação depende do seu projeto. Há dois designs:

  • Para ações contextuais em visualizações arbitrárias individuais
  • Para ações contextuais em lote em grupos de itens em uma RecyclerView, permitindo que o usuário selecione vários itens e realize uma ação em todos eles.

As seções a seguir descrevem a configuração necessária para o primeiro cenário.

Ativar o modo de ação contextual para visualizações individuais

Caso queira invocar o modo de ação contextual somente quando o usuário selecionar visualizações específicas, faça o seguinte:

  1. Implemente a interface ActionMode.Callback, conforme mostrado no exemplo a seguir. Nos métodos de callback, é possível especificar as ações da barra de ação contextual, responder aos eventos de clique em itens de ação e processar outros eventos de ciclo de vida do modo de ação.

    Kotlin

        private val actionModeCallback = object : ActionMode.Callback {
        // Called when the action mode is created. startActionMode() is called.
        override fun onCreateActionMode(mode: ActionMode, menu: Menu): Boolean {
            // Inflate a menu resource providing context menu items.
            val inflater: MenuInflater = mode.menuInflater
            inflater.inflate(R.menu.context_menu, menu)
            return true
        }

        // Called each time the action mode is shown. Always called after
        // onCreateActionMode, and might be called multiple times if the mode
        // is invalidated.
        override fun onPrepareActionMode(mode: ActionMode, menu: Menu): Boolean {
            return false // Return false if nothing is done
        }

        // Called when the user selects a contextual menu item.
        override fun onActionItemClicked(mode: ActionMode, item: MenuItem): Boolean {
            return when (item.itemId) {
                R.id.menu_share -> {
                    shareCurrentItem()
                    mode.finish() // Action picked, so close the CAB.
                    true
                }
                else -> false
            }
        }

        // Called when the user exits the action mode.
        override fun onDestroyActionMode(mode: ActionMode) {
            actionMode = null
        }
    }

    Java

        private ActionMode.Callback actionModeCallback = new ActionMode.Callback() {

        // Called when the action mode is created. startActionMode() is called.
        @Override
        public boolean onCreateActionMode(ActionMode mode, Menu menu) {
            // Inflate a menu resource providing context menu items.
            MenuInflater inflater = mode.getMenuInflater();
            inflater.inflate(R.menu.context_menu, menu);
            return true;
        }

        // Called each time the action mode is shown. Always called after
        // onCreateActionMode, and might be called multiple times if the mode
        // is invalidated.
        @Override
        public boolean onPrepareActionMode(ActionMode mode, Menu menu) {
            return false; // Return false if nothing is done.
        }

        // Called when the user selects a contextual menu item.
        @Override
        public boolean onActionItemClicked(ActionMode mode, MenuItem item) {
           switch (item.getItemId()) {
                case R.id.menu_share:
                    shareCurrentItem();
                    mode.finish(); // Action picked, so close the CAB.
                    return true;
                default:
                    return false;
            }
        }

        // Called when the user exits the action mode.
        @Override
        public void onDestroyActionMode(ActionMode mode) {
            actionMode = null;
        }
    };

    Esses callbacks de eventos são quase exatamente iguais aos callbacks do menu "opções", exceto que cada um deles também transmite o objeto ActionMode associado ao evento. É possível usar APIs de ActionMode para fazer várias mudanças no CAB, como revisar o título e o subtítulo com setTitle() e setSubtitle(), o que é útil para indicar quantos itens estão selecionados.

    O exemplo anterior define a variável actionMode como null quando o modo de ação é destruído. Na próxima etapa, veja como ela é inicializada e como salvar a variável de membro na atividade ou fragmento pode ser útil.

  2. Chame startActionMode() quando quiser mostrar a barra, como quando o usuário toca e mantém pressionada a visualização.

    Kotlin

        someView.setOnLongClickListener { view ->
        // Called when the user performs a touch & hold on someView.
        when (actionMode) {
            null -> {
                // Start the CAB using the ActionMode.Callback defined earlier.
                actionMode = activity?.startActionMode(actionModeCallback)
                view.isSelected = true
                true
            }
            else -> false
        }
    }

    Java

        someView.setOnLongClickListener(new View.OnLongClickListener() {
        // Called when the user performs a touch & hold on someView.
        public boolean onLongClick(View view) {
            if (actionMode != null) {
                return false;
            }

            // Start the CAB using the ActionMode.Callback defined earlier.
            actionMode = getActivity().startActionMode(actionModeCallback);
            view.setSelected(true);
            return true;
        }
    });

    Ao chamar startActionMode(), o sistema retorna o ActionMode criado. Ao salvar isso em uma variável de membro, é possível fazer mudanças na barra de ação contextual em resposta a outros eventos. No exemplo anterior, o ActionMode é usado para garantir que a instância ActionMode não seja recriada se já estiver ativa, verificando se o membro é nulo antes de iniciar o modo de ação.

Criar um menu pop-up

Uma imagem mostrando um menu pop-up no app Gmail, ancorado ao botão flutuante no canto superior direito.
Figura 4. Um menu pop-up no app Gmail, ancorado ao botão flutuante no canto superior direito.

Um PopupMenu é um menu modal ancorado a uma View. Ele aparece abaixo da visualização de âncora, se tiver espaço, ou acima da visualização. Ele é útil para o seguinte:

  • fornecer um menu de estilo de estouro para ações que se relacionam com o conteúdo específico, como cabeçalhos de e-mail do Gmail, exibidos na figura 4;
  • Fornecer uma segunda parte de uma sentença de comando, como um botão marcado Adicionar que produz um menu pop-up com diferentes opções de Adicionar.
  • Fornecer um menu semelhante a um Spinner que não retenha uma seleção persistente.

Se você definir o menu em XML, veja como mostrar o menu pop-up:

  1. Instancie um PopupMenu com o construtor dele, que usa o Context do app atual e a View em que o menu está ancorado.
  2. Use MenuInflater para inflar o recurso de menu no objeto Menu retornado por PopupMenu.getMenu().
  3. Chame o método PopupMenu.show().

Por exemplo, veja um botão que mostra um menu pop-up:

<ImageButton
    android:id="@+id/dropdown_menu"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:contentDescription="@string/descr_overflow_button"
    android:src="@drawable/arrow_drop_down" />

A atividade pode então exibir o menu pop-up desta forma:

Kotlin

findViewById<ImageButton>(R.id.dropdown_menu).setOnClickListener {
    val popup = PopupMenu(this, it)
    val inflater: MenuInflater = popup.menuInflater
    inflater.inflate(R.menu.actions, popup.menu)
    popup.show()
}

Java

findViewById(R.id.dropdown_menu).setOnClickListener(v -> {
    PopupMenu popup = new PopupMenu(this, v);
    popup.getMenuInflater().inflate(R.menu.actions, popup.getMenu());
    popup.show();
});

O menu é dispensado quando o usuário seleciona um item ou toca fora da área do menu. Para ouvir o evento de dispensa, use PopupMenu.OnDismissListener.

Processar eventos de clique

Para realizar uma ação quando o usuário seleciona um item de menu, implemente a interface PopupMenu.OnMenuItemClickListener e registre-a com o PopupMenu chamando setOnMenuItemclickListener(). Quando o usuário seleciona um item, o sistema chama o callback onMenuItemClick() na interface.

Isso é mostrado neste exemplo:

Kotlin

fun showMenu(v: View) {
    PopupMenu(this, v).apply {
        // MainActivity implements OnMenuItemClickListener.
        setOnMenuItemClickListener(this@MainActivity)
        inflate(R.menu.actions)
        show()
    }
}

override fun onMenuItemClick(item: MenuItem): Boolean {
    return when (item.itemId) {
        R.id.archive -> {
            archive(item)
            true
        }
        R.id.delete -> {
            delete(item)
            true
        }
        else -> false
    }
}

Java

public void showMenu(View v) {
    PopupMenu popup = new PopupMenu(this, v);

    // This activity implements OnMenuItemClickListener.
    popup.setOnMenuItemClickListener(this);
    popup.inflate(R.menu.actions);
    popup.show();
}

@Override
public boolean onMenuItemClick(MenuItem item) {
    switch (item.getItemId()) {
        case R.id.archive:
            archive(item);
            return true;
        case R.id.delete:
            delete(item);
            return true;
        default:
            return false;
    }
}

Criar um grupo de menu

Um grupo de menu é uma coleção de itens de menu que compartilham certas peculiaridades. Com um grupo, é possível fazer o seguinte:

É possível criar um grupo aninhando elementos <item> dentro de um elemento <group> no recurso de menu ou especificando um ID de grupo com o método add().

Veja um exemplo de recurso de menu que inclui um grupo:

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:id="@+id/menu_save"
          android:icon="@drawable/menu_save"
          android:title="@string/menu_save" />
    <!-- menu group -->
    <group android:id="@+id/group_delete">
        <item android:id="@+id/menu_archive"
              android:title="@string/menu_archive" />
        <item android:id="@+id/menu_delete"
              android:title="@string/menu_delete" />
    </group>
</menu>

Os itens que estão no grupo aparecem no mesmo nível que o primeiro item — todos os três itens no menu são irmãos. No entanto, é possível modificar as características dos dois itens no grupo mencionando o ID do grupo e usando os métodos anteriores. O sistema também nunca separa os itens agrupados. Por exemplo, se você declarar android:showAsAction="ifRoom" para cada item, eles vão aparecer na barra de ação ou nas ações adicionais.

Usar itens de menu marcáveis

Figura 5. Um submenu com itens marcáveis.

Um menu como uma interface pode ser útil para ativar e desativar as opções, usar uma caixa de seleção para opções independentes ou botões de opção para grupos de opções mutuamente exclusivas. A figura 5 mostra um submenu com itens marcáveis com botões de opção.

É possível definir o comportamento marcável para itens individuais de menu usando o atributo android:checkable no elemento <item> ou para um grupo inteiro com o atributo android:checkableBehavior no elemento <group>. Por exemplo, todos os itens neste grupo de menu são marcáveis com um botão de opção:

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
    <group android:checkableBehavior="single">
        <item android:id="@+id/red"
              android:title="@string/red" />
        <item android:id="@+id/blue"
              android:title="@string/blue" />
    </group>
</menu>

O atributo android:checkableBehavior aceita um dos seguintes valores:

single
Somente um item do grupo pode ser marcado, resultando em botões de opção.
all
Todos os itens podem ser marcados, resultando em caixas de seleção.
none
Nenhum item pode ser marcado.

Para aplicar um estado marcado padrão a um item, use o atributo android:checked no elemento <item> e mude-o no código com o método setChecked().

Quando um item marcável é selecionado, o sistema chama o respectivo método de callback do item selecionado, como onOptionsItemSelected(). É aqui que você define o estado da caixa de seleção, porque uma caixa de seleção ou um botão de opção não muda de estado automaticamente. É possível consultar o estado atual do item (como ele era antes de o usuário selecioná-lo) com isChecked() e, em seguida, definir o estado marcado com setChecked(). Isso é mostrado no exemplo a seguir:

Kotlin

override fun onOptionsItemSelected(item: MenuItem): Boolean {
    return when (item.itemId) {
        R.id.vibrate, R.id.dont_vibrate -> {
            item.isChecked = !item.isChecked
            true
        }
        else -> super.onOptionsItemSelected(item)
    }
}

Java

@Override
public boolean onOptionsItemSelected(MenuItem item) {
    switch (item.getItemId()) {
        case R.id.vibrate:
        case R.id.dont_vibrate:
            if (item.isChecked()) item.setChecked(false);
            else item.setChecked(true);
            return true;
        default:
            return super.onOptionsItemSelected(item);
    }
}

Caso você não defina o estado marcado dessa maneira, o estado visível da caixa de seleção ou do botão de opção não vai mudar quando o usuário selecionar. Quando o estado é definido, a atividade preserva o estado marcado do item para que, quando o usuário abrir o menu posteriormente, o estado marcado definido esteja visível.

Adicionar itens de menu com base em uma intent

Às vezes, você quer que um item de menu inicie uma atividade usando uma Intent, seja uma atividade no seu app ou em outro. Quando você sabe qual intent quer usar e tem um item de menu específico que inicia a intent, é possível executá-la com startActivity() durante o método de callback on-item-selected apropriado, como o callback onOptionsItemSelected().

No entanto, se você não tiver certeza de que o dispositivo do usuário contém um app que lida com a intent, adicionar um item de menu que a invoca pode resultar em um item de menu que não funciona, porque a intent pode não se resolver em uma atividade. Para resolver isso, o Android permite que você adicione itens de menu dinamicamente ao seu menu quando o Android encontra atividades no dispositivo que lidam com a intent.

Para adicionar itens de menu com base nas atividades disponíveis que aceitam uma intent, faça o seguinte:

  1. Defina uma intent com a categoria CATEGORY_ALTERNATIVE ou CATEGORY_SELECTED_ALTERNATIVE, ou ambas, além de quaisquer outros requisitos.
  2. Chame Menu.addIntentOptions(). O Android procura um app que possa realizar a intent e adiciona-o ao seu menu.

Se não houver nenhum app instalado que satisfaça a intent, nenhum item de menu será adicionado.

Isso é mostrado neste exemplo:

Kotlin

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    super.onCreateOptionsMenu(menu)

    // Create an Intent that describes the requirements to fulfill, to be
    // included in the menu. The offering app must include a category value
    // of Intent.CATEGORY_ALTERNATIVE.
    val intent = Intent(null, dataUri).apply {
        addCategory(Intent.CATEGORY_ALTERNATIVE)
    }

    // Search and populate the menu with acceptable offering apps.
    menu.addIntentOptions(
            R.id.intent_group,  // Menu group to which new items are added.
            0,                  // Unique item ID (none).
            0,                  // Order for the items (none).
            this.componentName, // The current activity name.
            null,               // Specific items to place first (none).
            intent,             // Intent created above that describes the requirements.
            0,                  // Additional flags to control items (none).
            null)               // Array of MenuItems that correlate to specific items (none).

    return true
}

Java

@Override
public boolean onCreateOptionsMenu(Menu menu){
    super.onCreateOptionsMenu(menu);

    // Create an Intent that describes the requirements to fulfill, to be
    // included in the menu. The offering app must include a category value
    // of Intent.CATEGORY_ALTERNATIVE.
    Intent intent = new Intent(null, dataUri);
    intent.addCategory(Intent.CATEGORY_ALTERNATIVE);

    // Search and populate the menu with acceptable offering apps.
    menu.addIntentOptions(
         R.id.intent_group,         // Menu group to which new items are added.
         0,                         // Unique item ID (none).
         0,                         // Order for the items (none).
         this.getComponentName(),   // The current activity name.
         null,                      // Specific items to place first (none).
         intent,                    // Intent created above that describes the requirements.
         0,                         // Additional flags to control items (none).
         null);                     // Array of MenuItems that correlate to specific items (none).

    return true;
}

Para cada atividade encontrada que fornece um filtro de intent correspondente à intent definida, um item de menu é adicionado, usando o valor no android:label do filtro de intent como o título do item e o ícone do app como o ícone do item de menu. O método addIntentOptions() retorna o número de itens de menu adicionados.

Permissão para a atividade ser adicionada a outros menus

Você pode oferecer os serviços da sua atividade para outros apps para que o seu possa ser incluído no menu de outros, revertendo as funções descritas anteriormente.

Para ser incluído nos menus de outros apps, defina um filtro de intent como de costume, mas inclua os valores CATEGORY_ALTERNATIVE ou CATEGORY_SELECTED_ALTERNATIVE, ou ambos, para a categoria do filtro de intent. Isso é mostrado neste exemplo:

<intent-filter label="@string/resize_image">
    ...
    <category android:name="android.intent.category.ALTERNATIVE" />
    <category android:name="android.intent.category.SELECTED_ALTERNATIVE" />
    ...
</intent-filter>

Leia mais sobre a criação de filtros de intent em Intents e filtros de intent.