Class: LauncherClient

Launcher Client

The Launcher Client handles spawning windows. It also maintains the list of spawnable components.

Methods

addToGroups
(params, cb)
clients/launcherClient.js, line 789

Name Type Description
params *
Name Type Description
windowIdentifier LauncherClient~windowIdentifier optional

Optional. Current window is assumed if not specified.

groupNames Array optional

List of groupnames to add window to. Groups will be created if they do not exist.

cb *

getActiveDescriptors
(cb)
clients/launcherClient.js, line 515

Gets the LauncherClient~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 array of windowDescriptors

getComponentDefaultConfig
(componentType, cb)
clients/launcherClient.js, line 95

Get the component config (i.e. 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)
clients/launcherClient.js, line 79

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)
clients/launcherClient.js, line 572

Gets components that can receive specfic data types. Returns an object containing a of ComponentTypes mapped to a list of dataTypes they can receive. This is based on the "advertiseReceivers" property in a component's config.

Since:
  • 2.0
Name Type Description
params
Name Type Description
dataTypes Array optional

An array of data types. Looks for components that can receive those data types

Example
LauncherClient.getComponentsThatCanReceiveDataTypes({ dataTypes: ['chartiq.chart', 'salesforce.contact']}, function(err, response) {
	//Response contains: {'chartiq.chart': ['Advanced Chart'], 'salesforce.contact': ['Salesforce Contact']}
})

getMonitorInfo
(params, cb)
clients/launcherClient.js, line 132

Gets monitorInfo (dimensions and position) 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 a supplemented OpenFin monitor descriptor which contains:

monitorRect - The full dimensions for the monitor from OpenFin.

availableRect - The dimensions for the available space on the monitor (less windows toolbars).

unclaimedRect - The dimensions for available monitor space less any space claimed by components (such as the application Toolbar).

Each of these is supplemented with the following additional members:

width - The width as calculated (right - left).

height - The height as calculated (bottom - top).

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.

Name Type Description
params object optional

Parameters

Name Type Description
windowIdentifier LauncherClient~windowIdentifier optional

The windowIdentifier to get the monitorInfo. If undefined, then the current window.

monitor any optional

If passed then a specific monitor is identified. Valid values are the same as for LauncherClient#spawn.

cb function

Returns a monitorInfo object containing the monitorRect, availableRect and unclaimedRect.

getMonitorInfoAll
(cb)
clients/launcherClient.js, line 153

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){Promise}
clients/launcherClient.js, line 503

Returns a LauncherClient~windowIdentifier for the current window

Name Type Description
cb LauncherClient~windowIdentifier

Callback function returns windowIdentifier for this window (optional or use the returned Promise)

Returns:
Type Description
Promise A promise that resolves to a windowIdentifier

getRawWindow
clients/launcherClient.js, line 424

Returns an object that provides raw access to a remote window. It returns an object that contains references to the Finsemble windowDescriptor, to the OpenFin window, and to the native JavaScript (browser) window.

This will only work for windows that are launched using the Finsemble Launcher API.

As in any browser, you will not be able to manipulate a window that has been launched cross domain or in a separate physical OpenFin application (separate process). Caution should be taken to prevent a window from being closed by the user if you plan on referencing it directly. Due to these inherent limitations we strongly advise against a paradigm of directly manipulating remote windows through JavaScript. Instead leverage the RouterClient to communicate between windows and to use an event based paradigm!

