Customizing keyboard shortcuts

Keyboard shortcuts are easily customized. Provide a keyMap config object with the keyboard key or combination as the property name, and the action (function name) as value. Key combinations are case-insensitive.

const taskBoard = new TaskBoard({
    keyMap: {
        // Changing keyboard navigation to respond to WASD keys.
        w : 'navigateUp',
        a : 'navigateLeft',
        s : 'navigateDown',
        d : 'navigateRight',
        
        // Removes mappings for arrow keys.
        ArrowUp    : null,
        ArrowLeft  : null,
        ArrowDown  : null,
        ArrowRight : null
    }
});

Modifier keys (Ctrl, Alt, Shift, and Meta) are also supported.

Note: For Mac users, the Command (⌘) key is equivalent to the Ctrl key on other platforms, however, this modifier key is presented as metaKey by the browser. For this reason, metaKey and ctrlKey are swapped to Ctrl andMeta modifier names (respectively) on the Mac platform.

Further, the Alt key is known as the Option (⌥) key on the Mac keyboard.

See the docs for details on keyboard events.

const taskBoard = new TaskBoard({
    keyMap: {
        'Shift+w' : 'selectUp',
        'Shift+a' : 'selectLeft',
        'Shift+s' : 'selectDown',
        'Shift+d' : 'selectRight'
    }
});

Features

TaskBoard features provides their own keyboard shortcuts. These will be applied to the TaskBoard's keyMap with the feature name prefixed to their action. A feature keyboard shortcut can easily be customized by the TaskBoard's keyMap:

const taskBoard = new TaskBoard({
    // Customize feature's keyMap in TaskBoard's keyMap
    keyMap: {
        'Ctrl+ArrowDown' : 'simpleTaskEdit.editNext',
        'Enter'          : 'sikmpleTaskEdit.complete'
    }
});

Multi-action combinations

A keyboard combination can sometimes be used for multiple actions across different components and different features. For most of these cases only one of the action handlers will recognize the action as something it will apply its logic to. However, some actions do collide. And for that there is a prioritization configuration property named weight built-in to the keyMap functionality.

const taskBoard = new TaskBoard({
    // Example of a configuration with a weight
    keyMap: {
        'Space': { handler: 'myCustomAction', weight: 100 }
    }
});

Please note that customizing these keyboard shortcuts can have side effects not intended and not always easily recognizable. A quick way to get the complete list of active keyboard shortcuts is when the TaskBoard has finished its configuration process, log out the value of the property keyMap of the TaskBoard instance object.

If you know what you are doing, the weight configuration can be a tool to configure more actions for the same keyboard combination. The colliding actions will be put in an array sorted by the largest weight last. The actions will then be called from beginning to end, until one not returns false. Not providing a weight puts the action on the top of the queue.

const taskBoard = new TaskBoard({
    // In this example we configure a custom action on Space to be prioritized before
    // the TaskMenu features existing Space action
    keyMap : {
        // Instead of using a string action, use an object with a handler and a
        // weight property.
        ' ' : { handler : 'myCustomAction', weight : 100 }
    },
    feature: {
        taskMenu: { // TaskMenu feature
            keyMap : {
                // This will affect the TaskMenu feature's Space keyboard shortcut
                // to be called after 'myCustomAction'
                ' ' : { handler: 'showContextMenuByKey', weight: 1000},

                // Removing a weighted keyboard combination action is almost always
                // safe to do.
                ArrowUp    : null,
                ArrowLeft  : null,
                ArrowDown  : null,
                ArrowRight : null
            }
        }
    }
});

Adding new keyboard combination actions

If you want to run a function by a keyboard combination it is very easy to set up using the keyMap configuration. Either add a new function to your TaskBoard class, use an existing function from the API or just provide a function or a function handle in the configuration.

const taskBoard = new TaskBoard({
    keyMap : {
        // This is a function from the existing TaskBoard API
        'Ctrl+S'       : 'saveState',

        // This is a function provided directly in the configuration object
        'Ctrl+O'       : () => location.href = './logout'
    }
});

class MyTaskBoard extends TaskBoard {
    static configurable = {
        keyMap: {
            // This function must be available on the TaskBoard subclass
            'Ctrl+Shift+M' : 'sendReminderEmail',
        }
    };
    
    sendReminderEmail(){
        myApi.post('./sendmail');
    }
}

If the current keyboard shortcut has multiple actions, and you want actions after your action to be called, the function should return false. This will make the keyMap functionality continue calling the other actions until one not returns false.

class myTaskBoard extends TaskBoard {
    static configurable = {
        keyMap: {
            'Enter': { action: 'openSomething', weight : 0 }
        }
    }
    
    openSomething(){
        new Something(this.selectedTasks).open();
        // Return false to continue calling other Enter actions
        // (probably opens the Task editor)
        return false;
    }
}