Custom Hotkeys

Table of Contents

• Glossary
• Adding new hotkeys
• Adding new hotkey categories

Glossary

Word	Meaning
Shortcut	QShortcut object created from a hotkey.
Hotkey	Template for creating shortcuts in the right categories. See Hotkey object.
Category	Place where hotkeys' actions are executed.
Action	Code that makes a hotkey do something.
Keybinding or key combo	The keys you press on the keyboard to do something.

Adding new hotkeys

Adding new hotkeys to a widget that already has hotkeys is quite easy.

Add an action

1. Locate the call to getApp()->hotkeys->shortcutsForCategory(...), it is located in the addShortcuts() method
2. Above that should be a HotkeyController::HotkeyMap named actions
3. Add your new action inside that map, it should return a non-empty QString only when configuration errors are found.
4. Go to ActionNames.hpp and add a definition for your hotkey with a nice user-friendly name. Be sure to double-check the argument count.

Add a default

Defaults are stored in HotkeyController.cpp in the resetToDefaults() method. To add a default just add a call to tryAddDefault in the appropriate section. Make sure that the name you gave the hotkey is unique.

void HotkeyController::tryAddDefault(std::set<QString> &addedHotkeys,
                                     HotkeyCategory category,
                                     QKeySequence keySequence, QString action,
                                     std::vector<QString> args, QString name)

• where action is the action you added before,
• category — same category that is in the shortcutsForCategory call
• name — unique name of the default hotkey
• keySequence - key combo for the hotkey

Adding new hotkey categories

If you want to add hotkeys to new widget that doesn't already have them it's a bit more work.

Add the HotkeyCategory value

Add a value for the HotkeyCategory enum in HotkeyCategory.hpp. If you widget is a popup, it's best to use the existing PopupWindow category.

Add a nice name for the category

Add a string name and display name for the category in HotkeyController.hpp to hotkeyCategoryNames and hotkeyCategoryDisplayNames.

Add a shortcut context

To make sure shortcuts created from your hotkeys are only executed in the right places, you need to add a shortcut context for Qt. This is done in Hotkey.cpp in Hotkey::getContext(). See the ShortcutContext enum docs for possible values

Override addShortcuts

If the widget you're adding Hotkeys is a BaseWidget or a BaseWindow. You can override the addShortcuts() method. You should also add a call to it in the constructor. Here is some template/example code:

void YourWidget::addShortcuts()
{
    HotkeyController::HotkeyMap actions{
        {"barrelRoll", // replace this with your action code
         [this](std::vector<QString> arguments) -> QString {
             // DO A BARREL ROLL
             return ""; // only return text if there is a configuration error.
         }},
    };
    this->shortcuts_ = getApp()->hotkeys->shortcutsForCategory(HotkeyCategory::PopupWindow /* or your category name */,
                                                            actions, this);
}

Renaming defaults

Renaming defaults is currently not possible. If you were to rename one, it would get recreated for everyone probably leading to broken shortcuts, don't do this until a proper mechanism has been made.