Class: WorkspaceClient

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 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	StandardErrorCallback	optional The callback to be invoked after the method completes successfully.

Example

FSBL.Clients.WorkspaceClient.autoArrange();
FSBL.Clients.WorkspaceClient.autoArrange({}, function(err) {
		//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	undefined | Type Literal	optional Name Type Description N/A Type Literal 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 The Finsemble identifier for the target window. If not provided, defaults to the current window.
cb	StandardErrorCallback	optional The callback to be invoked after the method completes successfully.

Example

FSBL.Clients.WorkspaceClient.bringWindowsToFront();
FSBL.Clients.WorkspaceClient.bringWindowsToFront({monitor: "all"}, function(err){
	// do something
});

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	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		Optional params Name Type Description switchAfterCreation 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

This function 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.
		}
});

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	StandardErrorCallback	optional The callback to be invoked after the method completes successfully.

Example

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

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.

getWorkspaceNames

(cb)

Returns a list of workspace names

Name	Type	Description
cb	any	optional The callback to be invoked after the method completes successfully.

Example

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

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

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

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

Example

FSBL.Clients.WorkspaceClient.import({force: false, workspaceJSONDefinition: workspaceDefinition}, function(err) {
		if (!err) console.log("import success.");
});

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

This function will let you know if the activeWorkspace 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
   }
});

minimizeAll

(params, cb)

Minimizes all windows.

Name	Type	Description
params	undefined | Type Literal	optional Name Type Description N/A Type Literal Name Type Description monitor string Same options as LauncherClient.showWindow except that "all" will work for all monitors. Defaults to all. windowIdentifier any The Finsemble identifier structure for the window triggering the request.
cb	StandardErrorCallback	optional The callback to be invoked after the method completes successfully.

Example

FSBL.Clients.WorkspaceClient.minimizeAll();
FSBL.Clients.WorkspaceClient.minimizeAll({monitor: "all"}, function(err){
	// do something
});

remove

(params, cb)

Removes a workspace. Either the workspace object or its name must be provided.

Name	Type	Description
params		Name Type Description name optional The workspace name removal is requested for. workspace optional The workspace data object.
cb	Function	Callback to fire after 'Finsemble.WorkspaceService.update' is transmitted.

Example

This function removes '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.
});

removeEventListener

(event, handler)

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

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 optional Whether to overwrite an existing workspace. removeOldWorkspace optional Whether to remove references to old workspace after renaming.
cb	Function	The callback to be invoked after the method completes successfully.

Example

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

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

This function persists the currently active workspace.

FSBL.Clients.WorkspaceClient.save(function(err) {
	//Do something.
});

saveAs

(params, cb)

Saves the currently active workspace with the provided name.

Name	Type	Description
params		Name Type Description force optional name optional The new name you want to save the workspace under.
cb	Function	The callback to be invoked after the method completes successfully.

Example

This function persists the currently active workspace with the provided name.

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	StandardErrorCallback	optional The callback to be invoked after the method completes successfully.

Example

This function loads the workspace 'My Workspace' from the storage tied to the application.

FSBL.Clients.WorkspaceClient.switchTo({
	name: 'My Workspace',
}, function(err, response) {
	//Do something.
});