Module: AppsClient

The Apps Client (formerly known as the Launcher Client) handles spawning apps and app services, and auxiliary functions such as adding or removing them from config dynamically or retrieving details of running instances (active descriptors).

The AppsClient API has capabilities to customize your end user's experience, by altering the apps available to them or customizing them at launch. For example, it can apply custom CSS-like positioning and fully display-aware positioning that deals with idiosyncrasies such as monitors with different scaling resolutions.

CSS provides higher level abstractions that help lay out an application that consists of constituent parts. Finsemble has borrowed CSS’s positioning paradigm and applied it to the task of laying out windows on the desktop. For example, this CSS-style positioning allows windows to be positioned on the left, right, top, or bottom of the end user’s screen. We've also developed new positions, such as adjacent, which allows a child window to spawn adjacent to their parent or another application.

Application windows can also be positioned and sized by percentage, relative to the monitor or to each other.

The Apps Client frequently uses the parameters windowName and componentType. Learn more about them here.

Type Aliases

AppIcons

Ƭ AppIcons: Object

Type declaration

Name	Type
taskbarIcon?	IconDescriptor
titleBarIcon	IconDescriptor
toolbarIcon	IconDescriptor

---

ComponentDescriptor

Ƭ ComponentDescriptor: Record<string, any>

---

ComponentList

Ƭ ComponentList: Record<string, ComponentDescriptor>

---

CompositeComponentData

Ƭ CompositeComponentData: Object

deprecated - kept to ensure backwards compatibility, will be removed (or used by real composite components) in a future version

Type declaration

Name	Type
closeComponentsTogether	boolean
compositeComponentUUID	string

---

ConnectId

Ƭ ConnectId: string | undefined | null

---

IconDescriptor

Ƭ IconDescriptor: IconUrl | IconInitials & { category?: string }

---

IconInitials

Ƭ IconInitials: Object

Type declaration

Name	Type
imageType	"initials"
name	string

---

IconUrl

Ƭ IconUrl: Object

Type declaration

Name	Type
imageType	"url" | "fonticon"
path	string

---

LaunchGroupComponentData

Ƭ LaunchGroupComponentData: Object

Type declaration

Name	Type
closeComponentsTogether	boolean
launchGroupComponentUUID	string
launchGroupId?	string

---

MonitorChoice

Ƭ MonitorChoice: number | "mine" | "primary" | "next" | "previous" | "all"

---

MonitorCommand

Ƭ MonitorCommand: "mine" | "primary" | "previous" | "next" | "" | number

---

MonitorCoordinates

Ƭ MonitorCoordinates: Object

Type declaration

Name	Type
bottom	number
height	number
left	number
right	number
top	number
width	number

---

MonitorInfo

Ƭ MonitorInfo: any

---

MonitorInfoDetail

Ƭ MonitorInfoDetail: Object

Type declaration

Name	Type
availableRect	MonitorCoordinates
deviceId	string
deviceScaleFactor	number
displayDeviceActive	boolean
monitor	MonitorRectDetails
monitorRect	MonitorCoordinates
name	string
position?	number
rawMonitor?	MonitorInfoDetail
taskbar?	MonitorInfoTaskbarDetails
whichMonitor?	number | "primary"

---

MonitorInfoTaskbarDetails

Ƭ MonitorInfoTaskbarDetails: Object

Type declaration

Name	Type
bottom	number
edge	"bottom" | "top" | "left" | "right"
height	number
left	number
right	number
top	number
width	number

---

MonitorRectDetails

Ƭ MonitorRectDetails: Object

Type declaration

Name	Type
dipRect	MonitorCoordinates
scaledRect	MonitorCoordinates

---

PositionTypes

Ƭ PositionTypes: "available" | "monitor" | "relative" | "virtual" | "absolute"

All the possible position types that can be used to define the spawn viewport

"available" Positioned according to the coordinates available on the monitor itself, less space claimed by the operating system (such as the windows toolbar). For instance, bottom:0 will place the new component with its bottom flush against the windows toolbar.

"monitor" Positioned according to the absolute size of the monitor. For instance, top:0 will place the component overlapping the toolbar.

"relative" Positioned relative to the relativeWindow. For instance, left:0;top:0 will join the top left corner of the new component with the top left corner of the relative window.

"virtual" Positioned against coordinates on the virtual screen. The virtual screen is the full viewing area of all monitors combined into a single theoretical monitor.

