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.
![Uma imagem mostrando como a lupa aparece depois de capturar a alça de seleção correta](https://developer.android.com/static/develop/ui/views/text-and-emoji/images/magnifier-1.png?hl=pt-br)
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:
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 é 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:
Kotlin
view.setBackgroundColor(...)
Java
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:
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 aumente uma região de visualização e tocá-lo, como mostrado na Figura 2.
ViewGroup
que contém uma "ImageView" à esquerda.
e um TextView
à direita.Isso pode ser feito 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 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.