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