"absolute" Positioned using native operating system coordinates. Only available with showWindow, not with spawn.

---

SpawnOptions

Ƭ SpawnOptions: Object

Type declaration

Name	Type	Description
Content-Security-Policy?	string | string[]	-
alwaysOnTop?	boolean	-
autoShow?	boolean	-
backgroundThrottling?	boolean	-
bottom?	number | string	A pixel value representing the distance from the bottom edge of the viewport as defined by "position". You can also use the percentage value, which represents the percentage distance from the bottom edge of the viewport relative to the viewport's height.
contextMenu?	boolean	-
cornerRounding?	{ height?: number ; width?: number }	-
cornerRounding.height?	number	-
cornerRounding.width?	number	-
customData?	Record<string, any>	-
height?	number | string	A pixel or percentage value.
isEvergreen?	boolean	-
left?	number | string	A pixel value representing the distance from the top edge of the viewport as defined by "position". You can also use the percentage value, which represents the percentage distance from the top edge of the viewport relative to the viewport's height. "adjacent" will snap to the right edge of the spawning or relative window. "center" will center the window If neither left nor right are provided, then the default will be to stagger the window based on the last spawned window.
opacity?	number	-
openLinksInExternalBrowser?	boolean	-
permissions?	any	-
resizable?	boolean	-
right?	number | string	A pixel value representing the distance from the right edge of the viewport as defined by "position". You can also use the percentage value, which represents the percentage distance from the right edge of the viewport relative to the viewport's width.
securityPolicy?	"trusted" | "untrusted"	-
showTaskbarIcon?	boolean	-
top?	number | string	A pixel value representing the distance from the top edge of the viewport as defined by "position". You can also use the percentage value, which represents the percentage distance from the top edge of the viewport relative to the viewport's height.
width?	number | string	A pixel or percentage value.
windowSpawnTimeout?	number	-
windowTitleBarUrl?	string	-

---

SpawnParams

Ƭ SpawnParams: Object

The parameters passed to Launcher.Spawn.

If properties are duplicated between the the app configuration those passed as parameters to spawn, parameters passed to spawn generally take precedence.

Type declaration

