Package com.vaadin.flow.component.screenorientation

Class ScreenOrientation

java.lang.Object

com.vaadin.flow.component.screenorientation.ScreenOrientation

All Implemented Interfaces:

Serializable

public final class ScreenOrientation
extends Object
implements Serializable

Entry point for the browser Screen Orientation API.

To observe the current orientation, subscribe to orientationSignal(). To pin the screen to a particular orientation for as long as the user stays on the current page, call lock(com.vaadin.flow.component.screenorientation.ScreenOrientationType) (most browsers require fullscreen first); release it again with unlock().

 Div portraitHint = new Div("Rotate your device to landscape");
 portraitHint.bindVisible(ScreenOrientation.orientationSignal()
         .map(data -> data.type().isPortrait()));

 ScreenOrientation.lock(ScreenOrientationType.LANDSCAPE_PRIMARY);
 

All methods operate on the current UI; the no-UI overloads require a current UI to be available on the calling thread.

Since:

25.2

See Also:

• Serialized Form

Method Summary

Modifier and Type	Method	Description
static void	lock(ScreenOrientationType orientation)	Locks the screen orientation to the given type for as long as the user remains on the current page.
static void	lock(ScreenOrientationType orientation, SerializableRunnable onSuccess, SerializableConsumer<ScreenOrientationLockError> onError)	Locks the screen orientation to the given type and notifies the matching callback when the browser resolves the request.
static Signal<ScreenOrientationData>	orientationSignal()	Returns a read-only signal that tracks the current screen orientation and its rotation angle for the current UI.
static Signal<ScreenOrientationData>	orientationSignal(UI ui)	Returns the read-only screen orientation signal for the given UI.
static void	unlock()	Releases a previous lock, allowing the screen to follow the device orientation again.
static void	unlock(SerializableRunnable onComplete)	Releases a previous lock and notifies the given callback after the browser has applied the unlock.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

orientationSignal

public static Signal<ScreenOrientationData> orientationSignal()

Returns a read-only signal that tracks the current screen orientation and its rotation angle for the current UI.

The signal is seeded from the initial client bootstrap, so user code always sees a real value when the browser supports the Screen Orientation API. Browsers that do not implement the API report ScreenOrientationType.UNSUPPORTED after bootstrap; the initial value before bootstrap is ScreenOrientationType.UNKNOWN. Once a real value has arrived, the signal never returns to UNKNOWN.

Bind it to a component to keep the UI in sync, e.g. hint.bindVisible(orientationSignal().map(data -> data.type().isPortrait())); call orientationSignal().peek() for a snapshot outside a reactive context, and .get() inside one.

Returns:

the read-only screen orientation signal for the current UI

Throws:

IllegalStateException - if there is no current UI

orientationSignal

public static Signal<ScreenOrientationData> orientationSignal(UI ui)

Returns the read-only screen orientation signal for the given UI. Same as orientationSignal() but without relying on the thread-bound current UI ? useful from framework code such as the bootstrap path.

Parameters:

ui - the UI whose orientation signal to return, not null

Returns:

the read-only screen orientation signal for ui

lock

public static void lock(ScreenOrientationType orientation)

Locks the screen orientation to the given type for as long as the user remains on the current page. Most browsers require the document to be in fullscreen mode, and locking is generally only honored on devices where a physical orientation actually exists (mobile, tablet).

This overload is fire-and-forget: failures are logged at DEBUG but not otherwise surfaced. Use lock(ScreenOrientationType, SerializableRunnable, SerializableConsumer) to react to success or to the specific lock error.

Parameters:

orientation - the orientation to lock to, not null and not ScreenOrientationType.UNKNOWN or ScreenOrientationType.UNSUPPORTED

Throws:

IllegalArgumentException - if orientation is ScreenOrientationType.UNKNOWN or ScreenOrientationType.UNSUPPORTED

IllegalStateException - if there is no current UI

lock

public static void lock(ScreenOrientationType orientation,
 SerializableRunnable onSuccess,
 SerializableConsumer<ScreenOrientationLockError> onError)

Locks the screen orientation to the given type and notifies the matching callback when the browser resolves the request. Mirrors the Geolocation.getPosition pattern so applications can bind UI to lock success and failure without having to write JavaScript glue.

The browser dispatches exactly one of the two callbacks on the UI thread. A lock typically requires fullscreen and a device that physically rotates ? see ScreenOrientationLockErrorCode for the failure reasons you can expect.

Parameters:

orientation - the orientation to lock to, not null and not ScreenOrientationType.UNKNOWN or ScreenOrientationType.UNSUPPORTED

onSuccess - invoked when the browser confirms the lock; not null

onError - invoked when the browser rejects the request, or when the Screen Orientation API is not available; not null

Throws:

IllegalArgumentException - if orientation is ScreenOrientationType.UNKNOWN or ScreenOrientationType.UNSUPPORTED

IllegalStateException - if there is no current UI

unlock

public static void unlock()

Releases a previous lock, allowing the screen to follow the device orientation again. A no-op on browsers that do not implement the Screen Orientation API.

Fire-and-forget: use unlock(SerializableRunnable) to be notified when the browser has applied the unlock.

Throws:

IllegalStateException - if there is no current UI

unlock

public static void unlock(SerializableRunnable onComplete)

Releases a previous lock and notifies the given callback after the browser has applied the unlock. A no-op (but the callback still fires) on browsers that do not implement the Screen Orientation API.

Mirrors the callback shape of lock(ScreenOrientationType, SerializableRunnable, SerializableConsumer) so cleanup flows ("leaving fullscreen ? am I fully unlocked yet?") can be sequenced reactively rather than assuming the unlock has landed.

Parameters:

onComplete - invoked on the UI thread once the unlock round-trip has completed; not null

Throws:

IllegalStateException - if there is no current UI