Module: WindowClient

WindowClient is primarily responsible for managing window state (the window's location and size) and app state (data inside of your app).

Type Aliases

Bounds

Ƭ Bounds: Object

Type declaration

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

Functions

addToTabCollection

▸ addToTabCollection(__namedParameters): Promise<void>

Adds one or more windows to an existing tab collection.

await FSBL.Clients.WindowClient.addToTabCollection({
  tabCollectionId: ["StackedWindow-sdsd-343-dsds"],
  windowNames: ["MyApp-3443-fdf-343-fdfdf", "MyOtherApp-dfdf-sdsd-dfdf-sdsd"],
  position: 2,
  promotedTab: "MyOtherApp-dfdf-sdsd-dfdf-sdsd",
});

Parameters

Name	Type	Description
__namedParameters	Object	-
__namedParameters.position?	number	Specifies where in the collection to add the new tabs. If not set then they will be appended to the end of the collection.
__namedParameters.promotedTab?	string	Tab to be promoted. If not set then the promoted tab will not be changed.
__namedParameters.tabCollectionId	string	ID of the tabCollection to join.
__namedParameters.windowNames	string[]	An array of window names to be added to the collection.

Returns

Promise<void>

---

bringToFront

▸ bringToFront(cb?): StandardPromise<void>

Brings the window to the top of all other windows.

FSBL.Clients.WindowClient.bringToFront();

Parameters

Name	Type
cb?	StandardErrorCallback<void>

Returns

StandardPromise<void>

---

bringWindowToFront

▸ bringWindowToFront(cb?): void

deprecated Use bringToFront() instead, which returns a promise.

Brings the window to the top of all other windows

This is a non-promise version for backward compatibility. Please use WindowClient.bringToFront()

deprecated Use bringToFront() instead, which returns a promise.

Parameters

Name	Type
cb?	StandardErrorCallback<void>

Returns

void

---

cancelTilingOrTabbing

▸ cancelTilingOrTabbing(params, cb?): void

This is used to cancel a tabbing or tiling operation.

deprecated This code will be moved into finsemble-ui

Parameters

Name	Type	Description
params	Object
params.windowIdentifier?	WindowIdentifier	The Finsemble identifier for the window.
cb?	() => void	The callback to be invoked after the method completes successfully.

Returns

void

---

close

▸ close(params?, cb?): StandardPromise<void>

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).

deprecated - Use of parameters has been deprecated, and will be removed in an upcoming version.

//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,
});

Parameters

Name	Type	Description
params?	Object
params.closeWindow	boolean	Whether to close the window. On shutdown this method is called, but the Window Service actually closes the window.
params.removeFromWorkspace	boolean	Whether to remove the window from the workspace.
params.userInitiated?	boolean	Whether the user clicked the X, or if the system asked the window to close.
cb?	StandardErrorCallback<void>	The callback to be invoked after the method completes successfully.

Returns

StandardPromise<void>

---

createTabCollection

▸ createTabCollection(__namedParameters): Promise<void>

Forms a tab collection from a list of existing windows. (See LauncherClient.spawnTabCollection() to form a tab collection from non-existing windows.)

await FSBL.Clients.WindowClient.createTabCollection({
  windowNames: ["MyApp-3443-fdf-343-fdfdf", "MyOtherApp-dfdf-sdsd-dfdf-sdsd"],
  promotedTab: "MyOtherApp-dfdf-sdsd-dfdf-sdsd",
});

Parameters

Name	Type	Description
__namedParameters	Object	-
__namedParameters.promotedTab?	string	The name of the tab to be promoted. If not set then the first window will be promoted.
__namedParameters.windowNames	string[]	An array of window names to put in the collection. The tabs will retain the ordering of this array.

Returns

Promise<void>

---

ejectFromGroup

▸ ejectFromGroup(): void

deprecated Ejects the window from the docking group

Returns

void

---

fitToDOM

▸ fitToDOM(params?, cb?): Promise<void>

Resize the window to fit the contents of the window's DOM, with optional padding.

Parameters

Name	Type
params?	null | { maxHeight?: number ; maxWidth?: number ; padding?: { height: number ; width: number } }
cb?	() => void

Returns

Promise<void>

---

formGroup

▸ formGroup(): void

deprecated Forms a group with any window that is touching the border of this window.

Returns

void

---

getBounds

▸ getBounds(cb): StandardPromise<Bounds>

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.

Parameters

Name	Type	Description
cb	StandardErrorCallback<Bounds>	The callback to be invoked after the method completes successfully.

Returns

StandardPromise<Bounds>

---

getComponentState

▸ getComponentState<T>(params, cb?): StandardPromise<T>

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

Here's how to retrieve data to restore the layout of our charts.

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

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

Type parameters

Name	Type
T	any

Parameters

Name	Type	Description
params	Object
params.field?	string	Field to retrieve.
params.fields?	string[]	Fields to retrieve.
params.windowName?	string	Window whose component state you are retrieving. If null, defaults to the calling window.
cb?	StandardErrorCallback<T>	The callback to be invoked after the method completes successfully.

