signal.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2011-2012 Henrik Andersson.
    Copyright (C) 2011 johannes hanika.
    Copyright (C) 2012 Ivan Tarozzi.
    Copyright (C) 2012 José Carlos García Sogo.
    Copyright (C) 2012-2015 Jérémy Rosen.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2012-2016 Tobias Ellinghaus.
    Copyright (C) 2013 Simon Spannagel.
    Copyright (C) 2014, 2016, 2019-2021 Pascal Obry.
    Copyright (C) 2014 Ronny Kahl.
    Copyright (C) 2018-2019 Edgardo Hoszowski.
    Copyright (C) 2018 Rikard Öxler.
    Copyright (C) 2019-2021 Aldric Renaudin.
    Copyright (C) 2019 luzpaz.
    Copyright (C) 2019 Ulrich Pegelow.
    Copyright (C) 2020 Chris Elston.
    Copyright (C) 2020 Hanno Schwalm.
    Copyright (C) 2020 Hubert Kowalski.
    Copyright (C) 2020-2021 Philippe Weyland.
    Copyright (C) 2021 Dan Torop.
    Copyright (C) 2022-2023, 2025 Aurélien PIERRE.
    Copyright (C) 2022 Martin Bařinka.
    Copyright (C) 2023 Luca Zulberti.
    Copyright (C) 2025 Alynx Zhou.
    
    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/>.
*/
 
#ifndef DT_CONTROL_SIGNAL_H
#define DT_CONTROL_SIGNAL_H
 
#include "common/logging.h"
#include <glib-object.h>
#include <stdint.h>
 
G_BEGIN_DECLS
 
typedef enum dt_signal_t
{
  DT_SIGNAL_MOUSE_OVER_IMAGE_CHANGE,
 
  DT_SIGNAL_ACTIVE_IMAGES_CHANGE,
 
  DT_SIGNAL_CONTROL_REDRAW_ALL,
 
  DT_SIGNAL_CONTROL_REDRAW_CENTER,
 
  DT_SIGNAL_VIEWMANAGER_VIEW_CHANGED,
 
  DT_SIGNAL_VIEWMANAGER_VIEW_CANNOT_CHANGE,
 
  DT_SIGNAL_VIEWMANAGER_THUMBTABLE_ACTIVATE,
 
  DT_SIGNAL_VIEWMANAGER_FILMSTRIP_ACTIVATE,
 
  DT_SIGNAL_VIEWMANAGER_FILMSTRIP_DRAG_BEGIN,
 
  DT_SIGNAL_COLLECTION_CHANGED,
 
  DT_SIGNAL_SELECTION_CHANGED,
 
  DT_SIGNAL_TAG_CHANGED,
 
  // when imgs <> NULL these images have some geotag changes
  // when IS_NULL_PTR(imgs) locations have changed
  // if locid <> 0 it the new selected location on map
  DT_SIGNAL_GEOTAG_CHANGED,
 
  DT_SIGNAL_METADATA_CHANGED,
 
  // TODO check if tag and metadata could be included there
  DT_SIGNAL_IMAGE_INFO_CHANGED,
 
  DT_SIGNAL_STYLE_CHANGED,
 
  DT_SIGNAL_IMAGES_ORDER_CHANGE,
 
  DT_SIGNAL_FILMROLLS_CHANGED,
 
  DT_SIGNAL_FILMROLLS_REMOVED,
 
  /* \brief This signal is raised when a preset is created/updated/deleted */
  DT_SIGNAL_PRESETS_CHANGED,
 
  DT_SIGNAL_DEVELOP_INITIALIZE,
 
  DT_SIGNAL_DEVELOP_PREVIEW_PIPE_FINISHED,
 
  DT_SIGNAL_DEVELOP_UI_PIPE_FINISHED,
 
  DT_SIGNAL_CACHELINE_READY,
 
  DT_SIGNAL_DEVELOP_MODULEGROUPS_SET,
 
  DT_SIGNAL_DEVELOP_HISTORY_WILL_CHANGE,
 
  DT_SIGNAL_DEVELOP_HISTORY_CHANGE,
 
  DT_SIGNAL_HISTORY_RESYNC,
 
  DT_SIGNAL_DEVELOP_MODULE_REMOVE,
 
  DT_SIGNAL_DEVELOP_MODULE_MOVED,
 
  DT_SIGNAL_DEVELOP_IMAGE_CHANGED,
 
  DT_SIGNAL_DARKROOM_UI_CHANGED,
 
  DT_SIGNAL_IMAGE_LOADED,
 
  DT_SIGNAL_CONTROL_PROFILE_CHANGED,
 
  DT_SIGNAL_CONTROL_PROFILE_USER_CHANGED,
 
  DT_SIGNAL_IMAGE_IMPORT,
 
  DT_SIGNAL_IMAGE_EXPORT_TMPFILE,
 
  DT_SIGNAL_IMAGEIO_STORAGE_CHANGE,
 
  DT_SIGNAL_PREFERENCES_CHANGE,
 
  DT_SIGNAL_CONTROL_NAVIGATION_REDRAW,
 
  DT_SIGNAL_CONTROL_LOG_REDRAW,
 
  DT_SIGNAL_CONTROL_TOAST_REDRAW,
 
  DT_SIGNAL_CONTROL_PICKERDATA_READY,
 
  DT_SIGNAL_CONTROL_NOTEBOOK_TAB_CHANGED,
 
  /* \brief This signal is raised when metadata view needs update */
  DT_SIGNAL_METADATA_UPDATE,
 
  /* \brief This signal is raised when the user choses a new location from map (module location)*/
  DT_SIGNAL_LOCATION_CHANGED,
 
  /* Raised when a mask form is selected/deselected */
  DT_SIGNAL_MASK_SELECTION_CHANGED,
  DT_SIGNAL_MASK_CHANGED,
  DT_SIGNAL_MASK_SHAPE_BUTTONS_DEACTIVATE,
 
  /* Raised when mask creation mode is entered, so every shape toolbar re-reads which shape is
     being created and presses the matching button -- the toolbars are not the only way in. */
  DT_SIGNAL_MASK_SHAPE_BUTTONS_SYNC,
 
  /* Raised when the focused darkroom module changes or its masks/blending GUI needs refresh */
  DT_SIGNAL_DEVELOP_MASKS_GUI_CHANGED,
 
  DT_SIGNAL_FILELIST_CHANGED,
 
  DT_SIGNAL_FOLDER_SURVEY_CHANGED,
 
  /* do not touch !*/
  DT_SIGNAL_COUNT
} dt_signal_t;
 
