Adicionar e gerenciar ações

A barra de apps permite adicionar botões para ações do usuário. Esse recurso permite colocar as ações mais importantes para o contexto atual na parte de cima do app. Por exemplo, um app de navegação de fotos pode mostrar os botões compartilhar e criar álbum na parte de cima quando o usuário estiver olhando para o rolo de fotos. Quando o usuário olha para uma foto individual, o app pode mostrar os botões cortar e filtrar.

O espaço na barra de apps é limitado. Se um app declarar mais ações do que o permitido na barra de apps, ela vai enviar as ações em excesso para um menu flutuante. O app também pode especificar que uma ação seja sempre exibida no menu flutuante em vez de ser mostrada na barra de apps.

Adicionar botões de ação

Todos os botões de ação e outros itens disponíveis no menu flutuante são definidos em um recurso de menu XML. Para adicionar ações à barra de ações, crie um novo arquivo XML no diretório res/menu/ do projeto.

Adicione um elemento <item> para cada item que você quer incluir na barra de ações, conforme mostrado no exemplo de arquivo XML do menu abaixo:

<menu xmlns:android="http://schemas.android.com/apk/res/android" 
xmlns:app="http://schemas.android.com/apk/res-auto">

    <!-- "Mark Favorite", must appear as action button if possible. -->
    <item
        android:id="@+id/action_favorite"
        android:icon="@drawable/ic_favorite_black_48dp"
        android:title="@string/action_favorite"
        app:showAsAction="ifRoom"/>

    <!-- Settings, must always be in the overflow. -->
    <item android:id="@+id/action_settings"
          android:title="@string/action_settings"
          app:showAsAction="never"/>

</menu>

O atributo app:showAsAction especifica se a ação é mostrada como um botão na barra de apps. Se você definir app:showAsAction="ifRoom", como na ação favorite do código de exemplo, a ação vai aparecer como um botão se houver espaço na barra de apps para ela. Se não houver espaço suficiente, as ações excedentes serão enviadas para o menu flutuante. Se você definir app:showAsAction="never", como na ação settings do código de exemplo, a ação será sempre listada no menu flutuante e não será exibida na barra de apps.

O sistema usará o ícone da ação como o botão de ação se a ação for exibida na barra de apps. Você pode encontrar muitos ícones úteis em Ícones do Material Design (link em inglês).

Responder a ações

Quando o usuário seleciona um dos itens da barra de apps, o sistema chama o método de callback onOptionsItemSelected() da atividade e transmite um objeto MenuItem para indicar qual item foi tocado. Na implementação de onOptionsItemSelected(), chame o método MenuItem.getItemId() para determinar qual item foi tocado. O ID retornado corresponde ao valor declarado no atributo android:id do elemento <item> correspondente.

Por exemplo, o snippet de código a seguir verifica qual ação o usuário seleciona. Se o método não reconhecer a ação do usuário, ele invocará o método da superclasse:

override fun onOptionsItemSelected(item: MenuItem) = when (item.itemId) {
    R.id.action_settings -> {
        // User chooses the "Settings" item. Show the app settings UI.
        true
    }

    R.id.action_favorite -> {
        // User chooses the "Favorite" action. Mark the current item as a
        // favorite.
        true
    }

    else -> {
        // The user's action isn't recognized.
        // Invoke the superclass to handle it.
        super.onOptionsItemSelected(item)
    }
}

@Override
public boolean onOptionsItemSelected(MenuItem item) {
    switch (item.getItemId()) {
        case R.id.action_settings:
            // User chooses the "Settings" item. Show the app settings UI.
            return true;

        case R.id.action_favorite:
            // User chooses the "Favorite" action. Mark the current item as a
            // favorite.
            return true;

        default:
            // The user's action isn't recognized.
            // Invoke the superclass to handle it.
            return super.onOptionsItemSelected(item);

    }
}