app events

33 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

second-instance event on Windows and Linux for deep links

On Windows and Linux, when a protocol handler is clicked, the app emits a 'second-instance' event rather than an 'open-url' event. The event listener receives (event, commandLine, workingDirectory) where commandLine is an array of strings and the last element is the deep link URL. The app must use app.requestSingleInstanceLock() to prevent multiple instances from running.

open-url event on macOS for protocol handlers

On macOS, protocol handlers trigger the 'open-url' event on the app object. The listener receives (event, url) where url is the complete protocol URL that was clicked. The 'open-url' listener must be registered during initial startup before app.whenReady() or other asynchronous initialization, otherwise listeners registered later may miss the launch URL delivered by macOS.

Event: will-finish-launching

The 'will-finish-launching' event is emitted when the application has finished basic startup. On Windows and Linux, this event is the same as the 'ready' event. On macOS, it represents the 'applicationWillFinishLaunching' notification of NSApplication. In most cases, you should do everything in the 'ready' event handler instead.

Event: activity-was-continued (macOS)

The 'activity-was-continued' event is emitted during Handoff after an activity from this device was successfully resumed on another one. It returns an event object, type string (identifying the activity, maps to NSUserActivity.activityType), and userInfo unknown (contains app-specific state stored by the activity).

Event: ready

The 'ready' event is emitted once when Electron has finished initializing. It returns an event object and launchInfo (Record<string, any> or NotificationResponse on macOS). On macOS, launchInfo holds the userInfo of NSUserNotification or UNNotificationResponse that was used to open the application if launched from Notification Center. You can call app.isReady() to check if this event has fired or app.whenReady() to get a Promise. 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 it is called synchronously in the top-level context of the main process.

Event: window-all-closed

The 'window-all-closed' event is emitted when all windows have been closed. If you do not subscribe to this event and all windows are closed, the default behavior is to quit the app. If you subscribe, you control whether the app quits or not. If the user pressed Cmd + Q or the developer called app.quit(), Electron will first try to close all windows and then emit the 'will-quit' event, and the 'window-all-closed' event would not be emitted.

Event: before-quit

The 'before-quit' event is emitted before the application starts closing its windows. It returns an event object. Calling event.preventDefault() will prevent the default behavior of terminating the application. If application quit was initiated by autoUpdater.quitAndInstall(), before-quit is emitted after emitting close event on all windows and closing them. 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.

Event: will-quit

The 'will-quit' event is emitted when all windows have been closed and the application will quit. It returns an event object. Calling event.preventDefault() will prevent the default behavior of terminating the application. See the 'window-all-closed' event for differences between 'will-quit' and 'window-all-closed' events. 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.

Event: quit

The 'quit' event is emitted when the application is quitting. It returns an event object and exitCode (Integer). 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.

Event: open-file (macOS)

The 'open-file' event is emitted when the user wants to open a file with the application. It returns an event object and path string. The event is usually emitted when the application is already open and the OS wants to reuse the application to open the file. It 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 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.

Event: open-url (macOS)

The 'open-url' event is emitted when the user wants to open a URL with the application. It returns an event object and url string. The application's Info.plist file must define the URL scheme within the CFBundleURLTypes key and set NSPrincipalClass to AtomApplication. Be sure to register a listener for the 'open-url' event early in 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.

Event: activate (macOS)

The 'activate' event is emitted when the application is activated. It returns an event object and hasVisibleWindows boolean. 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.

Event: did-become-active (macOS)

The 'did-become-active' event is emitted when the application becomes active. It returns an event object. 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.

Event: did-resign-active (macOS)

The 'did-resign-active' event is emitted when the app is no longer active and doesn't have focus. It returns an event object. This can be triggered by clicking on another application or by using the macOS App Switcher to switch to another application.

Event: continue-activity (macOS)

The 'continue-activity' event is emitted during Handoff when an activity from a different device wants to be resumed. It returns an event object, type string (identifying the activity, maps to NSUserActivity.activityType), userInfo unknown (contains app-specific state stored by the activity on another device), and details Object containing optional webpageURL string (identifying the URL of the webpage accessed by the activity on another device, if available). 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.

Event: will-continue-activity (macOS)

The 'will-continue-activity' event is emitted during Handoff before an activity from a different device wants to be resumed. It returns an event object and type string (identifying the activity, maps to NSUserActivity.activityType). You should call event.preventDefault() if you want to handle this event.

Event: continue-activity-error (macOS)