Name	Type	Description
addToTabCollection?	string | boolean	Adds the spawned app to a tab collection. If you supply a tabCollectionId string, Finsemble adds the app to the specified tab collection. If you supply a boolean, Finsemble attempts to tab with the calling window or the supplied relativeWindow argument.
addToWorkspace?	boolean	Defaults to false. Whether to add the new component to the workspace. The addToWorkspace config value set at the component level overwrites this value.
affinity?	string | boolean	Process affinity setting that allows render threads for web windows (served from the same 'site') to be grouped together to save memory. Group render process together thoughtfully by setting the same string value or disable rendering process grouping by setting false.
alias?	string	Used when windowType is "native" or "assimilation". Specifies the alias of a bundled asset.
arguments?	any	Used when windowType is "native" or "assimilation". Specifies the arguments to be sent to the application. This is used in conjunction with path. Arguments should be separated by spaces: --arg1 foo --arg2 bar except when params.argumentsAsQueryString is true, in which case set this parameter to be single string in URI format: arg=1&arg=2"
argumentsAsQueryString?	boolean	For native applications launched by URI: 1) the string is passed as the "arguments" parameter if appended as a query string; and 2) the automatically generated arguments described in "path" are appended to the query string
bottom?	number | string	A pixel value representing the distance from the bottom edge of the viewport as defined by "position". For non-absolute positions, you can also use the percentage value, which represents the percentage distance from the bottom edge of the viewport relative to the viewport's height.
canGroup?	boolean	Whether the component can group with other windows.
claimMonitorSpace?	boolean	For use with permanent toolbars. The available space for other components will be reduced by the amount of space covered by the newly spawned component. Users will be prevented from moving windows to a position that covers the claimed space.
closeComponentsTogether?	boolean	Defaults to false. Whether to close all components within a launchGroup component at the same time.
component?	any	Type of component to spawn.
componentState?	Record<string, any>	Populate the initial component state on spawn.
compositeComponentData?	CompositeComponentData	deprecated
connectId?	string	-
data?	any	Optional data to pass to the opening window. If set, then the spawned window can use WindowClient#getSpawnData to retrieve the data.
dockOnSpawn?	boolean	deprecated Please use groupOnSpawn instead. If true, will automatically group the window with the "relative" window (grouping to the parent window unless specified in params.relativeWindow). Note that you must also position the window in a valid position for grouping, for example, by setting the "left" or "top" parameters to "adjacent".
dockable?	["top", "bottom"] | ["bottom", "top"] | ["top"] | ["bottom"]	An array of parts of the monitor that the component can dock to. Valid values are top and bottom.
docked?	"top" | "bottom"	Which part of the monitor that the component will dock to on spawn. Valid options are top and bottom. Only valid if combined with the dockable property.
dockedHeight?	number	Currently, components can only dock to the full width of the monitor. This parameter determines what height the component will be when docked to a monitor.
env?	any	Sets environment variables for a spawned native application. Create a map (JSON) object of names to values. This is only available when running Assimilation.
ephemeral?	boolean	Indicates that this window is ephemeral. An ephemeral window is a dialog, menu, or other window that is temporarily displayed but usually hidden. Ephemeral windows automatically have the following settings assigned: resizable: false, showTaskbarIcon: false, alwaysOnTop: true. Note: Use options:{autoShow: false} to prevent an ephemeral widow from showing automatically.
forceOntoMonitor?	boolean | string	If true, will attempt to make the window have no edges outside the monitor boundary.
frame?	boolean	-
groupName?	string	Optional group name. Adds windows to a group (unrelated to docking or linking) that is used for window management functions. If the group does not exist it will be created.
groupOnSpawn?	boolean	Groups the window to the relativeWindow on spawn. Note that you must also position the window in a valid position for grouping, for example, by setting the "left" or "top" parameters to "adjacent".
height?	number | string	A pixel or percentage value.
launchGroupComponentData?	LaunchGroupComponentData	-
launchingWindow?	WindowIdentifier	Where the spawn request is coming from.
left?	number | string	A pixel value representing the distance from the left edge of the viewport as defined by "position". Must be numeric for absolute positions. You can also use the percentage value, which represents the percentage distance from the left edge of the viewport relative to the viewport's width. "adjacent" will snap to the right edge of the spawning or relative window. "center" will center the window If neither left nor right are provided, then the default will be to stagger the window based on the last spawned window.
maxHeight?	number	Maximum height window can be resized to.
maxWidth?	number	Maximum width window can be resized to.
minHeight?	number	Minimum height window can be resized to.
minWidth?	number	Minimum width window can be resized to.
monitor?	MonitorChoice	Which monitor to place the new window. "mine" - Place the window on the same monitor as the calling window. Integer value from 0-n (0 being the primary monitor). "primary" indicates the user's primary monitor. "all" - Put a copy of the component on all monitors.
name?	string	Name to give the component. If not provided, a random one will be generated.
native?	boolean	deprecated Please use windowType instead. Optional native application to launch with Assimilation service. Overrides what is passed in "component".
options?	SpawnOptions & { cachedBounds?: any ; execJSWhitelist?: any ; minWidth?: number ; name?: string ; newStack?: boolean ; preloadScripts?: any ; transparent?: any ; windowState?: any }	Properties to merge with the default windowDescriptor. Any value set here will be sent directly to the WebWindow, and will override the effect of relevant parameters to spawn(). By default, all Finsemble windows are frameless. FEA Permissions and window properties (such as always on top) are provided here.
path?	string	Used when windowType is "native" or "assimilation". Specifies the path to the application. The path can be: The name of an exe that is on the system path (e.g., notepad.exe). The full path to an executable on the user's machine (e.g., C:\Program Files\app.exe). A system installed URI (e.g., myuri://advancedapplauncher). When windowType is "native" then additional arguments will be automatically appended to the path or the URI. These arguments can be captured by the native application in order to tie it to Finsemble's window tracking. When building an application with finsemble.dll, this is handled automatically. Those arguments are: uuid - A generated UUID that uniquely identifies this window. left - The x coordinate of the new window top - The y coordinate of the new window width - The width of the new window height - The height of the new window finsembleWindowName - The name of the window in the Finsemble config componentType - The component type in the Finsemble config A common troublesome problem is when a native application needs to be launched from an intermediary application (such as a launcher or batch script). That intermediary application can pass these parameters which will allow the final application to connect back to Finsemble.
position?	PositionTypes	Defines a "viewport" for the spawn, with one of the Position Types: available - Positioned according to the coordinates available on the monitor itself, less space claimed by the operating system (such as the windows toolbar). For instance, bottom:0 will place the new component with its bottom flush against the windows toolbar. monitor - Positioned according to the absolute size of the monitor. For instance, top:0 will place the component overlapping the toolbar. relative - Positioned relative to the relativeWindow. For instance, left:0;top:0 will join the top left corner of the new component with the top left corner of the relative window. virtual - Deprecated. Positioned against coordinates on the virtual screen. The virtual screen is the full viewing area of all monitors combined into a single theoretical monitor. absolute - Positioned using native operating system coordinates. Only available with showWindow, not with spawn.
relativeWindow?	WindowIdentifier	The window to use when calculating any relative launches. If not set then the window from which spawn() was called.
right?	number | string	A pixel value representing the distance from the right edge of the viewport as defined by "position". For non-absolute positions, you can also use the percentage value, which represents the percentage distance from the right edge of the viewport relative to the viewport's width.
setBoundsOnly?	boolean	If true, then visibility of window will not be changed. In other words, a hidden window will not be made visible.
slave?	boolean	If true then the new window will act as a slave to the relativeWindow (or the launching window if relativeWindow is not specified). Slave windows will automatically close when their parent windows close.
spawnedByWorkspaceService?	boolean
staggerPixels?	number	Number of pixels to stagger (default when neither left, right, top or bottom are set).
tabTitle?	string	Optional - sets a tab title for the window.
toSpawn?	[object]	An array of objects defining the components to spawn. Each entry may either represent a single component in the form {componentType, spawnOptions} or a tabbed window of components in the form {components, spawnOptions}, where components is an array of single component definitions (again in the form {componentType, spawnOptions}). Most arguments that are normally passed to LauncherClient.spawn are supported, although positioning will be interpreted as relative to the group's coordinates and dimensions for single components and ignored for tabbed components (as these use the position specified in the group's spawnOptions). Note - This param will only be taken into account if the windowType param is 'composite' OR 'launchGroup'.
top?	number | string	A pixel value representing the distance from the top edge of the viewport as defined by "position". For non-absolute positions, you can also use the percentage value, which represents the percentage distance from the top edge of the viewport relative to the viewport's height.
url?	string	Optional url to launch. Overrides what is passed in "component".
width?	number | string	A pixel or percentage value.
windowIdentifier?	WindowIdentifier	Component instances are often referred to in Finsemble API calls via a windowIdentifier. A windowIdentifier is an object with both windowName and componentType properties.
windowInterop?	WindowInterop	-
windowTitleBarUrl?	string	-
windowType?	WindowTypes	Optional. Describes which type of component to spawn. WebWindow - A normal HTML window. assimilation - A window that is managed by the Finsemble assimilation process (usually a native window without source code access). Requires "path" to be specified, which may be the name of an executable on the system path, a system file path or system installed URI. native - A native window that has implemented finsemble.dll. Requires "path" to be specified. application - A standalone application that will be launched in its own browser process (giving it dedicated CPU and memory). This can also point to a standalone web application (such as from a third party). composite - DEPRECATED - Use launchGroup. launchGroup - A component composed of other components, usually group together. See toSpawn property.

