Esta página foi traduzida pela API Cloud Translation.

Adicionar menus

Menus são um componente comum da interface do usuário em muitos tipos de apps. Para fornecem uma experiência de usuário familiar e consistente, use o Menu APIs para apresentar ações do usuário e outras opções em suas atividades.

Imagem mostrando um exemplo de menu flutuante — **Figura 1**. Um menu acionado pelo toque 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 de uma atividades. Ela inclui ações que têm impacto global na aplicativo, como "Pesquisa", "Escrever e-mail" e em "Configurações".

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

Modo de ação contextual e menu de contexto

Um menu de contexto é um menu flutuante que aparece quando o usuário faz um toque e manter um elemento. Ela oferece ações que afetam o conteúdo selecionado ou o frame do contexto.

O modo de ação contextual exibe ações necessárias que afeta o conteúdo selecionado em uma barra na parte superior da tela e permite que o usuário seleciona vários itens.

Consulte a seção Criar um menu contextual nesta seção.

Menu pop-up

Um menu pop-up exibe uma lista vertical de itens ancorados à que invoca o menu. É bom para fornecer um excesso de ações relacionados a conteúdo específico ou oferecer 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, e é para isso que servem as ações contextuais. Em vez disso, o menu pop-up serve para ações estendidas que relacionam com regiões de conteúdo em sua atividade.

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

Definir um menu em XML

Para todos os tipos de menu, o Android oferece um formato XML padrão para definir o menu itens. Em vez de criar um menu no código da atividade, defina um menu e todos os itens em um arquivo XML recurso de menu. Você pode Em seguida, infle o recurso de menu, carregando-o como um Menu. na sua atividade ou fragmento.

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

É mais fácil para visualizar a estrutura do menu em XML.
Ela separa o conteúdo do menu das opções comportamentais o código-fonte.
Permite criar configurações de menu alternativas para diferentes plataformas. diferentes, tamanhos de tela e outras configurações, aproveitando a recursos do app de análise de dados em nuvem.

Para definir um menu, crie um arquivo XML dentro do arquivo res/menu/ e crie o menu com o seguinte elementos:

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

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. Itens no menu anterior inclua os seguintes atributos:

android:id: Um ID de recurso exclusivo do item, que permite que o app reconhecer o item quando que o usuário 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 este item aparece como um item de ação na barra de apps.

Esses são os atributos mais importantes, mas há muitos outros disponíveis. Para informações sobre todos os atributos compatíveis, consulte a Recurso de menu na documentação do Google Cloud.

Você pode 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 na barra de menus 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 em sua atividade, _inflate_ o recurso do 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.

No menu "opções", como o da Figura 1, você inclui ações e outras opções que são relevantes para o contexto de atividade atual, como "Pesquisa", "Escrever e-mail" e em "Configurações".

Uma imagem mostrando a barra de apps do app Planilhas Google — **Figura 2**. O aplicativo Planilhas Google, mostrando vários botões, incluindo o botão de estouro de ação.

É possível declarar itens para o menu "opções" no seu Activity subclasse ou uma Fragment subclasse. Se a atividade e os fragmentos declararem itens para o os itens serão combinados na interface. Os itens da atividade são exibidos primeiro, seguidos pelos de cada fragmento, na ordem em que os fragmentos são adicionados à atividade. Se necessário, você pode reordenar os itens do menu com o atributo android:orderInCategory em cada <item> que você precisa mover.

Para especificar o menu de opções para uma atividade, substitua onCreateOptionsMenu(): Os fragmentos fornecem as próprias onCreateOptionsMenu() o retorno de chamada. Nesse método, é possível inflar o recurso do menu, definido em XML, no Menu fornecido no o 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 MenuItem.

Processar eventos de clique

Quando o usuário seleciona um item no menu "opções", incluindo ações necessárias na barra de apps, o sistema chama o método onOptionsItemSelected() . Esse método transmite o MenuItem selecionado. Você pode 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 para o método add(). É possível combinar esse ID com um cardápio conhecido itens para realizar a ação apropriada.

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 lida com o item de menu, chame a implementação de superclasse de onOptionsItemSelected(): A implementação padrão retorna falsa.

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

Dica:se o app tiver várias atividades e algumas delas fornecem o mesmo menu de opções, considere criar uma atividade que implementa apenas as APIs onCreateOptionsMenu() e onOptionsItemSelected(). Em seguida, estenda essa classe para cada atividade que compartilha o mesmo menu "opções". Assim, você pode gerenciar um conjunto de códigos para lidar com ações do menu e cada classe descendente herda os comportamentos do menu. Se você quiser adicionar itens de menu descendentes, substitua >onCreateOptionsMenu() nessa atividades. Chame super.onCreateOptionsMenu(menu) para que o original itens de menu são criados e adicione novos itens com menu.add(). Também é possível modificar o comportamento da superclasse para itens de menu individuais.

Mudar itens do menu durante a execução

Depois que o sistema chama onCreateOptionsMenu(), ele retém uma instância do Menu que você preenche e não chama onCreateOptionsMenu() novamente, a menos que o menu seja invalidado. No entanto, use onCreateOptionsMenu() apenas para criar o menu inicial. sem fazer mudanças durante o ciclo de vida da atividade.

