Implementar uma lupa de texto

Testar 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 exibe uma cópia ampliada de um View por meio de uma painel de sobreposição que representa a lente. O recurso melhora a inserção de texto e experiência do usuário de seleção. Ao aplicar a lupa ao texto, um usuário pode posicione precisamente o cursor ou as alças de seleção visualizando a texto em um painel que acompanha o dedo.

A Figura 1 mostra como a lupa facilita a seleção de texto. APIs de lupa não são vinculados a texto, e você pode usar esse widget em vários casos de uso, como ler textos pequenos ou aumentar nomes de lugares difíceis de ver 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 seu app.

Uso da API

Você pode usar a lupa de maneira 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 é exibida no e contém uma região centralizada nas coordenadas informadas na visualização. O painel aparece acima do ponto central do conteúdo que está sendo copiado. A a lupa persiste indefinidamente até ser dispensada pelo usuário.

O snippet de código a seguir mostra como alterar o plano de fundo da imagem ampliada visualizar:

view.setBackgroundColor(...)

view.setBackgroundColor(...);

Supondo que a cor de fundo seja visível na lupa, o botão o conteúdo está desatualizado, como uma região da visualização com o plano de fundo antigo ainda é exibido. Para atualizar o conteúdo, use o 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 aumente uma região de visualização e tocá-lo, como mostrado na Figura 2.

Isso pode ser feito 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 a lupa específica comportamentos e ativar a lupa 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 verticalmente é fixada no centro da linha de texto atual.
• Ao mover-se horizontalmente, a lupa se move apenas entre o lado esquerdo e limites direito da linha atual. Além disso, quando o toque do usuário sai esses limites e a distância horizontal entre o toque e o limite é maior do que a metade da largura original do conteúdo da lupa, a lupa será dispensada, já que o cursor não estará mais visível lupa.
• A lupa nunca é acionada quando a fonte do texto é muito grande. O texto é é considerado grande demais quando a diferença entre a descida e a subida é maior do que a altura do conteúdo que cabe na lupa. O acionamento da lupa, nesse caso, não agrega valor.