@openfin/core 33.76.31 → 33.76.36

package/src/api/webcontents/main.js

@@ -8,32 +8,350 @@ class WebContents extends base_1.EmitterBase {
         this.identity = identity;
         this.entityType = entityType;
     }
+    /**
+     * Gets a base64 encoded image of all or part of the WebContents.
+     * @function capturePage
+     * @param options Options for the capturePage call.
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     *
+     * View:
+     * ```js
+     * const view = fin.View.getCurrentSync();
+     *
+     * // PNG image of a full visible View
+     * console.log(await view.capturePage());
+     *
+     * // Low-quality JPEG image of a defined visible area of the view
+     * const options = {
+     *     area: {
+     *         height: 100,
+     *         width: 100,
+     *         x: 10,
+     *         y: 10,
+     *     },
+     *     format: 'jpg',
+     *     quality: 20
+     * }
+     * console.log(await view.capturePage(options));
+     * ```
+     *
+     * Window:
+     * ```js
+     * const wnd = await fin.Window.getCurrent();
+     *
+     * // PNG image of a full visible window
+     * console.log(await wnd.capturePage());
+     *
+     * // Low-quality JPEG image of a defined visible area of the window
+     * const options = {
+     *     area: {
+     *         height: 100,
+     *         width: 100,
+     *         x: 10,
+     *         y: 10,
+     *     },
+     *     format: 'jpg',
+     *     quality: 20
+     * }
+     * console.log(await wnd.capturePage(options));
+     * ```
+     */
     capturePage(options) {
         return this.wire.sendAction('capture-page', { options, ...this.identity }).then(({ payload }) => payload.data);
     }
+    /**
+     * Executes Javascript on the WebContents, restricted to contents you own or contents owned by
+     * applications you have created.
+     * @param code JavaScript code to be executed on the view.
+     * @function executeJavaScript
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     * async function executeJavaScript(code) {
+     *     const view = await fin.View.wrap({uuid: 'uuid', name: 'view name'});
+     *     return await view.executeJavaScript(code);
+     * }
+     *
+     * executeJavaScript(`console.log('Hello, Openfin')`).then(() => console.log('Javascript excuted')).catch(err => console.log(err));
+     * ```
+     *
+     * Window:
+     * ```js
+     * async function executeJavaScript(code) {
+     *     const app = await fin.Application.start({
+     *         name: 'myApp',
+     *         uuid: 'app-1',
+     *         url: 'https://cdn.openfin.co/docs/javascript/stable/tutorial-Window.executeJavaScript.html',
+     *         autoShow: true
+     *     });
+     *     const win = await app.getWindow();
+     *     return await win.executeJavaScript(code);
+     * }
+     *
+     * executeJavaScript(`console.log('Hello, Openfin')`).then(() => console.log('Javascript excuted')).catch(err => console.log(err));
+     * ```
+     */
     executeJavaScript(code) {
         return this.wire
             .sendAction('execute-javascript-in-window', { ...this.identity, code })
             .then(({ payload }) => payload.data);
     }
+    /**
+     * Returns the zoom level of the WebContents.
+     * @function getZoomLevel
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     * async function getZoomLevel() {
+     *     const view = await fin.View.getCurrent();
+     *     return await view.getZoomLevel();
+     * }
+     *
+     * getZoomLevel().then(zoomLevel => console.log(zoomLevel)).catch(err => console.log(err));
+     * ```
+     *
+     * Window:
+     * ```js
+     * async function createWin() {
+     *     const app = await fin.Application.start({
+     *         name: 'myApp',
+     *         uuid: 'app-1',
+     *         url: 'https://cdn.openfin.co/docs/javascript/stable/tutorial-Window.getZoomLevel.html',
+     *         autoShow: true
+     *     });
+     *     return await app.getWindow();
+     * }
+     *
+     * async function getZoomLevel() {
+     *     const win = await createWin();
+     *     return await win.getZoomLevel();
+     * }
+     *
+     * getZoomLevel().then(zoomLevel => console.log(zoomLevel)).catch(err => console.log(err));
+     * ```
+     */
     getZoomLevel() {
         return this.wire.sendAction('get-zoom-level', this.identity).then(({ payload }) => payload.data);
     }
