@interopio/desktop
Version:
JavaScript library for io.Connect Desktop clients.
1,175 lines (996 loc) • 320 kB
TypeScript
/* eslint-disable @typescript-eslint/no-shadow */
import { ApplicationConfig } from "@interopio/schemas";
import { IOConnectCore } from "@interopio/core";
import { IOConnectWorkspaces } from "@interopio/workspaces-api";
import { UnsubscribeFunction } from "callback-registry";
/**
* Factory function that creates a new io.Connect instance.
*/
export default function IOConnectDesktopFactoryFunction(config?: IOConnectDesktop.Config): Promise<IOConnectDesktop.API>;
/**
* @docname io.Connect Desktop
* @intro
* **io.Connect Desktop** is a desktop integration platform that enables functional and visual integration of web, native and legacy apps.
*
* The io.Connect JavaScript library enables web apps to participate in **io.Connect Desktop** and use io.Connect functionalities via a set of APIs.
*
* ## Referencing
*
* ### From a JavaScript File
*
* io.Connect JavaScript is a library available as a single JavaScript file, which you can include in your web apps using a `<script>` tag:
*
* ```html
* <script type="text/javascript" src="desktop.umd.js"></script>
* ```
*
* When deploying your app in production, it's recommended to always reference a specific minified version:
*
* ```html
* <script type="text/javascript" src="desktop.umd.min.js"></script>
* ```
*
* ### From an NPM Module
*
* The io.Connect JavaScript library is also available as an `npm` package, which you can include as a dependency in your project and import in your code.
* The currently available packages are [`@interopio/core`](https://www.npmjs.com/package/@interopio/core) and
* [`@interopio/desktop`](https://www.npmjs.com/package/@interopio/desktop).
* The Core package is a subset of the Desktop package and offers basic functionalities for sharing data between apps
* (Interop, Shared Contexts, Pub/Sub, Metrics),
* while the Desktop package offers additional options for sharing data between apps (Channels), as well as advanced window management
* functionalities (App Management, Layouts, Window Management).
*
* To install the io.Connect library in your project, execute the following command:
*
* ```cmd
* npm install @interopio/desktop
* ```
*
* ## Initialization
*
* The io.Connect Desktop library registers a global factory function called `IODesktop()` that will resolve with the initialized API object when invoked:
*
* ```javascript
* import IODesktop from "@interopio/desktop";
*
* const io = await IODesktop();
* ```
*
* Optionally, you can provide configuration for the library:
*
* ```javascript
* import IODesktop from "@interopio/desktop";
*
* // Enabling the Channels API.
* const config = { channels: true };
*
* const io = await IODesktop(config);
* ```
*/
export declare namespace IOConnectDesktop {
export import AGM = IOConnectCore.Interop;
export import Contexts = IOConnectCore.Contexts;
export import Connection = IOConnectCore.Connection;
export import Logger = IOConnectCore.Logger;
export import Metrics = IOConnectCore.Metrics;
export import Auth = IOConnectCore.Auth;
export import FeedbackInfo = IOConnectCore.FeedbackInfo;
export import Channels = IOConnectDesktop.Channels.API;
export import ChannelContext = IOConnectDesktop.Channels.ChannelContext;
export import Interop = IOConnectCore.Interop;
export import GDObject = IOConnectCore.GDObject;
export import IOConnectDesktopObject = IOConnectCore.IOConnectDesktopObject;
export import GatewayConfig = IOConnectCore.GatewayConfig;
export import MetricsConfig = IOConnectCore.MetricsConfig;
export import InprocGWSettings = IOConnectCore.InprocGWSettings;
export import GwTokenProvider = IOConnectCore.GwTokenProvider;
export import LoggerConfig = IOConnectCore.LoggerConfig;
/**
* Optional configuration object for initializing the io.Connect library.
*/
export interface Config extends IOConnectCore.Config {
/**
* Initializes or disables the App Management API. You can also specify mode in which that App Management API will be initialized.
* @default "startOnly"
*/
appManager?: boolean | IOConnectDesktop.AppManager.Mode;
/**
* Initializes or disables the Layouts API. You can also specify mode and configuration with which that Layouts API will be initialized.
* @default "slim"
*/
layouts?: boolean | IOConnectDesktop.Layouts.Mode | IOConnectDesktop.Layouts.Configuration;
/**
* Initializes or disables the Activities API.
* @default "trackMyTypeAndInitiatedFromMe"
* @ignore
*/
activities?: boolean | IOConnectDesktop.Activities.ActivitiesModes;
/**
* Initializes or disables the Window Management API.
* @default true
*/
windows?: boolean;
/**
* Initializes or disables the Channels API.
* @default false
*/
channels?: boolean | IOConnectDesktop.Channels.Configuration;
/**
* Initializes or disables the Displays API.
* @default true
*/
displays?: boolean;
/**
* Configuration for the Intents Resolver UI.
*/
intents?: Intents.Config;
/**
* A list of io.Connect factory functions that will be initialized internally to provide access to specific functionalities.
*/
libraries?: ((io: IOConnectDesktop.API, config?: IOConnectDesktop.Config) => Promise<void>)[];
/**
* Determines whether io.Connect will share the initialized API object upon request via a custom web event.
* @default true
* @deprecated Use `exposeAPI` instead.
* @ignore
*/
exposeGlue?: boolean;
/**
* Determines whether io.Connect will share the initialized API object upon request via a custom web event.
* @default true
*/
exposeAPI?: boolean;
}
/**
* Instance of the initialized io.Connect library.
*/
export interface API extends IOConnectCore.API {
/**
* Window Management API.
*/
windows: IOConnectDesktop.Windows.API;
/**
* Activities API.
* @ignore
*/
activities: IOConnectDesktop.Activities.API;
/**
* App Management API.
*/
appManager: IOConnectDesktop.AppManager.API;
/**
* Layouts API.
*/
layouts: IOConnectDesktop.Layouts.API;
/**
* Channels API.
*/
channels: IOConnectDesktop.Channels.API;
/**
* Hotkeys API.
*/
hotkeys: IOConnectDesktop.Hotkeys.API;
/**
* Displays API.
*/
displays: IOConnectDesktop.Displays.API;
/**
* Intents API.
*/
intents: IOConnectDesktop.Intents.API;
/**
* Notifications API.
*/
notifications: IOConnectDesktop.Notifications.API;
/**
* Workspaces API.
*/
workspaces?: IOConnectWorkspaces.API;
/**
* Themes API.
*/
themes?: IOConnectDesktop.Themes.API;
/**
* App Preferences API.
*/
prefs: IOConnectDesktop.Preferences.API;
/**
* Cookies API.
*/
cookies: IOConnectDesktop.Cookies.API;
/**
* Interception API.
* @since io.Connect Desktop 9.6
*/
interception: IOConnectDesktop.Interception.API;
}
/**
* @intro
* An Activity is a collection of windows organized in a layout and sharing a private context. Here is an example of an Activity consisting of four windows:
*
* 
*
* Activities are usually registered as components in the application configuration and can be instantiated either as applications from the toolbar or programmatically - on demand.
*
* An *Activity type* is a definition template for an Activity, consisting of a collection of *window types*, their layout and an initial *Activity context*.
*
* A *window type* is a definition of a window, typically configured in the application configuration settings. However, the Activities API allows for an application to dynamically define both (window types and Activity types) at runtime.
*
* An *Activity context* is an object containing a set of key/value pairs which hold the current state of an Activity - e.g., the currently selected `party`, `instrument`, `order`, etc.
*
* An *Activity instance* is an instance of an *Activity type*, just like an object is an instance of a class in class-based languages. "Activity" is often used as a synonym for Activity instance.
*
* The Activities API enables:
*
* - the definition of window types and Activity types (collection of window types, layout and an initial context);
* - starting an Activity instance of a specific Activity type;
* - reacting to Activity events from an Activity-aware window, such as joining and leaving an Activity;
* - application state synchronization via Activity context management functions;
* - intra-Activity application collaboration via Activity Interop extension functions;
*
* The Activities API is accessible through the `io.activities` object.
*/
namespace Activities {
/** @ignore */
export interface LoggerConfig {
publish: string;
console: string;
metrics: string;
}
/** Activities configuration object. */
export interface Config {
/**
* @ignore
* Activities mode.
*/
mode?: boolean | ActivitiesModes;
/** Types of activities to track. */
typesToTrack: string[];
/** @ignore */
logger?: LoggerConfig;
}
/**
* Activities API mode.
*/
export type ActivitiesModes = "trackMyOnly" | "trackMyTypeAndInitiatedFromMe" | "trackAll" | "trackTypes";
/**
* Activities API.
*/
export interface API {
/** API version string. */
version: string;
/**
* Returns `true` if the current window is activity aware, meaning that the window was created as
* an activity participant - either a helper or an owner window.
*/
aware: boolean;
/** Returns `true` if the current window is activity aware and is currently participating in an activity. */
inActivity: boolean;
/** A lightweight, single activity oriented subset of the API which should be used by most activity applications. */
my: My;
/** Extended API that provides access to all running activities and windows and the available activity and window types. */
all: ActivitiesManagement;
/**
* This method notifies applications when the API is ready to be used.
* Note: If you are using the io.Connect library, you don't need to use this
* as the io.Connect library is initialized when all included libraries are initialized.
* @param callback Optional callback function to notify the application when the API is initialized.
*/
ready(callback?: (api: API) => void): Promise<API>;
/** Returns a list of frame colors that can be used for the activity frame. */
getAvailableFrameColors(): string[];
}
/**
* A lightweight, single activity oriented subset of the API which should be used
* by most activity applications.
*/
export interface My {
/** The current activity of the application. Can be `undefined` if currently not part of any activity. */
activity: Activity;
/** The current activity window. Can be `undefined` if the window is not part of any activity. */
window: ActivityWindow;
/** The context of the activity the application is part of. */
context: any;
/**
* Updates the activity context using the properties of the `context` argument.
* If the old context values are `{ a: 1, b: 2, c: 3 }`, invoking `updateContext({ b: 3, c: null, d: 4 })` will result in
* the following context state: `{ a: 1, b: 3, d: 4 }`.
* @param context Context object with which to update the current activity context.
* @param callback Optional callback function that will be executed when the context has been updated.
*/
updateContext(context: any, callback?: any): Promise<object>;
/**
* Replaces the specified activity context.
* @param context Context object with which to replace the existing activity context.
* @param callback Optional callback function that will be executed when the context has been replaced.
*/
setContext(context: any, callback?: any): Promise<object>;
/**
* Creates a new window and joins it to the activity.
* @param windowType The name or the window definition of the window you want to create and add to the activity.
*/
createWindow(windowType: string | WindowDefinition): Promise<ActivityWindow>;
/**
* Creates a stacked set of windows and joins them to the activity.
* @param windowTypes An array of window names or definitions you want to create and add to the activity.
* @param timeout Optional timeout for the operation.
*/
// tslint:disable-next-line:array-type
createStackedWindows(windowTypes: (string | WindowDefinition)[], timeout?: number): Promise<ActivityWindow[]>;
/**
* Subscribes for the event which fires when the current window joins an activity.
* @param callback Handler function for the event.
*/
onActivityJoined(callback: (activity: Activity) => void): void;
/**
* Subscribes for the event which fires when the current window leaves an activity.
* @param callback Handler function for the event.
*/
onActivityLeft(callback: (activity: Activity) => void): void;
/**
* Subscribes for context updates.
* @param callback Handler function that receives the updated context object, a delta object,
* an array of removed context properties and the activity instance as arguments.
*/
onContextChanged(callback: (context: object, delta: object, removed: string[], activity: Activity) => void): void;
/**
* @ignore
* Creates a new activity by cloning the current one.
* @param options Options for cloning an activity.
* @param callback Handler function for the cloned activity.
*/
clone(options: CloneOptions, callback: (activity: Activity) => void): Promise<Activity>;
/**
* @ignore
* Attaches the current activity to another activity.
* This stops the current activity. It can be restored by using the returned `AttachedActivityDescriptor` object.
* @param activity Activity to which to attach the current activity.
* @param tag
*/
attach(activity: Activity | string, tag?: object): Promise<AttachedActivityDescriptor>;
/** Sets the frame color of the current activity.
* @param color The color you want to set for activity frame color.
* @param callback Callback function invoked when the activity frame color has been changed.
*/
setFrameColor(color: string, callback: () => void): Promise<Activity>;
/** Returns the frame color of the current activity. */
getFrameColor(): string;
/** Subscribes for the event which fires when the activity frame color is changed. */
onFrameColorChanged(callback: () => void): void;
}
/**
* Extended API that provides access to all running activities and windows and all
* available activity and window types.
*/
export interface ActivitiesManagement {
/** Access point to the activity types. */
activityTypes: ActivityTypesAPI;
/** Access point to the window types. */
windowTypes: WindowTypesAPI;
/** Access point to the running activity windows. */
windows: WindowingAPI;
/** Access point to the running activity instances. */
instances: InstancesAPI;
/**
* @ignore
* Subscribes for the event which fires when an activity is attached to another activity.
* @param callback
*/
onAttached(callback: (activity: Activity, descriptor: AttachedActivityDescriptor) => void): void;
/**
* @ignore
* Subscribes for the event which fires when two activities are detached.
* @param callback
*/
onDetached(callback: (newActivity: Activity, oldActivity: Activity, descriptor: AttachedActivityDescriptor) => void): void;
/** Subscribes for the event which fires when the color of the activity frame is changed.
* @param callback Handler function for the event. Receives the activity and the new activity frame color as arguments.
*/
onActivityFrameColorChanged(callback: (activity: Activity, frameColor: string) => void): void;
}
/**
* The Activity Types API enables you to define templates for activities. You can specify the window types the activity should contain,
* the layout of the activity windows and the initial context they should share.
*/
export interface ActivityTypesAPI {
/** Returns all known activity types or a specific activity type by name. */
get(name?: string): ActivityType[] | ActivityType;
/**
* Registers a new activity type.
* @param activityTypeName The name of the activity type to be created.
* @param ownerWindowType The type of the owner window or a `WindowDefinition` of the owner window.
* @param helperWindowTypes Types of helper windows (or `WindowDefinitions` of helper windows).
* @param layoutConfig Layout configuration.
* @param description Description of the new activity type.
* @param callback Callback function to handle the result. If not specified, the method will return a `Promise` that resolves with the created activity type.
*/
register(activityTypeName: string, ownerWindowType: string | WindowDefinition, helperWindowTypes?: string[] | WindowDefinition[], layoutConfig?: any, description?: string, callback?: (at: ActivityType) => void): Promise<ActivityType>;
/**
* Unregisters an existing activity type.
* @param type The name of the activity type to be removed.
*/
unregister(type: string): void;
/**
* Initiates a new activity of the specified type.
* @param activityType The activity type to initiate.
* @param context The initial context of the activity.
* @param configuration Configuration with which you can override the predefined activity type configuration.
* @param callback Callback function to handle the result.
*/
initiate(activityType: string, context?: object, configuration?: OverrideTypeDefinition | WindowDefinition[], callback?: (act: Activity) => void): Promise<Activity>;
/** Subscribes for `ActivityType` events.
* @param handler Handler function for the event. Receives the activity type and the event name as arguments.
*/
subscribe(handler: (act: ActivityType, event: string) => void): void;
/** Unsubscribes from `ActivityType` events.
* @param handler Handler function for the event. Receives the activity type and the event name as arguments.
*/
unsubscribe(handler: (act: ActivityType, event: string) => void): void;
}
/**
* The Window Types API enables you to create and handle windows by type.
*/
export interface WindowTypesAPI {
/** Get all available window types or a specific type by name. */
get(name?: string): WindowType[] | WindowType;
/**
* Allows you to subscribe for window events - e.g., registering a window type.
* @param handler Handler function for the event. Receives the window type and the event name as arguments.
*/
subscribe(handler: (act: WindowType, event: string) => void): void;
/** Unsubscribes from window events.
* @param handler Handler function for the event. Receives the window type and the event name as arguments.
*/
unsubscribe(handler: (act: WindowType, action: string) => void): void;
/**
* Registers a factory function for a given `WindowType`. It will be called once a window of that type is requested.
* @param windowType Window type that will be constructed by the factory function. Can be a string (name of the window type)
* or an object with `name` and `description` properties.
* @param factoryMethod The factory function that will construct windows of the specified type.
*/
registerFactory(windowType: string | { name: string, description: string }, factoryMethod: (activityInfo: ActivityWindowCreateRequest) => Promise<void>): Promise<any>;
/**
* Unregisters all factory methods for a given `WindowType`.
* @param windowType Window type that is constructed by the factory function.
*/
unregisterFactory(windowType: string): Promise<any>;
}
/** Request object for creating an activity window. Passed to the factory function for creating activity windows. */
export interface ActivityWindowCreateRequest {
/** ID of the activity for which the window will be created. */
activityId?: string;
/** Type of the activity for which the window will be created. */
activityType?: string;
/** Type of the window that will be created as an activity window. */
type: string;
/** Gateway token for the window that will be created as an activity window. */
gwToken?: string;
/** Configuration for the window that will be created as an activity window. */
configuration?: any;
}
/**
* The Windowing API enables you to handle activity windows.
*/
export interface WindowingAPI {
/**
* Returns activity windows based on a filter. If no filter is supplied, all activity windows are returned.
* @param filter Filter object describing which activity windows to return.
*/
get(filter: { id?: string, type?: string, name?: string, activityId?: string }): ActivityWindow[];
/**
* Initializes an activity for the current window. By doing this, the window is announced as activity aware to the other activity participants.
* @param activityWindowId The ID of the window that was created.
* @param windowType Type of the window.
*/
announce(activityWindowId?: string, windowType?: string): Promise<ActivityWindow>;
/**
* Creates a new window of a given type and joins it to an activity.
*
* @param activity Activity to which to join the window.
* @param windowType The type of the window to be created and joined to the activity.
* @param callback Optional callback to handle the result.
*/
create(activity: Activity, windowType: string | WindowDefinition, callback?: (aw: ActivityWindow) => void): Promise<ActivityWindow>;
/**
* Allows you to subscribe for activity window events (e.g., window joining or leaving an activity).
* @param handler Handler function which receives the activity, the activity window and the event as parameters.
*/
subscribe(handler: (activity: Activity, window: ActivityWindow, event: any) => void): void;
/** Unsubscribes from an activity window event. */
unsubscribe(handler: (activity: Activity, window: ActivityWindow, event: any) => void): void;
}
/**
* API for managing activity instances.
*/
export interface InstancesAPI {
/**
* Returns all started activities.
* @param activityType Can be a string or an `ActivityType`.
*/
get(activityType?: string | ActivityType | string[] | ActivityType[]): Activity[];
/**
* Subscribes for activity status events.
* @param handler Handler function that receives the activity, the new and the old activity statuses as parameters.
*/
subscribe(handler: (activity: Activity, newStatus: ActivityStatus, oldStatus: ActivityStatus) => void): void;
/** Unsubscribes from receiving activity status events.
* @param handler Handler function that receives the activity, the new and the old activity statuses as parameters.
*/
unsubscribe(handler: (activity: Activity, newStatus: ActivityStatus, oldStatus: ActivityStatus) => void): void;
}
/**
* Object describing an activity.
*/
export interface Activity {
/** ID of the activity. */
id: string;
/** Type of the activity. */
type: ActivityType;
/** Context of the activity. */
context: any;
/** Status of the activity. */
status: ActivityStatus;
/** Owner window. */
owner: ActivityWindow;
/** List of all windows participating in the activity (including the owner window). */
windows: ActivityWindow[];
/**
* Creates a new window and joins it to the activity.
* @param windowType Type of the window to be created and joined to the activity.
* @param callback Optional callback function to handle the result. Receives the created activity window as a parameter.
*/
createWindow(windowType: string | WindowDefinition, callback?: (aw: ActivityWindow) => void): Promise<ActivityWindow>;
/**
* Creates a stacked set of windows and joins them to the activity.
* @param windowTypes Types of windows to create and join to the activity.
* @param timeout Optional timeout.
* @param callback Optional callback to handle the result. Receives an array of the created activity windows as a parameter.
*/
createStackedWindows(windowTypes: (string | WindowDefinition)[], timeout?: number, callback?: (aw: ActivityWindow[]) => void): Promise<ActivityWindow[]>;
/**
* Returns all windows of a given type participating in the activity.
* @param windowType Type of activity windows to return.
*/
getWindowsByType(windowType: string): ActivityWindow[];
/**
* Replaces the activity context with a new one.
* @param context Context object with which to replace the current activity context.
* @param callback Optional callback function to handle the result. Receives the activity as a parameter.
*/
setContext(context: any, callback?: (activity: Activity) => void): Promise<object>;
/**
* Updates the activity context with the properties from the provided context object.
* If the old context values are `{ a: 1, b: 2, c: 3 }`, invoking `updateContext({ b: 3, c: null, d: 4 })` will result in
* the following context state: `{ a: 1, b: 3, d: 4 }`.
* @param context Context object with which to update the existing activity context.
* @param callback Optional callback function to handle the result. Receives the activity as a parameter.
*/
updateContext(context: any, callback?: (activity: Activity) => void): Promise<object>;
/**
* Subscribes for activity status change events.
* @param handler Handler function for the event. Receives the activity, the new and the old activity statuses as parameters.
*/
onStatusChange(handler: (activity: Activity, newStatus: ActivityStatus, oldStatus: ActivityStatus) => void): () => void;
/**
* Subscribes for window related events, like joining or removing a window from the activity.
* @param handler Handler function for the event. Receives the activity, the window and the event as parameters.
*/
onWindowEvent(handler: (activity: Activity, window: ActivityWindow, event: ActivityWindowEvent) => void): () => void;
/**
* Subscribes for activity context updates.
* @param handler Handler function for the event.
*/
onContextChanged(handler: ContextUpdateHandler): void;
/** Stops the activity and closes all windows. */
stop(): void;
/**
* @ignore
* Creates a new activity with the same set of windows.
* @param options Cloning options.
*/
clone(options: CloneOptions): Promise<Activity>;
/**
* @ignore
* Attaches the current activity to another activity. This stops the current activity. It can be restored by using the returned `AttachedActivityDescriptor`.
* @param activity Activity to which to attach the current activity.
* @param tag
*/
attach(activity: Activity | string, tag?: object): Promise<AttachedActivityDescriptor>;
/**
* @ignore
* Subscribes for the event which fires when another activity is attached the current one.
* @param callback Callback function to handle the event. Receives the `AttachedActivityDescriptor` object of the attached activity as an argument.
*/
onActivityAttached(callback: (descriptor: AttachedActivityDescriptor) => void): void;
/**
* @ignore
* Subscribes for the event which fires when another activity is detached from this one.
* @param callback Callback function to handle the event. Receives the restored activity and its `AttachedActivityDescriptor` object as arguments.
*/
onDetached(callback: (newActivity: Activity, descriptor: AttachedActivityDescriptor) => void): void;
}
/**
* Object for overriding the activity type definition when initiating a new activity of a specified type.
*/
export interface OverrideTypeDefinition {
/** Owner window. */
owner: WindowDefinition;
/** Helper windows. */
helpers: WindowDefinition[];
}
/**
* Activity context update handler.
*
* @param context The full context object after the update.
* @param delta Object that contains only the changed context properties.
* @param removed Array of strings with the names of the removed properties.
* @param activity The activity that was updated.
*/
type ContextUpdateHandler = (context: object, delta: object, removed: string[], activity: Activity) => void;
/** The status of the activity instance. */
interface ActivityStatus {
/** Returns the activity instance state. */
getState(): string;
/** Returns the message for the activity status. */
getMessage(): string;
/** Returns the time of the activity status. */
getTime(): Date;
}
/** Activity window events for joining and leaving an activity. */
enum ActivityWindowEvent {
Joined,
Removed
}
/** Defines an activity window. */
interface WindowDefinition {
/** Window type. */
type: string;
/** Window name. */
name: string;
/** Whether the window is independent or not. */
isIndependent: boolean;
/** Distance of the top left window corner from the left edge of the screen. */
left?: number;
/** Distance of the top left window corner from the top edge of the screen. */
top?: number;
/** Width of the window. */
width?: number;
/** Height of the window. */
height?: number;
/** Positions the new window relatively to an existing window. */
relativeTo?: string | RelativeWindow;
/** Relative direction of positioning the new window. Considered only if `relativeTo` is supplied. Can be "bottom", "top", "left", "right". */
relativeDirection?: string;
/** Whether to use an existing window when creating a new window. */
useExisting?: boolean;
/** The context of the new window. */
context?: object;
/** Deprecated. Do not use, to be removed. */
arguments?: object;
/** Deprecated. */
windowStyleAttributes?: object;
}
/** Existing window used to relatively position another window. */
export interface RelativeWindow {
/** Type of the window that will be used to relatively position the new window. */
type?: string;
/** ID of the window that will be used to relatively position the new window. */
windowId?: string;
}
/**
* An activity type is a definition template for an activity consisting of a collection of window types,
* their layout and an initial activity context.
*/
interface ActivityType {
/** Name of the activity type. */
name: string;
/** Description of the activity type. */
description: string;
/** A list of window types that will be created when initiating a new instance of that activity type. */
helperWindows: WindowDefinition[];
/** Returns the definition of the owner window of that activity type. */
ownerWindow: WindowDefinition;
/**
* Initiates a new activity of this type.
* @param context The initial context to be used for the new activity.
* @param callback Optional callback to handle the result. Receives the created activity and a configuration object
* with which you can override the default activity definition.
*/
initiate(context: object, callback?: (activity: Activity) => void, configuration?: OverrideTypeDefinition | WindowDefinition[]): Promise<Activity>;
}
/** A window type is a definition of a window, typically configured in **io.Connect Desktop**. */
interface WindowType {
/** Name of the window type. */
name: string;
/** Returns the **io.Connect Desktop** configuration related to this window type (as an application object from the AppManager API) */
config: object;
/** All windows from that type. */
windows: ActivityWindow[];
}
/** Object defining the window bounds. */
interface WindowBounds {
/** Distance of the top left window corner from the top edge of the screen. */
top?: number;
/** Distance of the top left window corner from the left edge of the screen. */
left?: number;
/** Width of the window. */
width?: number;
/** Height of the window. */
height?: number;
}
/**
* A window participating in an activity.
*/
interface ActivityWindow {
/** ID of the window. */
id: string;
/** Name of the window. */
name: string;
/** Type of the window. */
type: WindowType;
/** The activity that the window is a part of. */
activity: Activity;
/** If `true`, the window is the owner of the activity. */
isOwner: boolean;
/** The Interop instance of that window. You can use it to invoke Interop methods for that window. */
instance: IOConnectDesktop.Interop.Instance;
/** Returns the window as an object from the Window Management API (`io.windows`). */
underlyingWindow: Windows.IOConnectWindow;
/** If `true`, this is an independent window. */
isIndependent(): boolean;
/**
* Sets window visibility.
* @param isVisible If `true`, the window will be visible.
* @param callback Optional callback to handle the result. Receives the activity window as an argument.
*/
setVisible(isVisible: boolean, callback?: (aw: ActivityWindow) => void): Promise<ActivityWindow>;
/**
* Activates the window.
* @param focus If `true`, the window will be on focus.
*/
activate(focus: boolean): Promise<ActivityWindow>;
/** Returns the window bounds. */
getBounds(): Promise<WindowBounds>;
/**
* Sets the window bounds.
* @param bounds Window bounds object.
* @param callback Optional callback to handle the result. Receives the activity window as an argument.
*/
setBounds(bounds: WindowBounds, callback?: (aw: ActivityWindow) => void): Promise<ActivityWindow>;
/** Closes the window. */
close(): Promise<any>;
/**
* Subscribes for the event which fires when the window joins an activity.
* @param callback Callback to handle the event. Receives as an argument the activity which the window has joined.
*/
onActivityJoined(callback: (activity: Activity) => void): void;
/**
* Subscribes for the event which fires when the window leaves an activity.
* @param callback Callback to handle the event. Receives as an argument the activity which the window has left.
*/
onActivityRemoved(callback: (activity: Activity) => void): void;
}
/**
* @ignore
* Object describing an activity that has been attached to another activity.
* Can be used to restore the attached activity.
*/
interface AttachedActivityDescriptor {
/** ID of the owner window of the attached activity. */
ownerId: string;
/** Helper windows IDs. */
windowIds: string[];
/** The frame color of the attached activity. */
frameColor: string;
/** Context object of the attached activity. */
context: object;
/** */
tag: object;
/**
* Restores the activity by detaching it from the activity it was previously attached to.
* @param descriptor Object describing the attached activity.
*/
detach(descriptor?: AttachedActivityDescriptor): Promise<Activity>;
}
/**
* @ignore
* Options for cloning an activity.
*/
interface CloneOptions {
/** Context for the new activity. */
context: object;
/** Offset from the top left corner of the original activity. */
offset: { left: number, top: number };
}
}
/**
* @docname App Management
* @intro
* The App Management API provides a way to manage **io.Connect Desktop** apps. It offers abstractions for:
*
* - *Application* - a program as a logical entity, registered in **io.Connect Desktop** with some metadata (name, description, icon, etc.)
* and with all the configuration needed to spawn one or more instances of it.
* The App Management API provides facilities for retrieving app metadata and for detecting when an app is started.
*
* - *Instance* - a running copy of an app. The App Management API provides facilities for starting/stopping app instances and tracking app-related events.
*
* The App Management API is accessible through the `io.appManager` object.
*/
namespace AppManager {
/**
* App Management API.
*/
export interface API extends AppManager, Entitlements {
/**
* Returns the current app instance.
*/
myInstance: Instance;
/**
* Returns the current app.
*/
myApplication: Application;
/**
* API for handling app definitions at runtime.
*/
inMemory: InMemoryStore;
/**
* Notifies when the App Management API is ready to be used.
*/
ready(): Promise<void>;
/**
* Exits io.Connect.
*/
exit(options?: ExitOpts): Promise<any>;
/**
* Restarts io.Connect.
*/
restart(options?: ExitOpts): Promise<any>;
/**
* Notifies when io.Connect will shut down or restart. If the callback is asynchronous, it will be awaited up to 60 seconds before shutdown continues.
* @param callback Callback function for handling the event.
*/
onShuttingDown(callback: (args: ShuttingDownEventArgs) => Promise<{ prevent: boolean }>): void;
}
/**
* Describes the event for shutting down io.Connect.
*/
export interface ShuttingDownEventArgs {
/**
* If `true`, io.Connect is restarting.
*/
restarting: boolean;
/**
* Describes the Interop instance that has initiated the shutdown.
*/
initiator?: IOConnectDesktop.Interop.Instance;
/**
* Reason for the shutdown.
*/
reason?: string;
}
/**
* API for handling app definitions at runtime. The API methods operate only on in-memory app definitions.
*/
export interface InMemoryStore {
/**
* Imports the provided collection of app definitions.
* @param definitions A collection of app definition objects to be imported.
* @param mode Mode for importing app definitions. Use `"replace"` (default) to replace all existing in-memory app definitions.
* Use `"merge"` to update the existing ones and add new ones.
*/
import(definitions: Definition[], mode?: "replace" | "merge"): Promise<ImportResult>;
/**
* Exports all available app definitions from the in-memory store.
*/
export(): Promise<Definition[]>;
/**
* Removes an app definition from the in-memory store.
* @param name Name of the app to be removed.
*/
remove(name: string): Promise<void>;
/**
* Removes all app definitions from the in-memory store.
*/
clear(): Promise<void>;
}
/**
* Describes the result from importing app definitions at runtime.
*/
export interface ImportResult {
/**
* Array of names of the successfully imported apps as specified in their definitions.
*/
imported: string[];
/**
* Array of objects describing errors from importing app definitions.
*/
errors: { app: string; error: string }[];
}
/**
* App Management API that allows you to handle your interop-enabled apps.
*/
export interface AppManager {
/**
* Retrieves an app by name.
* @param name Name of the desired app.
*/
application(name: string): Application | undefined;
/**
* Retrieves a collection of the available apps.
*/
applications(): Application[];
/**
* Retrieves a collection of all running app instances.
*/
instances(): Instance[];
/**
* Retrieves the configurations of the specified apps.
* @param apps List of names of the apps for which to retrieve configurations.
*/
getConfigurations(apps?: string[]): Promise<Definition[]>;
getConfigurations(apps: string[]): Promise<Record<string, any>>;
/**
* Notifies when a new app instance is started.
* @param callback Callback function for handling the event.
*/
onInstanceStarted(callback: (instance: Instance) => any): UnsubscribeFunction;
/**
* Notifies when starting a new app instance has failed.
* @param callback Callback function for handling the event.
*/
onInstanceStartFailed(callback: (instance: Instance) => any): UnsubscribeFunction;
/**
* Notifies when an app instance is stopped.
* @param callback Callback function for handling the event.
*/
onInstanceStopped(callback: (instance: Instance) => any): UnsubscribeFunction;
/**
* Notifies when an app instance is updated.
* @param callback Callback function for handling the event.
*/
onInstanceUpdated(callback: (instance: Instance) => any): UnsubscribeFunction;
/**
* Notifies when an app is registered in the environment.
* @param callback Callback function for handling the event.
*/
onAppAdded(callback: (app: Application) => any): UnsubscribeFunction;
/**
* Notifies when an app is removed from the environment.
* @param callback Callback function for handling the event.
*/
onAppRemoved(callback: (app: Application) => any): UnsubscribeFunction;
/**
* Notifies when an app is available and can be started.
* @param callback Callback function for handling the event.
*/
onAppAvailable(callback: (app: Application) => any): UnsubscribeFunction;
/**
* Notifies when an app is no longer available and can't be started.
* @param callback Callback function for handling the event.
*/
onAppUnavailable(callback: (app: Application) => any): UnsubscribeFunction;
/**
* Notifies when the configuration for an app has changed.
* @param callback Callback function for handling the event.
*/
onAppChanged(callback: (app: Application) => any): UnsubscribeFunction;
}
/** @ignore */
interface Entitlements {
/** Returns the region under which the API operates. */
getRegion(success?: (region: string) => any, error?: (err: any) => any): void | Promise<string>;
/**
* Returns the list of branches for which the user has coverage.
* Returns an error if your application does not have access to App Management admin functionality.
*/
getBranches(success?: (branches: Branch[]) => any, error?: (err: any) => any): void | Promise<Branch[]>;
/**
* Retrieves the user branch that the API operates under.
* Returns an error if your application does not have access to App Management admin functionality.
*/
getCurrentBranch(success?: (branch: Branch) => any, error?: (err: any) => any): void | Promise<Branch>;
/**
* Returns the effective entitlement value for a specific function.
* Returns null if there's no such functional entitlement.
* The entitlements depend on the branch that is selected.
* Most applications will typically only care about the function name.