Se você quiser modificar o menu "opções" com base em eventos que ocorrem durante a no ciclo de vida da atividade, onPrepareOptionsMenu() . Esse método transmite a você o objeto Menu da forma como ele existe para que você possa modificá-la, como adicionar, remover ou desativar itens. Os fragmentos também fornecem uma onPrepareOptionsMenu() o retorno de chamada.

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

Observação:nunca altere os itens no menu "opções" com base no View em foco. No modo de toque, quando o usuário não está usando um trackball ou Botão direcional: as visualizações não podem receber foco, então nunca use o foco como base para modificar itens no menu de opções. Se você quiser fornecer itens de menu que sensíveis ao contexto de uma View, use um menu contextual descritos na próxima seção.

Um menu contextual oferece ações que afetam um item ou contexto específico na interface. Você pode fornecer um menu de contexto para qualquer visualização, mas eles são mais usada frequentemente para itens em uma RecylerView ou outras coleções de visualizações em que o usuário pode realizar ações diretas em cada do item de linha.

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 faz um toque e manter uma visualização que declara suporte para um contexto . Os usuários podem realizar uma ação contextual em um item por vez.
No modo de ação contextual. Este modo é um sistema implementação de ActionMode que exibe uma barra de ação contextual (CAB, na sigla em inglês) na parte superior da tela com as ações necessárias que afetam os itens selecionados. Quando esse modo estiver ativo, os usuários poderão realizar uma ação em vários itens de uma só vez, oferece suporte a isso.

Observação:não é possível usar atalhos e ícones de itens no Menu de contexto.

Criar um menu de contexto flutuante

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

Registrar o View a que o menu de contexto está associado por chamar registerForContextMenu() e transmitindo o View.
Se sua atividade usa um RecyclerView e você quer que cada para fornecer o mesmo menu de contexto, registrar todos os itens para um contexto transmitindo o RecyclerView para o registerForContextMenu().

Implementar o onCreateContextMenu() em Activity ou Fragment.

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

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 a partir de um recurso de menu. O método de callback incluem o View selecionado pelo usuário e um ContextMenu.ContextMenuInfo que fornece informações adicionais sobre o item selecionado. Se sua atividade tem várias visualizações, cada uma fornecendo um menu de contexto diferente, você pode usar esses parâmetros para determinar qual menu de contexto deve inflar.

Implementação onContextItemSelected(), como 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 getItemId() método consulta o ID para o item de menu selecionado, que você atribui a cada item de menu em XML usando o atributo android:id, como mostrado em Definir um menu em XML.

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

Usar o modo de ação contextual

O modo de ação contextual é uma implementação do sistema ActionMode que direciona a interação do usuário para a performance ações contextuais. Quando um usuário ativa esse modo selecionando um item, um a barra de ação contextual aparece na parte superior da tela para apresentar ações que o usuário pode realizar nos itens selecionados. Enquanto esse modo estiver ativado, o usuário pode selecionar vários itens (se o app for compatível) e desmarcar a opção itens e continuar a navegar dentro da atividade. O modo de ação está 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 no lado esquerdo do barra.

Para visualizações que fornecem ações contextuais, você geralmente invoca a função modo de ação quando um desses dois eventos ou ambos ocorrerem:

O usuário realiza um toque e manter a visualização.
O usuário seleciona uma caixa de seleção ou um componente de IU semelhante dentro da visualização.

Como seu app invoca o modo de ação contextual e define o comportamento para cada ação depende do seu design. 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 e realizar uma ação em todos eles.

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

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

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

Implemente a interface ActionMode.Callback conforme mostrado no exemplo a seguir. Nos métodos de callback dele, é possível especificar as ações a barra de ação contextual, responder a eventos de clique em itens de ação e processar outros eventos de ciclo de vida para o 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 para menu de opções, mas cada uma também transmite o objeto ActionMode associado ao evento. É possível usar APIs ActionMode para fazer várias mudanças no CAB, como revisar o título e subtítulo com setTitle() e setSubtitle(), o que é útil para indicar quantos itens são selecionados.

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

Ligação startActionMode() quando você quiser mostrar a barra, como quando o usuário realiza um toque e manter 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;
        }
    });

Quando você chama startActionMode(), o sistema retorna a ActionMode criado. Ao salvar isso em uma variável de membro, você pode fazer alterações 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 será recriada se já tiver sido ativo, verificando se o membro é nulo antes de iniciar a ação modo

Criar um menu pop-up

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

Um PopupMenu é um menu modal ancorado a um View. Ele aparece abaixo da âncora se houver espaço ou acima dela. Ele é útil para seguinte:

Oferecer um menu de estilo flutuante para ações relacionadas a conteúdo específico, como os cabeçalhos de e-mail do Gmail, mostrados na figura 4.
Observação:isso não é o mesmo que um menu de contexto, que geralmente serve para ações que afetam o conteúdo selecionado. Para ações que afetam o conteúdo selecionado, use o método modo de ação contextual ou menu de contexto flutuante.
Fornecer uma segunda parte de uma frase de comando, como um botão marcado Add, que produz um menu pop-up com opções Add diferentes .
Oferecer um menu semelhante a um Spinner que não retenha uma seleção persistente.

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

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