typedef enum dt_debug_signal_action_t
{
  // powers of two, masking
  DT_DEBUG_SIGNAL_ACT_RAISE       = 1 << 0,
  DT_DEBUG_SIGNAL_ACT_CONNECT     = 1 << 1,
  DT_DEBUG_SIGNAL_ACT_DISCONNECT  = 1 << 2,
  DT_DEBUG_SIGNAL_ACT_PRINT_TRACE = 1 << 3,
} dt_debug_signal_action_t;
 
/* read-only accessors for the signal-debugging options, parsed once from the
 * command line at startup and never mutated afterwards (implemented in
 * darktable.c, next to dt_get_debug_flags()). */
int32_t dt_get_signal_debug_acts(void);
gboolean dt_get_signal_debug(const int signal);
 
/* inititialize the signal framework */
struct dt_control_signal_t *dt_control_signal_init();
 
/* The application-wide signal bus. Unlike the other service handles, this is
 * global by nature (a process-wide broadcast bus with no per-call context to
 * ride on), so this accessor is the intended end state, not an interim step —
 * same shape as the fully-encapsulated dt_conf_* API. Implemented by the
 * orchestrator (darktable.c). */
struct dt_control_signal_t *dt_control_signal_get_global(void);
/* cleanup the signal framework */
void dt_control_signal_cleanup(struct dt_control_signal_t *ctlsig);
/* raises a signal */
void dt_control_signal_raise(const struct dt_control_signal_t *ctlsig, const dt_signal_t signal, ...);
/* connects a callback to a signal */
void dt_control_signal_connect(const struct dt_control_signal_t *ctlsig, const dt_signal_t signal,
                               GCallback cb, gpointer user_data);
