shortcuts

Shortcuts are a way to control darktable using your keyboard, mouse, trackpad, or other input devices, such as MIDI and game controllers (as detailed in the midi device support section). They allow you to perform actions without interacting directly with a UI element.

An action is usually an operation that you might undertake using darktable’s point-and-click user interface. See common actions for a list of the most common ones. For example:

Increase, decrease or reset sliders
Scroll through dropdown lists
Enable, expand or focus modules
Click buttons
Switch between views

The recommended way to assign shortcuts to visual elements is the visual shortcut mapping mode.

🔗in a nutshell

If you just want to assign a specific key to toggle a button, the process is the following:

Click on the icon in the top panel
Hover the button that you want to control
Press the key that you want to use to control the button

Similarly, to control a slider with a shortcut you can:

Click on the icon
Hover the slider that you want to control
Press the key that you want to use to control the slider, and scroll the mouse wheel or move the mouse horizontally, vertically or diagonally

The system is very flexible and powerful, and this is just scratching the surface. Keep on reading to understand it better and learn how to make the most of it.

🔗types of shortcuts and actions

There are two types of actions:

Discrete actions: E.g., executing a command, focusing a UI element or resetting a slider
Directional actions: E.g., adjusting the value of a slider or scrolling through a list of presets

As the two action types are inherently different, so are the shortcuts you can use to trigger them:

Discrete actions can be triggered by discrete shortcuts consisting only of key presses and optionally mouse clicks
Directional actions need also a direction (and, in the case of sliders, a magnitude). Hence, the corresponding directional shortcuts will also incorporate a mouse movement

For example:

The key e can be used to focus a module, or to toggle it on/off
The key e, combined with up/down movements or the mouse, can be used to control the value of a slider

Note: A directional shortcut is sufficient to trigger a discrete action. The opposite is not true. However, it is possible to use a combination of two discrete shortcuts to control a directional action. For example, you can use two different shortcuts to trigger the up and down effects of a slider (see anatomy of an action).

If you are using keyboard and mouse, all shortcuts must start with one or more key presses, as mouse actions in isolation are used to navigate and interact with the UI.

If you have an input device, you can trigger discrete actions by pressing one or more buttons on the controller. Directional actions can use a combination of buttons and a knob/joystick movement, or just knob/joystick movement.

🔗anatomy of a shortcut

The simplest shortcut consists of just one key press (e.g., e).

The same key can be repeated up to three times, so also e double-press (i.e., e pressed and released twice in quick succession) and e triple-press (i.e., e pressed and released three times in quick succession) are valid, and distinct, shortcuts.

You can further extend a shortcut with up to three clicks of different mouse buttons. So, e double-press + left click or e + right click + left click are also valid shortcuts.

Finally, if your fingers are very nimble and you really need to go there, you can repeat the last click up to three times. So, also e + left click + middle double-click and e double press + middle click + left click + right triple-click are valid shortcuts.

Hence, the most complex shortcut can consist of 8 key/button presses:

Three key presses of the same key, (e.g., e), followed by
Three presses of the three mouse buttons, followed by
2 more repetitions of the last click.

Your shortcut can include one or more modifiers (shift, ctrl and alt). In this case, for a directional shortcut, both the last key and the modifier must be pressed down when you execute the movement. For example, ctrl + e double-press + pan means that while moving the mouse left and/or right both e and ctrl must be pressed down.

Note: If you are a macOS user, your shortcuts will use cmd instead of ctrl and option instead of alt.

If you are defining a directional shortcut, then the movement part of the shortcut must be executed while the last key, mouse or controller button is held down.

For example, the shortcut e double-press + pan, can be activated by pressing e twice, holding down e on the second press and moving the mouse horizontally while the key is pressed.

🔗short and long presses