The 'continue-activity-error' event is emitted during Handoff when an activity from a different device fails to be resumed. It returns an event object, type string (identifying the activity, maps to NSUserActivity.activityType), and error string (with the error's localized description).

Event: update-activity-state (macOS)

The 'update-activity-state' event is emitted when Handoff is about to be resumed on another device. It returns an event object, type string (identifying the activity, maps to NSUserActivity.activityType), and userInfo unknown (contains app-specific state stored by the activity). 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.

Event: new-window-for-tab (macOS)

The 'new-window-for-tab' event is emitted when the user clicks the native macOS new tab button. It returns an event object. The new tab button is only visible if the current BrowserWindow has a tabbingIdentifier. You must create a window in this handler in order for macOS tabbing to work as expected.

Event: browser-window-blur

The 'browser-window-blur' event is emitted when a BrowserWindow gets blurred. It returns an event object and window BrowserWindow.

Event: browser-window-focus

The 'browser-window-focus' event is emitted when a BrowserWindow gets focused. It returns an event object and window BrowserWindow.

Event: browser-window-created

The 'browser-window-created' event is emitted when a new BrowserWindow is created. It returns an event object and window BrowserWindow.

Event: web-contents-created

The 'web-contents-created' event is emitted when a new WebContents is created. It returns an event object and webContents WebContents.

Event: certificate-error

The 'certificate-error' event is emitted when failed to verify the certificate for url. It returns an event object, webContents WebContents, url string, error string (the error code), certificate Certificate, callback Function (with isTrusted boolean parameter indicating whether to consider the certificate as trusted), and isMainFrame boolean. To trust the certificate you should prevent the default behavior with event.preventDefault() and call callback(true).

Event: certificate-error example

This example shows how to handle certificate errors and trust specific certificates: ```js const { app } = require('electron') app.on('certificate-error', (event, webContents, url, error, certificate, callback) => { if (url === 'https://github.com') { // Verification logic. event.preventDefault() callback(true) } else { callback(false) } }) ```

Event: select-client-certificate

The 'select-client-certificate' event is emitted when a client certificate is requested. It returns an event object, webContents WebContents | null, url URL, certificateList Certificate[], and callback Function (with optional certificate Certificate parameter). 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. webContents is null when the request does not originate from a renderer process, for example when using net.request or net.fetch in the main process, or from a utility process created with respondToAuthRequestsFromMainProcess: true. For utility processes created without that flag, net requests proceed without a client certificate and this event is not emitted.

Event: select-client-certificate example

This example shows how to handle client certificate selection: ```js const { app } = require('electron') app.on('select-client-certificate', (event, webContents, url, list, callback) => { event.preventDefault() callback(list[0]) }) ```

Event: login

The 'login' event is emitted when webContents or Utility process wants to do basic auth. It returns an event object, webContents WebContents | null, authenticationResponseDetails Object (with url URL, pid number, isRequestForNavigation boolean indicating whether the request is for a navigation, firstAuthAttempt boolean indicating whether this is the first authentication attempt, optional responseHeaders Record<string, string | string[]> with the headers returned in the response), authInfo Object (with isProxy boolean, scheme string, host string, port Integer, realm string), and callback Function (with optional username string and optional password string parameters). 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.

Event: login example

This example shows how to handle login requests: ```js const { app } = require('electron') app.on('login', (event, webContents, details, authInfo, callback) => { event.preventDefault() callback('username', 'secret') }) ```

Event: gpu-info-update

The 'gpu-info-update' event is emitted whenever there is a GPU info update.

Event: render-process-gone

The 'render-process-gone' event is emitted when the renderer process unexpectedly disappears. It returns an event object, webContents WebContents, and details RenderProcessGoneDetails. This is normally because it was crashed or killed.

Event: child-process-gone

The 'child-process-gone' event is emitted when a child process unexpectedly disappears. It does not include renderer processes. It returns an event object and details Object with: type string (Process type: 'Utility', 'Zygote', 'Sandbox helper', 'GPU', 'Pepper Plugin', 'Pepper Plugin Broker', or 'Unknown'), reason string (The reason the child process is gone: 'clean-exit' - process exited with exit code zero, 'abnormal-exit' - process exited with non-zero exit code, 'killed' - process was sent SIGTERM or otherwise killed externally, 'crashed' - process crashed, 'oom' - process ran out of memory, 'launch-failed' - process never successfully launched, 'integrity-failure' - Windows code integrity checks failed, 'memory-eviction' - process proactively terminated to prevent OOM), exitCode number (the exit code for the process), optional serviceName string (the non-localized name of the process), and optional name string (the name of the process, examples for utility: 'Audio Service', 'Content Decryption Module Service', 'Network Service', 'Video Capture', etc.).

Event: second-instance

The 'second-instance' event is emitted inside the primary instance of your application when a second instance has been executed and calls app.requestSingleInstanceLock(). It returns an event object, argv string[] (an array of the second instance's command line arguments), workingDirectory string (the second instance's working directory), and additionalData unknown (a JSON object of additional data passed from the second instance). 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. 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. Extra command line arguments might be added by Chromium, such as --original-process-start-time.

Give your agent this brain