Skip to content

physical-units.md

Latest commit

 

History

History
89 lines (62 loc) · 4.74 KB

physical-units.md

File metadata and controls

89 lines (62 loc) · 4.74 KB
Raw

Physical units (compose + code.units)

What it is

Conversion of real-world measures (millimeters, centimeters, inches) using DisplayMetrics / Resources. It does not follow the “300 dp axis” scaling model; use when you need approximate physical size on the device.

Calculation used

  • toMm(mm, resources, context?): TypedValue.COMPLEX_UNIT_MM divided by density → dp as Float; may use DimenCache (CalcType.UNITIES).
  • toCm(cm, resources, context?): same pattern as toMm via mm (cm × 10) → dp Float (cached like toMm).
  • toInch(inches, resources, context?): TypedValue.COMPLEX_UNIT_IN divided by density → dp Float (cached like toMm).
  • Composable Float / Int .mm, .cm, .inch: wrap the above with LocalDensity / LocalResources / LocalContext. They return a Float in dp-equivalent units (not layout pixels). For Compose layout, use .dp on the result, e.g. 10f.mm.dp.

Pure helpers (convertMmToCm, inchToMm, …) are math-only between unit labels.

Code module (com.appdimens.dynamic.code.units.DimenPhysicalUnits):

  • toPxFromMm / Cm / Inch: direct applyDimension → pixels (no double conversion).
  • toDpFromMm / Cm / Inch: physical unit → dp.
  • toSpFromMm / Cm / Inch: via dp and scaledDensity.
  • radiusFromDiameter / radiusFromCircumference: radius in dp after normalizing the diameter/circumference: MM / CM / INCH via toDp*, DP raw, SP as value × (scaledDensity / density), PX as value / density.

How to use

Compose (import com.appdimens.dynamic.compose.mm, .cm, .inch):

import androidx.compose.ui.unit.dp
import com.appdimens.dynamic.compose.mm
import com.appdimens.dynamic.compose.cm

Modifier.width(10f.mm.dp)
Modifier.height(2.5f.cm.dp)
Composable property Receivers Return Typical use
mm Float, Int Float (dp) 10f.mm.dp → Dp for Modifier
cm Float, Int Float (dp) 2.5f.cm.dp
inch Float, Int Float (dp) 1f.inch.dp

Composable instance helpers (on DimenPhysicalUnits in the same file)

API Example
Float.radius(type: UnitType) 48f.radius(UnitType.MM) — radius in dp
Number.radius(type: UnitType) 48.radius(UnitType.DP)
Float.measureDiameter(isCircumference: Boolean) Toggle diameter vs circumference display
Number.measureDiameter(isCircumference: Boolean) Same

Object DimenPhysicalUnits (Compose) — non-composable helpers

API Role Example
toMm(mm, resources, context?) mm → dp Float DimenPhysicalUnits.toMm(10f, resources)
toCm(cm, resources, context?) cm → dp Float DimenPhysicalUnits.toCm(2.5f, resources)
toInch(inches, resources, context?) inch → dp Float DimenPhysicalUnits.toInch(1f, resources)
convertMmToCm / convertMmToInch pure Float convertMmToCm(100f)
convertCmToMm / convertCmToInch pure Float convertCmToInch(2.54f)
convertInchToCm / convertInchToMm pure Float convertInchToMm(1f)
Float.mmToCm(), Number.mmToCm(), … sugar over convert* 5f.mmToInch()
radius(diameter, type: UnitType, resources) half-size in dp radius(24f, UnitType.MM, resources)
displayMeasureDiameter(diameter, isCircumference) scale for circumference internal + extensions
unitSizeInDp(type, resources) size of 1.0 logical unit in dp (mm/cm/inch/dp/sp/px normalized to dp) unitSizeInDp(UnitType.MM, resources)

Use UnitType (MM, CM, INCH, SP, DP, PX, …) with radius and unitSizeInDp.

Note: the former name unitSizePerPx was renamed to unitSizeInDp because the values are expressed in dp, not raw pixels. If DOCUMENTATION/KDOC/ estiver desatualizado, gere HTML com Dokka e execute python3 scripts/sync_kdoc_from_dokka_html.py (ver README.md nesta pasta).

Why use it

Specs from print, regulation (touch target in mm), ruler-based prototyping, or physical mockups.

When to use it

  • Minimum tap target in mm.
  • Matching a cm spec.
  • When stakeholders reason in inches / mm, not dp.

Advantages and trade-offs

  • Pros: speaks “real world”; orthogonal to scaling strategies.
  • Cons: real vs nominal dpi varies; not a substitute for scaled / breakpoints for layout grids.

Recommended usage strategy

Use for legal / a11y minimums and isolated measurements; build the main grid with scaled (or another strategy).

Back to index