Bodenberg.AppDimens.Dynamic 3.6.1

Bodenberg.AppDimens.Dynamic

📖 Documentation: Bodenberg.AppDimens.Dynamic guide · complete API reference · all AppDimens .NET packages

.NET 10 binding for Android (net10.0-android) that wraps AppDimens Dynamic — responsive dp / sp / px sizing in code (no XML dimen grids), with 15 scaling strategies, conditional facilitators, aspect-ratio and multi-window variants, physical units, auto-resize helpers, and optional DataStore-backed caching.

Kotlin/Java sources, strategy semantics, and Android-focused guides live upstream:

→ bodenberg/appdimens-dynamic · DOCUMENTATION · KDoc search

Maven artifact embedded in this package: io.github.bodenberg:appdimens-dynamic 3.2.0.

Install

dotnet add package Bodenberg.AppDimens.Dynamic --version 3.6.1

Getting started (step by step)

New to AppDimens? Follow these steps in order — each one is copy-and-paste.

Step 1 — Is this the right package?

This package wraps a native Android library, so it only runs on Android.

Step 2 — Install

Visual Studio: right-click the project → Manage NuGet Packages… → search Bodenberg.AppDimens.Dynamic → Install.

Command line:

dotnet add package Bodenberg.AppDimens.Dynamic --version 3.6.1

In a MAUI app the package only affects the Android target — wrap Android-only code in #if ANDROID.

Step 3 — Use it from C#

All Dimen* methods return pixels (float). Android views expect pixels, so you can apply them directly:

using Android.Util;          // ComplexUnitType
using Com.Appdimens.Dynamic.Code;

// In an Activity (this = Context)
DynamicConfig.Warmup(this);   // optional, warms the cache

int padding = (int)DimenSdp.Sdp(this, 16);
myCard.SetPadding(padding, padding, padding, padding);

// Text: tell Android the value is already in pixels
myTitle.SetTextSize(ComplexUnitType.Px, DimenSsp.Ssp(this, 18));

⚠️ Common mistake: myTitle.TextSize = value; interprets the number as sp and scales it a second time. Always use SetTextSize(ComplexUnitType.Px, value) with AppDimens values.

Step 4 — Use it in a .NET MAUI app (Android)

MAUI sizes are device-independent units, so divide the pixel value by the screen density:

#if ANDROID
using Com.Appdimens.Dynamic.Code;
using Microsoft.Maui.Devices;

var context = Platform.CurrentActivity ?? Android.App.Application.Context;
var density = DeviceDisplay.MainDisplayInfo.Density;

titleLabel.FontSize = DimenSsp.Ssp(context, 18) / density;
card.Padding = new Thickness(DimenSdp.Sdp(context, 16) / density);
#endif

Step 5 — Keep sizes right after rotation / fold / resize

using Com.Appdimens.Dynamic;

public override void OnConfigurationChanged(Android.Content.Res.Configuration newConfig)
{
    base.OnConfigurationChanged(newConfig);
    DynamicConfig.OnConfigurationChanged(this, newConfig);   // recalculates factors
}

// Anywhere (e.g. OnCreate): re-apply sizes when they change
DynamicConfig.DimensionsShouldRefresh += (_, _) => ApplySizes();

Cheat sheet — which function do I use?

Rule of thumb: write the same numbers you would normally use in dp/sp. AppDimens treats them as sizes on a 300 dp-wide reference phone and scales them proportionally: 16 becomes ~19 dp on a 360 dp phone and ~32 dp on a 600 dp tablet.

Requirements

Use Android SDK platform 36+ (or MSBuild InstallAndroidDependencies) when building bindings locally on .NET 10.

What this library provides

C# namespaces (binding layout)

