Skip to main content

physical_diagonal 2.1.0 copy "physical_diagonal: ^2.1.0" to clipboard
physical_diagonal: ^2.1.0 copied to clipboard

Device and current-window physical screen diagonal (inches), real PPI, millimeter/inch unit conversion, and adaptive tablet layout detection.

physical_diagonal #

pub package LinkedIn

Device and current-window physical screen diagonal (inches), real hardware PPI, millimeter/inch-to-logical-pixel conversion, and adaptive tablet-layout detection powered by InheritedModel.

Migrating from 0.1.1: PhysicalDiagonal.platformVersion is gone. See "Migrating from 0.1.1" below.

What's new in 2.1.0 #

  • Granular rebuilds via InheritedModel. Calling context.isTabletLayout now subscribes specifically to PhysicalAspect.isTabletLayout — your layout widget only rebuilds when the window crosses the tabletThreshold (e.g., 7.0"), ignoring intermediate frames during interactive window resizing.
  • Real PPI & 1:1 physical unit conversion (mm, cm, inches). Native layers now report physicalPpi and logicalPpi. Render real-world physical dimensions (credit cards, rulers, medical/IoT targets) via context.mm(50), context.inches(2), or PhysicalSizedBox.mm(widthMm: 85.6, heightMm: 53.98).
  • Zero-boilerplate Widget & Golden testing. Pass overrideMetrics directly to PhysicalMetricsScope(overrideMetrics: ...) or call PhysicalDiagonal.setMockMetrics(...) in flutter test — no ensureInitialized() or method-channel mocking required.
  • PhysicalLayoutBuilder. Declarative adaptive builder (PhysicalLayoutBuilder.adaptive(phone: ..., tablet: ...)).

What's new in 2.0.2 #

  • New iOS models. The hardware table covers the iPhone 17 family (17, 17 Pro, 17 Pro Max, iPhone Air, 17e), the iPhone 18 Pro / 18 Pro Max, the iPhone Duo (foldable, dual-display), and the latest iPad mini, iPad (A16), iPad Air and iPad Pro (M4/M5) generations. Full list: Supported iOS devices.
  • iPhone Duo. One identifier, two screens: the plugin reports the 7.6" inner display when the screen's short side exceeds 550 pt, and the 5.4" outer display otherwise. Window tracking keeps working on top of it.
  • Better simulator support. In the iOS Simulator the plugin resolves the simulated device (via SIMULATOR_MODEL_IDENTIFIER) instead of the host Mac's architecture, on both Intel (x86_64) and Apple Silicon (arm64) hosts.

See CHANGELOG.md for the full history.

Install #

dependencies:
  physical_diagonal: ^2.1.0

Usage #

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await PhysicalDiagonal.ensureInitialized();
  runApp(
    const PhysicalMetricsScope(
      tabletThreshold: 7.0,
      child: MyApp(),
    ),
  );
}

// Granular subscription (only rebuilds when crossing 7.0"):
if (context.isTabletLayout) { ... }

// Full metrics subscription (rebuilds on any window resize):
final metrics = context.physical;

// 1:1 physical sizing in millimeters or inches:
const PhysicalSizedBox.mm(
  widthMm: 50,
  heightMm: 10,
  child: ColoredBox(color: Colors.indigo),
);

Widget & Golden Testing #

No platform channel setup or ensureInitialized() call is needed when using overrideMetrics:

testWidgets('renders tablet layout on 11-inch iPad', (tester) async {
  await tester.pumpWidget(
    const PhysicalMetricsScope(
      overrideMetrics: PhysicalMetrics(
        deviceDiagonal: 11.0,
        windowDiagonal: 11.0,
      ),
      child: MyApp(),
    ),
  );
  // Assertions...
});

Supported iOS devices #

The iOS diagonal comes from a static machine-identifier table in PhysicalDiagonalPlugin.swift.

