Module: WorkspaceClient
The Workspace Client manages all calls to load, save, rename, and delete workspaces.
The Workspace Client uses the windowIdentifier parameter. Learn more about them here.
See the Workspace tutorial for an overview of using the Workspace Client.
Type Aliases
FinsembleEventHandler
Ƭ FinsembleEventHandler: (event: FinsembleEvent) => void
Type declaration
▸ (event): void
Parameters
| Name | Type |
|---|---|
event | FinsembleEvent |
Returns
void
Functions
addEventListener
▸ addEventListener(event, handler): void
This provides the ability to listen to workspace events. The load-requested event provides a way to merge data into the workspace prior to loading. The close-requested and save-requested event, allow you to perform actions prior to the actual save and close. The rest of the events are informational only. To tell the workspace service to wait, you must call event.wait() in less than one second. To cancel event.cancel() must be called within 10 seconds, otherwise done is assumed. To send data event.done(data) must also be called within 10 seconds, otherwise done with no data is assumed.
// Sync examples:
FSBL.Clients.WorkspaceClient.addEventListener("close-requested", (event) => { doSomething(); })
FSBL.Clients.WorkspaceClient.addEventListener("load-requested", (event) => { const data = doSomething(); event.done(data); })
// Async examples:
FSBL.Clients.WorkspaceClient.addEventListener("close-requested", async (event) => { event.wait(); await doSomething(); event.done(); })
FSBL.Clients.WorkspaceClient.addEventListener("load-requested", async (event) => { event.wait(); const data = await doSomething(); event.done(data); })
Parameters
| Name | Type | Description |
|---|---|---|
event | WorkspaceEventName | The workspace event to listen for |
handler | FinsembleEventHandler | A function to handle the event |
Returns
void
autoArrange
▸ autoArrange(params, cb?): StandardPromise<void>
This method is an experimental feature in Finsemble Labs. Calling this method automatically arranges all windows on the user's screen into a grid-like pattern.
Parameters
| Name | Type | Description |
|---|---|---|
params | any | Parameters Unused |
cb? | StandardErrorCallback<void> | The callback to be invoked after the method completes successfully. |
Returns
StandardPromise<void>
bringWindowsToFront
▸ bringWindowsToFront(params?, cb?): StandardPromise<void>
Brings all windows to the front.
FSBL.Clients.WorkspaceClient.bringWindowsToFront();
FSBL.Clients.WorkspaceClient.bringWindowsToFront({monitor: "all"}, function(err){
// do something
});
Parameters
| Name | Type | Description |
|---|---|---|
params? | Object | |
params.monitor | string | Same options as LauncherClient.showWindow except that "all" will work for all monitors. Defaults to the monitor for the current window. |
params.windowIdentifier? | any | The Finsemble identifier for the target window. If not provided, defaults to the current window. |
cb? | StandardErrorCallback<void> | The callback to be invoked after the method completes successfully. |
Returns
StandardPromise<void>
createWorkspace
▸ createWorkspace(workspaceName, params?, cb?): Promise<{ workspaceName: string }>
Creates a new workspace, returning a promise for the final name of the new workspace as a string. After creation, if "switchAfterCreation" is true, the new workspace becomes the active workspace.
If the requested name already exists, a new workspace will be created with the form "[name] (1)" (or "[name] (2)", etc.)
This example creates the workspace 'My Workspace'.
FSBL.Clients.WorkspaceClient.createWorkspace("My workspace", {switchAfterCreation:true}),function(err, response) {
if (!err) {}
//Do something, such as notify the user that the workspace has been created.
}
});
Parameters
| Name | Type | Description |
|---|---|---|
workspaceName | string | Name for new workspace. If the workspaceName is empty, the workspace is given the name "Untitled." Subsequent creations with empty strings would result in "Untitled1", "Untitled2", etc. |
params? | Object | Optional params |
params.switchAfterCreation? | boolean | Whether to switch to the new workspace after creating it. Defaults to true. |
cb | (err: any, result: { workspaceName: string }) => void | cb(err,response) With response, set to new workspace object if no error. |
Returns
Promise<{ workspaceName: string }>
exportWorkspace
▸ exportWorkspace(params, cb): Promise<unknown>
Gets a workspace definition in JSON form.
FSBL.Clients.WorkspaceClient.export({'workspaceName': 'linker'}, function(err, workspaceDefinition) {
//do something with the workspace definition
});
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | |
params.workspaceName | string | The name of the workspace you want to export. |
cb | Function | callback(error, workspaceDefinition) |
Returns
Promise<unknown>
getActiveWorkspace
▸ getActiveWorkspace(cb?): Promise<{ data: Workspace }>
Gets the currently active workspace. This function is useful for setting the initial state of a menu or dialog. It is used in the toolbar component to set the initial state.
FSBL.Clients.WorkspaceClient.getActiveWorkspace((err, response) => {
// do something with the response.
});
Parameters
| Name | Type | Description |
|---|---|---|
cb? | StandardErrorCallback<{ data: Workspace }> | The callback to be invoked after the method completes successfully. |
Returns
Promise<{ data: Workspace }>
getControllerInstance
▸ getControllerInstance(): WorkspaceClientController
Returns
WorkspaceClientController
getWorkspaceActions
▸ getWorkspaceActions(cb?): Record<string, string>
Gets workspace actions defined as constants. Allows users to filter updates
Parameters
| Name | Type | Description |
|---|---|---|
cb? | StandardErrorCallback<Record<string, string>> | The callback to be invoked after the method completes successfully. |
Returns
Record<string, string>
getWorkspaceNames
▸ getWorkspaceNames(cb?): Promise<unknown>
Returns a list of workspace names. This function returns the list of all the workspace.
FSBL.Clients.WorkspaceClient.getWorkspaceNames((err, response) => {
console.log(JSON.stringify(response, null, 2));
});
Output:
[
"Default Workspace",
"Another workspace"
]
Parameters
| Name | Type | Description |
|---|---|---|
cb? | StandardErrorCallback<string[]> | The callback to be invoked after the method completes successfully. |
Returns
Promise<unknown>
getWorkspaces
▸ getWorkspaces(cb?): Promise<unknown>
Returns the list of saved workspaces. This function is useful for setting the initial state of a menu or dialog.
FSBL.Clients.WorkspaceClient.getWorkspaces((err, response) => {
//do something with the array of workspace objects
console.log(response)
});
Parameters
| Name | Type | Description |
|---|---|---|
cb? | Function | The callback to be invoked after the method completes successfully. |
Returns
Promise<unknown>
importWorkspace
▸ importWorkspace(params, cb?): Promise<Record<string, string>>
Adds a workspace definition to the list of available workspaces.
FSBL.Clients.WorkspaceClient.import({force: false, workspaceJSONDefinition: workspaceDefinition}, function(err) {
if (!err) console.log("import success.");
});
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | |
params.force | boolean | Whether to overwrite any workspace of the same name that already exists |
params.workspaceJSONDefinition | Record<string, string | Workspace> | The JSON for the workspace definition, as exported by the User Preferences menu in Finsemble Connect. |
cb? | Function | cb(err) where the operation was successful if !err; otherwise, err carries diagnostics |
Returns
Promise<Record<string, string>>
isWorkspaceDirty
▸ isWorkspaceDirty(cb?): Promise<boolean>
Checks to see if the workspace is dirty, i.e., if its state has been changed since the last save. If it's already dirty, the window doesn't need to compare its state to the saved state.
This example will let you know if the active workspace is dirty.
FSBL.Clients.WorkspaceClient.isWorkspaceDirty(function(err, response) {
if (response.data === true) {
//Do something like prompt the user if they'd like to save the currently loaded workspace before switching.
} else {
//Workspace is clean
}
});
Parameters
| Name | Type | Description |
|---|---|---|
cb? | Function | cb(err,response) with response set to true if dirty and false otherwise (when no error). |
Returns
Promise<boolean>
minimizeAll
▸ minimizeAll(params?, cb?): StandardPromise<void>
Minimizes all windows.
FSBL.Clients.WorkspaceClient.minimizeAll();
FSBL.Clients.WorkspaceClient.minimizeAll({monitor: "all"}, function(err){
// do something
});
Parameters
| Name | Type | Description |
|---|---|---|
params? | Object | |
params.monitor | string | Same options as LauncherClient.showWindow except that "all" will work for all monitors. Defaults to all. |
params.windowIdentifier? | any | The Finsemble identifier structure for the window triggering the request. |
cb? | StandardErrorCallback<void> | The callback to be invoked after the method completes successfully. |
Returns
StandardPromise<void>
remove
▸ remove(params, cb?): Promise<unknown>
Removes a workspace. Either the workspace object or its name must be provided.
The following examples both remove 'My Workspace' from the main menu and the default storage tied to the application.
FSBL.Clients.WorkspaceClient.remove({
name: 'My Workspace'
}, function(err, response) {
//You typically won't do anything here. If you'd like to do something when a workspace change happens, we suggest listening on the `Finsemble.WorkspaceService.update` channel.
});
FSBL.Clients.WorkspaceClient.remove({
workspace: {
version: "1.0.0",
name: 'My Workspace',
type: "workspace",
...
}
});
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | Parameters object specifying the workspace name to remove, either directly as name or by passing in the workspace from which the name will be extracted. |
params.name? | string | The workspace name removal is requested for. |
params.workspace? | Object | A workspace data object. |
params.workspace.name | string | - |
cb? | Function | Callback to fire after 'Finsemble.WorkspaceService.update' is transmitted. |
Returns
Promise<unknown>
removeEventListener
▸ removeEventListener(event, handler): void
Removes an event listener.
Parameters
| Name | Type | Description |
|---|---|---|
event | WorkspaceEventName | The workspace event that is listened on |
handler | FinsembleEventHandler | The handler that is in effect |
Returns
void
rename
▸ rename(params, cb?): Promise<unknown>
Renames the workspace with the provided name. Also removes all references in storage to the old workspace's name. This method is used to rename workspaces. It is used in the main Menu component. Note: If you attempt to rename a Workspace to a name that already exists a ({next number}) will be added to the newName.
FSBL.Clients.WorkspaceClient.rename({
oldName: 'My Workspace',
newName: 'The best workspace',
removeOldWorkspace: true,
}, function(err, response) {
//Do something.
});
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | |
params.newName | string | What to rename the workspace to. |
params.oldName | string | Name of workspace to rename. |
params.overwriteExisting? | boolean | Whether to overwrite an existing workspace. |
params.removeOldWorkspace? | boolean | Whether to remove references to old workspace after renaming. |
cb? | Function | The callback to be invoked after the method completes successfully. |
Returns
Promise<unknown>
save
▸ save(cb?): Promise<unknown>
Saves the current active workspace.
This example persists the currently active workspace.
FSBL.Clients.WorkspaceClient.save(function(err) {
//Do something.
});
Parameters
| Name | Type | Description |
|---|---|---|
cb? | Function | The callback to be invoked after the method completes successfully. |
Returns
Promise<unknown>
saveAs
▸ saveAs(params, cb?): Promise<unknown>
Saves the currently active workspace with the provided name.
This example persists the currently active workspace with the provided name.
FSBL.Clients.WorkspaceClient.saveAs({
name: 'My Workspace',
}, function(err, response) {
//Do something.
});
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | |
params.force? | boolean | Whether to overwrite a workspace already saved with the provided name. |
params.name | string | The new name you want to save the workspace under. |
cb? | Function | The callback to be invoked after the method completes successfully. |
Returns
Promise<unknown>
switchTo
▸ switchTo(params, cb?): Promise<{ data: Workspace }>
Switches to a workspace.
This example loads the workspace 'My Workspace' from the storage tied to the application.
FSBL.Clients.WorkspaceClient.switchTo({
name: 'My Workspace',
}, function(err, response) {
//Do something.
});
Parameters
| Name | Type | Description |
|---|---|---|
params | Object | |
params.name | string | The name of the workspace you want to switch to. |
cb? | StandardErrorCallback<{ data: Workspace }> | The callback to be invoked after the method completes successfully. |
Returns
Promise<{ data: Workspace }>