Class Surfaces

java.lang.Object
com.codename1.surfaces.Surfaces
public final class Surfaces extends Object

The static entry point for external surfaces: home-screen widgets and live activities -- the two faces of one concept, a live source of information that resides outside your app. Declare your widget kinds and register an action handler in init(), then publish content whenever your data changes:

Surfaces.registerWidgetKind(new WidgetKind("delivery_status")
        .setDisplayName("Delivery").setDescription("Track your order"));
Surfaces.setActionHandler(evt -> showOrder(evt.getParams()));
...
Surfaces.publish("delivery_status", new WidgetTimeline()
        .setContent(layout).addEntry(new Date(), state));
How surfaces render

Surfaces render while your app process may be dead: the published timeline is serialized (a JSON descriptor plus PNG blobs) and persisted where the platform renderer can reach it -- the iOS widget extension, the Android widget provider or a desktop surface window. Layouts embed ${key} placeholders resolved from each timeline entry's state map, and SurfaceDynamicText countdowns tick natively on the OS clock with no app wakeups. To refresh content periodically implement com.codename1.background.BackgroundFetch and re-publish there.

Widget kinds must also be declared at build time in the project's surfaces.json resource -- the platform widget galleries are compiled into the native app. See the package documentation.

Zero cost when unused

Merely referencing this package makes the build inject the native plumbing (the WidgetKit extension and app group on iOS, the widget receivers on Android). Apps that never touch com.codename1.surfaces get none of it. On the simulator the Widgets preview window renders published surfaces; on unsupported ports the API is an inert no-op.

  • Method Details

    • areWidgetsSupported

      public static boolean areWidgetsSupported()

      Returns true when this platform can render home-screen (or desktop) widgets.

      Returns

      true when widgets are supported

    • registerWidgetKind

      public static void registerWidgetKind(WidgetKind kind)

      Declares a widget kind at runtime. Call once per kind, typically from init(). The id must match a kind declared in the project's surfaces.json build-time manifest; a mismatch logs a prominent warning on supporting platforms.

      Parameters
      • kind: the kind declaration

    • getRegisteredKinds

      public static List<WidgetKind> getRegisteredKinds()
      Returns the widget kinds registered so far.

    • publish

      public static void publish(String kindId, WidgetTimeline timeline)

      Publishes a widget kind's content, atomically replacing any previously published timeline and asking the platform to re-render the kind's widget instances. A no-op on platforms without widget support.

      Threading

      Callable from any thread -- including com.codename1.background.BackgroundFetch#performBackgroundFetch(long, com.codename1.util.Callback) callbacks while the app UI is not running (on Android the fetch runs in a background service with no Activity at all). Publishing is data-only: the timeline is serialized, persisted where the platform renderer can reach it and the renderer is poked asynchronously; no step blocks on the EDT or the platform UI thread. Implementing background fetch and re-publishing there is the intended way to keep widgets fresh; see the com.codename1.surfaces.spi package documentation for the per-platform background update story.

      Parameters
      • kindId: the widget kind id
      • timeline: the content to publish

    • reloadWidgets

      public static void reloadWidgets(String kindId)

      Asks the platform to re-render widgets from their already-published timelines.

      Parameters
      • kindId: the kind to reload, or null for all kinds

    • getInstalledWidgetCount

      public static int getInstalledWidgetCount(String kindId)

      Returns the number of widget instances of a kind the user placed on the platform surface, or 0 when none exist or the platform cannot tell. Useful to skip publishing work when no widget is installed.

      Parameters
      • kindId: the widget kind id
      Returns

      the installed instance count, or 0

    • setActionHandler

      public static void setActionHandler(SurfaceActionHandler handler)

      Registers the single handler receiving surface action events on the EDT. Registration flushes any actions queued before it (e.g. the tap that cold-started the app), in arrival order, with their cold-start flag set.

      Parameters
      • handler: the handler, or null to clear

    • dispatchAction

      public static void dispatchAction(String source, String actionId, Map<String,Object> params)

      Framework/port entry point: delivers a surface action to the app. Ports call this after decoding their platform payload (deep link, intent extras, window click). Handles EDT marshaling; when no handler is registered yet the event is queued and flagged cold start.

      Parameters
      • source: the widget kind id or live activity type
      • actionId: the action id of the tapped node
      • params: the action parameters, may be null

    • setBridge

      public static void setBridge(SurfaceBridge b)

      Framework/port/test entry point: overrides the bridge resolved from the platform port. Passing null restores platform resolution.

      Parameters
      • b: the bridge, or null to resolve from the platform again