From 7dcc794d76acb16a08197d65b103dbe269fa1f86 Mon Sep 17 00:00:00 2001 From: Ayushman Chhabra <14110965+ayushmanchhabra@users.noreply.github.com> Date: Thu, 27 Aug 2026 16:07:41 +0530 Subject: [PATCH] =?UTF-8?q?=F0=9F=A4=96=20Merge=20PR=20#75409=20[nw.js]=20?= =?UTF-8?q?Add=20missing=20definitions=20and=20bump=20to=20latest=20v0.115?= =?UTF-8?q?.0=20by=20@ayushmanchhabra?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- types/nw.js/index.d.ts | 809 ++++++++++++++++++++++++++++++++++--- types/nw.js/nw.js-tests.ts | 154 ++++++- types/nw.js/package.json | 2 +- 3 files changed, 910 insertions(+), 55 deletions(-) diff --git a/types/nw.js/index.d.ts b/types/nw.js/index.d.ts index ec646a238fdac0..19d4dd8a404c81 100644 --- a/types/nw.js/index.d.ts +++ b/types/nw.js/index.d.ts @@ -19,6 +19,20 @@ declare global { */ set(data: string, type?: string, raw?: boolean): void; + /** + * Write `clipboardData` to the clipboard. + * + * @param clipboardData {NWJS_Helpers.ClipboardData} JSON object containing `data`, `type` and `raw` to be written to clipboard. + */ + set(clipboardData: ClipboardData): void; + + /** + * Write multiple types of data to clipboard simultaneously. + * + * @param clipboardDataList {NWJS_Helpers.ClipboardData[]} Array of `clipboardData` to be written to clipboard. + */ + set(clipboardDataList: ClipboardData[]): void; + /** * Get the data of `type` from clipboard. * @@ -28,6 +42,22 @@ declare global { */ get(type?: string, raw?: boolean): string; + /** + * Get the data described by `clipboardData` from clipboard. + * + * @param clipboardData {NWJS_Helpers.ClipboardReadOptions} JSON object containing `type` and `raw` argument for reading data from clipboard. + * @returns {string} the data retrieved from the clipboard. + */ + get(clipboardData: ClipboardReadOptions): string; + + /** + * Get multiple types of data from clipboard simultaneously. + * + * @param clipboardDataList {NWJS_Helpers.ClipboardReadOptions[]} Array of `clipboardData` for reading data from clipboard. + * @returns {NWJS_Helpers.ClipboardDataResult[]} array of `clipboardData` retrieved from the clipboard. Each item contains `type`, `data` and `raw` (optional) attributes. + */ + get(clipboardDataList: ClipboardReadOptions[]): ClipboardDataResult[]; + /** * Get an array contains list of available types of data in clipboard currenly. * You can use the returned list as a suggestion to get the right data from clipboard. @@ -42,6 +72,61 @@ declare global { clear(): void; } + /** + * JSON object containing `data`, `type` and `raw` to be written to the clipboard via `clip.set()`. + */ + interface ClipboardData { + /** + * The data to write to the clipboard. + */ + data: string; + + /** + * (Optional) the type of the data. Support text, png, jpeg, html and rtf. By default, type is set to "text". + */ + type?: string | undefined; + + /** + * (Optional) requiring raw image data. This option is only valid if type is png or jpeg. By default, raw is set to false. + */ + raw?: boolean | undefined; + } + + /** + * JSON object containing `type` and `raw` argument for reading data from the clipboard via `clip.get()`. + */ + interface ClipboardReadOptions { + /** + * (Optional) the type of the data. Support text, png, jpeg, html and rtf. By default, type is set to "text". + */ + type?: string | undefined; + + /** + * (Optional) requiring raw image data. This option is only valid if type is png or jpeg. + */ + raw?: boolean | undefined; + } + + /** + * An item returned by `clip.get(clipboardDataList)`. + */ + interface ClipboardDataResult { + /** + * The type of the data. + */ + type: string; + + /** + * The data retrieved from the clipboard. + */ + data: string; + + /** + * (Optional) Whether the image data is raw. Only present if type is png or jpeg. + */ + raw?: boolean | undefined; + } + /** * Object that contains options to use while creation of nw.Menu. example: new nw.Menu(MenuOption) */ @@ -49,7 +134,7 @@ declare global { /** * {string} (Optional) two types are accepted by this method: "menubar" or "contextmenu". The value is set to "contextmenu" by default. */ - type: string; + type?: "menubar" | "contextmenu" | undefined; } /** @@ -175,7 +260,10 @@ declare global { * @param should_include_screens {boolean} Whether should include screens * @param should_include_windows {boolean} Whether should include windows */ - start(should_include_screens: boolean, should_include_windows: boolean): void; + start( + should_include_screens: boolean, + should_include_windows: boolean, + ): void; /** * The DesktopCaptureMonitor will stop monitoring the system. @@ -186,8 +274,9 @@ declare global { * Register and return a valid stream id passed into chromeMediaSourceId in getUserMedia constraints. * * @param id {string} valid stream id. + * @returns {string} the registered stream id, to be passed into `chromeMediaSourceId` in `getUserMedia` constraints. */ - registerStream(id: string): void; + registerStream(id: string): string; on(event: string, listener: Function): this; @@ -204,7 +293,13 @@ declare global { */ on( event: "added", - listener: (id: string, name: string, order: number, type: string, primary: boolean) => any, + listener: ( + id: string, + name: string, + order: number, + type: string, + primary: boolean, + ) => any, ): this; /** @@ -225,7 +320,10 @@ declare global { * - (optional) new_order {number} Is the new z-order. * - (optional) old_order {number} Is the old z-order. */ - on(event: "orderchanged", listener: (id?: string, new_order?: number, old_order?: number) => any): this; + on( + event: "orderchanged", + listener: (id?: string, new_order?: number, old_order?: number) => any, + ): this; /** * Emit when the name of the source has changed. This can happen when a window changes title. @@ -235,7 +333,10 @@ declare global { * - (optional) id {string} Is the media id of the screen or window that has a name changed. * - (optional) name {string} Is the new name of the screen or window. */ - on(event: "namechanged", listener: (id?: string, name?: string) => any): this; + on( + event: "namechanged", + listener: (id?: string, name?: string) => any, + ): this; /** * Emit when the thumbnail of a source changed. @@ -245,7 +346,10 @@ declare global { * - (optional) id {string} Is the media id of the screen or window that has an updated thumbnail. * - (optional) name {string} Is the base64 encoded png of the thumbnail. */ - on(event: "thumbnailchanged", listener: (id?: string, thumbnail?: string) => any): this; + on( + event: "thumbnailchanged", + listener: (id?: string, thumbnail?: string) => any, + ): this; } /** @@ -255,14 +359,14 @@ declare global { /** * {Function} (Optional) A callback when the hotkey is triggered. */ - active: Function; + active?: Function | undefined; /** * {Function} (Optional) A callback when failed to register the hotkey. * * @param msg {string} Failure message */ - failed: (msg?: string) => any; + failed?: ((msg?: string) => any) | undefined; /** * {string} Key combinations of the shortcut, such as "ctrl+shift+a". @@ -310,35 +414,131 @@ declare global { */ interface PrintOption { /** - * The device name of the printer + * (Optional) Whether to print without the need for user's interaction. True by default. */ - printer: string; + autoprint?: boolean | undefined; /** - * The path of the output PDF when printing to PDF + * (Optional) Hide the flashing print preview dialog. False by default. */ - pdf_path: string; + silent?: boolean | undefined; /** - * Whether to enable header and footer + * (Optional) The device name of the printer returned by `nw.Window.getPrinters()`. No need to set this when printing to PDF. */ - headerFooterEnabled: boolean; + printer?: string | undefined; /** - * Whether to use landscape or portrait + * (Optional) The path of the output PDF when printing to PDF */ - landscape: boolean; + pdf_path?: string | undefined; /** - * The paper size spec + * (Optional) Whether to enable header and footer + */ + headerFooterEnabled?: boolean | undefined; + + /** + * (Optional) Whether to use landscape or portrait + */ + landscape?: boolean | undefined; + + /** + * (Optional) The paper size spec * example: 'mediaSize':{'name': 'CUSTOM', 'width_microns': 279400, 'height_microns': 215900, 'custom_display_name':'Letter', 'is_default': true} */ - mediaSize: any; + mediaSize?: PrintMediaSize | undefined; + + /** + * (Optional) Whether to print CSS backgrounds + */ + shouldPrintBackgrounds?: boolean | undefined; + + /** + * (Optional) 0 - Default; 1 - No margins; 2 - minimum; 3 - Custom, see `marginsCustom`. + */ + marginsType?: number | undefined; /** - * Whether to print CSS backgrounds + * (Optional) The custom margin setting; units are points. + * example: "marginsCustom":{"marginBottom":54,"marginLeft":70,"marginRight":28,"marginTop":32} */ - shouldPrintBackgrounds: boolean; + marginsCustom?: PrintMarginsCustom | undefined; + + /** + * (Optional) The number of copies to print. + */ + copies?: number | undefined; + + /** + * (Optional) The scale factor; 100 is the default. + */ + scaleFactor?: number | undefined; + + /** + * (Optional) String to replace the URL in the header. + */ + headerString?: string | undefined; + + /** + * (Optional) String to replace the URL in the footer. + */ + footerString?: string | undefined; + } + + /** + * The custom margin setting used by `PrintOption.marginsCustom`. Units are points. + */ + interface PrintMarginsCustom { + /** + * (Optional) The bottom margin, in points. + */ + marginBottom?: number | undefined; + + /** + * (Optional) The left margin, in points. + */ + marginLeft?: number | undefined; + + /** + * (Optional) The right margin, in points. + */ + marginRight?: number | undefined; + + /** + * (Optional) The top margin, in points. + */ + marginTop?: number | undefined; + } + + /** + * The paper size spec used by `PrintOption.mediaSize`. + */ + interface PrintMediaSize { + /** + * (Optional) The name of the paper size, e.g. "CUSTOM" or "NA_LETTER". + */ + name?: string | undefined; + + /** + * (Optional) The paper width in microns. + */ + width_microns?: number | undefined; + + /** + * (Optional) The paper height in microns. + */ + height_microns?: number | undefined; + + /** + * (Optional) The display name shown for the paper size, e.g. "Letter". + */ + custom_display_name?: string | undefined; + + /** + * (Optional) Whether this is the default paper size. + */ + is_default?: boolean | undefined; } /** @@ -356,6 +556,61 @@ declare global { datatype?: string | undefined; } + /** + * Options for nw.Window.get().captureScreenshot(). + */ + interface CaptureScreenshotOptions { + /** + * (Optional) Capture the whole page beyond the visible area. Currently the height of captured image is capped at 16384 pixels by Chromium. + */ + fullSize?: boolean | undefined; + + /** + * (Optional) The image format used to generate the image. It supports two formats: "png" and "jpeg". "png" is the default. + */ + format?: string | undefined; + + /** + * (Optional) Compression quality from range [0..100] (jpeg only). + */ + quality?: number | undefined; + + /** + * (Optional) Capture the screenshot of a given region only. + */ + clip?: CaptureScreenshotClip | undefined; + } + + /** + * Region to capture, used by `CaptureScreenshotOptions.clip`. + */ + interface CaptureScreenshotClip { + /** + * X offset in device independent pixels (dip). + */ + x: number; + + /** + * Y offset in device independent pixels (dip). + */ + y: number; + + /** + * Rectangle width in device independent pixels (dip). + */ + width: number; + + /** + * Rectangle height in device independent pixels (dip). + */ + height: number; + + /** + * Page scale factor. + */ + scale: number; + } + /** * This includes multiple functions to manipulate the cookies. */ @@ -367,7 +622,10 @@ declare global { * @param callback {function(cookie?)} The callback when cookie retrieved. * - (Optional) cookie {Cookie} Contains details about the cookie. This parameter is null if no such cookie was found. */ - get(details: CookiesGetDetails, callback: (cookie?: Cookie) => void): void; + get( + details: CookiesGetDetails, + callback: (cookie?: Cookie) => void, + ): void; /** * Retrieves all cookies from a single cookie store that match the given information. @@ -376,7 +634,10 @@ declare global { * @param callback {function(cookies?)} The callback when cookies retrieved. * - (Optional) cookies {Cookie[]} All the existing, unexpired cookies that match the given cookie info. */ - getAll(details: CookiesGetAllDetails, callback: (cookies?: Cookie[]) => void): void; + getAll( + details: CookiesGetAllDetails, + callback: (cookies?: Cookie[]) => void, + ): void; /** * Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist. @@ -385,7 +646,10 @@ declare global { * @param callback {function(cookie?)} The callback when cookie has been set. * - (Optional) cookie {Cookie} Contains details about the cookie that's been set. If setting failed for any reason, this will be "null", and "chrome.runtime.lastError" will be set. */ - set(details: CookiesSetDetails, callback: (cookie?: Cookie) => void): void; + set( + details: CookiesSetDetails, + callback: (cookie?: Cookie) => void, + ): void; /** * Deletes a cookie by name. @@ -394,7 +658,10 @@ declare global { * @param callback {function(cookie?)} The callback when cookie has been set. * - (Optional) details {Objet} Contains details about the cookie that's been removed. If removal failed for any reason, this will be "null", and "chrome.runtime.lastError" will be set. */ - remove(details: CookiesRemoveDetails, callback: (details?: CookiesRemovedDetails) => void): void; + remove( + details: CookiesRemoveDetails, + callback: (details?: CookiesRemovedDetails) => void, + ): void; /** * Fired when a cookie is set or removed. @@ -406,7 +673,18 @@ declare global { * @param callback {function(changeInfo?)} The callback when cookie has been changed. * - (Optional) changeInfo {Objet} Contains details about the cookie that's been changed. */ - addListener(callback: (changeInfo: CookiesOnChangedCallbackChangeInfo) => void): void; + addListener( + callback: (changeInfo: CookiesOnChangedCallbackChangeInfo) => void, + ): void; + + /** + * Remove a listener for onChanged event. + * + * @param callback {function(changeInfo?)} The callback to remove. + */ + removeListener( + callback: (changeInfo: CookiesOnChangedCallbackChangeInfo) => void, + ): void; }; } @@ -642,7 +920,13 @@ declare global { /** * The underlying reason behind the cookie's change. */ - cause: string | "evicted" | "expired" | "explicit" | "expired_overwrite" | "overwrite"; + cause: + | string + | "evicted" + | "expired" + | "explicit" + | "expired_overwrite" + | "overwrite"; } /** @@ -682,6 +966,172 @@ declare global { setNewWindowManifest(m: WindowOption): void; } + /* Manifest Format: http://docs.nwjs.io/en/latest/References/Manifest%20Format/ */ + /** + * The `package.json` manifest of an NW.js app, as returned by `nw.App.manifest`. + * Only the fields NW.js reads are typed here; a manifest may carry arbitrary + * additional `package.json` fields NW.js ignores. + */ + interface Manifest { + /** + * Which HTML page should be opened or which JavaScript file should be executed when NW.js starts. + */ + main: string; + + /** + * The name of the package. Must be a unique, lowercase alpha-numeric name without spaces (may include `.`, `_` or `-`). + */ + name: string; + + /** + * (Optional) Use it to rename the Helper application under macOS. + */ + product_string?: string | undefined; + + /** + * (Optional) Set to `false` to disable Node support in NW.js. + */ + nodejs?: boolean | undefined; + + /** + * (Optional) Path to a Node.js script file, executed on startup in Node context before the first DOM window loads. + */ + "node-main"?: string | undefined; + + /** + * (Optional) The host in the `chrome-extension://` protocol URL used for the application. + */ + domain?: string | undefined; + + /** + * (Optional) Whether to start up a single instance of the app. `true` by default. + * + * @deprecated since version 0.13.0 + */ + "single-instance"?: boolean | undefined; + + /** + * (Optional) Background script, executed in the background page at app start. + */ + "bg-script"?: string | undefined; + + /** + * (Optional) Controls how the window looks. See `WindowOption`. + */ + window?: WindowOption | undefined; + + /** + * (Optional) Controls what features of WebKit should be on/off. + */ + webkit?: WebkitOption | undefined; + + /** + * (Optional) Overrides the `User-Agent` header in HTTP requests made from the application. + * Supports `%name`, `%ver`, `%nwver`, `%webkit_ver`, `%chromium_ver` and `%osinfo` placeholders. + */ + "user-agent"?: string | undefined; + + /** + * (Optional) Enables calling Node in remote pages. Value(s) follow Chrome extension match patterns. + */ + "node-remote"?: string | string[] | undefined; + + /** + * (Optional) Chromium (content shell) command line arguments. + */ + "chromium-args"?: string | undefined; + + /** + * (Optional) URL of the crash report server. + */ + crash_report_url?: string | undefined; + + /** + * (Optional) Flags passed to the JS engine (v8). + */ + "js-flags"?: string | undefined; + + /** + * (Optional) Local filename, relative to the application path, of a script injected after CSS but before other DOM/script. + */ + inject_js_start?: string | undefined; + + /** + * (Optional) Local filename, relative to the application path, of a script injected after the document loads, before `onload`. + */ + inject_js_end?: string | undefined; + + /** + * (Optional) List of PEM-encoded certificates used as additional root certificates for validation. + */ + additional_trust_anchors?: string[] | undefined; + + /** + * (Optional) Number of megabytes for the quota of the DOM storage. + */ + dom_storage_quota?: number | undefined; + + /** + * (Optional, Mac) Whether the default `Edit` menu should be disabled. `false` by default. + * + * @deprecated since version 0.13.0 + */ + "no-edit-menu"?: boolean | undefined; + + /** + * (Optional) Permissions granted to `` tags, keyed by storage partition. + * A webview using one of these partitions (via its `partition` attribute) can load + * the listed resources and be used as a trusted DevTools container. + */ + webview?: WebviewManifestOption | undefined; + + /** + * NW.js only reads the fields above; any other `package.json` field (e.g. `dependencies`, `scripts`) is preserved as-is. + */ + [key: string]: any; + } + + /** + * `webview` manifest field. Grants extra permissions to `` partitions. + */ + interface WebviewManifestOption { + /** + * (Optional) The list of storage partitions and the resources each may access. + */ + partitions?: WebviewPartition[] | undefined; + } + + /** + * A single entry of `Manifest.webview.partitions`. + */ + interface WebviewPartition { + /** + * The name of the partition, matched against the `partition` attribute of a `` tag. + */ + name: string; + + /** + * (Optional) Resources the partition is allowed to load, following Chrome extension + * match patterns. e.g. `[""]`. + */ + accessible_resources?: string[] | undefined; + } + + /** + * `webkit` manifest subfield, controls what features of WebKit should be on/off. + */ + interface WebkitOption { + /** + * (Optional, Mac) Enable zooming with double tapping using 2 fingers. `false` by default. + */ + double_tap_to_zoom_enabled?: boolean | undefined; + + /** + * (Optional) Whether to load external browser plugins like Flash. `true` by default. + */ + plugin?: boolean | undefined; + } + /** * nw.Window Option that is in the same format as the Window subfields in manifest format. */ @@ -691,6 +1141,13 @@ declare global { */ id?: string | undefined; + /** + * (Optional) Whether the navigation toolbar should be shown. + * + * @deprecated since version 0.13.0 + */ + toolbar?: boolean | undefined; + /** * The default title of window created by NW.js */ @@ -793,6 +1250,16 @@ declare global { */ new_instance?: boolean | undefined; + /** + * (Optional) If true, the Node context and DOM context are merged in the new window's process. Use only when `new_instance` is true. + */ + mixed_context?: boolean | undefined; + + /** + * (Optional) Whether the window should be focused when it's opened. `false` by default. + */ + focus?: boolean | undefined; + /** * (Optional) The script to be injected before document loaded. */ @@ -819,6 +1286,54 @@ declare global { ignore(): void; } + /* webview Tag: http://docs.nwjs.io/en/latest/References/webview%20Tag/ */ + /** + * The NW.js-specific additions to the `` tag. + * + * Only the methods NW.js adds on top of Chrome's `` are declared here; for the + * upstream API surface, intersect this with the `` typings from `@types/chrome`: + * `document.getElementById("foo") as chrome.webviewTag.WebViewElement & NWJS_Helpers.webview` + */ + interface webview extends HTMLElement { + /** + * Open or close the DevTools window for the guest contents. + * + * @param show {boolean} Whether to open or close the devtools window. + * @param container {HTMLElement} (Optional) the `` element used to display the + * DevTools. By default the DevTools is shown in a new window. The container webview must + * be trusted, i.e. its `partition` must be listed in the `webview` field of the manifest. + */ + showDevTools(show: boolean, container?: HTMLElement): void; + + /** + * Inspect the element located at (`x`, `y`). Only meaningful after the DevTools has been + * opened with `webview.showDevTools()`. + * + * @param x {number} The x coordinate of the element to inspect. + * @param y {number} The y coordinate of the element to inspect. + */ + inspectElementAt(x: number, y: number): void; + + /** + * Get the id of the cookie store of the guest contents, to be used as `storeId` in the + * `chrome.cookies` API. + * + * @returns {string} The cookie store id. + */ + getCookieStoreId(): string; + } + + /** + * Extra field NW.js accepts in the `InjectDetails` of `webview.executeScript()`. + */ + interface WebviewInjectDetails { + /** + * (Optional) Inject the code into the main world context instead of an isolated world, + * so it can access JS objects of the target DOM context. + */ + mainWorld?: boolean | undefined; + } + interface win extends EventEmitter { /** * Get the corresponding DOM window object of the native window. @@ -851,9 +1366,16 @@ declare global { title: string; /** - * Get or set window's menubar. + * Get or set window's menubar. Set with a Menu with type `menubar`. + * When set to `null`, the menubar is completely removed for Windows and Linux, + * and the menubar is cleared out on Mac. + */ + menu: nw.Menu | null; + + /** + * Get whether the window is always on top of other windows. */ - menu: nw.Menu; + isAlwaysOnTop: boolean; /** * Get whether we're in fullscreen mode. @@ -904,6 +1426,20 @@ declare global { */ resizeTo(width: number, height: number): void; + /** + * Sets the inner width of the window. + * + * @param width {Integer} The inner width of the window + */ + setInnerWidth(width: number): void; + + /** + * Sets the inner height of the window. + * + * @param height {Integer} The inner height of the window + */ + setInnerHeight(height: number): void; + /** * Resizes a window by the specified amount. * @@ -961,6 +1497,13 @@ declare global { */ maximize(): void; + /** + * Unmaximize the window, i.e. the reverse of `maximize()`. + * + * @deprecated since version 0.13. Replaced by the `restore` event. + */ + unmaximize(): void; + /** * Minimize the window to task bar on Windows, iconify the window on GTK, and miniaturize the window on Mac OS X. */ @@ -1001,6 +1544,21 @@ declare global { */ toggleKioskMode(): void; + /** + * Turn on/off the transparency support. + * + * @deprecated since version 0.13. + * @param transparent {boolean} Whether to set the window to be transparent + */ + setTransparent(transparent: boolean): void; + + /** + * Turn the window's native shadow on/off. Useful for frameless, transparent windows. (Mac) + * + * @param shadow {boolean} Whether the window has a shadow + */ + setShadow(shadow: boolean): void; + /** * Open the devtools to inspect the window. * @@ -1008,7 +1566,10 @@ declare global { * @param callback {function(dev_win?)} callback with the native window of the DevTools window. * - (optional) dev_win {window} Window object that you can use any properties and methods of Window except the events */ - showDevTools(iframe?: string | HTMLIFrameElement, callback?: (dev_win?: Window) => void): void; + showDevTools( + iframe?: string | HTMLIFrameElement, + callback?: (dev_win?: Window) => void, + ): void; /** * Close the devtools window. @@ -1107,7 +1668,27 @@ declare global { * - (optional) arg {base64string|Buffer} Captured page data. * @param config {string|CapturePageConfig} (Optional) Conig how captured page returned. */ - capturePage(callback: (arg: string | Object) => void, config?: string | CapturePageConfig): void; + capturePage( + callback: (arg: string | Object) => void, + config?: string | CapturePageConfig, + ): void; + + /** + * Captures the window. It can be used to capture the full page beyond the visible area. To capture only the + * visible area, see `win.capturePage`. When `callback` is omitted, a Promise is returned and it will resolve + * with the `data` argument of the callback. + * + * @param options {CaptureScreenshotOptions} Options for the screenshot. + * @param callback {function(err, data)} (Optional) The callback when finished capturing the window. + * - err {string | null} `null` for success; a string with the error message for failure. + * - data {string} base64 encoded image + * @returns {Promise | void} A promise resolving with the base64 encoded image, if `callback` is omitted. + */ + captureScreenshot( + options: CaptureScreenshotOptions, + callback: (err: string | null, data: string) => void, + ): void; + captureScreenshot(options: CaptureScreenshotOptions): Promise; /** * Show window progress bar. @@ -1129,15 +1710,32 @@ declare global { * @param frame {HTMLIFrameElement} The frame to execute in. If iframe is null, it assumes in current window / frame. * @param script {string} The source code of the script to be executed */ - eval(frame: HTMLIFrameElement, script: string): void; + eval(frame: HTMLIFrameElement | null, script: string): void; /** * Load and execute the compiled snapshot in the frame. * * @param frame {HTMLIFrameElement} The frame to execute in. If iframe is null, it assumes in current window / frame. - * @param path {string} the path of the snapshot file generated by nwjc + * @param path {string | ArrayBuffer | Buffer} the path or Buffer or ArrayBuffer of the binary file generated by nwjc + */ + evalNWBin( + frame: HTMLIFrameElement | null, + path: string | ArrayBuffer | Buffer, + ): void; + + /** + * Load and execute the compiled binary for Modules in the frame. The binary should be compiled with `nwjc --nw-module`. + * The module must be registered with `evalNWBinModule` before it is imported. + * + * @param frame {HTMLIFrameElement} The frame to execute in. If iframe is null, it assumes in current window / frame. + * @param path {string | ArrayBuffer | Buffer} the path or Buffer or ArrayBuffer of the binary file generated by nwjc + * @param module_path {string} the module URL related to the current document. It will be used to resolve the module specifier. */ - evalNWBin(frame: HTMLIFrameElement, path: string): void; + evalNWBinModule( + frame: HTMLIFrameElement | null, + path: string | ArrayBuffer | Buffer, + module_path: string, + ): void; on(event: string, listener: Function): this; @@ -1181,7 +1779,10 @@ declare global { * @param listener {function(byCommandQ?)} The callback that handles the `document-start` event. * - (optional) frame {HTMLIFrameElement|any} Is the iframe object, or null if the event is for the window.. */ - on(event: "document-start", listener: (frame: HTMLIFrameElement | any) => any): this; + on( + event: "document-start", + listener: (frame: HTMLIFrameElement | any) => any, + ): this; /** * Emitted when the document object in this window or a child iframe is unloaded, but before the onunload event is emitted. @@ -1190,7 +1791,10 @@ declare global { * @param listener {function(byCommandQ?)} The callback that handles the `document-end` event. * - (optional) frame {HTMLIFrameElement|any} Is the iframe object, or null if the event is for the window.. */ - on(event: "document-end", listener: (frame: HTMLIFrameElement | any) => any): this; + on( + event: "document-end", + listener: (frame: HTMLIFrameElement | any) => any, + ): this; /** * Emitted when window gets focus. @@ -1250,7 +1854,10 @@ declare global { * - (optional) width {Integer} The new width of the window. * - (optional) height {Integer} The new height of the window. */ - on(event: "resize", listener: (width?: number, height?: number) => any): this; + on( + event: "resize", + listener: (width?: number, height?: number) => any, + ): this; /** * Emitted when window enters fullscreen state. @@ -1260,6 +1867,15 @@ declare global { */ on(event: "enter-fullscreen", listener: () => any): this; + /** + * Emitted when window leaves fullscreen state. + * + * @deprecated since version 0.13. Replaced by the `restore` event. + * @param event {string} Event name + * @param listener {function} The callback that handles the `leave-fullscreen` event. + */ + on(event: "leave-fullscreen", listener: () => any): this; + /** * Emitted when window zooming changed. * @@ -1269,6 +1885,29 @@ declare global { */ on(event: "zoom", listener: (zoom?: number) => any): this; + /** + * Emitted after the capturePage method is called and image data is ready. + * + * @deprecated since version 0.13. Use the callback with `win.capturePage()` instead. + * @param event {string} Event name + * @param listener {function(arg?)} The callback that handles the `capturepagedone` event. + * - (optional) arg {string|Object} Captured page data. + */ + on( + event: "capturepagedone", + listener: (arg?: string | Object) => any, + ): this; + + /** + * Emitted when the DevTools window has been opened. + * + * @deprecated since version 0.13. Use the `callback` passed to `win.showDevTools()` instead. + * @param event {string} Event name + * @param listener {function(url?)} The callback that handles the `devtools-opened` event. + * - (optional) url {string} URL of the DevTools window. + */ + on(event: "devtools-opened", listener: (url?: string) => any): this; + /** * Emitted after Devtools is closed. * @@ -1288,7 +1927,11 @@ declare global { */ on( event: "new-win-policy", - listener: (frame: HTMLIFrameElement | null, url: string, policy: WinPolicy) => any, + listener: ( + frame: HTMLIFrameElement | null, + url: string, + policy: WinPolicy, + ) => any, ): this; /** @@ -1302,7 +1945,11 @@ declare global { */ on( event: "navigation", - listener: (frame?: HTMLIFrameElement | any, url?: string, policy?: WinNavigationPolicy) => any, + listener: ( + frame?: HTMLIFrameElement | any, + url?: string, + policy?: WinNavigationPolicy, + ) => any, ): this; } } @@ -1325,8 +1972,9 @@ declare global { /** * Get a list of patterns of filtered command line arguments used by `App.argv`. + * By default: `[/^--url=/, /^--remote-debugging-port=/, /^--renderer-cmd-prefix=/, /^--nwapp=/]`. */ - filteredArgv: Object[]; + filteredArgv: RegExp[]; /** * Get the directory where the application starts. The application will change the current directory to where the package files reside after start. @@ -1341,7 +1989,7 @@ declare global { /** * Get the json object of the manifest file. */ - manifest: any; + manifest: NWJS_Helpers.Manifest; /** * Clear the HTTP cache in memory and the one on disk. This method call is synchronized. @@ -1374,7 +2022,10 @@ declare global { * @param component {string} ID of component; currently only `WIDEVINE` is supported. * @param callback {(version: string) => void} Callback after the component is enabled; `version` string parameter is the version of the enabled component. ‘0.0.0.0’ means it’s not installed. Use `App.updateComponent()` to install it. */ - enableComponent(component: string, callback: (version: string) => void): void; + enableComponent( + component: string, + callback: (version: string) => void, + ): void; /** * Query the proxy to be used for loading `url` in DOM. @@ -1455,7 +2106,10 @@ declare global { * @param component {string} ID of component; currently only `WIDEVINE` is supported. * @param callback {(success: boolean) => void} Callback after the component is updated; success is a boolean parameter for the update result. */ - updateComponent(component: string, callback: (success: boolean) => void): void; + updateComponent( + component: string, + callback: (success: boolean) => void, + ): void; on(event: string, listener: Function): this; @@ -1550,7 +2204,10 @@ declare global { * @param appname {string} The application name * @param options {Object} (Optional) Options to modify default `edit` and `window` MenuItems in Mac */ - createMacBuiltin(appname: string, options?: NWJS_Helpers.CreateMacBuiltinOption): void; + createMacBuiltin( + appname: string, + options?: NWJS_Helpers.CreateMacBuiltinOption, + ): void; } /* MenuItem: http://docs.nwjs.io/en/latest/References/MenuItem/ */ @@ -1588,7 +2245,7 @@ declare global { /** * Get or set the `tooltip` of a `MenuItem` */ - tooltip: boolean; + tooltip: string; /** * Get or set whether the `MenuItem` is `checked` @@ -1652,7 +2309,10 @@ declare global { * @param callback {Function} callback function with chosed streamId. * - (optional) streamId {string} streamId will be false if failed to execute or existing session is alive. */ - chooseDesktopMedia(sources: string[], callback: (streamId?: string | boolean) => void): void; + chooseDesktopMedia( + sources: string[], + callback: (streamId?: string | boolean) => void, + ): void; /** * Use this API to monitor the changes of screens and windows on desktop. This is an instance of EventEmitter. @@ -1668,7 +2328,10 @@ declare global { * @param listener {Function(screen?)} The callback that handles the `displayBoundsChanged` event. * - (optional) screen {screen} screen object */ - on(event: "displayBoundsChanged", listener: (screen: NWJS_Helpers.screen) => any): this; + on( + event: "displayBoundsChanged", + listener: (screen: NWJS_Helpers.screen) => any, + ): this; /** * Emitted when a new screen added. @@ -1677,7 +2340,10 @@ declare global { * @param listener {Function(screen?)} The callback that handles the `displayAdded` event. * - (optional) screen {screen} screen object */ - on(event: "displayAdded ", listener: (screen: NWJS_Helpers.screen) => any): this; + on( + event: "displayAdded", + listener: (screen: NWJS_Helpers.screen) => any, + ): this; /** * Emitted when existing screen removed. @@ -1686,7 +2352,10 @@ declare global { * @param listener {Function(screen?)} The callback that handles the `displayRemoved` event. * - (optional) screen {screen} screen object */ - on(event: "displayRemoved ", listener: (screen: NWJS_Helpers.screen) => any): this; + on( + event: "displayRemoved", + listener: (screen: NWJS_Helpers.screen) => any, + ): this; } /* Shell: http://docs.nwjs.io/en/latest/References/Shell/ */ @@ -1819,7 +2488,7 @@ declare global { * @param event {string} Event name * @param listener {Function} The callback that handles the `click` event. */ - on(event: "click ", listener: () => any): this; + on(event: "click", listener: () => any): this; } /* Window: http://docs.nwjs.io/en/latest/References/Window/ */ @@ -1856,14 +2525,54 @@ declare global { ): void; } + /* JavaScript Contexts: http://docs.nwjs.io/en/latest/For%20Users/Advanced/JavaScript%20Contexts%20in%20NW.js/ */ export function require(id: string): any; + /** + * The global object of the Node context. Same as `global` in the browser context. + */ + export var global: typeof globalThis; + + /** + * The `process` module of Node.js. Same as `process` in the browser context. + */ + export var process: NodeJS.Process; + export var App: App; export var Clipboard: Clipboard; export var Screen: Screen; export var Shell: Shell; export var Window: Window; } + + /* Changes to Node: http://docs.nwjs.io/en/latest/References/Changes%20to%20Node/ */ + namespace NodeJS { + interface ProcessVersions { + /** + * NW.js's version. + */ + nw: string; + + /** + * The Chromium version which NW.js is based on. + */ + chromium: string; + + /** + * `"sdk"` when the binary is a SDK build, or `"normal"` when the binary is a normal build. + */ + "nw-flavor": "sdk" | "normal"; + } + } + + /* Changes to DOM: http://docs.nwjs.io/en/latest/References/Changes%20to%20DOM/ */ + interface File { + /** + * NW.js only. The native path of the selected file. + * Only available in Node frames. + */ + readonly path: string; + } } declare module "nw.gui" { diff --git a/types/nw.js/nw.js-tests.ts b/types/nw.js/nw.js-tests.ts index a4f0f573398755..b5629e435538a3 100644 --- a/types/nw.js/nw.js-tests.ts +++ b/types/nw.js/nw.js-tests.ts @@ -4,11 +4,46 @@ var argv = nw.App.argv; var fullArgv = nw.App.fullArgv; -var filteredArgv = nw.App.filteredArgv; +// `filteredArgv` is a list of RegExp patterns, not plain objects +var filteredArgv: RegExp[] = nw.App.filteredArgv; +filteredArgv.forEach(function(pattern) { + console.log(pattern.test("--url=https://github.com")); +}); var startPath = nw.App.startPath; var dataPath = nw.App.dataPath; var manifest = nw.App.manifest; +// Known manifest fields are typed; unknown `package.json` fields still resolve +console.log(manifest.main, manifest.name, manifest["node-main"], manifest.dependencies); + +// `webview` permissions in the manifest +if (manifest.webview && manifest.webview.partitions) { + manifest.webview.partitions.forEach(function(partition) { + console.log(partition.name, partition.accessible_resources); + }); +} + +var trustedManifest: NWJS_Helpers.Manifest = { + main: "index.html", + name: "my-app", + window: { + title: "My App", + frame: false, + }, + webkit: { + plugin: false, + }, + webview: { + partitions: [ + { + name: "trusted", + accessible_resources: [""], + }, + ], + }, +}; +console.log(trustedManifest); + nw.App.clearCache(); nw.App.clearAppCache("/path/to/manifest_url"); nw.App.closeAllWindows(); @@ -59,7 +94,7 @@ clipboard.clear(); /** * nw.Menu Tests */ -// Create an empty context menu +// Create an empty context menu. The option argument, and its `type` field, are optional var menu = new nw.Menu(); // Add some items @@ -78,6 +113,11 @@ menu.popup(10, 10); for (var i = 0; i < menu.items.length; ++i) { console.log(menu.items[i]); } + +// `type` only accepts "menubar" or "contextmenu" +var contextMenuOption: NWJS_Helpers.MenuOption = { type: "contextmenu" }; +console.log(new nw.Menu(contextMenuOption)); + // Create an empty menubar var menu = new nw.Menu({ type: "menubar" }); @@ -97,6 +137,12 @@ menu.append( // Assign it to `window.menu` to get the menu displayed nw.Window.get().menu = menu; +// Setting the menubar to null removes it +nw.Window.get().menu = null; + +// Mac only: populate the builtin App, Edit and Window menus +menu.createMacBuiltin("My App", { hideEdit: false, hideWindow: true }); + /** * nw.MenuItem Tests */ @@ -144,6 +190,12 @@ item.click = function() { // init must be called once during startup, before any function to nw.Screen can be called nw.Screen.Init(); +var screens: NWJS_Helpers.screen[] = nw.Screen.screens; +screens.forEach(function(screen) { + console.log(screen.id, screen.bounds.width, screen.work_area.height, screen.scaleFactor); + console.log(screen.isBuiltIn, screen.rotation, screen.touchSupport); +}); + var screenCB = { onDisplayBoundsChanged: function(screen: any) { console.log("displayBoundsChanged", screen); @@ -186,18 +238,21 @@ nw.Screen.chooseDesktopMedia(["window", "screen"], function(streamId) { var dcm = nw.Screen.DesktopCaptureMonitor; nw.Screen.Init(); dcm.on("added", function(id, name, order, type, primary) { + // `registerStream` returns the stream id to pass as `chromeMediaSourceId` + var registeredStreamId: string = dcm.registerStream(id); + // select first stream and shutdown var constraints = { audio: { mandatory: { chromeMediaSource: "system", - chromeMediaSourceId: dcm.registerStream(id), + chromeMediaSourceId: registeredStreamId, }, }, video: { mandatory: { chromeMediaSource: "desktop", - chromeMediaSourceId: dcm.registerStream(id), + chromeMediaSourceId: registeredStreamId, }, }, }; @@ -212,6 +267,7 @@ dcm.on("orderchanged", function(id, new_order, old_order) {}); dcm.on("namechanged", function(id, name) {}); dcm.on("thumbnailchanged", function(id, thumbnail) {}); dcm.start(true, true); +console.log(dcm.started); /** * nw.Shell Tests @@ -304,6 +360,19 @@ nw.Window.open("https://github.com", {}, function(new_win) { }); }); +// The opened window is not focused by default; `focus` opts back in +nw.Window.open("https://github.com/nwjs/nw.js", { + position: "center", + width: 901, + height: 127, + focus: true, + new_instance: true, + mixed_context: true, + inject_js_start: "inject_start.js", + inject_js_end: "inject_end.js", + id: "main-window", +}); + // Get the current window var win = nw.Window.get(); @@ -340,6 +409,24 @@ win.capturePage( { format: "png", datatype: "buffer" }, ); +// captureScreenshot with a callback... +win.captureScreenshot({ fullSize: true, format: "png" }, function(err, data) { + if (err !== null) { + console.error(err); + return; + } + console.log(data); +}); + +// ...or without one, in which case it resolves with the base64 encoded image +win.captureScreenshot({ + format: "jpeg", + quality: 80, + clip: { x: 0, y: 0, width: 800, height: 600, scale: 1 }, +}).then(function(data: string) { + console.log(data); +}); + // Open a new window. nw.Window.open("popup.html", {}, function(win) { // Release the 'win' object here after the new window is closed. @@ -377,5 +464,64 @@ nw.Window.get().on("new-win-policy", function(frame, url, policy) { nw.Shell.openExternal(url); }); +nw.Window.get().on("navigation", function(frame, url, policy) { + if (policy) policy.ignore(); +}); + +/** + * Tag Tests + */ +declare var webviewEl: NWJS_Helpers.webview; + +// Show the DevTools of the guest contents in a new window... +webviewEl.showDevTools(true); + +// ...or inside another, trusted, webview +declare var devtoolsContainer: NWJS_Helpers.webview; +webviewEl.showDevTools(true, devtoolsContainer); + +webviewEl.inspectElementAt(120, 240); + +// The store id can be passed to the chrome.cookies API +var cookieStoreId: string = webviewEl.getCookieStoreId(); +console.log(cookieStoreId); + +// `mainWorld` can be added to the InjectDetails of webview.executeScript() +var injectDetails: NWJS_Helpers.WebviewInjectDetails = { mainWorld: true }; +console.log(injectDetails); + +/** + * JavaScript Contexts Tests + */ // Require a package var fs = nw.require("fs"); + +// The Node context's global object and process module +var nodeGlobal = nw.global; +console.log(nodeGlobal); + +console.log(nw.process.versions.nw); +console.log(nw.process.versions.chromium); +console.log(nw.process.versions["nw-flavor"]); +console.log(process.versions.nw, process.versions["nw-flavor"]); + +/** + * Changes to DOM Tests + */ +var fileinput = document.querySelector("input[type=file]") as HTMLInputElement; + +// The value contains the native path of the local file +var nativePath: string = fileinput.value; +console.log(nativePath); + +// And so does `path` on each item of `files` +var files = fileinput.files; +if (files !== null) { + for (var f = 0; f < files.length; ++f) { + console.log(files[f].path); + } +} + +// The nw* attributes are content attributes with no reflected IDL property +fileinput.setAttribute("nwsaveas", "filename.txt"); +fileinput.setAttribute("nwworkingdir", "/home/path/"); diff --git a/types/nw.js/package.json b/types/nw.js/package.json index 773847d5f76349..87d2b7fb6502c1 100644 --- a/types/nw.js/package.json +++ b/types/nw.js/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "@types/nw.js", - "version": "0.92.9999", + "version": "0.115.9999", "nonNpm": true, "nonNpmDescription": "nw.js", "projects": [