---

SpawnResponse

Ƭ SpawnResponse: Object

Type declaration

Name	Type
launchGroupWindows?	string[]
windowDescriptor	WindowDescriptor
windowIdentifier	WindowIdentifier

---

SpawnTabCollectionResponse

Ƭ SpawnTabCollectionResponse: Object

Type declaration

Name	Type
id	string
windows	SpawnResponse[]

---

WindowDescriptor

Ƭ WindowDescriptor: Object

Used to define the parameters for creating a Window.

Type declaration

Name	Type	Description
affinity?	string | boolean	Process affinity setting that allows render threads for web windows (served from the same 'site') to be grouped together to save memory. Group render process together thoughtfully by setting the same string value or disable rendering process grouping by setting false.
allowAutoArrange?	boolean	-
alwaysOnTop?	boolean	-
alwaysOnTopLevel?	string | null	-
autoShow?	boolean	-
backgroundColor?	string	-
bottom?	number	-
bounds?	{ bottom: number ; height: number ; left: number ; right: number ; top: number ; width: number }	-
bounds.bottom	number	-
bounds.height	number	-
bounds.left	number	-
bounds.right	number	-
bounds.top	number	-
bounds.width	number	-
canGroup?	boolean	-
childWindowOptions?	{ component?: any ; foreign?: any ; window?: any }	-
childWindowOptions.component?	any	-
childWindowOptions.foreign?	any	-
childWindowOptions.window?	any	-
claimMonitorSpace?	boolean	-
componentType?	string	The name of the component in this window. E.g "Welcome Component", etc.
customData?	{ appConfig?: any ; component?: any ; foreign?: any ; interop?: any ; isAnApp?: boolean ; manifest?: any ; monitorDimensions?: any ; spawnData?: any ; window?: any }	-
customData.appConfig?	any	-
customData.component?	any	-
customData.foreign?	any	-
customData.interop?	any	-
customData.isAnApp?	boolean	-
customData.manifest?	any	-
customData.monitorDimensions?	any	-
customData.spawnData?	any	-
customData.window?	any	-
defaultBottom?	number	-
defaultHeight?	number	-
defaultLeft?	number	-
defaultRight?	number	-
defaultTop?	number	-
defaultWidth?	number	-
execJSWhitelist?	string[]	-
external?	boolean	-
height?	number	-
hideTitleBar?	boolean	-
icons?	AppIcons	-
launchGroupComponentData?	LaunchGroupComponentData	-
left?	number	-
manifest?	{}	-
maxHeight?	number	-
maxWidth?	number	-
minHeight?	number	-
minWidth?	number	-
monitorInfo?	any	-
name?	string	-
opacity?	number	-
path?	string	-
permissions?	{ Application?: {} ; System?: {} ; Window?: {} }	-
permissions.Application?	{}	-
permissions.System?	{}	-
permissions.Window?	{}	-
preload?	any[]	-
preloadScripts?	any[]	-
resizable?	boolean	-
right?	number	-
securityPolicy?	string	-
showTaskbarIcon?	boolean	-
top?	number	-
transparent?	boolean	-
url?	string	-
uuid?	string	-
width?	number	-
windowInterop?	WindowInterop	-
windowTitleBarUrl?	string	-
windowType?	string	-
x?	number	-
y?	number	-

