Hotkeys

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

Finsemble supports a number of hotkeys, and you can also add your own.

Existing hotkeys

Here is the list of existing hotkeys that Finsemble suports.

Global hotkeys

Launch windows:
- Advanced chart: CTRL+ALT+A
- Notepad: CTRL+ALT+N
- Central Logger: CTRL+SHIFT+L
Window control:
- Minimize all: CTRL+ALT+DOWN ARROW
- Bring to front: CTRL+ALT+UP ARROW
Toolbar:
- Search: CTRL+ALT+F
- Call floating toolbar: CTRL+ALT+T
- Hide floating toolbar: CTRL+ALT+H
Special:
- Restart Finsemble: Ctrl + Alt + Shift + R

App hotkeys

Central Logger:
- Toggle the visibility of the client list: Ctrl+Alt+C
- Configure Logger for defaults: Ctrl+Alt+D
- Configure Logger for errors: Ctrl+Alt+E
- Configure Logger for field capture: Ctrl+Alt+S
- Clear log data: Ctrl+Alt+X
- Set top: Ctrl+Arrow Up
- Set bottom: Ctrl+Arrow Down
- Scroll to active row: Ctrl+Arrow Left or Ctrl+Arrow Right
- Show search box: Ctrl+F
Zoom-enabled windows (Welcome component):
- Zoom in: Ctrl+= or Ctrl++
- Zoom out: Ctrl+-
- Reset zoom: Ctrl+0

Global hotkeys

Global hotkeys are where the true power of the Hotkey client lies. Global hotkeys can activate a component 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 works in a similar way. To remove the global hotkey:

HotkeyClient.removeGlobalHotkey(keys, onHotkeyTriggered, onHotkeyUnRegistered);

Note: global hotkeys are best kept in desktop services.

Local hotkeys

If your app already has hotkeys, you don't have to switch to our API, but changing offers these advantages:

API consistency with global hotkeys.
Ability to detect which side of the keyboard that the key was pressed (left or right shift).

If you don't need these advantages for your app, you can leave your hotkeys as they are. If you do want to use our API for local hotkeys, here's an example:

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

// If a user presses CTRL+SHIFT+UP inside this component, all windows are 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);

You can remove a local hotkey like this:

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 won't be able to remove that handler (for example, 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 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, think carefully before you put global hotkeys inside of components that could be launched more than once. For safety's sake, keep them in your desktop services.