+    /**
+     * Sets the zoom level of the WebContents.
+     * @param level The zoom level
+     * @function setZoomLevel
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     * async function setZoomLevel(number) {
+     *     const view = await fin.View.getCurrent();
+     *     return await view.setZoomLevel(number);
+     * }
+     *
+     * setZoomLevel(4).then(() => console.log('Setting a  zoom level')).catch(err => console.log(err));
+     * ```
+     *
+     * Window:
+     * ```js
+     * async function createWin() {
+     *     const app = await fin.Application.start({
+     *         name: 'myApp',
+     *         uuid: 'app-1',
+     *         url: 'https://cdn.openfin.co/docs/javascript/stable/tutorial-Window.setZoomLevel.html',
+     *         autoShow: true
+     *     });
+     *     return await app.getWindow();
+     * }
+     *
+     * async function setZoomLevel(number) {
+     *     const win = await createWin();
+     *     return await win.setZoomLevel(number);
+     * }
+     *
+     * setZoomLevel(4).then(() => console.log('Setting a  zoom level')).catch(err => console.log(err));
+     * ```
+     */
     setZoomLevel(level) {
         return this.wire.sendAction('set-zoom-level', { ...this.identity, level }).then(() => undefined);
     }
+    /**
+     * Navigates the WebContents to a specified URL.
+     *
+     * @remarks The url must contain the protocol prefix such as http:// or https://.
+     * @param url - The URL to navigate the WebContents to.
+     *
+     * @function navigate
+     * @memberof View
+     * @instance
+     * @example
+     * View:
+     * ```js
+     * async function createView() {
+     *     const me = await fin.Window.getCurrent();
+     *     return fin.View.create({
+     *         name: 'viewName',
+     *         target: me.identity,
+     *         bounds: {top: 10, left: 10, width: 200, height: 200}
+     *     });
+     * }
+     *
+     * createView()
+     *     .then(view => view.navigate('https://example.com'))
+     *     .then(() => console.log('navigation complete'))
+     *     .catch(err => console.log(err));
+     * ```
+     *
+     * Window:
+     * ```js
+     * async function navigate() {
+     *     const win = await fin.Window.getCurrent();
+     *     return await win.navigate('https://cdn.openfin.co/docs/javascript/stable/tutorial-Window.navigate.html');
+     * }
+     * navigate().then(() => console.log('Navigate to tutorial')).catch(err => console.log(err));
+     * ```
+     * @experimental
+     */
     navigate(url) {
         return this.wire.sendAction('navigate-window', { ...this.identity, url }).then(() => undefined);
     }
+    /**
+     * Navigates the WebContents back one page.
+     * @function navigateBack
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     * async function navigateBack() {
+     *     const view = await fin.View.wrap({ name: 'testapp-view', uuid: 'testapp' });
+     *     await view.navigate('https://www.google.com');
+     *     return await view.navigateBack();
+     * }
+     * navigateBack().then(() => console.log('Navigated back')).catch(err => console.log(err));
+     * ```
+     *
+     * Window:
+     * ```js
+     * async function navigateBack() {
+     *     const win = await fin.Window.wrap({ name: 'testapp', uuid: 'testapp' });
+     *     await win.navigate('https://www.google.com');
+     *     return await win.navigateBack();
+     * }
+     * navigateBack().then(() => console.log('Navigated back')).catch(err => console.log(err));
+     * ```
+     */
     navigateBack() {
         return this.wire.sendAction('navigate-window-back', { ...this.identity }).then(() => undefined);
     }
+    /**
+     * Navigates the WebContents forward one page.
+     * @function navigateForward
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     * async function navigateForward() {
+     *     const view = await fin.View.getCurrent();
+     *     await view.navigate('https://www.google.com');
+     *     await view.navigateBack();
+     *     return await view.navigateForward();
+     * }
+     * navigateForward().then(() => console.log('Navigated forward')).catch(err => console.log(err));
+     * ```
+     *
+     * Window:
+     * ```js
+     * async function navigateForward() {
+     *     const win = await fin.Window.getCurrent();
+     *     await win.navigate('https://www.google.com');
+     *     await win.navigateBack();
+     *     return await win.navigateForward();
+     * }
+     * navigateForward().then(() => console.log('Navigated forward')).catch(err => console.log(err));
+     * ```
+     */
     async navigateForward() {
         await this.wire.sendAction('navigate-window-forward', { ...this.identity });
     }
