Android
Donkeh.Windowing.Android is deliberately small. It is the
framework-owned Android activity that boots the portable windowing stack on
an external GLES surface, applies mobile defaults, translates display density
into CSS pixels, and installs the Android runtime-permission provider. App
code still declares only an [AppRoot].
What the package hides
The application project targets net10.0-android and references
this package, but never writes an activity. The host hides four things that
would otherwise leak into every app:
| Concern | Handled by |
|---|---|
| Launcher activity and manifest entry | DonkehActivity is the MainLauncher, exported, with a fullscreen no-action-bar theme. |
| GLES context and surface | Creates a Silk.NET view with OpenGL ES 3.0, depth 24, stencil 8, no MSAA, VSync and a 60 Hz cap. |
| Density and lifecycle | Reads display density, converts the external surface into a CSS-pixel viewport and keeps the activity across configuration changes. |
| Runtime permissions | Installs an IPermissionService that requests from the activity and completes from OnRequestPermissionsResult. |
The activity
DonkehActivity derives from Silk.NET's SDL-backed
SilkActivity. Its attributes declare a fullscreen Material
no-action-bar theme and a configuration-change set that includes orientation,
keyboard, UI mode, density, screen layout and smallest screen size. Because
the activity handles those changes itself, rotation does not recreate it: the
same DonkehWindow keeps running and CSS reflows against the new
surface size.
[Activity(
Label = "Donkeh",
MainLauncher = true,
Exported = true,
Theme = "@android:style/Theme.Material.NoActionBar.Fullscreen",
ConfigurationChanges = SilkActivity.ConfigChangesFlags
| ConfigChanges.UiMode
| ConfigChanges.Density
| ConfigChanges.ScreenLayout
| ConfigChanges.SmallestScreenSize)]
public class DonkehActivity : SilkActivity
The SDL binding seam
SilkActivity is abstract, so .NET Android does not emit a static
JNI registration block for it, and the delegate getters that register
n_loadLibraries, n_setOrientationBis and
n_onDestroy are private on the binding base. The host
re-exposes those handlers for this concrete activity through
GetBaseHandler, which reflects the private static getter once.
DynamicDependency attributes keep the binding members rooted for
trimming.
MissingMethodException.
Starting the app
OnRun is the Android equivalent of the desktop entry point:
- Discover the
[AppRoot]definition. - Read
Resources.DisplayMetrics.Density. - Create
AndroidPermissionServiceand install it throughHost.UsePermissions. - Create a GLES 3.0 view with a 24-bit depth buffer, 8-bit stencil, no MSAA, VSync and a 60 FPS cap.
- Clone the app settings and override everything the activity owns: size, chrome, VSync, frame cap, samples, resizability, devtools and DPI.
- Create
DonkehWindow, run the view with the app root and merged styles, and let the shared window loop do the rest.
var settings = app.Settings with
{
Width = 0, // the activity owns the surface
Height = 0,
VSync = true,
TargetFramesPerSecond = 60,
Samples = 0, // no MSAA on the mobile path
Resizable = false,
Frameless = false,
EnableDevTools = false,
EnableTouchScrolling = true, // swipe pans the nearest scroll container
DpiScale = density
};
An app’s requested window width, height, frame style, MSAA, drag-resize and devtools settings are therefore visual suggestions on Android, not contracts. The surface, frame pacing and chrome belong to the activity.
Density and CSS pixels
Android reports a surface in physical pixels and a density scalar, not a
desktop-style logical window. The host passes density as
WindowSettings.DpiScale, so the window divides view and pointer
coordinates by it before layout and hit testing. CSS pixels stay independent
of the panel resolution.
Some SDL builds already expose a logical window size and a larger drawable.
In that case applying density again would shrink the UI, so the
Loaded handler checks the ratio and resets DpiScale
to zero when the framebuffer is already larger than the logical size. The
same handler prints density, DPI, size, framebuffer and GL version for
diagnosis.
Touch scrolling
SDL synthesizes mouse events from a single finger, which keeps taps,
focus and app-owned pointer handlers working. The missing piece is
panning, so the host enables EnableTouchScrolling: a drag
over scrollable content waits for an eight-pixel slop threshold, locks
to the gesture’s dominant axis and scrolls the nearest container that
can move on that axis. Panning bypasses smooth-scroll easing so the
content tracks the finger. A press that never crosses the threshold is
replayed as a normal click.
Gestures that begin on a scrollbar, text control, range slider, button,
link, media element or an element with a pointerdown
handler keep their existing behaviour. Scrollbar tracks gain a twelve-pixel
inward hit margin on touch hosts, and touching beside the thumb starts a
drag instead of jumping the track.
Long press
A touch press held still for 500 ms becomes a contextmenu
event, so Android gets the same menus as a desktop right-click. Drifting
more than 10 px, starting a drag or starting a scroll pan cancels the
candidate. Once it fires, the click that would normally follow the
release is suppressed, so the menu does not also activate the item under
the finger.
Runtime permissions
AndroidPermissionService translates Donkeh’s portable
HostPermission values into Android manifest permissions:
| Donkeh permission | Android permission(s) |
|---|---|
| Camera | CAMERA |
| Microphone | RECORD_AUDIO |
| Location | ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION |
| Notifications | POST_NOTIFICATIONS on API 33+; pre-33 resolves true |
| Photos | READ_MEDIA_IMAGES on API 33+, otherwise READ_EXTERNAL_STORAGE |
| Storage | READ_MEDIA_IMAGES on API 33+, otherwise read/write external storage |
| Contacts / Calendar | READ_CONTACTS / READ_CALENDAR |
| Bluetooth | BLUETOOTH_CONNECT on API 31+, otherwise legacy BLUETOOTH |
| Motion | ACTIVITY_RECOGNITION on API 29+, otherwise unsupported |
| Clipboard | Resolves immediately; no runtime prompt |
The provider first checks CheckSelfPermission for every required
name and returns immediately when all are granted. Otherwise it allocates a
request code, stores a pending completion in a dictionary, registers
cancellation, and posts RequestPermissions to the UI thread. The
activity forwards OnRequestPermissionsResult back to the
provider, which completes the task and removes the entry.
OnDestroy calls CancelAll, so every pending prompt
resolves false when the activity closes. The app must still declare the
matching uses-permission entries; the framework’s Android
permission targets can emit them from the central
DonkehAndroidPermissions list, and a hand-written manifest can
add more.
INTERNET is added automatically when an app stylesheet
references an external asset. The native host resolves remote
@import rules, their @font-face sources and
url(...) backgrounds at start-up; the build scans the app’s
CSS for http:// or https:// and emits the
permission. This matters for release builds because only debuggable APKs
receive INTERNET implicitly from the Android SDK. Set
DonkehAndroidInternet to true or
false to override detection.
Android versus desktop
| Area | Android behaviour |
|---|---|
| Surface | Activity-owned GLES view; the app does not create a native desktop window. |
| Frame pacing | VSync and a 60 FPS cap, regardless of desktop settings. |
| Chrome and resize | No native title bar, frameless resize handles or window dragging. |
| MSAA | Disabled; the mobile path keeps the surface and bandwidth cost down. |
| Devtools | Disabled by default on this path; the inspector is a desktop tool. |
| Orientation | Activity configuration changes keep the instance; layout reflows on resize. |
| Renderer | GLES 3.0 through the same DonkehWindow, layout and GLRenderer pipeline. |
Trade-offs and sharp edges
| Decision | Cost |
|---|---|
| Framework-owned activity | Zero app boilerplate, but the app cannot subclass or replace the launcher without writing its own host. |
| Reflection into SDL bindings | Keeps the JNI bootstrap working, but a binding rename is a compile-time-adjacent runtime failure. |
| Density with a fallback | Correct CSS pixels on most devices, with a heuristic for SDL builds that already scale the view. |
| Any-of permission result | Practical for paired permissions, but cannot tell the app which individual name failed. |
| Fixed 60 Hz / no MSAA | Predictable thermal and bandwidth behaviour, at the cost of high-refresh devices and smoother edges. |
| Manifest still app-owned | Permissions must be declared as well as requested; a missing manifest entry fails at runtime. |
| No devtools path | Saves layout and renderer overhead on mobile, but debugging happens on desktop or through logging. |
Code tour
| File | Read it for… |
|---|---|
DonkehActivity.cs | Activity attributes, SDL handler seam, app discovery, GLES view setup, settings overrides and DPI fallback. |
AndroidPermissionService.cs | Permission mapping, API-level differences, UI-thread request flow, pending completions and cancellation. |
Donkeh.Windowing.Android.csproj | The net10.0-android target, minimum API and SDK path fallbacks. |
The mental model: Android is not a separate UI stack. It is a thin activity
adapter that owns the surface and permissions, then hands a GLES view to the
same DonkehWindow used on desktop.