Deprecated
  • Finsemble now uses a splintering agent which disconnects windows from the main launcher. It becomes impossible to access raw windows. See LauncherClient.getActiveDescriptors() and Util.getFinWindow()
    Name Type Description
    params object

    Parameters

    Name Type Description
    windowName string

    The name of the window to access.

    Returns:
    Type Description
    LauncherClient~rawWindowResult An object containing windowDescriptor, finWindow, and browserWindow. Or null if window isn't found.

    showWindow
    (windowIdentifier, params, cb)
    clients/launcherClient.js, line 210

    Displays a window and relocates/resizes it according to the values contained in params.

    Name Type Description
    windowIdentifier LauncherClient~windowIdentifier

    A windowIdentifier.

    params object

    Parameters. These are the same as LauncherClient#spawn with the folowing exceptions:

    Name Type Default Description
    monitor any optional

    Same as spawn() except that null or undefined means the window should not be moved to a different monitor.

    left any optional

    Same as spawn() except that null or undefined means the window should not be moved from current horizontal location.

    top any optional

    Same as spawn() except that null or undefined means the window should not be moved from current vertical location.

    spawnIfNotFound boolean false optional

    If true, then spawns a new window if the requested one cannot be found. Note, only works if the windowIdentifier contains a componentType.

    slave boolean optional

    Cannot be set for an existing window. Will only go into effect if the window is spawned. (In other words, only use this in conjunction with spawnIfNotFound).

    cb function

    Callback to be invoked after function is completed. Callback contains an object with the following information: windowIdentifier - The LauncherClient~windowIdentifier for the new window. windowDescriptor - The LauncherClient~windowDescriptor of the new window. finWindow - An OpenFin window referencing the new window.

    spawn
    (component, params, cb)
    clients/launcherClient.js, line 381

    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%"

    Since:
    • 2.4.1 Added params.windowType (deprecated params.native), params.path, params.alias, params.argumentsAsQueryString - These are all for launching native apps.
    Name Type Description
    component String

    Type of the component to launch. If null or undefined, then params.url will be used instead.

    params object
    Name Type Default Description
    monitor any "mine" optional

    Which monitor to place the new window. "mine" - Place the window on the same monitor as the calling window. A numeric value of monitor (where primary is zero). "primary","next" and "previous" indicate a specific monitor. "all" - Put a copy of the component on all monitors

    position string unclaimed optional

    Defines a "viewport" for the spawn, with one of the following values:

    "unclaimed" (the default) Positioned based on the monitor space excluding space "claimed" by other components (such as toolbars). For instance, top:0 will place the new component directly below the toolbar.

    "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 joing the top left corner of the new component with the top left corner of the relative window.

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

    dockOnSpawn boolean false optional

    If true, will automatically dock the window with the "relative" window (dock to the parent window unless specified in params.relativeWindow).

    left any 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. Note - the staggering algorithm has a timing element that is optimized based on user testing.

    top any optional

    Same as left except related to the top of the viewport.

    right any optional

    Same as left except releated to the right of the viewport.

    bottom any optional

    Same as left except related to the bottom of the viewport.

    height any optional

    A pixel or percentage value.

    width any optional

    A pixel value or percentage value.

    forceOntoMonitor boolean optional

    If true will attempt to make the window no have parts outside the monitor boundary.

    ephemeral boolean false 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 OpenFin settings assigned: resizable: false, showTaskbarIcon: false, alwaysOnTop: true. Note, use options:{autoShow: false} to prevent an ephemeral widow from showing automatically.

    staggerPixels number 100 optional

    Number of pixels to stagger (default when neither left, right, top or bottom are set).

    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. This will be reflected in the unclaimedRect member from API calls that return monitorInfo. Users will be prevented from moving windows to a position that covers the claimed space. See position: 'unclaimed'.

    relativeWindow LauncherClient~windowIdentifier current window optional

    The window to use when calculating any relative launches. If not set then the window from which spawn() was called.

    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.

    url string optional

    Optional url to launch. Overrides what is passed in "component".

    native string optional

    @deprecated Please use windowType instead. Optional native application to launch with Assimilation service. Overrides what is passed in "component".

    windowType string openfin optional

    Optional. Describes which type of component to spawn.

    openfin - A normal OpenFin 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.

    native - A native window that has implemented finsemble.dll. Requires "path" to be specified. For more information.

    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 OpenFin application (such as from a third party). For more information on integrating Openfin apps.

    alias string optional

    Used when windowType is "native" or "assimilation". Specifies the alias of an OpenFin bundled asset.

    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 (i.e. notepad.exe). The full path to an executable on the user's machine (i.e. C:\Program Files\app.exe) A system installed uri (i.e. myuri://myapp).

    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

    openfinVersion - The openfin version that Finsemble runs (necessary for native windows to connection on the OpenFin IAB)

    openfinSocketPort - The openfin socket used for the IAB (necessary for Java windows that wish to use the OpenFin IAB)

    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.

    arguments string 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. Note that when params.argumentsAsQueryString is true, arguments should be a single string in uri format (i.e. a=1&b=2)

    argumentsAsQueryString boolean optional

    For native applications launched by URI, the automatic arguments assigned by path are converted into a query string.

    name string optional

    Optional window name. If not provided, then a random name will be assigned to the newly created OpenFin window.

    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.

    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.

    options LauncherClient~windowDescriptor optional

    Properties to merge with the default windowDescriptor. Any value set here will be sent directly to the OpenFin window, and will override the effect of relevant parameters to spawn(). See http://cdn.openfin.co/jsdocs/stable/fin.desktop.Window.html#~options for the full set and defaults, with the following exception:

    Name Type Default Description
    frame boolean false optional

    By default, all Finsemble windows are frameless

    addToWorkspace boolean false optional

    Whether to add the new component to the workspace. Even when true, the window will still not be added to the workspace if addToWorkspace==false in components.json config for the component type.

    cb function optional

    Callback to be invoked after function is completed. Callback contains an object with the following information: windowIdentifier - The {@LauncherClient~windowIdentifier} for the new component. windowDescriptor - The {@LauncherClient~windowDescriptor} for the new window. finWindow - An OpenFin window object that contains the spawned component.

    toggleWindowOnClick
    (element, windowIdentifier, params)
    clients/launcherClient.js, line 169

    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 | selector

    The DOM element, or selector, clicked by the end user

    windowIdentifier windowIdentifier

    Identifies the child window

    params object

    Parameters to be passed to LauncherClient#showWindow if the child window is allowed to open

    Type Definitions

    rawWindowResultobject

    A convenient assembly of native JavaScript window, OpenFin window and windowDescriptor.

    Properties:
    Name Type Description
    windowDescriptor LauncherClient~windowDescriptor

    The window descriptor.

    finWindow Fin.Desktop.Window

    The OpenFin window.

    browserWindow Window

    The native JavaScript window.

    windowDescriptorobject

    Finsemble windowDescriptor. This is a superset of the Openfin windowOptions object. In addition to the values provided by OpenFin, the windowDescriptor includes the following values.

    Properties:
    Name Type Argument Description
    url string <optional>

    url to load (if HTML5 component).

    native string <optional>

    The name of the native app (if a native component launched by Assimilation service).

    name string

    The name of the window (sometimes randomly assigned).

    componentType string

    The type of component (from components.json).

    windowIdentifier

    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.

    Properties:
    Name Type Argument Description
    windowName string <optional>

    The name of the physical OpenFin window, or a reference to a native window that was launched with Assimilation service

    uuid string <optional>

    Optional uuid of a particular OpenFin application process

    componentType string <optional>

    The type of component

    monitor number <optional>

    The number of the monitor. Potentially used to disambiguate multiple components with the same name (for searches only)