# Interface SurfaceBridge

public interface SurfaceBridge

The platform seam of the external surfaces framework, implemented by ports and returned from `CodenameOneImplementation.getSurfaceBridge()` (null on unsupported ports, making the whole public API an inert no-op).

Everything crosses this boundary as data -- JSON strings produced by the core serializer plus named PNG blobs -- never as live model objects, because surfaces render while the app process may be dead. Implementations MUST persist published payloads (shared container, files dir, preferences) so the platform renderer can re-render them without the app running.

Action events travel in the opposite direction: the port decodes its platform payload (deep link, intent extras, window click) and calls `com.codename1.surfaces.Surfaces.dispatchAction`, which handles EDT marshaling and cold-start queuing.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `areWidgetsSupported()`
  Returns true when this port can render home-screen (or desktop) widgets.
  `void`
  `endLiveActivity(String activityId, String finalStateJson, boolean dismissImmediately)`
  Ends a live activity.
  `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.
  `boolean`
  `isLiveActivitySupported()`
  Returns true when this port can present live activities (ongoing-state surfaces).
  `void`
  `publishWidgetTimeline(String kindId, String timelineJson, Map<String,byte[]> images)`
  Atomically replaces the persisted timeline of a widget kind and asks the platform to re-render its widget instances.
  `void`
  `registerWidgetKind(String kindJson)`
  Notifies the port of a runtime widget kind registration, letting it validate the kind against what was compiled into the native app and prepare storage.
  `void`
  `reloadWidgets(String kindId)`
  Asks the platform to re-render widget instances from their persisted timelines.
  `String`
  `startLiveActivity(String descriptorJson, Map<String,byte[]> images)`
  Starts a live activity.
  `void`
  `updateLiveActivity(String activityId, String stateJson)`
  Updates a running live activity with a fresh state map; the platform re-interpolates the existing layout locally.

- ## Method Details

  - ### areWidgetsSupported

    boolean areWidgetsSupported()
    Returns true when this port can render home-screen (or desktop) widgets.

  - ### isLiveActivitySupported

    boolean isLiveActivitySupported()
    Returns true when this port can present live activities (ongoing-state surfaces).

  - ### registerWidgetKind

    void registerWidgetKind(String kindJson)

    Notifies the port of a runtime widget kind registration, letting it validate the kind against what was compiled into the native app and prepare storage.

    ###### Parameters

    - `kindJson`: the serialized kind declaration

  - ### publishWidgetTimeline

    void publishWidgetTimeline(String kindId, String timelineJson, Map<String,byte[]> images)

    Atomically replaces the persisted timeline of a widget kind and asks the platform to re-render its widget instances.

    ###### Parameters

    - `kindId`: the widget kind id
    - `timelineJson`: the serialized timeline (layouts, entries, image names)
    - `images`: PNG blobs keyed by registered name; may be empty, never null

  - ### reloadWidgets

    void reloadWidgets(String kindId)

    Asks the platform to re-render widget instances from their persisted timelines.

    ###### Parameters

    - `kindId`: the widget kind to reload, or null for all kinds

  - ### getInstalledWidgetCount

    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.

    ###### Parameters

    - `kindId`: the widget kind id

  - ### startLiveActivity

    String startLiveActivity(String descriptorJson, Map<String,byte[]> images)

    Starts a live activity.

    ###### Parameters

    - `descriptorJson`: the serialized descriptor including the initial state
    - `images`: PNG blobs keyed by registered name; may be empty, never null

    ###### Returns

    a platform id for the running activity, or null when starting failed

  - ### updateLiveActivity

    void updateLiveActivity(String activityId, String stateJson)

    Updates a running live activity with a fresh state map; the platform re-interpolates the existing layout locally.

    ###### Parameters

    - `activityId`: the id returned from `startLiveActivity`
    - `stateJson`: the serialized state map

  - ### endLiveActivity

    void endLiveActivity(String activityId, String finalStateJson, boolean dismissImmediately)

    Ends a live activity.

    ###### Parameters

    - `activityId`: the id returned from `startLiveActivity`
    - `finalStateJson`: an optional final state shown before dismissal, or null
    - `dismissImmediately`: true to remove the surface right away instead of letting the platform linger on the final state