Titanium.App.iOS.SceneProxy

proxyiPhoneiPadmacOSsince 14.0.0

Proxy object representing a UIWindowScene in a multi-scene iOS application.

A SceneProxy provides access to a single UIWindowScene instance and its properties. Scene proxies are obtained via Titanium.App.iOS.currentScene, Titanium.App.iOS.scenes, Titanium.App.iOS.focusedScene, or the <Titanium.UI.Window.scene> property.

Multi-scene support is available on iOS 13 and later. The Titanium SDK includes a default UIApplicationSceneManifest in the generated Info.plist with UIApplicationSupportsMultipleScenes set to true and a single scene configuration named "Default Configuration" with delegate class TiApp.

To add additional scene configurations (e.g., for CarPlay or custom window scenes), add them under the <ios><plist><dict> section in your tiapp.xml:

<ios>
    <plist>
        <dict>
            <key>UIApplicationSceneManifest</key>
            <dict>
                <key>UIApplicationSupportsMultipleScenes</key>
                <true/>
                <key>UISceneConfigurations</key>
                <dict>
                    <key>UIWindowSceneSessionRoleApplication</key>
                    <array>
                        <dict>
                            <key>UISceneConfigurationName</key>
                            [string](api:Global.String)Default Configuration</string>
                            <key>UISceneDelegateClassName</key>
                            [string](api:Global.String)TiApp</string>
                        </dict>
                    </array>
                </dict>
            </dict>
        </dict>
    </plist>
</ios>

In single-scene apps (iOS versions prior to 13.0 or apps without a scene manifest), currentScene returns null and scenes returns an empty array.

Example

// Get the current scene
var scene = Ti.App.iOS.currentScene;
Ti.API.info('Scene ID: ' + scene.sceneId);
Ti.API.info('Scene Name: ' + scene.sceneName);
Ti.API.info('Active: ' + scene.isActive);
Ti.API.info('Foreground: ' + scene.isForeground);
Ti.API.info('Primary: ' + scene.isPrimary);
Ti.API.info('Key (focused): ' + scene.isKey);

// Get trait collection info
var traits = scene.traitCollection;
Ti.API.info('UI Style: ' + traits.userInterfaceStyle);
Ti.API.info('Horizontal Size Class: ' + traits.horizontalSizeClass);
Ti.API.info('Vertical Size Class: ' + traits.verticalSizeClass);

Properties 11

apiName

Stringsince Android 3.2.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0read-only

Inherited from Titanium.Proxy

The name of the API that this proxy corresponds to.

bubbleParent

Booleansince Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0

Inherited from Titanium.Proxy

Indicates if the proxy will bubble an event to its parent.

Default: true

id

Stringsince 14.0.0read-only

The unique identifier of the scene (alias for sceneId).

Convenience accessor that returns the same value as Titanium.App.iOS.SceneProxy.sceneId. This is the persistentIdentifier of the scene's UISceneSession.

isActive

Booleansince 14.0.0read-only

Whether the scene is currently active and receiving input.

Returns true when the scene is in the foreground and receiving events. A scene becomes active when the focus event fires and inactive when the blur fires.

isForeground

Booleansince 14.0.0read-only

Whether the scene is in the foreground (visible but may not be active).

Returns true when the scene is visible on screen, even if it is not the active scene (for example, when a system overlay is shown on top of it). A scene enters the foreground when the resumed event fires and enters the background when paused fires.

isKey

Booleansince 14.0.0read-onlyiOS 13.0+

Whether this scene's window is the one the user is currently interacting with.

Returns true when this scene's window was the last window to receive a touch event. This is the most reliable way to determine which scene has input focus in multi-scene mode (iPad Split View, Slide Over).

Important: In iPad Split View, both scenes report isKeyWindow as true and activationState as foregroundActive simultaneously. The isKey property uses hit-test tracking instead, making it a reliable focus indicator.

For the same information at the module level, use Titanium.App.iOS.focusedScene which returns the focused scene proxy directly.

isPrimary

Booleansince 14.0.0read-only

Whether this scene is the primary (first) scene.

Returns true for the scene that was launched first or is designated as the primary scene in the scene configuration.

sceneId

