Class LiveActivity

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

A running live activity: an ongoing-state surface (delivery, timer, ride, score) presented on the iOS lock screen and Dynamic Island, as an ongoing Android notification, or as a floating pill window on desktop. Start it with a descriptor and an initial state, then push fresh state maps as the situation evolves -- updates ship only the state, the layout is re-interpolated on the surface:

LiveActivity delivery = LiveActivity.start(descriptor, initialState);
...
delivery.update(stateMap("Arriving now", eta, 1.0f));
delivery.end(null);

On platforms without live activity support start(...) returns an inert handle whose methods are safe no-ops (isActive() returns false), so app code needs no platform checks.

  • Method Details

    • isSupported

      public static boolean isSupported()

      Returns true when this platform can present live activities.

      Returns

      true when live activities are supported

    • start

      public static LiveActivity start(LiveActivityDescriptor descriptor, Map<String,Object> initialState)

      Starts a live activity. On unsupported platforms (or when the platform refuses, e.g. the user disabled live activities) this returns an inert handle rather than throwing.

      Threading

      Callable from any thread, and a background thread is the right one. Starting an activity serializes the descriptor, writes its PNG blobs where the platform renderer can reach them and makes a synchronous native request (Activity.request is an XPC round trip on iOS). The simulator makes all of that free, so an app that starts activities on the EDT looks fine there and stalls on hardware; Surfaces.setDiagnosticsEnabled(Boolean) describes the checks that catch it. Note also that the returned handle is the only way to update or end this activity: check isActive() rather than tracking a flag of your own, or a start that the platform refused leaves you starting a second activity on top of a live one.

      Parameters
      • descriptor: the activity layout and regions
      • initialState: the initial state map, may be null
      Returns

      a handle to the running activity; check isActive() to know whether it is live

    • updateRemote

      public static void updateRemote(String id, String stateJson)
      Push-framework entry point that updates an already-running native activity by id.

    • endRemote

      public static void endRemote(String id, String finalStateJson, boolean dismissImmediately)
      Push-framework entry point that ends an already-running native activity by id. finalStateJson may be null to keep the last published state, matching the SurfaceBridge contract.

    • update

      public void update(Map<String,Object> state)

      Pushes a fresh state map to the running activity. A no-op on an inert or ended handle.

      Parameters
      • state: the new state map

    • end

      public void end(Map<String,Object> finalState)

      Ends the activity, optionally showing a final state before the platform dismisses the surface. A no-op on an inert or already-ended handle.

      Parameters
      • finalState: the final state to show, or null to keep the last state

    • end

      public void end(Map<String,Object> finalState, boolean dismissImmediately)

      Ends the activity.

      Parameters
      • finalState: the final state to show, or null to keep the last state
      • dismissImmediately: true to remove the surface right away instead of letting the platform linger on the final state

    • isActive

      public boolean isActive()
      Returns true while the activity is running (false for inert handles and after end).

    • getId

      public String getId()
      Returns the platform id of the activity, or null for inert handles. Action events from this activity carry the descriptor's activity type as their source.