Returns

StandardPromise<T>

---

getCurrentWindow

▸ getCurrentWindow(): FEAWindow

deprecated Use FSBL.System.Window.getCurrent()

Returns a reference to the current FEAWindow for the component.

Returns

FEAWindow

---

getPromotedTab

▸ getPromotedTab(__namedParameters, cb?): StandardPromise<string>

Gets the name of the promoted tab for a given tab collection.

const { err, data: windowName } =
  await FSBL.Clients.WindowClient.getPromotedTab({
    tabCollectionId: ["StackedWindow-dfdf-sdsd-dfdfdf-343434"],
  });
if (windowName) console.log(`The promoted window is ${windowName}`);

Parameters

Name	Type	Description
__namedParameters	Object	-
__namedParameters.tabCollectionId	string	ID of the tab collection.
cb?	StandardErrorCallback<string>	Optional callback to be invoked after the method completes successfully.

Returns

StandardPromise<string>

• Resolves to a tuple containing an error message and the name of the promoted tab in the collection.

---

getSpawnData

▸ getSpawnData(): any

Retrieves data that was set with LauncherClient.spawn.

Returns

any

The spawnData that was passed to calls to LauncherClient.spawn, or an empty object.

---

getTabCollection

▸ getTabCollection(__namedParameters, cb?): StandardPromise<{ promotedWindowName: string ; windows: string[] }>

Gets names of all the windows that are part of a tab collection.

const { err, data } = await FSBL.Clients.WindowClient.getTabCollection({
  id: "StackedWindow-dfdf-sdsd-dfdfdf-343434",
});
if (data)
  console.log(`The tab collection contains these windows: ${data.windows}`);

Parameters

Name	Type	Description
__namedParameters	Object	-
__namedParameters.id	string	-
cb?	StandardErrorCallback<{ promotedWindowName: string ; windows: string[] }>	Optional callback to be invoked after the method completes.

Returns

StandardPromise<{ promotedWindowName: string ; windows: string[] }>

• Resolves to a tuple with error message and object containing the list of the windows in that collection and the currently promoted window.

---

getTabCollectionForWindow

▸ getTabCollectionForWindow(__namedParameters, cb?): StandardPromise<{ id: string ; windows: string[] }>

Gets the tabCollectionId for a given window, if it is a member of a tab collection.

const { err, data } = await FSBL.Clients.WindowClient.getTabCollectionForWindow(
  {
    windowName: "MyApp-dfdf-sdsd-dfdfdf-343434",
  },
);
if (data)
  console.log(
    `The tab collection ${data.id} contains these windows: ${data.windows}`,
  );

Parameters

Name	Type	Description
__namedParameters	Object	-
__namedParameters.windowName	string	The name of a window that should be in a tab collection.
cb?	StandardErrorCallback<{ id: string ; windows: string[] }>	Optional callback to be invoked after the method completes.

Returns

StandardPromise<{ id: string ; windows: string[] }>

• Resolves to a tuple with error message and object containing the tabCollectionId and a list of the windows in that collection. An error will result if the window is not a member of any tab collection.

---

getWindowIdentifier

▸ getWindowIdentifier(): WindowIdentifier

Returns the window identifier for the current component.

Returns

WindowIdentifier

---

getWindowNameForDocking

▸ getWindowNameForDocking(): string

Gets the window name of current window. 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.

deprecated

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.

Returns

string

---

getWindowTitle

▸ getWindowTitle(windowName?): Promise<null | string>

Retrieves the window's title.

// Get the current window's title
await FSBL.Clients.WindowClient.getWindowTitle();

// Get a different window's title
await FSBL.Clients.WindowClient.getWindowTitle("windowName-foo-bar");

Parameters

Name	Type
windowName?	string

Returns

Promise<null | string>

title

---

maximize

▸ maximize(cb?): StandardPromise<void>

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

FSBL.Clients.WindowClient.maximize();

Parameters

Name	Type	Description
cb?	StandardErrorCallback<void>	Optional callback to be invoked after the method completes successfully.

Returns

StandardPromise<void>

---

minimize

▸ minimize(cb?): StandardPromise<void>

Minimizes window.

FSBL.Clients.WindowClient.minimize();

Parameters

Name	Type	Description
cb?	StandardErrorCallback<void>	Optional callback to be invoked after the method completes successfully.

Returns

StandardPromise<void>

---

promoteTab

▸ promoteTab(windowName): Promise<void>

Changes the visible tab in a tab collection. (The tab collection is identified automatically.)

await FSBL.Clients.WindowClient.promoteTab("MyApp-3443-fdf-343-fdfdf");

Parameters

Name	Type	Description
windowName	string	The name of the tab to be promoted.

Returns

Promise<void>

---

removeComponentState

▸ removeComponentState(params, cb?): StandardPromise<void>

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

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" }],
});

Parameters

Name	Type	Description
params	Object	Object of data to be removed
params.field?	string	The key name of the field to be saved. Required if not using fields.
params.fields?	{ field: string }[]	An array of objects with field keys to be removed.
params.windowName?	string	The name of the window to remove component state from
cb?	StandardErrorCallback<void>	The callback to be invoked after the method completes successfully.