+    /**
+     * Stops any current navigation the WebContents is performing.
+     * @function stopNavigation
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     * async function stopNavigation() {
+     *     const view = await fin.View.wrap({ name: 'testapp-view', uuid: 'testapp' });
+     *     await view.navigate('https://www.google.com');
+     *     return await view.stopNavigation();
+     * }
+     * stopNavigation().then(() => console.log('you shall not navigate')).catch(err => console.log(err));
+     * ```
+     *
+     * Window:
+     * ```js
+     * async function stopNavigation() {
+     *     const win = await fin.Window.wrap({ name: 'testapp', uuid: 'testapp' });
+     *     await win.navigate('https://www.google.com');
+     *     return await win.stopNavigation();
+     * }
+     * stopNavigation().then(() => console.log('you shall not navigate')).catch(err => console.log(err));
+     * ```
+     */
     stopNavigation() {
         return this.wire.sendAction('stop-window-navigation', { ...this.identity }).then(() => undefined);
     }
+    /**
+     * Reloads the WebContents
+     * @function reload
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     * async function reload() {
+     * 	const view = await fin.View.getCurrent();
+     *     return await view.reload();
+     * }
+     *
+     * reload().then(() => {
+     * 		console.log('Reloaded view')
+     * }).catch(err => console.log(err));
+     * ```
+     *
+     * Window:
+     * ```js
+     * async function reloadWindow() {
+     * 		const app = await fin.Application.start({
+     * 				name: 'myApp',
+     * 				uuid: 'app-1',
+     * 				url: 'https://cdn.openfin.co/docs/javascript/stable/tutorial-Window.reload.html',
+     * 				autoShow: true
+     * 		});
+     * 		const win = await app.getWindow();
+     *     return await win.reload();
+     * }
+     *
+     * reloadWindow().then(() => {
+     * 		console.log('Reloaded window')
+     * }).catch(err => console.log(err));
+     * ```
+     */
     reload(ignoreCache = false) {
         return this.wire
             .sendAction('reload-window', {
@@ -42,43 +360,615 @@ class WebContents extends base_1.EmitterBase {
         })
             .then(() => undefined);
     }
+    /**
+     * Prints the WebContents.
+     * @param options Printer Options
+     * @function print
+     * @memberOf View
+     * @instance
+     *
+     * @remarks When `silent` is set to `true`, the API will pick the system's default printer if deviceName
+     * is empty and the default settings for printing.
+     *
+     * Use the CSS style `page-break-before: always;` to force print to a new page.
+     *
+     * @example
+     * ```js
+     * const view = fin.View.getCurrentSync();
+     *
+     * view.print({ silent: false, deviceName: 'system-printer-name' }).then(() => {
+     *     console.log('print call has been sent to the system');
+     * });
+     * ```
+     */
     print(options = {}) {
         return this.wire.sendAction('print', { ...this.identity, options }).then(() => undefined);
     }
+    /**
+     * Find and highlight text on a page.
+     * @param searchTerm Term to find in page
+     * @param options Search options
+     * @function findInPage
+     * @memberOf View
+     * @instance
+     *
+     * @remarks By default, each subsequent call will highlight the next text that matches the search term.
+     *
+     * Returns a promise with the results for the request. By subscribing to the
+     * found-in-page event, you can get the results of this call as well.
+     *
+     * @example
+     * View:
+     * ```js
+     * const view = fin.View.getCurrentSync();
+     *
+     * //By subscribing to the 'found in page' event we can get the results of each findInPage call made.
+     * view.addListener('found-in-page', (event) => {
+     *     console.log(event);
+     * });
+     *
+     * // The promise also returns the results for the request
+     * view.findInPage('a').then((result) => {
+     *     console.log(result)
+     * });
+     * ```
+     *
+     * Window:
+     * ```js
+     * const win = fin.Window.getCurrentSync();
+     *
+     * //By subscribing to the 'found in page' event we can get the results of each findInPage call made.
+     * win.addListener('found-in-page', (event) => {
+     *     console.log(event);
+     * });
+     *
+     * // The promise also returns the results for the request
+     * win.findInPage('a').then((result) => {
+     *     console.log(result)
+     * });
+     * ```
+     */
     findInPage(searchTerm, options) {
         return this.wire
             .sendAction('find-in-page', { ...this.identity, searchTerm, options })
             .then(({ payload }) => payload.data);
     }
+    /**
+     * Stop a {@link View#findInPage findInPage} call by specifying any of these actions:
+     *
+     * * clearSelection - Clear the selection.
+     * * keepSelection - Translate the selection into a normal selection.
+     * * activateSelection - Focus and click the selection node.
+     *
+     * @example
+     * View:
+     * ```js
+     * const view = fin.View.getCurrentSync();
+     *
+     * view.addListener('found-in-page', (event) => {
+     *     setTimeout(() => {
+     *         view.stopFindInPage('clearSelection');
+     *     }, 5000);
+     * });
+     *
+     * view.findInPage('a').then(results => {
+     *     console.log(results);
+     * });
+     * ```
+     *
+     * Window:
+     * ```js
+     * const win = fin.Window.getCurrentSync();
+     *
+     * win.addListener('found-in-page', (event) => {
+     *     setTimeout(() => {
+     *         win.stopFindInPage('clearSelection');
+     *     }, 5000);
+     * });
+     *
+     * win.findInPage('a').then(results => {
+     *     console.log(results);
+     * });
+     * ```
+     */
     stopFindInPage(action) {
         return this.wire.sendAction('stop-find-in-page', { ...this.identity, action }).then(() => undefined);
     }
+    /**
+     * Returns an array with all system printers
+     * @deprecated use System.getPrinters instead
+     * @function getPrinters
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     * const view = fin.View.getCurrentSync();
+     *
+     * view.getPrinters()
+     *     .then((printers) => {
+     *         printers.forEach((printer) => {
+     *             if (printer.isDefault) {
+     *                 console.log(printer);
+     *             }
+     *         });
+     *     })
+     *     .catch((err) => {
+     *         console.log(err);
+     *     });
+     * ```
+     *
+     * Window:
+     * ```js
+     * const win = fin.Window.getCurrentSync();
+     *
+     * win.getPrinters()
+     *     .then((printers) => {
+     *         printers.forEach((printer) => {
+     *             if (printer.isDefault) {
+     *                 console.log(printer);
+     *             }
+     *         });
+     *     })
+     *     .catch((err) => {
+     *         console.log(err);
+     *     });
+     * ```
+     */
     getPrinters() {
         return this.wire.sendAction('get-printers', { ...this.identity }).then(({ payload }) => payload.data);
     }
+    /**
+     * Gives focus to the WebContents.
+     *
+     * @function focus
+     * @emits focused
+     * @memberOf Window
+     * @instance
+     * @example
+     * ```js
+     * async function focusWindow() {
+     *     const app = await fin.Application.start({
+     *         name: 'myApp',
+     *         uuid: 'app-1',
+     *         url: 'https://cdn.openfin.co/docs/javascript/stable/tutorial-Window.focus.html',
+     *         autoShow: true
+     *     });
+     *     const win = await app.getWindow();
+     *     return await win.focus();
+     * }
+     *
+     * focusWindow().then(() => console.log('Window focused')).catch(err => console.log(err));
+     * ```
+     */
     async focus({ emitSynthFocused } = { emitSynthFocused: true }) {
         await this.wire.sendAction('focus-window', { emitSynthFocused, ...this.identity });
     }
+    /**
+     * Shows the Chromium Developer Tools
+     * @function showDeveloperTools
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     * async function showDeveloperTools() {
+     *     const view = await fin.View.getCurrent();
+     *     return view.showDeveloperTools();
+     * }
+     *
+     * showDevelopertools()
+     * .then(() => console.log('Showing dev tools'))
+     * .catch(err => console.error(err));
+     * ```
+     *
+     * Window:
+     * ```js
+     * async function showDeveloperTools() {
+     *     const win = await fin.Window.getCurrent();
+     *     return win.showDeveloperTools();
+     * }
+     *
+     * showDevelopertools()
+     * .then(() => console.log('Showing dev tools'))
+     * .catch(err => console.error(err));
+     * ```
+     */
     async showDeveloperTools() {
         // Note this hits the system action map in core state for legacy reasons.
         await this.wire.sendAction('show-developer-tools', this.identity);
     }
+    /**
+     * Retrieves the process information associated with a WebContents.
+     *
+     * @remarks This includes any iframes associated with the WebContents
+     *
+     * @function getProcessInfo
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     *     const view = await fin.View.getCurrent();
+     *     const processInfo = await view.getProcessInfo();
+     * ```
+     *
+     * Window:
+     * ```js
+     *     const win = await fin.Window.getCurrent();
+     *     const processInfo = await win.getProcessInfo();
+     * ```
+     */
     async getProcessInfo() {
         const { payload: { data } } = await this.wire.sendAction('get-process-info', this.identity);
         return data;
     }
+    /**
+     * Retrieves information on all Shared Workers.
+     * @function getSharedWorkers
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     *     const view = await fin.View.create({
+     *         name: 'viewName',
+     *         target: fin.me.identity,
+     *         bounds: {top: 10, left: 10, width: 200, height: 200}
+     *     });
+     *
+     *     await view.navigate('http://mdn.github.io/simple-shared-worker/index2.html');
+     *
+     *     const sharedWorkers = await view.getSharedWorkers();
+     * ```
+     *
+     * Window:
+     * ```js
+     *     const winOption = {
+     *         name:'child',
+     *         defaultWidth: 300,
+     *         defaultHeight: 300,
+     *         url: 'http://mdn.github.io/simple-shared-worker/index2.html',
+     *         frame: true,
+     *         autoShow: true
+     *     };
+     *     const win = await fin.Window.create(winOption);
+     *     const sharedWorkers = await win.getSharedWorkers();
+     * ```
+     */
     async getSharedWorkers() {
         return this.wire.sendAction('get-shared-workers', this.identity).then(({ payload }) => payload.data);
     }
+    /**
+     * Opens the developer tools for the shared worker context.
+     * @function inspectSharedWorker
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     *     const view = await fin.View.create({
+     *         name: 'viewName',
+     *         target: fin.me.identity,
+     *         bounds: {top: 10, left: 10, width: 200, height: 200}
+     *     });
+     *
+     *     await view.navigate('http://mdn.github.io/simple-shared-worker/index2.html');
+     *
+     *     await view.inspectSharedWorker();
+     * ```
+     *
+     * Example:
+     * ```js
+     *     const winOption = {
+     *         name:'child',
+     *         defaultWidth: 300,
+     *         defaultHeight: 300,
+     *         url: 'http://mdn.github.io/simple-shared-worker/index2.html',
+     *         frame: true,
+     *         autoShow: true
+     *     };
+     *     const win = await fin.Window.create(winOption);
+     *     await win.inspectSharedWorker();
+     * ```
+     */
     async inspectSharedWorker() {
         await this.wire.sendAction('inspect-shared-worker', { ...this.identity });
     }
+    /**
+     * Inspects the shared worker based on its ID.
+     * @param workerId - The id of the shared worker.
+     * @function inspectSharedWorkerById
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     *     const view = await fin.View.create({
+     *         name: 'viewName',
+     *         target: fin.me.identity,
+     *         bounds: {top: 10, left: 10, width: 200, height: 200}
+     *     });
+     *
+     *     await view.navigate('http://mdn.github.io/simple-shared-worker/index2.html');
+     *
+     *     const sharedWorkers = await view.getSharedWorkers();
+     *     await view.inspectSharedWorkerById(sharedWorkers[0].id);
+     * ```
+     *
+     * Window:
+     * ```js
+     *     const winOption = {
+     *         name:'child',
+     *         defaultWidth: 300,
+     *         defaultHeight: 300,
+     *         url: 'http://mdn.github.io/simple-shared-worker/index2.html',
+     *         frame: true,
+     *         autoShow: true
+     *     };
+     *     const win = await fin.Window.create(winOption);
+     *     const sharedWorkers = await win.getSharedWorkers();
+     *     await win.inspectSharedWorkerById(sharedWorkers[0].id);
+     * ```
+     */
     async inspectSharedWorkerById(workerId) {
         await this.wire.sendAction('inspect-shared-worker-by-id', { ...this.identity, workerId });
     }
+    /**
+     * Opens the developer tools for the service worker context.
+     * @function inspectServiceWorker
+     * @memberOf View
+     * @instance
+     *
+     * @example
+     * View:
+     * ```js
+     *     const view = await fin.View.create({
+     *         name: 'viewName',
+     *         target: fin.me.identity,
+     *         bounds: {top: 10, left: 10, width: 200, height: 200}
+     *     });
+     *
+     *     await view.navigate('http://googlechrome.github.io/samples/service-worker/basic/index.html');
+     *
+     *     await view.inspectServiceWorker();
+     * ```
+     *
+     * Window:
+     * ```js
+     *     const winOption = {
+     *         name:'child',
+     *         defaultWidth: 300,
+     *         defaultHeight: 300,
+     *         url: 'http://googlechrome.github.io/samples/service-worker/basic/index.html',
+     *         frame: true,
+     *         autoShow: true
+     *     };
+     *     const win = await fin.Window.create(winOption);
+     *     await win.inspectServiceWorker();
+     * ```
+     */
     async inspectServiceWorker() {
         await this.wire.sendAction('inspect-service-worker', { ...this.identity });
     }
+    /**
+     * Shows a popup window.
+     *
+     * @remarks If this WebContents is a view and its attached window has a popup open, this will close it.
+     *
+     * Shows a popup window. Including a `name` in `options` will attempt to show an existing window as a popup, if
+     * that window doesn't exist or no `name` is included a window will be created. If the caller view or the caller
+     * view's parent window currently has a popup window open, calling `showPopupWindow` again will dismiss the currently
+     * open popup window before showing the new popup window. Also, if the caller view is destroyed or detached, the popup
+     * will be dismissed.
+     *
+     * NOTE: in the case where the window being shown as a popup needs to be created, it is a child of the caller view's parent window.
+     *
+     * @example
+     *
+     * Create and show a single-use popup window that returns a single result to the caller. `initialOptions` allows
+     * us to pass window options to the popup window that will be created. `resultDispatchBehavior: 'close'` ensures
+     * that once the popup window calls `dispatchPopupResult` it is closed. `blurBehavior: 'close'` will yield a dismissed
+     * result should the popup window lose focus.
+     *
+     * ```js
+     * const result = await fin.me.showPopupWindow({
+     *     initialOptions: {
+     *         frame: false
+     *     },
+     *     url: '<my_popup_url>',
+     *     resultDispatchBehavior: 'close',
+     *     blurBehavior: 'close',
+     *     focus: true,
+     *     height: 300,
+     *     width: 300,
+     *     x: 0,
+     *     y: 0
+     * });
+     * ```
+     *
+     * Same as above but using an existing window as a popup by referencing its `name`:
+     *
+     * Note: if a window with the `name` provided doesn't exist, it will be created.
+     *
+     * ```js
+     * const result = await fin.me.showPopupWindow({
+     *     initialOptions: {
+     *         frame: true
+     *     },
+     *     name: 'my-popup', // shows the 'my-popup' window if it exists, otherwise creates it
+     *     url: '<my_popup_url>', // navigates to this url if it doesn't match the location.href of the 'my-popup' window
+     *     resultDispatchBehavior: 'close',
+     *     blurBehavior: 'close',
+     *     focus: true,
+     *     hideOnClose: true, // persist window on 'dismissed' result, alternatively change onResultDispatch and blurBehavior to 'hide'
+     *     height: 300,
+     *     width: 300,
+     *     x: 0,
+     *     y: 0
+     * });
+     * ```
+     *
+     * Create and show a popup window that is able to return multiple results to the caller via an `onPopupResult` callback. Each
+     * time the popup window calls `dispatchPopupResult`, the callback will be executed on the result. Once the popup window is
+     * closed or hidden, the `showPopupWindow` promise will resolve with a `dismissed` result that will include the most recently
+     * dispatched result as `lastDispatchResult`:
+     *
+     * ```js
+     * const popupResultCallback = (payload) => {
+     *        if (payload.result === 'clicked') {
+     *            if (payload.data.topic === 'color-changed') {
+     *                // do something like
+     *                // setColor(payload.data.value);
+     *            }
+     *        }
+     * };
+     *
+     * await fin.me.showPopupWindow({
+     *     initialOptions: {
+     *         frame: false
+     *     },
+     *     url: '<my_popup_url>',
+     *     resultDispatchBehavior: 'none',
+     *     blurBehavior: 'close',
+     *     focus: true,
+     *     height: 300,
+     *     width: 300,
+     *     x: 0,
+     *     y: 0,
+     *     onPopupResult: popupResultCallback
+     * });
+     * ```
+     *
+     * Same as above but using an existing window as a popup:
+     *
+     * ```js
+     * const popupResultCallback = (payload) => {
+     *        if (payload.result === 'clicked') {
+     *            if (payload.data.topic === 'color-changed') {
+     *                // do something like
+     *                // setColor(payload.data.value);
+     *            }
+     *        }
+     * };
+     *
+     * await fin.me.showPopupWindow({
+     *     initialOptions: {
+     *         frame: false
+     *     },
+     *     name: 'my-popup', // shows the 'my-popup' window if it exists, otherwise creates it
+     *     url: '<my_popup_url>', // navigates to this url if it doesn't match the location.href of the 'my-popup' window
+     *     resultDispatchBehavior: 'none',
+     *     blurBehavior: 'hide',
+     *     focus: true,
+     *     hideOnClose: true, // we can just use this or we can change blurBehavior to 'hide'
+     *     height: 300,
+     *     width: 300,
+     *     x: 0,
+     *     y: 0,
+     *     onPopupResult: popupResultCallback
+     * });
+     * ```
+     *
+     * Create or show a popup window that disables user movement (positioning and resizing) in the caller
+     * view's parent window by using `blurBehavior: 'modal'`:
+     *
+     * ```js
+     * const result = await fin.me.showPopupWindow({
+     *     initialOptions: {
+     *         frame: false
+     *     },
+     *     url: '<my_popup_url>',
+     *     resultDispatchBehavior: 'close',
+     *     blurBehavior: 'modal',
+     *     focus: true,
+     *     height: 300,
+     *     width: 300,
+     *     x: 0,
+     *     y: 0
+     * });
+     * ```
+     *
+     * Create a popup window as a modal:
+     *
+     * Note: The only way to ensure true modal behavior is to create the window being shown as a popup with a
+     * `modalParentIdentity` that uses the caller view's parent window identity.
+     *
+     * ```js
+     * const result = await fin.me.showPopupWindow({
+     *     initialOptions: {
+     *         frame: false,
+     *         modalParentIdentity: fin.me.identity
+     *     },
+     *     url: '<my_popup_url>',
+     *     resultDispatchBehavior: 'close',
+     *     blurBehavior: 'modal',
+     *     focus: true,
+     *     height: 300,
+     *     width: 300,
+     *     x: 0,
+     *     y: 0
+     * });
+     * ```
+     *
+     * Pass data to a popup window that is available when the popup is shown.
+     *
+     * Note: this is just one example for a use of `additionalOptions`, it can be used to update any updatable
+     * window options when creating or showing an existing window as a popup.
+     *
+     * ```js
+     * const result = await fin.me.showPopupWindow({
+     *     additionalOptions: {
+     *         customData: {
+     *             foo: 'bar'
+     *         }
+     *     },
+     *     url: '<my_popup_url>',
+     *     resultDispatchBehavior: 'close',
+     *     blurBehavior: 'close',
+     *     focus: true,
+     *     height: 300,
+     *     width: 300,
+     *     x: 0,
+     *     y: 0
+     * });
+     *
+     * // Access from the popup window context like so:
+     * const { customData } = await fin.me.getOptions();
+     * const { foo } = customData;
+     * ```
+     *
+     * Execute a callback on the popup's OpenFin window when the popup is shown:
+     *
+     * ```js
+     * const popupWindowCallback = async (win) => {
+     *     await win.flash();
+     * };
+     *
+     * const result = await fin.me.showPopupWindow({
+     *     url: '<my_popup_url>',
+     *     resultDispatchBehavior: 'close',
+     *     blurBehavior: 'close',
+     *     focus: true,
+     *     height: 300,
+     *     width: 300,
+     *     x: 0,
+     *     y: 0,
+     *     onPopupReady: popupWindowCallback;
+     * });
+     * ```
+     * @function showPopupWindow
+     * @memberOf View
+     * @instance
+     * @param options
+     *
+     */
     async showPopupWindow(options) {
         this.wire.sendAction(`${this.entityType}-show-popup-window`, this.identity).catch(() => {
             // we do not want to expose this error, just continue if this analytics-only call fails