@openfin/core 33.76.31 → 33.76.36

package/src/api/view/Instance.js

@@ -177,19 +177,19 @@ const window_1 = require("../window");
  * really no need to provide it.
  */
 /**
- * @classdesc A View can be used to embed additional web content into a Window.
+ * A View can be used to embed additional web content into a Window.
  * It is like a child window, except it is positioned relative to its owning window.
- * It has the ability to listen for <a href="tutorial-View.EventEmitter.html">View-specific events</a>.
+ * It has the ability to listen for {@link OpenFin.ViewEvents View-specific events}.
  *
  * By default, a View will try to share the same renderer process as other Views owned by its parent Application.
- * To change that behavior, see the processAffinity {@link View~options view option}.
+ * To change that behavior, see the processAffinity {@link OpenFin.ViewOptions view option}.
  *
  * A View's lifecycle is tied to its owning window and can be re-attached to a different window at any point during its lifecycle.
- * @class
- * @alias View
- * @hideconstructor
  */
 class View extends main_1.WebContents {
+    /**
+     * @internal
+     */
     constructor(wire, identity) {
         super(wire, identity, 'view');
         this.identity = identity;
@@ -198,170 +198,46 @@ class View extends main_1.WebContents {
             return platform.getClient();
         }));
         /**
-         * Returns the zoom level of the view.
-         * @function getZoomLevel
-         * @memberOf View
-         * @instance
-         * @return {Promise.<number>}
-         * @tutorial View.getZoomLevel
-         */
-        /**
-         * Sets the zoom level of the view.
-         * @param { number } level The zoom level
-         * @function setZoomLevel
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.setZoomLevel
-         */
-        /**
-         * Find and highlight text on a page.
-         * @param { string } searchTerm Term to find in page
-         * @param { FindInPageOptions } options Search options
-         * @function findInPage
-         * @memberOf View
-         * @instance
-         * @return {Promise.<number>}
-         * @tutorial View.findInPage
-         */
-        /**
-         * Stops any findInPage call with the provided action.
-         * @param {string} action
-         * Action to execute when stopping a find in page:<br>
-         * "clearSelection" - Clear the selection.<br>
-         * "keepSelection" - Translate the selection into a normal selection.<br>
-         * "activateSelection" - Focus and click the selection node.<br>
-         * @function stopFindInPage
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.stopFindInPage
-         */
-        /**
-         * Navigates the view to a specified URL. The url must contain the protocol prefix such as http:// or https://.
-         * @param { string } url - The URL to navigate the view to.
-         * @return {Promise.<void>}
-         * @function navigate
-         * @memberof View
-         * @instance
-         * @tutorial View.navigate
-         * @experimental
-         */
-        /**
-         * Navigates the view back one page.
-         * @function navigateBack
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.navigateBack
-         */
-        /**
-         * Navigates the view forward one page.
-         * @function navigateForward
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.navigateForward
-         */
-        /**
-         * Stops any current navigation the view is performing.
-         * @function stopNavigation
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.stopNavigation
-         */
-        /**
-         * Reloads the view current page
-         * @function reload
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.reload
-         */
-        /**
-         * Prints the view's web page
-         * @param { PrintOptions } [options] Printer Options
-         * @function print
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.print
-         */
-        /**
-         * Returns an array with all system printers
-         * @deprecated use System.getPrinters instead
-         * @function getPrinters
-         * @memberOf View
-         * @instance
-         * @return { Promise.Array.<PrinterInfo> }
-         * @tutorial View.getPrinters
-         */
-        /**
-         * Shows the Chromium Developer Tools
-         * @function showDeveloperTools
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.showDeveloperTools
-         */
-        /**
-         * Retrieves the process information associated with a view.
-         * @function getProcessInfo
-         * @memberOf View
-         * @instance
-         * @return {Promise.<EntityProcessDetails>}
-         * @tutorial View.getProcessInfo
-         */
-        /**
-         * Retrieves information on all Shared Workers.
-         * @function getSharedWorkers
-         * @memberOf View
-         * @instance
-         * @return {Promise.Array.<SharedWorkerInfo>}
-         * @tutorial View.getSharedWorkers
-         */
-        /**
-         * Opens the developer tools for the shared worker context.
-         * @function inspectSharedWorker
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.inspectSharedWorker
-         */
-        /**
-         * Inspects the shared worker based on its ID.
-         * @param { string } workerId - The id of the shared worker.
-         * @function inspectSharedWorkerById
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.inspectSharedWorkerById
-         */
-        /**
-         * Opens the developer tools for the service worker context.
-         * @function inspectServiceWorker
-         * @memberOf View
-         * @instance
-         * @return {Promise.<void>}
-         * @tutorial View.inspectServiceWorker
-         */
-        /**
-         * Shows a popup window. If the window this view is currently attached to has a popup open, closes it.
-         * @function showPopupWindow
-         * @memberOf View
-         * @instance
-         * @param {PopupOptions} options
-         * @return {Promise<PopupResult>}
-         * @tutorial View.showPopupWindow
-         */
-        /**
-         * Attaches the current view to a the given window identity.
+         * Attaches the current view to the given window identity.
          * Identity must be the identity of a window in the same application.
          * This detaches the view from its current window, and sets the view to be destroyed when its new window closes.
          * @param target {Identity}
-         * @return {Promise.<void>}
-         * @tutorial View.attach
+         *
+         * @example
+         * ```js
+         * let view;
+         * async function createView() {
+         *     const me = await fin.Window.getCurrent();
+         *     return fin.View.create({
+         *         name: 'viewNameAttach',
+         *         target: me.identity,
+         *         bounds: {top: 10, left: 10, width: 200, height: 200}
+         *     });
+         * }
+         *
+         * async function attachView() {
+         *     view = await createView();
+         *     console.log('View created.');
+         *
+         *     await view.navigate('https://google.com');
+         *     console.log('View navigated to given url.');
+         *
+         *     const winOption = {
+         *         name:'winOptionName',
+         *         defaultWidth: 300,
+         *         defaultHeight: 300,
+         *         url: 'https://cdn.openfin.co/docs/javascript/stable/tutorial-Window.create.html',
+         *         frame: true,
+         *         autoShow: true
+         *     };
+         *     const newWindow = await fin.Window.create(winOption);
+         *     view.attach(newWindow.identity);
+         * }
+         *
+         * attachView()
+         *     .then(() => console.log('View attached to new window.'))
+         *     .catch(err => console.log(err));
+         * ```
          * @experimental
          */
         this.attach = async (target) => {
@@ -369,8 +245,12 @@ class View extends main_1.WebContents {
         };
         /**
          * Destroys the current view
-         * @return {Promise.<void>}
-         * @tutorial View.destroy
+         *
+         * @example
+         * ```js
+         * const view = fin.View.wrapSync({ uuid: 'viewUuid', name: 'viewName' });
+         * view.destroy();
+         * ```
          * @experimental
          */
         this.destroy = async () => {
@@ -378,8 +258,37 @@ class View extends main_1.WebContents {
         };
         /**
          * Shows the current view if it is currently hidden.
-         * @return {Promise.<void>}
-         * @tutorial View.show
+         *
+         * @example
+         * ```js
+         * let view;
+         * async function createView() {
+         *     const me = await fin.Window.getCurrent();
+         *     return fin.View.create({
+         *         name: 'viewNameShow',
+         *         target: me.identity,
+         *         bounds: {top: 10, left: 10, width: 200, height: 200}
+         *     });
+         * }
+         *
+         * async function hideAndShowView() {
+         *     view = await createView();
+         *     console.log('View created.');
+         *
+         *     await view.navigate('https://google.com');
+         *     console.log('View navigated to given url option.');
+         *
+         *     await view.hide();
+         *     console.log("View hidden.");
+         *
+         *     view.show();
+         *     console.log("View shown.");
+         * }
+         *
+         * hideAndShowView()
+         *     .then(() => console.log('View hidden and shown.'))
+         *     .catch(err => console.log(err));
+         * ```
          * @experimental
          */
         this.show = async () => {
@@ -387,8 +296,33 @@ class View extends main_1.WebContents {
         };
         /**
          * Hides the current view if it is currently visible.
-         * @return {Promise.<void>}
-         * @tutorial View.hide
+         *
+         * @example
+         * ```js
+         * let view;
+         * async function createView() {
+         *     const me = await fin.Window.getCurrent();
+         *     return fin.View.create({
+         *         name: 'viewNameHide',
+         *         target: me.identity,
+         *         bounds: {top: 10, left: 10, width: 200, height: 200}
+         *     });
+         * }
+         *
+         * async function hideView() {
+         *     view = await createView();
+         *     console.log('View created.');
+         *
+         *     await view.navigate('https://google.com');
+         *     console.log('View navigated to given url.');
+         *
+         *     await view.hide();
+         * }
+         *
+         * hideView()
+         *     .then(() => console.log('View hidden.'))
+         *     .catch(err => console.log(err));
+         * ```
          * @experimental
          */
         this.hide = async () => {
@@ -397,8 +331,41 @@ class View extends main_1.WebContents {
         /**
          * Sets the bounds (top, left, width, height) of the view relative to its window.
          * @param bounds {ViewBounds}
-         * @return {Promise.<void>}
-         * @tutorial View.setBounds
+         *
+         * @remarks View position is relative to the bounds of the window.
+         * ({top: 0, left: 0} represents the top left corner of the window)
+         *
+         * @example
+         * ```js
+         * let view;
+         * async function createView() {
+         *     const me = await fin.Window.getCurrent();
+         *     return fin.View.create({
+         *         name: 'viewNameSetBounds',
+         *         target: me.identity,
+         *         bounds: {top: 10, left: 10, width: 200, height: 200}
+         *     });
+         * }
+         *
+         * async function setViewBounds() {
+         *     view = await createView();
+         *     console.log('View created.');
+         *
+         *     await view.navigate('https://google.com');
+         *     console.log('View navigated to given url.');
+         *
+         *     await view.setBounds({
+         *         top: 100,
+         *         left: 100,
+         *         width: 300,
+         *         height: 300
+         *     });
+         * }
+         *
+         * setViewBounds()
+         *     .then(() => console.log('View set to new bounds.'))
+         *     .catch(err => console.log(err));
+         * ```
          * @experimental
          */
         this.setBounds = async (bounds) => {
@@ -406,8 +373,29 @@ class View extends main_1.WebContents {
         };
         /**
          * Gets the bounds (top, left, width, height) of the view relative to its window.
-         * @return {Promise.<ViewBounds>}
-         * @tutorial View.getBounds
+         *
+         * @remarks View position is relative to the bounds of the window.
+         * ({top: 0, left: 0} represents the top left corner of the window)
+         *
+         * @example
+         * ```js
+         * const view = await fin.View.create({
+         *     name: 'viewNameSetBounds',
+         *     target: fin.me.identity,
+         *     bounds: {top: 10, left: 10, width: 200, height: 200}
+         * });
+         *
+         * await view.navigate('https://google.com');
+         *
+         * await view.setBounds({
+         *     top: 100,
+         *     left: 100,
+         *     width: 300,
+         *     height: 300
+         * });
+         *
+         * console.log(await view.getBounds());
+         * ```
          * @experimental
          */
         this.getBounds = async () => {
@@ -416,8 +404,33 @@ class View extends main_1.WebContents {
         };
         /**
          * Gets the View's info.
-         * @return {Promise.<ViewInfo>}
-         * @tutorial View.getInfo
+         *
+         * @example
+         * ```js
+         * let view;
+         * async function createView() {
+         *     const me = await fin.Window.getCurrent();
+         *     return fin.View.create({
+         *         name: 'viewNameGetInfo',
+         *         target: me.identity,
+         *         bounds: {top: 10, left: 10, width: 200, height: 200}
+         *     });
+         * }
+         *
+         * async function getViewInfo() {
+         *     view = await createView();
+         *     console.log('View created.');
+         *
+         *     await view.navigate('https://google.com');
+         *     console.log('View navigated to given url.');
+         *
+         *     return view.getInfo();
+         * }
+         *
+         * getViewInfo()
+         *     .then((info) => console.log('View info fetched.', info))
+         *     .catch(err => console.log(err));
+         * ```
          * @experimental
          */
         this.getInfo = async () => {
@@ -426,8 +439,15 @@ class View extends main_1.WebContents {
         };
         /**
          * Retrieves the layout for the window the view is attached to.
-         * @return {Promise.<Layout>}
-         * @tutorial View.getParentLayout
+         *
+         * @example
+         * ```js
+         *     //get the current View
+         *     const view = await fin.View.getCurrent();
+         *
+         *     //get a reference to the Layout for the Window the view is part of
+         *     const layout = await view.getParentLayout();
+         * ```
          * @experimental
          */
         this.getParentLayout = async () => {
@@ -439,8 +459,35 @@ class View extends main_1.WebContents {
         };
         /**
          * Gets the View's options.
-         * @return {Promise<ViewOptions>}
-         * @tutorial View.getOptions
+         *
+         * @example
+         * ```js
+         * let view;
+         * async function createView() {
+         *     const me = await fin.Window.getCurrent();
+         *     return fin.View.create({
+         *         name: 'viewNameGetOptions',
+         *         target: me.identity,
+         *         bounds: {top: 10, left: 10, width: 200, height: 200}
+         *     });
+         * }
+         *
+         * async function getViewOptions() {
+         *     view = await createView();
+         *     console.log('View created.');
+         *
+         *     await view.navigate('https://google.com');
+         *     console.log('View navigated to given url.');
+         *
+         *     const me = await fin.Window.getCurrent();
+         *     view = fin.View.wrapSync({ uuid: me.identity.uuid, name: 'viewNameGetOptions' });
+         *     return view.getOptions();
+         * }
+         *
+         * getViewOptions()
+         *     .then((info) => console.log('View options fetched.', info))
+         *     .catch(err => console.log(err));
+         * ```
          * @experimental
          */
         this.getOptions = async () => {
@@ -448,9 +495,39 @@ class View extends main_1.WebContents {
         };
         /**
          * Updates the view's options.
-         * @param { Partial<ViewOptions> } options
-         * @return {Promise.<void>}
-         * @tutorial View.updateOptions
+         * @param options
+         *
+         * @example
+         * ```js
+         * let view;
+         * async function createView() {
+         *     const me = await fin.Window.getCurrent();
+         *     return fin.View.create({
+         *         url: 'https://google.com',
+         *         name: 'viewNameUpdateOptions',
+         *         target: me.identity,
+         *         bounds: {top: 10, left: 10, width: 200, height: 200}
+         *     });
+         * }
+         *
+         * async function updateViewOptions() {
+         *     view = await createView();
+         *     console.log('View created.');
+         *
+         *     await view.navigate('https://google.com');
+         *     console.log('View navigated to given url option.');
+         *
+         *     const newOptions = { autoResize: {
+         *         width: true,
+         *         horizontal: true
+         *     }};
+         *     return view.updateOptions(newOptions);
+         * }
+         *
+         * updateViewOptions()
+         *     .then(payload => console.log('View options updated: ', payload))
+         *     .catch(err => console.log(err));
+         * ```
          * @experimental
          */
         this.updateOptions = async (options) => {
@@ -458,17 +535,37 @@ class View extends main_1.WebContents {
         };
         /**
          * Retrieves the window the view is currently attached to.
-         * @return {Promise.<_Window>}
+         *
          * @experimental
+         * @example
+         * ```js
+         * const view = fin.View.wrapSync({ uuid: 'viewUuid', name: 'viewName' });
+         * view.getCurrentWindow()
+         *     .then(win => console.log('current window', win))
+         *     .catch(err => console.log(err));)
+         * ```
          */
         this.getCurrentWindow = async () => {
             const { payload: { data } } = await this.wire.sendAction('get-view-window', { ...this.identity });
             return new window_1._Window(this.wire, data);
         };
         /**
-         * Retrieves the current {@link TabStack} of the view if it belongs to one.
-         * @return {Promise<TabStack>} The {@link TabStack} this view belongs to.
+         * Retrieves the current {@link OpenFin.TabStack} of the view if it belongs to one.
+         * @returns this view belongs to.
          * @throws if this view does not belong to a TabStack or if the window has been destroyed.
+         * @example
+         * ```js
+         * if (!fin.me.isView) {
+         *     throw new Error('Not running in a platform View.');
+         * }
+         *
+         * const stack = await fin.me.getCurrentStack();
+         * // Alternatively, you can wrap any view and get the stack from there
+         * // const viewFromSomewhere = fin.View.wrapSync(someView.identity);
+         * // const stack = await viewFromSomewhere.getCurrentStack();
+         * const views = await stack.getViews();
+         * console.log(`Stack contains ${views.length} view(s)`);
+         * ```
          */
         this.getCurrentStack = async () => {
             this.wire.sendAction('view-get-current-stack').catch(() => {
@@ -486,10 +583,21 @@ class View extends main_1.WebContents {
             }
         };
         /**
-         * Triggers the before-unload handler for the View, if one is set. Returns `true` if the handler is trying to prevent the View from unloading, and `false` if it isn't.
-         * Only enabled when setting enableBeforeUnload: true in your View options. If this option is not enabled it will always return false.
-         * @returns {Promise<boolean>}
-         * @tutorial View.triggerBeforeUnload
+         * Triggers the before-unload handler for the View, if one is set.
+         *
+         * @remarks Returns `true` if the handler is trying to prevent the View from unloading, and `false` if it isn't.
+         * Only enabled when setting enableBeforeUnload: true in your View options. If this option is not enabled it will
+         * always return false.
+         *
+         * This method is used internally by the Platform Provider to determine the status of each before unload handler in Views when closing the Window.
+         *
+         * @example
+         *
+         * ```js
+         * // from inside a View context
+         * const unloadPrevented = await fin.me.triggerBeforeUnload();
+         * ```
+         *
          * @experimental
          */
         this.triggerBeforeUnload = async () => {
@@ -504,11 +612,31 @@ class View extends main_1.WebContents {
          *
          * **Known issue**: When View.bindToElement is used on a element that takes up the entire page in a platform window, the bound view will not respond responsively when the window is resized to be smaller.
          *
-         * @param {HTMLElement} element - HTML element to attach the view to.
-         * @return {Function} - Cleanup function that will disconnect the element resize observer.
+         * @param element - HTML element to attach the view to.
+         * @returns - Cleanup function that will disconnect the element resize observer.
          * @internal
          * @experimental
-         * @tutorial View.bindToElement
+         * @remarks View will resize accordingly when the element is resized. If the element is repositioned in the DOM the view will not be repositioned, to handle this case call `bindToElement` again once the element changes position.
+         *
+         * @example
+         * ```html
+         * <div id="view-container"></div>
+         * <script>
+         *     async function createAndAttachView() {
+         *         const url = 'https://example.com';
+         *         const elementId = 'view-container';
+         *         const element = document.getElementById(elementId);
+         *         const view = await fin.View.create({
+         *             name: 'my-view',
+         *             url,
+         *             target: fin.me.identity
+         *         });
+         *         await view.navigate(url);
+         *         await view.bindToElement(element);
+         *     }
+         *     createAndAttachView().catch(console.error);
+         * </script>
+         * ```
          */
         this.bindToElement = async (element) => {
             if (!element) {
@@ -518,33 +646,19 @@ class View extends main_1.WebContents {
             return this.wire.environment.observeBounds(element, onChange);
         };
     }
-    /**
-     * Gets a base64 encoded image of the view or a part of it.
-     * @function capturePage
-     * @param { CapturePageOptions } [options] Options for the capturePage call.
-     * @memberOf View
-     * @instance
-     * @return {Promise.<string>}
-     * @tutorial View.capturePage
-     */
-    /**
-     * Executes Javascript on the view, restricted to contents you own or contents owned by
-     * applications you have created.
-     * @param { string } code JavaScript code to be executed on the view.
-     * @function executeJavaScript
-     * @memberOf View
-     * @instance
-     * @return {Promise.<void>}
-     * @tutorial View.executeJavaScript
-     */
     /**
      * Focuses the view
-     * @return {Promise.<void>}
+     *
      * @function focus
      * @memberof View
      * @emits focused
      * @instance
-     * @tutorial View.focus
+     * @example
+     * ```js
+     * const view = fin.View.wrapSync({ uuid: 'viewUuid', name: 'viewName' });
+     * await view.focus();
+     * // do things with the focused view
+     * ```
      * @experimental
      */
     async focus({ emitSynthFocused } = { emitSynthFocused: true }) {

package/src/api/view/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Entry point for the OpenFin View namespace.
+ *
+ * Because TypeDoc does not currently support multiple modules with the same name, the module alias "ViewModule" is used for
+ * the module containing static members of the `View` namespace (available under `fin.View`), while `View` documents
+ * instances of the OpenFin `View` class.
+ *
+ * @packageDocumentation
+ */
 import ViewModule from './Factory';
 export default ViewModule;
 export * from './Instance';