# 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 Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `areWidgetsSupported()`
  Returns true when this platform can render home-screen (or desktop) widgets.
  `static void`
  `dispatchAction(String source, String actionId, Map<String,Object> params)`
  Framework/port entry point: delivers a surface action to the app.
  `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.
  `static List<WidgetKind>`
  `getRegisteredKinds()`
  Returns the widget kinds registered so far.
  `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.
  `static void`
  `registerWidgetKind(WidgetKind kind)`
  Declares a widget kind at runtime.
  `static void`
  `reloadWidgets(String kindId)`
  Asks the platform to re-render widgets from their already-published timelines.
  `static void`
  `setActionHandler(SurfaceActionHandler handler)`
  Registers the single handler receiving surface action events on the EDT.
  `static void`
  `setBridge(SurfaceBridge b)`
  Framework/port/test entry point: overrides the bridge resolved from the platform port.

  ### Methods inherited from class Object

  `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## 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