@glue42/desktop
Version:
Glue42 desktop library
1,178 lines (1,004 loc) • 265 kB
TypeScript
import { ApplicationConfig } from "@glue42/schemas";
import { Glue42Core } from "@glue42/core";
import { Glue42Workspaces } from "@glue42/workspaces-api";
import { UnsubscribeFunction } from "callback-registry";
/**
* Factory function that creates a new Glue42 instance.
*/
export default function Glue(config?: Glue42.Config): Promise<Glue42.Glue>;
/**
* @docname Glue
* @intro
* **Glue42 Enterprise** is a real-time user interface (UI) integration platform. Apps are combined at the user
* interface level to provide a better user experience (UX).
* UI integration makes it easier for users to access the right data and functionality at the right time and also reduce
* the number of times they need to copy/paste their way between one app and another.
* **Glue42 Enterprise** provides intuitive paths from one function to the next, in order to deliver business outcomes quickly and reliably.
* It allows developers to connect to any (legacy, 3rd party or modern)
* web or desktop app and have multiple apps interact with each other in real time.
*
* The Glue42 JavaScript library enables JavaScript apps to participate in **Glue42 Enterprise** and use Glue42 functionalities via a set of APIs.
*
* ## Referencing the Library
*
* ### From a JavaScript File
*
* Glue42 JavaScript is a library available as a single JavaScript file, which you can include in your web apps using a `<script>` tag.
* If you are using a Glue42 installer, you can find the JavaScript files in `%LOCALAPPDATA%\Tick42\GlueSDK\GlueJS\js\web`.
*
* ```html
* <script type="text/javascript" src="desktop.umd.js"></script>
* ```
*
* When deploying your app in production, it is recommended to always reference a specific minified version:
*
* ```html
* <script type="text/javascript" src="desktop.umd.min.js"></script>
* ```
*
* **Using the Glue42 CDN**
*
* You can alternatively point to Glue42 JavaScript `npm` packages and files via the [Glue42 CDN](https://cdn.glue42.com/) by using URLs in the format:
*
* ```html
* https://cdn.glue42.com/:package@:version/:file
* ```
*
* - Using the latest version: `https://cdn.glue42.com/desktop@latest`;
* - Using a fixed version: `https://cdn.glue42.com/desktop@5.6.1`
* - Using a specific file different from the one defined in the `package.json`: `https://cdn.glue42.com/browse/desktop@5.6.1/dist/web/@glue42/desktop.min.js`
* - To see all available versions and files, append `/` to the URL: `https://cdn.glue42.com/desktop/`
*
* ### From an NPM Module
*
* The Glue42 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 [`@glue42/core`](https://www.npmjs.com/package/@glue42/core) and
* [`@glue42/desktop`](https://www.npmjs.com/package/@glue42/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 include any of the packages as a dependency in your project, navigate to the root directory of your project and run:
*
* ```cmd
* npm install @glue42/desktop
* ```
*
* Your `package.json` file now should have an entry similar to this:
*
* ```json
* {
* "dependencies": {
* "@glue42/desktop": "^5.6.1"
* }
* }
* ```
*
* ## Initializing the Library
*
* When included, the JavaScript library will register a global factory function called `Glue()`.
* It should be invoked with an *optional* configuration object to initialize the library. The factory function will resolve with the initialized `glue` API object.
*
* Initialization in a Glue42 Window:
*
* ```javascript
* import Glue from "@glue42/desktop"
*
* // You don't need to specify any configuration.
* const initializeGlue42 = async () => {
* window.glue = await Glue();
* };
*
* initializeGlue42().catch(console.error);
* ```
* See also the [**Glue42 Enterprise** documentation](../../../../getting-started/how-to/glue42-enable-your-app/javascript/index.html) for more details.
*/
export declare namespace Glue42 {
export import AGM = Glue42Core.AGM;
export import Contexts = Glue42Core.Contexts;
export import Connection = Glue42Core.Connection;
export import Logger = Glue42Core.Logger;
export import Metrics = Glue42Core.Metrics;
export import Auth = Glue42Core.Auth;
export import FeedbackInfo = Glue42Core.FeedbackInfo;
export import Channels = Glue42.Channels.API;
export import ChannelContext = Glue42.Channels.ChannelContext;
export import Interop = Glue42Core.Interop;
export import GDObject = Glue42Core.GDObject;
export import GlueDesktopObject = Glue42Core.GlueDesktopObject;
export import GatewayConfig = Glue42Core.GatewayConfig;
export import MetricsConfig = Glue42Core.MetricsConfig;
export import InprocGWSettings = Glue42Core.InprocGWSettings;
export import GwTokenProvider = Glue42Core.GwTokenProvider;
export import LoggerConfig = Glue42Core.LoggerConfig;
/**
* Optional configuration object when initializing the Glue42 library.
*/
export interface Config extends Glue42Core.Config {
/**
* Initializes or disables the App Management API.
* @default "startOnly"
*/
appManager?: boolean | Glue42.AppManager.Mode;
/**
* Initializes or disables the Layouts API.
* @default "slim"
*/
layouts?: boolean | Glue42.Layouts.Mode | Glue42.Layouts.Configuration;
/**
* Initializes or disables the Activities API.
* @default "trackMyTypeAndInitiatedFromMe"
*/
activities?: boolean | Glue42.Activities.ActivitiesModes;
/**
* Initializes or disables the Window Management API.
* @default true
*/
windows?: boolean;
/**
* Initializes or disables the Channels API.
* @default false
*/
channels?: boolean;
/**
* Initializes or disables the Displays API.
* @default true
*/
displays?: boolean;
/**
* Configuration for the Intents Resolver UI.
*/
intents?: Intents.Config;
/**
* A list of Glue42 factory functions that will be initialized internally to provide access to specific functionalities.
*/
libraries?: ((glue: Glue42.Glue, config?: Glue42.Config) => Promise<void>)[];
/**
* Determines whether Glue42 will share the initialized API object upon request via a custom web event.
* @default true
*/
exposeGlue?: boolean;
}
/**
* Instance of the initialized Glue42 library.
*/
export interface Glue extends Glue42Core.GlueCore {
/**
* Window Management API.
*/
windows: Glue42.Windows.API;
/**
* Activities API.
*/
activities: Glue42.Activities.API;
/**
* App Management API.
*/
appManager: Glue42.AppManager.API;
/**
* Layouts API.
*/
layouts: Glue42.Layouts.API;
/**
* Channels API.
*/
channels: Glue42.Channels.API;
/**
* Hotkeys API.
* @since Glue42 3.6
*/
hotkeys: Glue42.Hotkeys.API;
/**
* Displays API.
* @since Glue42 3.9
*/
displays: Glue42.Displays.API;
/**
* Intents API.
* @since Glue42 3.9
*/
intents: Glue42.Intents.API;
/**
* Notifications API.
* @since Glue42 3.9
*/
notifications: Glue42.Notifications.API;
/**
* Workspaces API.
* @since Glue42 3.10
*/
workspaces?: Glue42Workspaces.API;
/**
* Themes API.
* @since Glue42 3.10
*/
themes?: Glue42.Themes.API;
/**
* App Preferences API.
* @since Glue42 3.12
*/
prefs: Glue42.Preferences.API;
/**
* Cookies API.
* @since Glue42 3.16
*/
cookies: Glue42.Cookies.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 `glue.activities` object.
*/
namespace Activities {
/** @ignore */
export interface LoggerConfig {
publish: string;
console: string;
metrics: string;
}
/** Activities configuration object. */
// eslint-disable-next-line @typescript-eslint/no-shadow
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 Glue42 library, you don't need to use this
* as the Glue42 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 Glue42 Desktop. */
interface WindowType {
/** Name of the window type. */
name: string;
/** Returns the Glue42 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: Glue42Core.AGM.Instance;
/** Returns the window as an object from the Window Management API (`glue.windows`). */
underlyingWindow: Windows.GDWindow;
/** 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 **Glue42 Enterprise** apps. It offers abstractions for:
*
* - *Application* - a program as a logical entity, registered in **Glue42 Enterprise** 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 `glue.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.
* @since Glue42 3.12
*/
inMemory: InMemoryStore;
/**
* Notifies when the App Management API is ready to be used.
*/
ready(): Promise<void>;
/**
* Exits Glue42.
*/
exit(options?: ExitOpts): Promise<any>;
/**
* Restarts Glue42.
*/
restart(options?: ExitOpts): Promise<any>;
/**
* Notifies when Glue42 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.
* @since Glue42 3.11
*/
onShuttingDown(callback: (args: ShuttingDownEventArgs) => Promise<{ prevent: boolean }>): void;
}
/**
* Object passed as an argument to the callback for handling the Glue42 shutdown event.
*/
export interface ShuttingDownEventArgs {
/**
* If `true`, Glue42 is restarting.
*/
restarting: boolean;
/**
* Describes the Interop instance that has initiated the shutdown.
*/
initiator?: Glue42.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 Glue42 enabled apps. */
export interface AppManager {
/**
* Retrieves an app by name.
* @param name Name of the desired app.
*/
application(name: string): Application;
/**
* 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.
* @since Glue42 3.17
*/
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