package com.codename1.surfaces

External surfaces: home-screen widgets and live activities from one declarative API.

Both features answer the same developer question – how do I keep a live source of information outside my app? – so Codename One models them as one concept. A widget is persistent, user-placed and content-driven (weather, next meeting, delivery status on the home screen). A live activity is transient, app-started and progress-driven (the delivery that is out RIGHT NOW, a running timer, a live score on the iOS lock screen / Dynamic Island, an ongoing Android notification, a floating desktop pill). They share the layout model, the serialization, the state mechanism and the action model.

The dead-process rule

Surfaces render while your app process may not be running. Everything you hand this API is therefore turned into plain data at publish time: layouts serialize to a compact JSON descriptor, images are encoded to named PNG blobs, and “callbacks” are string action ids that open the app and are delivered to your SurfaceActionHandler on the EDT (queued across a cold start). Layout text embeds ${key} placeholders resolved from a per-entry state map, so content changes are cheap re-publishes of data, not layouts.

The layout model

A small sealed catalog of nodes every platform can render natively – SurfaceColumn, SurfaceRow, SurfaceBox, SurfaceText, SurfaceDynamicText, SurfaceImage, SurfaceProgress, SurfaceVector, SurfaceSpacer – with shared styling (padding, background, corner radius, alignment, weight, size, action). SurfaceDynamicText is the headline feature: countdowns and elapsed-time text the OS animates on its own clock, so a delivery ETA ticks every second with zero app wakeups. SurfaceVector covers the widgets the template catalog cannot express – clocks, gauges, dials – with a retained list of vector drawing ops (fills, strokes, arcs, text, rotation groups) replayed natively by every renderer.

The lowest common denominator contract

Android app widgets (RemoteViews) are the constrained platform; the catalog is designed to its floor and degrades as follows:

Descriptors are limited to 8 nesting levels; keep payloads (JSON + images) comfortably under 200kb – the iOS widget extension runs in about 30mb of memory and Android parcels rendered widgets over a 1mb binder transaction.

Example: an analog clock widget

A SurfaceVector face plus per-minute timeline entries driving the hand angles. Angles use the clock convention (degrees, 0 = 12 o’clock, clockwise positive); the OS flips the entries on schedule, so the clock stays correct for an hour with zero app wakeups:

SurfaceVector face = new SurfaceVector(200, 200)
        .fillEllipse(100, 100, 96, 96, SurfaceColor.BACKGROUND)
        .beginRotation("hourAngle", 100, 100)
            .line(100, 100, 100, 52, 8, SurfaceColor.LABEL).endRotation()
        .beginRotation("minuteAngle", 100, 100)
            .line(100, 100, 100, 24, 5, SurfaceColor.ACCENT).endRotation();
WidgetTimeline t = new WidgetTimeline().setContent(face);
for (int m = 0; m < 60; m++) {
    int totalMinutes = hourOfDay * 60 + minute + m;
    Map<String, Object> state = new HashMap<String, Object>();
    state.put("minuteAngle", totalMinutes % 60 * 6f);
    state.put("hourAngle", totalMinutes % 720 * 0.5f);
    t.addEntry(new Date(minuteStart + m * 60000L), state);
}
Surfaces.publish("analog_clock", t);

Build-time manifest: surfaces.json

Platform widget galleries are compiled into the native app, so widget kinds must be known at build time. Keep a surfaces.json in your project resources (next to your icons) mirroring your runtime WidgetKind registrations:

{
  "liveActivities": true,
  "kinds": [
    { "id": "delivery_status", "name": "Delivery", "description": "Track your order",
      "iosFamilies": ["systemSmall", "systemMedium"] }
  ]
}

Refresh and updates

This version updates surfaces from the running app: publish a WidgetTimeline of dated entries (the OS flips entries on schedule without waking you), implement com.codename1.background.BackgroundFetch to re-publish periodically, and push live activity state with LiveActivity.update(...). Push-driven updates (server-sent widget content and ActivityKit push tokens) are planned; the wire format already accommodates them.

Zero cost when unused

Referencing this package makes the build inject the native plumbing (WidgetKit extension and app group on iOS, widget receivers on Android). Apps that never touch it get none of it. On unsupported ports every entry point is an inert no-op.