Skip to content

scaled.md

Latest commit

 

History

History
61 lines (37 loc) · 4.48 KB

scaled.md

File metadata and controls

61 lines (37 loc) · 4.48 KB
Raw

Scaled strategy (compose / mirrored code — sources under compose/scaled/)

Artifact: io.github.bodenberg:appdimens-kmp:1.0.1 (:library) API catalog: COMPOSE-API-CONVENTIONS.md · modules: MODULES.md

What it is

Scaled is the default AppDimens Dynamic mode: it scales design values around the 300 dp reference on the chosen axis (smallest width, height, or width of the window). This is the classic SDP / HDP / WDP behavior with cache, qualifiers, and Configuration integration.

Typical usage: Scaled is the most widely used strategy and fits most apps and screens. Use it without a for straightforward linear scaling, or with a / ia when aspect-ratio-aware refisement is needed — both are still Scaled; you only need another strategy when requirements clearly call for a different curve.

Calculation used

  • Read the effective axis in dp (after orientation inverters, if any).
  • Without applyAspectRatio (a / ia): result ≈ base × (dim / 300) — factor 1/300 (INV_BASE_RATIO in DimenCache).
  • With applyAspectRatio: uses DimenCache.calculateRawScaling, which combines deviation from 300 dp with the per-window aspect-ratio adjustment derived in the immutable DimenMetrics snapshot (logNormalizedAr, defaultScaledAspectRatioMultiplier), read via DimenCache.currentMetrics at resolution time.
  • With ignoreMultiWindows (i / ia) and the multi-window heuristic active: returns the raw base value (no scaling).
  • Reference constant: BASE_WIDTH_DP = 300f in DesignScaleConstants (which axis is used depends on the qualifier).

Common suffixes: a = aspect ratio; i = ignore multi-window; ia = both. Inverters (e.g. .sdpPh, .sdpLw) swap the effective axis by orientation.

How to use

Compose — import extensions from com.appdimens.kmp.compose (the package that exposes sdp, hdp, wdp, ssp, etc. — the source files live under compose/scaled/ but the package is top-level compose):

import com.appdimens.kmp.compose.sdp
import com.appdimens.kmp.compose.hdp
import com.appdimens.kmp.compose.wdp

Modifier.padding(16.sdp).width(100.wdp)

The code module also exposes Int and Float receiver overloads for sdp / hdp / wdp (and a / i / ia variants), plus toDynamicScaledPx / toDynamicScaledDp, to avoid Number boxing on hot paths. The Number overloads remain for backward compatibility.

Code (Views / Kotlin) — com.appdimens.kmp.code.DimenSdp, DimenSsp, extensions ssp, scaledSp(), etc.

Each strategy follows the same file pattern: Dimen*Dp, *DpExtensions, *Scaled, *Sp, *SpExtensions, *SpScaled (in scaled, Sp templates may use names like DimenSsp* in legacy code).

Builders (scaledDp / scaledSp): customValue accepts fractional dp/sp (Number / Dp); values are not truncated to integers. The screen(..., customValue: Number) overload forwards applyAspectRatio and customSensitivityK like the Dp overload. SSP scaling uses the same DimenCalculationPlumbing multi-window and qualifier rules as the Dp path.

Why use it

It is the library’s balanced choice: predictable, tightly integrated with DimenCache, supports builders (scaledDp() / scaledSp()), facilitators (rotation, UI mode, qualifier), and inverters — without exotic curves.

When to use it

  • Normal app layouts (phone, tablet, foldable).
  • When you want the same baseline “look” the main README describes.
  • Whenever there is no strong reason to use pure percent, power, fluid, etc.

Advantages and trade-offs

  • Pros: familiar curve; strong performance — shouldBypassCache skips snapshot-cache storage for PERCENT / SCALED / DENSITY / DIAGONAL / INTERPOLATED / PERIMETER (and default AR on those paths); see library/PERFORMANCE.md.
  • Cons: on very large screens, linear growth (without a) can feel aggressive vs power or fluid — then consider another strategy only for affected components.

Recommended usage strategy

Use SDP (.sdp) for spacing and sizes that should stay coherent across rotation; HDP for vertical lists; WDP when available width should dominate. Enable a if non-standard aspect ratios hurt the layout. Only after QA, replace selectively with another strategy from this index.

Back to index