/* disconnects a callback from a sink */
void dt_control_signal_disconnect(const struct dt_control_signal_t *ctlsig, GCallback cb, gpointer user_data);
/* disconnects every handler registered with user_data, on any signal and any callback function.
   Safety net for module teardown: guarantees no dangling instance can still be invoked by a
   later signal broadcast, even if the caller's own gui_cleanup() forgot (or was skipped for) one
   of several signals it connected in gui_init(). */
void dt_control_signal_disconnect_all(const struct dt_control_signal_t *ctlsig, gpointer user_data);
/* blocks a callback */
void dt_control_signal_block_by_func(const struct dt_control_signal_t *ctlsig, GCallback cb, gpointer user_data);
/* unblocks a callback */
void dt_control_signal_unblock_by_func(const struct dt_control_signal_t *ctlsig, GCallback cb, gpointer user_data);
 
#define DT_DEBUG_CONTROL_SIGNAL_RAISE(ctlsig, signal, ...)                                                                       \
  do                                                                                                                             \
  {                                                                                                                              \
    if((dt_get_signal_debug_acts() & DT_DEBUG_SIGNAL_ACT_RAISE) && dt_get_signal_debug(signal))                 \
    {                                                                                                                            \
      dt_print(DT_DEBUG_SIGNAL, "[signal] %s:%d, function %s(): raise signal %s\n", __FILE__, __LINE__, __FUNCTION__, #signal);  \
    }                                                                                                                            \
    dt_control_signal_raise(ctlsig, signal, ##__VA_ARGS__);                                                                      \
  } while (0)
 
#define DT_DEBUG_CONTROL_SIGNAL_CONNECT(ctlsig, signal, cb, user_data)                                                           \
  do                                                                                                                             \
  {                                                                                                                              \
    if((dt_get_signal_debug_acts() & DT_DEBUG_SIGNAL_ACT_CONNECT) && dt_get_signal_debug(signal))                \
    {                                                                                                                            \
      dt_print(DT_DEBUG_SIGNAL, "[signal] %s:%d, function: %s() connect handler %s to signal %s\n", __FILE__, __LINE__,          \
               __FUNCTION__, #cb, #signal);                                                                                      \
    }                                                                                                                            \
    dt_control_signal_connect(ctlsig, signal, cb, user_data);                                                                    \
  } while (0)
 
#define DT_DEBUG_CONTROL_SIGNAL_DISCONNECT(ctlsig, cb, user_data)                                                                \
  do                                                                                                                             \
  {                                                                                                                              \
    if(dt_get_signal_debug_acts() & DT_DEBUG_SIGNAL_ACT_DISCONNECT)                                                       \
    {                                                                                                                            \
      dt_print(DT_DEBUG_SIGNAL, "[signal] %s:%d, function: %s() disconnect handler %s\n", __FILE__, __LINE__, __FUNCTION__, #cb);\
    }                                                                                                                            \
    dt_control_signal_disconnect(ctlsig, cb, user_data);                                                                         \
  } while (0)
 
#define DT_DEBUG_CONTROL_SIGNAL_DISCONNECT_ALL(ctlsig, user_data)                                                                \
  do                                                                                                                             \
  {                                                                                                                              \
    if(dt_get_signal_debug_acts() & DT_DEBUG_SIGNAL_ACT_DISCONNECT)                                                       \
    {                                                                                                                            \
      dt_print(DT_DEBUG_SIGNAL, "[signal] %s:%d, function: %s() disconnect all handlers for %p\n", __FILE__, __LINE__,          \
               __FUNCTION__, (void *)(user_data));                                                                               \
    }                                                                                                                            \
    dt_control_signal_disconnect_all(ctlsig, user_data);                                                                         \
  } while (0)
 
G_END_DECLS
 
#endif // DT_CONTROL_SIGNAL_H
 
// clang-format off
// modelines: These editor modelines have been set for all relevant files by tools/update_modelines.py
// vim: shiftwidth=2 expandtab tabstop=2 cindent
// kate: tab-indents: off; indent-width 2; replace-tabs on; indent-mode cstyle; remove-trailing-spaces modified;
// clang-format on