---

WindowIdentifier

Ƭ WindowIdentifier: Object

An object that includes all the potential identifications for a window. For instance, one can try and obtain a reference for a window if some of these values are known.

Type declaration

Name	Type	Description
componentType?	string | null	The type of component
uuid?	string	uuid is deprecated
waitForReady?	boolean	-
windowName	string	The name of the physical HTML window, or a reference to a native window that was launched with Assimilation service
windowType?	string	-

---

WindowInterop

Ƭ WindowInterop: Object

Type declaration

Name	Type
connectId?	ConnectId
grandParent?	WindowIdentifier
launchGroupId?	string
parent?	WindowIdentifier

---

WindowLocator

Ƭ WindowLocator: { windowName: string } | { componentType: string ; uuid?: string }

---

WindowTypes

Ƭ WindowTypes: "WebWindow" | "NativeWindow" | "assimilation" | "assimilated" | "native" | "FinsembleNativeWindow" | "application" | "WebApplication" | "composite" | "launchGroup" | "Citrix" | "external"

All the possible window types, including their aliases used in config.

Functions

addApps

▸ addApps(apps, cb?): StandardPromise<FDC3AppDefinition[]>

Adds to Finsemble new FDC3 App definition(s), in the form of an array of FDC3 2.0 AppD records. After the apps are added, a user can launch them via the Apps Client, fdc3.open, fdc3.raiseIntent or Toolbar launcher menus.

const { err, data } = await FSBL.Clients.AppsClient.addApps([anFDC3App]);

You can update apps by correlating the appIds. Example:

// Get MyApp
const { data: apps } = await FSBL.Clients.AppsClient.getApps(["MyApp"]);
const myApp = apps[0];

// Update MyApp name to "My App New Name"
app.name = `MyApp New Name`;

// Update the app in Finsemble
await FSBL.Clients.AppsClient.addApps([app]);

Parameters

Name	Type	Description
apps	FDC3AppDefinition[]	he array of FDC3 2.0 AppD records (FDC3AppDefinition) to add to Finsemble.
cb?	StandardErrorCallback<any>	The callback to be invoked after the apps are set or on error.

Returns

StandardPromise<FDC3AppDefinition[]>

A promise that resolves to an array of the added app objects.

---

clone

▸ clone(toClone?, spawnParams?, cb?): Promise<{ error?: StandardError ; response?: SpawnResponse }>

Clone an existing component. Will clone the calling window if no window is specified. Cannot clone freestanding or singleton components.

