Magnifier widget

Available in Android 9 (API level 28) and higher, the magnifier widget is a virtual magnifying glass that displays an enlarged copy of a chosen View through an overlay pane that represents the lens. The feature improves the text insertion and selection user experience: when applying the magnifier to text, a user can precisely position the cursor or the selection handles by viewing the magnified text in a pane that follows their finger. Figure 1 below showcases the way the magnifier facilitates selecting text. The magnifier APIs are not tied to text, and this widget can be used in a variety of use cases, such as reading small type or enlarging hard-to-see place names on maps.

The magnifier is already integrated with platform widgets such as TextView, EditText, or WebView. It provides consistent text manipulation across applications. The widget comes with a simple API and can be used to magnify any View depending on your application’s context.

Figure 1. Magnifying text. After the user grabs the right selection handle, the magnifier pops up to help with accurate placement.

API usage

The magnifier can be programmatically used on an arbitrary view as follows:

Kotlin

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

Java

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

Assuming that the view hierarchy already had the first layout, the magnifier is displayed on the screen and contains a region centered on the given coordinates within the View. The pane appears above the center point of the content being copied. The magnifier persists indefinitely until the user dismisses it.

Note: The arguments of show() are relative to the top left corner of the view being magnified.

Suppose that we want to change the background of the magnified view:

Kotlin

view.setBackgroundColor(...)

Java

view.setBackgroundColor(...);

Assuming that the background color is visible within the magnifier, the magnifier’s content is now stale, as a region of the view with the old background is still displayed. To refresh the content, use the update() method:

Kotlin

view.post { magnifier.update() }

Java

view.post(new Runnable() {
    magnifier.update();
});

Note: We post the update operation to make sure that by the time this is executed, the view with the new background color will have already been drawn. This is because the magnifier content always stays a frame behind the magnified view.

When finished, close the magnifier by calling the dismiss() method:

Kotlin

magnifier.dismiss()

Java

magnifier.dismiss();

Magnify on user interaction

A common use case for the magnifier is to allow the user to enlarge a view region by touching it, as shown in Figure 2 below. You can achieve this by updating the magnifier according to the touch events received by the view:

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;
    }
});

Note: the magnifier never displays magnified content that does not belong to the view, even when the view is included in scrollable containers and partially masked. When the coordinates passed to show() imply copying outside content, they are coerced inside the visible region of the view.

Figure 2. The magnifier follows the user's touch. It is applied to a ViewGroup that contains an ImageView to the left and a TextView to the right.

Additional considerations when magnifying text

For the platform text widgets, it's important to understand specific magnifier behaviors and to enable the magnifier for your custom text view in a consistent way across the entire Android platform. Consider the following:

• The magnifier is triggered immediately when the user grabs an insertion or selection handle.
• The magnifier always smoothly follows the user’s finger horizontally, while vertically it is fixed to the center of the current text line.
• When moving horizontally, the magnifier moves only between the left and right bounds of the current line. Moreover, when the user’s touch leaves these bounds and the horizontal distance between the touch and the closest bound is larger than half of the original width of the magnifier content, the magnifier is dismissed, as the cursor would no longer be visible inside the magnifier.
• The magnifier is never triggered when the text font is too large. Specifically, text is considered too large when the difference between the font’s descent and ascent is larger than the height of the content that fits in the magnifier. Triggering the magnifier in this case does not add value.