The Android Developer Challenge is back! Submit your idea before December 2.

Adicionar e processar ações

A barra de apps permite adicionar botões para ações do usuário. Com esse recurso, é possível colocar as ações mais importantes para o contexto atual na parte superior do app. Por exemplo, um app para procurar fotos pode mostrar os botões compartilhar e criar álbum na parte superior quando o usuário está vendo o rolo de fotos. Quando o usuário vê 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 ações demais na barra de apps, ela enviará as ações em excesso para um menu flutuante. O app também pode especificar que uma ação deve ser sempre mostrada no menu flutuante, em vez de exibida na barra de apps.

Figura 1. Uma barra de apps com um único botão de ação e um menu flutuante.

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ção, crie um novo arquivo XML no diretório res/menu/ do seu projeto.

Adicione um elemento <item> para cada item que você quer incluir na barra de ação, conforme mostrado neste exemplo de código de um arquivo XML de menu:

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

        <!-- "Mark Favorite", should 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, should 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 deve ser mostrada como um botão na barra de apps. Se você definir o app:showAsAction="ifRoom" (como na ação favorite do código de exemplo), a ação será exibida como um botão se houver espaço na barra de apps. Caso contrário, 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.

Se a ação for exibida na barra de apps, o sistema usará o ícone dela como botão de ação. Você pode encontrar diversos ícones úteis na página Ícones do Material Design (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 clicado. Na implementação de onOptionsItemSelected(), chame o método MenuItem.getItemId() para determinar qual item foi pressionado. O código retornado corresponde ao valor declarado no atributo android:id do elemento <item> correspondente.

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

Kotlin

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

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

        else -> {
            // If we got here, the user's action was not recognized.
            // Invoke the superclass to handle it.
            super.onOptionsItemSelected(item)
        }
    }
    

Java

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

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

            default:
                // If we got here, the user's action was not recognized.
                // Invoke the superclass to handle it.
                return super.onOptionsItemSelected(item);

        }
    }