FSBL.Clients.AppsClient.clone(
  { windowName: "window-to-clone" },
  { left: 0, top: 0 },
  (err, data) => {},
);

Parameters

Name	Type	Description
toClone?	null | WindowIdentifier	An optional WindowIdentifier of the window to clone. If you don't provide this parameter, Finsemble tries to clone the calling window.
spawnParams?	null | SpawnParams	Optional spawn parameters that override the cloned window params on spawn.
cb?	StandardErrorCallback<SpawnResponse>	An optional callback that is called when spawn has completed.

Returns

Promise<{ error?: StandardError ; response?: SpawnResponse }>

---

getActiveDescriptors

▸ getActiveDescriptors(cb?): StandardPromise<Record<string, WindowDescriptor>>

Gets the windowDescriptor for all open windows.

note

This returns descriptors even if the window is not part of the workspace.

FSBL.Clients.AppsClient.getActiveDescriptors(function (error, response) {
  if (error) {
    Logger.system.error(
      "Error getting active descriptors: ",
      +JSON.stringify(error),
    );
  } else {
    const activeDescriptors = response;
    //{
    //  ...
    //  Toolbar-1-Finsemble: {...},
    //  Welcome-Component-80-6453-Finsemble: {...},
    //  ...
    //}
  }
});

Parameters

Name	Type	Description
cb?	StandardErrorCallback<Record<string, WindowDescriptor>>	Callback returns an object containing windowDescriptors keyed by name.

Returns

StandardPromise<Record<string, WindowDescriptor>>

---

getApps

▸ getApps(appIds?, cb?): StandardPromise<FDC3AppDefinition[]>

Retrieves the AppD records for a specified list appIds known to Finsemble.

Parameters

Name	Type	Description
appIds?	string[]	an array of app IDs to retrieve. If not provided, Finsemble retrieves all apps.
cb?	StandardErrorCallback<any>	The callback to be invoked after the apps are retrieved or on error.

Returns

StandardPromise<FDC3AppDefinition[]>

A promise that resolves to an array of app objects.

---

getComponentDefaultConfig

▸ getComponentDefaultConfig(componentType, cb?): StandardPromise<ComponentDescriptor>

Get the component config for a specific component from components.json.

const { err, data } = await FSBL.Clients.AppsClient.getComponentDefaultConfig(
  "ChartIQ Example App",
);

Parameters

Name	Type	Description
componentType	string	The type of the component.
cb?	StandardErrorCallback<ComponentDescriptor>	Callback returns the default config (windowDescriptor) for the requested componentType.

Returns

StandardPromise<ComponentDescriptor>

---

getComponentList

▸ getComponentList(cb?): StandardPromise<ComponentList>

Get a list of registered components from components.json.

const { err, data } = await FSBL.Clients.AppsClient.getComponentList();
if (!err) {
  console.log(data);
  // {
  //   "Toolbar": { ... },
  //   "Tour": { ... },
  //   ...
  // }
}

Parameters

Name	Type	Description
cb?	StandardErrorCallback<ComponentList>	Callback returns an object map of components. Each component object contains the default config for that component.

Returns

StandardPromise<ComponentList>

---

getMonitorInfo

▸ getMonitorInfo(params?, cb?): StandardPromise<MonitorInfoDetail>

Get monitor information for a given windowIdentifier or for a specific monitor. If neither the identifier nor monitor are provided, returns the monitorInfo for the current window.

The information returned contains:

monitorRect - The full dimensions for the monitor.
availableRect - The dimensions for the available space on the monitor (not including the Windows task bar).
position - A number that represents the position of the monitor. The primary monitor is zero.
whichMonitor - Contains the string "primary" if it is the primary monitor.

The dimensions are supplemented with the following additional members:

width - The width calculated as right - left.
height - The height calculated as bottom - top.

// Get the info for the monitor that the calling app is on
const { err, data } = await FSBL.Clients.AppsClient.getMonitorInfo();
if (!err) {
  console.log(data);
  // Example results:
  // {
  //    availableRect: {width, height, bottom, left, ...},
  //   deviceId: "123456",
  //   deviceScaleFactor: 2,
  //   displayDeviceActive: true,
  //   monitor: {dipRect, scaledRect},
  //   monitorRect: {width, height, bottom, left, right, ...}
  //   name: "device0",
  //   position: 0,
  //   taskbar: {top, left, right, bottom, width, ...}
  //   whichMonitor: "primary"
  // }
}

