UIWindowScene
UIWindowScene represents one instance of the App's UI, called a scene. Every window of the App belongs to a scene, and the scene determines which screen those windows appear on and whether they are in the foreground or background right now.
A scene is the prerequisite for any UI. A window (UIWindow) must be built on a scene to be shown, and view controllers and views must be put in a window to be shown. Without a scene, the App's code still runs, but nothing can be shown on screen.
Scenes are created and destroyed by the system; the App can't create one itself. When the system has created a scene, it fires the sceneconnect event on application, and the event object's scene property is that scene; when the scene is taken away, it fires scenedisconnect. Once a scene is connected, it can also be read from application.scenes.
Each scene has a session, a UISceneSession, read from session. A scene object may be destroyed and recreated by the system; the session lives longer than the scene object and can be used to store that scene's data.
Inheritance: EventTarget → NSObject → UIResponder → UIScene → UIWindowScene
UIScene is the base class of scenes. It has no usable members of its own and can't be constructed: new UIScene() throws TypeError: Illegal constructor: UIScene cannot be constructed.
For how to rebuild the UI after a scene is destroyed and where to store data, see the guide Creating windows and handling scenes.
Constructor
Can't be created with new. new UIWindowScene() throws TypeError: Illegal constructor: UIWindowScene is created by the runtime, not by new. There are only two ways to get a scene: e.scene from the sceneconnect event, and application.scenes. Scenes can't be subclassed either; see Native classes: no subclassing.
Instance properties
| Property | Description |
|---|---|
activationState read-only | Whether this scene is shown and interactive right now |
session read-only | This scene's session: the scene's persistent identity |
traitCollection read-only | The appearance traits of the whole scene, such as whether Settings is set to dark or light |
isFullScreen read-only | Whether the scene fills the whole screen |
screen read-only | Which screen this scene appears on |
effectiveGeometry read-only | The current geometry: the interface orientation and whether it is locked |
statusBarManager read-only | What the status bar looks like right now |
title | The title shown on the card in the app switcher |
subtitle | The subtitle shown on the card in the app switcher |
Instance methods
| Method | Description |
|---|---|
openURL() | Asks the system to open a URL: go to Safari, dial a number, go to another App |
requestGeometryUpdateWithPreferences() | Asks to rotate the interface to a given orientation |
Events
| Event | When it fires |
|---|---|
inactive | This scene is about to stop being active: about to go to the background, or temporarily interrupted |
background | This scene has entered the background |
foreground | This scene is about to return to the foreground |
active | This scene has become active and the user can interact |
traitchange | The scene's appearance traits changed |
geometrychange | The interface rotated. Dispatched on the spot; listeners run inside the rotation animation |
- Events are not cancelable. Callbacks don't run synchronously at the moment the state changes; they run a little later. See How the runtime works.
- You can also listen for and dispatch events with custom names on a scene, the same as with any
EventTarget. - Connecting and disconnecting scenes are not in this table: they are
sceneconnectandscenedisconnectonapplication.
Number of scenes
How many scenes an App has at the same time depends on the device:
| Device | Number of scenes |
|---|---|
| iPhone | One. There may be one more when an external display is connected |
| iPad | The user can open several windows of the same App, and each window is a scene. Each scene's UI and foreground/background state are independent |
To find out whether the App allows several scenes at once, read application.supportsMultipleScenes. Multiple scenes on iPad are not verified in the simulator.
When there is no scene
In these cases the App's code is running, but no scene is available:
- Right after the App launches, while the script's top level runs. The system creates the scene only after the script finishes, so
application.scenesis an empty array at that point. That's why code that builds the UI can't go at the top level; it goes in thesceneconnectcallback. - After the system destroys the scene. After the App goes to the background, the system can destroy the scene to reclaim memory;
scenedisconnectfires onapplicationthen. - The user closed a window. On iPad, the user can close one of the App's windows from the multitasking view, and the corresponding scene is destroyed.
The last two cases are not verified in the simulator: the system never destroyed a scene during the acceptance tests.
After a scene is destroyed
A destroyed scene doesn't mean the App restarts. The App's process is still there, and so are the JS variables, data, and unfinished network requests. Only that scene and the UI on it are destroyed.
After destruction, these things happen in order:
- The system fires
scenedisconnectonapplication; the event object'ssceneis the destroyed scene. - The runtime stops keeping that scene. If the App's code doesn't keep it either, the scene is garbage-collected together with its windows, view controllers, and all views, and the memory goes back to the system.
- When the user returns to the App, the system creates a new scene object and fires
sceneconnectagain.
The new scene and the old scene are two different objects. Their session represents the same UI: session.persistentIdentifier is the same, and the data stored in session.userInfo is still there. This process comes from the runtime's code and iOS's definition and is not verified in the simulator.
If the App's code stored the scene in a variable outside the callback, or attached it to a long-lived object such as application:
- The old scene is not released. Its windows, view controllers, and all views stay in memory too.
- The old scene is no longer usable. Its windows are no longer shown on screen. New windows built on it aren't shown either. Reading its
activationStategives'unattached'. - No error is reported. Reading and writing the old scene's properties doesn't throw, so this mistake is hard to notice.
Attaching it to application has the worst consequence: application exists for as long as the App runs, so a scene attached to it is never released. Every time the scene is destroyed and recreated, one more copy is left behind. These points are not verified in the simulator.
Scene state and App state
There are two ways to read foreground/background state and two sets of events:
| About what | Reading the state | Events | |
|---|---|---|---|
| Scene level | This one scene | scene.activationState | active / inactive / foreground / background on scene |
| App level | All scenes combined | application.state | The events of the same names on application |
With only one scene, the two sets of events come in pairs. The two states update at different moments. For the same inactive event, the values read in the callback, as measured:
| Event | Read in the callback |
|---|---|
inactive on scene | scene.activationState is 'foregroundInactive', already the new value |
inactive on application | application.state is 'active', still the old value |
To determine "what the state is now" in an event callback, read scene.activationState.
The same scene is always the same object
The same scene is the same object in JS no matter where you got it from, and can be compared with ===. So event listeners attached to a scene are never lost. You can also attach custom properties to a scene, and reading it from elsewhere gives the same ones; see Native classes: custom properties are allowed.
Examples
Observing scene state changes
Starting from a blank App: get the scene, build a window and view controller on it, then listen for the scene's state changes and log a line to the console on each change.
application.addEventListener('sceneconnect', (e) => {
const scene = e.scene;
const win = new UIWindow(scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
for (const type of ['active', 'inactive', 'foreground', 'background']) {
scene.addEventListener(type, (ev) => {
console.log('Scene event:', ev.type, '| State:', scene.activationState);
});
}
});Effect
- A blank view controller appears on screen, with the system background color (white in light mode).
- When the user presses Home to go to the Home Screen, the console logs two lines:
inactive, thenbackground. - When the user switches back to the App, the console logs two lines:
foreground, thenactive.
The first line in full is Scene event: inactive | State: foregroundInactive (measured); the state values in the other three lines are not verified in the simulator. The order inactive → background → foreground → active was measured on the events of the same names on application; the order of the scene events is not verified in the simulator. Whether foreground and active are also logged after the scene connects at App launch is not verified in the simulator.
This code has not been run as a whole in the simulator. Every API it uses has been run in the acceptance tests.
Corresponding iOS API
| ObjC | JS |
|---|---|
scene:willConnectToSession:options: / UISceneWillConnectNotification | application.addEventListener('sceneconnect', (e) => { e.scene }) |
sceneDidDisconnect: / UISceneDidDisconnectNotification | application.addEventListener('scenedisconnect', …) |
sceneDidBecomeActive: / UISceneDidActivateNotification | scene.addEventListener('active', …) |
sceneWillResignActive: / UISceneWillDeactivateNotification | scene.addEventListener('inactive', …) |
sceneWillEnterForeground: / UISceneWillEnterForegroundNotification | scene.addEventListener('foreground', …) |
sceneDidEnterBackground: / UISceneDidEnterBackgroundNotification | scene.addEventListener('background', …) |
UIApplication.sharedApplication.connectedScenes | application.scenes |
scene.activationState == UISceneActivationStateForegroundActive | scene.activationState === 'foregroundActive' |
[[UIWindow alloc] initWithWindowScene:scene] | new UIWindow(scene) |
scene.fullScreen | scene.isFullScreen |
scene.title = @"Inbox" | scene.title = 'Inbox' |
[scene openURL:url options:nil completionHandler:^(BOOL ok){}] | await scene.openURL(url) |
scene.session.persistentIdentifier | scene.session.persistentIdentifier |
scene.session.userInfo = @{ @"kind": @"mailDetail" } | scene.session.userInfo = { kind: 'mailDetail' } |
See also
- Creating windows and handling scenes: the recommended approach, where to store data, foreground and background, sessions
UISceneSession: the scene's sessionapplication: thesceneconnect/scenedisconnectevents, thescenesproperty, and the App-level foreground/background eventsUIWindow: building a window on a scene to make the UI appear- Native classes: which classes can be constructed, can't be subclassed, and accept custom properties