LayrzSelectionMagnifier

LayrzSelectionMagnifier

A Material-free magnifier widget that displays magnified text during long-press+drag selection on touch platforms.

Metadata
Domain: Selection
Phase: M2 (Selection framework)
Primitive: RawMagnifier, MagnifierInfo
Status: Shipped in 0.0.12.
Platforms: Touch (iOS, Android, web mobile) only. Desktop platforms do not show the magnifier.

---

Overview

LayrzSelectionMagnifier displays a magnifying lens that follows the user's finger during long-press text selection on touch devices. The magnifier shows an enlarged view of the text under the finger, helping the user see exactly which character they are selecting.

When It Appears

The magnifier is shown:

• During long-press text selection (initial long-press + drag to extend selection)
• On touch platforms only (iOS, Android, mobile browsers)
• Dismissed when the drag ends, selection is cleared, or the user taps elsewhere

---

API Reference

class LayrzSelectionMagnifier extends StatelessWidget {
  /// The magnification scale factor applied to magnified content.
  ///
  /// Controls the size of the magnified view. Default is 1.25 (25% magnification).
  /// Common values: 1.0 (no magnification), 1.5 (50% magnification).
  final double scale;

  const LayrzSelectionMagnifier({
    super.key,
    this.scale = 1.25,
  });
}

Parameters

• scale (double, default 1.25) — Magnification multiplier. The magnified view is scaled by this factor:
  • 1.0 = no magnification (actual size)
  • 1.25 = 25% larger (default, recommended for most text sizes)
  • 1.5 = 50% larger (for very small text or accessibility)
  • 2.0 = 100% larger (strongly magnified)

---

Visual Properties

The magnifier is rendered as a lens above the current line of text:

• Lens size: 77.37 × 37.9 logical pixels (wide and short, Material design standard)
• Position: Horizontally at the user's finger, vertically above the current text line
• Border radius: Rounded rectangle (full lens appearance)
• Elevation: Positioned above all other content via an overlay
• Content: Magnified copy of the text field content, showing the region under the user's finger

---

Positioning Algorithm

The magnifier positions itself by tracking MagnifierInfo during drag:

1. Horizontal: Finger's x-coordinate, clamped to the current line's bounds
2. Vertical: Above the caret/selection position with a fixed offset to prevent obscuring the finger
3. Focal point: The region of magnified content shown in the lens is calculated so that the text under the user's finger appears in the center of the lens

This algorithm ensures:

• The magnified region is always centered on the user's finger
• The magnifier never fully obscures the text being selected
• The magnifier stays on-screen (within the scrollable area)

---

Scale Parameter

The scale parameter controls how much magnification is applied. The default of 1.25 (25% magnification) is recommended because:

• Small enough that the magnified text is still recognizable (not distorted by extreme zoom)
• Large enough to resolve individual characters for precision selection
• Balanced with the fixed lens size to avoid showing too much context

Common configurations:

// Standard selection (default)
LayrzSelectionMagnifier()
// Equivalent to LayrzSelectionMagnifier(scale: 1.25)

// No magnification (lens shows actual size)
LayrzSelectionMagnifier(scale: 1.0)

// Stronger magnification for accessibility
LayrzSelectionMagnifier(scale: 1.5)

// Extreme zoom (use sparingly)
LayrzSelectionMagnifier(scale: 2.0)

---

Platform Behavior

Touch Platforms (iOS, Android, Web Mobile)

The magnifier is shown and updated in real time during long-press+drag selection. The user sees the magnified region following their finger.

Desktop Platforms (Windows, macOS, Linux)

The magnifier is not shown. Selection on desktop is primarily via keyboard (Shift+arrows, Ctrl+A) or mouse drag without magnification.

---

Technical Notes

• Touch tracking: The magnifier listens to MagnifierInfo updates from EditableText, which reports finger position, text caret position, and line geometry
• Focal point calculation: The focal point offset is calculated so that the content under the user's finger appears magnified in the center of the lens. This requires coordinating the magnifier's position, the scale factor, and the focal point offset.
• Lens dimensions: The 77.37 × 37.9 size is Material's standard magnifier lens dimensions and is not configurable
• Real-time updates: As the user drags, the magnifier recomputes its position and the focal point to track the selection
• Accessibility: The magnifier is visually present but is not exposed as a separate interactive element to screen readers (it is a visual aid, not a control)

---

Related Components

• LayrzTextSelectionControls — integrates the magnifier into text selection via selectionControls
• LayrzSelectionHandlePainter — renders the teardrop-shaped selection handles (related visual element)
• LayrzTextInput — uses LayrzTextSelectionControls, which includes the magnifier

---

Interaction Example

On a touch device, during text selection:

1. User long-presses a word in LayrzTextInput

   • Magnifier appears above the long-pressed position
   • Text under the finger is magnified and visible in the lens

2. User drags to extend the selection

   • Magnifier moves horizontally to track the finger
   • Focal point updates to show the text region under the finger
   • Selection expands as the user drags

3. User releases

   • Magnifier disappears
   • Selection toolbar appears above the selected text (showing copy, cut, paste, select all actions)

---

Last updated: 2026-08-20
Related documents: LayrzTextInput, LayrzTextSelectionControls, Selection (D50)