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 microservices.


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. However, in order to reduce conflicts and ensure consistency across calls, we've provided a key map for you to use. The key map can be found in the seed project at finsemble/dist/common/keyMaps.json. For instance, instead of ["ctrl", "left shift", "a"], we recommend you use [keyMap.ctrl, keyMap.shift, keyMap.a].

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 microservices

Global hotkeys are best stored inside of microservices. Microservices 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 hot key—otherwise the hot key would launch N charts. 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 microservices.


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


Further reading

The documentation of the Hotkey Client provides additional information.