accelerators.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2011-2013 Jérémy Rosen.
    Copyright (C) 2011 Robert Bieber.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2012, 2014, 2016-2017 Tobias Ellinghaus.
    Copyright (C) 2016 Roman Lebedev.
    Copyright (C) 2019-2020 Aldric Renaudin.
    Copyright (C) 2020 Chris Elston.
    Copyright (C) 2020-2022 Diederik Ter Rahe.
    Copyright (C) 2020 Heiko Bauke.
    Copyright (C) 2020 Hubert Kowalski.
    Copyright (C) 2020-2021 Pascal Obry.
    Copyright (C) 2021 Bill Ferguson.
    Copyright (C) 2022 Martin Bařinka.
    Copyright (C) 2023, 2025 Aurélien PIERRE.
    Copyright (C) 2026 Guillaume Stutin.
    
    darktable is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.
    
    darktable is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
    
    You should have received a copy of the GNU General Public License
    along with darktable.  If not, see <http://www.gnu.org/licenses/>.
*/
#include <gdk/gdkkeysyms.h>
#include <gtk/gtk.h>
#ifdef GDK_WINDOWING_WAYLAND
#include <gdk/gdkwayland.h>
#endif
 
#include "system/dtpthread.h"
 
G_BEGIN_DECLS
 
#define DT_ACCELS_WIDGET_SHORTCUT_KEY "dt-accel-shortcut"
#define DT_ACCELS_WIDGET_TOOLTIP_DISABLED_KEY "dt-accel-tooltip-disabled"
 
#ifndef DT_WIDGETS_ACCELERATORS_H
#define DT_WIDGETS_ACCELERATORS_H
 
/* Ansel's accelerator system is fully custom (see dt_accels_dispatch()) and never
 * goes through GTK's own accelerator string parser, so it gets none of the
 * "<Primary>" -> Ctrl/Cmd translation that convention normally provides for free.
 * Each default shortcut that is meant to follow the OS's own accelerator
 * convention (most menu/window-level shortcuts) must be registered with
 * DT_PRIMARY_MASK instead of GDK_CONTROL_MASK. A shortcut that must remain the
 * literal Ctrl key even on macOS should keep GDK_CONTROL_MASK explicitly.
 * On the Quartz GDK backend a physical Cmd keypress is reported through
 * GDK_MOD2_MASK (see _accels_keys_decode() in accelerators.c for the matching
 * GDK_META_MASK duplicate it has to filter out on that same backend). */
#ifdef GDK_WINDOWING_QUARTZ
#define DT_PRIMARY_MASK GDK_MOD2_MASK
#else
#define DT_PRIMARY_MASK GDK_CONTROL_MASK
#endif
 
typedef struct dt_accels_t
{
  char *config_file;
  GtkAccelGroup *global_accels;     // used, aka init it and free it
  GtkAccelGroup *darkroom_accels;   // darkroom-specific accels
  GtkAccelGroup *lighttable_accels; // lighttable-specific accels
  GtkAccelGroup *map_accels;        // map-specific accels
  GtkAccelGroup *print_accels;      // print-specific accels
  GtkAccelGroup *slideshow_accels;  // slideshow-specific accels
 
  // reference to the above group currently loaded in the main window. don't init,
  // don't free, only update
  GtkAccelGroup *active_group;
 
  GHashTable *acceleratables;       // Key/value list of path/dt_shortcut_t
  gint reset;                       // ref counter of how many parts disconnected accels
  GdkKeymap *keymap;                // default screen keymap to decode key values
  GdkModifierType default_mod_mask; // set of modifier masks relevant only to key strokes
 
  // TRUE if we didn't find a keyboardrc config file at startup and we need to init a new one
  gboolean init;
 
  // between key_pressed and key_release events, this stores the active key strokes;
  // cleared when the main window gains or loses the focus (see dt_accels_dispatch)
  GtkAccelKey active_key;
 
  // Temporarily disable accelerators
  gboolean disable_accels;
 
  GtkAccelFlags flags;
 
  dt_pthread_mutex_t lock;
 
  // Views can register a global callback to handle scroll events
  // for example while keystrokes are on.
  struct scroll
  {
    gboolean (*callback)(GdkEventScroll event, void *data);
    void *data;
  } scroll;
} dt_accels_t;
 
typedef enum dt_shortcut_type_t
{
  DT_SHORTCUT_UNSET = 0,   // shortcut non-inited
  DT_SHORTCUT_DEFAULT = 1, // shortcut inited with compile-time defaults
  DT_SHORTCUT_USER = 2     // shortcut changed by user config
} dt_shortcut_type_t;
 