Returns

StandardPromise<void>

---

removeFromTabCollection

▸ removeFromTabCollection(__namedParameters): Promise<void>

Removes one or more tabs from their tab collection(s). The tab collection is identified automatically. Tab collections with fewer than two tabs are removed from the system. If the tab collection is maximized then windows that are removed will be restored to their previous unmaximized position and size.

await FSBL.Clients.WindowClient.removeFromTabCollection({
  windowNames: ["MyApp-3443-fdf-343-fdfdf", "MyOtherApp-dfdf-sdsd-dfdf-sdsd"],
});

Parameters

Name	Type	Description
__namedParameters	Object	-
__namedParameters.visibility?	boolean	An optional parameter to indicate whether the removed windows should be made visible after they are removed.
__namedParameters.windowNames	string[]	The array of window names to be removed.

Returns

Promise<void>

---

restore

▸ restore(cb?): StandardPromise<void>

Restores window from a maximized or minimized state.

FSBL.Clients.WindowClient.restore();

Parameters

Name	Type	Description
cb?	StandardErrorCallback<void>	Optional callback to be invoked after the method completes successfully.

Returns

StandardPromise<void>

---

setAlwaysOnTop

▸ setAlwaysOnTop(alwaysOnTop, cb?): StandardPromise<void>

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

FSBL.Clients.WindowClient.setAlwaysOnTop(true);

Parameters

Name	Type	Description
alwaysOnTop	boolean	The new mode for the window's alwaysOnTop option to be set to.
cb?	StandardErrorCallback<void>	Optional callback to be invoked after the method completes successfully.

Returns

StandardPromise<void>

---

setComponentState

▸ setComponentState<T>(params, cb?): StandardPromise<void>

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

Here is how to save the chart layout when it changes.

let 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" },
  ],
});

Type parameters

Name	Type
T	any

Parameters

Name	Type	Description
params	Object	Object of data to be saved
params.field?	string	The key name of the field to be saved. Required if not using fields.
params.fields?	{ field: string ; value: T }[]	An array of objects with field and value keys to be saved.
params.value?	T	Value of the data being saved. Required if not using fields.
params.windowName?	string	Name of the component whose state you are setting. Defaults to the calling window.
cb?	StandardErrorCallback<void>	The callback to be invoked after the method completes successfully.

Returns

StandardPromise<void>

---

setShape

▸ setShape(params?, callback?): void

deprecated Defines areas of the window that will be displayed and clickable. All other areas of the window will be transparent. Can be used to create click-through areas of a window.

Parameters

Name	Type	Default value	Description
params?	(null | { height: Number ; width: Number ; x: Number ; y: Number })[]	undefined	Optional. Takes an array of rectangle Objects for the areas of the window that will be displayed and clickable. Passing in an empty array or omitting this parameter will cause the full area of the window to be displayed and clickable. A rectangle is defined as: { x: x coordinate for the origin of the rectangle (integer) y: x coordinate for the origin of the rectangle (integer) width: width of the rectangle (integer) height: height of the rectangle (integer) }
callback	Function	Function.prototype	-

Returns

void

---

setTaskbarIconOverlay

▸ setTaskbarIconOverlay(url): void

Important

This feature is experimental. The signature may change in the future.

Sets an overlay image on the MS Windows taskbar, for instance to indicate activity. (This is sometimes referred to as a "badge").

The url must point to a 16x16 png image. Images of other sizes or types will not display.

note

MacOS does not support taskbar overlay images. This function is safe to call on MacOS but will not perform any function.

Parameters

Name	Type	Description
url	null | string	The url of the icon to use. Pass null to remove the overlay icon.

Returns

void

---

showAtMousePosition

▸ showAtMousePosition(): void

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

Returns

void

---

startMovingWindow

▸ startMovingWindow(event): void

deprecated 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.

Parameters

Name	Type
event	MouseEvent

Returns

void

---

startTilingOrTabbing

▸ startTilingOrTabbing(params, cb?): void

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

deprecated This code will be moved into finsemble-ui

Parameters

Name	Type	Description
params	Object	params.windowIdentifier is required.
params.windowIdentifier	WindowIdentifier	The Finsemble identifier for the target window.
cb?	() => void	The callback to be invoked after the method completes successfully.

Returns

void

---

stopMovingWindow

▸ stopMovingWindow(): void

deprecated Stops moving a window that was set in motion via startMovingWindow.

Returns

void

---

stopTilingOrTabbing

▸ stopTilingOrTabbing(params, cb?): void

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

deprecated This code will be moved into finsemble-ui

Parameters

Name	Type	Description
params	Object
params.action?	string	-
params.allowDropOnSelf?	boolean	Determines whether a tab can be dropped on the window where the drag originated.
params.mousePosition?	Object	Where the pointer is on the screen
params.mousePosition.x	number	-
params.mousePosition.y	number	-
cb?	() => void	The callback to be invoked after the method completes successfully.

Returns

void