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:
Kotlin
val view: View = findViewById(R.id.view) val magnifier = Magnifier.Builder(view).build() magnifier.show(view.width / 2.0f, view.height / 2.0f)
Java
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:
Kotlin
view.setBackgroundColor(...)
Java
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:
Kotlin
view.post { magnifier.update() }
Java
view.post(magnifier::update);
Ao terminar, feche a lupa chamando o
método dismiss()
:
Kotlin
magnifier.dismiss()
Java
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:
Kotlin
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 }
Java
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.