By default, all key presses and button clicks in a shortcut are short, i.e., the key/button is pressed and immediately released. However, the last repetition of a key/button press in a shortcut can also be a long one. You can turn a normal key/button press into a long press by simply holding it a little longer before releasing it (longer than double-click speed but shorter than twice double-click speed). This applies to key presses and mouse clicks alike. Hence e double-press and e long double-press are two distinct shortcuts that can be assigned to different actions. The associated action triggers when the key is released, which entails that a shortcut ending with a long press cannot be used for a directional shortcut.

🔗movements in directional shortcuts

The following movements are supported when defining directional shortcuts:

Movement of the mouse scroll wheel
Horizontal, vertical or diagonal movement of the mouse cursor
Movement of a knob/joystick on an input device

When using an input device, you can directly assign a control knob or joystick to an action. However, this will significantly reduce the flexibility of such devices, as you will be able to use the knob/joystick only to control one action. By prefixing the movement with a key or button press you can use the same knob/joystick to control multiple actions.

🔗triggering multiple shortcuts at once

If both e + scroll and f + scroll are mapped to a slider (or if you have fallbacks enabled), then scrolling the mouse wheel while holding down both e and f will move both sliders. Similarly, you could map e double-press + scroll and f double-press + scroll to two nodes in a graph (say, yellow and green in color equalizer). You can then move both sliders at once by:

pressing and releasing e once;
pressing and holding e;
pressing and holding f;
using the scroll wheel while both e and f are pressed.

This works because the repeat key counter is per-shortcut, not per key, and it is reset only after the current shortcut ends (i.e., when the repeated key is released). Thus it is possible to trigger as many actions at once as your fingers can handle, provided that all the shortcuts involved have the same number of key presses (i.e., single, double or triple presses).

🔗shortcuts must be unique within a view

A single action may have multiple shortcuts but a single shortcut can only be linked to one action in a given darktable view – you can’t chain actions together except by applying a preset or style. You can, however, set up a single shortcut that does one thing in the lighttable view and another in the darkroom view.

🔗additional modifiers

The only valid modifiers are the shift, ctrl and alt keys on the keyboard. You can assign any key (or input device buttons) to function as one of the existing modifier types by assigning keys/buttons to the “global/modifier” action. However, you cannot define new modifier types.

🔗anatomy of an action

Actions apply an effect to an element of a widget, where these terms are defined as follows:

widget: Each visible part of the user interface is a widget. For example, the darktable application window is a widget, containing side panel widgets, each of which contains module widgets, each of which contains button, slider and dropdown list widgets etc. When assigning a shortcut to an action, you must first decide which widget it will apply to.
element: An element is the part of a UI widget that is affected by your shortcut. For example, for a slider that has a picker, you can make a shortcut activate the picker button element or change the value element of the slider. For a row of tabs (the row is a single widget) you can select which tab element to activate or use your mouse scroll wheel to scroll through the tabs.
effect: A shortcut can sometimes have multiple possible effects on a given element. For example, a button can be activated as if it was pressed with a plain mouse-click or as if it was pressed with Ctrl+click. A slider’s value can be edited, increased/decreased or reset.

For example, you can assign the shortcut e + scroll to change the value (the effect) of the exposure slider (the element) of the exposure correction widget.

🔗assigning shortcuts to actions

There are two primary methods of assigning shortcuts to actions: visual shortcut mapping (recommended) and the shortcut mapping screen. The former makes it easier to remap multiple shortcuts at once, while the latter allows for finer control and more flexibility.

🔗visual shortcut mapping

Click on the icon in the top panel of any darktable view to enter visual shortcut mapping mode. If you hold Ctrl while clicking the button, no confirmation will appear when overwriting an existing shortcut mapping.

The mouse cursor will change as you hover over UI widgets, to indicate whether or not a mapping can be created:

appears when you hover over a module header, to indicate that you can click to expand the module.
indicates that, in addition to assigning a shortcut, you can also add the widget to the quick access panel in the darkroom (by Ctrl+clicking on it).
indicates that the widget is already in the quick access panel (Ctrl+click to remove it).
indicates that a shortcut can be defined for the widget under the cursor but it cannot be added to or removed from the quick access panel.
indicates that there is no mappable widget under the cursor.

