Class: LauncherClient
Launcher Client (Finsemble Workspaces)
The Launcher Client handles spawning windows of all kinds. Finsemble provides the architecture to launch, resize, and reposition any component, whether native, modern, or third-party.
The Launcher API has capabilities to customize your end user's experience. This includes CSS-like positioning and a fully display-aware positioning that deals with idiosyncrasies such as monitors with different scaling resolutions.
CSS provides higher level abstractions that aid in laying out an application that is composed of constituent parts.
Finsemble has borrowed CSS’s positioning paradigm and applied it to the task of laying out windows on the desktop.
This CSS-style positioning allows windows to be positioned on the left
, right
, top
, or bottom
of the end user’s screen for instance; we also developed new positions, such as adjacent
, which allows a child window to spawn adjacent to their parent.
Components can be positioned and sized by percentage, relative to the monitor or to each other (nested windows).
The Launcher Client frequently uses the parameters windowName
and componentType
. Learn more about them here.
Methods
-
addEventListener(event, handler)
-
Name Type Description event
string handler
Function -
getActiveDescriptors(cb)
-
Gets the windowDescriptor for all open windows.
Note: This returns descriptors even if the window is not part of the workspace.
Name Type Description cb
Function Callback returns an object containing windowDescriptors keyed by name.
Example
FSBL.Clients.LauncherClient.getActiveDescriptors(function (error, response) { if (error) { Logger.system.error("Error getting active descriptors: ", + JSON.stringify(error)); } else { const activeDescriptors = response.data; //{ // ... // Toolbar-1-Finsemble: {...}, // Welcome-Component-80-6453-Finsemble: {...}, // ... //} } });
-
getComponentDefaultConfig(componentType, cb)
-
Get the component config (from components.json) for a specific component.
Name Type Description componentType
string The type of the component.
cb
Function Callback returns the default config (windowDescriptor) for the requested componentType.
-
getComponentList(cb)
-
Get a list of registered components (those that were entered into components.json).
Name Type Description cb
Function Callback returns an object map of components. Each component object contains the default config for that component.
-
getComponentsThatCanReceiveDataTypes(params, cb)
-
Gets components that can receive specific data types. Returns an object containing componentTypes mapped to a list of dataTypes they can receive. This is based on the "advertiseReceivers" property in a component's config.
Name Type Description params
Name Type Description dataTypes
string[] An array of data types. Looks for components that can receive those data types.
cb
Function The callback to be invoked after the method completes successfully.
Example
FSBL.Client.LauncherClient.getComponentsThatCanReceiveDataTypes({ dataTypes: ['chartiq.chart', 'salesforce.contact']}, function(err, response) { //Response contains: {'chartiq.chart': ['Advanced Chart'], 'salesforce.contact': ['Salesforce Contact']} })
-
getMonitorInfo(params, cb)
-
Gets monitor information for a given windowIdentifier or for a specific monitor. If neither the identifier or monitor are provided then the monitorInfo for the current window is returned.
The information returned contains:
monitorRect - The full dimensions for the monitor.
availableRect - The dimensions for the available space on the monitor (less the Windows task bar).
position - The position of the monitor, numerically from zero to X. 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 as calculated (right - left).
height - The height as calculated (bottom - top).Name Type Description params
Name Type Description monitor
string optional 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 all monitors.
windowIdentifier
identifier optional The windowIdentifier to get the monitorInfo. If undefined, then the current window.
cb
Function Returns a monitorInfo object containing the monitorRect and availableRect.
-
getMonitorInfoAll(cb)
-
Gets monitorInfo (dimensions and position) for all monitors. Returns an array of monitorInfo objects. See LauncherClient#getMonitorInfo for the format of a monitorInfo object.
Name Type Description cb
Function Returns an array of monitorInfo objects.
-
getMyWindowIdentifier(cb)
-
Returns a windowIdentifier for the current window.
Name Type Description cb
Function Callback function returns windowIdentifier for this window (optional or use the returned Promise)
-
locatorToIdentifier(locator)
-
Name Type Description locator
Type Literal | Type Literal Name Type Description N/A
Type Literal N/A
Type Literal Name Type Description windowName
string -
registerComponent(params, cb)
-
Dynamically registers a component with the Launcher Service for the current Finsemble session. This method registers a given component in a component manifest, making it available to an app launcher component. Note: Components registered in this way are removed at the end of Finsemble's current session.
Name Type Description params
Name Type Description componentType
string The key of the component in the component's config.
manifest
any This should be a component manifest, i.e., a component configuration file like components.json.
cb
Function The callback to be invoked after the method completes successfully.
-
removeEventListener(event, handler)
-
Removes an event listener added by addEventListener
Name Type Description event
any An event that was used with addEventListener to add a listener
handler
any The handler that was used with addEventListener for the event
-
showWindow(windowLocator, params, cb)
-
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 will be unsnapped/ungrouped/untabbed from the other windows. * If invoked on a tabbed window or a window in a group, the window will be removed from the tab/group.
Name Type Description windowLocator
Type Literal | Type Literal Name Type Description N/A
Type Literal Name Type Description windowName
string N/A
Type Literal params
ShowWindowParams Name Type Description addToWorkspace
boolean optional 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 optional Set a process affinity flag. This allows windows to grouped together under a single process (a.k.a. Application). This flag is only available when your container is Electron.
alias
string optional Used when windowType is "native" or "assimilation". Specifies the alias of a bundled asset.
arguments
any optional 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 optional 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
autoFocus
boolean optional Whether or not the window should be focused when shown.
bottom
optional A pixel value representing the distance from the top edge of the viewport as defined by "position". A percentage value may also be used, representing the percentage distance from the top edge of the viewport relative to the viewport's height.
canGroup
boolean optional Whether the component can group with other windows.
claimMonitorSpace
boolean optional 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 optional Defaults to false. Whether to close all components within a launchGroup at the same time.
component
any optional Type of component to spawn.
data
any optional Optional data to pass to the opening window. If set, then the spawned window can use WindowClient#getSpawnData to retrieve the data.
dockOnSpawn
boolean optional If true, will automatically dock the window with the "relative" window (dock to the parent window unless specified in params.relativeWindow). Note that you must also position the window in a valid position for docking, for example, by setting the "left" or "top" parameters to "adjacent".
dockable
optional An array of parts of the monitor that the component can dock to. Valid values are `top` and `bottom`.
docked
optional 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 optional 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 optional 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 optional 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
optional If true, will attempt to make the window have no edges outside the monitor boundary.
groupName
string optional 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 optional Groups the window to the `relativeWindow` based on their adjacent position.
height
optional A pixel or percentage value.
launchingWindow
any optional Where the spawn request is coming from.
left
optional A pixel value representing the distance from the left edge of the viewport as defined by "position". A percentage value may also be used, representing 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 optional Maximum height window can be resized to.
maxWidth
number optional Maximum width window can be resized to.
minHeight
number optional Minimum height window can be resized to.
minWidth
number optional Minimum width window can be resized to.
monitor
optional 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 optional Name to give the component. If not provided, a random one will be generated.
native
boolean optional options
any optional 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 optional 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 optional 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
identifier optional The window to use when calculating any relative launches. If not set then the window from which spawn() was called.
right
optional A pixel value representing the distance from the right edge of the viewport as defined by "position". A percentage value may also be used, representing the percentage distance from the right edge of the viewport relative to the viewport's width.
setBoundsOnly
boolean optional If true, then visibility of window will not be changed. In otherwords, a hidden window will not be made visible.
slave
boolean optional 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.
spawnIfNotFound
boolean optional If true, then spawns a new window if the requested one cannot be found. *Note, only works if the windowIdentifier contains a componentType.*
spawnedByWorkspaceService
boolean optional staggerPixels
number optional Number of pixels to stagger (default when neither left, right, top or bottom are set).
toSpawn
optional 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 {@see windowType} param is 'composite'.
top
optional A pixel value representing the distance from the right edge of the viewport as defined by "position". A percentage value may also be used, representing the percentage distance from the bottom edge of the viewport relative to the viewport's width.
url
string optional Optional url to launch. Overrides what is passed in "component".
width
optional A pixel or percentage value.
windowIdentifier
identifier optional Component instances are often referred to in Finsemble API calls via a windowIdentifier. A windowIdentifier is an object with both windowName and componentType properties.
windowType
WindowTypes optional 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. This launch a component in its own browser process (splintered, giving it dedicated CPU and memory). This can also point to a standalone web application (such as from a third party).
composite - A component made of other components, usually group together. See {@see toSpawn} property.
cb
Function Callback to be invoked after the function is completed regardless if the call fails or succeeds. Callback contains two arguments in the following order. 1) error: an object containing details related to the reason the call failed and where the exception occurred. This object will be null if the call has succeeded. 2) 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.Example
FSBL.Clients.LauncherClient.showWindow({windowName: "Welcome Component-86-3416-Finsemble", componentType: "Welcome Component"}, {spawnIfNotFound: true}, (err, data)=> {});
-
spawn(component, params, cb)
-
Asks the Launcher service to spawn a new component. Any parameter below can also be specified in ../config/components.json, which will then operate as the default for that value.
The launcher parameters mimic CSS window positioning. For instance, to set a full size window use `left=0`,`top=0`,`right=0`,`bottom=0`. This is functionally equivalent to: left=0,top=0,width="100%",height="100%".
Name Type Description component
string params
SpawnParams The parameters passed to Launcher.Spawn.
For properties duplicated between the top-level and `options`, `options` takes precedence.
Name Type Description addToWorkspace
boolean optional 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 optional Set a process affinity flag. This allows windows to grouped together under a single process (a.k.a. Application). This flag is only available when your container is Electron.
alias
string optional Used when windowType is "native" or "assimilation". Specifies the alias of a bundled asset.
arguments
any optional 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 optional 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
optional A pixel value representing the distance from the top edge of the viewport as defined by "position". A percentage value may also be used, representing the percentage distance from the top edge of the viewport relative to the viewport's height.
canGroup
boolean optional Whether the component can group with other windows.
claimMonitorSpace
boolean optional 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 optional Defaults to false. Whether to close all components within a launchGroup at the same time.
component
any optional Type of component to spawn.
data
any optional Optional data to pass to the opening window. If set, then the spawned window can use WindowClient#getSpawnData to retrieve the data.
dockOnSpawn
boolean optional If true, will automatically dock the window with the "relative" window (dock to the parent window unless specified in params.relativeWindow). Note that you must also position the window in a valid position for docking, for example, by setting the "left" or "top" parameters to "adjacent".
dockable
optional An array of parts of the monitor that the component can dock to. Valid values are `top` and `bottom`.
docked
optional 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 optional 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 optional 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 optional 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
optional If true, will attempt to make the window have no edges outside the monitor boundary.
groupName
string optional 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 optional Groups the window to the `relativeWindow` based on their adjacent position.
height
optional A pixel or percentage value.
launchingWindow
any optional Where the spawn request is coming from.
left
optional A pixel value representing the distance from the left edge of the viewport as defined by "position". A percentage value may also be used, representing 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 optional Maximum height window can be resized to.
maxWidth
number optional Maximum width window can be resized to.
minHeight
number optional Minimum height window can be resized to.
minWidth
number optional Minimum width window can be resized to.
monitor
optional 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 optional Name to give the component. If not provided, a random one will be generated.
native
boolean optional options
any optional 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 optional 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 optional 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
identifier optional The window to use when calculating any relative launches. If not set then the window from which spawn() was called.
right
optional A pixel value representing the distance from the right edge of the viewport as defined by "position". A percentage value may also be used, representing the percentage distance from the right edge of the viewport relative to the viewport's width.
setBoundsOnly
boolean optional If true, then visibility of window will not be changed. In otherwords, a hidden window will not be made visible.
slave
boolean optional 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 optional staggerPixels
number optional Number of pixels to stagger (default when neither left, right, top or bottom are set).
toSpawn
optional 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 {@see windowType} param is 'composite'.
top
optional A pixel value representing the distance from the right edge of the viewport as defined by "position". A percentage value may also be used, representing the percentage distance from the bottom edge of the viewport relative to the viewport's width.
url
string optional Optional url to launch. Overrides what is passed in "component".
width
optional A pixel or percentage value.
windowIdentifier
identifier optional Component instances are often referred to in Finsemble API calls via a windowIdentifier. A windowIdentifier is an object with both windowName and componentType properties.
windowType
WindowTypes optional 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. This launch a component in its own browser process (splintered, giving it dedicated CPU and memory). This can also point to a standalone web application (such as from a third party).
composite - A component made of other components, usually group together. See {@see toSpawn} property.
cb
Function Function invoked after the window is created
-
toggleWindowOnClick(element, windowLocator, params)
-
A convenience method for dealing with a common use-case, which is toggling the appearance and disappearance of a child window when a button is pressed, aka drop down menus. Simply call this method from the click handler for your element. Your child window will need to close itself on blur events.
Name Type Description element
HTMLElement The DOM element, or selector, clicked by the end user.
windowLocator
Type Literal | Type Literal Name Type Description N/A
Type Literal Name Type Description windowName
string N/A
Type Literal params
SpawnParams The parameters passed to Launcher.Spawn.
For properties duplicated between the top-level and `options`, `options` takes precedence.
Name Type Description addToWorkspace
boolean optional 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 optional Set a process affinity flag. This allows windows to grouped together under a single process (a.k.a. Application). This flag is only available when your container is Electron.
alias
string optional Used when windowType is "native" or "assimilation". Specifies the alias of a bundled asset.
arguments
any optional 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 optional 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
optional A pixel value representing the distance from the top edge of the viewport as defined by "position". A percentage value may also be used, representing the percentage distance from the top edge of the viewport relative to the viewport's height.
canGroup
boolean optional Whether the component can group with other windows.
claimMonitorSpace
boolean optional 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 optional Defaults to false. Whether to close all components within a launchGroup at the same time.
component
any optional Type of component to spawn.
data
any optional Optional data to pass to the opening window. If set, then the spawned window can use WindowClient#getSpawnData to retrieve the data.
dockOnSpawn
boolean optional If true, will automatically dock the window with the "relative" window (dock to the parent window unless specified in params.relativeWindow). Note that you must also position the window in a valid position for docking, for example, by setting the "left" or "top" parameters to "adjacent".
dockable
optional An array of parts of the monitor that the component can dock to. Valid values are `top` and `bottom`.
docked
optional 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 optional 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 optional 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 optional 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
optional If true, will attempt to make the window have no edges outside the monitor boundary.
groupName
string optional 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 optional Groups the window to the `relativeWindow` based on their adjacent position.
height
optional A pixel or percentage value.
launchingWindow
any optional Where the spawn request is coming from.
left
optional A pixel value representing the distance from the left edge of the viewport as defined by "position". A percentage value may also be used, representing 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 optional Maximum height window can be resized to.
maxWidth
number optional Maximum width window can be resized to.
minHeight
number optional Minimum height window can be resized to.
minWidth
number optional Minimum width window can be resized to.
monitor
optional 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 optional Name to give the component. If not provided, a random one will be generated.
native
boolean optional options
any optional 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 optional 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 optional 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
identifier optional The window to use when calculating any relative launches. If not set then the window from which spawn() was called.
right
optional A pixel value representing the distance from the right edge of the viewport as defined by "position". A percentage value may also be used, representing the percentage distance from the right edge of the viewport relative to the viewport's width.
setBoundsOnly
boolean optional If true, then visibility of window will not be changed. In otherwords, a hidden window will not be made visible.
slave
boolean optional 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 optional staggerPixels
number optional Number of pixels to stagger (default when neither left, right, top or bottom are set).
toSpawn
optional 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 {@see windowType} param is 'composite'.
top
optional A pixel value representing the distance from the right edge of the viewport as defined by "position". A percentage value may also be used, representing the percentage distance from the bottom edge of the viewport relative to the viewport's width.
url
string optional Optional url to launch. Overrides what is passed in "component".
width
optional A pixel or percentage value.
windowIdentifier
identifier optional Component instances are often referred to in Finsemble API calls via a windowIdentifier. A windowIdentifier is an object with both windowName and componentType properties.
windowType
WindowTypes optional 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. This launch a component in its own browser process (splintered, giving it dedicated CPU and memory). This can also point to a standalone web application (such as from a third party).
composite - A component made of other components, usually group together. See {@see toSpawn} property.
-
unRegisterComponent(params, cb)
-
Unregisters a component with the Launcher Service.
Name Type Description params
Name Type Description componentType
string The key of the component in the component's config.
cb
Function