Stringsince 14.0.0read-only

The unique identifier of the scene.

The persistentIdentifier of the scene's UISceneSession. This value uniquely identifies the scene across its lifetime.

sceneName

Stringsince 14.0.0read-only

The configuration name of the scene.

The name of the UISceneConfiguration used to create this scene. Defaults to "Default Configuration" if no custom name is set.

traitCollection

Dictionarysince 14.0.0read-onlyiOS 13.0+

The trait collection for this scene.

Returns a dictionary with the scene's UITraitCollection properties:

userInterfaceStyle (Number): The user interface style. One of 0 (Unspecified), 1 (Light), or 2 (Dark).
horizontalSizeClass (Number): The horizontal size class. One of 0 (Unspecified), 1 (Compact), or 2 (Regular).
verticalSizeClass (Number): The vertical size class. One of 0 (Unspecified), 1 (Compact), or 2 (Regular).
displayScale (Number): The display scale factor.
layoutDirection (Number): The layout direction. One of 0 (Left to Right), 1 (Right to Left).

Returns null if the scene does not have a window or on iOS versions prior to 13.0.

window

Titanium.UI.Windowsince 14.0.0read-only

The root window proxy for this scene.

Returns the Titanium.UI.Window proxy for the root view controller of this scene. Returns null if the scene does not have a window.

Methods 4

addEventListener

Inherited from Titanium.Proxy

Adds the specified callback as an event listener for the named event.

Parameters
Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

applyProperties

since 3.0.0

Inherited from Titanium.Proxy

Applies the properties to the proxy.

Parameters
Parameters	Type	Description
props	Dictionary	A dictionary of properties to apply.

fireEvent

Inherited from Titanium.Proxy

Fires a synthesized event to any registered listeners.

Parameters
Parameters	Type	Description
name	String	Name of the event.
event?	Dictionary	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

removeEventListener

Inherited from Titanium.Proxy

Removes the specified callback as an event listener for the named event.

Parameters
Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to `addEventListener`. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

Events 4

blur

iPhoneiPadsince 14.0.0iOS 13.0+

Fired when this scene is about to resign the active state.

Fires when the scene is about to lose its active status, for example when a system overlay (like the notification center) covers the scene or when the user switches to another scene. This is the per-scene equivalent of the legacy pause event and mirrors Titanium.UI.Window.blur at the scene level.

Add a listener via scene.addEventListener('blur', fn).

Event properties
Event properties	Type	Description
sceneId	String	The unique identifier of the scene.
scene	Titanium.App.iOS.SceneProxy	The scene proxy that is resigning active.

focus

iPhoneiPadsince 14.0.0iOS 13.0+

Fired when this scene becomes active and can receive user input.

Fires when the scene transitions to the active state, meaning it is in the foreground and receiving user input events. This is the per-scene equivalent of the legacy resumed event and mirrors Titanium.UI.Window.focus at the scene level.

Add a listener via scene.addEventListener('focus', fn). The listener fires only for this scene, not for other scenes in the app.

Event properties
Event properties	Type	Description
sceneId	String	The unique identifier of the scene.
scene	Titanium.App.iOS.SceneProxy	The scene proxy that became active.

paused

iPhoneiPadsince 14.0.0iOS 13.0+

Fired when this scene has entered the background.

Fires when the scene is no longer visible on screen. This can happen when the user switches to another app or when the scene is dismissed. This is the per-scene equivalent of the legacy paused event.

Add a listener via scene.addEventListener('paused', fn).

Event properties
Event properties	Type	Description
sceneId	String	The unique identifier of the scene.
scene	Titanium.App.iOS.SceneProxy	The scene proxy that entered the background.

resumed

iPhoneiPadsince 14.0.0iOS 13.0+

Fired when this scene is about to enter the foreground.

Fires when the scene transitions from the background to the foreground, meaning it becomes visible on screen but may not yet be active. This is the per-scene equivalent of the legacy resume event.

Add a listener via scene.addEventListener('resumed', fn).

Event properties
Event properties	Type	Description
sceneId	String	The unique identifier of the scene.
scene	Titanium.App.iOS.SceneProxy	The scene proxy that is entering the foreground.