To define new shortcuts: Press a key combination while hovering over a mappable widget. A default action will be assigned to that shortcut based on the type of widget and whether it is directional. See the common actions section for examples of some of the defaults. You can assign as many shortcuts as you like in a single mapping session and then exit mapping mode when you are finished by clicking the icon again or right-clicking anywhere on the screen.

To explore already defined shortcuts: Left-click on a mappable widget to open the shortcut mapping screen for that widget (see below). Left-click anywhere else on the screen to open the shortcut mapping screen, expanded (where possible) based on the part of the screen you have clicked on. This screen can be used to alter the action assigned to a shortcut and to configure shortcuts for non-visual actions. Entering the shortcut mapping screen exits visual shortcut mapping mode.

To update existing shortcuts: Define a second shortcut against the same widget. If you attempt to reallocate an existing shortcut to a new action, you will be notified of the conflict and prompted to replace the existing shortcut.

To change the default speed of a slider: Scroll with your mouse wheel while in visual mapping mode (without pressing any other buttons/keys) when hovering over the slider – scroll up to increase and down to decrease. When you leave mapping mode, normal mouse scrolls over that slider will change its value with the adjusted speed.

🔗shortcut mapping screen

The shortcut mapping screen can be accessed from the global preferences dialog or by right-clicking on the visual mapping button. This screen allows access to all available actions, including some that are not directly linked to a UI widget.

The top panel of the shortcut mapping screen shows a list of available UI widgets/actions and the bottom panel shows the shortcuts currently assigned to them. Fields that can be changed by user action are shown in bold.

Note: You can search the top and bottom panels using the text entry boxes at the bottom of the screen, and use the up/down arrow keys to navigate between matches.

To create a new shortcut for an item: Double-click an item in the top panel, and then enter your desired shortcut (right-click to cancel). Once you have done this, a new entry will appear in the bottom panel showing the shortcut you have created. You can then manually alter the element, effect, speed or instance of the assigned action against that shortcut in the bottom panel. To delete a user-defined shortcut, select it in the bottom panel and press the Delete key.

Selecting an existing shortcut in the bottom panel will highlight (in bold) the matching action and its parents in the top panel. You can use this to navigate the top panel and find related actions.

The following additional options are provided in the shortcut mapping screen:

export…: Export the current shortcut mappings for one or all of your devices (keyboard/mouse, midi, game controller) to an external file. The dialog will show you how many shortcuts exist for each device.
import extras: Import extended shortcuts from a system file (shortcutsrc, with an optional language suffix, from your darktable installation – not the local config file of the same name). Existing shortcuts matching any in the system file will be replaced. These shortcuts will be localized to your system language if a localized version of the system file is available – currently, only German (shortcutsrc.de) in addition to the default English.
import…: Import shortcut mappings from an external file for one or all of your devices. When loading a device, you can chose to assign it a different number. This can for example be used to exchange midi layouts. Before loading, you can chose to wipe the specific device first. When loading all from an empty file, this will effectively delete all your shortcuts.
restore…: Restore your shortcut mappings to (a) The mappings shipped with darktable by default, (b) The start of your current session, or (c) The point at which the shortcut mapping screen was last opened. When restoring, you can choose to leave any additional shortcuts that were added after the relevant checkpoint as they are, so that only changed shortcuts are restored to their previous meaning. Or you can choose to first clear all shortcuts and just load the restore point.

🔗deleting default shortcuts

When you delete a shortcut that has been created by darktable by default, that shortcut is moved to a separate “disabled defaults” category, in order to prevent it from being reloaded the next time darktable is launched. To reinstate a deleted shortcut, simply delete the shortcut from that category. You will be prompted if reinstating this shortcut overwrites another one that has been created in the meantime.