// Get monitor info for a given window
const { err, data } = await FSBL.Clients.AppsClient.getMonitorInfo({
  windowIdentifier: {
    windowName: "ABC-uuid",
  },
});
if (!err) {
  console.log(
    `App ABC-uuid is currently on the monitor with index ${data.position}`,
  );
}

// Get the dimensions of the first non-primary monitor
const { err, data } = await FSBL.Clients.AppsClient.getMonitorInfo({
  monitor: 1,
});
if (!err) {
  console.log("Available dimensions for monitor[1]: ", data.monitorRect);
  console.log(
    "Available dimensions, minus claimed space, for monitor[1]: ",
    data.availableRect,
  );
}

Parameters

Name	Type	Description
params	Object
params.monitor?	MonitorCommand	If passed then a specific monitor is identified. Valid values include: "mine" - Place the window on the same monitor as the calling window. Integer value from 0-n (0 being the primary monitor). "primary" indicates the user's primary monitor. "all" - Put a copy of the component on each monitor.
params.windowIdentifier?	WindowIdentifier	The windowIdentifier to get the monitorInfo. If undefined, this points to the current window.
cb?	StandardErrorCallback<MonitorInfoDetail>	Returns a monitorInfo object containing the monitorRect and availableRect.

Returns

StandardPromise<MonitorInfoDetail>

A promise that resolves to a monitorInfo.

---

getMonitorInfoAll

▸ getMonitorInfoAll(cb?): StandardPromise<MonitorInfoDetail[]>

Get monitorInfo (dimensions and position) for all monitors. Returns an array of monitorInfo objects. See AppsClient#getMonitorInfo for the format of a monitorInfo object.

const {err, data} = await FSBL.Clients.AppsClient.getMonitorInfoAll();
if(!err){
console.log(`There are ${data.length} monitors.`);
}

Parameters

Name	Type	Description
cb?	StandardErrorCallback<MonitorInfoDetail[]>	Returns an array of monitorInfo objects.

Returns

StandardPromise<MonitorInfoDetail[]>

---

getMyWindowIdentifier

▸ getMyWindowIdentifier(cb?): Promise<WindowIdentifier>

Returns a windowIdentifier for the current window.

const myWindowIdentifier =
  await FSBL.Clients.AppsClient.getMyWindowIdentifier();
console.log(myWindowIdentifier);
// {
//   windowName: "ABC-uuid",
//   componentType: "ABC"
// }

Parameters

Name	Type	Description
cb?	(windowIdentifier: WindowIdentifier) => void	Callback function returns windowIdentifier for this window. (Optional or use the returned Promise)

Returns

Promise<WindowIdentifier>

A promise that resolves to a windowIdentifier.

---

removeApps

▸ removeApps(appIds, cb?): StandardPromise<string[]>

Removes from Finsemble one or more apps,specified via an array of appId values. After an app is removed, it can no longer be launched via the AppsClient, fdc3.open, fdc3.raiseIntent or launcher menus. Removed applications are automatically removed from launcher menus.

Existing instances of the apps are NOT closed automatically when removed, either from the current workspace or saved workspaces. However, saved workspaces containing them are unable to launch them when the workspace is loaded.

const { err, data } = await FSBL.Clients.AppsClient.removeApps(["fdc3AppId"]);

Parameters

Name	Type	Description
appIds	string[]	-
cb?	StandardErrorCallback<any>	The callback to be invoked after the apps are removed or on error.

Returns

StandardPromise<string[]>

A promise that resolves to an array of the removed appId strings.

---

showWindow

▸ showWindow(windowLocator, params, cb?): StandardPromise<SpawnResponse>

Displays a window and relocates/resizes it according to the values contained in parameters. If the specified window is in a group or tabbed, it is unsnapped/ungrouped/untabbed from the other windows. If invoked on a tabbed window or a window in a group, the window is removed from the tab/group.

Caution: A window can inherit parameters only once, at the time when it’s spawned. When the component already exists, changing parameters other than positioning arguments (monitor, relativeWindow, top, bottom, left, right, width, height) has no effect.

FSBL.Clients.AppsClient.showWindow(
  {
    windowName: "Welcome Component-86-3416-Finsemble",
    componentType: "Welcome Component",
  },
  { spawnIfNotFound: true },
  (err, data) => {},
);

Parameters

