Clarification on shortcuts documentation

Masterpiga · November 1, 2025, 1:23pm

Hi all,

Thanks to @dterrahe and others I started understanding shortcuts a bit better.

As I found the corresponding manual entry a bit confusing, I decided to take a stab at improving it, revising (to me) confusing terminology and adding some examples. If all is well I should have a PR before the end of the weekend.

The reason why I am writing is that there are two passages that I think are in contradiction, unless (as it is very possible) I am misunderstanding something.

At the end of line 176 , in the context of utility modules, there is the following statement:

Extended shortcuts are not currently available for preset elements.

Which I understand as: it is not possible to define a shortcut including movement to select a preset.

But then, on line 199, in the context of processing modules, it says:

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.

Is there a difference between utility and processing modules w.r.t. preset navigation via shortcut, is this just an inconsistency or am I misunderstanding something?

I believe that you can assign a simple shortcut to both utilty and processing modules, and then use the scroll wheel to navigate the presets. You can probably also assign an extended shortcut to them, but this does not add a lot of value as you can already scroll the list when you activate the preset list with a simple shortcut. Or else?

Any clarification would be greatly appreciated.

Tagging @elstoc who was the last to edit that file (3 years ago! :D) and @dterrahe who I believe authored most of the related code (apologies if I am wrong).

Thanks for your help!

wpferguson · November 1, 2025, 6:32pm

Yes. In dev speak utility modules are libs and processing modules are iops. IIRC the preset handling code is different between the two.

You can “explore” shortcuts by choosing an item and assigning a shortcut to it. Then it becomes visible in the lower window and you can click on the fields and see what options are supported.

You can unassign the shortcut by double clicking on the assigned shortcut and using the same keystroke combination to remove it.

Masterpiga · November 2, 2025, 9:54am

So, this is a shortcut assigned to the presets element of a processing module:

And this is for a utility module:

It seems to me that they support the same effects.
I believe that the docs are just a bit inconsistent, maybe because at some point the two implementations were more divergent and the docs have not been updated when that changed.

It is still possible that I am not understanding what the quoted parts of the docs are trying to convey, though.

Masterpiga · November 2, 2025, 1:47pm

Well, here is my attempt to improve the docs based on what I understood so far:

github.com/darktable-org/dtdocs

Clarity and structure improvements in the shortcuts documentations

master ← masterpiga:clarity_improvements_in_shortcuts

opened 01:46PM - 02 Nov 25 UTC

masterpiga

+128 -86

The documentation about shortcuts was confusing to me. After a few exchanges on …pixls.us, I think that I understand things better. Armed with this better understanding, I thought that I was in a good position to try to improve it. The content is by and large the same, I have just moved things around a bit to keep the information flow more consistent and to add a bit of structure. In terms of content changes, the only notable one is that I replaced the distinction between **simple** vs. **extended** shortcuts, which seemed a bit arbitrary and that I found confusing, with **discrete** vs. **continuous**, as these shortcuts are associate with **discrete** (e.g., click) vs. **continuos** (e.g., change value) UI actions. This also shifts the focus from the type of shortcut that one is defining to the kind of action that one wants to trigger, which IMHO is more logical and hence easier to understand. I also added a few more concrete examples, which were lacking, and whenever possible aded captions to the paragraph to make it easier to find what one is looking for.