Public Kotlin @JvmStatic APIs appear under Com.Appdimens.Dynamic.* (Java package → C# namespace):

Foldable-aware overloads use AndroidX.Window.Layout.IFoldingFeature from Xamarin.AndroidX.Window.

Quick start (Activity / Views)

Warm the cache once (recommended), then read pixel sizes:

using Android.App;
using Android.OS;
using Com.Appdimens.Dynamic.Code;

[Activity(Label = "My App", MainLauncher = true)]
public class MainActivity : Activity
{
    protected override void OnCreate(Bundle? savedInstanceState)
    {
        base.OnCreate(savedInstanceState);

        DimenSdp.WarmupCache(this);

        float paddingPx = DimenSdp.Sdp(this, 16);
        float heightPx  = DimenSdp.Hdp(this, 32);
        float widthPx   = DimenSdp.Wdp(this, 100);
        float fontPx    = DimenSsp.Ssp(this, 16);
    }

    public override void OnConfigurationChanged(Android.Content.Res.Configuration newConfig)
    {
        base.OnConfigurationChanged(newConfig);
        Com.Appdimens.Dynamic.Core.DimenCache.InvalidateOnConfigChange(newConfig);
    }
}

Scaled API (DimenSdp / DimenSsp)

Primary entry points in Com.Appdimens.Dynamic.Code:

Inverter shortcuts (orientation-aware axis switch), examples:

• SdpPh / SdpPha — smallest width in portrait → height in landscape
• SdpLw / SdpLwa — smallest width → width in landscape
• HdpLw, WspLh, … — same idea for HDP / WSP

Facilitators (imperative), examples:

// Landscape uses 24 sdp, otherwise 16
float pad = DimenSdp.SdpRotate(this, 16, 24);

// TV UI mode override
float tvTitle = DimenSsp.SspMode(this, 16, 22, Com.Appdimens.Dynamic.Common.UiModeType.Television);

// sw ≥ 600 bucket
float tablet = DimenSdp.SdpQualifier(this, 16, 20,
    Com.Appdimens.Dynamic.Common.DpQualifier.SmallWidth, 600);

// Combined UI mode + qualifier (+ optional FoldingFeature overloads)
float fold = DimenSdp.SdpScreen(this, 16, 28,
    Com.Appdimens.Dynamic.Common.UiModeType.Television,
    Com.Appdimens.Dynamic.Common.DpQualifier.SmallWidth, 600);

Kotlin extension-style facilitators (sdpRotatePlain, nested chains) are exposed as DimenSdpExtensionsKt / DimenSspExtensionsKt when generated; prefer plain Dp/float overloads in C# when chaining to avoid double scaling (see upstream COMPOSE-API-CONVENTIONS).

DimenScaled builder

Build a rule list; resolution uses priority inside the builder, not lexical nesting:

using Com.Appdimens.Dynamic.Code;
using Com.Appdimens.Dynamic.Common;

var scaled = DimenSdp.Scaled(16)
    .Screen(UiModeType.Television, DpQualifier.SmallWidth, 600, 40f)
    .Screen(UiModeType.Television, 32f)
    .Screen(Orientation.Landscape, 20f);

float px = scaled.Sdp(this);

Use DimenSsp.Scaled / ScaledSp for typography with the same .Screen(...) pattern.

Other scaling strategies

Each strategy lives under Com.Appdimens.Dynamic.Code.<Strategy> with Dimen<Strategy>, Dimen<Strategy>Dp, Dimen<Strategy>Sp, extension/facilitator types, and optional *Scaled builders.

Recommendation: start with Scaled → then percent / auto when needed; adopt others for specialized layouts (strategy guide).

Method prefixes mirror Scaled (psdp, asdp, fsdp, …) — import the matching Dimen* type for that strategy.

Physical units

Com.Appdimens.Dynamic.Code.Units.DimenPhysicalUnits converts real-world units using display metrics:

using Com.Appdimens.Dynamic.Code.Units;

float dpFromMm = DimenPhysicalUnits.ToDpFromMm(10f, Resources);
float pxFromCm = DimenPhysicalUnits.ToPxFromCm(2f, Resources);
float spFromInch = DimenPhysicalUnits.ToSpFromInch(0.25f, Resources);

Also: MmToCm, RadiusFromDiameter, RadiusFromCircumference, etc.

Resize helpers

Com.Appdimens.Dynamic.Code.Resize.DimenResize / DimenResizeKt expose auto-resize utilities (text size, square size, bounds). Compose-oriented variants may reference Composer; for .NET, check generated members or follow upstream DOCUMENTATION/resize.md.

Cache and configuration

Com.Appdimens.Dynamic.Core.DimenCache:

Persistence uses AndroidX DataStore; this NuGet pulls Xamarin.AndroidX.DataStore.Preferences (required at runtime for DimenCache).

Jetpack Compose (com.appdimens.dynamic.compose)

The AAR ships Compose extensions (DimenSdpKt, DimenAutoKt, autoResizeTextSp, …) that take androidx.compose.runtime.Composer. With the current class-parse binding pipeline, many Compose helpers are not practical from C# (missing or incomplete Composer wrappers).

Use this package for:

• Com.Appdimens.Dynamic.Code — Activities, Fragments, custom View measurement, MAUI Android handlers
• Com.Appdimens.Dynamic.Core / Common — cache, qualifiers, shared types

Compose-first apps on .NET may need a future binding strategy or shared logic called from Kotlin.

Dependencies brought in by this package

Package version vs embedded AAR

When Maven publishes a new version, run ./scripts/sync-aar-from-maven.sh <maven-version> and bump the NuGet version accordingly.

Build this binding locally

cd appdimens-dynamic-net-binding
dotnet build AppDimens.Dynamic.sln -c Release

Optional smoke APK: AppDimens.Dynamic.SmokeTest — produce it with:

dotnet publish AppDimens.Dynamic.SmokeTest/AppDimens.Dynamic.SmokeTest.csproj -c Release -f net10.0-android -p:AndroidPackageFormat=apk

Sync the upstream AAR:

./scripts/sync-aar-from-maven.sh 3.2.0

Related packages

Links

License

Apache 2.0, consistent with the upstream library.