public final class Surfaces

Overrides whether the simulator-only surface diagnostics run. They are on in the simulator and off everywhere else, which is almost always what you want: they catch usage that works in the simulator but stalls or silently does nothing on a device (rasterizing a surface image on the EDT, publishing to a kind that was never registered, republishing far past the platform’s reload budget), and they cost nothing in a shipped build because they never run there. Diagnostics that are certain to misbehave on a device throw IllegalStateException; the rest log a one-time warning.

Pass null to restore the default behaviour. Turning them off is a last resort for a case a check gets wrong – please report it if you hit one.

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

A background thread is the RIGHT thread, not merely a permitted one. On a device this writes the payload into the shared container and makes a synchronous native call, and any SurfaceImage holding an Image that is not an EncodedImage is rasterized here – on iOS that encode blocks the caller on the platform UI thread while the pixels are read back off the GPU. Publishing on the EDT therefore stalls the UI on hardware while looking instantaneous in the simulator. Pass EncodedImages and publish off the EDT; the simulator diagnostics flag both mistakes (see setDiagnosticsEnabled(Boolean)).

Push-framework entry point for a server-rendered timeline descriptor. The descriptor uses the same wire format as publish(). The descriptor is persisted directly once the Codename One runtime receives it. A platform that doesn’t run application code for a background push applies it when the application next starts or resumes.

Equivalent to publishRemote(String,String,Map) with no imagery. A descriptor that references an image by name renders a gap where it should be, so prefer the overload whenever the artwork travelled with the descriptor.

As publishRemote(String,String), with the imagery the descriptor references.

A timeline’s node tree names its images rather than embedding them – SurfaceSerializer hashes the bytes and puts the hash on the wire – so a descriptor that arrived from somewhere else is only complete if its side-map arrived too. Without this overload publishRemote discarded the imagery unconditionally and every referenced image rendered as a gap.

The two callers are a server push and the phone-to-watch mirror, which forwards a phone-side publish() of a watch-bearing kind to the watch. Both are the same operation: a descriptor produced elsewhere, applied here.