UNPKG

electron

Version:

Build cross platform desktop apps with JavaScript, HTML, and CSS

891 lines (883 loc) • 1.05 MB
// Type definitions for Electron 37.2.0 // Project: http://electronjs.org/ // Definitions by: The Electron Team <https://github.com/electron/electron> // Definitions: https://github.com/electron/typescript-definitions /// <reference types="node" /> type DOMEvent = Event; type GlobalResponse = Response; type GlobalRequest = Request; declare namespace Electron { const NodeEventEmitter: typeof import('events').EventEmitter; type Accelerator = string; type Event<Params extends object = {}> = { preventDefault: () => void; readonly defaultPrevented: boolean; } & Params; interface App extends NodeJS.EventEmitter { // Docs: https://electronjs.org/docs/api/app /** * Emitted when Chrome's accessibility support changes. This event fires when * assistive technologies, such as screen readers, are enabled or disabled. See * https://www.chromium.org/developers/design-documents/accessibility for more * details. * * @platform darwin,win32 */ on(event: 'accessibility-support-changed', listener: (event: Event, /** * `true` when Chrome's accessibility support is enabled, `false` otherwise. */ accessibilitySupportEnabled: boolean) => void): this; /** * @platform darwin,win32 */ off(event: 'accessibility-support-changed', listener: (event: Event, /** * `true` when Chrome's accessibility support is enabled, `false` otherwise. */ accessibilitySupportEnabled: boolean) => void): this; /** * @platform darwin,win32 */ once(event: 'accessibility-support-changed', listener: (event: Event, /** * `true` when Chrome's accessibility support is enabled, `false` otherwise. */ accessibilitySupportEnabled: boolean) => void): this; /** * @platform darwin,win32 */ addListener(event: 'accessibility-support-changed', listener: (event: Event, /** * `true` when Chrome's accessibility support is enabled, `false` otherwise. */ accessibilitySupportEnabled: boolean) => void): this; /** * @platform darwin,win32 */ removeListener(event: 'accessibility-support-changed', listener: (event: Event, /** * `true` when Chrome's accessibility support is enabled, `false` otherwise. */ accessibilitySupportEnabled: boolean) => void): this; /** * Emitted when the application is activated. Various actions can trigger this * event, such as launching the application for the first time, attempting to * re-launch the application when it's already running, or clicking on the * application's dock or taskbar icon. * * @platform darwin */ on(event: 'activate', listener: (event: Event, hasVisibleWindows: boolean) => void): this; /** * @platform darwin */ off(event: 'activate', listener: (event: Event, hasVisibleWindows: boolean) => void): this; /** * @platform darwin */ once(event: 'activate', listener: (event: Event, hasVisibleWindows: boolean) => void): this; /** * @platform darwin */ addListener(event: 'activate', listener: (event: Event, hasVisibleWindows: boolean) => void): this; /** * @platform darwin */ removeListener(event: 'activate', listener: (event: Event, hasVisibleWindows: boolean) => void): this; /** * Emitted during Handoff after an activity from this device was successfully * resumed on another one. * * @platform darwin */ on(event: 'activity-was-continued', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity. */ userInfo: unknown) => void): this; /** * @platform darwin */ off(event: 'activity-was-continued', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity. */ userInfo: unknown) => void): this; /** * @platform darwin */ once(event: 'activity-was-continued', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity. */ userInfo: unknown) => void): this; /** * @platform darwin */ addListener(event: 'activity-was-continued', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity. */ userInfo: unknown) => void): this; /** * @platform darwin */ removeListener(event: 'activity-was-continued', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity. */ userInfo: unknown) => void): this; /** * Emitted before the application starts closing its windows. Calling * `event.preventDefault()` will prevent the default behavior, which is terminating * the application. * * > [!NOTE] If application quit was initiated by `autoUpdater.quitAndInstall()`, * then `before-quit` is emitted _after_ emitting `close` event on all windows and * closing them. * * > [!NOTE] On Windows, this event will not be emitted if the app is closed due to * a shutdown/restart of the system or a user logout. */ on(event: 'before-quit', listener: (event: Event) => void): this; off(event: 'before-quit', listener: (event: Event) => void): this; once(event: 'before-quit', listener: (event: Event) => void): this; addListener(event: 'before-quit', listener: (event: Event) => void): this; removeListener(event: 'before-quit', listener: (event: Event) => void): this; /** * Emitted when a browserWindow gets blurred. */ on(event: 'browser-window-blur', listener: (event: Event, window: BrowserWindow) => void): this; off(event: 'browser-window-blur', listener: (event: Event, window: BrowserWindow) => void): this; once(event: 'browser-window-blur', listener: (event: Event, window: BrowserWindow) => void): this; addListener(event: 'browser-window-blur', listener: (event: Event, window: BrowserWindow) => void): this; removeListener(event: 'browser-window-blur', listener: (event: Event, window: BrowserWindow) => void): this; /** * Emitted when a new browserWindow is created. */ on(event: 'browser-window-created', listener: (event: Event, window: BrowserWindow) => void): this; off(event: 'browser-window-created', listener: (event: Event, window: BrowserWindow) => void): this; once(event: 'browser-window-created', listener: (event: Event, window: BrowserWindow) => void): this; addListener(event: 'browser-window-created', listener: (event: Event, window: BrowserWindow) => void): this; removeListener(event: 'browser-window-created', listener: (event: Event, window: BrowserWindow) => void): this; /** * Emitted when a browserWindow gets focused. */ on(event: 'browser-window-focus', listener: (event: Event, window: BrowserWindow) => void): this; off(event: 'browser-window-focus', listener: (event: Event, window: BrowserWindow) => void): this; once(event: 'browser-window-focus', listener: (event: Event, window: BrowserWindow) => void): this; addListener(event: 'browser-window-focus', listener: (event: Event, window: BrowserWindow) => void): this; removeListener(event: 'browser-window-focus', listener: (event: Event, window: BrowserWindow) => void): this; /** * Emitted when failed to verify the `certificate` for `url`, to trust the * certificate you should prevent the default behavior with * `event.preventDefault()` and call `callback(true)`. */ on(event: 'certificate-error', listener: (event: Event, webContents: WebContents, url: string, /** * The error code */ error: string, certificate: Certificate, callback: (isTrusted: boolean) => void, isMainFrame: boolean) => void): this; off(event: 'certificate-error', listener: (event: Event, webContents: WebContents, url: string, /** * The error code */ error: string, certificate: Certificate, callback: (isTrusted: boolean) => void, isMainFrame: boolean) => void): this; once(event: 'certificate-error', listener: (event: Event, webContents: WebContents, url: string, /** * The error code */ error: string, certificate: Certificate, callback: (isTrusted: boolean) => void, isMainFrame: boolean) => void): this; addListener(event: 'certificate-error', listener: (event: Event, webContents: WebContents, url: string, /** * The error code */ error: string, certificate: Certificate, callback: (isTrusted: boolean) => void, isMainFrame: boolean) => void): this; removeListener(event: 'certificate-error', listener: (event: Event, webContents: WebContents, url: string, /** * The error code */ error: string, certificate: Certificate, callback: (isTrusted: boolean) => void, isMainFrame: boolean) => void): this; /** * Emitted when the child process unexpectedly disappears. This is normally because * it was crashed or killed. It does not include renderer processes. */ on(event: 'child-process-gone', listener: (event: Event, details: Details) => void): this; off(event: 'child-process-gone', listener: (event: Event, details: Details) => void): this; once(event: 'child-process-gone', listener: (event: Event, details: Details) => void): this; addListener(event: 'child-process-gone', listener: (event: Event, details: Details) => void): this; removeListener(event: 'child-process-gone', listener: (event: Event, details: Details) => void): this; /** * Emitted during Handoff when an activity from a different device wants to be * resumed. You should call `event.preventDefault()` if you want to handle this * event. * * A user activity can be continued only in an app that has the same developer Team * ID as the activity's source app and that supports the activity's type. Supported * activity types are specified in the app's `Info.plist` under the * `NSUserActivityTypes` key. * * @platform darwin */ on(event: 'continue-activity', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity on another device. */ userInfo: unknown, details: ContinueActivityDetails) => void): this; /** * @platform darwin */ off(event: 'continue-activity', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity on another device. */ userInfo: unknown, details: ContinueActivityDetails) => void): this; /** * @platform darwin */ once(event: 'continue-activity', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity on another device. */ userInfo: unknown, details: ContinueActivityDetails) => void): this; /** * @platform darwin */ addListener(event: 'continue-activity', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity on another device. */ userInfo: unknown, details: ContinueActivityDetails) => void): this; /** * @platform darwin */ removeListener(event: 'continue-activity', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity on another device. */ userInfo: unknown, details: ContinueActivityDetails) => void): this; /** * Emitted during Handoff when an activity from a different device fails to be * resumed. * * @platform darwin */ on(event: 'continue-activity-error', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * A string with the error's localized description. */ error: string) => void): this; /** * @platform darwin */ off(event: 'continue-activity-error', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * A string with the error's localized description. */ error: string) => void): this; /** * @platform darwin */ once(event: 'continue-activity-error', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * A string with the error's localized description. */ error: string) => void): this; /** * @platform darwin */ addListener(event: 'continue-activity-error', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * A string with the error's localized description. */ error: string) => void): this; /** * @platform darwin */ removeListener(event: 'continue-activity-error', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * A string with the error's localized description. */ error: string) => void): this; /** * Emitted when the application becomes active. This differs from the `activate` * event in that `did-become-active` is emitted every time the app becomes active, * not only when Dock icon is clicked or application is re-launched. It is also * emitted when a user switches to the app via the macOS App Switcher. * * @platform darwin */ on(event: 'did-become-active', listener: (event: Event) => void): this; /** * @platform darwin */ off(event: 'did-become-active', listener: (event: Event) => void): this; /** * @platform darwin */ once(event: 'did-become-active', listener: (event: Event) => void): this; /** * @platform darwin */ addListener(event: 'did-become-active', listener: (event: Event) => void): this; /** * @platform darwin */ removeListener(event: 'did-become-active', listener: (event: Event) => void): this; /** * Emitted when the app is no longer active and doesn’t have focus. This can be * triggered, for example, by clicking on another application or by using the macOS * App Switcher to switch to another application. * * @platform darwin */ on(event: 'did-resign-active', listener: (event: Event) => void): this; /** * @platform darwin */ off(event: 'did-resign-active', listener: (event: Event) => void): this; /** * @platform darwin */ once(event: 'did-resign-active', listener: (event: Event) => void): this; /** * @platform darwin */ addListener(event: 'did-resign-active', listener: (event: Event) => void): this; /** * @platform darwin */ removeListener(event: 'did-resign-active', listener: (event: Event) => void): this; /** * Emitted whenever there is a GPU info update. */ on(event: 'gpu-info-update', listener: () => void): this; off(event: 'gpu-info-update', listener: () => void): this; once(event: 'gpu-info-update', listener: () => void): this; addListener(event: 'gpu-info-update', listener: () => void): this; removeListener(event: 'gpu-info-update', listener: () => void): this; /** * Emitted when `webContents` or Utility process wants to do basic auth. * * The default behavior is to cancel all authentications. To override this you * should prevent the default behavior with `event.preventDefault()` and call * `callback(username, password)` with the credentials. * * If `callback` is called without a username or password, the authentication * request will be cancelled and the authentication error will be returned to the * page. */ on(event: 'login', listener: (event: Event, webContents: WebContents, authenticationResponseDetails: AuthenticationResponseDetails, authInfo: AuthInfo, callback: (username?: string, password?: string) => void) => void): this; off(event: 'login', listener: (event: Event, webContents: WebContents, authenticationResponseDetails: AuthenticationResponseDetails, authInfo: AuthInfo, callback: (username?: string, password?: string) => void) => void): this; once(event: 'login', listener: (event: Event, webContents: WebContents, authenticationResponseDetails: AuthenticationResponseDetails, authInfo: AuthInfo, callback: (username?: string, password?: string) => void) => void): this; addListener(event: 'login', listener: (event: Event, webContents: WebContents, authenticationResponseDetails: AuthenticationResponseDetails, authInfo: AuthInfo, callback: (username?: string, password?: string) => void) => void): this; removeListener(event: 'login', listener: (event: Event, webContents: WebContents, authenticationResponseDetails: AuthenticationResponseDetails, authInfo: AuthInfo, callback: (username?: string, password?: string) => void) => void): this; /** * Emitted when the user clicks the native macOS new tab button. The new tab button * is only visible if the current `BrowserWindow` has a `tabbingIdentifier` * * @platform darwin */ on(event: 'new-window-for-tab', listener: (event: Event) => void): this; /** * @platform darwin */ off(event: 'new-window-for-tab', listener: (event: Event) => void): this; /** * @platform darwin */ once(event: 'new-window-for-tab', listener: (event: Event) => void): this; /** * @platform darwin */ addListener(event: 'new-window-for-tab', listener: (event: Event) => void): this; /** * @platform darwin */ removeListener(event: 'new-window-for-tab', listener: (event: Event) => void): this; /** * Emitted when the user wants to open a file with the application. The `open-file` * event is usually emitted when the application is already open and the OS wants * to reuse the application to open the file. `open-file` is also emitted when a * file is dropped onto the dock and the application is not yet running. Make sure * to listen for the `open-file` event very early in your application startup to * handle this case (even before the `ready` event is emitted). * * You should call `event.preventDefault()` if you want to handle this event. * * On Windows, you have to parse `process.argv` (in the main process) to get the * filepath. * * @platform darwin */ on(event: 'open-file', listener: (event: Event, path: string) => void): this; /** * @platform darwin */ off(event: 'open-file', listener: (event: Event, path: string) => void): this; /** * @platform darwin */ once(event: 'open-file', listener: (event: Event, path: string) => void): this; /** * @platform darwin */ addListener(event: 'open-file', listener: (event: Event, path: string) => void): this; /** * @platform darwin */ removeListener(event: 'open-file', listener: (event: Event, path: string) => void): this; /** * Emitted when the user wants to open a URL with the application. Your * application's `Info.plist` file must define the URL scheme within the * `CFBundleURLTypes` key, and set `NSPrincipalClass` to `AtomApplication`. * * As with the `open-file` event, be sure to register a listener for the `open-url` * event early in your application startup to detect if the application is being * opened to handle a URL. If you register the listener in response to a `ready` * event, you'll miss URLs that trigger the launch of your application. * * @platform darwin */ on(event: 'open-url', listener: (event: Event, url: string) => void): this; /** * @platform darwin */ off(event: 'open-url', listener: (event: Event, url: string) => void): this; /** * @platform darwin */ once(event: 'open-url', listener: (event: Event, url: string) => void): this; /** * @platform darwin */ addListener(event: 'open-url', listener: (event: Event, url: string) => void): this; /** * @platform darwin */ removeListener(event: 'open-url', listener: (event: Event, url: string) => void): this; /** * Emitted when the application is quitting. * * > [!NOTE] On Windows, this event will not be emitted if the app is closed due to * a shutdown/restart of the system or a user logout. */ on(event: 'quit', listener: (event: Event, exitCode: number) => void): this; off(event: 'quit', listener: (event: Event, exitCode: number) => void): this; once(event: 'quit', listener: (event: Event, exitCode: number) => void): this; addListener(event: 'quit', listener: (event: Event, exitCode: number) => void): this; removeListener(event: 'quit', listener: (event: Event, exitCode: number) => void): this; /** * Emitted once, when Electron has finished initializing. On macOS, `launchInfo` * holds the `userInfo` of the `NSUserNotification` or information from * `UNNotificationResponse` that was used to open the application, if it was * launched from Notification Center. You can also call `app.isReady()` to check if * this event has already fired and `app.whenReady()` to get a Promise that is * fulfilled when Electron is initialized. * * > [!NOTE] The `ready` event is only fired after the main process has finished * running the first tick of the event loop. If an Electron API needs to be called * before the `ready` event, ensure that it is called synchronously in the * top-level context of the main process. */ on(event: 'ready', listener: (event: Event, /** * @platform darwin */ launchInfo: (Record<string, any>) | (NotificationResponse)) => void): this; off(event: 'ready', listener: (event: Event, /** * @platform darwin */ launchInfo: (Record<string, any>) | (NotificationResponse)) => void): this; once(event: 'ready', listener: (event: Event, /** * @platform darwin */ launchInfo: (Record<string, any>) | (NotificationResponse)) => void): this; addListener(event: 'ready', listener: (event: Event, /** * @platform darwin */ launchInfo: (Record<string, any>) | (NotificationResponse)) => void): this; removeListener(event: 'ready', listener: (event: Event, /** * @platform darwin */ launchInfo: (Record<string, any>) | (NotificationResponse)) => void): this; /** * Emitted when the renderer process unexpectedly disappears. This is normally * because it was crashed or killed. */ on(event: 'render-process-gone', listener: (event: Event, webContents: WebContents, details: RenderProcessGoneDetails) => void): this; off(event: 'render-process-gone', listener: (event: Event, webContents: WebContents, details: RenderProcessGoneDetails) => void): this; once(event: 'render-process-gone', listener: (event: Event, webContents: WebContents, details: RenderProcessGoneDetails) => void): this; addListener(event: 'render-process-gone', listener: (event: Event, webContents: WebContents, details: RenderProcessGoneDetails) => void): this; removeListener(event: 'render-process-gone', listener: (event: Event, webContents: WebContents, details: RenderProcessGoneDetails) => void): this; /** * This event will be emitted inside the primary instance of your application when * a second instance has been executed and calls `app.requestSingleInstanceLock()`. * * `argv` is an Array of the second instance's command line arguments, and * `workingDirectory` is its current working directory. Usually applications * respond to this by making their primary window focused and non-minimized. * * > [!NOTE] `argv` will not be exactly the same list of arguments as those passed * to the second instance. The order might change and additional arguments might be * appended. If you need to maintain the exact same arguments, it's advised to use * `additionalData` instead. * * > [!NOTE] If the second instance is started by a different user than the first, * the `argv` array will not include the arguments. * * This event is guaranteed to be emitted after the `ready` event of `app` gets * emitted. * * > [!NOTE] Extra command line arguments might be added by Chromium, such as * `--original-process-start-time`. */ on(event: 'second-instance', listener: (event: Event, /** * An array of the second instance's command line arguments */ argv: string[], /** * The second instance's working directory */ workingDirectory: string, /** * A JSON object of additional data passed from the second instance */ additionalData: unknown) => void): this; off(event: 'second-instance', listener: (event: Event, /** * An array of the second instance's command line arguments */ argv: string[], /** * The second instance's working directory */ workingDirectory: string, /** * A JSON object of additional data passed from the second instance */ additionalData: unknown) => void): this; once(event: 'second-instance', listener: (event: Event, /** * An array of the second instance's command line arguments */ argv: string[], /** * The second instance's working directory */ workingDirectory: string, /** * A JSON object of additional data passed from the second instance */ additionalData: unknown) => void): this; addListener(event: 'second-instance', listener: (event: Event, /** * An array of the second instance's command line arguments */ argv: string[], /** * The second instance's working directory */ workingDirectory: string, /** * A JSON object of additional data passed from the second instance */ additionalData: unknown) => void): this; removeListener(event: 'second-instance', listener: (event: Event, /** * An array of the second instance's command line arguments */ argv: string[], /** * The second instance's working directory */ workingDirectory: string, /** * A JSON object of additional data passed from the second instance */ additionalData: unknown) => void): this; /** * Emitted when a client certificate is requested. * * The `url` corresponds to the navigation entry requesting the client certificate * and `callback` can be called with an entry filtered from the list. Using * `event.preventDefault()` prevents the application from using the first * certificate from the store. */ on(event: 'select-client-certificate', listener: (event: Event, webContents: WebContents, url: string, certificateList: Certificate[], callback: (certificate?: Certificate) => void) => void): this; off(event: 'select-client-certificate', listener: (event: Event, webContents: WebContents, url: string, certificateList: Certificate[], callback: (certificate?: Certificate) => void) => void): this; once(event: 'select-client-certificate', listener: (event: Event, webContents: WebContents, url: string, certificateList: Certificate[], callback: (certificate?: Certificate) => void) => void): this; addListener(event: 'select-client-certificate', listener: (event: Event, webContents: WebContents, url: string, certificateList: Certificate[], callback: (certificate?: Certificate) => void) => void): this; removeListener(event: 'select-client-certificate', listener: (event: Event, webContents: WebContents, url: string, certificateList: Certificate[], callback: (certificate?: Certificate) => void) => void): this; /** * Emitted when Electron has created a new `session`. */ on(event: 'session-created', listener: (session: Session) => void): this; off(event: 'session-created', listener: (session: Session) => void): this; once(event: 'session-created', listener: (session: Session) => void): this; addListener(event: 'session-created', listener: (session: Session) => void): this; removeListener(event: 'session-created', listener: (session: Session) => void): this; /** * Emitted when Handoff is about to be resumed on another device. If you need to * update the state to be transferred, you should call `event.preventDefault()` * immediately, construct a new `userInfo` dictionary and call * `app.updateCurrentActivity()` in a timely manner. Otherwise, the operation will * fail and `continue-activity-error` will be called. * * @platform darwin */ on(event: 'update-activity-state', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity. */ userInfo: unknown) => void): this; /** * @platform darwin */ off(event: 'update-activity-state', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity. */ userInfo: unknown) => void): this; /** * @platform darwin */ once(event: 'update-activity-state', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity. */ userInfo: unknown) => void): this; /** * @platform darwin */ addListener(event: 'update-activity-state', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity. */ userInfo: unknown) => void): this; /** * @platform darwin */ removeListener(event: 'update-activity-state', listener: (event: Event, /** * A string identifying the activity. Maps to `NSUserActivity.activityType`. */ type: string, /** * Contains app-specific state stored by the activity. */ userInfo: unknown) => void): this; /** * Emitted when a new webContents is created. */ on(event: 'web-contents-created', listener: (event: Event, webContents: WebContents) => void): this; off(event: 'web-contents-created', listener: (event: Event, webContents: WebContents) => void): this; once(event: 'web-contents-created', listener: (event: Event, webContents: WebContents) => void): this; addListener(event: 'web-contents-created', listener: (event: Event, webContents: WebContents) => void): this; removeListener(event: 'web-contents-created', listener: (event: Event,