Diagonal Devices (identifiers)
4.7" iPhone SE 2nd / 3rd gen (iPhone12,8, iPhone14,6)
5.4" iPhone 12 mini, 13 mini (iPhone13,1, iPhone14,4)
6.1" iPhone 12, 12 Pro, 13, 13 Pro, 14, 14 Pro, 15, 15 Pro, 16, 16e, 17e
6.3" iPhone 16 Pro, 17, 17 Pro, 18 Pro (iPhone17,1, iPhone18,1, iPhone18,3, iPhone19,1, iPhone19,2)
6.5" iPhone Air (iPhone18,4)
6.7" iPhone 12 Pro Max, 13 Pro Max, 14 Plus, 14 Pro Max, 15 Plus, 15 Pro Max, 16 Plus
6.9" iPhone 16 Pro Max, 17 Pro Max, 18 Pro Max (iPhone17,2, iPhone18,2, iPhone19,3, iPhone19,7)
5.4" / 7.6" iPhone Duo (iPhone19,4) — outer / inner display
8.3" iPad mini 6th gen, iPad mini (A17 Pro)
10.2" iPad 8th / 9th gen
10.9" iPad Air 4th / 5th gen, iPad 10th gen, iPad (A16)
11.0" iPad Pro 11" (M1 / M2 / M4 / M5), iPad Air 11" (M2 / M3 / M4)
12.9" iPad Pro 12.9" (M1 / M2)
13.0" iPad Air 13" (M2 / M3 / M4), iPad Pro 13" (M4 / M5)

Identifiers not in the table fall back to UIDevice.userInterfaceIdiom: 11.0" for iPad, 6.1" for iPhone.

iPhone Duo #

The Duo is a single machine identifier (iPhone19,4) with two displays of different size:

Display Logical size Reported diagonal
Outer 466 × 678 pt 5.4"
Inner 626 × 890 pt 7.6"

Rule: short side > 550 pt → 7.6", otherwise 5.4". With the default tabletThreshold of 7.0, isTabletLayout is false on the outer display and true on the inner display.

iOS Simulator #

When running on x86_64 or arm64 simulators, the plugin reads SIMULATOR_MODEL_IDENTIFIER and looks up the simulated device in the hardware table.

Migrating from 0.1.1 #

Replace:

// 0.1.1
final diagonal = await PhysicalDiagonal.platformVersion;

with:

// 2.0.0+
await PhysicalDiagonal.ensureInitialized();
// then, under a PhysicalMetricsScope:
final diagonal = context.physical.deviceDiagonal;

Platform requirements #

  • iOS deployment target: 13.0.
  • Android minSdk: 21.
  • Supports both CocoaPods and Swift Package Manager on iOS.

Known limitations #

  • iOS hardware-diagonal table is a static machine-identifier list. Unlisted future devices fall back to UIDevice.userInterfaceIdiom (phone/pad).
  • Android DisplayMetrics.xdpi/ydpi accuracy depends on OEM reporting (historically ~5% off on some devices).

LLM / Agent Context #

  • Initialization: await PhysicalDiagonal.ensureInitialized(); before runApp. Never throws.
  • Granular reads in widgets: context.isTabletLayout, context.windowDiagonal, context.deviceDiagonal, context.mm(num), context.cm(num), context.inches(num).
  • Full snapshot in widgets: context.physical returns PhysicalMetrics (deviceDiagonal, windowDiagonal, tabletThreshold, physicalPpi, logicalPpi, isTabletLayout).
  • Testing: Use PhysicalMetricsScope(overrideMetrics: PhysicalMetrics(...)) or PhysicalDiagonal.setMockMetrics(...).

Maintainer #

Built and maintained by Dmytro Ivanitsky — Senior Flutter & Dart Engineer / Mobile Tech Lead.
Connect on LinkedIn • GitHub

2
likes
160
points
628
downloads

Documentation

API reference

Publisher

verified publisherivanitsky.top

Weekly Downloads

Device and current-window physical screen diagonal (inches), real PPI, millimeter/inch unit conversion, and adaptive tablet layout detection.

Homepage
Repository (GitHub)
View/report issues

License

MIT (license)

Dependencies

flutter

More

Packages that depend on physical_diagonal

Packages that implement physical_diagonal