Alternatively, you may disable preferences > miscellaneous > interface > load default shortcuts at startup to prevent default shortcuts from being loaded on startup. While this option is disabled, darktable will only load user-defined shortcuts and any defaults that you have not subsequently deleted or overridden.

🔗common actions

The following is a list of some of the actions to which you can assign shortcuts, organized by widget type. This is not an exhaustive list and you are encouraged to browse the shortcut mapping screen for a complete list of available actions.

Note: Some actions may have no effect. For example, all sliders include a button element, regardless of whether such a button is actually present alongside a given slider.

🔗global actions

Actions in the “global” section of the shortcut mapping screen can be executed from any darktable view. Most of these actions do not have specific elements as they are used to perform one-off operations.

For example, the predefined shortcut tab triggers the action globals/panels/all, which toggles the visibility of all the side panels in the current view.

🔗view-specific actions

Actions in the “views” section can only be executed from the specified darktable view. As with global actions, most do not have specific elements as they are used to perform one-off operations.

For example, the predefined shortcut ctrl + b triggers the action views/darkroom/guide lines/toggle, which toggles guide lines in the darktable view. It has an effect setting which allows you to directly simulate a right-click on the button, which in this case opens the guide lines configuration popup.

🔗actions on modules

All utility and processing modules have the following elements:

show: Acts as a toggle that expands and collapses the module.
reset: Acts as a button that resets all module parameters when activated. The ctrl-activate action can be used to re-apply any automatic presets for that module.
presets: Allows you to select actions from the presets menu (e.g. edit, update, previous, next). The default action, when assigning a discrete shortcut to a preset element, is to display a list of the available presets for selection.

When a shortcut is assigned to a utility module, the default action is to toggle the show element (expand/collapse the module).

🔗processing modules

Additionally, processing modules have the following elements:

enable: Acts as a toggle that switches the module on and off.
focus: Acts as a toggle that focuses or unfocuses the module. This is useful for modules such as crop or tone equalizer, whose on-screen controls are only activated when those modules have focus. For crop, changes are saved only when the module loses focus.
instance: Allows you to select actions from the multiple-instance menu (e.g. move up/down, create new instance). The discrete action associated to the instance element displays a list of the available options for selection; a directional action is also available and will move the preferred module instance (see below) up and down the pixelpipe.

If an action affects a processing module that can have multiple instances, you can choose which instance to adjust with a given shortcut. By default, all actions will affect the “preferred” instance, as defined using the settings in preferences > miscellaneous > shortcuts with multiple instances.

Additional options are available in the shortcuts mapping screen to adjust the blend parameters (the <blending> section) and module controls (the <focused> section) for the currently-focused module. The latter section allows you to assign shortcuts to the first, second, third (etc.) button, drop-down, slider and tab on the module. The shortcuts will affect different module controls depending on which module currently has focus (as the available list of controls changes).

For example, you if you assign ' + scroll to processing modules/\<focused\>/sliders and set element to 1st, you will be able to use the scroll wheel while holding down ' to adjust the value of the first slider of the currently focused module. If exposure is focused you will affect the exposure correction slider, if denoise (profiled) is focused you will affect the denoising strength slider.

🔗buttons

A button is a clickable icon in the darktable interface. The default action is to activate that button as if clicked with the left mouse button. You can modify this action to activate the button as if clicked while holding a modifier key.

🔗toggles

A toggle is a button that has a persistent on/off state. It therefore has additional effects to allow you to toggle it or explicitly set its state. As with a normal button, the default action is to activate the toggle as if clicked with the left mouse button (which toggles the button on/off).

For example, the predefined shortcut shift + O is associated to views/darkroom/raw overexposed/toggle, which toggles on/off the raw overexposure indicator in the darkroom.

🔗dropdowns

A dropdown is a multi-selection box and has the following elements available:

