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.

Methods

`public abstract boolean areWidgetsSupported()`	Returns true when this port can render home-screen (or desktop) widgets.
`public abstract boolean isLiveActivitySupported()`	Returns true when this port can present live activities (ongoing-state surfaces).
`public abstract 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.
`public abstract 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.
`public abstract void reloadWidgets(String kindId)`	Asks the platform to re-render widget instances from their persisted timelines.
`public abstract 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.
`public abstract` `String startLiveActivity(String descriptorJson, Map<String, byte[]> images)`	Starts a live activity.
`public abstract void updateLiveActivity(String activityId, String stateJson)`	Updates a running live activity with a fresh state map; the platform re-interpolates the existing layout locally.
`public abstract void endLiveActivity(String activityId, String finalStateJson, boolean dismissImmediately)`	Ends a live activity.

Method details

areWidgetsSupported

public abstract boolean areWidgetsSupported()

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

isLiveActivitySupported

public abstract boolean isLiveActivitySupported()

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

registerWidgetKind

public abstract 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 String: the serialized kind declaration

publishWidgetTimeline

public abstract 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 String: the widget kind id
timelineJson String: the serialized timeline (layouts, entries, image names)
images Map<String, byte[]>: PNG blobs keyed by registered name; may be empty, never null

reloadWidgets

public abstract void reloadWidgets(String kindId)

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

Parameters

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

getInstalledWidgetCount

public abstract 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 String: the widget kind id

startLiveActivity

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

Starts a live activity.

Parameters

descriptorJson String: the serialized descriptor including the initial state
images Map<String, byte[]>: 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

public abstract 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 String: the id returned from startLiveActivity
stateJson String: the serialized state map

endLiveActivity

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

Ends a live activity.

Parameters

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