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 capturing arrow keys events to increase/decrease the value. Only one widget in the whole application can grab the focus at any given time.

Clicking on a widget will automatically give it the focus, but that makes for a terrible workflow where you may have to constantly switch between mouse and keyboard. To allow a full-keyboard workflow, Ansel provides shortcuts to switch the focus to any desired target widget. From there, interacting with widgets (to change their value or their state) is done through generic (non-user-configurable) key bindings.

This means that :

  1. Widgets shortcuts are only meant to select a target widget (visible or not) to which further keyboard interactions will be dispatched,
  2. There is only one shortcut to configure (and remember) per widget,
  3. All widgets of the same type (button, slider, combobox) will use the same keyboard interactions once focused (easier to remember).

Focused control widgets will appear in a bolder font that the others. Focused modules will be highlighted.

Actions (other than widget focusing ones) don’t target widgets at all, and calling their shortcut directly triggers them, possibly outside the GUI.

Finding default shortcuts, setting new ones

image
The shortcuts window

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.

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+Space.

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 :

  1. open the native module tab of this module,
  2. expand and focus the module,
  3. scroll the right sidebar such that at least the header of the module (if not the whole module) is visible,
  4. 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:

  1. open the native module tab of this module,
  2. expand and focus the module,
  3. scroll the right sidebar such that at least the header of the module (if not the whole module) is visible,
  4. collapse and fade out all other modules,
  5. open the right notebook (tab) page if the control is insterted into a notebook,
  6. 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,
    • Insert triggers the attached color-picker if any.
  • on comboboxes:
    • arrow keys Up/Down will cycle through the options,
    • Enter validates the selected option and closes the popup,
    • Escape exits 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.

Module instances

When several instances of modules are in use, shortcuts are always attached to the first-added instance, which may not necessarily be the first in the pixel pipeline: the first instance is always the unnamed, base instance, until it gets deleted (then the next replaces it).1

All module instances that have an instance name set will get a private focusing action attached to the module (but none attached to its controls), using a path prefixed with Modules/Instances/ and followed by Module name/Instance name. Since instance names are a property of each editing history, and not constant during the lifecycle of the whole application, this focusing action cannot be assigned a key shortcut and is accessible only from the global action search.

When renaming the base instance of a module, it gets its own Modules/Instances/ focusing action, but this is only a duplicate of the default one from Modules/, and it doesn’t change the behaviour of the default actions (focusing the module and its controls).

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).

  1. The recommended workflow always uses the first instance as an average global setting, most likely to be accessed from keyboard for quick adjustments. Later instances are supposed to be local, often using masks, for which keyboard setting will not be enough if possible at all. ↩︎