Implementar uma lupa de texto

Teste o Compose

O Jetpack Compose é o kit de ferramentas de interface recomendado para Android. Aprenda a usar texto no Compose.

Modifier.magnifier() →

Disponível no Android 9 (nível 28 da API) e versões mais recentes, o widget de lupa é uma lupa virtual que mostra uma cópia ampliada de uma View em um painel de sobreposição que representa a lente. O recurso melhora a experiência do usuário na inserção e seleção de texto. Ao aplicar a lupa ao texto, o usuário pode posicionar com precisão o cursor ou as alças de seleção, visualizando o texto ampliado em um painel após o dedo.

A figura 1 mostra como a lupa facilita a seleção de texto. As APIs de lupa não estão vinculadas ao texto, e você pode usar esse widget em vários casos de uso, como ler textos pequenos ou ampliar nomes de lugares difíceis de enxergar em mapas.

A lupa já está integrada aos widgets da plataforma, como TextView, EditText e WebView. Ela fornece uma manipulação de texto consistente em todos os apps. O widget vem com uma API simples e pode ser usado para ampliar qualquer View, dependendo do contexto do app.

Uso da API

Você pode usar a lupa de forma programática em uma visualização arbitrária da seguinte maneira:

val view: View = findViewById(R.id.view)
val magnifier = Magnifier.Builder(view).build()
magnifier.show(view.width / 2.0f, view.height / 2.0f)

View view = findViewById(R.id.view);
Magnifier magnifier = new Magnifier.Builder(view).build();
magnifier.show(view.getWidth() / 2, view.getHeight() / 2);

Supondo que a hierarquia de visualização tenha o primeiro layout, a lupa é mostrada na tela e contém uma região centralizada nas coordenadas especificadas na visualização. O painel aparece acima do ponto central do conteúdo que está sendo copiado. A lupa persiste indefinidamente até que o usuário a dispense.

O snippet de código a seguir mostra como mudar o plano de fundo da visualização ampliada:

view.setBackgroundColor(...)

view.setBackgroundColor(...);

Supondo que a cor do plano de fundo esteja visível na lupa, o conteúdo da lupa fica desatualizado, porque uma região da visualização com o plano de fundo antigo ainda é exibida. Para atualizar o conteúdo, use o método update() da seguinte maneira:

view.post { magnifier.update() }

view.post(magnifier::update);

Ao terminar, feche a lupa chamando o método dismiss():

magnifier.dismiss()

magnifier.dismiss();

Ampliar com a interação do usuário

Um caso de uso comum da lupa é permitir que o usuário amplie uma região de visualização tocando nela, como mostrado na Figura 2.

É possível fazer isso atualizando a lupa de acordo com os eventos de toque recebidos pela visualização, da seguinte maneira:

imageView.setOnTouchListener { v, event ->
  when (event.actionMasked) {
    MotionEvent.ACTION_DOWN, MotionEvent.ACTION_MOVE -> {
      val viewPosition = IntArray(2)
      v.getLocationOnScreen(viewPosition)
      magnifier.show(event.rawX - viewPosition[0], event.rawY - viewPosition[1])
    }
    MotionEvent.ACTION_CANCEL, MotionEvent.ACTION_UP -> {
      magnifier.dismiss()
    }
  }
  true
}

imageView.setOnTouchListener(new View.OnTouchListener() {
    @Override
    public boolean onTouch(View v, MotionEvent event) {
        switch (event.getActionMasked()) {
            case MotionEvent.ACTION_DOWN:
                // Fall through.
            case MotionEvent.ACTION_MOVE: {
                final int[] viewPosition = new int[2];
                v.getLocationOnScreen(viewPosition);
                magnifier.show(event.getRawX() - viewPosition[0],
                               event.getRawY() - viewPosition[1]);
                break;
            }
            case MotionEvent.ACTION_CANCEL:
                // Fall through.
            case MotionEvent.ACTION_UP: {
                magnifier.dismiss();
            }
        }
        return true;
    }
});

Considerações adicionais ao ampliar texto

Para os widgets de texto da plataforma, é importante entender os comportamentos específicos da lupa e ativá-la para a visualização de texto personalizada de maneira consistente em toda a Plataforma Android. Considere o seguinte:

• A lupa é acionada imediatamente quando o usuário segura uma alça de inserção ou seleção.
• A lupa sempre segue o dedo do usuário na horizontal suavemente, enquanto na vertical ela é fixada no centro da linha de texto atual.
• Ao se mover horizontalmente, a lupa se move apenas entre os limites esquerdo e direito da linha atual. Além disso, quando o toque do usuário sai desses limites e a distância horizontal entre o toque e o limite mais próximo é maior que metade da largura original do conteúdo da lupa, a lupa é dispensada, porque o cursor não fica mais visível dentro da lupa.
• A lupa nunca é acionada quando a fonte do texto é muito grande. O texto é considerado muito grande quando a diferença entre o descendente e o crescente da fonte é maior do que a altura do conteúdo que se encaixa na lupa. Nesse caso, o acionamento da lupa não agrega valor.