From f2973a165445be62916670e1db44ac5aa601cc12 Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Sat, 1 Nov 2025 08:23:43 +0100 Subject: [PATCH 01/14] Revamps documentation on keyboard shortcuts for improved clarity. --- content/preferences-settings/shortcuts.md | 212 +++++++++++++--------- 1 file changed, 126 insertions(+), 86 deletions(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index 0b71e8dd36..66db427a1a 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -5,77 +5,85 @@ weight: 120 draft: false --- -You can perform almost any action in darktable with a keyboard/mouse shortcut. You can also use various other input devices, including MIDI devices and game controllers -- see the [midi device support](../special-topics/midi-device-support.md) section for details. These are referred to as _external devices_ or just _devices_ in this guide. +_Shortcuts_ are a way to control darktable using your keyboard, pointing device or external controller. They allow you to perform _actions_ without interacting directly with a UI element. -# defining shortcuts +An _action_ is usually (but not always) an operation that you might undertake using darktable's point-and-click user interface. +See [common actions](#common-actions) below for a list of the most common ones. For example: -A _shortcut_ is a combination of key or button presses and/or mouse or device movements that performs an _action_ in darktable. +- 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](#visual-shortcut-mapping) mode. +A _shortcut_ is a combination of inputs that triggers one of the actions available in a given context. -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, say, and another in the darkroom view. +Darktable comes with many predefined shortcuts that use a combination of key presses and mouse movements, but you can also use various other input devices, including MIDI devices and game controllers -- see the [midi device support](../special-topics/midi-device-support.md) section for details. These are referred to as _external devices_ or just _devices_ in this guide. -## initiating a shortcut +# types of actions and shortcuts -A shortcut must be initiated by either +There are two types of actions: -- pressing a key on the keyboard; or -- pressing a button or moving a knob/joystick on an external device +_Discrete_ actions +: E.g., executing a command, focusing a UI element or resetting a slider -You cannot initiate a shortcut by moving your mouse, or by pressing the left, right or middle mouse buttons, as these actions are used to interact with darktable's UI. +_Continuous actions_ +: E.g., adjusting the value of a slider or scrolling through a list of presets -## simple shortcuts +As the two action types are inherently different, so are the shortcuts you can use to trigger them: -A shortcut that only includes button and/or key presses (and not mouse/device movements) is referred to as a _simple_ shortcut. +- _Discrete actions_ can be triggered by _discrete shortcuts_ consisting only of key presses and optionally mouse clicks +- _Continuous actions_ need also a direction (and, in the case of sliders, a magnitude). Hence, the corresponding _continuous shortcuts_ will also incorporate a mouse movement -A simple shortcut must be initiated as above, but can include: +For example: -- One or more modifier keys (Shift, Ctrl, Alt), held down while executing the remainder of the shortcut -- Up to three key presses, the last one of which may be a long-press (defined as a key-press longer than your system's double-click duration) -- Similarly, up to three device-button presses or mouse-button clicks, the last of which may be long +- 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 your pointing device, can be used to control the value of a slider -Various combinations of keyboard, mouse, and device buttons can be used to create simple shortcuts. +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. -### creating additional modifiers +If you have an external controller, you can trigger discrete actions by pressing one or more buttons on the controller. Continuous actions can use a combination of buttons and a knob/joystick movement, or just knob/joystick movement. -The only valid modifiers are the Shift, Ctrl and Alt keys on the keyboard. You can define additional keys (or device buttons) as modifiers by assigning keys/buttons to the "global/modifier" action. However, these will merely function as extra Ctrl, Alt or Shift keys -- you cannot create "new" modifiers. +# anatomy of a shortcut -## extending simple shortcuts with movement +Shortcuts can consist of up to three key/button presses **of the same key/button** (in a quick sequence). +So, for example, `E`, `E + E` and `E + E + E` are all valid shortcuts to trigger discrete actions, as well as `E + left-click`, `E + right-click` or `E + E + left-click`. -For certain actions you can choose to _extend_ a simple shortcut using mouse/device movement. For example you might hold Ctrl+X while scrolling with your mouse to change the value of a slider. The following can be used to extend a simple shortcut: +On the contrary, `E + A` is not a valid shortcut, and darktable will interpret it as a two different shortcuts: `E` followed by `A`. -- Movement of the mouse scroll wheel -- Horizontal, vertical or diagonal movement of the mouse cursor -- Movement of a knob/joystick on an external device +Your shortcut can include one or more modifiers (`Shift`, `Ctrl/Cmd` and `Alt/Option`). In this case, the modifier(s) have to be held down while executing the remainder of the shortcut. So, `Ctrl + E + E` means holding down `Ctrl` while pressing `E` twice in a rapid sequence. + +If you are defining a continuous shortcut, then the movement part of the shortcut must be executed while the last key, mouse or controller button is held down. -To extend a simple shortcut, you must hold the final key/button of the simple shortcut while performing the extending mouse/device movement. +For example, the shortcut `E + E + pan`, can be activated by pressing `E` twice, holding down `E` on the second press and moving the mouse horizontally. While you are holding down `E`, moving the mouse horizontally will adjust the value associated with the shortcut's action. As you release the `E` key, moving the mouse horizontally will just move the mouse on the screen. -For external devices you do not need to start with a _simple_ shortcut -- you can directly assign a control knob or joystick to an action -- though this will significantly reduce the flexibility of such devices. +**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, say, and another in the darkroom view. -Long button and key presses cannot be extended, as the length of the click/press is timed using the release of the final button/key -- such shortcuts must be terminated with the raising of the final button/key. +**Additional modifiers.** As mentioned above, the only valid modifiers are the Shift, Ctrl/Cmd and Alt/Option keys on the keyboard. You can define additional keys (or device buttons) as modifiers by assigning keys/buttons to the "global/modifier" action. However, these will merely function as extra Ctrl, Alt or Shift keys -- you cannot create "new" modifiers. ---- +## defining continuous shortcuts + +The following movements are supported when defining continuous shortcuts: -**Note:** You may need to switch off the "disable touchpad while typing" setting if you want to use extended shortcuts with a laptop touchpad. +- Movement of the mouse scroll wheel +- Horizontal, vertical or diagonal movement of the mouse cursor +- Movement of a knob/joystick on an external device --- -# actions +**Note:** You may need to switch off the "disable touchpad while typing" setting if you want to use continuous shortcuts with a laptop touchpad. -Shortcuts are used to initiate _actions_ within darktable. +--- -An _action_ is usually (but not always) an operation that you might undertake using darktable's point-and-click user interface. For example: +As mentioned above, when employing an external 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. Conversely, by prefixing the movement with a key or button press you can use the same knob/joystick to control multiple actions. -- Increase, decrease or reset sliders -- Scroll through dropdown lists -- Enable, expand or focus modules -- Click buttons -- Switch between views +# anatomy of an action -Such point-and-click type _actions_ are normally defined as the application of an _effect_ to an _element_ of a _widget_, where these terms are defined as follows: +_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 known as 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 is to be applied to. +: 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](../darkroom/processing-modules/module-controls.md#pickers), 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. @@ -83,9 +91,11 @@ element 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. +So, for example, you can assign the shortcut `E + mouse-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 a shortcut to an action. +There are two primary methods of assigning shortcuts to actions: [visual shortcut mapping](#visual-shortcut-mapping) (recommended) and the [shortcut mapping screen](#shortcut-mapping-screen). The former makes it easier to remap multiple shortcuts at once, while the latter allows for finer control and more flexibility. Both options are detailed below. ## visual shortcut mapping @@ -103,23 +113,34 @@ The mouse cursor will change as you hover over UI widgets, to indicate whether o - ![Don't signal](./shortcuts/no-signal.png#icon) indicates that there is no mappable widget under the cursor. -Press a key combination while hovering over a mappable widget to assign a shortcut to that widget -- a default action will be assigned to that shortcut based on the type of widget and whether you have keyed a _simple_ or _extended_ shortcut. See below for details of some of the default assigned actions. - -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 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 your shortcut includes a movement. See the [common actions](#common-actions) section below 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 ![visual mapping button](./shortcuts/visual-mapping-button.png#icon) icon again or right-clicking anywhere on the screen. -You can delete a user-defined shortcut mapping by defining it a second time against the same widget. If you attempt to reallocate an existing shortcut to a new action, you will be notified of the conflict and asked whether you wish to replace the existing shortcut. +**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. -Finally, if you scroll with your mouse wheel while in visual mapping mode (without pressing any other buttons/keys) when hovering over a slider, this will change the default speed for that 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. +**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 most flexible way to create shortcuts is by using the shortcut mapping screen, which can be accessed from the global preferences dialog or by left-clicking in visual mapping mode. This screen allows access to all available actions, including some that are not directly linked to a UI widget. +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. You can search the top and bottom panels using the text entry boxes at the bottom of the screen (use the up/down arrow keys to navigate between matches). Fields that can be changed by user action are shown in bold. +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. -Double-click an item in the top panel to create a new shortcut for that item, 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. +--- + +**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. @@ -142,29 +163,30 @@ Alternatively, you may disable [preferences > miscellaneous > interface > load d # 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. If you assign a shortcut to a widget, it will be given a default action, depending on the type of widget and on whether you have assigned a simple or extended shortcut. +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 that it is possible to assign a number of actions that 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 +**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. -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. +--- -## views +## global 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. +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. -## buttons +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. -A button is a clickable icon in the darktable interface. The default action, when assigning a simple shortcut to a _button_, 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. +## view-specific actions -## toggles +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. -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, when assigning a simple shortcut to a toggle, is to activate the toggle as if clicked with the left mouse button (which toggles the button on/off). +For example, the predefined shortcut `Ctrl/Cmd + B` triggers the action `views/darktable/guide lines/toggle`, which toggles guide lines in the darktable view. -## utility modules +## actions on modules -All utility modules have the following elements: +All _utility_ and _processing_ modules have the following elements: _show_ : Acts as a _toggle_ that expands and collapses the module. @@ -173,15 +195,13 @@ _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](../darkroom/processing-modules/presets.md) menu (e.g. edit, update, previous, next). The default action, when assigning a simple shortcut to a _preset_ element, is to display a list of the available presets for selection. Extended shortcuts are not currently available for preset elements. - -The default action, when assigning a simple shortcut to a utility module, is to _toggle_ the _show_ element (expand/collapse the module). +: Allows you to select actions from the [presets](../darkroom/processing-modules/presets.md) 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. -In addition, shortcuts are available for all of the controls on each module as well as any stored presets (see below). +When a shortcut is assigned to a utility module, the default action is to _toggle_ the _show_ element (expand/collapse the module). -## processing modules +### processing modules -Processing modules have the same elements and defaults as utility modules with the following additional elements: +Additionally, processing modules have the following elements: _enable_ : Acts as a _toggle_ that switches the module on and off. @@ -190,30 +210,42 @@ _focus_ : Acts as a _toggle_ that focuses or defocuses the module. This is useful for modules such as [_crop_](../module-reference/processing-modules/crop.md) or [_tone equalizer_](../module-reference/processing-modules/tone-equalizer.md), 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](../darkroom/processing-modules/multiple-instances.md) menu (e.g. move up/down, create new instance). The default action, when assigning a simple shortcut to the _instance_ element, is to display a list of the available options for selection; An extended shortcut will move the _preferred module instance_ (see below) up and down the pixelpipe. +: Allows you to select actions from the [multiple-instance](../darkroom/processing-modules/multiple-instances.md) 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 continuous 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](./miscellaneous.md#shortcuts-with-multiple-instances). Additional options are available in the shortcuts mapping screen to adjust the blend parameters (the \ section) and module controls (the \ 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). -You can also assign scroll shortcuts to the 'preset' menu, which allows you to use your mouse scroll wheel to scroll through the module's presets. +For example, you if you assign `' + mouse-scroll` to `processing modules/\/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. + +## actions on specific widget types -## dropdowns +### 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 simple shortcut to a dropdown, is to display a popup _edit_ box with a list of the available values for selection; An extended shortcut (including a mouse movement) will scroll through the available values. +: 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 continuous 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-reference/processing-modules/crop.md) module has a button that allows the crop controls to be changed from portrait to landscape and vice versa. -## sliders +### 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 simple shortcut to a slider, is to display a popup _edit_ box so you can enter a value; An extended shortcut (including a mouse movement) 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. +: 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 continuous 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. @@ -226,26 +258,34 @@ _button_ 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 +# 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. -Where a _widget_ can have multiple different _actions_ applied to it, it can be tedious to set up individual shortcuts for each one of those actions. To make this process simpler, if you create a simple shortcut a number of effects can be made available by default as extensions to that shortcut. These are known as _fallbacks_. +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_. -While 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 might not be what you want), and can be hard to understand. 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. +--- + +**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. + +--- -To take a brief example, you could create a simple shortcut (e.g. Ctrl+R) against a processing module. This will automatically set up the following _fallback_ effects using the defined shortcut, extended with mouse-clicks. In each case (except the first) you should hold the initial shortcut while clicking with your mouse. The final mouse-click will apply the action defined below: +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 (no mouse-click) 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 +- `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 -Similar fallbacks are defined for many common UI elements and all can be manually overridden. +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. -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. +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 that 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. +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. -As with any other shortcut, fallback settings are fully customizable. +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. \ No newline at end of file From 5ecb1ef4e79ba9a1bbf788f5331e0b8613a771ec Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Mon, 3 Nov 2025 10:59:35 +0100 Subject: [PATCH 02/14] Added information about multiple button presses and triggering multiple shortcuts at once. --- content/preferences-settings/shortcuts.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index 66db427a1a..0341390110 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -46,10 +46,14 @@ If you have an external controller, you can trigger discrete actions by pressing # anatomy of a shortcut -Shortcuts can consist of up to three key/button presses **of the same key/button** (in a quick sequence). -So, for example, `E`, `E + E` and `E + E + E` are all valid shortcuts to trigger discrete actions, as well as `E + left-click`, `E + right-click` or `E + E + left-click`. - -On the contrary, `E + A` is not a valid shortcut, and darktable will interpret it as a two different shortcuts: `E` followed by `A`. +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 + E` and `E + E + E` are valid, and distinct, shortcuts. +You can further extend a shortcut with up to three clicks of the same mouse button. So, `E + E + left-click` or `E + right-click + right-click` are also valid shortcuts. +Finally, if your fingers are very nimble and you really need to go there, you can add either or both of the mouse buttons that you haven't incorporated yet. So, also `E + left-click + middle-click` and `E + E + right-click + right-click + right-click + left-click + middle-click` are valid shortcuts. +Hence, the most complex shortcut can consist of 8 key/button presses: +* Three key presses of the same `key`, followed by +* Three presses of any mouse button, followed by +* 1 press of each remaining mouse button. Your shortcut can include one or more modifiers (`Shift`, `Ctrl/Cmd` and `Alt/Option`). In this case, the modifier(s) have to be held down while executing the remainder of the shortcut. So, `Ctrl + E + E` means holding down `Ctrl` while pressing `E` twice in a rapid sequence. @@ -57,6 +61,10 @@ If you are defining a continuous shortcut, then the movement part of the shortcu For example, the shortcut `E + E + pan`, can be activated by pressing `E` twice, holding down `E` on the second press and moving the mouse horizontally. While you are holding down `E`, moving the mouse horizontally will adjust the value associated with the shortcut's action. As you release the `E` key, moving the mouse horizontally will just move the mouse on the screen. +**Triggering multiple shortcuts at once.** Note that `E + A` is not a valid shortcut, and darktable will interpret it as a two different shortcuts: `E` followed by `A`. This is by design, as the system allows one to trigger multiple continuous shortcuts at once. +For example, if both `E + scroll` and `A + scroll` are mapped to a slider (or if you have fallbacks enabled), then scrolling with the mouse while holding down both `E` and `A` will move both sliders. If you have a series of keys assigned to nodes in a curve (e.g, tone equalizer) this allows you to move multiple nodes in parallel. + + **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, say, and another in the darkroom view. From a438e1414fbec024f17e59d652acae8546e322cc Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Mon, 3 Nov 2025 11:09:28 +0100 Subject: [PATCH 03/14] Explain that MacOs uses different modifiers only once. --- content/preferences-settings/shortcuts.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index 0341390110..e20a484511 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -55,7 +55,14 @@ Hence, the most complex shortcut can consist of 8 key/button presses: * Three presses of any mouse button, followed by * 1 press of each remaining mouse button. -Your shortcut can include one or more modifiers (`Shift`, `Ctrl/Cmd` and `Alt/Option`). In this case, the modifier(s) have to be held down while executing the remainder of the shortcut. So, `Ctrl + E + E` means holding down `Ctrl` while pressing `E` twice in a rapid sequence. +Your shortcut can include one or more modifiers (`Shift`, `Ctrl` and `Alt`). In this case, the modifier(s) have to be held down while executing the remainder of the shortcut. So, `Ctrl + E + E` means holding down `Ctrl` while pressing `E` twice in a rapid sequence. + +--- + +**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 continuous shortcut, then the movement part of the shortcut must be executed while the last key, mouse or controller button is held down. @@ -64,11 +71,10 @@ For example, the shortcut `E + E + pan`, can be activated by pressing `E` twice, **Triggering multiple shortcuts at once.** Note that `E + A` is not a valid shortcut, and darktable will interpret it as a two different shortcuts: `E` followed by `A`. This is by design, as the system allows one to trigger multiple continuous shortcuts at once. For example, if both `E + scroll` and `A + scroll` are mapped to a slider (or if you have fallbacks enabled), then scrolling with the mouse while holding down both `E` and `A` will move both sliders. If you have a series of keys assigned to nodes in a curve (e.g, tone equalizer) this allows you to move multiple nodes in parallel. - **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, say, and another in the darkroom view. -**Additional modifiers.** As mentioned above, the only valid modifiers are the Shift, Ctrl/Cmd and Alt/Option keys on the keyboard. You can define additional keys (or device buttons) as modifiers by assigning keys/buttons to the "global/modifier" action. However, these will merely function as extra Ctrl, Alt or Shift keys -- you cannot create "new" modifiers. +**Additional modifiers.** As mentioned above, the only valid modifiers are the `Shift`, `Ctrl` and `Alt` keys on the keyboard. You can define additional keys (or device buttons) as modifiers by assigning keys/buttons to the "global/modifier" action. However, these will merely function as extra `Ctrl`, `Alt` or `Shift` keys -- you cannot create "new" modifiers. ## defining continuous shortcuts @@ -190,7 +196,7 @@ For example, the predefined shortcut `Tab` triggers the action `globals/panels/a 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/Cmd + B` triggers the action `views/darktable/guide lines/toggle`, which toggles guide lines in the darktable view. +For example, the predefined shortcut `Ctrl + B` triggers the action `views/darktable/guide lines/toggle`, which toggles guide lines in the darktable view. ## actions on modules From 381b87576b514e5541a4bce1e169773636fb05ec Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Mon, 3 Nov 2025 11:13:38 +0100 Subject: [PATCH 04/14] Adds missing fullstop. --- content/preferences-settings/shortcuts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index e20a484511..f82608a33e 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -60,7 +60,7 @@ Your shortcut can include one or more modifiers (`Shift`, `Ctrl` and `Alt`). In --- **Note:** -If you are a MacOs user, your shortcuts will use `Cmd` instead of `Ctrl` and `Option` instead of `Alt` +If you are a MacOs user, your shortcuts will use `Cmd` instead of `Ctrl` and `Option` instead of `Alt`. --- From bc98e258929e2970dcca61f3d97381d35e64db9d Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Mon, 3 Nov 2025 17:52:09 +0100 Subject: [PATCH 05/14] Correct order for multiple clicks and long keypresses. --- content/preferences-settings/shortcuts.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index f82608a33e..fa9defc47b 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -38,7 +38,7 @@ As the two action types are inherently different, so are the shortcuts you can u 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 your pointing device, can be used to control the value of a slider +- The key `e`, combined with up/down movements or your pointing device, can be used to control the value of a slider 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. @@ -48,12 +48,12 @@ If you have an external controller, you can trigger discrete actions by pressing 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 + E` and `E + E + E` are valid, and distinct, shortcuts. -You can further extend a shortcut with up to three clicks of the same mouse button. So, `E + E + left-click` or `E + right-click + right-click` are also valid shortcuts. -Finally, if your fingers are very nimble and you really need to go there, you can add either or both of the mouse buttons that you haven't incorporated yet. So, also `E + left-click + middle-click` and `E + E + right-click + right-click + right-click + left-click + middle-click` are valid shortcuts. +You can further extend a shortcut with up to three clicks of different mouse buttons. So, `E + E + 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-click + middle-click` and `E + E + middle-click + left-click + right-click + right-click + right-click` are valid shortcuts. Hence, the most complex shortcut can consist of 8 key/button presses: * Three key presses of the same `key`, followed by -* Three presses of any mouse button, followed by -* 1 press of each remaining mouse button. +* Three presses of the three mouse buttons, followed by +* 2 more repetions of the last click. Your shortcut can include one or more modifiers (`Shift`, `Ctrl` and `Alt`). In this case, the modifier(s) have to be held down while executing the remainder of the shortcut. So, `Ctrl + E + E` means holding down `Ctrl` while pressing `E` twice in a rapid sequence. @@ -68,6 +68,9 @@ If you are defining a continuous shortcut, then the movement part of the shortcu For example, the shortcut `E + E + pan`, can be activated by pressing `E` twice, holding down `E` on the second press and moving the mouse horizontally. While you are holding down `E`, moving the mouse horizontally will adjust the value associated with the shortcut's action. As you release the `E` key, moving the mouse horizontally will just move the mouse on the screen. +**Long keypresses.** +The last repetition of a key in a shortcut can be either a _short_ (i.e., normal) or _long_ keypress, defined as holding down the key for a bit longer than the duration of a double click. Hence `E + E` and `E + E(long)` 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 continuos shortcut. + **Triggering multiple shortcuts at once.** Note that `E + A` is not a valid shortcut, and darktable will interpret it as a two different shortcuts: `E` followed by `A`. This is by design, as the system allows one to trigger multiple continuous shortcuts at once. For example, if both `E + scroll` and `A + scroll` are mapped to a slider (or if you have fallbacks enabled), then scrolling with the mouse while holding down both `E` and `A` will move both sliders. If you have a series of keys assigned to nodes in a curve (e.g, tone equalizer) this allows you to move multiple nodes in parallel. From a01494a4a612717eabb46bf0ad0fc57bb1770f98 Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Mon, 3 Nov 2025 18:06:41 +0100 Subject: [PATCH 06/14] Add implementation details for continuos actions. --- content/preferences-settings/shortcuts.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index fa9defc47b..94c8df0b2c 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -305,4 +305,10 @@ To see a list of _all_ of the default fallbacks, click the "enable fallbacks" ch 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. \ No newline at end of file +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. + +# implementation details + +This section covers some technical aspects that can be interesting for power users. + +**Continuous actions:** Continuous actions are convenience abstractions to make assigning shortcuts faster, but are actually implemented as two discrete actions that target the appropriate effects (e.g., `up` and `down`) of a widget. For example, assigning `E + pan` to a slider assignes `E + left` to the `down` action and `E + right` to the `up` action. \ No newline at end of file From 53003ecbf6e13cd93b4a6058d6170f39ee22e1d1 Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Tue, 4 Nov 2025 08:56:56 +0100 Subject: [PATCH 07/14] Use uppercase E for consistency. --- content/preferences-settings/shortcuts.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index 94c8df0b2c..df94c0bb92 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -37,8 +37,8 @@ As the two action types are inherently different, so are the shortcuts you can u 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 your pointing device, can be used to control the value of a slider +- 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 your pointing device, can be used to control the value of a slider 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. From 14e5b30de1596931a46351e83eb6be83458b2b1d Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Tue, 4 Nov 2025 09:09:50 +0100 Subject: [PATCH 08/14] Removed some fluff and fixed a couple of inconsistencies. --- content/preferences-settings/shortcuts.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index df94c0bb92..76e50bfa84 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -47,9 +47,13 @@ If you have an external controller, you can trigger discrete actions by pressing # 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 + E` and `E + E + E` are valid, and distinct, shortcuts. + You can further extend a shortcut with up to three clicks of different mouse buttons. So, `E + E + 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-click + middle-click` and `E + E + middle-click + left-click + right-click + right-click + right-click` are valid shortcuts. + Hence, the most complex shortcut can consist of 8 key/button presses: * Three key presses of the same `key`, followed by * Three presses of the three mouse buttons, followed by @@ -66,13 +70,13 @@ If you are a MacOs user, your shortcuts will use `Cmd` instead of `Ctrl` and `Op If you are defining a continuous 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 + E + pan`, can be activated by pressing `E` twice, holding down `E` on the second press and moving the mouse horizontally. While you are holding down `E`, moving the mouse horizontally will adjust the value associated with the shortcut's action. As you release the `E` key, moving the mouse horizontally will just move the mouse on the screen. +For example, the shortcut `E + E + pan`, can be activated by pressing `E` twice, holding down `E` on the second press and moving the mouse horizontally and moving the mouse horizontally will the key is pressed. -**Long keypresses.** -The last repetition of a key in a shortcut can be either a _short_ (i.e., normal) or _long_ keypress, defined as holding down the key for a bit longer than the duration of a double click. Hence `E + E` and `E + E(long)` 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 continuos shortcut. +**Short and long keypresses.** +By default, all keypresses in a shortcut are _short_, i.e., the key is pressed and immediately released. However, the last repetition of a key in a shortcut can also be a _long_ keypress, defined as holding down the key for a bit longer than the duration of a double click. Hence `E + E` and `E + E(long)` 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 continuos shortcut. **Triggering multiple shortcuts at once.** Note that `E + A` is not a valid shortcut, and darktable will interpret it as a two different shortcuts: `E` followed by `A`. This is by design, as the system allows one to trigger multiple continuous shortcuts at once. -For example, if both `E + scroll` and `A + scroll` are mapped to a slider (or if you have fallbacks enabled), then scrolling with the mouse while holding down both `E` and `A` will move both sliders. If you have a series of keys assigned to nodes in a curve (e.g, tone equalizer) this allows you to move multiple nodes in parallel. +For example, if both `E + mouse-scroll` and `A + mouse-scroll` are mapped to a slider (or if you have fallbacks enabled), then scrolling with the mouse while holding down both `E` and `A` will move both sliders. If you have a series of keys assigned to nodes in a curve (e.g, tone equalizer) this allows you to move multiple nodes in parallel. **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, say, and another in the darkroom view. From b95eb484703640a941a3e254dd1a57ee6945f19c Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Tue, 4 Nov 2025 13:32:06 +0100 Subject: [PATCH 09/14] Added clarification about using a composition of discrete shortcuts to trigger a continuos action. --- content/preferences-settings/shortcuts.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index 76e50bfa84..6014b4192c 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -40,6 +40,13 @@ 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 your pointing device, can be used to control the value of a slider +--- + +**Note:** +By construction, a _continuous shortcut_ is sufficiently expressive 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 _continuous action_. For example, you can use two different shortcuts to trigger the `up` and `down` effects of a slider (see [anatomy of an action](#anatomy-of-an-action) below). + +--- + 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 external controller, you can trigger discrete actions by pressing one or more buttons on the controller. Continuous actions can use a combination of buttons and a knob/joystick movement, or just knob/joystick movement. @@ -309,10 +316,4 @@ To see a list of _all_ of the default fallbacks, click the "enable fallbacks" ch 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. - -# implementation details - -This section covers some technical aspects that can be interesting for power users. - -**Continuous actions:** Continuous actions are convenience abstractions to make assigning shortcuts faster, but are actually implemented as two discrete actions that target the appropriate effects (e.g., `up` and `down`) of a widget. For example, assigning `E + pan` to a slider assignes `E + left` to the `down` action and `E + right` to the `up` action. \ No newline at end of file +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. \ No newline at end of file From 79fe8d33c1b2f6fe577609e7b8a5512b6eab273e Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Tue, 4 Nov 2025 14:26:10 +0100 Subject: [PATCH 10/14] Explains how simultaneous shortcuts work. --- .gitignore | 1 + content/preferences-settings/shortcuts.md | 13 +++++++------ 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index 9cc2f8e892..1512264e81 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ public/* public-epub/* public-pdf/* .hugo_build.lock +.vscode/settings.json diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index 6014b4192c..16bcc682f1 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -64,7 +64,7 @@ Finally, if your fingers are very nimble and you really need to go there, you ca Hence, the most complex shortcut can consist of 8 key/button presses: * Three key presses of the same `key`, followed by * Three presses of the three mouse buttons, followed by -* 2 more repetions of the last click. +* 2 more repetitions of the last click. Your shortcut can include one or more modifiers (`Shift`, `Ctrl` and `Alt`). In this case, the modifier(s) have to be held down while executing the remainder of the shortcut. So, `Ctrl + E + E` means holding down `Ctrl` while pressing `E` twice in a rapid sequence. @@ -79,11 +79,12 @@ If you are defining a continuous shortcut, then the movement part of the shortcu For example, the shortcut `E + E + pan`, can be activated by pressing `E` twice, holding down `E` on the second press and moving the mouse horizontally and moving the mouse horizontally will the key is pressed. -**Short and long keypresses.** -By default, all keypresses in a shortcut are _short_, i.e., the key is pressed and immediately released. However, the last repetition of a key in a shortcut can also be a _long_ keypress, defined as holding down the key for a bit longer than the duration of a double click. Hence `E + E` and `E + E(long)` 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 continuos shortcut. +**Short and long key presses.** +By default, all key presses in a shortcut are _short_, i.e., the key is pressed and immediately released. However, the last repetition of a key in a shortcut can also be a _long_ keypress, defined as holding down the key for a bit longer than the duration of a double click. Hence `E + E` and `E + E(long)` 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 continuos shortcut. -**Triggering multiple shortcuts at once.** Note that `E + A` is not a valid shortcut, and darktable will interpret it as a two different shortcuts: `E` followed by `A`. This is by design, as the system allows one to trigger multiple continuous shortcuts at once. -For example, if both `E + mouse-scroll` and `A + mouse-scroll` are mapped to a slider (or if you have fallbacks enabled), then scrolling with the mouse while holding down both `E` and `A` will move both sliders. If you have a series of keys assigned to nodes in a curve (e.g, tone equalizer) this allows you to move multiple nodes in parallel. +**Triggering multiple shortcuts at once.** +If both `E + mouse-scroll` and `F + mouse-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, say, `E + E + mouse-scroll` and `F + F + mouse-scroll` to two nodes in a graph (say, `yellow` and `green` in color equalizer). You can then use `E + E(hold) + F(hold) + mouse-scroll` to move both sliders at once. 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, say, and another in the darkroom view. @@ -235,7 +236,7 @@ _enable_ : Acts as a _toggle_ that switches the module on and off. _focus_ -: Acts as a _toggle_ that focuses or defocuses the module. This is useful for modules such as [_crop_](../module-reference/processing-modules/crop.md) or [_tone equalizer_](../module-reference/processing-modules/tone-equalizer.md), whose on-screen controls are only activated when those modules have focus. For _crop_, changes are saved only when the module loses focus. +: Acts as a _toggle_ that focuses or de-focuses the module. This is useful for modules such as [_crop_](../module-reference/processing-modules/crop.md) or [_tone equalizer_](../module-reference/processing-modules/tone-equalizer.md), 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](../darkroom/processing-modules/multiple-instances.md) 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 continuous action is also available and will move the _preferred module instance_ (see below) up and down the pixelpipe. From ee18e6ddbffc79ca661467ef10295f6123b83f67 Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Tue, 4 Nov 2025 17:51:32 +0100 Subject: [PATCH 11/14] Revisit explanation concerning modifier requirements for continuous shortcuts. --- content/preferences-settings/shortcuts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index 16bcc682f1..be6c3f0ca6 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -66,7 +66,7 @@ Hence, the most complex shortcut can consist of 8 key/button presses: * 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, the modifier(s) have to be held down while executing the remainder of the shortcut. So, `Ctrl + E + E` means holding down `Ctrl` while pressing `E` twice in a rapid sequence. +Your shortcut can include one or more modifiers (`Shift`, `Ctrl` and `Alt`). In this case, for a continuous shortcut, both the last key and the modifier must be pressed down when you execute the movement. For example, `Ctrl + E + E + pan` means that while moving the mouse left and/or right both `E` and `Ctrl` must be pressed down. --- From 593af6f5ff3ca18400d2dbb03bd110249e852b5d Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Tue, 4 Nov 2025 19:24:35 +0100 Subject: [PATCH 12/14] Undo changes to .gitignore --- .gitignore | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitignore b/.gitignore index 1512264e81..9cc2f8e892 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,3 @@ public/* public-epub/* public-pdf/* .hugo_build.lock -.vscode/settings.json From bb437a0301e4087168ff13aa15e6b3cd01b6b091 Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Wed, 5 Nov 2025 10:51:55 +0100 Subject: [PATCH 13/14] Removes accidentally repeated string. --- content/preferences-settings/shortcuts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index be6c3f0ca6..4feaffff93 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -77,7 +77,7 @@ If you are a MacOs user, your shortcuts will use `Cmd` instead of `Ctrl` and `Op If you are defining a continuous 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 + E + pan`, can be activated by pressing `E` twice, holding down `E` on the second press and moving the mouse horizontally and moving the mouse horizontally will the key is pressed. +For example, the shortcut `E + E + 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 key presses.** By default, all key presses in a shortcut are _short_, i.e., the key is pressed and immediately released. However, the last repetition of a key in a shortcut can also be a _long_ keypress, defined as holding down the key for a bit longer than the duration of a double click. Hence `E + E` and `E + E(long)` 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 continuos shortcut. From d004da33f4a81d76cd6eaadcb2cead59fd677a5c Mon Sep 17 00:00:00 2001 From: Daniele Pighin Date: Wed, 5 Nov 2025 10:57:08 +0100 Subject: [PATCH 14/14] Spells "keypress" as "key press". --- content/preferences-settings/shortcuts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/preferences-settings/shortcuts.md b/content/preferences-settings/shortcuts.md index 4feaffff93..17ff029bf8 100644 --- a/content/preferences-settings/shortcuts.md +++ b/content/preferences-settings/shortcuts.md @@ -80,7 +80,7 @@ If you are defining a continuous shortcut, then the movement part of the shortcu For example, the shortcut `E + E + 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 key presses.** -By default, all key presses in a shortcut are _short_, i.e., the key is pressed and immediately released. However, the last repetition of a key in a shortcut can also be a _long_ keypress, defined as holding down the key for a bit longer than the duration of a double click. Hence `E + E` and `E + E(long)` 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 continuos shortcut. +By default, all key presses in a shortcut are _short_, i.e., the key is pressed and immediately released. However, the last repetition of a key in a shortcut can also be a _long_ key press, defined as holding down the key for a bit longer than the duration of a double click. Hence `E + E` and `E + E(long)` 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 continuos shortcut. **Triggering multiple shortcuts at once.** If both `E + mouse-scroll` and `F + mouse-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.