@openfin/core 33.76.31 → 33.76.36

package/src/api/application/Factory.js

@@ -3,87 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const base_1 = require("../base");
 const validate_1 = require("../../util/validate");
 const Instance_1 = require("./Instance");
-/**
- * @PORTED
- * @typedef {object} ApplicationOptions
- * @summary Application creation options.
- * @desc This is the options object required by {@link Application.start Application.start}.
- *
- * The following options are required:
- * * `uuid` is required in the app manifest as well as by {@link Application.start Application.start}
- * * `name` is optional in the app manifest but required by {@link Application.start Application.start}
- * * `url` is optional in both the app manifest {@link Application.start Application.start} and  but is usually given
- * (defaults to `"about:blank"` when omitted).
- *
- * _This jsdoc typedef mirrors the `ApplicationOption` TypeScript interface in `@types/openfin`._
- *
- * **IMPORTANT NOTE:**
- * This object inherits all the properties of the window creation {@link Window~options options} object,
- * which will take priority over those of the same name that may be provided in `mainWindowOptions`.
- *
- * @property {boolean} [disableIabSecureLogging=false]
- * When set to `true` it will disable IAB secure logging for the app.
- *
- * @property {string} [loadErrorMessage="There was an error loading the application."]
- * An error message to display when the application (launched via manifest) fails to load.
- * A dialog box will be launched with the error message just before the runtime exits.
- * Load fails such as failed DNS resolutions or aborted connections as well as cancellations, _e.g.,_ `window.stop()`,
- * will trigger this dialog.
- * Client response codes such as `404 Not Found` are not treated as fails as they are valid server responses.
- *
- * @property {Window~options} [mainWindowOptions]
- * The options of the main window of the application.
- * For a description of these options, click the link (in the Type column).
- *
- * @property {number} [maxViewPoolSize=1000]
- * Platforms Only.  The maximum number of "detached" or "pooled" Views that can exist in the Platform before being closed.
- * If you do not wish for views to be pooled on your platform, set this property to zero.
- *
- * @property {boolean} [preventQuitOnLastWindowClosed=false]
- * Platforms Only. Prevent the Platform Provider from quitting automatically when the last Platform Window is closed.
- * Note: if the Platform Provider is showing, it won't close automatically.
- * If you want a hidden Platform Provider to remain open after the last Platform Window has been closed, set this property to true.
- *
- * @property {string} [name]
- * The name of the application (and the application's main window).
- *
- * If provided, _must_ match `uuid`.
- *
- * @property {boolean} [nonPersistent=false]
- * A flag to configure the application as non-persistent.
- * Runtime exits when there are no persistent apps running.
- *
- * @property {boolean} [plugins=false]
- * Enable Flash at the application level.
- *
- * @property {boolean} [spellCheck=false]
- * Enable spell check at the application level.
- *
- * @property {string} [url="about:blank"]
- * The url to the application (specifically the application's main window).
- *
- * @property {boolean} [enableJumpList=false]
- * Enables the use of the Jumplists API and the 'pin to taskbar' functionality.
- * Only relevant in Windows.
- *
- * @property {string} uuid
- * The _Unique Universal Identifier_ (UUID) of the application, unique within the set of all other applications
- *  running in the OpenFin Runtime.
- *
- * Note that `name` and `uuid` must match.
- *
- * @property {boolean} [webSecurity=true]
- * When set to `false` it will disable the same-origin policy for the app.
- */
-/**
- * @lends Application
- */
 class ApplicationModule extends base_1.Base {
     /**
      * Asynchronously returns an Application object that represents an existing application.
-     * @param { Identity } identity
-     * @return {Promise.<Application>}
-     * @tutorial Application.wrap
+     * @param identity
+     *
+     * @example
+     *
+     * ```js
+     * fin.Application.wrap({ uuid: 'testapp' })
+     * .then(app => app.isRunning())
+     * .then(running => console.log('Application is running: ' + running))
+     * .catch(err => console.log(err));
+     * ```
+     *
      * @static
      */
     async wrap(identity) {
@@ -98,9 +31,15 @@ class ApplicationModule extends base_1.Base {
     }
     /**
      * Synchronously returns an Application object that represents an existing application.
-     * @param { Identity } identity
-     * @return {Application}
-     * @tutorial Application.wrapSync
+     * @param identity
+     *
+     * @example
+     *
+     * ```js
+     * const app = fin.Application.wrapSync({ uuid: 'testapp' });
+     * await app.close();
+     * ```
+     *
      * @static
      */
     wrapSync(identity) {
@@ -125,10 +64,26 @@ class ApplicationModule extends base_1.Base {
         return this.wrap({ uuid: appOptions.uuid });
     }
     /**
-     * DEPRECATED method to create a new Application. Use {@link Application.start} instead.
-     * @param { ApplicationOptions } appOptions
-     * @return {Promise.<Application>}
-     * @tutorial Application.create
+     * DEPRECATED method to create a new Application. Use {@link Application.ApplicationModule.start Application.start} instead.
+     * @param appOptions
+     *
+     *
+     * @example
+     *
+     * ```js
+     * async function createApp() {
+     *     const app = await fin.Application.create({
+     *         name: 'myApp',
+     *         uuid: 'app-3',
+     *         url: 'https://cdn.openfin.co/docs/javascript/stable/tutorial-Application.create.html',
+     *         autoShow: true
+     *     });
+     *     await app.run();
+     * }
+     *
+     * createApp().then(() => console.log('Application is created')).catch(err => console.log(err));
+     * ```
+     *
      * @ignore
      */
     create(appOptions) {
@@ -140,9 +95,23 @@ class ApplicationModule extends base_1.Base {
     }
     /**
      * Creates and starts a new Application.
-     * @param { ApplicationOptions } appOptions
-     * @return {Promise.<Application>}
-     * @tutorial Application.start
+     * @param appOptions
+     *
+     * @example
+     *
+     * ```js
+     * async function start() {
+     *     return fin.Application.start({
+     *         name: 'app-1',
+     *         uuid: 'app-1',
+     *         url: 'https://cdn.openfin.co/docs/javascript/stable/tutorial-Application.start.html',
+     *         autoShow: true
+     *     });
+     * }
+     * start().then(() => console.log('Application is running')).catch(err => console.log(err));
+     * ```
+     *
+     *
      * @static
      */
     async start(appOptions) {
@@ -156,11 +125,38 @@ class ApplicationModule extends base_1.Base {
     /**
      * Asynchronously starts a batch of applications given an array of application identifiers and manifestUrls.
      * Returns once the RVM is finished attempting to launch the applications.
-     * @param { Array.<ManifestInfo> } applications
-     * @param {RvmLaunchOptions} [opts] - Parameters that the RVM will use.
-     * @return {Promise.<void>}
+     * @param applications
+     * @param opts - Parameters that the RVM will use.
+     *
      * @static
-     * @tutorial Application.startManyManifests
+     * @example
+     *
+     * ```js
+     *
+     * const applicationInfoArray = [
+     *     {
+     *         "uuid": 'App-1',
+     *         "manifestUrl": 'http://localhost:5555/app1.json',
+     *     },
+     *     {
+     *         "uuid": 'App-2',
+     *         "manifestUrl": 'http://localhost:5555/app2.json',
+     *     },
+     *     {
+     *         "uuid": 'App-3',
+     *         "manifestUrl": 'http://localhost:5555/app3.json',
+     *     }
+     * ]
+     *
+     * fin.Application.startManyManifests(applicationInfoArray)
+     *     .then(() => {
+     *         console.log('RVM has finished launching the application list.');
+     *     })
+     *     .catch((err) => {
+     *         console.log(err);
+     *     })
+     * ```
+     *
      * @experimental
      */
     async startManyManifests(applications, opts) {
@@ -168,8 +164,23 @@ class ApplicationModule extends base_1.Base {
     }
     /**
      * Asynchronously returns an Application object that represents the current application
-     * @return {Promise.<Application>}
-     * @tutorial Application.getCurrent
+     *
+     * @example
+     *
+     * ```js
+     * async function isCurrentAppRunning () {
+     *     const app = await fin.Application.getCurrent();
+     *     return app.isRunning();
+     * }
+     *
+     * isCurrentAppRunning().then(running => {
+     *     console.log(`Current app is running: ${running}`);
+     * }).catch(err => {
+     *     console.error(err);
+     * });
+     *
+     * ```
+     *
      * @static
      */
     getCurrent() {
@@ -180,8 +191,23 @@ class ApplicationModule extends base_1.Base {
     }
     /**
      * Synchronously returns an Application object that represents the current application
-     * @return {Application}
-     * @tutorial Application.getCurrentSync
+     *
+     * @example
+     *
+     * ```js
+     * async function isCurrentAppRunning () {
+     *     const app = fin.Application.getCurrentSync();
+     *     return app.isRunning();
+     * }
+     *
+     * isCurrentAppRunning().then(running => {
+     *     console.log(`Current app is running: ${running}`);
+     * }).catch(err => {
+     *     console.error(err);
+     * });
+     *
+     * ```
+     *
      * @static
      */
     getCurrentSync() {
@@ -192,10 +218,18 @@ class ApplicationModule extends base_1.Base {
     }
     /**
      * Retrieves application's manifest and returns a running instance of the application.
-     * @param {string} manifestUrl - The URL of app's manifest.
-     * @param {RvmLaunchOptions} [opts] - Parameters that the RVM will use.
-     * @return {Promise.<Application>}
-     * @tutorial Application.startFromManifest
+     * @param manifestUrl - The URL of app's manifest.
+     * @param opts - Parameters that the RVM will use.
+     *
+     * @example
+     *
+     * ```js
+     * fin.Application.startFromManifest('http://localhost:5555/app.json').then(app => console.log('App is running')).catch(err => console.log(err));
+     *
+     * // For a local manifest file:
+     * fin.Application.startFromManifest('file:///C:/somefolder/app.json').then(app => console.log('App is running')).catch(err => console.log(err));
+     * ```
+     *
      * @static
      */
     async startFromManifest(manifestUrl, opts) {
@@ -207,6 +241,20 @@ class ApplicationModule extends base_1.Base {
         await app._run(opts); // eslint-disable-line no-underscore-dangle
         return app;
     }
+    /**
+     * @deprecated Use {@link Application.ApplicationModule.startFromManifest Application.startFromManifest} instead.
+     * Retrieves application's manifest and returns a wrapped application.
+     * @param manifestUrl - The URL of app's manifest.
+     * @param callback - called if the method succeeds.
+     * @param errorCallback - called if the method fails. The reason for failure is passed as an argument.
+     *
+     * @example
+     *
+     * ```js
+     * fin.Application.createFromManifest('http://localhost:5555/app.json').then(app => console.log(app)).catch(err => console.log(err));
+     * ```
+     * @ignore
+     */
     createFromManifest(manifestUrl) {
         console.warn('Deprecation Warning: fin.Application.createFromManifest is deprecated. Please use fin.Application.startFromManifest');
         this.wire.sendAction('application-create-from-manifest').catch((e) => {