@openfin/core 33.77.5 → 34.78.1

package/out/mock-alpha.d.ts

@@ -855,7 +855,7 @@ declare namespace ApplicationEvents {
     export {
         CrashedEvent,
         FileDownloadLocationChangedEvent,
-        RunRequestedEvent,
+        RunRequestedEvent_2 as RunRequestedEvent,
         TrayIconClickedEvent,
         WindowAlertRequestedEvent,
         WindowCreatedEvent,
@@ -2952,9 +2952,9 @@ declare type ConstViewOptions = {
      */
     processAffinity: string;
     /**
-     * Defines the hotkeys that will be emitted as a `hotkey` event on the view. For usage example see [example]{@tutorial hotkeys}.
+     * Defines the hotkeys that will be emitted as a `hotkey` event on the view. For usage example, see {@link MutableWindowOptions hotkeys Example}.
      * Within Platform, OpenFin also implements a set of pre-defined actions called
-     * [keyboard commands]{@link https://developers.openfin.co/docs/platform-api#section-5-3-using-keyboard-commands}
+     * {@link https://developers.openfin.co/docs/platform-api#section-5-3-using-keyboard-commands keyboard commands}
      * that can be assigned to a specific hotkey in the platform manifest.
      */
     hotkeys: Hotkey[];
@@ -6289,6 +6289,64 @@ declare type JumpListTask = {
 
 /**
  * The LaunchEmitter is an `EventEmitter`. It can listen to app version resolver events.
+ *
+ *
+ * ### Supported event types:
+ *
+ * * app-version-progress
+ * * runtime-status
+ * * app-version-complete
+ * * app-version-error
+ *
+ * ### App version resolver events
+ *
+ * #### app-version-progress
+ * Generated when RVM tries each manifest in the list of fallbackManifests, validate it and see if it's compatible with the system app.
+ * ```js
+ * //This response has the following shape:
+ * {
+ *     type: 'app-version-progress',
+ *     manifest: 'https://cdn.openfin.co/release/system-apps/notifications/1.13.0/app.json',       // A manifest in the fallbackManifest list
+ *     srcManifest: 'https://cdn.openfin.co/myapp.json'    // To keep track of the original manifest url
+ * }
+ * ```
+ *
+ * #### runtime-status
+ * Generated when RVM checks runtime availability.
+ * ```js
+ * //This response has the following shape:
+ * {
+ *     type: 'runtime-status',
+ *     version: '29.105.71.32',    // runtime version
+ *     exists: false,    // check if the runtime already exists on the machine
+ *     writeAccess: true,  // check if the runtime directory has write access
+ *     reachable: true, // check if the runtime asset location is reachable/downloadable
+ *     healthCheck: true,   // check if there is runtime health check
+ *     error: 'Not able to resolve runtime version'    // give an error message if runtime version cannot be resolved
+ * }
+ * ```
+ *
+ * #### app-version-complete
+ * Generated when RVM has successfully found the target runtime version and (about to) delegate launch to the runtime.
+ * ```js
+ * //This response has the following shape:
+ * {
+ *     type: 'app-version-complete',
+ *     manifest: 'https://cdn.openfin.co/release/system-apps/notifications/1.13.0/app.json',       // A manifest in the fallbackManifest list
+ *     srcManifest: 'https://cdn.openfin.co/myapp.json'    // To keep track of the original manifest url
+ * }
+ * ```
+ *
+ * #### app-version-error
+ * Generated when RVM failed to find an available runtime version after trying each manifest in the list of fallbackManifests.
+ * ```js
+ * //This response has the following shape:
+ * {
+ *     type: 'app-version-error',
+ *     srcManifest: 'https://cdn.openfin.co/myapp.json',    // To keep track of the original manifest url
+ *     error: 'All fallback manifest URLs failed'  // error message
+ * }
+ * ```
  */
 declare type LaunchEmitter = TypedEventEmitter<AppVersionEvent>;
 
@@ -6307,44 +6365,7 @@ declare type LaunchIntoPlatformPayload = {
 
 declare class Layout extends Base {
     #private;
-    /**
-     * Initialize the window's Layout.
-     *
-     * @remarks Must be called from a custom window that has a 'layout' option set upon creation of that window.  If a containerId
-     * is not provided, this method attempts to find an element with the id `layout-container`.
-     *
-     * A Layout will emit events locally on the DOM element representing the layout-container. In order to capture the relevant
-     * events during Layout initiation, set up the listeners on the DOM element prior to calling init.
-     *
-     * @example
-     * ```js
-     * // if no options are included, the layout in the window options is initialized in an element with the id `layout-container`
-     * const layout = await fin.Platform.Layout.init();
-     * ```
-     * <br /><br />
-     * # Example
-     * To target a different HTML element use the options object.
-     * ```js
-     * const containerId = 'my-custom-container-id';
-     *
-     * const myLayoutContainer = document.getElementById(containerId);
-     *
-     * myLayoutContainer.addEventListener('tab-created', function(event) {
-     *     const { tabSelector } = event.detail;
-     *     const tabElement = document.getElementById(tabSelector);
-     *     const existingColor = tabElement.style.backgroundColor;
-     *     tabElement.style.backgroundColor = "red";
-     *     setTimeout(() => {
-     *         tabElement.style.backgroundColor = existingColor;
-     *     }, 2000);
-     * });
-     *
-     * // initialize the layout into an existing HTML element with the div `my-custom-container-id`
-     * // the window must have been created with a layout in its window options
-     * const layout = await fin.Platform.Layout.init({ containerId });
-     * ```
-     */
-    init: (options?: InitLayoutOptions_2) => Promise<Layout>;
+    /* Excluded from this release type: init */
     identity: Identity_4;
     private platform;
     wire: Transport;
@@ -6713,15 +6734,43 @@ declare class LayoutModule extends Base {
      */
     getCurrentSync(): OpenFin_2.Layout;
     /**
-     * Initialize the window's Layout.  Must be called from a custom window that has a 'layout' option set upon creation of that window.
+     * Initialize the window's Layout.
+     *
+     * @remarks Must be called from a custom window that has a 'layout' option set upon creation of that window.
      * If a containerId is not provided, this method attempts to find an element with the id `layout-container`.
-     * A Layout will <a href="tutorial-Layout.DOMEvents.html">emit events locally</a> on the DOM element representing the layout-container.
+     * A Layout will emit events locally on the DOM element representing the layout-container.
      * In order to capture the relevant events during Layout initiation, set up the listeners on the DOM element prior to calling `init`.
      * @param options - Layout init options.
      *
-     * @static
      * @experimental
-     * @tutorial Layout.init
+     *
+     * @example
+     * ```js
+     * // If no options are included, the layout in the window options is initialized in an element with the id `layout-container`
+     * const layout = await fin.Platform.Layout.init();
+     * ```
+     * <br>
+     *
+     * ```js
+     * const containerId = 'my-custom-container-id';
+     *
+     * const myLayoutContainer = document.getElementById(containerId);
+     *
+     * myLayoutContainer.addEventListener('tab-created', function(event) {
+     *     const { tabSelector } = event.detail;
+     *     const tabElement = document.getElementById(tabSelector);
+     *     const existingColor = tabElement.style.backgroundColor;
+     *     tabElement.style.backgroundColor = "red";
+     *     setTimeout(() => {
+     *         tabElement.style.backgroundColor = existingColor;
+     *     }, 2000);
+     * });
+     *
+     * // initialize the layout into an existing HTML element with the div `my-custom-container-id`
+     * // the window must have been created with a layout in its window options
+     * const layout = await fin.Platform.Layout.init({ containerId });
+     * ```
+     * @static
      */
     init: (options?: InitLayoutOptions) => Promise<OpenFin_2.Layout>;
 }
@@ -7145,7 +7194,7 @@ declare type MutableViewOptions = {
      * is called.  If a window in a Platform is trying to update or retrieve its own context, it can use the
      * {@link Platform#setWindowContext Platform.setWindowContext} and {@link Platform#getWindowContext Platform.getWindowContext} calls.
      * _When omitted, _inherits_ from the parent application._
-     * As opposed to customData, this is meant for frequent updates and sharing with other contexts. [Example]{@tutorial customContext}
+     * As opposed to customData, this is meant for frequent updates and sharing with other contexts. For usage example, see {@link MutableWindowOptions customContext Example}.
      */
     customContext: any;
     /**
@@ -7242,7 +7291,42 @@ declare type MutableWindowOptions = {
      * is called.  If a window in a Platform is trying to update or retrieve its own context, it can use the
      * {@link Platform#setWindowContext Platform.setWindowContext} and {@link Platform#getWindowContext Platform.getWindowContext} calls.
      * _When omitted, _inherits_ from the parent application._
-     * As opposed to customData, this is meant for frequent updates and sharing with other contexts. [Example]{@tutorial customContext}
+     * As opposed to customData, this is meant for frequent updates and sharing with other contexts.
+     *
+     * @example
+     * This Example shows a window sharing context to all it's views.
+     * By executing the code here in the correct context, the view will have global `broadcastContext` and `addContextListener` methods available.
+     * The window will synchronize context between views such that calling `broadcastContext` in any of the views will invoke any listeners added with `addContextListener` in all attached views.
+     *
+     * ### In Window (frame)
+     * ```js
+     * const me = fin.Window.getCurrentSync();
+     * me.on('options-changed', async (event) => {
+     *     if (event.diff.customContext) {
+     *         const myViews = await me.getCurrentViews();
+     *         const customContext = event.diff.customContext.newVal;
+     *         myViews.forEach(v => {
+     *             v.updateOptions({customContext});
+     *         });
+     *     }
+     * })
+     *
+     * ```
+     * ### in View (content)
+     * ```js
+     * const me = fin.View.getCurrentSync();
+     * const broadcastContext = async (customContext) => {
+     *     const myWindow = await me.getCurrentWindow()
+     *     await myWindow.updateOptions({customContext})
+     * };
+     * const addContextListener = async (listener) => {
+     *     await me.on('options-changed', (event) => {
+     *         if (event.diff.customContext) {
+     *             listener(event.diff.customContext.newVal);
+     *         }
+     *     });
+     * }
+     * ```
      */
     customContext: any;
     /**
@@ -7263,10 +7347,45 @@ declare type MutableWindowOptions = {
      */
     hideOnClose: boolean;
     /**
-     * Defines the hotkeys that will be emitted as a `hotkey` event on the window. For usage example see [example]{@tutorial hotkeys}.
+     * Defines the hotkeys that will be emitted as a `hotkey` event on the window.
      * Within Platform, OpenFin also implements a set of pre-defined actions called
-     * [keyboard commands]{@link https://developers.openfin.co/docs/platform-api#section-5-3-using-keyboard-commands}
+     * {@link https://developers.openfin.co/docs/platform-api#section-5-3-using-keyboard-commands keyboard commands}
      * that can be assigned to a specific hotkey in the platform manifest.
+     *
+     * @example
+     *
+     * This example shows the example of using the `hotkeys` option on Windows/Views and the corresponding `hotkey` event emitted when a specified hotkey is pressed.
+     * ### Defining the hotkey
+     * ```js
+     * const myMagicWindow = await fin.Window.create({
+     *     name: 'magicWin',
+     *     hotkeys: [
+     *         {
+     *             keys: 'Ctrl+M',
+     *         }
+     *     ]
+     * });
+     *
+     * ```
+     * ### Listening to the hotkey
+     * ```js
+     * myMagicWindow.on('hotkey', (hotkeyEvent) => {
+     *     console.log(`A hotkey was pressed in the magic window!: ${JSON.stringify(hotkeyEvent)}`);
+     * });
+     * ```
+     *
+     * ### Removing a hotkey
+     * After the following change, the `hotkey` event will no longer be emitted when Ctrl+M is pressed:
+     * ```js
+     * const currentHotkeys = (await myMagicWindow.getOptions()).hotkeys;
+     * const newHotkeys = currentHotkeys.filter(hotkey => hotkey.keys !== 'Ctrl+M');
+     * myMagicWindow.updateOptions({
+     *     hotkeys: newHotkeys
+     * });
+     * ```
+     *
+     * @remarks The `hotkeys` option is configured per-instance and isn't passed down to the children of Window/View.
+     * Therefore, if you want a Window/View *and* all of its children to support hotkeys, you must configure the `hotkeys` option for every created child.
      */
     hotkeys: Hotkey[];
     /**
@@ -9072,6 +9191,15 @@ declare interface PlatformProvider {
      *
      */
     handleViewsAndWindowClose(windowId: OpenFin_2.Identity, userDecision: OpenFin_2.BeforeUnloadUserDecision): Promise<void>;
+    /**
+     * Handles subsequent launch attempts of the current platform.
+     * Attempts to launch appManifestUrl passed as userAppConfigArgs.
+     * If no appManifestUrl is present will attempt to launch using the requesting manifest snapshot.
+     * If no appManifestUrl or snapshot is available nothing will be launched.
+     * @param { RunRequestedEvent<'application', 'run-requested'> } payload
+     * @returns {Promise<void>}
+     */
+    handleRunRequested({ manifest, userAppConfigArgs }: RunRequestedEvent): Promise<void>;
 }
 
 /**
@@ -9939,13 +10067,15 @@ declare interface RTCStrategyEndpointPayload {
     rtc: RTCPacket;
 }
 
+declare type RunRequestedEvent = OpenFin_2.ApplicationEvents.RunRequestedEvent;
+
 /**
  * Generated when Application.run() is called for an already running application.
  */
-declare type RunRequestedEvent = IdentityEvent & {
+declare type RunRequestedEvent_2 = IdentityEvent & {
     type: 'run-requested';
     userAppConfigArgs: Record<string, any>;
-    manifest: OpenFin_2.ManifestInfo;
+    manifest: OpenFin_2.Manifest;
 };
 
 declare type RuntimeConfig = {
@@ -12499,7 +12629,6 @@ declare class View_2 extends WebContents<ViewEvent> {
      * 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}
      *
      * @example
      * ```js
@@ -12620,7 +12749,6 @@ declare class View_2 extends WebContents<ViewEvent> {
     hide: () => Promise<void>;
     /**
      * Sets the bounds (top, left, width, height) of the view relative to its window.
-     * @param bounds {ViewBounds}
      *
      * @remarks View position is relative to the bounds of the window.
      * ({top: 0, left: 0} represents the top left corner of the window)
@@ -14135,12 +14263,12 @@ declare type WillMoveOrResizeEvent = NamedEvent & {
 /**
  * An Application event that does propagate to (republish on) parent topics.
  */
-declare type WillPropagateApplicationEvent = ClosedEvent | ApplicationConnectedEvent | CrashedEvent | InitializedEvent | ManifestChangedEvent | NotRespondingEvent | RespondingEvent | RunRequestedEvent | StartedEvent | TrayIconClickedEvent | FileDownloadLocationChangedEvent;
+declare type WillPropagateApplicationEvent = ClosedEvent | ApplicationConnectedEvent | CrashedEvent | InitializedEvent | ManifestChangedEvent | NotRespondingEvent | RespondingEvent | RunRequestedEvent_2 | StartedEvent | TrayIconClickedEvent | FileDownloadLocationChangedEvent;
 
 /**
  * A View event that does propagate to (republish on) parent topics.
  */
-declare type WillPropagateViewEvent = WillPropagateWebContentsEvent | AttachedEvent | CreatedEvent | DestroyedEvent | HiddenEvent_2 | HotkeyEvent | ShownEvent | TargetChangedEvent;
+declare type WillPropagateViewEvent = (WillPropagateWebContentsEvent & BaseViewEvent) | AttachedEvent | CreatedEvent | DestroyedEvent | HiddenEvent_2 | HotkeyEvent | ShownEvent | TargetChangedEvent;
 
 /**
  * A WebContents event that does propagate to (republish on) parent topics.
@@ -14277,7 +14405,7 @@ declare type WillResizeEvent = WillMoveOrResizeEvent & {
  * alphaMask turns anything of matching RGB value transparent.
  * <br>
  * Caveats:
- * * runtime key --disable-gpu is required. Note: Unclear behavior on remote Desktop support
+ * * Runtime flags --disable-gpu and --allow-unsafe-compositing are required. Note: Unclear behavior on remote Desktop support
  * * User cannot click-through transparent regions
  * * Not supported on Mac
  * * Windows Aero must be enabled
@@ -14465,6 +14593,7 @@ declare type WillResizeEvent = WillMoveOrResizeEvent & {
  * A flag that specifies how transparent the window will be.
  * Changing opacity doesn't work on Windows 7 without Aero so setting this value will have no effect there.
  * This value is clamped between `0.0` and `1.0`.
+ * * In software composition mode, the runtime flag --allow-unsafe-compositing is required.
  *
  * @property {preloadScript[]} [preloadScripts] - _Inheritable_
  * A list of scripts that are eval'ed before other scripts in the page. When omitted, _inherits_