Name	Type	Description
windowLocator	WindowLocator	-
params	any	Configuration settings from the finsemble.appd[].manifest.window section of the application manifest may be used as parameters to this function, except for the options element. These are the same as AppsClient.spawn() with the following exceptions: monitor - Same as spawn() except that null or undefined means don't move the window to a different monitor. left - Same as spawn() except that null or undefined means don't move the window from current horizontal location. top - Same as spawn() except that null or undefined means don't move the window from current vertical location. slave - Cannot be set for an existing window. Goes into effect only if the window is spawned. In other words, use this only in conjunction with spawnIfNotFound. spawnIfNotFound - If true, spawns a new window if the requested one cannot be found. Note: only works if the windowIdentifier contains a componentType. autoFocus - Whether or not the window should be in focus when shown.
cb?	StandardErrorCallback<SpawnResponse>	Callback to be invoked after the function is completed regardless of whether the call fails or succeeds. Callback contains two arguments in the following order: error: an object containing details related to the reason the call failed and where the exception occurred. This object is null if the call has succeeded. data: an object with the following information: windowIdentifier - The WindowIdentifier for the new window. windowDescriptor - The WindowDescriptor of the new window. finWindow - A finWindow object referencing the new window.

Returns

StandardPromise<SpawnResponse>

---

spawn

▸ spawn(component, params, cb?): Promise<{ error?: StandardError ; response?: SpawnResponse }>

Asks the Launcher service to spawn a new component. You can also specify any of the following parameters in public/config/components.json, which will then operate as the default for that value.

The launcher parameters mimic CSS window positioning. For example, to set a full screen window, use {left: 0, top: 0, right: 0, bottom: 0}. This is functionally equivalent to {left: 0, top: 0, width: "100%", height: "100%"}.

You can also spawn more than one component at a time by using a single action, such as clicking a button on a menu. See https://github.com/ChartIQ/finsemble-seed/tree/recipes/SpawnComponentGroup for an example of spawning a component group.

FSBL.Clients.AppsClient.spawn(
  "Welcome Component",
  { left: 0, top: 0, position: "relative" },
  (err, data) => {},
);

Parameters

Name	Type	Description
component	string	The application or component to spawn.
params	SpawnParams	Configuration settings from the finsemble.appd[].manifest.window section of the application manifest may be used as parameters to this function, except for the options element.
cb?	StandardErrorCallback<SpawnResponse>	Function invoked after the window is created

Returns

Promise<{ error?: StandardError ; response?: SpawnResponse }>

---

spawnTabCollection

▸ spawnTabCollection(__namedParameters, cb?): StandardPromise<SpawnTabCollectionResponse>

Spawns a set of apps and assembles them into a tab collection. you can specify spawn parameters for the entire collection or for individual apps. However, positioning parameters (e.g. left or top) are disregarded when set on individual apps.

await FSBL.Clients.AppsClient.spawnTabCollection({
  componentList: [
    { appID: "Welcome Component", individualParams: { alwaysOnTop: true } },
  ],
  globalParams: { left: 100, top: 100 },
});

Parameters

Name	Type	Description
__namedParameters	Object	-
__namedParameters.componentList	{ appID: string ; individualParams?: SpawnParams }[]	The apps to open. Each should be an object that contains the appID (from AppD) and an optional set of SpawnParams.
__namedParameters.globalParams?	TabbedGlobalSpawnParams	Positioning parameters for the collection. If omitted, the collection is spawned in a default location.
cb?	StandardErrorCallback<SpawnTabCollectionResponse>	-

Returns

StandardPromise<SpawnTabCollectionResponse>

• Resolves to an object that contains the ID of the tab collection and the list of window names for the spawned apps

---

toggleWindowOnClick

▸ toggleWindowOnClick(element, windowLocator, params): void

A convenient method for dealing with a common use case of toggling the appearance and disappearance of a child window when a user presses a button of a dropdown menus. Call this method from the click handler for your element. Your child window needs to close itself on blur events. Caution: A window can inherit parameters only once, at the time when it’s spawned. When the component already exists, changing parameters other than positioning arguments (monitor, relativeWindow, top, bottom, left, right, width, height) has no effect.

Parameters

Name	Type	Description
element	HTMLElement	The DOM element, or selector, clicked by the end user.
windowLocator	WindowLocator	-
params	any	Parameters to be passed to AppsClient.showWindow() if the child window is allowed to open

Returns

void