Class: WorkspaceClient
Workspace Client (Finsemble Workspaces)
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.
Methods
-
addEventListener(event, handler)
-
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.
Name Type Description event
load-requested | load-complete | load-failed | load-interrupted | close-requested | close-complete | close-canceled | close-failed | save-requested | save-complete | save-failed handler
FinsembleEventHandler Example
// 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); })
-
autoArrange(params, cb)
-
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.
Name Type Description params
Parameters
Name Type Description monitor
string optional Same options as LauncherClient.showWindow. Default is monitor of calling window.
monitorDimensions
any optional The surface area of the monitor to arrange over. If not defined defaults to the available area of the current monitor.
cb
Function The callback to be invoked after the method completes successfully.
Example
FSBL.Clients.WorkspaceClient.autoArrange(function(err, response) { //do something after the auto-arrange, maybe make all of the windows flash or notify the user that their monitor is now tidy. });
-
bringWindowsToFront(params, cb)
-
Brings all windows to the front.
Name Type Description params
optional Name Type Description monitor
string Same options as LauncherClient.showWindow except that "all" will work for all monitors. Defaults to the monitor for the current window.
windowIdentifier
any optional The Finsemble identifier for the target window. If not provided, defaults to the current window.
cb
Function The callback to be invoked after the method completes successfully.
Example
FSBL.Clients.WorkspaceClient.bringWindowsToFront();
-
createWorkspace(workspaceName, params, cb)
-
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.)
Name Type Description workspaceName
any 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
Optional params
Name Type Description switchAfterCreation
boolean optional Whether to switch to the new workspace after creating it. Defaults to true.
cb
(Anonymous function) cb(err,response)
With response, set to new workspace object if no error.Example
FSBL.Clients.WorkspaceClient.createWorkspace(function(err, response) { if (!err) {} //Do something like notify the user that the workspace has been created. } });
-
export(params, cb)
-
Gets a workspace definition in JSON form.
Name Type Description params
Name Type Description workspaceName
string The name of the workspace you want to export.
cb
any callback(error, workspaceDefinition)
Example
FSBL.Clients.WorkspaceClient.export({'workspaceName:': 'linker'}, function(err, workspaceDefinition) { //do something with the workspace definition })'; -
getActiveWorkspace(cb)
-
Gets the currently active workspace.
Name Type Description cb
StandardCallback The callback to be invoked if the method fails.
Example
FSBL.Clients.WorkspaceClient.getActiveWorkspace((err, response) => { // do something with the response. });
-
getWorkspaceActions(cb)
-
Gets workspace actions defined as constants. Allows users to filter updates
Name Type Description cb
any optional The callback to be invoked after the method completes successfully.
-
getWorkspaces(cb)
-
Returns the list of saved workspaces.
Name Type Description cb
any optional The callback to be invoked after the method completes successfully.
Example
FSBL.Clients.WorkspaceClient.getActiveWorkspace((err, response) => { //setState is a React component method. self.setState({ workspaces: response }); });
-
import(params, cb)
-
Adds a workspace definition to the list of available workspaces.
Name Type Description params
Name Type Description force
boolean Whether to overwrite any workspace of the same name that already exists
workspaceJSONDefinition
Record The JSON for the workspace definition, as exported by the User Preferences menu in Finsemble Connect.
cb
any optional cb(err)
where the operation was successful if !err; otherwise, err carries diagnostics -
isWorkspaceDirty(cb)
-
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.
Name Type Description cb
Function cb(err,response)
with response set to true if dirty and false otherwise (when no error).Example
FSBL.Clients.WorkspaceClient.isWorkspaceDirty(function(err, response) { //Do something like prompt the user if they'd like to save the currently loaded workspace before switching. });
-
minimizeAll(params, cb)
-
Minimizes all windows.
Name Type Description params
optional Name Type Description monitor
string Same options as LauncherClient.showWindow except that "all" will work for all monitors. Defaults to all.
windowIdentifier
any optional The Finsemble identifier structure for the window triggering the request.
cb
Function The callback to be invoked after the method completes successfully.
Example
FSBL.Clients.WorkspaceClient.bringWindowsToFront();
-
remove(params, cb)
-
Removes a workspace. Either the workspace object or its name must be provided.
Name Type Description params
Name Type Description name
string optional The workspace name removal is requested for.
workspace
The workspace data object.
Name Type Description name
string The workspace name removal is requested for.
cb
Function Callback to fire after 'Finsemble.WorkspaceService.update' is transmitted.
Example
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. });
-
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
-
rename(params, cb)
-
Renames the workspace with the provided name. Also removes all references in storage to the old workspace's name.
Name Type Description params
Name Type Description newName
string What to rename the workspace to.
oldName
string Name of workspace to rename.
overwriteExisting
boolean optional Whether to overwrite an existing workspace.
removeOldWorkspace
boolean optional Whether to remove references to old workspace after renaming.
cb
Function The callback to be invoked after the method completes successfully.
Example
FSBL.Clients.WorkspaceClient.rename({ oldName: 'My Workspace', newName: 'The best workspace', removeOldWorkspace: true, }, function(err, response) { //Do something. });
-
save(cb)
-
Saves the currently saved workspace. Changes to the
activeWorkspace
are made on every change automatically.Name Type Description cb
Function The callback to be invoked after the method completes successfully.
Example
FSBL.Clients.WorkspaceClient.save(function(err, response) { //Do something. });
-
saveAs(params, cb)
-
Saves the currently active workspace with the provided name.
Name Type Description params
Name Type Description force
boolean Whether to overwrite a workspace already saved with the provided name.
name
string optional The new name you want to save the workspace under.
cb
Function The callback to be invoked after the method completes successfully.
Example
FSBL.Clients.WorkspaceClient.saveAs({ name: 'My Workspace', }, function(err, response) { //Do something. });
-
switchTo(params, cb)
-
Switches to a workspace.
Name Type Description params
Name Type Description name
string The name of the workspace you want to switch to.
cb
Function The callback to be invoked after the method completes successfully.
Example
FSBL.Clients.WorkspaceClient.switchTo({ name: 'My Workspace', }, function(err, response) { //Do something. });