selection: Allows values to be selected from the dropdown list in various ways. The default action, when assigning a discrete shortcut to a dropdown, is to display a popup edit box with a list of the available values for selection; A directional shortcut (i.e., including a mouse movement) will scroll through the available values.
button: A standard button element that allows the button to the right of the dropdown (if present) to be activated. For example, the aspect dropdown in the crop module has a button that allows the crop controls to be changed from portrait to landscape and vice versa.

🔗sliders

A slider allows you to continuously alter an integer or decimal value, and has the following elements available:

value: Allows the current value of the slider to be altered. The default action, when assigning a discrete shortcut to a slider, is to display a popup edit box so you can enter a value; A directional shortcut will change the value up and down. Value elements are also used for modifying some on-screen graphs. When modifying the value element with a shortcut you may not exceed the bounds set in the visual slider.
force: This is the same as the value element described above, but it allows you to exceed the bounds set in the visual slider.
zoom: Allows you to change the upper and lower bounds of the visual slider without altering the current value.
button: A standard button element that allows the button to the right of the slider (if present) to be activated. For example, a slider may include a picker to visually set its value based on selected elements of the image.

You can alter the value of a slider more quickly or slowly than normal by defining the speed of the action in the shortcut mapping screen. By default a value (or force) effect is given a speed of 1.0, which means that it is changed at the default rate defined by the given slider. You can alter the slider more quickly by increasing the speed (a speed of 10 makes the action 10x faster) or more slowly by decreasing it (a speed of 0.1 makes the action 10x slower).

🔗fallbacks (a.k.a. generalized shortcut extensions)

As discussed above, a widget can have multiple different actions applied to it, and you may want to set shortcuts to control several of them. For example, to toggle a module on/off, expand/collapse it, and reset it to its default state. Normally, this would require setting 3 shortcuts for each module. If you want to control 5 modules in this fashion, you have to define 15 shortcuts. Setting up all these shortcuts one by one can be tedious and error prone.

To make this process simpler and to ensure consistency across all modules, you can create a single discrete shortcut for each module and then have a number of effects made available by default as extensions to that shortcut. These generalized shortcut extensions are called shortcut fallbacks.

Note: Fallbacks are a powerful way to quickly set up multiple actions using predefined and consistent shortcuts. They will assign a lot of actions automatically, which may be confusing if you are not aware of them. Fallbacks are therefore disabled by default and you will need to click on the enable fallbacks check box in the shortcuts setup window to enable them.

If they are enabled, when you create a discrete shortcut (e.g., ctrl + r) against a processing module the following shortcuts will be defined automatically:

ctrl + r to show/hide the module (the default fallback)
ctrl + r + left click to enable/disable the module
ctrl + r + left double-click to reset the module
ctrl + r + right click to show the module’s preset menu
ctrl + r + right double-click to show the module’s multiple instance menu

In each case (except the first) you should hold the initial shortcut while clicking with your mouse. The final single/double mouse-click will apply the corresponding action.

Similar fallbacks are defined for many common UI elements. As with any other shortcut, fallback settings are fully customizable.

To see a list of all of the default fallbacks, click the “enable fallbacks” checkbox in the shortcut mapping screen and select the “fallbacks” category in the top panel. To see the fallbacks for a given widget (e.g. a slider) just select that widget in the top panel. In both cases an additional item (also named “fallbacks”) will then appear in the bottom panel containing full details of the available fallbacks.

Fallbacks are only applied if no other shortcut using the resulting combination has been explicitly created. In the above example, if you were to explicitly assign ctrl + r + left click to another action, the “enable/disable module” fallback would be ignored.

Some fallback actions are defined using modifier keys (usually ctrl + and shift +). In this case you must define an initial shortcut without such a modifier in order to be able to use these fallbacks. For example, if you assign ctrl + r to an action, you cannot use a ctrl + fallback. Some default fallbacks of this type are provided for the value element and for horizontal/vertical movements in the (zoomed) central area – in this case, shift + increases the speed to 10.0 and ctrl + decreases the speed to 0.1.