physical_diagonal
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. Callingcontext.isTabletLayoutnow subscribes specifically toPhysicalAspect.isTabletLayout— your layout widget only rebuilds when the window crosses thetabletThreshold(e.g., 7.0"), ignoring intermediate frames during interactive window resizing. - Real PPI & 1:1 physical unit conversion (
mm,cm,inches). Native layers now reportphysicalPpiandlogicalPpi. Render real-world physical dimensions (credit cards, rulers, medical/IoT targets) viacontext.mm(50),context.inches(2), orPhysicalSizedBox.mm(widthMm: 85.6, heightMm: 53.98). - Zero-boilerplate Widget & Golden testing. Pass
overrideMetricsdirectly toPhysicalMetricsScope(overrideMetrics: ...)or callPhysicalDiagonal.setMockMetrics(...)influtter test— noensureInitialized()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/ydpiaccuracy depends on OEM reporting (historically ~5% off on some devices).
LLM / Agent Context
- Initialization:
await PhysicalDiagonal.ensureInitialized();beforerunApp. 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.physicalreturnsPhysicalMetrics(deviceDiagonal,windowDiagonal,tabletThreshold,physicalPpi,logicalPpi,isTabletLayout). - Testing: Use
PhysicalMetricsScope(overrideMetrics: PhysicalMetrics(...))orPhysicalDiagonal.setMockMetrics(...).
Maintainer
Built and maintained by Dmytro Ivanitsky — Senior Flutter & Dart Engineer / Mobile Tech Lead.
Connect on LinkedIn • GitHub