typedef struct dt_shortcut_t
{
  GtkWidget *widget;          // link to the widget being accelerated. Can be NULL.
  GList *closure;             // GList of GClosures, aka callback + data being accelerated. Always non-NULL once
                               // built through dt_accels_new_{widget,action,virtual}_shortcut(): accel groups are
                               // never attached to a GtkWindow (see dt_accels_dispatch), so the internal dispatcher
                               // is the only path that can activate a shortcut, and it always goes through this closure.
  char *path;                 // global path for that accel
  const char *signal;         // widget signal to be wired to that accel
  GtkAccelGroup *accel_group; // the accel_group to which this shortcut belongs
  guint key;                  // default key
  GdkModifierType mods;       // default modifier
  dt_shortcut_type_t type;
  gboolean locked;            // if shortcut can't be changed by user
  gboolean virtual_shortcut;  // if shortcut is mapped to a key-pressed event handler instead of a global action callback
  const char *description;    // user-legible description of the action
  dt_accels_t *accels; // back-reference for convenience
} dt_shortcut_t;
 
 
dt_accels_t *dt_accels_init(char *config_file, GtkAccelFlags flags);
void dt_accels_cleanup(dt_accels_t *accels);
 
 
gchar *dt_accels_build_path(const gchar *scope, const gchar *feature);
 
void dt_accels_load_user_config(dt_accels_t *accels);
 
 
void dt_accels_connect_accels(dt_accels_t *accels);
 
 
void dt_accels_connect_active_group(dt_accels_t *accels, const gchar *group);
 
void dt_accels_disconnect_active_group(dt_accels_t *accels);
 
 
void dt_accels_new_virtual_shortcut(dt_accels_t *accels, GtkAccelGroup *accel_group, const gchar *accel_path,
                                    GtkWidget *widget,
                                    guint key_val, GdkModifierType accel_mods);
 
 
void dt_accels_new_virtual_instance_shortcut(dt_accels_t *accels,
                                             gboolean (*action_callback)(GtkAccelGroup *group,
                                                                         GObject *acceleratable, guint keyval,
                                                                         GdkModifierType mods, gpointer user_data),
                                             gpointer data, GtkAccelGroup *accel_group, const gchar *action_scope,
                                             const gchar *action_name);
 
void dt_accels_new_widget_shortcut(dt_accels_t *accels, GtkWidget *widget, const gchar *signal,
                                   GtkAccelGroup *accel_group, const gchar *accel_path, guint key_val,
                                   GdkModifierType accel_mods, const gboolean lock);
 
 
void dt_accels_new_action_shortcut(dt_accels_t *accels,
                                   gboolean (*action_callback)(GtkAccelGroup *group, GObject *acceleratable,
                                                               guint keyval, GdkModifierType mods,
                                                               gpointer user_data),
                                   gpointer data, GtkWidget *target_widget, GtkAccelGroup *accel_group,
                                   const gchar *action_scope, const gchar *action_name, guint key_val,
                                   GdkModifierType accel_mods, const gboolean lock, const char *description);
 
 
gboolean dt_accels_dispatch(GtkWidget *w, GdkEvent *event, gpointer user_data);
 
void dt_accels_attach_scroll_handler(dt_accels_t *accels, gboolean (*callback)(GdkEventScroll event, void *data),
                                     void *data);
 
void dt_accels_detach_scroll_handler(dt_accels_t *accels);
 
 
// Temporarily enable/disable keyboard accels, for example during GtkEntry typing.
// Connect it from Gtk focus in/out event handlers
static inline void dt_accels_disable(dt_accels_t *accels, gboolean state)
{
  accels->disable_accels = state;
}
 
void dt_accels_remove_accel(dt_accels_t *accels, const char *path, gpointer data);
 
void dt_accels_remove_shortcut(dt_accels_t *accels, const char *path);
 
void dt_accels_window(dt_accels_t *accels, GtkWindow *main_window);
 
void dt_accels_search(dt_accels_t *accels, GtkWindow *main_window, GtkWidget *anchor);
 
/* ------------------------------------------------------------------------------------------
 * Host hooks
 *
 * The shortcut system is otherwise self-contained GTK: a key arrives, a path is matched, a
 * closure fires. These four are the only things it cannot answer by itself, so the host
 * supplies them instead of the module reaching for application globals.
 *
 * All are optional. Unregistered, each degrades to a sensible inert default.
 * ------------------------------------------------------------------------------------------ */
 
void dt_accels_set_global(dt_accels_t *accels);
dt_accels_t *dt_accels_get_global(void);
 
void dt_accels_disconnect_on_text_input(GtkWidget *widget);
 
typedef gint (*dt_accels_top_offset_handler_t)(void);
void dt_accels_set_top_offset_handler(dt_accels_top_offset_handler_t handler);
 
typedef void (*dt_accels_refocus_handler_t)(void);
void dt_accels_set_refocus_handler(dt_accels_refocus_handler_t handler);
 
typedef gchar *(*dt_accels_recent_get_handler_t)(int index);
typedef void (*dt_accels_recent_set_handler_t)(int index, const char *value);
void dt_accels_set_recent_handlers(dt_accels_recent_get_handler_t get,
                                   dt_accels_recent_set_handler_t set);
 
/* Shorthand for a darkroom-scoped action shortcut, resolved through this module's own
 * instance rather than through the application's GUI struct. */
#define dt_accels_new_darkroom_action(a, b, w, c, d, e, f, g)                                 \
  dt_accels_new_action_shortcut(dt_accels_get_global(), a, b, w,                              \
                                dt_accels_get_global()->darkroom_accels, c, d, e, f, FALSE, g)
 
G_END_DECLS
 
#endif // DT_WIDGETS_ACCELERATORS_H