Class: WindowClient

Window Client (Finsemble Workspaces)

The Window Client is primarily responsible for managing the windowState (the window's bounds) and componentState (data inside of your component). The reference below is provided in case you'd like to manually trigger events.

The Window Client also injects the window title bar control, which contains controls for minimizing, maximizing, closing, and restoring your window. For information about the window title bar, please see the UI Component tutorial.

Methods

bringWindowToFront
()

Brings the window to the top of all other windows.

Example
FSBL.Clients.WindowClient.bringWindowToFront();

cancelTilingOrTabbing
(params, cb)

This is used to cancel a tabbing or tiling operation.

Name Type Description
params
Name Type Description
windowIdentifier WindowIdentifier

The Finsemble identifier for the window.

cb Function

The callback to be invoked after the method completes successfully.

close
(params, cb)

Closes window. Defaults are to remove the window from the workspace if the user presses the X button, but not if the window is closed via an app-level request (e.g., switching workspaces, so all windows need to close).

Name Type Description
params
Name Type Description
closeWindow boolean

Whether to close the window. On shutdown this method is called, but the Window Service actually closes the window.

ignoreParent boolean optional

Whether or not to update the parent (stack) window when closing.

removeFromWorkspace boolean

Whether to remove the window from the workspace.

userInitiated boolean optional

Whether the user clicked the X, or if the system asked the window to close.

cb StandardCallback

The callback to be invoked after the method completes successfully.

Example
//Close window and remove from workspace (e.g., user closes the window).
FSBL.Clients.WindowClient.close({ removeFromWorkspace: true, closeWindow: true });
//Close window and keep in workspace (e.g., application requests that all windows close themselves).
FSBL.Clients.WindowClient.close({ removeFromWorkspace: false, closeWindow: false });

fitToDOM
(params, cb)

Automatically resizes the height of the window to fit the full DOM of the current window.

Name Type Description
params optional
Name Type Description
maxHeight number optional

Maximum height to make the window.

maxWidth number optional

Maximum width to make the window.

padding
Name Type Description
height number

How much padding around the DOM to add to the height of the window.

width number

How much padding around the DOM to add to the width of the window.

cb Function optional

Optional callback to be invoked after the method completes successfully.

getBounds
(cb)

Returns the object defining bounds for the current window including the position of the left and right edges measured in pixels from the left edge of the monitor, the top and bottom edges measured in pixels from the top edge, and the width and height of the component in pixels. Please note that this method differs from the right and bottom coordinates passed to LauncherClient.spawn(); those are measured from the right and bottom edges of the screen.

Name Type Description
cb StandardCallback

The callback to be invoked after the method completes successfully.

getComponentState
(params, cb)

Given a field, this function retrieves app state. If no params are given, the full state is returned.

Name Type Description
params
Name Type Description
field string optional

Field to retrieve.

fields string[] optional

Fields to retrieve.

windowName string optional

Window whose component state you are retrieving. If null, the default is to the calling window.

cb StandardCallback

The callback to be invoked after the method completes successfully.

Example

The example below shows how we retrieve data to restore the layout in our charts.

FSBL.Clients.WindowClient.getComponentState({
	 field: 'myChartLayout',
}, function (err, state) {
	importLayout(state);
});

FSBL.Clients.WindowClient.getComponentState({
		fields: ['myChartLayout', 'chartType'],
}, function (err, state) {
	var chartType = state['chartType'];
	var myChartLayout = state['myChartLayout'];
});

getCurrentWindow
()

Returns a reference to the current window for the component.

getSpawnData
()

Retrieves data that was set with LauncherClient.spawn.

getWindowIdentifier
()

Returns the window identifier for the current component.

getWindowNameForDocking
()

Gets the window name of current window or the parent, if tabbed. The code that manages window movement will not see a child window if it's part of a stacked window. This function will return the window name that the Window Service cares about for window movement.

getWindowTitle
()

Retrieves the window's title.

Example
var windowTitle = FSBL.Clients.WindowClient.getWindowTitle();

headerCommandChannel
(commandChannel)

Establishes a command channel with the Finsemble window title bar component. The Window Client can update the title bar's state via this channel.

Name Type Description
commandChannel

A function callback that receives commands.

injectHeader
(params, cb)

The Finsemble window title bar is injected if either FSBLHeader: true or FSBLHeader is an object with the same items as the properties of params below are in the component's config. If you want to inject the window title bar later, you can do so by calling this function.

Name Type Description
params InjectHeaderParams | boolean optional
Name Type Description
InjectHeaderParams
Name Type Description
bodyMarginTop string

Sets the body margin (e.g. "25px"). Default is "auto" which will measure the height of the injected component when rendered.

bumpElements
Name Type Description
absolute

Either false, "all" or "0Positioned". If all, all fixed elements are moved. 0Positioned only moves elements that have top 0. Only applies to children of the document.body. Default is all.

bumpBy string

Sets the amount to bump elements by (e.g. "25px"). Default is "auto" which will measure the height of the injected component when rendered.

fixed

Either false, "all" or "0Positioned". If all, all fixed elements are moved. 0Positioned only moves elements that have top 0. Default is all.

component string

Component to inject. Default is "windowTitleBar"

forceHeaderHeight boolean

Sets a height on the main FSBLHeader div. Either false or a specified height (e.g. "25px").

cb StandardCallback

maximize
(cb)

Maximizes the window taking into account any claimed space on the monitor.

Name Type Description
cb Function

Optional callback to be invoked after the method completes successfully.

Example
FSBL.Clients.WindowClient.maximize();

minimize
(cb)

Minimizes window.

Name Type Description
cb StandardCallback

Optional callback to be invoked after the method completes successfully.

Example
FSBL.Clients.WindowClient.minimize();

removeComponentState
(params, cb)

Given a field, this function removes it from app state.

Name Type Description
params

Object of data to be removed

Name Type Description
field string optional

The key name of the field to be saved. Required if not using `fields`.

fields optional

An array of objects with `field` keys to be removed.

windowName string optional

The name of the window to remove component state from

cb StandardCallback

The callback to be invoked after the method completes successfully.

Example

The example below shows how we would remove our chart layout when it no longer needed.

// remove unused state value
FSBL.Clients.WindowClient.removeComponentState({ field: 'myChartLayout'});
FSBL.Clients.WindowClient.removeComponentState({ fields: [{field:'myChartLayout'}, {field:'chartType'}]);

restore
(cb)

Restores window from a maximized or minimized state.

Name Type Description
cb StandardCallback

Optional callback to be invoked after the method completes successfully.

Example
FSBL.Clients.WindowClient.restore();

sendIdentifierForTilingOrTabbing
(params, cb)

This is used to let Finsemble know which window is being dragged. params.windowIdentifier must be the identifier of the tab being dragged. This is only used if the identifier is unknown when startTilingOrTabbing is called.

Name Type Description
params

The windowIdentifier is required.

Name Type Description
windowIdentifier WindowIdentifier

The Finsemble identifier for the target window.

cb Function

The callback to be invoked after the method completes successfully.

setAlwaysOnTop
(alwaysOnTop, cb)

Sets whether window is always on top. By default, this is false.

Name Type Description
alwaysOnTop boolean

The new mode for the window's alwaysOnTop option to be set to.

cb Function optional

Optional callback to be invoked after the method completes successfully.

Example
FSBL.Clients.WindowClient.setAlwaysOnTop(true);

setComponentState
(params, cb)

Given a field, this function sets and persists app state.

Name Type Description
params

Object of data to be saved

Name Type Description
field string optional

The key name of the field to be saved. Required if not using `fields`.

fields optional

An array of objects with `field` and `value` keys to be saved.

value any optional

Value of the data being saved. Required if not using `fields`.

windowName string optional

Name of the component whose state you are setting. Defaults to the calling window.

cb StandardCallback

The callback to be invoked after the method completes successfully.

Example

The example below shows how we save our chart layout when it changes.

var s = stx.exportLayout(true);
//saving layout'
FSBL.Clients.WindowClient.setComponentState({ field: 'myChartLayout', value: s });
FSBL.Clients.WindowClient.setComponentState({ fields: [{field:'myChartLayout', value: s }, {field:'chartType', value: 'mountain'}]);

setWindowTitle
(title)

This function sets the window's title in the windowTitleBar component, and in the DOM's title element. This is useful to set the title dynamically based on state information: you can keep the window's title in sync with a piece of data (e.g., a Symbol). This title will not persist between sessions automatically; use setComponentState/getComponentState to persist the title.

Name Type Description
title any

Window title.

Example

The code shows how you would change your window title.

 FSBL.Clients.WindowClient.setWindowTitle("My Component's New Title");

showAtMousePosition
()

Moves the window so that it's centered above the user's mouse.

startMovingWindow
(event)

Begin programmatically moving the window; the first parameter is a mouse event. Until `stopMovingWindow` is invoked, the window will follow the user's mouse. This should be invoked inside of a `mouseDown` event handler.

Name Type Description
event MouseEvent

startTilingOrTabbing
(params, cb)

This is used by the Finsemble window title bar when a tab is dragged for tiling or tabbing.

Name Type Description
params

params.windowIdentifier is required.

Name Type Description
windowIdentifier WindowIdentifier

The Finsemble identifier for the target window.

cb Function

The callback to be invoked after the method completes successfully.

stopMovingWindow
()

Stops moving a window that was sent in motion via `startMovingWindow`.

stopTilingOrTabbing
(params, cb)

This function is used by the Finsemble window title bar to end tiling or tabbing.

Name Type Description
params
Name Type Description
allowDropOnSelf boolean optional

Determines whether a tab can be dropped on the window where the drag originated.

mousePosition

Where the pointer is on the screen

Name Type Description
x number

X position of the pointer

y number

Y position of the pointer

cb Function

The callback to be invoked after the method completes successfully.