@nativescript/core
Version:
A JavaScript library providing an easy to use api for interacting with iOS and Android platform APIs.
443 lines (442 loc) • 20.8 kB
TypeScript
import { CoreTypes } from '../core-types';
import type { View } from '../ui/core/view';
import type { NavigationEntry } from '../ui/frame/frame-interfaces';
import type { AndroidApplication as AndroidApplicationType, iOSApplication as iOSApplicationType } from '.';
import type { ApplicationEventData, CssChangedEventData, DiscardedErrorEventData, FontScaleChangedEventData, LaunchEventData, OrientationChangedEventData, SystemAppearanceChangedEventData, LayoutDirectionChangedEventData, UnhandledErrorEventData, SceneOpenURLContextsEventData, SceneContinueUserActivityEventData, ScenePerformActionForShortcutItemEventData } from './application-interfaces';
import type { NativeWindow, PrimaryWindowChangedEventData, WindowBase, WindowCloseEventData, WindowContentRequest, WindowContentResolver, WindowOpenEventData, WindowOpenOptions, WindowRole } from '../native-window';
/**
* @deprecated Use `NativeWindowEvents` from `@nativescript/core/native-window` instead.
*/
export declare const SceneEvents: {
/** @deprecated Use `NativeWindowEvents.sceneWillConnect` instead. */
sceneWillConnect: string;
/** @deprecated Use `NativeWindowEvents.sceneDidActivate` instead. */
sceneDidActivate: string;
/** @deprecated Use `NativeWindowEvents.sceneWillResignActive` instead. */
sceneWillResignActive: string;
/** @deprecated Use `NativeWindowEvents.sceneWillEnterForeground` instead. */
sceneWillEnterForeground: string;
/** @deprecated Use `NativeWindowEvents.sceneDidEnterBackground` instead. */
sceneDidEnterBackground: string;
/** @deprecated Use `NativeWindowEvents.sceneDidDisconnect` instead. */
sceneDidDisconnect: string;
/** @deprecated Use the Application 'windowOpen' event and NativeWindow.setContent() instead. */
sceneContentSetup: string;
};
export type SceneEventName = (typeof SceneEvents)[keyof typeof SceneEvents];
interface ApplicationEvents {
off(eventNames: string, callback?: any, thisArg?: any): void;
notify<T = ApplicationEventData>(eventData: T): void;
hasListeners(eventName: string): boolean;
on(eventNames: string, callback: (args: ApplicationEventData) => void, thisArg?: any): void;
/**
* This event is raised when application css is changed.
*/
on(event: 'cssChanged', callback: (args: CssChangedEventData) => void, thisArg?: any): void;
/**
* Event raised then livesync operation is performed.
*/
on(event: 'livesync', callback: (args: ApplicationEventData) => void, thisArg?: any): void;
/**
* This event is raised on application launchEvent.
*/
on(event: 'launch', callback: (args: LaunchEventData) => void, thisArg?: any): void;
/**
* This event is raised once the JS context is initialized.
*/
on(event: 'ready', callback: (args: ApplicationEventData) => void, thisArg?: any): void;
/**
* This event is raised after the application has performed most of its startup actions.
* Its intent is to be suitable for measuring app startup times.
* @experimental
*/
on(event: 'displayed', callback: (args: ApplicationEventData) => void, thisArg?: any): void;
/**
* This event is raised when the Application is suspended.
*/
on(event: 'suspend', callback: (args: ApplicationEventData) => void, thisArg?: any): void;
/**
* This event is raised when the Application is resumed after it has been suspended.
*/
on(event: 'resume', callback: (args: ApplicationEventData) => void, thisArg?: any): void;
/**
* This event is raised when the Application is about to exit.
*
* On Android it is raised when the last window closes; the process may stay alive.
* On iOS it is raised when the process itself terminates.
*/
on(event: 'exit', callback: (args: ApplicationEventData) => void, thisArg?: any): void;
/**
* This event is raised when there is low memory on the target device.
*/
on(event: 'lowMemory', callback: (args: ApplicationEventData) => void, thisArg?: any): void;
/**
* This event is raised when an uncaught error occurs while the application is running.
*/
on(event: 'uncaughtError', callback: (args: UnhandledErrorEventData) => void, thisArg?: any): void;
/**
* This event is raised when an discarded error occurs while the application is running.
*/
on(event: 'discardedError', callback: (args: DiscardedErrorEventData) => void, thisArg?: any): void;
/**
* This event is raised when the orientation of the application changes.
*/
on(event: 'orientationChanged', callback: (args: OrientationChangedEventData) => void, thisArg?: any): void;
/**
* This event is raised when the operating system appearance changes
* between light and dark theme (for Android);
* between light and dark mode (for iOS) and vice versa.
*/
on(event: 'systemAppearanceChanged', callback: (args: SystemAppearanceChangedEventData) => void, thisArg?: any): void;
/**
* This event is raised when the operating system layout direction changes
* between ltr and rtl.
*/
on(event: 'layoutDirectionChanged', callback: (args: LayoutDirectionChangedEventData) => void, thisArg?: any): void;
on(event: 'fontScaleChanged', callback: (args: FontScaleChangedEventData) => void, thisArg?: any): void;
on(event: 'windowOpen', callback: (args: WindowOpenEventData) => void, thisArg?: any): void;
on(event: 'windowClose', callback: (args: WindowCloseEventData) => void, thisArg?: any): void;
on(event: 'primaryWindowChanged', callback: (args: PrimaryWindowChangedEventData) => void, thisArg?: any): void;
on(event: 'sceneOpenURLContexts', callback: (args: SceneOpenURLContextsEventData) => void, thisArg?: any): void;
on(event: 'sceneContinueUserActivity', callback: (args: SceneContinueUserActivityEventData) => void, thisArg?: any): void;
on(event: 'scenePerformActionForShortcutItem', callback: (args: ScenePerformActionForShortcutItemEventData) => void, thisArg?: any): void;
}
export declare class ApplicationCommon {
/**
* @deprecated Use the 'ready' event for application initialization and Application.setWindowContentResolver() to provide window UI. 'launch' continues to fire before the first window's content is created, and its 'root' property is still honored, for backwards compatibility. It never fires for additional windows. In a scene-based app it fires with the first window's content, so a background launch that connects no scene does not raise it.
*/
readonly launchEvent = "launch";
/**
* Raised once per JS context, as soon as the context is initialized. It is never deferred,
* so it also fires on a background launch where no window is created.
*
* Guaranteed ordering: `ready` -> `windowOpen` -> raw connect/create events -> content
* resolution (the legacy `launch` bridge runs here, for the first window only) ->
* `contentLoaded` -> `activate`/`displayed`.
*/
readonly readyEvent = "ready";
/**
* Reflects whole-app state: with multiple windows it is raised once the app itself is
* no longer in the foreground, not when an individual window backgrounds. Listen on a
* NativeWindow for per-window state.
*/
readonly suspendEvent = "suspend";
readonly displayedEvent = "displayed";
readonly backgroundEvent = "background";
readonly foregroundEvent = "foreground";
readonly resumeEvent = "resume";
/**
* On Android, raised when the last window closes; the process may stay alive.
* On iOS, raised when the process itself terminates.
*/
readonly exitEvent = "exit";
readonly lowMemoryEvent = "lowMemory";
readonly uncaughtErrorEvent = "uncaughtError";
readonly discardedErrorEvent = "discardedError";
readonly orientationChangedEvent = "orientationChanged";
readonly systemAppearanceChangedEvent = "systemAppearanceChanged";
readonly layoutDirectionChangedEvent = "layoutDirectionChanged";
readonly fontScaleChangedEvent = "fontScaleChanged";
readonly livesyncEvent = "livesync";
readonly loadAppCssEvent = "loadAppCss";
readonly cssChangedEvent = "cssChanged";
readonly initRootViewEvent = "initRootView";
readonly windowOpenEvent: "windowOpen";
readonly windowCloseEvent: "windowClose";
readonly primaryWindowChangedEvent: "primaryWindowChanged";
/**
* @deprecated Use `Application.android.on()` instead.
*/
static on: ApplicationEvents['on'];
/**
* @deprecated Use `Application.android.once()` instead.
*/
static once: ApplicationEvents['on'];
/**
* @deprecated Use `Application.android.off()` instead.
*/
static off: ApplicationEvents['off'];
/**
* @deprecated Use `Application.android.notify()` instead.
*/
static notify: ApplicationEvents['notify'];
/**
* @deprecated Use `Application.android.hasListeners()` instead.
*/
static hasListeners: ApplicationEvents['hasListeners'];
on: ApplicationEvents['on'];
once: ApplicationEvents['on'];
off: ApplicationEvents['off'];
notify: ApplicationEvents['notify'];
hasListeners: ApplicationEvents['hasListeners'];
private _orientation;
private _systemAppearance;
private _layoutDirection;
private _inBackground;
private _suspended;
private _cssFile;
private _readyNotified;
private _appCssLoaded;
private _launchBridgeConsumed;
private _windowContentResolver;
protected mainEntry: NavigationEntry;
started: boolean;
/**
* Boolean to enable/disable systemAppearanceChanged
*/
get autoSystemAppearanceChanged(): boolean;
set autoSystemAppearanceChanged(value: boolean);
/**
* @internal - should not be constructed by the user.
*/
constructor();
/**
* @internal
*/
livesync(rootView: View, context?: ModuleContext): void;
/**
* Applies the the `newCssClass` to the `rootView` and removes all other css classes from `cssClasses`
* previously applied to the `rootView`.
* @param rootView
* @param cssClasses
* @param newCssClass
* @param skipCssUpdate
*/
applyCssClass(rootView: View, cssClasses: string[], newCssClass: string, skipCssUpdate?: boolean): void;
private addCssClass;
private removeCssClass;
/**
* Same as {@link applyCssClass}, minus the system class list: window-scoped classes
* must not leak into it, because it seeds every window's root view.
*/
private applyWindowScopedCssClass;
/**
* The modal registry is process-wide, so only the modals presented over this root
* view may follow its window-scoped classes.
*/
private getOwnedModalViews;
private increaseStyleScopeApplicationCssSelectorVersion;
private setRootViewCSSClasses;
/**
* iOS Only
* Dynamically change the preferred frame rate
* For devices (iOS 15+) which support min/max/preferred frame rate you can specify ranges
* For devices (iOS < 15), you can specify the max frame rate
* see: https://developer.apple.com/documentation/quartzcore/optimizing_promotion_refresh_rates_for_iphone_13_pro_and_ipad_pro
* To use, ensure your Info.plist has:
* ```xml
* <key>CADisableMinimumFrameDurationOnPhone</key>
* <true/>
* ```
* @param options { min?: number; max?: number; preferred?: number }
*/
setMaxRefreshRate(options?: {
min?: number;
max?: number;
preferred?: number;
}): void;
/**
* @returns The main entry of the application
*/
getMainEntry(): any;
/**
* Sets the callback that supplies the UI for windows that need content.
* Pass `null` to remove a previously set resolver.
*/
setWindowContentResolver(resolver: WindowContentResolver | null): void;
/**
* @returns The callback currently supplying window content, if any.
*/
getWindowContentResolver(): WindowContentResolver | null;
protected _windows: NativeWindow[];
/**
* Get the primary NativeWindow.
*/
get primaryWindow(): NativeWindow | undefined;
/**
* Get the NativeWindow the user is currently interacting with - the one that activated most
* recently and is still attached. Falls back to the primary window while no window holds
* activation, which is the case before the first window activates and on a platform that
* never raises `activate`.
*/
get activeWindow(): NativeWindow | undefined;
/**
* Get the active windows, filtered by role.
*
* Defaults to the view-carrying app windows (`application` and `embedded`).
* Pass `'all'` to include every registered surface, including ones that carry no view tree.
*/
getWindows(role: 'all'): WindowBase[];
getWindows(role?: WindowRole | WindowRole[]): NativeWindow[];
getWindows(role?: WindowRole | WindowRole[] | 'all'): WindowBase[];
/**
* Get a registered NativeWindow by its id.
*/
getWindowById(id: string): NativeWindow | undefined;
/**
* Opens a new window.
*
* @param options Options for the new window, including data to hand to it.
*/
openWindow(options?: WindowOpenOptions): void;
/**
* @internal - Get all registered NativeWindows, whatever their role.
*/
_getWindows(): NativeWindow[];
/**
* @internal - Register a NativeWindow created by the platform lifecycle.
*/
_registerWindow(nativeWindow: NativeWindow): void;
/**
* @internal - retire the windows behind discarded window-session ids.
*
* A session id can only stand in for a window whose native surface is already gone.
* iOS reports sessions discarded while the app was not running on the next launch,
* and such an id can name the session driving the app now, so an id match alone is
* no evidence that the window is finished with. Retiring an attached window tears
* down the UI in use - its root view unloads and nothing ever reloads it - so only
* detached windows are retired. Ids matching no window are ignored: they routinely
* belong to windows this JS context has never seen.
*/
_retireDiscardedWindows(ids: string[]): void;
/**
* @internal - Unregister a NativeWindow when its native surface is gone for good.
*/
_unregisterWindow(nativeWindow: NativeWindow): void;
/**
* Hook for platform-specific bookkeeping right after a window joins the registry,
* before `windowOpen` is raised.
*/
protected _onWindowRegistered(nativeWindow: NativeWindow): void;
/**
* Hook for platform-specific bookkeeping right after a window takes over the primary
* role, before `primaryWindowChanged` is raised.
*/
protected _onPrimaryWindowPromoted(nativeWindow: NativeWindow): void;
private _traitsWindow;
/**
* Points the application-level orientation, appearance and layout direction at the
* primary window, which owns those values now that each window has its own.
*/
private trackPrimaryWindowTraits;
/**
* Adopts the window's values. The very first window seeds them quietly — there is no
* previous application state for it to differ from — while a later promotion raises
* the change events, because app code observed the outgoing window's values.
*/
private syncTraitsFromWindow;
private onWindowActivated;
private onWindowOrientationChanged;
private onWindowSystemAppearanceChanged;
private onWindowLayoutDirectionChanged;
/**
* @internal - raises `ready` at most once per JS context.
*/
notifyReady(): void;
/**
* @internal - produces the content for a window that has none.
*
* Resolution order: the window content resolver, then the legacy `launch` event
* (offered to the first window that asks for content and to no other), then the
* application main entry. A resolver or a `launch` handler returning `null` takes
* ownership of the content, so nothing else is tried. A missing main entry leaves
* the window empty instead of throwing, because content can still arrive later
* through `run()`/`resetRootView()`.
*
* @param options.install `false` returns the resolved view instead of applying it,
* for platform pipelines that install the root view on the native surface themselves.
* @param options.launchData platform payload merged into the legacy `launch` event args.
* @returns The resolved view, or `null` when no content was produced.
*/
_resolveWindowContent(window: NativeWindow, request: WindowContentRequest, options?: {
install?: boolean;
launchData?: any;
}): View | null;
private resolveWindowContent;
private buildContentView;
/**
* Loads the app CSS once per JS context. On the legacy `launch` path this has to run
* after the handlers, which are allowed to call `setCssFileName()`.
*/
private _ensureAppCssLoaded;
protected notifyLaunch(additionalLanchEventData?: any): View | null;
createRootView(view?: View, fireLaunchEvent?: boolean, additionalLanchEventData?: any): View;
getRootView(): View;
resetRootView(entry?: NavigationEntry | string): void;
/**
* @param window the window the root view belongs to. Supplies the window-scoped CSS
* classes; without it they come from the primary window.
*/
initRootView(rootView: View, window?: NativeWindow): void;
/**
* Get application level static resources.
*/
getResources(): any;
/**
* Set application level static resources.
*/
setResources(res: any): void;
/**
* Sets css file name for the application.
*/
setCssFileName(cssFileName: string): void;
/**
* Gets css file name for the application.
*/
getCssFileName(): string;
/**
* Loads immediately the app.css.
* By default the app.css file is loaded shortly after "loaded".
* For the Android snapshot the CSS can be parsed during the snapshot generation,
* as the CSS does not depend on runtime APIs, and loadAppCss will be called explicitly.
*/
loadAppCss(): void;
addCss(cssText: string, attributeScoped?: boolean): void;
run(entry?: string | NavigationEntry): void;
protected getOrientation(): 'portrait' | 'landscape' | 'unknown';
protected setOrientation(value: 'portrait' | 'landscape' | 'unknown'): void;
/**
* @deprecated Use Application.primaryWindow?.orientation() - or the NativeWindow of the relevant view - instead. Continues to reflect the primary window.
*/
orientation(): 'portrait' | 'landscape' | 'unknown';
orientationChanged(rootView: View, newOrientation: 'portrait' | 'landscape' | 'unknown'): void;
getNativeApplication(): any;
hasLaunched(): boolean;
protected getSystemAppearance(): 'dark' | 'light' | null;
protected setSystemAppearance(value: 'dark' | 'light'): void;
/**
* @deprecated Use Application.primaryWindow?.systemAppearance() - or the NativeWindow of the relevant view - instead. Continues to reflect the primary window.
*/
systemAppearance(): 'dark' | 'light' | null;
/**
* enable/disable systemAppearanceChanged
*/
setAutoSystemAppearanceChanged(value: boolean): void;
/**
* Updates root view classes including those of modals
* @param rootView the root view
* @param newSystemAppearance the new appearance change
*/
systemAppearanceChanged(rootView: View, newSystemAppearance: 'dark' | 'light'): void;
protected getLayoutDirection(): CoreTypes.LayoutDirectionType | null;
protected setLayoutDirection(value: CoreTypes.LayoutDirectionType): void;
/**
* @deprecated Use Application.primaryWindow?.layoutDirection() - or the NativeWindow of the relevant view - instead. Continues to reflect the primary window.
*/
layoutDirection(): CoreTypes.LayoutDirectionType | null;
/**
* Updates root view classes including those of modals
* @param rootView the root view
* @param newLayoutDirection the new layout direction change
*/
layoutDirectionChanged(rootView: View, newLayoutDirection: CoreTypes.LayoutDirectionType): void;
get inBackground(): boolean;
setInBackground(value: boolean, additonalData?: any): void;
get suspended(): boolean;
setSuspended(value: boolean, additonalData?: any): void;
get android(): AndroidApplicationType;
get ios(): iOSApplicationType;
get AndroidApplication(): AndroidApplicationType;
get iOSApplication(): iOSApplicationType;
}
export {};