Ansel interface is designed to support two mutually-exclusive modes of interaction and navigation: through pointing devices (mouse or graphic tablet) and through the keyboard. Compared to Darktable, many interactions that required combinations of both have been removed, which makes the workflows more efficient.
Shortcuts and available actions
Ansel exposes app-wise actions and GUI controls to keyboard bindings through pathes like Darkroom/Modules/Exposure/Black point
, where the left-most member of the path is the view and the right-most member is the actual control being bound. A such path defines an human-readable unique identifier that also says where the control is located in the application GUI.
Ansel has two kinds of objects that users can map to keyboard binding through those pathes:
- GUI controls/widgets : buttons, sliders, comboboxes, etc. Shortcuts attached to those will give them the focus,
- Actions : most of them are attached to the global menu, but some are contextual, depending on which widget has the focus. Shortcuts attached to those will trigger the actions.
The focus is a GUI state in which a widget will capture all keyboard events sent to the application. For text entries, that obviously means recording keystrokes to type text. For other widgets, like sliders, that may be arrow keys events to increase/decrease the value. Only one widget in the whole application can grab the focus at any given time. Ansel shortcuts attached to widgets will therefore switch the focus to them. From there, interacting with widgets (to change their value or their state) is done through generic (non-user-configurable) key bindings. Widgets shortcuts are therefore only meant select a target widget (visible or not) to which further keyboard interactions will be dispatched.
Finding default shortcuts, setting new ones
Note
A popup window showing all available actions and their defined keys is available from the global menu, under Edit → Keyboard shortcuts…. This window is meant to be at the same time a cheatsheet and a controller to edit shortcuts.The shortcut pathes are broken into a hierarchical tree in this window. The first level of the hierarchy defines the shortcuts groups:
- there is one global group (tied to the global menu),
- there are several local groups (tied to each view : darkroom, lighttable, etc.).
Inside each group, a combination of keys can be used at most once. If you try to re-use a key combination already in use somewhere else in the same group, you will get an error message saying what path is already using it.
Several shortcuts groups can include the same combination of keys. The global group is loaded all the time in all views of the application, the local groups are loaded only when entering their respecting view and unloaded when exiting it (only one is loaded at anytime). If the global and a local group have each a shortcut using the same keys, as long as the local group is loaded, its shortcut will take precedence over the global shortcut.
- Read-only shortcuts
- They are signaled with a lock icon, meaning they can’t be edited by users. They are described as contextual interaction on focus, because they will need a widget of the right type focused before to have any effect. You will find them under :
Darkroom/Controls
(for sliders and comboboxes interactions),Lighttable/Thumbtable
(for navigation into the thumbnails grid).
- They are given here in a “cheatsheet” spirit and are guaranteed to be up-to-date with what the code defines. The values found in the popup supercede any documentation regarding shortcuts defaults. The keys used by the read-only shortcuts will be unusable in user-parametrable shortcuts from the same group.
- User-parametrable shortcuts
- They are either focusing actions, targeting a control, a module or a toolbox, or direct action triggers, like any action from the global menu.
- Edit a shortcut : double click on the shortcut label, or on the disabled label, in the keys column, then type the keys you want to define as a shortcut. To stop recording keystrokes, you can either hit Escape or click outside the keys column (which may be more reliable).
- Clear a shortcut : double click on the trashbin icon, on the right of the shortcut. There is no way to clear a shortcut once in editing mode.
- After a shortcut has been edited, it will be used without having to restart the application. If the shortcut applies to a menu entry, it should be updated in the menu too.
The shortcuts popup window has a double search-engine:
- one for features, that performs a case-insensitive search into action pathes,
- one for keys, allowing to search for key modifiers, or keys, or combinations of both:
- if only a key modifier or key is given, results will be returned for partial matches,
- if both a key and a modifier are given, results will be returned for full matches,
- the syntax for key combinations is
<Mod1><Mod2>Key
, where all elements are optional. Auto-completion is provided for modifiers when you start typing<
.
- features and key searches can be combined to efficiently narrow results,
- as long as any search entry is not empty, the shortcut treeview is expanded. To automatically expand all items while not searching anything in particular, you can input
/
into the feature search entry.
Vimkey-like, global action search
All the available actions can be searched and triggered from anywhere in the software, using a vimkey-like command with auto-completion. The feature is available from the global menu, under Help → Search actions (default shortcut : Ctrl+P).
This opens a modal popup with a search entry. Type in there a path (partial or complete) or simply the name of the action you are looking for. The auto-completion will return the list of all available actions matching your search from the currently-active shortcut groups, along with a description and their defined shortcut (if any). From there, by selecting one of the results (with mouse click, or navigating with arrow keys then hitting Enter), you will trigger the action. To cancel, hit Escape.
In this context, the action pathes become commands that can be triggered from the search popup without having to define shortcuts, which helps if you know what action you want to trigger but don’t remember where its controller is in the GUI, or simply if you can’t be bothered remembering shortcuts.
In darkroom, if you select in the global action search the path to a control (slider or combobox) within a module, the focusing action will open the parent module, scroll it such that it gets visible, make sure the control is visible (like changing the notebook page if the control is within a notebook/tabs) and focus the control. From there, you can keep interacting with the control through arrow keys to change its value.
This feature has also replaced the module search bar used since Darktable 3.6, because triggering the focus action on a module achieves the same result as restricting the list of modules to those matching a name query (making this module appear in GUI).
Keyboard workflow
Lighttable
Toolboxes
You can collapse/expand the toolboxes, in the left sidebar, by assigning them shortcuts or using the global action search on their focusing action. The effect of the focusing action is a toggle, so expanded toolboxes will be collapsed on the next action trigger.
Once a control has gained focus in a toolbox (which, so far, can only happen with a click), focusing on the next control can be done with Tab or using the arrow keys (in some situations). Otherwise, the focus is automatically given to the thumbtable (grid of thumbnails).
Thumbtable
Navigation within thumbnails can be done with arrow keys. PageUp/PageDown scroll the view to the previous/next page. Home/End move all the way to the start/end of the grid.
Navigation within thumbnails only hovers. To commmit the hovered thumbnail to a selection, press Space for a singleton selection. To add/remove the hovered thumbnail to/from the current set of selected images, press Ctrl+Space. To extend the current selection up to the hovered thumbnail (range selection), press Shift+
A selection is absolutely mandatory to be able to modify image metadata, such as ratings (stars), color labels, etc. or to apply any batch operations. Ansel is designed such that selections can only be made by “hard” interactions (pressing an hardware button), as to prevent user errors. Batch selection options, independent from the thumbtable, can be found in the global menu, under Selection.
Applying ratings uses the numeric keys (0-5) by default, applying color labels uses the F1-F6 keys.
Opening a picture in darkroom is done with Enter.
Filters
You can filter the current collection by text using the search entry, which will search into all text metadata of the image. To enter the search entry, the default shortcut is Ctrl+F.
Darkroom
Modules
To collapse/expand and focus a module, you can:
- hit Alt and see the mnemonic keys that some module have in their name, then type the mnemonic. This works only for visible modules.
- use the action search or define a shortcut on the module focusing action. This works also for hidden modules.
The module focusing action will automatically :
- open the native module tab of this module,
- expand and focus the module,
- scroll the right sidebar such that at least the header of the module (if not the whole module) is visible,
- collapse and fade out all other modules,
The user-defined set of favourite modules, that used to be displayed in a separate tab, is replaced by the ability to target a specific module through its focusing action.
To expand+focus the previous/next module in the current module tab, use Page Up/Page Down.
To switch to the next/previous module tab, use Ctrl+Tab and Ctrl+Shift+Tab. Once you reached one end of the modules tabs, it will cycle back to the other end.
Modules controls
To go directly to a control (slider or combobox), use the action search or define a shortcut to its focusing action. This will automatically:
- open the native module tab of this module,
- expand and focus the module,
- scroll the right sidebar such that at least the header of the module (if not the whole module) is visible,
- collapse and fade out all other modules,
- open the right notebook (tab) page if the control is insterted into a notebook,
- focus the control.
Once the control is focused:
- on sliders:
- arrow keys Left/Right will increase/decrease the value by a normal step,
- Ctrl+ arrows change the value using a fine step,
- Shift+ arrows change the value using a coarse step,
- on comboboxes:
- arrow keys Up/Down will cycle through the options,
- Enter validates the selected option and closes the popup,
- Escape exists the popup without validating the selected option.
Once a control is focused, you can focus to the previous/next with Up/Down keys, or Tab. To focus the previous/next control outside a notebook tab, when you reached the end of the current notebook page, use Ctrl+Up/Down.
Once a shortcut is attached to a control (slider or combobox) focusing action, as long as the shortcut keys are kept pressed, all mouse scrolling events are sent to this control even when the mouse is not over the widget (as it would normally require to record scrolling events). This allows a 2-hands mixed workflow where one hand, on the keyboard, selects the target control, while the other scrolls on the mouse to adjust the value. It replaces MIDI support that achieves the same through mapping exactly one potentiometer to exactly one control, which will quickly run out of knobs to control Ansel.
System integration
Certain shortcuts are already reserved by your operating system and desktop environment. It may be a good idea to let the OS listen and decode those before they are passed on to Ansel (in which case, they are consumed and never passed on). To do so, go into the Preferences popup, to miscellaneous, and check the box let the OS mask Ansel shortcuts.
Key variants and alternatives
The numpad key alternatives (digits, enter, delete, home, end, insert, page up/down, arrows) are decoded as the non-numpad alternatives by all shortcuts, which means numbers will be seen as the same object no matter where they are typed. They respond to numlock as they should (numlock on enables digits and arithmetic operators, numlock off enables navigation).
Ansel allows single-key shortcuts, without modifier, which is non-standard and may cause issues with some keys. For this reason, shortcuts are temporarily disabled when a text entry is active. If that causes issues on your system, consider using typical double-key shortcuts (with a modifier).