Usar visualizações e provedores de ações

Com a Toolbar da Biblioteca de Suporte v7 appcompat, os usuários podem interagir com seu app de várias maneiras. As lições anteriores descreveram como definir uma ação, que pode ser um botão ou um item de menu. Esta lição descreve como adicionar dois componentes versáteis:

• Uma visualização de ação oferece recursos avançados na barra de apps. Por exemplo, uma visualização de ação de pesquisa permite que o usuário digite o texto de pesquisa na barra de apps, sem ter que mudar atividades ou fragmentos.
• Um provedor de ações é uma ação que tem o próprio layout personalizado. A ação aparece inicialmente como um botão ou item de menu, mas quando o usuário clica nela, o provedor de ações controla o comportamento resultante da maneira que você quiser definir. Por exemplo, o provedor de ações pode responder a um clique exibindo um menu.

As Bibliotecas de Suporte do Android oferecem vários widgets especializados de visualização de ação e de provedor de ações. Por exemplo, o widget SearchView implementa uma visualização de ação para inserir consultas de pesquisa, e o widget ShareActionProvider implementa um provedor de ações para compartilhar informações com outros apps. Você também pode definir as próprias visualizações e provedores de ações.

Adicionar uma visualização de ação

Para adicionar uma visualização de ação, crie um elemento <item> no recurso de menu da barra de ferramentas, conforme descrito em Adicionar botões de ação. Adicione um dos dois atributos a seguir ao elemento <item>:

• actionViewClass: a classe de um widget que implementa a ação.
• actionLayout: um recurso de layout que descreve os componentes da ação.

Defina o atributo showAsAction como "ifRoom|collapseActionView" ou "never|collapseActionView". A sinalização collapseActionView indica como exibir o widget quando o usuário não está interagindo com ele: se o widget estiver na barra de apps, o app precisará exibi-lo como um ícone. Se o widget estiver no menu flutuante, o app precisará exibi-lo como um item de menu. Quando o usuário interage com a visualização de ação, ela é expandida para preencher a barra de apps.

Por exemplo, o código a seguir adiciona um widget SearchView à barra de apps:

    <item android:id="@+id/action_search"
         android:title="@string/action_search"
         android:icon="@drawable/ic_search"
         app:showAsAction="ifRoom|collapseActionView"
         app:actionViewClass="android.support.v7.widget.SearchView" />
    

Se o usuário não estiver interagindo com o widget, o app exibirá o widget como o ícone especificado por android:icon. Se não houver espaço suficiente na barra de apps, o app adicionará a ação ao menu flutuante. Quando o usuário toca no ícone ou no item de menu, o widget se expande para preencher a barra de ferramentas, permitindo que o usuário interaja com ele.

Figura 1. Quando o usuário clica no ícone da visualização de ação, a IU da visualização preenche a barra de ferramentas.

Se você precisar, configure a ação no callback onCreateOptionsMenu() da sua atividade. Você pode ver a referência de objeto da visualização de ação chamando o método getActionView(). Por exemplo, o código a seguir usa a referência do objeto para o widget SearchView definido no exemplo de código anterior:

    override fun onCreateOptionsMenu(menu: Menu?): Boolean {
        menuInflater.inflate(R.menu.main_activity_actions, menu)

        val searchItem = menu?.findItem(R.id.action_search)
        val searchView = searchItem?.actionView as SearchView

        // Configure the search info and add any event listeners...

        return super.onCreateOptionsMenu(menu)
    }
    

    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        getMenuInflater().inflate(R.menu.main_activity_actions, menu);

        MenuItem searchItem = menu.findItem(R.id.action_search);
        SearchView searchView =
                (SearchView) searchItem.getActionView();

        // Configure the search info and add any event listeners...

        return super.onCreateOptionsMenu(menu);
    }
    

Responder a uma visualização de ação expandida

Se o elemento <item> da ação tiver uma sinalização collapseActionView, o app exibirá a visualização de ação como um ícone até que o usuário interaja com essa visualização. Quando o usuário clica no ícone, o gerenciador integrado de onOptionsItemSelected() expande a visualização de ação. Se a subclasse de atividade modificar o método onOptionsItemSelected(), seu método modificado precisará chamar super.onOptionsItemSelected() para que a superclasse possa expandir a visualização de ação.

Se você quer fazer algo quando a ação é expandida ou recolhida, pode definir uma classe que implemente MenuItem.OnActionExpandListener e passar um membro dessa classe para setOnActionExpandListener(). Por exemplo, é possível que você queira atualizar a atividade depois que uma visualização de ação é expandida ou recolhida. O seguinte snippet mostra como definir e passar um listener:

    override fun onCreateOptionsMenu(menu: Menu?): Boolean {
        menuInflater.inflate(R.menu.options, menu)
        // ...

        // Define the listener
        val expandListener = object : MenuItem.OnActionExpandListener {
            override fun onMenuItemActionCollapse(item: MenuItem): Boolean {
                // Do something when action item collapses
                return true // Return true to collapse action view
            }

            override fun onMenuItemActionExpand(item: MenuItem): Boolean {
                // Do something when expanded
                return true // Return true to expand action view
            }
        }

        // Get the MenuItem for the action item
        val actionMenuItem = menu?.findItem(R.id.myActionItem)

        // Assign the listener to that action item
        actionMenuItem?.setOnActionExpandListener(expandListener)

        // Any other things you have to do when creating the options menu...

        return true
    }
    

    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        getMenuInflater().inflate(R.menu.options, menu);
        // ...

        // Define the listener
        OnActionExpandListener expandListener = new OnActionExpandListener() {
            @Override
            public boolean onMenuItemActionCollapse(MenuItem item) {
                // Do something when action item collapses
                return true;  // Return true to collapse action view
            }

            @Override
            public boolean onMenuItemActionExpand(MenuItem item) {
                // Do something when expanded
                return true;  // Return true to expand action view
            }
        };

        // Get the MenuItem for the action item
        MenuItem actionMenuItem = menu.findItem(R.id.myActionItem);

        // Assign the listener to that action item
        MenuItemCompat.setOnActionExpandListener(actionMenuItem, expandListener);

        // Any other things you have to do when creating the options menu...

        return true;
    }
    

Adicionar um provedor de ações

Para declarar um provedor de ações, crie um elemento <item> no recurso de menu da barra de ferramentas, conforme descrito em Adicionar botões de ação. Adicione um atributo actionProviderClass e configure-o com o nome de classe totalmente qualificado para a classe do provedor de ações.

Por exemplo, o código a seguir declara ShareActionProvider, um widget definido na Biblioteca de Suporte que permite que seu app compartilhe dados com outros apps:

    <item android:id="@+id/action_share"
        android:title="@string/share"
        app:showAsAction="ifRoom"
        app:actionProviderClass="android.support.v7.widget.ShareActionProvider"/>
    

Nesse caso, não é necessário declarar um ícone para o widget, porque ShareActionProvider disponibiliza os próprios gráficos. Se você está usando uma ação personalizada, declare um ícone.

Para saber mais sobre como criar um provedor de ações personalizadas, consulte a referência do ActionProvider. Para mais informações sobre como configurar um ShareActionProvider, consulte a referência dessa classe.