WarningLegacy version 5 documentation. View current documentation.

Hotkeys

The users of your Finsemble application will want hotkeys for convenience and expedience. The Hotkey Client provides a convenient way to create local and global hotkeys.

Global hotkeys

Global hotkeys are where the true power of the Hotkey Client lies. Global hotkeys can activate components even when that component is not in focus.

To add a global hotkey:

const HotkeyClient = Finsemble.Clients.HotkeyClient;
HotkeyClient.addGlobalHotkey(keys, onHotkeyTriggered, onHotkeyRegistered);

Removing a hotkey mirrors the add functionality. To remove the global hotkey:

HotkeyClient.removeGlobalHotkey(keys, onHotkeyTriggered, onHotkeyUnRegistered);

Please note that global hotkeys are best kept in desktop services.

Local hotkeys

If your application already has hotkeys, you don't necessarily have to change from this method to our API. If you do, however, there are a couple of advantages:

  1. API consistency with global hotkeys.
  2. The ability to detect which side of the keyboard that the key was pressed (e.g., left or right shift).

If those advantages aren't necessary for your application, you can leave them as they are. If you do want to use our API for local hotkeys, an example follows:

const keyMap = FSBL.Clients.HotkeyClient.keyMap,
	keys = [keyMap.ctrl, keyMap.shift, keyMap.up];

// If CTRL+SHIFT+UP is pressed inside of this component, all windows will be brought to the front of the stack.
function onHotkeyTriggered(err, response) {
	if (err) {
		return console.error(err);
	}
	FSBL.Clients.LauncherClient.bringWindowsToFront();
}
// If there's a problem registering, it will come through this function (e.g., you pass in a bad key).
function onHotkeyRegistered(err, response) {
	if (err) {
		return console.error(err);
	}
}

function onHotkeyUnregistered(err) {
	if (err) {
		return console.error(err);
	}
	console.log("Success!");
}

HotkeyClient.addLocalHotkey(keys, onHotkeyTriggered, onHotkeyRegistered);

Removing a local hotkey is similar:

HotkeyClient.removeLocalHotkey(keys, onHotkeyTriggered, onHotkeyUnRegistered);

The key map

There are many ways to render the names of key strokes. For example, "esc," "escape," "ESC," and "ESCAPE" are all valid ways to describe the key in the top-left of most keyboards.

To reduce conflicts and ensure consistency across calls, we've provided a key map for you to use. Invoke by key map by using: FSBL.Clients.HotkeyClient.keyMap.[keystroke]

This call maps common keystroke spellings to strings. For example, by beginning to enter "Del," the key map will fill in "delete", which is the appropriate spelling for the Hotkey Client.


Disabling hotkeys

Hotkeys are made possible through AssimilationMain.exe, the program that enables Finsemble's native integration capabilities. To modify its behavior, you must create an INI file to modify this asset.

Here's a sample config for the INI file. DoCapture=falsedisables hotkeys.

[Settings];
Port = 8392;
DoCapture = false[Logger];
Folder = logs;
WriteAsync = true;
LogErrors = true;
LogWarnings = true;
LogInfo = false;
LogDebug = false;
LogToFile = true;
LogToDebugger = false;
FilesNumber = 1;
FileSize = 2621440;

Spawning components with hotkeys

It is possible to set a hotkey chord to spawn a component by way of configuration. This is set through finsemble.components.[componentName].component.spawnOnHotKey. Finsemble's configuration is read at startup, which then dynamically sets the appropriate hotkey chord.

The Central Logger has its own config to handle this. The hotkey for showing the Central Logger is configurable through finsemble.servicesConfig.logger.hotkeyShowCentralLogger. By default, the hotkey is set to CTRL+SHIFT+L.

See the Config Reference for more details.


Best Practices

Use named functions for event handlers

We recommend using named functions for your handlers. If, when you created the hotkey, you passed in an anonymous function, you will be unable to remove that handler (e.g., when the component is closed). This is common to all event handlers, but we wanted to make it clear that we recommend using named event handlers so that they can be removed.

Specify global hotkeys in desktop services

Global hotkeys are best stored inside of desktop services. Desktop services are singletons, so you don't need to worry that a key combination will be registered multiple times. Also, because they are singletons, they are loaded before components and are intended to serve multiple components.

If you put the hotkeys in a component, you'll need to handle cases where multiple copies of the component are spawned and the hotkeys are registered in multiple instances. For example, let's say we wanted to add a global hot key to the Finsemble toolbar. The problem with this scenario is that there can be more than one toolbar. So we need to make sure that only one of the toolbars registered can launch components via the hotkey—otherwise the hot key would launch N toolbars. That's definitely not the expected behavior!

For that reason, we recommend that you exercise caution putting global hotkeys inside of components that could be launched more than once. For safety's sake, keep them in your desktop services.


check   Add global hotkeys to desktop services and users can utilize them regardless of which window is in focus.
 

Further reading

The documentation of the Hotkey Client provides additional information.