Por exemplo, aqui está 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 dele. área Para detectar 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 o PopupMenu.OnMenuItemClickListener e registrá-la com seu PopupMenu chamando setOnMenuItemclickListener() Quando o usuário seleciona um item, o sistema chama o método onMenuItemClick() em sua 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 cardápios

Um grupo de menu é uma coleção de itens de menu que compartilham certas peculiaridades. Com um faça o seguinte:

Mostrar ou ocultar todos os itens usando setGroupVisible():
Ativar ou desativar todos os itens usando setGroupEnabled():
Especificar se todos os itens são marcáveis usando setGroupCheckable():

Você pode criar um grupo aninhando elementos <item> dentro dele um elemento <group> no recurso de menu ou especificando um com o ID do grupo add() .

Confira 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 do 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. Para exemplo, se você declarar android:showAsAction="ifRoom" para cada item, ambos aparecem na barra de ações ou ambos aparecem na ação estouro.

Usar itens de menu marcáveis

Figura 5. Um submenu com itens marcáveis.

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

Você pode definir o comportamento marcável para itens de menu individuais usando o Atributo android:checkable em <item> ou para um grupo inteiro com a android:checkableBehavior no elemento <group>. Por exemplo, todos os itens em esse grupo de menu podem ser marcados 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 uma das seguinte:

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

É possível aplicar um estado marcado padrão a um item usando o Atributo android:checked no elemento <item> e alterá-la no código com o setChecked() .

Quando um item marcável é selecionado, o sistema chama o respectivo método de callback selecionado pelo item, como onOptionsItemSelected(). É aqui que você define o estado da caixa de seleção, porque uma caixa de seleção ou um botão não muda seu estado automaticamente. É possível consultar o estado atual do item, como era antes de o usuário selecioná-lo, com isChecked() e defina o estado marcado com setChecked(). Isso é mostrado 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);
    }
}

Se o estado marcado não for definido dessa maneira, o estado visível do caixa de seleção ou botão de opção não muda quando o usuário seleciona. Quando você define o estado, a atividade preserva o estado marcado do item para que quando o usuário abrir o menu posteriormente, o estado marcado que você definiu será visíveis.

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 em seu aplicativo ou em outro aplicativo. Quando você saber a intent que você quer usar e ter um item de menu específico que inicie é possível executá-la com startActivity() durante o método de retorno de chamada selecionado no item, como o Chamada de retorno onOptionsItemSelected().

No entanto, se você não tiver certeza de que o dispositivo do usuário contém um app que processa a intenção e, em seguida, a adição de um item de menu que a invoca pode resultar em uma que não funciona, porque a intent pode não se resolver em uma atividade. Para resolver isso, o Android permite adicionar itens de menu dinamicamente ao O Android encontra atividades no dispositivo que processam sua intent.

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

Definir uma intent com a categoria CATEGORY_ALTERNATIVE ou CATEGORY_SELECTED_ALTERNATIVE, ou ambos, além de outros requisitos.
Ligação Menu.addIntentOptions(): O Android procura por aplicativos que possam realizar a intent e adiciona eles ao seu menu.

Se não houver apps instalados que satisfaçam à intent, nenhum menu são adicionados.

Observação:CATEGORY_SELECTED_ALTERNATIVE é usado para processar o elemento selecionado na tela. Use-a apenas ao criar um menu no onCreateContextMenu():

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 definido, um item de menu é adicionado usando o valor no atributo android:label como o título do item de menu, e o ícone do app como o menu. ícone de item. O método addIntentOptions() retorna o número de itens de menu adicionados.

Observação:quando você chama addIntentOptions(), ele substitui todos os itens de menu pelo grupo do menu especificado no primeiro argumento.

Permitir que sua atividade seja adicionada a outros menus

É possível oferecer os serviços da sua atividade a outros apps para que ele possa ser incluído no menu de outros, revertendo os papéis descritos anteriormente.

Para ser incluído em outros menus do app, defina um filtro de intent como de costume, mas inclua CATEGORY_ALTERNATIVE ou Valores CATEGORY_SELECTED_ALTERNATIVE ou ambos para a intent categoria de filtro. 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 como escrever filtros de intent em Intents e intenções filtros.

Adicionar menus

Definir um menu em XML

Criar um menu de opções

Kotlin

Java

Processar eventos de clique

Kotlin

Java

Mudar itens do menu durante a execução

Criar um menu contextual

Criar um menu de contexto flutuante

Kotlin

Java

Kotlin

Java

Usar o modo de ação contextual

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

Kotlin

Java

Kotlin

Java

Criar um menu pop-up

Kotlin

Java

Processar eventos de clique

Kotlin

Java

Criar um grupo de cardápios

Usar itens de menu marcáveis

Kotlin

Java

Adicionar itens de menu com base em uma intent

Kotlin

Java

Permitir que sua atividade seja adicionada a outros menus